You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
More info and better formatting in media type registry
Add specification links, add parent sections, link to Objects,
use a name and description, use the name of the registry, add
some notes to specifications where appropriate.
@@ -24,7 +53,7 @@ As of OAS v3.1, binary data is modeled using an empty Schema Object, in accordan
24
53
{% endcapture %}
25
54
26
55
{% capture remarks %}
27
-
As specified in the linked reference section ("Working with Binary Data"), modeling binary data that has been encoded into a string is handled differently from raw binary data, with two variations: With an Encoding Object or with the Schema Object's `contentMediaType` and `contentEncoding`.
56
+
As specified in [Working with Binary Data](https://spec.openapis.org/oas/latest.html#working-with-binary-data), modeling binary data that has been encoded into a string is handled differently from raw binary data, with two variations: With the [Schema Object](https://spec.openapis.org/oas/latest.html#schema-object)'s `contentMediaType` and `contentEncoding`, or with a `Content-Transfer-Encoding` header in the [Encoding Object](https://spec.openapis.org/oas/latest.html#encoding-object) (for media types that use Encoding Objects). Consult the specification for how these two mechanisms interact when they both apply.
28
57
29
58
In OAS v3.0, raw binary content was modeled as `type: string, format: binary`, while `type: string, format: byte` was used for base64-encoded binary. This was dropped in favor of JSON Schema draft 2020-12's support because it did not allow specifying the media type along with the binary encoding.
- section: "Appendix E: Percent-Encoding and Form Media Types"
@@ -25,10 +44,12 @@ Web-style form data consists of name-value pairs, with duplicate names allowed,
25
44
{% endcapture %}
26
45
27
46
{% capture remarks %}
28
-
Both form media types use the Encoding Object to map object properties from schema-ready data structures to name-value pairs, with special rules for arrays causing each array value to be treated as a separate pair with the same name.
47
+
Both form media types use the [Encoding Object](https://spec.openapis.org/oas/latest.html#encoding-object) to map object properties from schema-ready data structures to name-value pairs, with special rules for arrays causing each array value to be treated as a separate pair with the same name.
29
48
While the ordering of pairs is significant in these formats, the OAS does not (as of v3.2) provide a way to control such ordering.
30
49
31
-
As of OAS v3.2, endpoint URL query strings can be modeled as a media type using `in: querystring` in the Parameter Object. The query string can also be modeled using multiple `in: query` Parameter Objects through mechanisms similar to the Encoding Object.
50
+
As of OAS v3.2, endpoint URL query strings can be modeled as a media type using `in: querystring` in the [Parameter Object](https://spec.openapis.org/oas/latest.html#parameter-object). The query string can also be modeled using multiple `in: query` Parameter Objects through mechanisms similar to the Encoding Object.
51
+
52
+
Note that URL-encoded forms have been defined by different standards organizations at different times, leading to inconsistencies regarding percent-encoding in later standards and implementations; this is addressed in detail in [Appendix E](https://spec.openapis.org/oas/latest.html#appendix-e-percent-encoding-and-form-media-types).
32
53
{% endcapture %}
33
54
34
55
{% include media-type-entry.md summary=summary remarks=remarks %}
@@ -18,7 +29,7 @@ The JSON form for linksets is used to define the schema-ready data form for mode
18
29
19
30
{% capture remarks %}
20
31
In addition to modeling the `Link` header, these two media types are supported anywhere else a media type document is allowed.
21
-
In all cases, the `application/linkset+json` data model is used with the Schema Object, with the choice of the parent key for the Media Type Object (with or without `+json`) determining only the serialization.
32
+
In all cases, the `application/linkset+json` data model is used with the [Schema Object](https://spec.openapis.org/oas/latest.html#schema-object), with the choice of the parent key for the [Media Type Object](https://spec.openapis.org/oas/latest.html#media-type-object) (with or without `+json`) determining only the serialization.
22
33
{% endcapture %}
23
34
24
35
{% include media-type-entry.md summary=summary remarks=remarks %}
default_for: text-based (not just <tt>text/*</tt>)
10
21
references:
11
22
- section: Parameter Object
@@ -27,7 +38,7 @@ A plain text document is modeled as a single string.
27
38
In addition to normal use as HTTP message contents or `multipart` parts, `text/plain` is useful with the `content` field of the Parameter Object or Header Object to work around the automatic percent-encoding triggered by the use of the `schema` field.
28
39
In particular, cookies with multiple values are not well-served by `style: form` and are better modeled as text.
29
40
30
-
Note that unlike JSON strings, the contents of the string representing the plain text are not quoted when serializing to a document. While a Schema Object of `{type: string, const: foo}` for JSON validates the JSON value `"foo"`, for plain text it validates `foo`, without quotes.
41
+
Note also that unlike JSON strings, the contents of the string representing the plain text are not quoted when serializing to a document. While a Schema Object of `{type: string, const: foo}` for JSON validates the JSON value `"foo"`, for plain text it validates `foo`, without quotes.
31
42
{% endcapture %}
32
43
33
44
{% include media-type-entry.md summary=summary remarks=remarks %}
@@ -17,7 +31,7 @@ XML is modeled using the OAS's `xml` extension keyword for JSON Schema, which ha
17
31
{% endcapture %}
18
32
19
33
{% capture remarks %}
20
-
As of OAS v3.2, the XML Object uses the `nodeType` field to determine the type of [interface node](https://dom.spec.whatwg.org/#interface-node) to which a given Schema Object corresponds: `element`, `attribute`, `text`, `cdata`, or `none`. If `nodeType` is set to `none`, a Schema Object does not correspond to anything and the nodes corresponding to its immediate subschemas are placed directly under the node of its parent schema.
34
+
As of OAS v3.2, the [XML Object](https://spec.openapis.org/oas/latest.html#xml-object) uses the `nodeType` field to determine the type of [interface node](https://dom.spec.whatwg.org/#interface-node) to which a given Schema Object corresponds: `element`, `attribute`, `text`, `cdata`, or `none`. If `nodeType` is set to `none`, a Schema Object does not correspond to anything and the nodes corresponding to its immediate subschemas are placed directly under the node of its parent schema.
21
35
22
36
Certain behaviors are retained for compatibility with OAS v3.1, including implicit text nodes for elements with a primitive type, and somewhat complex rules for the default value of `nodeType`.
23
37
In OAS v3.1 and earlier, only elements, their implicit primitive-type text nodes, and attributes were supported, with the now-deprecated `attribute` and `wrapped` flags as controls.
0 commit comments