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.

Author: handrews

_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

_includes/media-type-entry.md

@@ -0,0 +1,28 @@
+# <a href=".">{{ page.collection }}</a>
+
+## {{ page.description }}
+
+**Media Type(s):**
+
+{% for media_type in page.media_types %}• <tt>{{ media_type.name }}</tt>{% unless media_type.registered %} _<small>(not IANA-registered)</small>_{% endunless %}{% unless forloop.last %}<br />{% 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 }})<br />{% endfor %}
+{% endif %}
+
+## Summary
+
+{{ include.summary }}
+
+{% if include.remarks %}
+## Remarks
+
+{{ include.remarks }}
+{% endif %}
+

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 %}

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 %}

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 %}

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 %}

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 %}
+

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 %}

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 <tt>text/*</tt>)
+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 %}

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 %}