Media Types Registry #4808

handrews · 2025-07-22T20:18:07Z

[NOTE: This is only a "draft" to keep it from being published too early. It is fully ready for review.]

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.

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.

registries/_media-type/sequential_multipart.md

philsturgeon

This is really good. There are plenty of examples of times tooling was unaware of a particular variant of multipart or whatever and because the spec isnt a good place to list potentially evolving lists of formats this is a great solution.

I edited one bit for more neutral language but it ofc made me chuckle.

ralfhandl

+1 in general, with some questions

_includes/media-type-entry.md

ralfhandl · 2025-07-23T14:21:00Z

_includes/media-type-entry.md

@@ -0,0 +1,28 @@
+# <a href=".">{{ page.collection }}</a>
+
+## {{ page.description }}


Why not

## {{ page.slug }} - {{ page.description }}

as in all other includes?

Because the slug (and the collection name) aren't UI elements. We shouldn't be using the page slug at all except in places like URLs where the syntax restrictions on slugs make sense. I strongly dislike using the collection name there as well- media-type looks awful as a page title. format is tolerable, although it should be Format. The slug is the file name which is not useful in many cases.

Although I don't actually remember taking the slug out, so it's probably because I copied the tag kind registry as the newest registry. It doesn't do that either.

But I flat-out refuse to have a page title like sequential_json - Sequential JSON.

If we want a name plus a description, then I can move the current description field to a new name field and add a description field with an actual description. And preferably replace {{ page.collection }} with a more readable title while I'm at it. media-type is awful.

Agreed, we should check where the slug makes sense - maybe in the Format registry if it is the technical name of the described format - and remove it everywhere else.

I also like the idea of a readable title instead of the technical page.collection name - can we access the name attribute we define per collection in _config.yaml?

ralfhandl · 2025-07-23T14:36:59Z

_includes/media-type-entry.md

+{% 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.


Is it "unknown" or "other"?

If "unknown", unknown by whom?

Unknown to the tool. Let's say I send you something as application/jsonpath, a media type we actually use in an example in the spec. That is a text-based media type, so you just model it as a string. Which we do in that example.

On the other hand, application/http is technically binary as the content portion can be raw binary (actually this is an interesting case as messages with text content could be treated as text 🤔 , although if you want to ensure text you use message/http but then you have to deal with fairly bonkers legacy MIME client formatting requiremetns).

I'm not dead set on using "unknown". I don't like "other" because it gives the sense that there's some known set of media types (only sort-of true as not even all the ones in our registry are IANA-registered), where everything not explicitly listed is "other." But (as we see with application/http), it's not even entirely clear where some of the boundaries are. On the other hand, given a truly unknown media type, how does the tool determine text vs binary? If it's got a charset parameter, it's text-based, but many (most?) text-based types do not have such a parameter.

If we can't figure out what to say here I can just take page.default_for out and we can think on it more. That might be safest.

I think "unrecognized" might be better.

ralfhandl · 2025-07-23T14:40:06Z

registries/_media-type/binary.md

+{% 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`.


Suggested change

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 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`.

Also: should "Encoding Object" and "Schema Object" be links to the spec, or should there be OAS References to these Objects?

In English, the word after a colon is capitalized. The colon, like the period, should also have two spaces after it, but HTML destroyed that rule :-(

I googled and found

In American English, the first word after a colon is sometimes capitalized if it begins a complete sentence

which is not the case here. Found multiple sources with similar rules, and stumbled over the "W" because my reading experience matches these rules.

Won't insist if you disagree 🤷‍♂️

You've got references, I'll go with it. I was just taught "treat a colon like a period" as a dimly-remembered rule from grade school.

ralfhandl · 2025-07-23T14:41:35Z

registries/_media-type/forms.md

Add links to the mentioned OAS Objects?

ralfhandl · 2025-07-23T14:43:17Z

registries/_media-type/linksets.md

+{% endcapture %}
+
+{% capture remarks %}
+In addition to modeling the `Link` header, these two media types are supported anywhere else a media type document is allowed.


What is a "media type document"?

Document of a particular media type? Please feel free to suggest something better, I wasn't all that satisfied with that phraase even when I wrote it.

I don't understand what the sentence is supposed to mean, so I'm in favor of removing it.

Oh I see. I just mean under any content field that takes Map [string, Media Type Object]. Which is annoyingly convoluted to say.

I think we don't have to say it at all. If some places in the OAS would restrict allowed media types, these places would have to spell that out.

Default is "anything goes".

Co-authored-by: Phil Sturgeon <67381+philsturgeon@users.noreply.github.com>

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.

handrews · 2025-07-23T18:30:51Z

@ralfhandl OK I just added a lot of updates, including some you did not ask for :-)

handrews · 2025-07-23T20:23:32Z

@ralfhandl Addressed both the remaining things. I just rewrote the Link Sets page a bit and I hope it overall makes more sense now.

handrews added this to the v3.2.0 milestone Jul 22, 2025

handrews requested review from philsturgeon and a team July 22, 2025 20:18

handrews added the registries Related to any or all spec.openapis.org-hosted registries label Jul 22, 2025

handrews marked this pull request as draft July 22, 2025 20:18

philsturgeon reviewed Jul 23, 2025

View reviewed changes

registries/_media-type/sequential_multipart.md Outdated Show resolved Hide resolved

philsturgeon approved these changes Jul 23, 2025

View reviewed changes

ralfhandl reviewed Jul 23, 2025

View reviewed changes

handrews and others added 2 commits July 23, 2025 08:21

Update registries/_media-type/sequential_multipart.md

bda90e1

Co-authored-by: Phil Sturgeon <67381+philsturgeon@users.noreply.github.com>

More info and better formatting in media type registry

2ce5114

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.

More review fixes.

36fea1a

		@@ -0,0 +1,28 @@
		# <a href=".">{{ page.collection }}</a>

		## {{ page.description }}

	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 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`.

Media Types Registry #4808

Are you sure you want to change the base?

Media Types Registry #4808

Uh oh!

Conversation

handrews commented Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

philsturgeon left a comment

Choose a reason for hiding this comment

Uh oh!

ralfhandl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

handrews commented Jul 23, 2025

Uh oh!

handrews commented Jul 23, 2025

Uh oh!

Uh oh!

handrews commented Jul 22, 2025 •

edited

Loading