Appendix on RFC6570-derived behavior

This is the first of several appendixes to be added to clarify
the most obscure details of Parameter Object and Encoding Object
serialization.

This clarifies the correspondence between OAS fields and RFC6570
operators, and acknowledges that some field values and combinations
do not have analogues.  It provides further guidance for how to
use RFC6570 implementations to support these configurations.

This includes a SHOULD directive regarding using RFC6570 expansion
with the non-RFC6570 styles, as the use of "explode" and
"allowReserved" does not otherwise make any sense.  It perhaps
could be a MUST.

This also includes an acknowledgement of ambiguity in reconciling
`contentType` and `style` in the Encoding Object, make the behavior

Author: handrews

versions/3.0.4.md

@@ -1060,6 +1060,8 @@ Field Name | Type | Description
 <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.
 
+See also [Appendix B: Using RFC6570 Implementations](#usingRFC6570Implementations) for additional guidance.
+
 ###### Fixed Fields and considerations for use with `content`
 
 For more complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter, as well as give examples of its use.
@@ -1607,6 +1609,9 @@ Field Name | Type | Description
 <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` | 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`.
 
+When the request body media type is `application/x-www-form-urlencoded`, the way contradictions between `style` and `contentType` are handled is _implementation-defined_.
+For compatibility with version 3.1 of this specification, it is RECOMMENDED that `contentType` be disregarded when an explicit value is present for `style`, and for `contentType` to control the serialization (without use of RFC6570 expansion) if `style` is _not_ present.
+
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
 ##### Encoding Object Example
@@ -3495,3 +3500,55 @@ Version   | Date       | Notes
 1.2       | 2014-03-14 | Initial release of the formal document.
 1.1       | 2012-08-22 | Release of Swagger 1.1
 1.0       | 2011-08-10 | First release of the Swagger Specification
+
+## <a name="usingRFC6570Implementations"></a>Appendix B: Using RFC6570 Implementations
+
+Serialization is defined in terms of RFC6570 URI Templates in two scenarios:
+
+Object | Condition
+------ | ---------
+Parameter Object | When `schema` is present
+Encoding Object | When encoding for `application/x-www-form-urlencoded` and any of `style`, `explode`, or `allowReserved` are used
+
+See the [Encoding Object](#encodingObject) for a discussion of whether the default values of the three fields is considered to be "using" those fields.
+
+Implementations of this specification MAY use an implementation of RFC6570 to perform variable expansion, however, some caveats apply.
+
+### Equivalences Between Fields and RFC6570 Operators
+
+Certain field values translate to RFC6570 operators (or lack thereof):
+
+field | value | operator
+----- | ----- | --------
+style | simple | _n/a_
+style | matrix | `;`
+style | label | `.`
+style | form | `?`
+allowReserved | `false` | _n/a_
+allowReserved | `true` | `+`
+explode | `false` | _n/a_
+explode | `true` | `*`
+
+Multiple `style: form` parameters are equivalent to a single RFC6570 "varspec" using the `?` operator:
+
+```YAML
+- name: foo
+  in: query
+  schema:
+    type: object
+  explode: true
+- name: bar
+  in: query
+  schema:
+    type: string
+```
+
+This example is equivalent to RFC6570's `{?foo*,bar}`, and ***NOT*** `{?foo*}{&bar}`.
+The `&` operator has no equivalent in OpenAPI:
+
+### Non-RFC6570 Field Values and Combinations
+
+Configurations with no direct RFC6570 equivalence SHOULD also be handled according to RFC6570.
+Implementations MAY pass individual names and values to RFC6570 regular or reserved expansion (based on `allowReserved`), and then assemble the results into a string with the appropriate deliiters.
+
+This includes the styles `pipeDelimited`, `spaceDelimited`, and `deepObject`, as well as the combination of the `form` style with `allowReserved: true`.