Re: [media-types] OpenApi media type registration questions

[Sean Leonard <[e-mail]>]

On 3/7/2016 5:40 PM, Darrel Miller wrote:
> 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.

You can put it in the Standards subtree if you want. It is slightly more 
work, but you can jettison the ".vnd" part.

To get it in the Standards subtree, either the registration has to be 
based on a specification by a recognized Standards Development 
Organization (SDO), or published as an RFC at least at Informational 
level. Only the format specification has to be by a a recognized 
SDO--the format specification document does not have to incorporate the 
media type registration template. So if you already have the format in a 
published document, you can write the media type registration template 
yourself.

However, it sounds like you need to publish an RFC in this case 
(assuming that you don't want ".vnd"). The RFC can go through IETF 
Consensus (i.e., go through a working group), or can go through the 
Independent Submission Editor as an Independent document.


>
> 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?

No objections, just further comments.

>
> 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?


Regarding +yaml, adding a new structured syntax registration requires 
Expert Review. This means that an RFC is not required. Just fill out the 
template and get it reviewed and approved.

Under the circumstances, however, I would recommend that a discrete YAML 
media type be defined if you want the structured syntax suffix. This is 
mainly because it seems to make sense to have a generic way to 
interchange YAML that is not specific to OpenAPI. I would recommend 
text/yaml. The distinction between text/yaml and application/yaml boils 
down to a few considerations:

1. Whether you want to preserve the bytes exactly "as-is", versus have 
media type aware processors "massage it" on the way down (e.g., 
manipulate or canonicalize LF <-> CRLF).

2. Whether you want media type handlers to fall back to text/plain or 
application/octet-stream. The former will behave like a plain text file 
or stream (because it is). The latter will look like an opaque blob or 
opaque file (because it is).

3. Whether the format itself declares the charset. In (for example) XML, 
<?xml version="1.0" encoding="XXX"?> declares the charset, so text/xml; 
charset=YYY can get out-of-sync.

3. Whether you want charset conversion services. text/yaml; 
charset="iso-8859-15" can get converted to (any) Unicode encoding 
"automagically". Per RFC 6657, the registration of the text-based media 
type is supposed to declare the default or preferred charset. So even if 
you assume YAML is "always" in Unicode, that alone is not a reason to go 
to application/yaml (because in text/yaml you can just declare that YAML 
is always in one of the Unicode encodings).

Overall my opinion is on the side of text/yaml, if you register the 
generic type at all. You do not have to. I am not familiar with the 
history of YAML, but I suppose there is probably some reason why it has 
not been registered yet. Perhaps implementers found that text/plain 
worked fine for them, or for computer-to-computer interchange it was 
easier to exchange JSON or XML.

Sean