Skip to content

Commit c582104

Browse files
lornajanelornajane
authored
Merge pull request #4808 from handrews/media-type-reg
2 parents d6d9cb4 + bae48fd commit c582104

File tree

11 files changed

+449
-0
lines changed

11 files changed

+449
-0
lines changed

‎_config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,11 @@ collections:
1818
name: Format Registry
1919
output: true
2020
permalink: /registry/:collection/:title
21+
media-type:
22+
slug: media-type
23+
name: Media Type Registry
24+
output: true
25+
permalink: /registry/:collection/:title
2126
extension:
2227
slug: extension
2328
name: Specification Extension Registry

‎_includes/media-type-entry.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{% assign registry = site.collections | where:"label", page.collection | first %}
2+
# <a href=".">{{ registry.name }}</a>
3+
4+
5+
## {{ page.name }}: {{ page.description }}
6+
7+
**Media Type(s):**
8+
9+
{% for media_type in page.media_types %}• <tt>{{ media_type.name }}</tt> <small>({% if media_type.iana %}[IANA]({{ media_type.iana }}){% else %}not IANA-registered{% endif %})</small> – {% for spec in media_type.specifications %}[{{ spec.name }}]({{ spec.url }}){% if spec.note %} <small>({{ spec.note }})</small>{% endif %}{% unless forloop.last %}, {% endunless %}{% endfor %}{% unless forloop.last %}<br />{% endunless %}{% endfor %}
10+
{% if page.default_for %}
11+
12+
This page also applies to any unrecognized {{ page.default_for }} media type.
13+
{% endif %}
14+
15+
{% if page.references %}
16+
**OAS References:**
17+
18+
{% 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 %}<br />{% endunless %}{% endfor %}
19+
{% endif %}
20+
21+
## Summary
22+
23+
{{ include.summary }}
24+
25+
{% if include.remarks %}
26+
## Remarks
27+
28+
{{ include.remarks }}
29+
{% endif %}
30+

‎registries/_media-type/binary.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
owner: handrews
3+
name: Binary
4+
description: Non-text-based media types
5+
media_types:
6+
- name: application/octet-stream
7+
iana: https://www.iana.org/assignments/media-types/application/octet-stream
8+
specifications:
9+
- name: RFC2045
10+
url: https://www.rfc-editor.org/rfc/rfc2045
11+
- name: RFC2046 §4.5.1
12+
url: https://www.rfc-editor.org/rfc/rfc2046#section-4.5.1
13+
- name: audio/*
14+
iana: https://www.iana.org/assignments/media-types/media-types.xhtml#audio
15+
specifications:
16+
- name: RFC2045
17+
url: https://www.rfc-editor.org/rfc/rfc2045
18+
- name: RFC2046 §4.2
19+
url: https://www.rfc-editor.org/rfc/rfc2046#section-4.3
20+
- name: image/*
21+
iana: https://www.iana.org/assignments/media-types/media-types.xhtml#image
22+
specifications:
23+
- name: RFC2045
24+
url: https://www.rfc-editor.org/rfc/rfc2045
25+
- name: RFC2046 §4.2
26+
url: https://www.rfc-editor.org/rfc/rfc2046#section-4.2
27+
- name: video/*
28+
iana: https://www.iana.org/assignments/media-types/media-types.xhtml#video
29+
specifications:
30+
- name: RFC2045
31+
url: https://www.rfc-editor.org/rfc/rfc2045
32+
- name: RFC2046 §4.4
33+
url: https://www.rfc-editor.org/rfc/rfc2046#section-4.4
34+
default_for: binary
35+
references:
36+
- section: Working with Binary Data
37+
anchor: working-with-binary-data
38+
parentObject: Schema Object
39+
parentAnchor: schema-object
40+
- section: Binary Streams
41+
anchor: binary-streams
42+
parentObject: Media Type Object
43+
parentAnchor: media-type-object
44+
- section: "`Content-Transfer-Encoding` and `contentEncoding`"
45+
anchor: content-transfer-encoding-and-contentencoding
46+
parentObject: Encoding Object
47+
parentAnchor: encoding-object
48+
layout: default
49+
---
50+
51+
{% capture summary %}
52+
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).
53+
{% endcapture %}
54+
55+
{% capture remarks %}
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.
57+
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.
59+
{% endcapture %}
60+
61+
{% include media-type-entry.md summary=summary remarks=remarks %}

‎registries/_media-type/forms.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
owner: handrews
3+
name: Forms
4+
description: Ordered name-value pairs
5+
media_types:
6+
- name: application/x-www-form-urlencoded
7+
iana: https://www.iana.org/assignments/media-types/application/x-www-form-urlencoded
8+
specifications:
9+
- name: WHATWG URL
10+
url: https://url.spec.whatwg.org/#application/x-www-form-urlencoded
11+
- name: HTTP 4.01 §17.13.4.1
12+
url: https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1
13+
note: historical
14+
- name: RFC1866 §8.2.1
15+
url: https://datatracker.ietf.org/doc/html/rfc1866#section-8.2.1
16+
note: historical but cited by later RFCs and the OAS
17+
- name: multipart/form-data
18+
iana: https://www.iana.org/assignments/media-types/multipart/form-data
19+
specifications:
20+
- name: RFC7578
21+
url: https://www.rfc-editor.org/rfc/rfc7578.html
22+
references:
23+
- section: Encoding By Name
24+
anchor: encoding-by-name
25+
parent: Encoding Usage and Restrictions
26+
parentAnchor: encoding-usage-and-restrictions
27+
- section: Encoding the `x-www-form-urlencoded` Media Type
28+
anchor: encoding-the-x-www-form-urlencoded-media-type
29+
parent: Encoding Object
30+
parentAnchor: encoding-object
31+
- section: Encoding multipart Media Types
32+
anchor: encoding-multipart-media-types
33+
parent: Encoding Object
34+
parentAnchor: encoding-object
35+
- section: "Appendix C: Using RFC6570-Based Serialization"
36+
anchor: appendix-c-using-rfc6570-based-serialization
37+
- section: "Appendix E: Percent-Encoding and Form Media Types"
38+
anchor: appendix-e-percent-encoding-and-form-media-types
39+
layout: default
40+
---
41+
42+
{% capture summary %}
43+
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.
44+
{% endcapture %}
45+
46+
{% capture remarks %}
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.
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.
49+
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).
53+
{% endcapture %}
54+
55+
{% include media-type-entry.md summary=summary remarks=remarks %}

‎registries/_media-type/linksets.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
owner: handrews
3+
name: Link Sets
4+
description: Sets of RFC8288 Web Links
5+
media_types:
6+
- name: application/linkset
7+
iana: https://www.iana.org/assignments/media-types/application/linkset
8+
specifications:
9+
- name: RFC9264
10+
url: https://www.rfc-editor.org/rfc/rfc9264
11+
- name: RFC8288
12+
url: https://www.rfc-editor.org/rfc/rfc8288
13+
- name: application/linkset+json
14+
iana: https://www.iana.org/assignments/media-types/application/linkset+json
15+
specifications:
16+
- name: RFC9264
17+
url: https://www.rfc-editor.org/rfc/rfc9264
18+
references:
19+
- section: Modeling Link Headers
20+
anchor: modeling-link-headers
21+
parentObject: Header Object
22+
parentAnchor: header-object
23+
layout: default
24+
---
25+
26+
{% capture summary %}
27+
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.
28+
{% endcapture %}
29+
30+
{% capture remarks %}
31+
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.
32+
{% endcapture %}
33+
34+
{% include media-type-entry.md summary=summary remarks=remarks %}

‎registries/_media-type/sequential_json.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
owner: handrews
3+
name: Sequential JSON
4+
description: Multiple concatenated JSON documents suitable for streaming
5+
media_types:
6+
- name: application/jsonl
7+
iana: false
8+
specifications:
9+
- name: JSON Lines
10+
url: https://jsonlines.org/
11+
- name: application/json-seq
12+
iana: https://www.iana.org/assignments/media-types/application/json-seq
13+
specifications:
14+
- name: RFC7464
15+
url: https://www.rfc-editor.org/rfc/rfc7464
16+
- name: RFC8091
17+
url: https://www.rfc-editor.org/rfc/rfc8091
18+
- name: application/x-ndjson
19+
iana: false
20+
specifications:
21+
- name: Newline Delimited JSON
22+
url: https://github.com/ndjson/ndjson-spec
23+
references:
24+
- section: Sequential Media Types
25+
anchor: sequential-media-types
26+
parentObject: Media Type Object
27+
parentAnchor: media-type-object
28+
- section: Streaming Sequential Media Types
29+
anchor: streaming-sequential-media-types
30+
parentObject: Media Type Object
31+
parentAnchor: media-type-object
32+
- section: Sequential JSON
33+
anchor: sequential-json
34+
parentObject: Media Type Object
35+
parentAnchor: media-type-object
36+
layout: default
37+
---
38+
39+
{% capture summary %}
40+
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.
41+
{% endcapture %}
42+
43+
{% capture remarks %}
44+
All sequential JSON media types support the same two approaches:
45+
* Use the `schema` field to model the whole document as if it were a JSON array
46+
* Use `itemSchema` to model one item at a time for streaming purposes, where all items use the same schema
47+
{% endcapture %}
48+
49+
{% include media-type-entry.md summary=summary remarks=remarks %}

‎registries/_media-type/sequential_multipart.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
owner: handrews
3+
name: Sequential Multipart
4+
description: Multipart subtypes with unnamed parts
5+
media_types:
6+
- name: multipart/*
7+
iana: https://www.iana.org/assignments/media-types/media-types.xhtml#multipart
8+
specifications:
9+
- name: RFC2045
10+
url: https://www.rfc-editor.org/rfc/rfc2045
11+
- name: RFC2046 §5.1
12+
url: https://www.rfc-editor.org/rfc/rfc2046#section-5.1
13+
- name: multipart/mixed
14+
iana: https://www.iana.org/assignments/media-types/multipart/mixed
15+
specifications:
16+
- name: RFC2045
17+
url: https://www.rfc-editor.org/rfc/rfc2045
18+
- name: RFC2046 §5.1.3
19+
url: https://www.rfc-editor.org/rfc/rfc2046#section-5.1.3
20+
- name: multipart/alternative
21+
iana: https://www.iana.org/assignments/media-types/multipart/alternative
22+
specifications:
23+
- name: RFC2045
24+
url: https://www.rfc-editor.org/rfc/rfc2045
25+
- name: RFC2046 §5.1.4
26+
url: https://www.rfc-editor.org/rfc/rfc2046#section-5.1.4
27+
- name: multipart/related
28+
iana: https://www.iana.org/assignments/media-types/multipart/related
29+
specifications:
30+
- name: RFC2389
31+
url: https://www.rfc-editor.org/rfc/rfc2389
32+
- name: RFC2557
33+
url: https://www.rfc-editor.org/rfc/rfc2557
34+
- name: multipart/byteranges
35+
iana: https://www.iana.org/assignments/media-types/multipart/byteranges
36+
specifications:
37+
- name: RFC9110 §14.6
38+
url: https://www.rfc-editor.org/rfc/rfc9110#name-media-type-multipart-bytera
39+
references:
40+
- section: Encoding By Position
41+
anchor: encoding-by-position
42+
parentObject: Media Type Object
43+
parentAnchor: media-type-object
44+
- section: Encoding `multipart` Media Types
45+
anchor: encoding-multipart-media-types
46+
parentObject: Encoding Object
47+
parentAnchor: encoding-object
48+
layout: default
49+
---
50+
51+
{% capture summary %}
52+
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).
53+
{% endcapture %}
54+
55+
{% capture remarks %}
56+
All known `multipart` subtypes except `multipart/form-data` are ordered, without any names for the parts.
57+
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`).
58+
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.
59+
60+
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.
61+
62+
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.
63+
{% endcapture %}
64+
65+
{% include media-type-entry.md summary=summary remarks=remarks %}
66+

‎registries/_media-type/sse.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
owner: handrews
3+
name: Server-Sent Events
4+
description: Event streams for SSE
5+
media_types:
6+
- name: text/event-stream
7+
iana: false
8+
specifications:
9+
- name: WHATWG HTML §Server-Sent Events
10+
url: https://html.spec.whatwg.org/multipage/server-sent-events.html#parsing-an-event-stream
11+
- name: WHATWG HTML §IANA
12+
url: https://html.spec.whatwg.org/multipage/iana.html#text/event-stream
13+
references:
14+
- section: Sequential Media Types
15+
anchor: sequential-media-types
16+
parentObject: Media Type Object
17+
parentAnchor: media-type-object
18+
- section: Special Considerations for Server-Sent Events
19+
anchor: special-considerations-for-server-sent-events
20+
parentObject: Media Type Object
21+
parentAnchor: media-type-object
22+
- section: Server-Sent Event Stream (Examples)
23+
anchor: server-sent-event-streams
24+
parentObject: Media Type Object
25+
parentAnchor: media-type-object
26+
layout: default
27+
---
28+
29+
{% capture summary %}
30+
Server-Sent Events use the `text/event-stream` media type to stream events.
31+
Each event is modeled as if it were a JSON object with fields and types
32+
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.
33+
{% endcapture %}
34+
35+
{% capture remarks %}
36+
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.
37+
38+
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.
39+
{% endcapture %}
40+
41+
{% include media-type-entry.md summary=summary remarks=remarks %}

‎registries/_media-type/text.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
owner: handrews
3+
name: Text
4+
description: Text-based media types
5+
media_types:
6+
- name: text/*
7+
iana: https://www.iana.org/assignments/media-types/media-types.xhtml#text
8+
specifications:
9+
- name: RFC2045
10+
url: https://www.rfc-editor.org/rfc/rfc2045
11+
- name: RFC2046 §4.1
12+
url: https://www.rfc-editor.org/rfc/rfc2046#section-4.1
13+
- name: text/plain
14+
iana: https://www.iana.org/assignments/media-types/text/plain
15+
specifications:
16+
- name: RFC2046 §4.1.3
17+
url: https://www.rfc-editor.org/rfc/rfc2046#section-4.1.3
18+
- name: RFC3676
19+
url: https://www.rfc-editor.org/rfc/rfc3676
20+
default_for: text-based (not just <tt>text/*</tt>)
21+
references:
22+
- section: Parameter Object
23+
anchor: parameter-object
24+
- section: Header Object
25+
anchor: header-object
26+
- section: Encoding Object
27+
anchor: encoding-object
28+
layout: default
29+
---
30+
31+
{% capture summary %}
32+
A plain text document is modeled as a single string.
33+
{% endcapture %}
34+
35+
{% capture remarks %}
36+
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.
37+
{% endcapture %}
38+
39+
{% include media-type-entry.md summary=summary remarks=remarks %}

0 commit comments

Comments
 (0)