From a20c2547d9d6b608e7ce4b51a218c314ba5decaf Mon Sep 17 00:00:00 2001
From: amitlan <amitlangote09@gmail.com>
Date: Tue, 17 Jan 2023 22:22:00 +0900
Subject: [PATCH v3 11/11] Proposed reworking of SQL/JSON documentaion

Author: Elena Indrupskaya, Nikita Glukhov
Discussion: https://postgr.es/m/98ab8c72-49ad-d1e1-c9b6-8aca3a58e0f4@postgrespro.ru
---
 doc/src/sgml/func.sgml | 162 +++++++++++++++++++++--------------------
 1 file changed, 82 insertions(+), 80 deletions(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index fe6007e93b..f3e9079fae 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17699,18 +17699,18 @@ $.* ? (@ like_regex "^\\d+$")
       <entry role="func_table_entry"><para role="func_signature">
         <indexterm><primary>json constructor</primary></indexterm>
           <function>json</function> (
-          <parameter>expression</parameter>
+          <replaceable>expression</replaceable>
           <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional></optional>
           <optional> { <literal>WITH</literal> | <literal>WITHOUT</literal> } <literal>UNIQUE</literal> <optional> <literal>KEYS</literal> </optional></optional>
           <optional> <literal>RETURNING</literal> <replaceable>json_data_type</replaceable> </optional>)
        </para>
        <para>
-        The <parameter>expression</parameter> can be any text type or a
+        The <replaceable>expression</replaceable> can be any text type or a
         <type>bytea</type> in UTF8 encoding. If the
-        <parameter>expression</parameter> is NULL, an
+        <replaceable>expression</replaceable> is NULL, an
         <acronym>SQL</acronym> null value is returned.
         If <literal>WITH UNIQUE</literal> is specified, the
-        <parameter>expression</parameter> must not contain any duplicate
+        <replaceable>expression</replaceable> must not contain any duplicate
         object keys.
        </para>
        <para>
@@ -17725,12 +17725,12 @@ $.* ? (@ like_regex "^\\d+$")
      <row>
       <entry role="func_table_entry"><para role="func_signature">
         <indexterm><primary>json_scalar</primary></indexterm>
-        <function>json_scalar</function> (<parameter>expression</parameter>
+        <function>json_scalar</function> (<replaceable>expression</replaceable>
         <optional> <literal>RETURNING</literal> <replaceable>json_data_type</replaceable> </optional>)
        </para>
        <para>
         Returns a JSON scalar value representing
-        <parameter>expression</parameter>.
+        <replaceable>expression</replaceable>.
         If the input is NULL, an SQL NULL is returned. If the input is a number
         or a boolean value, a corresponding JSON number or boolean value is
         returned. For any other value a JSON string is returned.
@@ -17748,8 +17748,8 @@ $.* ? (@ like_regex "^\\d+$")
       <entry role="func_table_entry"><para role="func_signature">
         <indexterm><primary>json_object</primary></indexterm>
         <function>json_object</function> (
-        <optional> { <parameter>key_expression</parameter> { <literal>VALUE</literal> | ':' }
-         <parameter>value_expression</parameter> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> }<optional>, ...</optional> </optional>
+        <optional> { <replaceable>key_expression</replaceable> { <literal>VALUE</literal> | ':' }
+         <replaceable>value_expression</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> }<optional>, ...</optional> </optional>
         <optional> { <literal>NULL</literal> | <literal>ABSENT</literal> } <literal>ON NULL</literal> </optional>
         <optional> { <literal>WITH</literal> | <literal>WITHOUT</literal> } <literal>UNIQUE</literal> <optional> <literal>KEYS</literal> </optional> </optional>
         <optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> </optional>)
@@ -17757,15 +17757,15 @@ $.* ? (@ like_regex "^\\d+$")
        <para>
         Constructs a JSON object of all the key value pairs given,
         or an empty object if none are given.
-        <parameter>key_expression</parameter> is a scalar expression
+        <replaceable>key_expression</replaceable> is a scalar expression
         defining the <acronym>JSON</acronym> key, which is
         converted to the <type>text</type> type.
         It cannot be <literal>NULL</literal> nor can it
         belong to a type that has a cast to the <type>json</type>.
         If <literal>WITH UNIQUE</literal> is specified, there must not
-        be any duplicate <parameter>key_expression</parameter>.
+        be any duplicate <replaceable>key_expression</replaceable>.
         If <literal>ABSENT ON NULL</literal> is specified, the entire
-        pair is omitted if the <parameter>value_expression</parameter>
+        pair is omitted if the <replaceable>value_expression</replaceable>
         is <literal>NULL</literal>.
        </para>
        <para>
@@ -17777,7 +17777,7 @@ $.* ? (@ like_regex "^\\d+$")
       <entry role="func_table_entry"><para role="func_signature">
         <indexterm><primary>json_objectagg</primary></indexterm>
         <function>json_objectagg</function> (
-        <optional> { <parameter>key_expression</parameter> { <literal>VALUE</literal> | ':' } <parameter>value_expression</parameter> } </optional>
+        <optional> { <replaceable>key_expression</replaceable> { <literal>VALUE</literal> | ':' } <replaceable>value_expression</replaceable> } </optional>
         <optional> { <literal>NULL</literal> | <literal>ABSENT</literal> } <literal>ON NULL</literal> </optional>
         <optional> { <literal>WITH</literal> | <literal>WITHOUT</literal> } <literal>UNIQUE</literal> <optional> <literal>KEYS</literal> </optional> </optional>
         <optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> </optional>)
@@ -17785,8 +17785,8 @@ $.* ? (@ like_regex "^\\d+$")
        <para>
         Behaves like <function>json_object</function> above, but as an
         aggregate function, so it only takes one
-        <parameter>key_expression</parameter> and one
-        <parameter>value_expression</parameter> parameter.
+        <replaceable>key_expression</replaceable> and one
+        <replaceable>value_expression</replaceable> parameter.
        </para>
        <para>
         <literal>SELECT json_objectagg(k:v) FROM (VALUES ('a'::text,current_date),('b',current_date + 1)) AS t(k,v)</literal>
@@ -17797,7 +17797,7 @@ $.* ? (@ like_regex "^\\d+$")
       <entry role="func_table_entry"><para role="func_signature">
         <indexterm><primary>json_array</primary></indexterm>
         <function>json_array</function> (
-        <optional> { <parameter>value_expression</parameter> <optional> <literal>FORMAT JSON</literal> </optional> } <optional>, ...</optional> </optional>
+        <optional> { <replaceable>value_expression</replaceable> <optional> <literal>FORMAT JSON</literal> </optional> } <optional>, ...</optional> </optional>
         <optional> { <literal>NULL</literal> | <literal>ABSENT</literal> } <literal>ON NULL</literal> </optional>
         <optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> </optional>)
        </para>
@@ -17808,7 +17808,7 @@ $.* ? (@ like_regex "^\\d+$")
         </para>
        <para>
         Constructs a JSON array from either a series of
-        <parameter>value_expression</parameter> parameters or from the results
+        <replaceable>value_expression</replaceable> parameters or from the results
         of <replaceable>query_expression</replaceable>,
         which must be a SELECT query returning a single column. If
         <literal>ABSENT ON NULL</literal> is specified, NULL values are ignored.
@@ -17828,7 +17828,7 @@ $.* ? (@ like_regex "^\\d+$")
       <entry role="func_table_entry"><para role="func_signature">
         <indexterm><primary>json_arrayagg</primary></indexterm>
         <function>json_arrayagg</function> (
-        <optional> <parameter>value_expression</parameter> </optional>
+        <optional> <replaceable>value_expression</replaceable> </optional>
         <optional> <literal>ORDER BY</literal> <replaceable>sort_expression</replaceable> </optional>
         <optional> { <literal>NULL</literal> | <literal>ABSENT</literal> } <literal>ON NULL</literal> </optional>
         <optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> </optional>)
@@ -17836,7 +17836,7 @@ $.* ? (@ like_regex "^\\d+$")
        <para>
         Behaves in the same way as <function>json_array</function>
         but as an aggregate function so it only takes one
-        <parameter>value_expression</parameter> parameter.
+        <replaceable>value_expression</replaceable> parameter.
         If <literal>ABSENT ON NULL</literal> is specified, any NULL
         values are omitted.
         If <literal>ORDER BY</literal> is specified, the elements will
@@ -17876,18 +17876,18 @@ $.* ? (@ like_regex "^\\d+$")
      <row>
       <entry role="func_table_entry"><para role="func_signature">
         <indexterm><primary>IS JSON</primary></indexterm>
-        <parameter>expression</parameter> <literal>IS</literal> <optional> <literal>NOT</literal> </optional> <literal>JSON</literal>
+        <replaceable>expression</replaceable> <literal>IS</literal> <optional> <literal>NOT</literal> </optional> <literal>JSON</literal>
         <optional> { <literal>VALUE</literal> | <literal>SCALAR</literal> | <literal>ARRAY</literal> | <literal>OBJECT</literal> } </optional>
         <optional> { <literal>WITH</literal> | <literal>WITHOUT</literal> } <literal>UNIQUE</literal> <optional> <literal>KEYS</literal> </optional> </optional>
        </para>
        <para>
-        This predicate tests whether <parameter>expression</parameter> can be
+        This predicate tests whether <replaceable>expression</replaceable> can be
         parsed as JSON, possibly of a specified type.
         If <literal>SCALAR</literal> or <literal>ARRAY</literal> or
         <literal>OBJECT</literal> is specified, the
         test is whether or not the JSON is of that particular type. If
-        <literal>WITH UNIQUE</literal> is specified, then an any object in the
-        <parameter>expression</parameter> is also tested to see if it
+        <literal>WITH UNIQUE</literal> is specified, then any object in the
+        <replaceable>expression</replaceable> is also tested to see if it
         has duplicate keys.
        </para>
        <para>
@@ -17913,12 +17913,12 @@ FROM
      <row>
       <entry role="func_table_entry"><para role="func_signature">
         <function>json_serialize</function> (
-        <parameter>expression</parameter> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional>
-        <optional> <literal>RETURNING</literal> <parameter>data_type</parameter> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> </optional>)
+        <replaceable>expression</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional>
+        <optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> </optional>)
        </para>
        <para>
         Transforms an SQL/JSON value into a character or binary string. The
-        <parameter>expression</parameter> can be of any JSON type, any
+        <replaceable>expression</replaceable> can be of any JSON type, any
         character string type, or <type>bytea</type> in UTF8 encoding.
         The returned type can be any character string type or
         <type>bytea</type>. The default is <type>text</type>.
@@ -17941,7 +17941,7 @@ FROM
   <note>
    <para>
     SQL/JSON paths can only be applied to the <type>jsonb</type> type, so it
-    might be necessary to cast the <parameter>context_item</parameter>
+    might be necessary to cast the <replaceable>context_item</replaceable>
     argument of these functions to <type>jsonb</type>.
    </para>
   </note>
@@ -17967,16 +17967,16 @@ FROM
       <entry role="func_table_entry"><para role="func_signature">
         <indexterm><primary>json_exists</primary></indexterm>
         <function>json_exists</function> (
-        <parameter>context_item</parameter>, <parameter>path_expression</parameter> <optional> <literal>PASSING</literal> { <parameter>value</parameter> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
+        <replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable> <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
         <optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> </optional>
         <optional> { <literal>TRUE</literal> | <literal>FALSE</literal> |<literal> UNKNOWN</literal> | <literal>ERROR</literal> } <literal>ON ERROR</literal> </optional>)
        </para>
        <para>
-        Returns true if the SQL/JSON <parameter>path_expression</parameter>
-        applied to the <parameter>context_item</parameter> using the
-        <parameter>value</parameter>s yields any items.
+        Returns true if the SQL/JSON <replaceable>path_expression</replaceable>
+        applied to the <replaceable>context_item</replaceable> using the
+        <replaceable>value</replaceable>s yields any items.
         The <literal>ON ERROR</literal> clause specifies what is returned if
-        an error occurs. Note that if the <parameter>path_expression</parameter>
+        an error occurs. Note that if the <replaceable>path_expression</replaceable>
         is <literal>strict</literal>, an error is generated if it yields no items.
         The default value is <literal>UNKNOWN</literal> which causes a NULL
         result.
@@ -17998,28 +17998,30 @@ FROM
       <entry role="func_table_entry"><para role="func_signature">
         <indexterm><primary>json_value</primary></indexterm>
         <function>json_value</function> (
-        <parameter>context_item</parameter>, <parameter>path_expression</parameter>
-        <optional> <literal>PASSING</literal> { <parameter>value</parameter> <literal>AS</literal> <parameter>varname</parameter> } <optional>, ...</optional></optional>
-        <optional> <literal>RETURNING</literal> <parameter>data_type</parameter> </optional>
-        <optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>DEFAULT</literal> <parameter>expression</parameter> } <literal>ON EMPTY</literal> </optional>
-        <optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>DEFAULT</literal> <parameter>expression</parameter> } <literal>ON ERROR</literal> </optional>)
+        <replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable>
+        <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
+        <optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> </optional>
+        <optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>DEFAULT</literal> <replaceable>expression</replaceable> } <literal>ON EMPTY</literal> </optional>
+        <optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>DEFAULT</literal> <replaceable>expression</replaceable> } <literal>ON ERROR</literal> </optional>)
        </para>
        <para>
         Returns the result of applying the
-        <parameter>path_expression</parameter> to the
-        <parameter>context_item</parameter> using the
-        <parameter>value</parameter>s. The extracted value must be
+        <replaceable>path_expression</replaceable> to the
+        <replaceable>context_item</replaceable> using the
+        <replaceable>value</replaceable>s. The extracted value must be
         a single <acronym>SQL/JSON</acronym> scalar item. For results that
         are objects or arrays, use the <function>json_query</function>
-        instead.
-        The returned <parameter>data_type</parameter> has the same semantics
+        function instead.
+        The returned <replaceable>data_type</replaceable> has the same semantics
         as for constructor functions like <function>json_objectagg</function>.
         The default returned type is <type>text</type>.
         The <literal>ON EMPTY</literal> clause specifies the behavior if the
-        <parameter>path_expression</parameter> yields no value at all.
+        <replaceable>path_expression</replaceable> yields no value at all.
         The <literal>ON ERROR</literal> clause specifies the behavior if an
-        error occurs, as a result of either the evaluation or the application
-        of the <literal>ON EMPTY</literal> clause.
+        error occurs as a result of <type>jsonpath</type> evaluation
+        (including cast to the output type) or execution of
+        <literal>ON EMPTY</literal> behavior (that was caused by empty result
+        of <type>jsonpath</type> evaluation).
        </para>
        <para>
         <literal>json_value(jsonb '"123.45"', '$' RETURNING float)</literal>
@@ -18038,24 +18040,24 @@ FROM
       <entry role="func_table_entry"><para role="func_signature">
         <indexterm><primary>json_query</primary></indexterm>
         <function>json_query</function> (
-        <parameter>context_item</parameter>, <parameter>path_expression</parameter> <optional> <literal>PASSING</literal> { <parameter>value</parameter> <literal>AS</literal> <parameter>varname</parameter> } <optional>, ...</optional></optional>
-        <optional> <literal>RETURNING</literal> <parameter>data_type</parameter> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> </optional>
+        <replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable> <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
+        <optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> </optional>
         <optional> { <literal>WITHOUT</literal> | <literal>WITH</literal> { <literal>CONDITIONAL</literal> | <optional><literal>UNCONDITIONAL</literal></optional> } } <optional> <literal>ARRAY</literal> </optional> <literal>WRAPPER</literal> </optional>
         <optional> { <literal>KEEP</literal> | <literal>OMIT</literal> } <literal>QUOTES</literal> <optional> <literal>ON SCALAR STRING</literal> </optional> </optional>
-        <optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>EMPTY</literal> { <optional> <literal>ARRAY</literal> </optional> | <literal>OBJECT</literal> } | <literal>DEFAULT</literal> <parameter>expression</parameter> } <literal>ON EMPTY</literal> </optional>
-        <optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>EMPTY</literal> { <optional> <literal>ARRAY</literal> </optional> | <literal>OBJECT</literal> } | <literal>DEFAULT</literal> <parameter>expression</parameter> } <literal>ON ERROR</literal> </optional>)
+        <optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>EMPTY</literal> { <optional> <literal>ARRAY</literal> </optional> | <literal>OBJECT</literal> } | <literal>DEFAULT</literal> <replaceable>expression</replaceable> } <literal>ON EMPTY</literal> </optional>
+        <optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>EMPTY</literal> { <optional> <literal>ARRAY</literal> </optional> | <literal>OBJECT</literal> } | <literal>DEFAULT</literal> <replaceable>expression</replaceable> } <literal>ON ERROR</literal> </optional>)
       </para>
        <para>
         Returns the result of applying the
-        <parameter>path_expression</parameter> to the
-        <parameter>context_item</parameter> using the
-        <parameter>value</parameter>s.
+        <replaceable>path_expression</replaceable> to the
+        <replaceable>context_item</replaceable> using the
+        <replaceable>value</replaceable>s.
         This function must return a JSON string, so if the path expression
         returns multiple SQL/JSON items, you must wrap the result using the
         <literal>WITH WRAPPER</literal> clause. If the wrapper is
         <literal>UNCONDITIONAL</literal>, an array wrapper will always
         be applied, even if the returned value is already a single JSON object
-        or array, but if it is <literal>CONDITIONAL</literal> it will not be
+        or array, but if it is <literal>CONDITIONAL</literal>, it will not be
         applied to a single array or object. <literal>UNCONDITIONAL</literal>
         is the default.
         If the result is a scalar string, by default the value returned will have
@@ -18064,7 +18066,7 @@ FROM
         The <literal>ON ERROR</literal> and <literal>ON EMPTY</literal>
         clauses have similar semantics to those clauses for
         <function>json_value</function>.
-        The returned <parameter>data_type</parameter> has the same semantics
+        The returned <replaceable>data_type</replaceable> has the same semantics
         as for constructor functions like <function>json_objectagg</function>.
         The default returned type is <type>text</type>.
        </para>
@@ -18129,7 +18131,7 @@ FROM
    columns. Columns produced by <literal>NESTED PATH</literal>s at the
    same level are considered to be <firstterm>siblings</firstterm>,
    while a column produced by a <literal>NESTED PATH</literal> is
-   considered to be a child of the column produced by and
+   considered to be a child of the column produced by a
    <literal>NESTED PATH</literal> or row expression at a higher level.
    Sibling columns are always joined first. Once they are processed,
    the resulting rows are joined to the parent row.
@@ -18138,13 +18140,13 @@ FROM
   <variablelist>
    <varlistentry>
     <term>
-     <literal><parameter>context_item</parameter>, <parameter>path_expression</parameter> <optional> <literal>AS</literal> <parameter>json_path_name</parameter> </optional> <optional> <literal>PASSING</literal> { <parameter>value</parameter> <literal>AS</literal> <parameter>varname</parameter> } <optional>, ...</optional></optional></literal>
+     <literal><replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable> <optional> <literal>AS</literal> <replaceable>json_path_name</replaceable> </optional> <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional></literal>
     </term>
     <listitem>
     <para>
      The input data to query, the JSON path expression defining the query,
      and an optional <literal>PASSING</literal> clause, which can provide data
-     values to the <parameter>path_expression</parameter>.
+     values to the <replaceable>path_expression</replaceable>.
      The result of the input data
      evaluation is called the <firstterm>row pattern</firstterm>. The row
      pattern is used as the source for row values in the constructed view.
@@ -18154,7 +18156,7 @@ FROM
 
    <varlistentry>
     <term>
-     <literal>COLUMNS</literal>( <parameter>json_table_column</parameter> <optional>, ...</optional> )
+     <literal>COLUMNS</literal>( <replaceable>json_table_column</replaceable> <optional>, ...</optional> )
     </term>
     <listitem>
 
@@ -18162,15 +18164,15 @@ FROM
      The <literal>COLUMNS</literal> clause defining the schema of the
      constructed view. In this clause, you must specify all the columns
      to be filled with SQL/JSON items.
-     The <parameter>json_table_column</parameter>
+     The <replaceable>json_table_column</replaceable>
      expression has the following syntax variants:
     </para>
 
   <variablelist>
    <varlistentry>
     <term>
-     <literal><parameter>name</parameter> <parameter>type</parameter>
-          <optional> <literal>PATH</literal> <parameter>json_path_specification</parameter> </optional></literal>
+     <literal><replaceable>name</replaceable> <replaceable>type</replaceable>
+          <optional> <literal>PATH</literal> <replaceable>json_path_specification</replaceable> </optional></literal>
     </term>
     <listitem>
 
@@ -18180,7 +18182,7 @@ FROM
     </para>
     <para>
      The provided <literal>PATH</literal> expression parses the
-     row pattern defined by <parameter>json_api_common_syntax</parameter>
+     row pattern defined by <replaceable>json_api_common_syntax</replaceable>
      and fills the column with produced SQL/JSON items, one for each row.
      If the <literal>PATH</literal> expression is omitted,
      <function>JSON_TABLE</function> uses the
@@ -18203,8 +18205,8 @@ FROM
 
    <varlistentry>
     <term>
-     <parameter>name</parameter> <parameter>type</parameter> <literal>FORMAT</literal> <parameter>json_representation</parameter>
-          <optional> <literal>PATH</literal> <parameter>json_path_specification</parameter> </optional>
+     <replaceable>name</replaceable> <replaceable>type</replaceable> <literal>FORMAT</literal> <replaceable>json_representation</replaceable>
+          <optional> <literal>PATH</literal> <replaceable>json_path_specification</replaceable> </optional>
     </term>
     <listitem>
 
@@ -18214,12 +18216,12 @@ FROM
     </para>
     <para>
      The provided <literal>PATH</literal> expression parses the
-     row pattern defined by <parameter>json_api_common_syntax</parameter>
+     row pattern defined by <replaceable>json_api_common_syntax</replaceable>
      and fills the column with produced SQL/JSON items, one for each row.
      If the <literal>PATH</literal> expression is omitted,
      <function>JSON_TABLE</function> uses the
-     <literal>$.<parameter>name</parameter></literal> path expression,
-     where <parameter>name</parameter> is the provided column name.
+     <literal>$.<replaceable>name</replaceable></literal> path expression,
+     where <replaceable>name</replaceable> is the provided column name.
      In this case, the column name must correspond to one of the
      keys within the SQL/JSON item produced by the row pattern.
     </para>
@@ -18235,8 +18237,8 @@ FROM
 
    <varlistentry>
     <term>
-       <parameter>name</parameter> <parameter>type</parameter>
-       <literal>EXISTS</literal> <optional> <literal>PATH</literal> <parameter>json_path_specification</parameter> </optional>
+       <replaceable>name</replaceable> <replaceable>type</replaceable>
+       <literal>EXISTS</literal> <optional> <literal>PATH</literal> <replaceable>json_path_specification</replaceable> </optional>
     </term>
     <listitem>
 
@@ -18245,10 +18247,10 @@ FROM
     </para>
     <para>
      The provided <literal>PATH</literal> expression parses the
-     row pattern defined by <parameter>json_api_common_syntax</parameter>,
+     row pattern defined by <replaceable>json_api_common_syntax</replaceable>,
      checks whether any SQL/JSON items were returned, and fills the column with
      resulting boolean value, one for each row.
-     The specified <parameter>type</parameter> should have cast from
+     The specified <replaceable>type</replaceable> should have cast from
      <type>boolean</type>.
      If the <literal>PATH</literal> expression is omitted,
      <function>JSON_TABLE</function> uses the
@@ -18265,8 +18267,8 @@ FROM
 
    <varlistentry>
     <term>
-     <literal>NESTED PATH</literal> <parameter>json_path_specification</parameter> <optional> <literal>AS</literal> <parameter>json_path_name</parameter> </optional>
-          <literal>COLUMNS</literal> ( <parameter>json_table_column</parameter> <optional>, ...</optional> )
+      <literal>NESTED PATH</literal> <replaceable>json_path_specification</replaceable> <optional> <literal>AS</literal> <replaceable>json_path_name</replaceable> </optional>
+          <literal>COLUMNS</literal> ( <replaceable>json_table_column</replaceable> <optional>, ...</optional> )
     </term>
     <listitem>
 
@@ -18274,7 +18276,7 @@ FROM
      Extracts SQL/JSON items from nested levels of the row pattern,
      generates one or more columns as defined by the <literal>COLUMNS</literal>
      subclause, and inserts the extracted SQL/JSON items into each row of these columns.
-     The <parameter>json_table_column</parameter> expression in the
+     The <replaceable>json_table_column</replaceable> expression in the
      <literal>COLUMNS</literal> subclause uses the same syntax as in the
      parent <literal>COLUMNS</literal> clause.
     </para>
@@ -18290,14 +18292,14 @@ FROM
 
     <para>
      You can use the <literal>PLAN</literal> clause to define how
-     to join the columns returned by <parameter>NESTED PATH</parameter> clauses.
+     to join the columns returned by <literal>NESTED PATH</literal> clauses.
     </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
     <term>
-     <parameter>name</parameter> <literal>FOR ORDINALITY</literal>
+     <replaceable>name</replaceable> <literal>FOR ORDINALITY</literal>
     </term>
     <listitem>
 
@@ -18316,13 +18318,13 @@ FROM
 
    <varlistentry>
     <term>
-     <literal>AS</literal> <parameter>json_path_name</parameter>
+     <literal>AS</literal> <replaceable>json_path_name</replaceable>
     </term>
     <listitem>
 
     <para>
-     The optional <parameter>json_path_name</parameter> serves as an
-     identifier of the provided <parameter>json_path_specification</parameter>.
+     The optional <replaceable>json_path_name</replaceable> serves as an
+     identifier of the provided <replaceable>json_path_specification</replaceable>.
      The path name must be unique and distinct from the column names.
      When using the <literal>PLAN</literal> clause, you must specify the names
      for all the paths, including the row pattern. Each path name can appear in
@@ -18333,7 +18335,7 @@ FROM
 
    <varlistentry>
     <term>
-     <literal>PLAN</literal> ( <parameter>json_table_plan</parameter> )
+     <literal>PLAN</literal> ( <replaceable>json_table_plan</replaceable> )
     </term>
     <listitem>
 
@@ -18419,7 +18421,7 @@ FROM
 
    <varlistentry>
     <term>
-     <literal>PLAN DEFAULT</literal> ( <replaceable>OUTER | INNER</replaceable> <optional>, <replaceable>UNION | CROSS</replaceable> </optional> )
+     <literal>PLAN DEFAULT</literal> ( <literal><replaceable>OUTER | INNER</replaceable> <optional>, <replaceable>UNION | CROSS</replaceable> </optional></literal> )
     </term>
     <listitem>
      <para>
-- 
2.35.3

