Skip to content

v3.3: define a mechanism for preserving value/part order in forms #5403

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
miqui merged 4 commits into from
Jul 2, 2026
Merged

v3.3: define a mechanism for preserving value/part order in forms #5403

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
313c7e9
define a mechanism for preserving value/part order in forms
karenetheridge Jun 25, 2026
8396745
some media-types, e.g. multipart/form-data, define an explicit ordering
karenetheridge Jun 9, 2026
5972558
encoding headers are not needed for serializing an array
karenetheridge Jun 4, 2026
0f6075e
Apply suggestion from @handrews
miqui Jul 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions src/oas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,9 +57,9 @@

### JSON and YAML Compatibility

In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](https://yaml.org/spec/1.2/spec.html) is RECOMMENDED along with the additional constraints listed in [[!RFC9512]] [Section 3.4](https://www.rfc-editor.org/rfc/rfc9512.html#name-yaml-and-json).

Check failure on line 60 in src/oas.md

View workflow job for this annotation

GitHub Actions / lint 

[Linkspector] reported by reviewdog 🐶
Cannot reach https://yaml.org/spec/1.2/spec.html Status: 404

Raw Output:
message:"Cannot reach https://yaml.org/spec/1.2/spec.html Status: 404"  location:{path:"src/oas.md"  range:{start:{line:60  column:92}  end:{line:60  column:134}}}  severity:ERROR  source:{name:"linkspector"  url:"https://github.com/UmbrellaDocs/linkspector"}

The recommendation in previous versions of this specification to restrict YAML to its "JSON" [schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231) allowed for the inclusion of certain values that (despite the name) cannot be represented in JSON.

Check failure on line 62 in src/oas.md

View workflow job for this annotation

GitHub Actions / lint 

[Linkspector] reported by reviewdog 🐶
Cannot reach https://yaml.org/spec/1.2/spec.html#id2803231 Status: 404

Raw Output:
message:"Cannot reach https://yaml.org/spec/1.2/spec.html#id2803231 Status: 404"  location:{path:"src/oas.md"  range:{start:{line:62  column:94}  end:{line:62  column:157}}}  severity:ERROR  source:{name:"linkspector"  url:"https://github.com/UmbrellaDocs/linkspector"}
OAD authors SHOULD NOT rely on any such JSON-incompatible YAML values.

### Case Sensitivity
Expand Down Expand Up @@ -1378,7 +1378,7 @@
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.
Expand All @@ -1393,6 +1393,8 @@
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.
Expand All @@ -1401,8 +1403,8 @@

##### 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.
Comment thread
miqui marked this conversation as resolved.
Outdated

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.
Expand Down
Loading