v3.3: remove invalid mention of prefixEncoding, itemEncoding here#5441
v3.3: remove invalid mention of prefixEncoding, itemEncoding here#5441karenetheridge wants to merge 2 commits into
Conversation
In section 4.14.5.2 (Encoding by Position) we already said: "To use the prefixEncoding and/or itemEncoding fields, either itemSchema or a schema indicating an array type MUST be present.", however there is no parallel guidance in 4.14.5.1 (Encoding by Name) that says that the encoding field MUST also have a schema indicating an object type present.
karenetheridge
changed the title
This is the same phrasing as in "Encoding by Name" which states that the `encoding` fields do nothing if they don't have a corresponding data instance.
7cc6e85 to
82fb935
Compare
karenetheridge
left a comment
karenetheridge
left a comment
There was a problem hiding this comment.
some extra commentary here as I keep re-reading various sections of the spec and noticing inconsistencies between them, or things that we mandate without a clear reason for doing so.
| ##### 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. |
There was a problem hiding this comment.
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).
| 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. |
There was a problem hiding this comment.
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.
1 participant
In section 4.14.5.2 (Encoding by Position) we already said: "To use the prefixEncoding and/or itemEncoding fields, either itemSchema or a schema indicating an array type MUST be present.", however there is no parallel guidance in 4.14.5.1 (Encoding by Name) that says that the encoding field MUST also have a schema indicating an object type present.
(I already edited this sentence earlier in this release cycle to add mention of prefixEncoding alongside itemEncoding, but this entire sentence is inconsistent with the previous section, so we should either remove this sentence entirely, or soften the previous statement about prefixEncoding and itemEncoding requiring an array schema.)