Registry of media type modeling approaches

[handrews]

It's fairly common for people to want to model things that are not obviously mapped to the JSON Schema data model. We basically support a few media types, which would include any variations with a structured suffix (e.g. +json) as long as the additional features of the media type don't need to be modeled:

• application/json is supported natively with the Schema Object
• application/xml is supported (to some degree) with the XML Object
• application/x-www-form-urlencoded is supported (to some degree) in message bodies with the Encoding Object
• multipart/form-data is supported (to some degree) with the Encoding Object
• text/plain is arguably supported by treating it as a single string, but arguably you could do more with textual serialization of data

The spec talks about multipart in general, but other multipart formats use ordered rather than named parts, which makes the Encoding Object unsuitable. We also have requests for formats with a little more information than JSON.

We definitely want to keep some media types in the spec, as they are either commonly used in HTTP APIs, or have significant enough historical usage that they need an interoperable way to be modeled.

But other media types are more fringe, or emerging, or are such niche historical oddities that it's not worth trying to define an mandatory interoperable approach. But they could still use some interoperability that's more opt-in.

Therefore I'd like to propose a new registry for defining how the a media type can be mapped to the JSON Schema data model. In some cases, this is pretty intuitive and doesn't even require much implementaton support. In other cases, it might get pretty elaborate, but we can let the community sort out what is worth imlementing or not.

Why not just use x-fields?

This proposal is essentially "x-fields for media types." The approaches might use x-fields, but not all would need any x-fields, and some might need a combination of multiple ones. This is not an area that always breaks down to fields - both the XML Object and the Encoding Object are more complex than that. This would give more flexibility, plus a single place to look for this specific topic.

What about things without media types?

Structured headers come to mind, and would have a similar approach but without a media type. They also go somewhere different than request/response bodies, which need something to put in Content-Type anyway. If there are non-header, non-body things that need dealing with that don't have a media type, we can cross that bridge when we get to it.

Relevant issues:

Many of the issues with the media and encoding label are relevant to greater or lesser degrees. Many (such as application/json-seq or multipart/mixed) are sufficiently core that they ought to be in the spec. But others, such as application/cbor are less obvious fits at this time, but well worth community experimentation.

[handrews]

It would also be good to extend this registry to HTTP headers. Given how the Parameter Object and Media Type Objects work, this might need to be done by making up some x-oas media types (or vnd.oas?), but we have a lot of header modeling problems and a data modeling problem is a data modeling problem whether the specification is a media type or something else that defines a grammar.