From f1c2dcf2d1965ecea32fbabb373502e7da06f292 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 13 May 2026 09:58:23 -0700 Subject: [PATCH 01/11] describe stringified response codes without referencing a specific format In JSON, property keys are always strings; in YAML they may or not be depending on the parser, but other formats may also be in use (TOML, TOON etc). What matters is the resulting type(s) of the decoded data, not the specific formatting used for the serialized form. --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index d5ff769632..3a79cb8c9c 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2129,7 +2129,7 @@ call. | Field Pattern | Type | Description | | ---- | :----: | ---- | -| [HTTP Status Code](#http-status-codes) | [Response Object](#response-object) \| [Reference Object](#reference-object) | Any [HTTP status code](#http-status-codes) can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. This field MUST be enclosed in quotation marks (for example, `"200"`) for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `200` and `299`. Only the following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code. | +| [HTTP Status Code](#http-status-codes) | [Response Object](#response-object) \| [Reference Object](#reference-object) | Any [HTTP status code](#http-status-codes) can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. This field MUST be represented by a string (for example, `"200"` enclosed in quotes in YAML) for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `200` and `299`. Only the following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code. | This object MAY be extended with [Specification Extensions](#specification-extensions). From 1189d3a4a990881e8cb362d2d4151cf5c89a1c9d Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 13 May 2026 09:20:51 -0700 Subject: [PATCH 02/11] remove unnecessary use of "content" Appendix D no longer talks about percent-encoding of headers, as the specification is now clear that percent-encoding of headers is never done (with the exception of the use of style:form in Cookie headers). --- src/oas.md | 24 ++++++++---------------- 1 file changed, 8 insertions(+), 16 deletions(-) diff --git a/src/oas.md b/src/oas.md index 3a79cb8c9c..c3fec51ffa 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2000,8 +2000,6 @@ multipart/mixed: As described in [[?RFC2557]], a set of resources making up a web page can be sent in a `multipart/related` payload, preserving links from the `text/html` document to subsidiary resources such as scripts, style sheets, and images by defining a `Content-Location` header for each page. The first part is used as the root resource (unless using `Content-ID`, which RFC2557 advises against and is forbidden in this example), so we use `prefixItems` and `prefixEncoding` to define that it must be an HTML resource, and then allow any of several different types of resources in any order to follow. -The `Content-Location` header is defined using `content: {text/plain: {...}}` to avoid percent-encoding its URI value; see [Appendix D](#appendix-d-serializing-headers-and-cookies) for further details. - ```yaml components: headers: @@ -2010,12 +2008,10 @@ components: schema: false RFC2557ContentLocation: required: true - content: - text/plain: - schema: - $comment: Use a full URI (not a relative reference) - type: string - format: uri + schema: + $comment: Use a full URI (not a relative reference) + type: string + format: uri requestBodies: RFC2557: content: @@ -2060,8 +2056,6 @@ multipart/mixed: For `multipart/byteranges` [[RFC9110]] [Section 14.6](https://www.rfc-editor.org/rfc/rfc9110.html#section-14.6), a `Content-Range` header is required: -See [Appendix D](#appendix-d-serializing-headers-and-cookies) for an explanation of why `content: {text/plain: {...}}` is used to describe the header value. - ```yaml multipart/byteranges: itemSchema: @@ -2071,12 +2065,10 @@ multipart/byteranges: headers: Content-Range: required: true - content: - text/plain: - schema: - # The `pattern` regular expression that would - # be included in practice is omitted for simplicity - type: string + schema: + # The `pattern` regular expression that would + # be included in practice is omitted for simplicity + type: string ``` ##### Example: Nested `multipart/mixed` From 7ce1fec3d28f1067db4b531836adbedc7940820d Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 13 May 2026 10:03:05 -0700 Subject: [PATCH 03/11] be clear which property we are referring to --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index c3fec51ffa..fbc16e3c79 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1374,7 +1374,7 @@ Each field has its own set of media types with which it can be used; for all oth The behavior of the `encoding` field is designed to support web forms, and is therefore only defined for media types structured as name-value pairs that allow repeat values, most notably `application/x-www-form-urlencoded` and `multipart/form-data`. -To use the `encoding` field, each key under the field MUST exist as a property; `encoding` entries with no corresponding property SHALL be ignored. +To use the `encoding` field, each key under the field MUST exist in the data instance as a property; `encoding` entries with no corresponding property SHALL be ignored. Array properties MUST be handled by applying the given Encoding Object to produce one encoded value per array item, each with the same `name`, as is recommended by [[!RFC7578]] [Section 4.3](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3) for supplying multiple values per form field. For all other value types for both top-level non-array properties and for values, including array values, within a top-level array, the Encoding Object MUST be applied to the entire value. The order of these name-value pairs in the target media type is implementation-defined. From d1eb6f554b79e35ee666aa9656796e18e41dd440 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Tue, 12 May 2026 12:44:26 -0700 Subject: [PATCH 04/11] include an ABNF for contentType (amended) closes #4788 --- src/oas.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index fbc16e3c79..87b82255d7 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1715,7 +1715,7 @@ These fields MAY be used either with or without the RFC6570-style serialization | 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/*`), with ABNF: `media-range *( "," OWS media-range )`. The default value depends on the type as shown in the table below. | +| 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 [media type range](https://www.rfc-editor.org/rfc/rfc9110.html#appendix-A) (e.g. `image/*`). The default value depends on the type as shown in the table below. | | headers | Map[`string`, [Header Object](#header-object) \| [Reference Object](#reference-object)] | A map allowing additional information to be provided as headers. `Content-Type` is described separately and SHALL be ignored in this section. This field SHALL be ignored if the media type is not a `multipart`. | | encoding | Map[`string`, [Encoding Object](#encoding-object)] | Applies nested Encoding Objects in the same manner as the [Media Type Object](#media-type-object)'s `encoding` field. | | prefixEncoding | [[Encoding Object](#encoding-object)] | Applies nested Encoding Objects in the same manner as the [Media Type Object](#media-type-object)'s `prefixEncoding` field. | @@ -1741,6 +1741,14 @@ Determining how to handle a `type` value of `null` depends on how `null` values If `null` values are entirely omitted, then the `contentType` is irrelevant. See [Appendix B](#appendix-b-data-type-conversion) for a discussion of data type conversion options. +The contentType field is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax: + +```abnf +encoding-content-type = media-range *( "," OWS media-range ) +``` + +Here, media-range and OWS are taken from [[RFC9110]]. + ##### Fixed Fields for RFC6570-style Serialization | Field Name | Type | Description | From 1432e75e362eb7853209db9a9d88bb87621c30fe Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 13 May 2026 10:02:33 -0700 Subject: [PATCH 05/11] use extra markup to clarify intent We are specifically talking about the "encoding" keyword here, and the multipart/form-data media-type (most other multipart types decode to arrays). --- src/oas.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/oas.md b/src/oas.md index 87b82255d7..9a89bbf755 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1379,10 +1379,10 @@ Array properties MUST be handled by applying the given Encoding Object to produc For all other value types for both top-level non-array properties and for values, including array values, within a top-level array, the Encoding Object MUST be applied to the entire value. The order of these name-value pairs in the target media type is implementation-defined. -For `application/x-www-form-urlencoded`, the encoding keys MUST map to parameter names, with the values produced according to the rules of the [Encoding Object](#encoding-object). +For `application/x-www-form-urlencoded`, the `encoding` keys MUST map to parameter names, with the values produced according to the rules of the [Encoding Object](#encoding-object). See [Encoding the `x-www-form-urlencoded` Media Type](#encoding-the-x-www-form-urlencoded-media-type) for guidance and examples, both with and without the `encoding` field. -For `multipart`, the encoding keys MUST map to the [`name` parameter](https://www.rfc-editor.org/rfc/rfc7578#section-4.2) of the `Content-Disposition: form-data` header of each part, as is defined for `multipart/form-data` in [[!RFC7578]]. +For `multipart` types that decode to an object, such as `multipart/form-data`, the `encoding` keys MUST map to the [`name` parameter](https://www.rfc-editor.org/rfc/rfc7578#section-4.2) of the `Content-Disposition: form-data` header of each part, as is defined for `multipart/form-data` in [[!RFC7578]]. See [[!RFC7578]] [Section 5](https://www.rfc-editor.org/rfc/rfc7578.html#section-5) for guidance regarding non-ASCII part names. See [Encoding `multipart` Media Types](#encoding-multipart-media-types) for further guidance and examples, both with and without the `encoding` field. From 03344fc975c5cf953da34b15f114dab1f36424b4 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 13 May 2026 09:17:17 -0700 Subject: [PATCH 06/11] fix error: these keywords deal with items, not properties --- src/oas.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/oas.md b/src/oas.md index 9a89bbf755..eb38c4397c 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1272,8 +1272,8 @@ See [Working With Examples](#working-with-examples) for further guidance regardi | example | Any | Example of the media type; see [Working With Examples](#working-with-examples). | | examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the media type; see [Working With Examples](#working-with-examples). | | encoding | Map[`string`, [Encoding Object](#encoding-object)] | A map between a property name and its encoding information, as defined under [Encoding By Name](#encoding-by-name). The `encoding` field SHALL only apply when the media type is `multipart` or `application/x-www-form-urlencoded`. If no Encoding Object is provided for a property, the behavior is determined by the default values documented for the Encoding Object. This field MUST NOT be present if `prefixEncoding` or `itemEncoding` are present. | -| prefixEncoding | [[Encoding Object](#encoding-object)] | An array of positional encoding information, as defined under [Encoding By Position](#encoding-by-position). The `prefixEncoding` field SHALL only apply when the media type is `multipart`. If no Encoding Object is provided for a property, the behavior is determined by the default values documented for the Encoding Object. This field MUST NOT be present if `encoding` is present. | -| itemEncoding | [Encoding Object](#encoding-object) | A single Encoding Object that provides encoding information for multiple array items, as defined under [Encoding By Position](#encoding-by-position). The `itemEncoding` field SHALL only apply when the media type is `multipart`. If no Encoding Object is provided for a property, the behavior is determined by the default values documented for the Encoding Object. This field MUST NOT be present if `encoding` is present. | +| prefixEncoding | [[Encoding Object](#encoding-object)] | An array of positional encoding information, as defined under [Encoding By Position](#encoding-by-position). The `prefixEncoding` field SHALL only apply when the media type is `multipart`. If no Encoding Object is provided for an item, the behavior is determined by the default values documented for the Encoding Object. This field MUST NOT be present if `encoding` is present. | +| itemEncoding | [Encoding Object](#encoding-object) | A single Encoding Object that provides encoding information for multiple array items, as defined under [Encoding By Position](#encoding-by-position). The `itemEncoding` field SHALL only apply when the media type is `multipart`. If no Encoding Object is provided for an item, the behavior is determined by the default values documented for the Encoding Object. This field MUST NOT be present if `encoding` is present. | This object MAY be extended with [Specification Extensions](#specification-extensions). From 3fb284b0a520d0716e0a5dda6ddaf87714b7ebc6 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Sat, 30 May 2026 15:44:46 -0700 Subject: [PATCH 07/11] set the type here, to ensure the body content is deserialized as an object --- src/oas.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/oas.md b/src/oas.md index eb38c4397c..bb19b6a0e0 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1962,6 +1962,7 @@ requestBody: content: multipart/form-data: schema: + type: object properties: # The property name `file` will be used for all files. file: From 2f7b55b232167a505cddb9ce6ef241449b734b3c Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 3 Jun 2026 17:50:49 -0700 Subject: [PATCH 08/11] fix error: encoding objects also now apply to array items --- src/oas.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/oas.md b/src/oas.md index bb19b6a0e0..8d4f7f7671 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1753,9 +1753,9 @@ Here, media-range and OWS are taken from [[RFC9110]]. | Field Name | Type | Description | | ---- | :----: | ---- | -| style | `string` | Describes how a specific property value will be serialized depending on its type. See [Parameter Object](#parameter-object) for details on the [`style`](#parameter-style) field. The behavior follows the same values as `query` parameters, including the default value of `"form"` which applies only when `contentType` is _not_ being used due to one or both of `explode` or `allowReserved` being explicitly specified. Note that the initial `?` used in query strings is not used in `application/x-www-form-urlencoded` message bodies, and MUST be removed (if using an RFC6570 implementation) or simply not added (if constructing the string manually). This field SHALL be ignored if the media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. | -| 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, or when [`style`](#encoding-style) is `"deepObject"`, this field has no effect. When `style` is `"form"`, the default value is `true`. For all other styles, the default value is `false`. This field SHALL be ignored if the media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. | -| allowReserved | `boolean` | When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2), 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 target media type; see [URL Percent-Encoding](#url-percent-encoding) for details. The default value is `false`. This field SHALL be ignored if the media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. | +| style | `string` | Describes how a specific value will be serialized depending on its type. See [Parameter Object](#parameter-object) for details on the [`style`](#parameter-style) field. The behavior follows the same values as `query` parameters, including the default value of `"form"` which applies only when `contentType` is _not_ being used due to one or both of `explode` or `allowReserved` being explicitly specified. Note that the initial `?` used in query strings is not used in `application/x-www-form-urlencoded` message bodies, and MUST be removed (if using an RFC6570 implementation) or simply not added (if constructing the string manually). This field SHALL be ignored if the media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. | +| explode | `boolean` | When this is true, 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, or when [`style`](#encoding-style) is `"deepObject"`, this field has no effect. When `style` is `"form"`, the default value is `true`. For all other styles, the default value is `false`. This field SHALL be ignored if the media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. | +| allowReserved | `boolean` | When this is true, values are serialized using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2), 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 target media type; see [URL Percent-Encoding](#url-percent-encoding) for details. The default value is `false`. This field SHALL be ignored if the media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. | When using RFC6570-style serialization for `multipart/form-data`, URI percent-encoding MUST NOT be applied, and the value of `allowReserved` has no effect. See also [Appendix C: Using RFC6570 Implementations](#appendix-c-using-rfc6570-based-serialization) for additional guidance. From 92e840523d6f216dfea8d11d35e42d3add8a3ba0 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 24 Jun 2026 17:06:54 -0700 Subject: [PATCH 09/11] define a mechanism for preserving value/part order in forms This change is accompanied by an edit to the "Forms" page in the Media-Type Registry. --- src/oas.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/oas.md b/src/oas.md index 8d4f7f7671..eb9605a217 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1392,6 +1392,8 @@ See [Encoding `multipart` Media Types](#encoding-multipart-media-types) for furt Most `multipart` media types, including `multipart/mixed` which defines the underlying rules for parsing all `multipart` types, do not have named parts. Data for these media types are modeled as an array, with one item per part, in order. +For applications that wish to preserve part order, `multipart/form-data` content may also be modelled as an array, with one item per part, in order (where each item consists of an object containing the name/value pair); the `schema` SHALL be used to determine whether deserializing to an `object` or an `array` is preferred. See examples in [Media Type Registry: Forms](https://spec.openapis.org/registry/media-type/forms). + To use the `prefixEncoding` and/or `itemEncoding` fields, either `itemSchema` or an array `schema` MUST be present. These fields are analogous to the `prefixItems` and `items` JSON Schema keywords, with `prefixEncoding` (if present) providing an array of Encoding Objects that are each applied to the value at the same position in the data array, and `itemEncoding` applying its single Encoding Object to all remaining items in the array. As with `prefixItems`, it is _not_ an error if the instance array is shorter than the `prefixEncoding` array; the additional Encoding Objects SHALL be ignored. From ed1d645dd7523aeff1cc3f7a583b881d874afd12 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Tue, 9 Jun 2026 13:50:10 -0700 Subject: [PATCH 10/11] some media-types, e.g. multipart/form-data, define an explicit ordering --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index eb9605a217..7ca864131b 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1377,7 +1377,7 @@ The behavior of the `encoding` field is designed to support web forms, and is th To use the `encoding` field, each key under the field MUST exist in the data instance as a property; `encoding` entries with no corresponding property SHALL be ignored. Array properties MUST be handled by applying the given Encoding Object to produce one encoded value per array item, each with the same `name`, as is recommended by [[!RFC7578]] [Section 4.3](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3) for supplying multiple values per form field. For all other value types for both top-level non-array properties and for values, including array values, within a top-level array, the Encoding Object MUST be applied to the entire value. -The order of these name-value pairs in the target media type is implementation-defined. +The order of these name-value pairs in the target media type is implementation-defined when not explicitly defined by that media-type's specification. For `application/x-www-form-urlencoded`, the `encoding` keys MUST map to parameter names, with the values produced according to the rules of the [Encoding Object](#encoding-object). See [Encoding the `x-www-form-urlencoded` Media Type](#encoding-the-x-www-form-urlencoded-media-type) for guidance and examples, both with and without the `encoding` field. From a5edad7c88a9d47c28e894aa69cda68f94dfa271 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 3 Jun 2026 17:44:59 -0700 Subject: [PATCH 11/11] encoding headers are not needed for serializing an array We have the names for each part, as the parsed data uses the format: [ { : }, { : }, ... ] --- src/oas.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/oas.md b/src/oas.md index 7ca864131b..e0f622277a 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1402,8 +1402,8 @@ The `itemEncoding` field can also be used with `itemSchema` to support streaming ##### Additional Encoding Approaches -The `prefixEncoding` field can be used with any `multipart` content to require a fixed part order. -This includes `multipart/form-data`, for which the Encoding Object's `headers` field MUST be used to provide the `Content-Disposition` and part name, as no property names exist to provide the names automatically. +The `prefixEncoding` and/or `itemEncoding` fields, and/or usage of a [`schema` indicating an array type](#non-json-data) (or `itemSchema`), can be used with any `multipart` content to require a fixed part order. +This includes `multipart/form-data`, in which the property name of each item is used to populate the `Content-Disposition` headers with the part name. Prior versions of this specification advised using the [`name` parameter](https://www.rfc-editor.org/rfc/rfc7578#section-4.2) of the `Content-Disposition: form-data` header of each part with `multipart` media types other than `multipart/form-data` in order to work around the limitations of the `encoding` field. Implementations MAY choose to support this workaround, but as this usage is not common, implementations of non-`form-data` `multipart` media types are unlikely to support it.