Skip to content

Commit

Permalink
Split up Encoding fields like Param/Header
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@handrews
handrews committed Jun 10, 2024
1 parent 9a82f73 commit a4f3498
Showing 1 changed file with 25 additions and 19 deletions.
44 changes: 25 additions & 19 deletions versions/3.0.4.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
---|:---:|---
<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`.
<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).

Expand All @@ -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
---|:---:|---
<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`.

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)).
Expand All @@ -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:
Expand Down

0 comments on commit a4f3498

Please sign in to comment.