Further clarify style+explode examples

handrews · handrews · commit 48478764fd80 · 2024-06-12T16:12:32.000-07:00
This aligns all examples with RFC6570 operator prefixing behavior,
which was previously only shown for `matrix` and `label`.  The
non-RFC6570 styles (`spaceDelimited`, `pipeDelimited`, and
`deepObject`) are treated as analogues of `form` and therefore
prefixed with a `?`.  The lack of suitablity of this for
cookie parameters has been addressed with an appendix in
another change, and the appendix has been stubbed out here to
ensure that the link is valid.
diff --git a/versions/3.0.4.md b/versions/3.0.4.md
@@ -1072,6 +1072,8 @@ The rules for serialization of the parameter are specified in one of two ways.
 Parameter Objects MUST include either a `content` field or a `schema` field, but not both.
 See [Appendix B](#dataTypeConversion) for a discussion of converting values of various types to string representations.
 
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
 ###### Common Fixed Fields
 
 These fields MAY be used with either `content` or `schema`.
@@ -1083,7 +1085,7 @@ Field Name | Type | Description
 <a name="parameterDescription"></a>description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
 <a name="parameterRequired"></a>required | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.
 <a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.
-<a name="parameterAllowEmptyValue"></a> allowEmptyValue | `boolean` | If `true`, clients MAY pass a zero-length string value in place of parameters that would otherwise be omitted entirely, which the server SHOULD interpret as the parameter being unused. Default value is `false`. If [`style`](#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Interactions between this field and the parameter's [Schema Object](#schemaObject) are implementation-defined. This field is valid only for `query` parameters. Use of this property is NOT RECOMMENDED, and it is likely to be removed in a later revision.
+<a name="parameterAllowEmptyValue"></a> allowEmptyValue | `boolean` | If `true`, clients MAY pass a zero-length string value in place of parameters that would otherwise be omitted entirely, which the server SHOULD interpret as the parameter being unused. Default value is `false`. If [`style`](#parameterStyle) is used, and if [behavior is _n/a_ (cannot be serialized)](#style-examples), the value of `allowEmptyValue` SHALL be ignored. Interactions between this field and the parameter's [Schema Object](#schemaObject) are implementation-defined. This field is valid only for `query` parameters. Use of this property is NOT RECOMMENDED, and it is likely to be removed in a later revision.
 
 Note that while `"Cookie"` as a `name` is not forbidden with `in: header`, the effect of defining a cookie parameter that way is undefined; use `in: cookie` instead.
 
@@ -1098,7 +1100,7 @@ Serializing with `schema` is NOT RECOMMENDED for `in: cookie` parameters, `in: h
 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="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`. Note that despite `false` being the default for `deepObject`, the combination of `false` with `deepObject` is undefined.
 <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; see [Working With Examples](#working-with-examples).
@@ -1141,24 +1143,31 @@ Assume a parameter named `color` has one of the following values:
    array -> ["blue","black","brown"]
    object -> { "R": 100, "G": 200, "B": 150 }
 ```
-The following table shows examples of the different serializations for each value.
-The examples are percent-encoded as required by RFC6570 and RFC3986; see [Appendix E](#percentEncodingAndFormMediaTypes) for a thorough discussion of percent-encoding concerns, including why unencoded `|` (`%7C`), `[` (`%5B`), and `]` (`%5D`) seem to work in some environments despite not being compliant.
+
+The following table shows examples, as would be shown with the `example` or `examples` keywords, of the different serializations for each value.
+
+* The value _e/s_ denotes the empty string
+* The behavior of combinations marked _n/a_ is undefined
+* The `empty` column refers to values that [RFC6570 §2.3](https://www.rfc-editor.org/rfc/rfc6570.html#section-2.3) describes as "undefined", and is unrelated to the `allowEmptyValues` field
+* For `form` and the non-RFC6570 query string styles `spaceDelimited`, `pipeDelimited`, and `deepObject`, each example is shown prefixed with `?` as if it were the only query parameter; see [Appendix C](#usingRFC6570Implementations) for more information on constructing query strings from multiple parameters, and [Appendix D](#serializingHeadersAndCookies) for warnings regarding `form` and cookie parameters
+* The examples are percent-encoded as required by RFC6570 and RFC3986; see [Appendix E](#percentEncodingAndFormMediaTypes) for a thorough discussion of percent-encoding concerns, including why unencoded `|` (`%7C`), `[` (`%5B`), and `]` (`%5D`) seem to work in some environments despite not being compliant.
 
 [`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object`
 ----------- | ------ | -------- | -------- | -------- | -------
 matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150
 matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150
 label | false | . | .blue | .blue,black,brown | .R,100,G,200,B,150
 label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150
-simple | false | n/a | blue | blue,black,brown | R,100,G,200,B,150
-simple | true | n/a | blue | blue,black,brown | R=100,G=200,B=150
-form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150
-form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150
-spaceDelimited | false | n/a | n/a | color=blue%20black%20brown | color=R%20100%20G%20200%20B%20150
-pipeDelimited | false | n/a | n/a | color=blue%7Cblack%7Cbrown | color=R%7C100%7CG%7C200%7CB%7C150
-deepObject | true | n/a | n/a | n/a | color%5BR%5D=100&color%5BG%5D=200&color%5BB%5D=150
-
-This object MAY be extended with [Specification Extensions](#specificationExtensions).
+simple | false | _e/s_ | blue | blue,black,brown | R,100,G,200,B,150
+simple | true | _e/s_ | blue | blue,black,brown | R=100,G=200,B=150
+form | false | ?color= | ?color=blue | ?color=blue,black,brown | ?color=R,100,G,200,B,150
+form | true | ?color= | ?color=blue | ?color=blue&color=black&color=brown | ?R=100&G=200&B=150
+spaceDelimited | false | _n/a_ | _n/a_ | ?color=blue%20black%20brown | ?color=R%20100%20G%20200%20B%20150
+spaceDelimited | true | _n/a_ | _n/a_ | _n/a_ | _n/a_
+pipeDelimited | false | _n/a_ | _n/a_ | ?color=blue%7Cblack%7Cbrown | ?color=R%7C100%7CG%7C200%7CB%7C150
+pipeDelimited | true | _n/a_ | _n/a_ | _n/a_ | _n/a_
+deepObject | false | _n/a_ | _n/a_ | _n/a_ | _n/a_
+deepObject | true | _n/a_ | _n/a_ | _n/a_ | ?color%5BR%5D=100&color%5BG%5D=200&color%5BB%5D=150
 
 ##### Parameter Object Examples
 
@@ -1685,9 +1694,9 @@ See [Appendix B](#dataTypeConversion) for a discussion of data type conversion o
 
 Field Name | Type | Description
 ---|:---:|---
-<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](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="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. Note that the initial `?` using in query strings is not used in `applcation/x-www-form-urlencoded` message bodies, and MUST be removed (if using an RFC6570 implementation) or simply not added (if constructing the string manually). 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`. Note that despite `false` being the default for `deepObject`, the combination of `false` with `deepObject` is undefined. 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 property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.
 
 See also [Appendix C: Using RFC6570 Implementations](#usingRFC6570Implementations) for additional guidance.
 
