Further clarify style+explode examples

handrews · handrews · commit d236464feb82 · 2024-06-08T19:15:34.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
@@ -1048,6 +1048,8 @@ There are four possible parameter locations specified by the `in` field:
 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.
 
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
 ###### Common Fixed Fields
 
 These fields MAY be used with either `content` or `schema`.
@@ -1059,7 +1061,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.
 
 ###### Fixed Fields for use with `schema`
 
@@ -1069,7 +1071,7 @@ When `example` or `examples` are provided in conjunction with the `schema` objec
 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` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. 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.
@@ -1108,24 +1110,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
 
@@ -1623,8 +1632,8 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="encodingContentType"></a>contentType | `string` | The Content-Type for encoding a specific property. Default value depends on the property type: for `string` with `format` being `binary` – `application/octet-stream`; for other primitive types – `text/plain`; for `object` - `application/json`; for `array` – the default is defined based on the inner type. The value can be a specific media type (e.g. `application/json`), a wildcard media type (e.g. `image/*`), or a comma-separated list of the two types.
 <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="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` messages, 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` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. The default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
@@ -3533,6 +3542,8 @@ Version   | Date       | Notes
 
 ## <a name="usingRFC6570Implementations"></a>Appendix C: Using RFC6570 Implementations
 
+## <a name="serializingHeadersAndCookies"></a>Appendix D: Serializing Headers and Cookies
+
 ## <a name="percentEncodingAndFormMediaTypes"></a>Appendix E: Percent-Encoding and Form Media Types
 
 _**NOTE:** In this section, the `application/x-www-form-urlencoded` and `multipart/form-data` media types are abbreviated as `form-urlencoded` and `form-data`, respectively, for readability._
