Skip to content

Commit ed60733

Browse files
committed
Remove media type registry mentions for encoding.
This removes the more general language allowing for future expansion with the media type registry (although the general language still had the same effect of restricting to `multipart` and `application/x-www-form-urlencoded` in practice).
1 parent 35dc935 commit ed60733

File tree

1 file changed

+11
-13
lines changed

1 file changed

+11
-13
lines changed

src/oas.md

Lines changed: 11 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -84,8 +84,6 @@ Some examples of possible media type definitions:
8484
application/vnd.github.v3.patch
8585
```
8686

87-
#### Media Type Registry
88-
8987
### HTTP Status Codes
9088

9189
The HTTP Status Codes are used to indicate the status of the executed operation.
@@ -1617,33 +1615,33 @@ See [Working With Examples](#working-with-examples) for further guidance regardi
16171615
| <a name="media-type-schema"></a>schema | [Schema Object](#schema-object) | The schema defining the content of the request, response, parameter, or header. |
16181616
| <a name="media-type-example"></a>example | Any | Example of the media type; see [Working With Examples](#working-with-examples). |
16191617
| <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). |
1620-
| <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). |
1621-
1618+
| <a name="media-type-encoding"></a>encoding | Map[`string`, [Encoding Object](#encoding-object)] | A map between a property name and its encoding information, as defined under [Encoding Usage and Restrictions](#encoding-usage-and-restrictions). 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. |
16221619

16231620
This object MAY be extended with [Specification Extensions](#specification-extensions).
16241621

16251622
##### Encoding Usage and Restrictions
16261623

1624+
The `encoding` field defines how to map each [Encoding Object](#encoding-object) to a specific value in the data.
1625+
16271626
To use the `encoding` field, a `schema` MUST exist, and the `encoding` field's keys MUST exist in the schema as properties.
1628-
Array properties MUST be handled by applying the given Encoding Object to multiple parts (or query parameters) with the same `name`, as is recommended by [RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3) for supplying multiple values per form field.
1629-
For all other property types, including array values within a top-level array, the Encoding Object MUST be applied to the entire value.
1627+
Array properties MUST be handled by applying the given Encoding Object to one part 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.
1628+
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.
16301629

1631-
The behavior of the `encoding` field is designed to support web forms, and is therefore only defined for media types structured as name-value pairs that allow repeat values.
1630+
The behavior of the `encoding` field is designed to support web forms, and is therefore only defined for media types structured as name-value pairs that allow repeat values, most notably `application/x-www-form-urlencoded` and `multipart/form-data`.
16321631
The order of these name-value pairs in the target media type is implementation-defined.
16331632

16341633
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).
16351634
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.
16361635

1637-
For `multipart/*`, the encoding keys MUST map to the [`name` parameter](https://www.rfc-editor.org/rfc/rfc7578#section-4.2) of the `Content-Disposition: form-data` header of each part.
1638-
See [RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-5) for guidance regarding non-ASCII part names.
1636+
For `multipart`, the encoding keys MUST map to the [`name` parameter](https://www.rfc-editor.org/rfc/rfc7578#section-4.2) of the `Content-Disposition: form-data` header of each part, as is defined for `multipart/form-data` in [[?RFC7578]].
1637+
See [[?RFC7578]] [Section 5](https://www.rfc-editor.org/rfc/rfc7578.html#section-5) for guidance regarding non-ASCII part names.
16391638

1640-
This usage of a `name` [`Content-Disposition` parameter](https://www.iana.org/assignments/cont-disp/cont-disp.xhtml#cont-disp-2) is defined for `multipart/form-data` ([[?RFC7578]]) and the `form-data` [`Content-Disposition` value](https://www.iana.org/assignments/cont-disp/cont-disp.xhtml#cont-disp-1).
1641-
Implementations MAY choose to support the `name` `Content-Disposition` parameter and the `encoding` field with other `multipart` formats, but this usage is unlikely to be supported by generic `multipart` implementations.
1639+
Other `multipart` media types are not directly supported as they do not define a mechanism for part names.
1640+
However, the usage of a `name` [`Content-Disposition` parameter](https://www.iana.org/assignments/cont-disp/cont-disp.xhtml#cont-disp-2) is defined for the `form-data` [`Content-Disposition` value](https://www.iana.org/assignments/cont-disp/cont-disp.xhtml#cont-disp-1), which is not restricted to `multipart/form-data`.
1641+
Implementations MAY choose to support the a `Conent-Disposition` of `form-data` with a `name` parameter in other `multipart` media types in order to use the `encoding` field with them, but this usage is unlikely to be supported by generic `multipart` implementations.
16421642

16431643
See [Encoding `multipart` Media Types](#encoding-multipart-media-types) for further guidance and examples, both with and without the `encoding` field.
16441644

1645-
For all media types where no mapping is defined by either this specification or the [Media Type Registry](#media-type-registry), the `encoding` field SHALL be ignored.
1646-
16471645
##### Media Type Examples
16481646

16491647
```json

0 commit comments

Comments
 (0)