Merge pull request #3857 from handrews/enc-304

Encoding Object content and header clarifications (3.0.4)

Author: miqui

versions/3.0.4.md

@@ -1646,19 +1646,72 @@ An `encoding` attribute is introduced to give you control over the serialization
 A single encoding definition applied to a single schema property.
 See [Appendix B](#dataTypeConversion) for a discussion of converting values of various types to string representations.
 
-##### Fixed Fields
+Properties are correlated with `multipart` parts using the `name` parameter to `Content-Disposition: form-data`, and with `application/x-www-form-urlencoded` using the query string paramter names.
+In both cases, their order is implementation-defined.
+
+###### Common Fixed Fields
+
+These fields MAY be used either with or without the RFC6570-style serialization fields defined in the next section below.
+
+Field Name | Type | Description
+---|:---:|---
+<a name="encodingContentType"></a>contentType | `string` | The `Content-Type` for encoding a specific property. The value is a comma-separated list, each element of which is either a specific media type (e.g. `image/png`) or a wildcard media type (e.g. `image/*`). Default value depends on the property type as shown in the table below.
+<a name="encodingHeaders"></a>headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | A map allowing additional information to be provided as headers. `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`.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+The default values for `contentType` are as follows, where an _n/a_ in the `format` column means that the presence or value of `format` is irrelevant:
+
+Property `type` | Property `format` | Default `contentType`
+------------- | --------------- | ---------------------
+`string` | `binary` | `application/octet-stream`
+`string` | _none, or any except `binary`_ | `text/plain`
+`number`, `integer`, or `boolean` | _n/a_ | `text/plain`
+`object` | _n/a_ | `application/json`
+`array` | _n/a_ | according to the `type` and `format` of the `items` schema
+
+Determining how to handle `null` values if `nullable: true` is present depends on how `null` values are being serialized.
+If `null` values are entirely omitted, then the `contentType` is irrelevant.
+See [Appendix B](#dataTypeConversion) for a discussion of data type conversion options.
+
+##### Fixed Fields for RFC6570-style Serialization
+
 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="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).
-
 See also [Appendix C: Using RFC6570 Implementations](#usingRFC6570Implementations) for additional guidance.
 
+The role of `contentType` with `application/x-www-form-urlencoded` request bodies was not described in detail in version 3.0.3 and earlier of this specification.
+To match the intent of these fields and be compatible with version 3.1 of this specification, it is RECOMMENDED that whenever any of `style`, `explode`, or `allowReserved` are present with an explicit value:
+
+* The value of `contentType`, whether it is explicitly defined or has the default value, is to be ignored
+* If any of `style`, `explode`, or `allowReserved` are _not_ present with explicit values, then they are to be treated as if they were present with their default values
+
+However, if all three of `style`, `explode`, and `allowReserved` fields are absent, it is RECOMMENDED that:
+
+* All three keywords are to be entirely ignored, rather than treated as having their default values
+* Encoding is to be based on `contentType` alone, whether it is present with an explicit value or absent and treated as having its default value
+
+This makes the presence of at least one of `style`, `explode`, or `allowReserved` with an explicit value equivalent to using `schema` with `in: query` Parameter Objects, and their absence the equivalent of using `content`, but with the media type specified in `contentType` rather than through a Media Type Object.
+
+###### Encoding `multipart` Media Types
+
+The `form-data` disposition and its `name` parameter are mandatory for `multipart/form-data` ([RFC7578 §4.2](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.2)).
+Array properties are handled by applying the same `name` to multiple parts, as is recommended by [RFC7578 §4.3](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3) for supplying multiple values per form field.
+See [RFC7578 §5](https://www.rfc-editor.org/rfc/rfc7578.html#section-5) for guidance regarding non-ASCII part names.
+
+Various other `multipart` types, most notable `multipart/mixed` ([RFC2046 §5.1.3](https://www.rfc-editor.org/rfc/rfc2046.html#section-5.1.3)) neither require nor forbid specific `Content-Disposition` values, which means care must be taken to ensure that any values used are supported by all relevant software.
+It is not currently possible to correlate schema properties with unnamed, ordered parts in media types such as `multipart/mixed`, but implementations MAY choose to support such types when `Content-Disposition: form-data` is used with a `name` parameter.
+
+Note that there are significant restrictions on what headers can be used with `multipart` media types in general ([RFC2046 §5.1](https://www.rfc-editor.org/rfc/rfc2046.html#section-5.1)) and `multi-part/form-data` in particular ([RFC7578 §4.8](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.8)).
+
+Note also that `Content-Transfer-Encoding` is deprecated for `multipart/form-data` ([RFC7578 §4.7](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.7)) where binary data is supported, as it is in HTTP.
+Using `format: byte` for a multipart field is equivalent to setting `Content-Transfer-Encoding: base64`.
+If `format: byte` is used along with setting a different `Content-Transfer-Encoding` value with the `headers` field, the result is undefined.
+
 ##### Encoding Object Example
 
 `multipart/form-data` allows for binary parts: