Media Types Registry #4808
Draft
Media Types Registry #4808
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
handrews
added
the
registries
philsturgeon
approved these changes
Jul 23, 2025
There was a problem hiding this comment.
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
reviewed
Jul 23, 2025
registries/_media-type/forms.md
Outdated
There was a problem hiding this comment.
Add links to the mentioned OAS Objects?
Co-authored-by: Phil Sturgeon <[email protected]>
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.
|
@ralfhandl OK I just added a lot of updates, including some you did not ask for :-) |
|
@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
commented
Aug 7, 2025
| {% 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. |
There was a problem hiding this comment.
@handrews to update this for fixed percent-encoding / style stuff
handrews
commented
Aug 7, 2025
|
|
||
| {% 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. |
There was a problem hiding this comment.
This too if the draft PR is accepted
handrews
commented
Aug 7, 2025
Comment on lines
+11
to
+12
| - name: application/json-seq | ||
| registered: https://www.iana.org/assignments/media-types/application/json-seq |
There was a problem hiding this comment.
Not showing up as registered, check why
ralfhandl
approved these changes
Aug 8, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
[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.