From a4f3498be540785dbc1a4eba8bfe3e4ad9453de0 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 10 Jun 2024 16:25:51 -0700 Subject: [PATCH] Split up Encoding fields like Param/Header This splits the Encoding Object's fixed fields table to make the usage more clear, and closer to how it is presented for the Parameter and Header Objects --- versions/3.0.4.md | 44 +++++++++++++++++++++++++------------------- 1 file changed, 25 insertions(+), 19 deletions(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 87becf3752..a541f57281 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -1624,14 +1624,14 @@ See [Appendix B](#dataTypeConversion) for a discussion of converting values of v 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. -##### Fixed Fields +###### 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 ---|:---:|--- 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. 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`. -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`. -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`. -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). @@ -1644,8 +1644,29 @@ Property Type | Property Format | Default `contentType` `object` | _n/a_ | `application/json` `array` | _n/a_ | according to the `type` and `format` of the `items` schema +##### Fixed Fields for RFC6570-style Serialization + +Field Name | Type | Description +---|:---:|--- +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`. +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`. +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`. + 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)). @@ -1661,21 +1682,6 @@ Note also that `Content-Transfer-Encoding` is deprecated for `multipart/form-dat 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 the `application/x-www-form-urlencoded` Media Type - -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 Object Example `multipart/form-data` allows for binary parts: