From cfc9d188c4f145759f6658a4013bc24375362252 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 28 Mar 2025 10:53:09 -0700 Subject: [PATCH 1/5] Media Types Registry This registry groups media types by their data modeling approaches, and provides pages that give a brief overview of that approach as well as links to relevant OAS sections. The section titles and anchors are intended to work with 3.2 (so we should not publish it until 3.2 is published). The summary and remarks are only intended to give the general idea of how the media types work, and what changes have been made from release to release. This initial set only includes media types that are mentioned in the OAS, but the layout should work without needing any links to such sections. We'll have to decide how much detail to put if and when we start making additions outside of the OAS, which we hope to eventually do. The point of this is to not require a minor OAS version to add future media types, as long as they do not require new fields or Objects. I omitted YAML since AFAIK it is rarely used in actual API payloads, and the OAS provides no guidance on how to handle YAML features that are not compatible with JSON. And of course for JSON-compatible YAML, you just treat it like JSON. --- _config.yml | 5 +++ _includes/media-type-entry.md | 28 ++++++++++++++ registries/_media-type/binary.md | 32 ++++++++++++++++ registries/_media-type/forms.md | 34 +++++++++++++++++ registries/_media-type/linksets.md | 24 ++++++++++++ registries/_media-type/sequential_json.md | 31 +++++++++++++++ .../_media-type/sequential_multipart.md | 38 +++++++++++++++++++ registries/_media-type/sse.md | 29 ++++++++++++++ registries/_media-type/text.md | 33 ++++++++++++++++ registries/_media-type/xml.md | 26 +++++++++++++ registry/media-type.md | 29 ++++++++++++++ 11 files changed, 309 insertions(+) create mode 100644 _includes/media-type-entry.md create mode 100644 registries/_media-type/binary.md create mode 100644 registries/_media-type/forms.md create mode 100644 registries/_media-type/linksets.md create mode 100644 registries/_media-type/sequential_json.md create mode 100644 registries/_media-type/sequential_multipart.md create mode 100644 registries/_media-type/sse.md create mode 100644 registries/_media-type/text.md create mode 100644 registries/_media-type/xml.md create mode 100644 registry/media-type.md diff --git a/_config.yml b/_config.yml index 8904b78dd3..cd06d919b6 100644 --- a/_config.yml +++ b/_config.yml @@ -18,6 +18,11 @@ collections: name: Format Registry output: true permalink: /registry/:collection/:title + media-type: + slug: media-type + name: Media Type Registry + output: true + permalink: /registry/:collection/:title extension: slug: extension name: Specification Extension Registry diff --git a/_includes/media-type-entry.md b/_includes/media-type-entry.md new file mode 100644 index 0000000000..abe45fe7d1 --- /dev/null +++ b/_includes/media-type-entry.md @@ -0,0 +1,28 @@ +# {{ page.collection }} + +## {{ page.description }} + +**Media Type(s):** + +{% for media_type in page.media_types %}• {{ media_type.name }}{% unless media_type.registered %} _(not IANA-registered)_{% endunless %}{% unless forloop.last %}
{% endunless %}{% endfor %} +{% if page.default_for %} + +This page also applies to any unknown {{ page.default_for }} media type. +{% endif %} + +{% if page.references %} +**OAS References:** + +{% for ref in page.references %}• [{{ ref.section }}](https://spec.openapis.org/oas/latest.html#{{ ref.anchor }})
{% endfor %} +{% endif %} + +## Summary + +{{ include.summary }} + +{% if include.remarks %} +## Remarks + +{{ include.remarks }} +{% endif %} + diff --git a/registries/_media-type/binary.md b/registries/_media-type/binary.md new file mode 100644 index 0000000000..eeed230708 --- /dev/null +++ b/registries/_media-type/binary.md @@ -0,0 +1,32 @@ +--- +owner: handrews +description: Binary +media_types: + - name: application/octet-stream + registered: true + - name: audio/* + registered: true + - name: image/* + registered: true + - name: video/* + registered: true +default_for: binary +references: + - section: Working with Binary Data + anchor: working-with-binary-data + - section: Binary Streams + anchor: binary-streams +layout: default +--- + +{% capture summary %} +As of OAS v3.1, binary data is modeled using an empty Schema Object, in accordance with JSON Schema's guidance regarding [non-JSON instances](https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html#name-non-json-instances). +{% endcapture %} + +{% capture remarks %} +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`. + +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. +{% endcapture %} + +{% include media-type-entry.md summary=summary remarks=remarks %} diff --git a/registries/_media-type/forms.md b/registries/_media-type/forms.md new file mode 100644 index 0000000000..17d63c7112 --- /dev/null +++ b/registries/_media-type/forms.md @@ -0,0 +1,34 @@ +--- +owner: handrews +description: Forms +media_types: + - name: application/x-www-form-urlencoded + registered: true + - name: multipart/form-data + registered: true +references: + - section: Encoding the x-www-form-urlencoded Media Type + anchor: encoding-the-x-www-form-urlencoded-media-type + - section: Encoding By Name + anchor: encoding-by-name + - section: Encoding multipart Media Types + anchor: encoding-multipart-media-types + - section: "Appendix C: Using RFC6570-Based Serialization" + anchor: appendix-c-using-rfc6570-based-serialization + - section: "Appendix E: Percent-Encoding and Form Media Types" + anchor: appendix-e-percent-encoding-and-form-media-types +layout: default +--- + +{% capture summary %} +Web-style form data consists of name-value pairs, with duplicate names allowed, and are structured either in a way compatible with URI form query strings or as a `multipart` document. +{% endcapture %} + +{% capture remarks %} +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. +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. + +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. +{% endcapture %} + +{% include media-type-entry.md summary=summary remarks=remarks %} diff --git a/registries/_media-type/linksets.md b/registries/_media-type/linksets.md new file mode 100644 index 0000000000..3b451c8143 --- /dev/null +++ b/registries/_media-type/linksets.md @@ -0,0 +1,24 @@ +--- +owner: handrews +description: Link Sets +media_types: + - name: application/linkset + registered: true + - name: application/linkset+json + registered: true +references: + - section: Modeling Link Headers + anchor: modeling-link-headers +layout: default +--- + +{% capture summary %} +The JSON form for linksets is used to define the schema-ready data form for modeling the HTTP `Link` header, with the rules for converting from that form to `application/linkset` and then to the single-line HTTP field syntax defining the serialization process for that data. +{% endcapture %} + +{% capture remarks %} +In addition to modeling the `Link` header, these two media types are supported anywhere else a media type document is allowed. +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. +{% endcapture %} + +{% include media-type-entry.md summary=summary remarks=remarks %} diff --git a/registries/_media-type/sequential_json.md b/registries/_media-type/sequential_json.md new file mode 100644 index 0000000000..c53082f1d9 --- /dev/null +++ b/registries/_media-type/sequential_json.md @@ -0,0 +1,31 @@ +--- +owner: handrews +description: Sequential JSON +media_types: + - name: application/jsonl + registered: false + - name: application/x-ndjson + registered: false + - name: application/json-seq + registered: true +references: + - section: Sequential Media Types + anchor: sequential-media-types + - section: Streaming Sequential Media Types + anchor: streaming-sequential-media-types + - section: Sequential JSON (examples) + anchor: sequential-json +layout: default +--- + +{% capture summary %} +Sequential JSON media types concatenate multiple JSON documents into one document or stream, and only vary in their choices of delimiter and the restrictions on what whitespace is allowed between JSON syntax tokens. +{% endcapture %} + +{% capture remarks %} +All sequential JSON media types support the same two approaches: +* Use the `schema` field to model the whole document as if it were a JSON array +* Use `itemSchema` to model one item at a time for streaming purposes, where all items use the same schema +{% endcapture %} + +{% include media-type-entry.md summary=summary remarks=remarks %} diff --git a/registries/_media-type/sequential_multipart.md b/registries/_media-type/sequential_multipart.md new file mode 100644 index 0000000000..846ab61ea5 --- /dev/null +++ b/registries/_media-type/sequential_multipart.md @@ -0,0 +1,38 @@ +--- +owner: handrews +description: Sequential Multipart +media_types: + - name: multipart/* + registered: true + - name: multipart/mixed + registered: true + - name: multipart/alternative + registered: true + - name: multipart/related + registered: true + - name: multipart/byteranges + registered: true +references: + - section: Encoding By Position + anchor: encoding-by-position + - section: Encoding multipart Media Types + anchor: encoding-multipart-media-types +layout: default +--- + +{% capture summary %} +All `multipart` media types are based on a common syntax defined by `multipart/mixed`, and any `multipart` subtype not explicitly registered is expected to be usable by treating it as `multipart/mixed` in accordance with [RFC2046 §5.1.3](https://www.rfc-editor.org/rfc/rfc2046.html#section-5.1.3). +{% endcapture %} + +{% capture remarks %} +All known `multipart` subtypes except `multipart/form-data` are ordered, without any names for the parts. +They are either modeled as arrays using `schema`, or a uniform schema can be applied to each part for streaming purposes using `itemSchema` (this is particularly relevant to `multipart/byteranges`). +In both cases, `itemEncoding` can used to manage the media type and headers of each, while if `schema` is used, `prefixEncoding` is also available for describing some fixed number of initial parts in a specific order. + +The `boundary` required parameter is common to all `multipart` subtypes, but does not need to be described explicitly in OpenAPI Descriptions as it is typically generated and used automatically, with a value that is not predictable in advance. + +Note that OAS v3.0 claimed support for `multipart/mixed`, but did not define a mechanism for doing so for reasons that are no longer known. This claim of support was removed in OAS v3.0.4 and OAS v3.1.1, but can be seen in older patch releases of the 3.0 and 3.1 lines. +{% endcapture %} + +{% include media-type-entry.md summary=summary remarks=remarks %} + diff --git a/registries/_media-type/sse.md b/registries/_media-type/sse.md new file mode 100644 index 0000000000..6e3377bda5 --- /dev/null +++ b/registries/_media-type/sse.md @@ -0,0 +1,29 @@ +--- +owner: handrews +description: Server-Sent Events +media_types: + - name: text/event-stream + registered: false +references: + - section: Sequential Media Types + anchor: sequential-media-types + - section: Special Considerations for `text/event-stream` Content + anchor: special-considerations-for-text-event-stream-conten + - section: Server-Sent Event Streams (example) + anchor: server-sent-event-streams +layout: default +--- + +{% capture summary %} +Server-Sent Events use the `text/event-stream` media type to stream events. +Each event is modeled as if it were a JSON object with fields and types +as given in the SSE specification, ignoring comments (fields with an empty string for the name) and any variations in serialization that represent the same event content. +{% endcapture %} + +{% capture remarks %} +A complete event stream can be modeled as if it were a JSON array of such objects in the `schema` field, but the more common use case is to use the `itemSchema` field to apply the same schema to each event as it is streamed. + +Note that application-level conventions regarding event usage (e.g. "sentinel events") that are not part of the media type specification are not modeled, as the OAS does not currently (as of OAS v3.2) work with semantics above the media type level. +{% endcapture %} + +{% include media-type-entry.md summary=summary remarks=remarks %} diff --git a/registries/_media-type/text.md b/registries/_media-type/text.md new file mode 100644 index 0000000000..9b9ea797d7 --- /dev/null +++ b/registries/_media-type/text.md @@ -0,0 +1,33 @@ +--- +owner: handrews +description: Text +media_types: + - name: text/* + registered: true + - name: text/plain + registered: true +default_for: text-based (not just text/*) +references: + - section: Parameter Object + anchor: parameter-object + - section: Header Object + anchor: header-object + - section: Encoding Object + anchor: encoding-object + - section: "Appendix D: Serializing Headers and Cookies" + anchor: appendix-d-serializing-headers-and-cookies +layout: default +--- + +{% capture summary %} +A plain text document is modeled as a single string. +{% endcapture %} + +{% capture remarks %} +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. +In particular, cookies with multiple values are not well-served by `style: form` and are better modeled as text. + +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. +{% endcapture %} + +{% include media-type-entry.md summary=summary remarks=remarks %} diff --git a/registries/_media-type/xml.md b/registries/_media-type/xml.md new file mode 100644 index 0000000000..93cbb7304f --- /dev/null +++ b/registries/_media-type/xml.md @@ -0,0 +1,26 @@ +--- +owner: handrews +description: XML +media_types: + - name: application/xml + registered: true +references: + - section: XML Object + anchor: xml-object + - section: XML Modeling + anchor: xml-modeling +layout: default +--- + +{% capture summary %} +XML is modeled using the OAS's `xml` extension keyword for JSON Schema, which has an XML Object as its value. +{% endcapture %} + +{% capture remarks %} +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. + +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`. +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. +{% endcapture %} + +{% include media-type-entry.md summary=summary remarks=remarks %} diff --git a/registry/media-type.md b/registry/media-type.md new file mode 100644 index 0000000000..6213cde436 --- /dev/null +++ b/registry/media-type.md @@ -0,0 +1,29 @@ +--- +title: Media Type Registry +layout: default +permalink: /registry/media-type/index.html +parent: Registry +--- + +# Media Type Registry + +This registry lists the non-JSON media types addressed by the OpenAPI Specification (OAS), and links to the appropriate OAS sections and external specifications. +See [Working With Data](https://spec.openapis.org/oas/latest.html#working-with-data) and [Parsing and Serializing](https://spec.openapis.org/oas/latest.html#parsing-and-serializing) for a discussion of serialized, schema-ready, and application forms of data, and how to convert among the forms. + +## Specification Versions + +This registry is for and [linked from](https://spec.openapis.org/oas/latest.html#media-types) version 3.2 and later of the OAS. Earlier versions and other specifications such as Arazzo MAY support approaches added in this registry, as long as the necessary Objects and fields are available in those versions. + +## Contributing + +Please open a [discussion](https://github.com/OAI/OpenAPI-Specification/discussions) explaining your _**use cases**_ for any media type(s) you would like to see added. + +## Media Types + +**Note:** Media types with a structured suffix are handled the same way as the media type corresponding to the suffix (e.g. all `+json` media types are handled as `application/json`). + +|Group|Media Types| +|---|---| +{% for value in site.media-type %}| {{ value.description }} | {% for mt in value.media_types %}{{ mt.name }}{% unless forloop.last %}
{% endunless%}{% endfor %}{% if value.default_for %}
any unknown {{ value.default_for }} media type{% endif %}| +{% endfor %} + From bda90e1a2e917e442799dd4254663657173e2255 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 23 Jul 2025 08:21:05 -0700 Subject: [PATCH 2/5] Update registries/_media-type/sequential_multipart.md Co-authored-by: Phil Sturgeon <67381+philsturgeon@users.noreply.github.com> --- registries/_media-type/sequential_multipart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/registries/_media-type/sequential_multipart.md b/registries/_media-type/sequential_multipart.md index 846ab61ea5..9e5838d9d3 100644 --- a/registries/_media-type/sequential_multipart.md +++ b/registries/_media-type/sequential_multipart.md @@ -31,7 +31,7 @@ In both cases, `itemEncoding` can used to manage the media type and headers of e The `boundary` required parameter is common to all `multipart` subtypes, but does not need to be described explicitly in OpenAPI Descriptions as it is typically generated and used automatically, with a value that is not predictable in advance. -Note that OAS v3.0 claimed support for `multipart/mixed`, but did not define a mechanism for doing so for reasons that are no longer known. This claim of support was removed in OAS v3.0.4 and OAS v3.1.1, but can be seen in older patch releases of the 3.0 and 3.1 lines. +Note that OAS v3.0 claimed support for `multipart/mixed`, but behaviour was undefined. The claim of support was removed in OAS v3.0.4 and OAS v3.1.1, but can be seen in older patch releases of the 3.0 and 3.1 lines. {% endcapture %} {% include media-type-entry.md summary=summary remarks=remarks %} From 2ce5114569dfa49f372cf65ef010f28dc50d5f0a Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Wed, 23 Jul 2025 11:01:03 -0700 Subject: [PATCH 3/5] 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. --- _includes/media-type-entry.md | 10 ++--- registries/_media-type/binary.md | 41 +++++++++++++++--- registries/_media-type/forms.md | 35 ++++++++++++---- registries/_media-type/linksets.md | 19 +++++++-- registries/_media-type/sequential_json.md | 26 ++++++++++-- .../_media-type/sequential_multipart.md | 42 +++++++++++++++---- registries/_media-type/sse.md | 18 ++++++-- registries/_media-type/text.md | 19 +++++++-- registries/_media-type/xml.md | 20 +++++++-- registry/media-type.md | 6 +-- 10 files changed, 190 insertions(+), 46 deletions(-) diff --git a/_includes/media-type-entry.md b/_includes/media-type-entry.md index abe45fe7d1..e4f7aad062 100644 --- a/_includes/media-type-entry.md +++ b/_includes/media-type-entry.md @@ -1,19 +1,19 @@ -# {{ page.collection }} +# Media Type Registry -## {{ page.description }} +## {{ page.name }}: {{ page.description }} **Media Type(s):** -{% for media_type in page.media_types %}• {{ media_type.name }}{% unless media_type.registered %} _(not IANA-registered)_{% endunless %}{% unless forloop.last %}
{% endunless %}{% endfor %} +{% for media_type in page.media_types %}• {{ media_type.name }} ({% if media_type.iana %}[IANA]({{ media_type.iana }}){% else %}not IANA-registered{% endif %}) – {% for spec in media_type.specifications %}[{{ spec.name }}]({{ spec.url }}){% if spec.note %} ({{ spec.note }}){% endif %}{% unless forloop.last %}, {% endunless %}{% endfor %}{% unless forloop.last %}
{% endunless %}{% endfor %} {% if page.default_for %} -This page also applies to any unknown {{ page.default_for }} media type. +This page also applies to any unrecognized {{ page.default_for }} media type. {% endif %} {% if page.references %} **OAS References:** -{% for ref in page.references %}• [{{ ref.section }}](https://spec.openapis.org/oas/latest.html#{{ ref.anchor }})
{% endfor %} +{% for ref in page.references %}• [{{ ref.section }}](https://spec.openapis.org/oas/latest.html#{{ ref.anchor }}){% if ref.parent %} ([{{ ref.parent }}](https://spec.openapis.org/oas/latest.html#{{ ref.parentAnchor }})){% endif %}{% unless forloop.last %}
{% endunless %}{% endfor %} {% endif %} ## Summary diff --git a/registries/_media-type/binary.md b/registries/_media-type/binary.md index eeed230708..ebbcc20ef8 100644 --- a/registries/_media-type/binary.md +++ b/registries/_media-type/binary.md @@ -1,21 +1,50 @@ --- owner: handrews -description: Binary +name: Binary +description: Non-text-based media types media_types: - name: application/octet-stream - registered: true + iana: https://www.iana.org/assignments/media-types/application/octet-stream + specifications: + - name: RFC2045 + url: https://www.rfc-editor.org/rfc/rfc2045 + - name: RFC2046 §4.5.1 + url: https://www.rfc-editor.org/rfc/rfc2046#section-4.5.1 - name: audio/* - registered: true + iana: https://www.iana.org/assignments/media-types/media-types.xhtml#audio + specifications: + - name: RFC2045 + url: https://www.rfc-editor.org/rfc/rfc2045 + - name: RFC2046 §4.2 + url: https://www.rfc-editor.org/rfc/rfc2046#section-4.3 - name: image/* - registered: true + iana: https://www.iana.org/assignments/media-types/media-types.xhtml#image + specifications: + - name: RFC2045 + url: https://www.rfc-editor.org/rfc/rfc2045 + - name: RFC2046 §4.2 + url: https://www.rfc-editor.org/rfc/rfc2046#section-4.2 - name: video/* - registered: true + iana: https://www.iana.org/assignments/media-types/media-types.xhtml#video + specifications: + - name: RFC2045 + url: https://www.rfc-editor.org/rfc/rfc2045 + - name: RFC2046 §4.4 + url: https://www.rfc-editor.org/rfc/rfc2046#section-4.4 default_for: binary references: - section: Working with Binary Data anchor: working-with-binary-data + parent: Working with Data + parentAnchor: Working with Data - section: Binary Streams anchor: binary-streams + parent: Media Type Object + parentAnchor: media-type-object + - section: "`Content-Transfer-Encoding` and `contentEncoding`" + anchor: content-transfer-encoding-and-contentencoding + parent: Encoding Object + parentAnchor: encoding-object layout: default --- @@ -24,7 +53,7 @@ As of OAS v3.1, binary data is modeled using an empty Schema Object, in accordan {% endcapture %} {% capture remarks %} -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`. +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. 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. {% endcapture %} diff --git a/registries/_media-type/forms.md b/registries/_media-type/forms.md index 17d63c7112..874c4fe28d 100644 --- a/registries/_media-type/forms.md +++ b/registries/_media-type/forms.md @@ -1,18 +1,37 @@ --- owner: handrews -description: Forms +name: Forms +description: Ordered name-value pairs media_types: - name: application/x-www-form-urlencoded - registered: true + iana: https://www.iana.org/assignments/media-types/application/x-www-form-urlencoded + specifications: + - name: WHATWG URL + url: https://url.spec.whatwg.org/#application/x-www-form-urlencoded + - name: HTTP 4.01 §17.13.4.1 + url: https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1 + note: historical + - name: RFC1866 §8.2.1 + url: https://datatracker.ietf.org/doc/html/rfc1866#section-8.2.1 + note: historical but cited by later RFCs and the OAS - name: multipart/form-data - registered: true + iana: https://www.iana.org/assignments/media-types/multipart/form-data + specifications: + - name: RFC7578 + url: https://www.rfc-editor.org/rfc/rfc7578.html references: - - section: Encoding the x-www-form-urlencoded Media Type - anchor: encoding-the-x-www-form-urlencoded-media-type - section: Encoding By Name anchor: encoding-by-name + parent: Encoding Usage and Restrictions + parentAnchor: encoding-usage-and-restrictions + - section: Encoding the `x-www-form-urlencoded` Media Type + anchor: encoding-the-x-www-form-urlencoded-media-type + parent: Encoding Object + parentAnchor: encoding-object - section: Encoding multipart Media Types anchor: encoding-multipart-media-types + parent: Encoding Object + parentAnchor: encoding-object - section: "Appendix C: Using RFC6570-Based Serialization" anchor: appendix-c-using-rfc6570-based-serialization - 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, {% endcapture %} {% capture remarks %} -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. +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. 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. -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. +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. + +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). {% endcapture %} {% include media-type-entry.md summary=summary remarks=remarks %} diff --git a/registries/_media-type/linksets.md b/registries/_media-type/linksets.md index 3b451c8143..6be31189e7 100644 --- a/registries/_media-type/linksets.md +++ b/registries/_media-type/linksets.md @@ -1,14 +1,25 @@ --- owner: handrews -description: Link Sets +name: Link Sets +description: Sets of RFC8288 Web Links media_types: - name: application/linkset - registered: true + iana: https://www.iana.org/assignments/media-types/application/linkset + specifications: + - name: RFC9264 + url: https://www.rfc-editor.org/rfc/rfc9264 + - name: RFC8288 + url: https://www.rfc-editor.org/rfc/rfc8288 - name: application/linkset+json - registered: true + iana: https://www.iana.org/assignments/media-types/application/linkset+json + specifications: + - name: RFC9264 + url: https://www.rfc-editor.org/rfc/rfc9264 references: - section: Modeling Link Headers anchor: modeling-link-headers + parent: Header Object + parentAnchor: header-object layout: default --- @@ -18,7 +29,7 @@ The JSON form for linksets is used to define the schema-ready data form for mode {% capture remarks %} In addition to modeling the `Link` header, these two media types are supported anywhere else a media type document is allowed. -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. +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. {% endcapture %} {% include media-type-entry.md summary=summary remarks=remarks %} diff --git a/registries/_media-type/sequential_json.md b/registries/_media-type/sequential_json.md index c53082f1d9..a3c0961642 100644 --- a/registries/_media-type/sequential_json.md +++ b/registries/_media-type/sequential_json.md @@ -1,20 +1,38 @@ --- owner: handrews -description: Sequential JSON +name: Sequential JSON +description: Multiple concatenated JSON documents suitable for streaming media_types: - name: application/jsonl registered: false + specifications: + - name: JSON Lines + url: https://jsonlines.org/ + - name: application/json-seq + registered: https://www.iana.org/assignments/media-types/application/json-seq + specifications: + - name: RFC7464 + url: https://www.rfc-editor.org/rfc/rfc7464 + - name: RFC8091 + url: https://www.rfc-editor.org/rfc/rfc8091 - name: application/x-ndjson registered: false - - name: application/json-seq - registered: true + specifications: + - name: Newline Delimited JSON + url: https://github.com/ndjson/ndjson-spec references: - section: Sequential Media Types anchor: sequential-media-types + parent: Media Types + parentAnchor: media-types - section: Streaming Sequential Media Types anchor: streaming-sequential-media-types - - section: Sequential JSON (examples) + parent: Media Type Object + parentAnchor: media-type-object + - section: Sequential JSON anchor: sequential-json + parent: Media Type Examples + parentAnchor: media-type-examples layout: default --- diff --git a/registries/_media-type/sequential_multipart.md b/registries/_media-type/sequential_multipart.md index 9e5838d9d3..f49ab1c7f7 100644 --- a/registries/_media-type/sequential_multipart.md +++ b/registries/_media-type/sequential_multipart.md @@ -1,22 +1,50 @@ --- owner: handrews -description: Sequential Multipart +name: Sequential Multipart +description: Multipart subtypes with unnamed parts media_types: - name: multipart/* - registered: true + iana: https://www.iana.org/assignments/media-types/media-types.xhtml#multipart + specifications: + - name: RFC2045 + url: https://www.rfc-editor.org/rfc/rfc2045 + - name: RFC2046 §5.1 + url: https://www.rfc-editor.org/rfc/rfc2046#section-5.1 - name: multipart/mixed - registered: true + iana: https://www.iana.org/assignments/media-types/multipart/mixed + specifications: + - name: RFC2045 + url: https://www.rfc-editor.org/rfc/rfc2045 + - name: RFC2046 §5.1.3 + url: https://www.rfc-editor.org/rfc/rfc2046#section-5.1.3 - name: multipart/alternative - registered: true + iana: https://www.iana.org/assignments/media-types/multipart/alternative + specifications: + - name: RFC2045 + url: https://www.rfc-editor.org/rfc/rfc2045 + - name: RFC2046 §5.1.4 + url: https://www.rfc-editor.org/rfc/rfc2046#section-5.1.4 - name: multipart/related - registered: true + iana: https://www.iana.org/assignments/media-types/multipart/related + specifications: + - name: RFC2389 + url: https://www.rfc-editor.org/rfc/rfc2389 + - name: RFC2557 + url: https://www.rfc-editor.org/rfc/rfc2557 - name: multipart/byteranges - registered: true + iana: https://www.iana.org/assignments/media-types/multipart/byteranges + specifications: + - name: RFC9110 §14.6 + url: https://www.rfc-editor.org/rfc/rfc9110#name-media-type-multipart-bytera references: - section: Encoding By Position anchor: encoding-by-position - - section: Encoding multipart Media Types + parent: Encoding Usage and Restrictions + parentAnchor: encoding-usage-and-restrictions + - section: Encoding `multipart` Media Types anchor: encoding-multipart-media-types + parent: Encoding Object + parentAnchor: encoding-object layout: default --- diff --git a/registries/_media-type/sse.md b/registries/_media-type/sse.md index 6e3377bda5..9b19d62fac 100644 --- a/registries/_media-type/sse.md +++ b/registries/_media-type/sse.md @@ -1,16 +1,28 @@ --- owner: handrews -description: Server-Sent Events +name: Server-Sent Events +description: Event streams for SSE media_types: - name: text/event-stream - registered: false + iana: false + specifications: + - name: WHATWG HTML §Server-Sent Events + url: https://html.spec.whatwg.org/multipage/server-sent-events.html#parsing-an-event-stream + - name: WHATWG HTML §IANA + url: https://html.spec.whatwg.org/multipage/iana.html#text/event-stream references: - section: Sequential Media Types anchor: sequential-media-types + parent: Media Types + parentAnchor: media-types - section: Special Considerations for `text/event-stream` Content anchor: special-considerations-for-text-event-stream-conten - - section: Server-Sent Event Streams (example) + parent: Media Type Object + parentAnchor: media-type-object + - section: Server-Sent Event Stream anchor: server-sent-event-streams + parent: Media Type Examples + parentAnchor: media-type-examples layout: default --- diff --git a/registries/_media-type/text.md b/registries/_media-type/text.md index 9b9ea797d7..082bc07f9e 100644 --- a/registries/_media-type/text.md +++ b/registries/_media-type/text.md @@ -1,11 +1,22 @@ --- owner: handrews -description: Text +name: Text +description: Text-based media types media_types: - name: text/* - registered: true + iana: https://www.iana.org/assignments/media-types/media-types.xhtml#text + specifications: + - name: RFC2045 + url: https://www.rfc-editor.org/rfc/rfc2045 + - name: RFC2046 §4.1 + url: https://www.rfc-editor.org/rfc/rfc2046#section-4.1 - name: text/plain - registered: true + iana: https://www.iana.org/assignments/media-types/text/plain + specifications: + - name: RFC2046 §4.1.3 + url: https://www.rfc-editor.org/rfc/rfc2046#section-4.1.3 + - name: RFC3676 + url: https://www.rfc-editor.org/rfc/rfc3676 default_for: text-based (not just text/*) references: - section: Parameter Object @@ -27,7 +38,7 @@ A plain text document is modeled as a single string. 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. In particular, cookies with multiple values are not well-served by `style: form` and are better modeled as text. -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. +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. {% endcapture %} {% include media-type-entry.md summary=summary remarks=remarks %} diff --git a/registries/_media-type/xml.md b/registries/_media-type/xml.md index 93cbb7304f..6a2b0f240a 100644 --- a/registries/_media-type/xml.md +++ b/registries/_media-type/xml.md @@ -1,14 +1,28 @@ --- owner: handrews -description: XML +name: XML +description: Extensible markup language media_types: - name: application/xml - registered: true + iana: https://www.iana.org/assignments/media-types/application/xml + specifications: + - name: RFC7303 + url: https://www.rfc-editor.org/rfc/rfc7303 + - name: XML 1.0 + url: https://www.w3.org/TR/xml/ + note: commonly used + - name: XML 1.1 + url: https://www.w3.org/TR/xml11/ + note: rarely used + - name: WHATWG DOM + url: https://dom.spec.whatwg.org/ references: - section: XML Object anchor: xml-object - section: XML Modeling anchor: xml-modeling + parent: Schema Object + parentAnchor: schema-object layout: default --- @@ -17,7 +31,7 @@ XML is modeled using the OAS's `xml` extension keyword for JSON Schema, which ha {% endcapture %} {% capture remarks %} -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. +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. 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`. 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. diff --git a/registry/media-type.md b/registry/media-type.md index 6213cde436..f18817edc9 100644 --- a/registry/media-type.md +++ b/registry/media-type.md @@ -22,8 +22,8 @@ Please open a [discussion](https://github.com/OAI/OpenAPI-Specification/discussi **Note:** Media types with a structured suffix are handled the same way as the media type corresponding to the suffix (e.g. all `+json` media types are handled as `application/json`). -|Group|Media Types| -|---|---| -{% for value in site.media-type %}| {{ value.description }} | {% for mt in value.media_types %}{{ mt.name }}{% unless forloop.last %}
{% endunless%}{% endfor %}{% if value.default_for %}
any unknown {{ value.default_for }} media type{% endif %}| +|Group|Description|Media Types| +|---|---|---| +{% for value in site.media-type %}| {{ value.name }} | {{ value.description }} | {% for mt in value.media_types %}{{ mt.name }}{% unless forloop.last %}
{% endunless%}{% endfor %}{% if value.default_for %}
any unrecognized {{ value.default_for }} media type{% endif %}| {% endfor %} From 36fea1afef946f80ed3a69d14e32048c79e54ecd Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Wed, 23 Jul 2025 13:22:24 -0700 Subject: [PATCH 4/5] More review fixes. --- registries/_media-type/binary.md | 2 +- registries/_media-type/linksets.md | 5 ++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/registries/_media-type/binary.md b/registries/_media-type/binary.md index ebbcc20ef8..1bb7ddce96 100644 --- a/registries/_media-type/binary.md +++ b/registries/_media-type/binary.md @@ -53,7 +53,7 @@ As of OAS v3.1, binary data is modeled using an empty Schema Object, in accordan {% endcapture %} {% capture remarks %} -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. +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. 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. {% endcapture %} diff --git a/registries/_media-type/linksets.md b/registries/_media-type/linksets.md index 6be31189e7..414f978822 100644 --- a/registries/_media-type/linksets.md +++ b/registries/_media-type/linksets.md @@ -24,12 +24,11 @@ layout: default --- {% capture summary %} -The JSON form for linksets is used to define the schema-ready data form for modeling the HTTP `Link` header, with the rules for converting from that form to `application/linkset` and then to the single-line HTTP field syntax defining the serialization process for that data. +The JSON form for linksets is used to define the schema-ready data form for both of these media types, with `application/linkset` being usable for HTTP `Link` header values using the conversion defined in the RFC. {% endcapture %} {% capture remarks %} -In addition to modeling the `Link` header, these two media types are supported anywhere else a media type document is allowed. -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. +The `application/linkset+json` data model is used with the [Schema Object](https://spec.openapis.org/oas/latest.html#schema-object) for both media types, 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 format. {% endcapture %} {% include media-type-entry.md summary=summary remarks=remarks %} From bae48fdfb27198cb4a09df1f9fec7d4c1413c424 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 8 Sep 2025 11:36:47 -0700 Subject: [PATCH 5/5] Update Media Type Regisry for reorg, review feedback This updates for various moved and re-titled sections to which we were linking. It also replaces the immediate-parent link with a link to the Object section in which the subsection appears, since after the section reorg almost everything is under an Object. This is more robust to minor changes in subsection organization, but also helps users find the relevant part of the OAS. --- _includes/media-type-entry.md | 6 ++++-- registries/_media-type/binary.md | 8 ++++---- registries/_media-type/linksets.md | 2 +- registries/_media-type/sequential_json.md | 16 ++++++++-------- registries/_media-type/sequential_multipart.md | 6 +++--- registries/_media-type/sse.md | 16 ++++++++-------- registries/_media-type/text.md | 7 +------ registries/_media-type/xml.md | 2 +- registry/media-type.md | 2 +- 9 files changed, 31 insertions(+), 34 deletions(-) diff --git a/_includes/media-type-entry.md b/_includes/media-type-entry.md index e4f7aad062..203ed418b0 100644 --- a/_includes/media-type-entry.md +++ b/_includes/media-type-entry.md @@ -1,4 +1,6 @@ -# Media Type Registry +{% assign registry = site.collections | where:"label", page.collection | first %} +# {{ registry.name }} + ## {{ page.name }}: {{ page.description }} @@ -13,7 +15,7 @@ This page also applies to any unrecognized {{ page.default_for }} media type. {% if page.references %} **OAS References:** -{% for ref in page.references %}• [{{ ref.section }}](https://spec.openapis.org/oas/latest.html#{{ ref.anchor }}){% if ref.parent %} ([{{ ref.parent }}](https://spec.openapis.org/oas/latest.html#{{ ref.parentAnchor }})){% endif %}{% unless forloop.last %}
{% endunless %}{% endfor %} +{% for ref in page.references %}• [{{ ref.section }}](https://spec.openapis.org/oas/latest.html#{{ ref.anchor }}){% if ref.parentObject %} ([{{ ref.parentObject }}](https://spec.openapis.org/oas/latest.html#{{ ref.parentAnchor }})){% endif %}{% unless forloop.last %}
{% endunless %}{% endfor %} {% endif %} ## Summary diff --git a/registries/_media-type/binary.md b/registries/_media-type/binary.md index 1bb7ddce96..14dbd91c77 100644 --- a/registries/_media-type/binary.md +++ b/registries/_media-type/binary.md @@ -35,15 +35,15 @@ default_for: binary references: - section: Working with Binary Data anchor: working-with-binary-data - parent: Working with Data - parentAnchor: Working with Data + parentObject: Schema Object + parentAnchor: schema-object - section: Binary Streams anchor: binary-streams - parent: Media Type Object + parentObject: Media Type Object parentAnchor: media-type-object - section: "`Content-Transfer-Encoding` and `contentEncoding`" anchor: content-transfer-encoding-and-contentencoding - parent: Encoding Object + parentObject: Encoding Object parentAnchor: encoding-object layout: default --- diff --git a/registries/_media-type/linksets.md b/registries/_media-type/linksets.md index 414f978822..5f5bf14322 100644 --- a/registries/_media-type/linksets.md +++ b/registries/_media-type/linksets.md @@ -18,7 +18,7 @@ media_types: references: - section: Modeling Link Headers anchor: modeling-link-headers - parent: Header Object + parentObject: Header Object parentAnchor: header-object layout: default --- diff --git a/registries/_media-type/sequential_json.md b/registries/_media-type/sequential_json.md index a3c0961642..5aa755b4e3 100644 --- a/registries/_media-type/sequential_json.md +++ b/registries/_media-type/sequential_json.md @@ -4,35 +4,35 @@ name: Sequential JSON description: Multiple concatenated JSON documents suitable for streaming media_types: - name: application/jsonl - registered: false + iana: false specifications: - name: JSON Lines url: https://jsonlines.org/ - name: application/json-seq - registered: https://www.iana.org/assignments/media-types/application/json-seq + iana: https://www.iana.org/assignments/media-types/application/json-seq specifications: - name: RFC7464 url: https://www.rfc-editor.org/rfc/rfc7464 - name: RFC8091 url: https://www.rfc-editor.org/rfc/rfc8091 - name: application/x-ndjson - registered: false + iana: false specifications: - name: Newline Delimited JSON url: https://github.com/ndjson/ndjson-spec references: - section: Sequential Media Types anchor: sequential-media-types - parent: Media Types - parentAnchor: media-types + parentObject: Media Type Object + parentAnchor: media-type-object - section: Streaming Sequential Media Types anchor: streaming-sequential-media-types - parent: Media Type Object + parentObject: Media Type Object parentAnchor: media-type-object - section: Sequential JSON anchor: sequential-json - parent: Media Type Examples - parentAnchor: media-type-examples + parentObject: Media Type Object + parentAnchor: media-type-object layout: default --- diff --git a/registries/_media-type/sequential_multipart.md b/registries/_media-type/sequential_multipart.md index f49ab1c7f7..2ea39505bd 100644 --- a/registries/_media-type/sequential_multipart.md +++ b/registries/_media-type/sequential_multipart.md @@ -39,11 +39,11 @@ media_types: references: - section: Encoding By Position anchor: encoding-by-position - parent: Encoding Usage and Restrictions - parentAnchor: encoding-usage-and-restrictions + parentObject: Media Type Object + parentAnchor: media-type-object - section: Encoding `multipart` Media Types anchor: encoding-multipart-media-types - parent: Encoding Object + parentObject: Encoding Object parentAnchor: encoding-object layout: default --- diff --git a/registries/_media-type/sse.md b/registries/_media-type/sse.md index 9b19d62fac..d511390980 100644 --- a/registries/_media-type/sse.md +++ b/registries/_media-type/sse.md @@ -13,16 +13,16 @@ media_types: references: - section: Sequential Media Types anchor: sequential-media-types - parent: Media Types - parentAnchor: media-types - - section: Special Considerations for `text/event-stream` Content - anchor: special-considerations-for-text-event-stream-conten - parent: Media Type Object + parentObject: Media Type Object parentAnchor: media-type-object - - section: Server-Sent Event Stream + - section: Special Considerations for Server-Sent Events + anchor: special-considerations-for-server-sent-events + parentObject: Media Type Object + parentAnchor: media-type-object + - section: Server-Sent Event Stream (Examples) anchor: server-sent-event-streams - parent: Media Type Examples - parentAnchor: media-type-examples + parentObject: Media Type Object + parentAnchor: media-type-object layout: default --- diff --git a/registries/_media-type/text.md b/registries/_media-type/text.md index 082bc07f9e..6dc9a3f827 100644 --- a/registries/_media-type/text.md +++ b/registries/_media-type/text.md @@ -25,8 +25,6 @@ references: anchor: header-object - section: Encoding Object anchor: encoding-object - - section: "Appendix D: Serializing Headers and Cookies" - anchor: appendix-d-serializing-headers-and-cookies layout: default --- @@ -35,10 +33,7 @@ A plain text document is modeled as a single string. {% endcapture %} {% capture remarks %} -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. -In particular, cookies with multiple values are not well-served by `style: form` and are better modeled as text. - -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. +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. {% endcapture %} {% include media-type-entry.md summary=summary remarks=remarks %} diff --git a/registries/_media-type/xml.md b/registries/_media-type/xml.md index 6a2b0f240a..b04c5396d8 100644 --- a/registries/_media-type/xml.md +++ b/registries/_media-type/xml.md @@ -21,7 +21,7 @@ references: anchor: xml-object - section: XML Modeling anchor: xml-modeling - parent: Schema Object + parentObject: Schema Object parentAnchor: schema-object layout: default --- diff --git a/registry/media-type.md b/registry/media-type.md index f18817edc9..948bd374a8 100644 --- a/registry/media-type.md +++ b/registry/media-type.md @@ -8,7 +8,7 @@ parent: Registry # Media Type Registry This registry lists the non-JSON media types addressed by the OpenAPI Specification (OAS), and links to the appropriate OAS sections and external specifications. -See [Working With Data](https://spec.openapis.org/oas/latest.html#working-with-data) and [Parsing and Serializing](https://spec.openapis.org/oas/latest.html#parsing-and-serializing) for a discussion of serialized, schema-ready, and application forms of data, and how to convert among the forms. +See [Parsing and Serializing](https://spec.openapis.org/oas/latest.html#parsing-and-serializing) for a discussion of serialized, schema-ready, and application forms of data, and how to convert among the forms. ## Specification Versions