Allow mapping a media type to a schema definition

[ePaul]

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]

:+1: 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.)

[dolmen]

It doesn't seem that binding a MIME type to a schema is necessary. But it would be at least needed to be able to specify a MIME type for each Response object.

In Swagger 2.0 produces is defined at the operation level and applies to all responses. This forbid to uses different MIME types for different responses and to use for example a specific MIME type for errors, as proposed in RFC 7807 ("Problem Details for HTTP APIs").

[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.

[handrews]

@webron @darrelmiller I think in OAS 3.0 this is handled by organizing responses, including schemas, under media types, right? So this can probably be closed.

[ioggstream]

Can we close? @darrelmiller @ePaul

[handrews]

Proposed to close 3+ years ago with no objections, closing.