Need a media type for OpenAPI Specifications

[mpnally]

We are implementing an API in which the body of some messages can be OpenAPI Specification "documents". For this purpose, we need a media type for OpenAPI Specifications. We would prefer to use a standard one (or more) blessed by the OpenAPI initiative rather than making up our own.

Our application requires that OpenAPI Specifications be treated as text documents, in the sense that if a specification is PUT or POSTed, a subsequent GET will return a body that is character-by-character the same as the one that was PUT (assuming someone else didn't change it in between times). This suggests to us that for this usage, a text/something media type is the right one. Our preferred format is yaml, so something like text/oas+yaml would make sense. We would probably also support text/oas+json. If we did not have the requirement of character-by-character fidelity, we might be attracted more to something in the application/something family, and it may be that different media types are needed for different usages.

[lovelydinosaur]

Duplicate of #110

[darrelmiller]

I'm not sure I understand the suggested relationship between symmetrical PUT/GET requests and the text/* media types. A server can chose to make GET/PUT symmetrical whether the media type is application/* or text/. And personally I see no reason for trying to register a text/ media type for OpenAPI.

[mpnally]

Oops, sorry about the duplicate.

It seems to be hard to find clear guidance on when to use application/something versus text/something. Why do we use text/html rather than application/html? Why is there both text/xml and application/xml? RFC 3023 says this: "If an XML document -- that is, the unprocessed, source XML document -- is readable by casual users, text/xml is preferable to application/xml".

In our scenarios, the clients are treating the OAS as a text document, so text/oas+yaml makes sense to me. If our client were interested primarily in the API specified by the OAS document, rather than the document itself, text/oas+yaml would make sense to me. It would be nice if OAS allowed URLs for both the API and the OAS document to be established, as JSON Schema does. If we had that, a way to formalize what I said above would be to say that application/oas+yaml would be my preferred media type for the API itself, while text/oas+yaml would be my preferred media type for the OAS document that describes it.

[webron]

@darrelmiller @mpnally - since this is indeed a duplicate of #110, would you mind moving this part of the discussion there? It'd make tracking things easier.

[mpnally]

My fault, sorry. Should we just stop this thread, or should I also try to transfer some of this discussion to f #110 ?

[akuckartz]

@mpnally yes, do it, please.

[webron]

I'd suggest moving the critical parts there, though the issues are linked and should be handled together. For a higher chance of this being taken under consideration, mention those there please.

Closing the ticket for now.