What is the media type of an OpenAPI schema?

Question

Whenever searching for this I find resources on how to specify the media type of a resource that the schema defines, but I can't see an answer on what the actual media type of the schema itself is.

Given the way HTTP works, it makes sense to me that if I request the right content type with the Accept header, my server can respond appropriately.

Thus, if I request /products with Accept: application/json I would get products in JSON format, but if I requested openapi-whatever I would get the OpenAPI schema.

I think I can probably use either application/openapi+json or application/openapi+yaml, but I can't see anything about it in the actual specification.

I'm not sure whether or not I actually want to use the Accept header for this difference, but I certainly want to respond with the correct Content-Type header in any case.

Answer 1

The OpenAPI Initiative's Technical Steering Committee (TSC) approved the following media types:

application/vnd.oai.openapi      (YAML variant)
application/vnd.oai.openapi+json (JSON only variant)

with an optional version parameter:

application/vnd.oai.openapi;version=2.0

However, these media types are not yet registered with IANA.

Answer 2

This seems to be newer (Sept. 2021):

• application/openapi+yaml
• application/openapi+json

https://www.ietf.org/archive/id/draft-polli-rest-api-mediatypes-00.html