OpenApi media type registration questions

As a member of the Technical Developer Community of the Open APIs Initiative
( https://openapis.org/governance ), I am exploring options for registering
media types for the Open API specification (previously Swagger)
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md .


Currently this document format is in its second major revision and we are
working towards a third that is likely going to have breaking changes.  The
document itself has a version property within it so there is no need for
that to appear in the media type.

There are also two distinct representations of the OpenAPI document.  One
uses the JSON format and the other uses the YAML format. It would be
desirable to distinguish between these two representations and we believe
the best approach would be to follow the precedent set by RFC 6839 and use a
+json and +yaml suffix.  As +yaml is not defined with RFC 6839 and there is
no registry defined in which to add this new suffix, I am assuming a new RFC
would be needed to register this.

As we see it, there are two different subtypes that are potentials homes for
these registrations.  There is the vendor subtree and the Standards subtree.
Considering the current support and fairly broad adoption of this format and
its new home in the Linux Foundation, I would think the standards tree would
be the more appropriate place. However, any guidance on this would be
appreciated. 

I would like to submit registrations for:

  application/openapi+json
  application/openapi+yaml
  
Other than the need for +yaml RFC does anyone have any objections to these?

One final question is related to the fact that these formats are a form of
documentation for an API and may be read directly by humans.  Is it
recommended to also register text/ versions of these media types to allow
servers to communicate this intent?

Thanks for any info/opinions/guidance you can provide.

Darrel Miller

Received on Tuesday, 8 March 2016 00:59:05 UTC