From: Alexander Korotkov <akorotkov@postgresql.org>
Date: Tue, 14 Jul 2026 21:47:33 +0000 (+0300)
Subject: Fix and polish JSON_TABLE documentation
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=4a82912bb2a2bc757142eca48f0fded1817a9a7c;p=thirdparty%2Fpostgresql.git

Fix and polish JSON_TABLE documentation

Correct the JSON_TABLE synopsis to place the ON ERROR clause after the
PLAN clause, matching the grammar (the previous order could not be
typed).  Replace a dangling reference to json_path_specification with
path_expression, the term the synopsis actually defines.  Mark up the
PLAN DEFAULT keywords with <literal> and fix a couple of wording issues.
Also list OUTER before INNER consistently, including in the parent/child
join description, where OUTER is the default.

Author: Thom Brown <thom@linux.com>
Discussion: https://postgr.es/m/CAA-aLv5PGAFmAEpbhKQz8wppoOOTHfo-=LJb2sAB3974-9QtOw@mail.gmail.com
---

diff --git a/doc/src/sgml/func/func-json.sgml b/doc/src/sgml/func/func-json.sgml
index 541d02d4a6e..0763ec81ed8 100644
--- a/doc/src/sgml/func/func-json.sgml
+++ b/doc/src/sgml/func/func-json.sgml
@@ -3640,8 +3640,8 @@ DETAIL:  Missing "]" after array dimensions.
    against the row constructed from the columns specified in the parent
    <literal>COLUMNS</literal> clause to get the row in the final view.  Child
    columns themselves may contain a <literal>NESTED PATH</literal>
-   specification thus allowing to extract data located at arbitrary nesting
-   levels.  Columns produced by multiple <literal>NESTED PATH</literal>s at the
+   specification, thus allowing extraction of data located at arbitrary
+   nesting levels.  Columns produced by multiple <literal>NESTED PATH</literal>s at the
    same level are considered to be <firstterm>siblings</firstterm> of each
    other and their rows after joining with the parent row are combined using
    UNION.
@@ -3662,12 +3662,12 @@ DETAIL:  Missing "]" after array dimensions.
 JSON_TABLE (
     <replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable> <optional> AS <replaceable>json_path_name</replaceable> </optional> <optional> PASSING { <replaceable>value</replaceable> AS <replaceable>varname</replaceable> } <optional>, ...</optional> </optional>
     COLUMNS ( <replaceable class="parameter">json_table_column</replaceable> <optional>, ...</optional> )
-    <optional> { <literal>ERROR</literal> | <literal>EMPTY</literal> <optional>ARRAY</optional>} <literal>ON ERROR</literal> </optional>
     <optional>
         PLAN ( <replaceable class="parameter">json_table_plan</replaceable> ) |
-        PLAN DEFAULT ( { INNER | OUTER } <optional> , { CROSS | UNION } </optional>
-                     | { CROSS | UNION } <optional> , { INNER | OUTER } </optional> )
+        PLAN DEFAULT ( { OUTER | INNER } <optional> , { CROSS | UNION } </optional>
+                     | { CROSS | UNION } <optional> , { OUTER | INNER } </optional> )
     </optional>
+    <optional> { <literal>ERROR</literal> | <literal>EMPTY</literal> <optional>ARRAY</optional>} <literal>ON ERROR</literal> </optional>
 )
 
 <phrase>
@@ -3853,7 +3853,7 @@ where <replaceable class="parameter">json_table_column</replaceable> is:
      The <literal>NESTED PATH</literal> syntax is recursive,
      so you can go down multiple nested levels by specifying several
      <literal>NESTED PATH</literal> subclauses within each other.
-     It allows to unnest the hierarchy of JSON objects and arrays
+     It allows you to unnest the hierarchy of JSON objects and arrays
      in a single function invocation rather than chaining several
      <function>JSON_TABLE</function> expressions in an SQL statement.
     </para>
@@ -3886,7 +3886,7 @@ where <replaceable class="parameter">json_table_column</replaceable> is:
 
     <para>
      The optional <replaceable>json_path_name</replaceable> serves as an
-     identifier of the provided <replaceable>json_path_specification</replaceable>.
+     identifier of the provided <replaceable>path_expression</replaceable>.
      The path name must be unique and distinct from the column names.  Each
      path name can appear in the <literal>PLAN</literal> clause only once.
     </para>
@@ -3920,33 +3920,33 @@ where <replaceable class="parameter">json_table_column</replaceable> is:
   <variablelist>
    <varlistentry>
     <term>
-     <literal>INNER</literal>
+     <literal>OUTER</literal>
     </term>
     <listitem>
 
     <para>
-     Use <literal>INNER JOIN</literal>, so that the parent row
-     is omitted from the output if it does not have any child rows
-     after joining the data returned by <literal>NESTED PATH</literal>.
+     Use <literal>LEFT OUTER JOIN</literal>, so that the parent row
+     is always included into the output even if it does not have any child rows
+     after joining the data returned by <literal>NESTED PATH</literal>, with NULL values
+     inserted into the child columns if the corresponding
+     values are missing.
+    </para>
+    <para>
+     This is the default option for joining columns with parent/child relationship.
     </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
     <term>
-     <literal>OUTER</literal>
+     <literal>INNER</literal>
     </term>
     <listitem>
 
     <para>
-     Use <literal>LEFT OUTER JOIN</literal>, so that the parent row
-     is always included into the output even if it does not have any child rows
-     after joining the data returned by <literal>NESTED PATH</literal>, with NULL values
-     inserted into the child columns if the corresponding
-     values are missing.
-    </para>
-    <para>
-     This is the default option for joining columns with parent/child relationship.
+     Use <literal>INNER JOIN</literal>, so that the parent row
+     is omitted from the output if it does not have any child rows
+     after joining the data returned by <literal>NESTED PATH</literal>.
     </para>
     </listitem>
    </varlistentry>
@@ -3991,7 +3991,7 @@ where <replaceable class="parameter">json_table_column</replaceable> is:
 
    <varlistentry>
     <term>
-     <literal>PLAN DEFAULT</literal> ( <literal><replaceable>OUTER | INNER</replaceable> <optional>, <replaceable>UNION | CROSS</replaceable> </optional></literal> )
+     <literal>PLAN DEFAULT</literal> ( { <literal>OUTER</literal> | <literal>INNER</literal> } <optional>, { <literal>UNION</literal> | <literal>CROSS</literal> } </optional> )
     </term>
     <listitem>
      <para>