Allow mapping a media type to a schema definition

This is a proposal for OpenAPI.next.

---

One of the foundations of REST are media types (inherited from MIME, such as text/html). A media type defines how a resource representation might look like, and what it means.

For JSON REST APIs described with Swagger, one possible way of using media types is to declare anything as application/json – because actually every message is in this format. But of course our API will not accept/produce just any JSON document – we have schema definitions which restrict what can be in a response, or in a body parameter, and whose descriptions also give some meaning to the fields of the JSON object. In effect, we are creating a kind of media type here.

In my team, we actually define a media type for each schema (e.g. application/x.zalando.wholesale.warehouse+json in one of my recent APIs), and use it also for the Content-Type and Accept headers (and document it in the produces/consumes properties of the operations).

Could we make it possible to formally name the media type belonging to a schema?

First, this is just documentation. But then this could also be used to enable Content-Negotiation (in #146), by linking it to the consumes/produces properties of an operation.

[DavidBiesack]

Most response objects are tied to a schema, so it seems natural to me to make the link between media type and schema at the schema object, not in the Response object. It is of no value to us to use the same schema but with different media types in different operations or responses. This of course assumes that the schema is sufficiently expressive enough to accurately describe the media type.

[DavidBiesack]

👍 the tools could also recognize the association (code gen, UI). For example, in the UI, select a Request Content Type from the drop down, and the UI would show the associated model schema, which the user could then select to populate the request body (or if there were an example associated with the schema or media type, populate the input text area with that example JSON.)