Fix handling of parameter names, clarify table entry

handrews · handrews · commit 0fa3c454868a · 2024-05-27T12:34:15.000-07:00
* Paramter names don't need to be modeled as template variables.
* Include an example of a parameter name that needs encoding.
* Add more details to the fixed field entries for allowReserved
diff --git a/versions/3.0.4.md b/versions/3.0.4.md
@@ -1068,7 +1068,7 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="parameterStyle"></a>style | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.
 <a name="parameterExplode"></a>explode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.
-<a name="parameterAllowReserved"></a>allowReserved | `boolean` | When this is true, parameter values are serialized  using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#autoid-20), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#autoid-13), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are not allowed in the query string, or have a meaning other than their literal value (e.g. `+` as an escape for the space character in `application/x-www-form-urlencoded` query strings). This property only applies to parameters with an `in` value of `query`. The default value is `false`.
+<a name="parameterAllowReserved"></a>allowReserved | `boolean` | When this is true, parameter values are serialized  using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#autoid-20), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#autoid-13), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are [not allowed in the query string](https://datatracker.ietf.org/doc/html/rfc3986#autoid-24) (`[`, `]`, `#`), or have a special meaning in `application/x-www-form-urlencoded` (`-`, `&`, `+`); see Appendices [C](#usingRFC6570Implementations) and [E](#percentEncodingAndFormMediaTypes) for details. This property only applies to parameters with an `in` value of `query`. The default value is `false`.
 <a name="parameterSchema"></a>schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the parameter.
 <a name="parameterExample"></a>example | Any | Example of the parameter's potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL _override_ the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.
 <a name="parameterExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the parameter's potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL _override_ the example provided by the schema.
@@ -1620,7 +1620,7 @@ Field Name | Type | Description
 <a name="encodingHeaders"></a>headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | A map allowing additional information to be provided as headers, for example `Content-Disposition`.  `Content-Type` is described separately and SHALL be ignored in this section. This property SHALL be ignored if the request body media type is not a `multipart`.
 <a name="encodingStyle"></a>style | `string` | Describes how a specific property value will be serialized depending on its type.  See [Parameter Object](#parameterObject) for details on the [`style`](#parameterStyle) property. The behavior follows the same values as `query` parameters, including default values. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.
 <a name="encodingExplode"></a>explode | `boolean` | When this is true, property values of type `array` or `object` generate separate parameters for each value of the array, or key-value-pair of the map.  For other types of properties this property has no effect. When [`style`](#encodingStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.
-<a name="encodingAllowReserved"></a>allowReserved | `boolean` | When this is true, parameter values are serialized  using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#autoid-20), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#autoid-13), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are not allowed in the query string, or have a meaning other than their literal value (e.g. `+` as an escape for the space character in `application/x-www-form-urlencoded` query strings).  The default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.
+<a name="encodingAllowReserved"></a>allowReserved | `boolean` | When this is true, parameter values are serialized  using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#autoid-20), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#autoid-13), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are [not allowed in the query string](https://datatracker.ietf.org/doc/html/rfc3986#autoid-24) (`[`, `]`, `#`), or have a special meaning in `application/x-www-form-urlencoded` (`-`, `&`, `+`); see Appendices [C](#usingRFC6570Implementations) and [E](#percentEncodingAndFormMediaTypes) for details. This property only applies to parameters with an `in` value of `query`. The default value is `false`.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
@@ -3541,6 +3541,9 @@ Implementations of this specification MAY use an implementation of RFC6570 to pe
 
 Note that when using `style: form` RFC6570 expansion to produce an `application/x-www-form-urlencoded` HTTP message body, it is necessary to remove the `?` prefix that is produced to satisfy the URI query string syntax.
 
+Note also that not all RFC6570 implementations support all four levels of operators, all of which are needed to fully support the OpenAPI Specification's usage.
+Using an implementation with a lower level of support will require additional manual construction of URI Templates to work around the limitations.
+
 ### Equivalences Between Fields and RFC6570 Operators
 
 Certain field values translate to RFC6570 operators (or lack thereof):
@@ -3587,7 +3590,7 @@ This includes:
   * any parameter name that is not a legal RFC6570 variable name (alphanumerics, `_`, and percent-encoded characters)
 
 The Parameter Object's `name` field has a much more permissive syntax than [RFC6570 variable name syntax](https://www.rfc-editor.org/rfc/rfc6570#section-2.3).
-A parameter name that includes characters outside of the allowed RFC6570 variable character set MUST be percent-encoded before it can be used in a URI Template, and MUST set `allowReserved: true` to avoid double percent-encoding.
+A parameter name that includes characters outside of the allowed RFC6570 variable character set MUST be percent-encoded before it can be used in a URI Template.
 
 ### Examples
 
@@ -3664,39 +3667,36 @@ parameters:
 We can't combine the `?` and `+` RFC6570 prefixes, and there's no way with RFC6570 to replace the `,` separator with a space character.
 So we need to restructure the data to fit a manually constructed URI Template that passes all of the pieces through the right sort of expansion.
 
-Here is one such template.
-The exact variable names are unimportant, but in this example "f" and "w" are meant to suggest "formulas" and "words", while "n" and "v" suggest "name" and "value":
+Here is one such template, using a made-up convention of `words.0` for the first entry in the words value, `words.1` for the second.
 
 ```urlencoded
-?{+fn0}={+fv0}&{+fn1}={+fv1}&{+fn2}={+fv2}&{wn}={wv0} {wv1} {wv2}
+?a={+a}&b={+b}&c={+c}&words={words.0} {words.1} {words.2}
 ```
 
-We'll also need to pre-process the names and values for `formulas` because while `/` and most other reserved characters are allowed in the query string by RFC3986, `[`, `]`, and `#` [are not](https://datatracker.ietf.org/doc/html/rfc3986#appendix-A), and `&`, `=`, and `+` all have [special behavior](https://www.rfc-editor.org/rfc/rfc1866#section-8.2.1) in the `application/x-www-form-urlencoded` format, which is what we are using in the query string.
+RFC6570 [mentions](https://www.rfc-editor.org/rfc/rfc6570.html#section-2.4.2) the use of `.` "to indicate name hierarchy in substructures," but does not define any specific naming convention or behavior for it.
+Since the `.` usage is not automatic, we'll need to construct an appropriate input structure for this new template.
+
+We'll also need to pre-process the values for `formulas` because while `/` and most other reserved characters are allowed in the query string by RFC3986, `[`, `]`, and `#` [are not](https://datatracker.ietf.org/doc/html/rfc3986#appendix-A), and `&`, `=`, and `+` all have [special behavior](https://www.rfc-editor.org/rfc/rfc1866#section-8.2.1) in the `application/x-www-form-urlencoded` format, which is what we are using in the query string.
 
 Setting `allowReserved: true` does _not_ make reserved characters that are not allowed in URIs allowed, it just allows them to be _passed through expansion unchanged._
 Therefore, any tooling still needs to percent-encode those characters because reserved expansion will not do it, but it _will_ leave the percent-encoded triples unchanged.
-See also Appendix D for further guidance on percent-encoding and form media types, including guidance on handling the delimiter characters for `spaceDelimited`, `pipeDelimited`, and `deepObject` in parameter names and values.
+See also [Appendix E](#to indicate name hierarchy in substructures) for further guidance on percent-encoding and form media types, including guidance on handling the delimiter characters for `spaceDelimited`, `pipeDelimited`, and `deepObject` in parameter names and values.
 
-So here is our data structure that arranges the names and values to suit the template above, where names and values for `formulas` have `[]#&=+` pre-percent encoded (although only `+` appears in this example):
+So here is our data structure that arranges the names and values to suit the template above, where values for `formulas` have `[]#&=+` pre-percent encoded (although only `+` appears in this example):
 
 ```YAML
-fn0: a
-fv0: x%2By
-fn1: b
-fv1: x/y
-fn2: c
-fv2: x^y
-wn: words
-wv0: math
-wv1: is
-wv2: fun
+a: x%2By
+b: x/y
+c: x^y
+words.0: math
+words.1: is
+words.2: fun
 ```
 
 Expanding our manually assembled template with our restructured data yields the following query string:
 
 ```urlencoded
 ?a=x%2By&b=x/y&c=x%5Ey&words=math%20is%20fun
-
 ```
 The `/` and the pre-percent-encoded `%2B` have been left alone, but the disallowed `^` character (inside a value) and space characters (in the template but outside of the expanded variables) were percent-encoded.
 
@@ -3723,19 +3723,48 @@ This means that the manually constructed URI Template and restructured data need
 Restructured data:
 
 ```YAML
-wn: words
-wv0: hello
-wv1: world
+words.0: hello
+words.1: world
 ```
 
 Manually constructed URI Template:
 
 ```urlencoded
-?{wn}={wv0} {wv1}
+?words={words.0} {words.1}
 ```
 
 Result:
 
 ```urlencoded
 ?words=hello%20world
 ```
+
+#### Illegal Variable Names as Parameter Names
+In this example, the heart emoji is not legal in URI Template names (or URIs):
+
+```YAML
+parameters:
+- name: ❤️
+  in: query
+  schema:
+    type: string
+```
+
+We can't just pass `❤️: love!` to an RFC6570 implementation.
+Instead, we have to pre-percent-encode the name (which is a six-octet UTF-8 sequence) in both the data and the URI Template:
+
+```YAML
+%E2%9D%A4%EF%B8%8F: love!
+```
+
+```urlencoded
+{?%E2%9D%A4%EF%B8%8F}
+```
+
+This will expand to the result:
+
+```urlencoded
+?%E2%9D%A4%EF%B8%8F=love%21
+```
+
+## <a name="percentEncodingAndFormMediaTypes"></a>Appendix E: Percent-Encoding and Form Media Types
