First pass at a media types registry. #4517
Conversation
This attempts to explain the basics of what is going on in terms of "modeling" (what you do with a Schema Object and in-memory data structures) and "mapping" (how you translate that model into something that fits a particular media type that can be serialized onto, or parsed off of, the wire). This includes some sequential / streaming formats that will be added for 3.2, as well as a selection of media types directly addressed in the OAS text. We could add more, for example `image/*` that is more-or-less identical to `application/octet-stream`, but this gives the general idea. I omitted YAML since AFAIK it is rarely used in actual API payloads, and such use is not directly mentioned in the OAS.
handrews
added
media and encoding
|
|
||
| # Media Type Registry | ||
|
|
||
| This registry defines how to use the Schema Object, Media Type Object, and in some cases other Objects to model media types other than `application/json` or media types using a `+json` suffix. |
There was a problem hiding this comment.
| This registry defines how to use the Schema Object, Media Type Object, and in some cases other Objects to model media types other than `application/json` or media types using a `+json` suffix. | |
| This registry defines how to use the Schema Object, Media Type Object, and in some cases other Objects to model media types other than `application/json` including media types using a `+json` suffix. |
There was a problem hiding this comment.
@duncanbeevers I don't think +suffix media types are considered subsets of the larger type? @darrelmiller might know for certain. But I think the semantics (indicated by the part before the +) are considered more important than the syntax (after the +) which is just a "here's how you can do partial processing" bit of info.
There was a problem hiding this comment.
I think its been pretty common for folks to see application/something+json as the subtype is more like metadata (application/vnd.google+json would be type/metadata+subtype) but in reality the subtype is more important, and the suffix is on a short list of defined ways to process that, one of which is +json meaning its really type/subtype+waytoprocessit.
If you believe the former then "including" makes sense, but if you believe the latter then the latter then "or" makes more sense.
Some relevant RFC over here: https://datatracker.ietf.org/doc/html/rfc6838#section-4.2.8
4.2.8. Structured Syntax Name Suffixes
XML in MIME [RFC3023] defined the first such augmentation to the
media type definition to additionally specify the underlying
structure of that media type. To quote:This document also standardizes a convention (using the suffix '+xml') for naming media types ... when those media types represent XML MIME (Multipurpose Internet Mail Extensions) entities.That is, it specified a suffix (in that case, "+xml") to be appended
to the base subtype name.Since this was published, the de facto practice has arisen for using
this suffix convention for other well-known structuring syntaxes. In
particular, media types have been registered with suffixes such as
"+der", "+fastinfoset", and "+json". This specification formalizes
this practice and sets up a registry for structured type name
suffixes.
Conveniently summarized on Wikipedia (and nowhere else really):
Suffix is an augmentation to the media type definition to additionally specify the underlying structure of that media type, allowing for generic processing based on that structure and independent of the exact type's particular semantics. Media types that make use of a named structured syntax should use the appropriate IANA registered "+"suffix for that structured syntax when they are registered. Unregistered suffixes should not be used (since January 2013). Structured syntax suffix registration procedures are defined in RFC 6838.[15]
The +xml suffix has been defined since January 2001 (RFC 3023[17]), and was formally included in the initial contents of the Structured Syntax Suffix Registry along with +json, +ber, +der, +fastinfoset, +wbxml, and +zip in January 2013 (RFC 6839). Subsequent additions include +gzip, +cbor, +json-seq, and +cbor-seq.[18]
IMO this means the or is fine.
Co-authored-by: Duncan Beevers <[email protected]>
|
@duncanbeevers examples, schemas, representative payloads, etc. all belong on the learn site. All of the registries are bare-bones references, and this one is in line with that pattern. Contributions to the Learn site are encouraged :-) |
|
@duncanbeevers I do think that if/when we have that content on the Learn site, we should link to it directly from here (and similarly for other registries). |
|
I'm not sure if the Learn site is the most appropriate place to put the mapping information and schemas? Surely that would be considered part of the specification itself (although not the core spec). |
|
@karenetheridge @duncanbeevers please let's have the debate over where to put additional content somewhere else, like a discussion here or in the learn repo. Please keep this PR focused on the changes that are in-scope. @karenetheridge no one is proposing moving the actual mapping info out of the spec or registries. |
I wasn't aware this information was ever there to begin with. Where is it, as I cannot find it? |
|
@karenetheridge the registry entries in this PR link to the relevant parts of the specification. It's not all laid out in that exact language, of course, because I'm retrofitting a consistent concept onto an inconsistent set of rules, but I'm only talking about what's in the spec, and this registry only indexes what is in the spec. I am not trying to expand beyond that in this PR, nor is this PR trying to solve where additional things that aren't already present should live. |
Thanks to @jeremyfiel for reminders of how confusing this is.
This attempts to explain the basics of what is going on in terms of "modeling" (what you do with a Schema Object and in-memory data structures) and "mapping" (how you translate that model into something that fits a particular media type that can be serialized onto, or parsed off of, the wire).
This includes some sequential / streaming formats that will be added for 3.2, as well as a selection of media types directly addressed in the OAS text. We could add more, for example
image/*that is more-or-less identical toapplication/octet-stream, but this gives the general idea.I omitted YAML since AFAIK it is rarely used in actual API payloads, and such use is not directly mentioned in the OAS.