v3.2 Arrange encoding information more clearly #4562
Conversation
Refactor this to put the rules for mapping Encoding Objects to valules with the `encoding` field (which performs the mapping) rather than having most of it in the Encoding Object (which should focus on how to apply a single Encoding Object to a single value). This notably takes the special handling of arrays as repeated values out of the Encoding Object section (and the default `contentType` field value table) and moves it to the Media Type Object. The Encoding Object behavior is now consistent for all types, while the _mapping_ done by the `encoding` field handles the special case. The only change (as opposed to re-organization and re-wording) in this PR is the addition of a default `contentType` of `application/json` for array values, which in the context of the existing behavior is only relevant for array values nested under a top-level array. Past OAS versions were silent on this topic, and presumably it just does not come up much, but it was a gap we should fill. As dicussed in today's TDC call, we have increasing (and modern) use cases for supporting `multipart/mixed` (which we previously claimed to support but never did). This refactor makes possible future support easier by moving the array special case, which is governed by the `multipart/form-data` RFC, out of the Encoding Object (which needs to work with other `multipart` formats) and places it with the `encoding` field (which is web form-format-specific).
handrews
added
the
media and encoding
handrews
changed the title
|
Note that a lot of this could be backported to 3.1.2, although it's not clear to me that doing so would be the ideal move. |
| @@ -1615,10 +1617,33 @@ See [Working With Examples](#working-with-examples) for further guidance regardi | |||
| | <a name="media-type-schema"></a>schema | [Schema Object](#schema-object) | The schema defining the content of the request, response, parameter, or header. | | |||
| | <a name="media-type-example"></a>example | Any | Example of the media type; see [Working With Examples](#working-with-examples). | | |||
| | <a name="media-type-examples"></a>examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the media type; see [Working With Examples](#working-with-examples). | | |||
| | <a name="media-type-encoding"></a>encoding | Map[`string`, [Encoding Object](#encoding-object)] | A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. 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. | | |||
| | <a name="media-type-encoding"></a>encoding | Map[`string`, [Encoding Object](#encoding-object)] | A map between a property name and its encoding information for media types supporting name-value pairs and allowing duplicate names, as defined under [Encoding Usage and Restrictions](#encoding-usage-and-restrictions). | | |||
There was a problem hiding this comment.
I'm unclear why it is necessary for the media type to allow duplicate names. What breaks if the media type does not allow duplicate names?
There was a problem hiding this comment.
@mikekistler If you try to use an array value with a media type that does not support duplicate names, you will get duplicate names anyway, and that usually isn't good.
The only media types for which the encoding field (and indeed the Encoding Object as a whole) has well-defined behavior at all are application/x-www-form-urlencoded and multipart/form-data, both of which support duplicate names (which is how you are required to specify multiple file uploads). So this does not add any new restriction, it just documents the implicit restriction that already exists.
There was a problem hiding this comment.
@mikekistler I just pushed a commit noting the history of this field in implementing web forms, which (to me, at least) explains why the field has such a specific usage pattern. Please let me know if that helps! I agree that otherwise it seems quite random.
Co-authored-by: Mike Kistler <[email protected]>
Co-authored-by: Mike Kistler <[email protected]>
The oddities of its media type support derive from its history as the OAS implementation of web forms.
[NOTE: The empty "Media Type Registry" header is there to avoid build errors- it will be a minor conflict to resolve when PR #4554 is merged]
TL;DR: Supporting
multipart/mixed(streaming or otherwise) will require a different way to map Encoding Objects to data structures, so this splits the mapping definition (controlled by the Media Type Object'sencodingfield) from the logic of the Encoding Object itself. Previously the mapping details were in the Encoding Object description, despite the Encoding Object only applying to one value at a time.As dicussed in today's TDC call, we have increasing (and modern) use cases for supporting
multipart/mixed(which we previously claimed to support but never did). This refactor makes possible future support easier by moving the array special case, which is governed by themultipart/form-dataRFC, out of the Encoding Object (which needs to work with othermultipartformats) and placing it with the Media Type Object'sencodingfield (which is web form-format-specific).This PR refactors encoding guidance to put the rules for mapping Encoding Objects to valules with the
encodingfield (which performs the mapping) rather than having most of it in the Encoding Object (which should focus on how to apply a single Encoding Object to a single value).This notably takes the special handling of arrays as repeated values out of the Encoding Object section (and the default
contentTypefield value table) and moves it to the Media Type Object. The Encoding Object behavior is now consistent for all types, while the mapping done by theencodingfield handles the special case.The only change (as opposed to re-organization and re-wording) in this PR is the addition of a default
contentTypeofapplication/jsonfor array values, which in the context of the existing behavior is only relevant for array values nested under a top-level array. Past OAS versions were silent on this topic, and presumably it just does not come up much, but it was a gap we should fill.