Skip to content

v3.3: remove invalid mention of prefixEncoding, itemEncoding here #5441

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

Open
karenetheridge wants to merge 2 commits into
base: v3.3-dev
Choose a base branch
from
+3 −2
Open

v3.3: remove invalid mention of prefixEncoding, itemEncoding here #5441

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e07c6c6
remove invalid mention of prefixEncoding, itemEncoding here
karenetheridge Jul 20, 2026
82fb935
include parallel clause for encoding by position
karenetheridge Jul 21, 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
5 changes: 3 additions & 2 deletions src/oas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1397,15 +1397,16 @@ 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 a [`schema` indicating an array type](#non-json-data) MUST be present.
To use the `prefixEncoding` and/or `itemEncoding` fields, each item referenced by the field MUST exist in the data instance; `prefixEncoding` and `itemEncoding` entries with no corresponding item SHALL be ignored.

@karenetheridge karenetheridge Jul 21, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is mostly obvious, since if there is no data to operate on, what would the encoding object even do? but it is consistent with Encoding by Name.

The part that is removed also brings consistency with Encoding by Name, which does not require that type: object must exist in the schema, nor even does it require that there is a properties entry for each individual part name. Both multipart/form-data and multipart/mixed can be successfully serialized from their original object or array representations without either a schema or an encoding object, and deep objects can be deserialized successfully as well if Content-Type headers are included.


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.

The `itemEncoding` field can also be used with `itemSchema` to support streaming `multipart` content.

##### Additional Encoding Approaches

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.
Usage of a [`schema` indicating an array type](#non-json-data) (or `itemSchema`), can be used with any `multipart` content to produce a fixed part order.

@karenetheridge karenetheridge Jul 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't much like this statement either, because it is redundant for multipart content that is not form-data: other multipart types can only be deserialized to an array, as they have no part names, so there should be no need for a schema (or an encoding object, for that matter, if the part values are all ordinary strings, and even if they're serialized values, e.g. application/json, we don't need an encoding object to make use of Content-Type on the parts).

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