From 313c7e9144be2b4947bffd793018535b8a5155c1 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 24 Jun 2026 17:06:54 -0700 Subject: [PATCH 1/3] 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 d5b3645174..6c3aac21e3 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1393,6 +1393,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 8396745c13a4d86f65a6bb291f7ec6a8862e692e Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Tue, 9 Jun 2026 13:50:10 -0700 Subject: [PATCH 2/3] 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 6c3aac21e3..1c894c4c5f 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1378,7 +1378,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 5972558fd8da06c0f8e77f40ae0b46c2bb8ec97c Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Wed, 3 Jun 2026 17:44:59 -0700 Subject: [PATCH 3/3] 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 1c894c4c5f..f5492902bf 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1403,8 +1403,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 are 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.