From 7faf8e3def9ab882ea9571c784cd7c7ad5e19fbe Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 13 May 2026 09:58:23 -0700 Subject: [PATCH 01/13] describe stringified response codes without referencing a specific format (#5332) 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 c31702d246..28796cbce1 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 e922d90ad509c7059ffd92c40210f8d991bbe37a Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 13 May 2026 09:20:51 -0700 Subject: [PATCH 02/13] remove unnecessary use of "content" (#5333) 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 28796cbce1..8ed735b695 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 2aad4125e7b9adc29c839ba38bba157259a445c1 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 13 May 2026 10:03:05 -0700 Subject: [PATCH 03/13] be clear which property we are referring to (#5330) --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 8ed735b695..e4b17113ee 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 16734c2a2e93bed0f1f0e937b19667be4d4d8356 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Tue, 12 May 2026 12:44:26 -0700 Subject: [PATCH 04/13] include an ABNF for contentType (amended) (#5324) closes #4788 --- src/oas.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index e4b17113ee..ee89fa9e75 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 7648160412e9d51db1f288a38cca303c60c68a55 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 13 May 2026 10:02:33 -0700 Subject: [PATCH 05/13] use extra markup to clarify intent (#5331) 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 ee89fa9e75..645855ffef 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 d8dc4382447a7739a55b3607ec828c7f9fda6795 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 13 May 2026 09:17:17 -0700 Subject: [PATCH 06/13] fix error: these keywords deal with items, not properties (#5386) --- src/oas.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/oas.md b/src/oas.md index 645855ffef..9c6fa17835 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 084f97ee436c56e221bf9e405bf1e42206e75c82 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Sat, 30 May 2026 15:44:46 -0700 Subject: [PATCH 07/13] set the type here, to ensure the body content is deserialized as an object (#5390) --- src/oas.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/oas.md b/src/oas.md index 9c6fa17835..a56692bd4e 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 fd245a7b8170699316aa3fe3d32d551799f0e03c Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 3 Jun 2026 17:50:49 -0700 Subject: [PATCH 08/13] fix error: encoding objects also now apply to array items (#5404) --- src/oas.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/oas.md b/src/oas.md index a56692bd4e..6acd9f045a 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 fd1fe2e1f63d6129b487b460fe7ec46f4a56dea3 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 24 Jun 2026 17:06:54 -0700 Subject: [PATCH 09/13] define a mechanism for preserving value/part order in forms (#5403) 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 6acd9f045a..4bba8fbc9d 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 a84af72765b963eba70e303a34d7db7f897ad276 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Tue, 9 Jun 2026 13:50:10 -0700 Subject: [PATCH 10/13] some media-types, e.g. multipart/form-data, define an explicit ordering (#5403) --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 4bba8fbc9d..089bc9131a 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 d8107c201ad4dc12d1cc02f79376dc96313dd25f Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 3 Jun 2026 17:44:59 -0700 Subject: [PATCH 11/13] encoding headers are not needed for serializing an array (#5403) 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 089bc9131a..e0b514fcd8 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. From b5ab7d02903224dcdfce0d6a16f3c3879abb1574 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 13 May 2026 09:19:21 -0700 Subject: [PATCH 12/13] replace "array schema" with clearer definition (#5334) --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index e0b514fcd8..de095a2df3 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1394,7 +1394,7 @@ Data for these media types are modeled as an array, with one item per part, in o 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. +To use the `prefixEncoding` and/or `itemEncoding` fields, either `itemSchema` or a [`schema` indicating an array type](#non-json-data) 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 e59e3a819281af05862b00a58a1f7c4558ed7f17 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 3 Jun 2026 17:37:50 -0700 Subject: [PATCH 13/13] clarify how encoding works for deserialization too (#5422) ..and be more specific about what an "array property" and "array schema" are --- src/oas.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/src/oas.md b/src/oas.md index de095a2df3..c84ac1dff1 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1375,11 +1375,13 @@ 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 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. +When serializing, property values of the array type 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; when deserializing, the Encoding object is applied to each item of the array property of the same name. +For deserialization to an object, multiple values with the same `name` MUST be collapsed into an array value for that named property, with one item per value, in order. +For all other value types for both top-level non-array property values and for other values, including items of the array type 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 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). +For `application/x-www-form-urlencoded`, the `encoding` keys MUST map to parameter names, with the serialized 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` 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]]. @@ -1926,11 +1928,19 @@ requestBody: schema: type: object properties: - # No Encoding Object, so use default `text/plain` + # No Encoding Object for this property, so use string default `text/plain` id: type: string format: uuid + # An Encoding object allows multiple values to be provided for this + # property, without any attempt to decode the array as application/json + alias: + type: [ string, array ] + pattern: '^[A-Z][a-z]*$' + items: + pattern: '^[A-Z][a-z]*$' + # Encoding Object overrides the default `application/json` content type # for each item in the array with `application/xml; charset=utf-8` addresses: @@ -1944,6 +1954,8 @@ requestBody: profileImage: {} encoding: + alias: + contentType: text/plain addresses: contentType: application/xml; charset=utf-8 profileImage: