Media Types Registry #4808
Media Types Registry #4808
Conversation
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
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.
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 Is this PR now ready for review/merge? It already has two TSC approvals, and there shouldn't be any harm in publishing the mew registry before referencing it in a new spec version. |
|
I read this as having a few edits pending (the open comments). Agree that we can publish whenever @handrews and enough reviewers are happy! |
|
The tag kinds registry is also already published: https://spec.openapis.org/registry/tag-kind/index.html |
|
@lornajane @ralfhandl I'm probably going to hold off until after we restructure the headings, as those will change where the links go. As will the resolution of this conversation about headings and anchors in PR4876. |
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.
|
@ralfhandl and all @OAI/tsc , this is now "ready for review" with all known expected fixes done, but I'm leaving it in draft so it doesn't get merged yet. Taking it out of draft will not clear the approvals, so if approved it should be fine to take it out of draft and merge it as soon as 3.2 is on the spec site. Or right before. Just let's not leave something with broken links up for a week or more. |
|
I will be out of town next week- if we are ready to ship while I am away, feel free to make any final edits and approve and merge without my involvement. Particularly as we can deploy further updates at any time if I spot some other issue when I get back. |
|
Do you think the PR is ready for review as it is now? |
|
@ralfhandl Review yes, merge no.
|
[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.