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

From: Darrel Miller <[email-masked]>
Date: Mon, 7 Mar 2016 17:40:18 -0800

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

---

From: Sean Leonard <[email-masked]>
Date: Mon, 7 Mar 2016 21:25:32 -0800

> be the more appropriate place. However, any guidance on this would be

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.

> Other than the need for +yaml RFC does anyone have any objections to these?

No objections, just further comments.

> 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

---

From: Darrel Miller <[email-masked]>
Date: Wed, 9 Mar 2016 16:29:02 -0800

Thanks for your feedback Sean.

> -----Original Message-----
> From: media-types [mailto:[email-masked]] On Behalf Of
> Sean Leonard

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

I'm just guessing, but I don't believe there is going to be any appetite for
republishing the existing specification as an IETF document.  I will find
out.

> 
> 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.
> 
As there is an existing "working group" managed via the Linux Foundation
infrastructure, an independent submission would probably be the appropriate
route to take, assuming the group decide it is worth publishing an IETF
version of the spec to remove the vnd.

> 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.
> 
I'm not sure I follow.  Where would I find this template to fill out that
allows me to register a new suffix?  I don't see any reference to this
process in RFC 6839.

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

I had not considered the fact that someone had never got around to
registering a YAML media type.

> The
> distinction between text/yaml and application/yaml boils down to a few
> considerations:
> snip

Thanks for enumerating these.  It was never really clear to me when to use
one versus the other.

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

I think YAML sees more usage as a file format than a message format and
therefore the need for a media type has been less pressing.

Thanks again for your assistance.

Darrel

---

From: Sean Leonard <[email-masked]>
Date: Wed, 9 Mar 2016 16:44:11 -0800

> allows me to register a new suffix?  I don't see any reference to this

RFC 6838 Section 6
https://tools.ietf.org/html/rfc6838#section-6

RFC 6839 has examples of the template actually instantiated in the text.

> Thanks again for your assistance.

You are welcome!

Sean

---

From: Darrel Miller <[email-masked]>
Date: Wed, 9 Mar 2016 17:20:14 -0800

Sean,

> RFC 6839 has examples of the template actually instantiated in the text.

Thanks. So this is where I find myself in a catch-22 situation.  In order to
register the +yaml suffix, it needs to there a reference to a specification
for YAML.  However, there is no such specification that is managed by a SDO.
I searched in the YAML Core mailing list and back in 2003 they discussed
their plan to use text/yaml as the media type.  There has been no further
discussion of registering a media type since then on the list.

So it seems that, without a spec under an SDO, it would not be possible to
register text/yaml or register the suffix.

It seems that the only option available would be for someone to convince the
YAML team to allow a variant of their spec (it has images in it) to be
created as an IETF spec.

Does that reasoning appear sound?

Darrel

---

From: Sean Leonard <[email-masked]>
Date: Wed, 9 Mar 2016 17:28:26 -0800

[adding apps-discuss and dispatch]

> Does that reasoning appear sound?

Not exactly.

First of all, it's the same situation as Markdown (see the text/markdown 
discussion over time on the apps-discuss mailing list).

The most important hurdle has been passed: some people actually *want* 
text/yaml.

The second hurdle has also (likely) been passed: people are actually 
using text/yaml for YAML stuff. This turns out to be more useful than 
the registration itself. Deploy first, register later. ;-)

The next hurdle is overcoming developer laziness, since it requires some 
modicum of effort to do the registration. Sounds like we have a willing 
victim...er...volunteer. ;-)

Getting text/yaml just requires an Informational independent-stream or 
IETF stream RFC. First write an Internet-Draft. The Internet-Draft can 
reference the yaml.org specification, without changing control over the 
specification to the IETF. Then submit the draft to the dispatch mailing 
list. (Maybe also a couple of other mailing lists, for places in IETF 
that use YAML.)

Depending on the outcome of the discussion, either the IETF will take it 
up, or not. If they do, then the media type registration will be 
published with IETF Consensus (see text/markdown). If not, then it can 
still be published an the independent stream by submitting it to the 
Independent Submissions Editor (see image/bmp, aka 
draft-seantek-windows-image) 
<https://www.rfc-editor.org/about/independent/>.

I have not tried to register a structured syntax suffix before. 
Superficially, the process appears to be simpler, as it only needs 
Expert Review. For that, just follow what RFC 6838 Section 6 says.

Best of luck!

Sean

---

From: Mark Baker <[email-masked]>
Date: Wed, 9 Mar 2016 21:33:29 -0500

FYI, an attempt was made to register a YAML media type last year. See;

https://mailarchive.ietf.org/arch/search/?email_list=media-types&f_from=bjh21%40cam.ac.uk