Subject: [media-types] Proposed media type registration for YAML

From: Ben Harris <[email-masked]>
Date: Tue, 7 Jul 2015 15:33:55 +0100 (BST)

Below is a media type registration I'm proposing to submit for YAML.  I 
have one specific question for the list:

* Is it appropriate to use a "text/*" type for something that might be 
encoded in UTF-16 or UTF-32?  I'm confident that YAML in UTF-8 fits the 
line-break requirements of RFC 2046, but I'm not sure whether that permits 
UTF-16 or UTF-32.

    Type name:

text

    Subtype name:

vnd.yaml

    Required parameters:

None

    Optional parameters:

There is a single optional parameter, "version", whose value MUST match 
the ns-yaml-version production in YAML 1.1 or YAML 1.2.  If provided, it 
identifies a version of the YAML specification to which the corresponding 
entity conforms.

The "charset" parameter is not used: The YAML specifications define how a 
YAML processor should determine whether a YAML stream is encoded in UTF-8, 
UTF-16, or UTF-32.

    Encoding considerations:

binary

    Security considerations:

Interpreting arbitrary YAML can be dangerous.  Many YAML processors are 
able to serialise and deserialise arbitrary objects in their host 
programming language, which can include arbitrary executable code. 
Applications consuming YAML from untrusted sources MUST restrict the range 
of object types that can be deserialised to those that are safe.

YAML allows for the construction of complex data structures, including 
cyclic ones.  This can create structures that simple reference-counting 
garbage collectors cannot collect when they become unreferenced.  YAML 
consumers using such garbage collectors may need to record which 
references were generated using aliases and to break those references 
before allowing the structure to become unreferenced.

    Interoperability considerations:

N/A

    Published specification:

YAML Ain’t Markup Language (YAML™) Version 1.2, 
http://yaml.org/spec/1.2/spec.html
YAML Ain’t Markup Language (YAML™) Version 1.1, http://yaml.org/spec/1.1/
YAML Ain't Markup Language (YAML™) 1.0, http://yaml.org/spec/1.0/

In each case, a text/vnd.yaml entity is a complete YAML stream, which 
might potentially contain multiple YAML documents.

    Applications that use this media type:

A wide variety of implementations are listed at <http://yaml.org>.

    Fragment identifier considerations:

Fragment identifiers are reserved for future standardisation.  While 
having them refer to YAML anchor names is tempting, those are deliberately 
not unique within a stream and hence would not make good fragment 
identifiers.

    Additional information:

      Deprecated alias names for this type: N/A
      Magic number(s): N/A
      File extension(s): .yaml  .yml
      Macintosh file type code(s): N/A

    Person & email address to contact for further information:

YAML mailing list <[email-masked]>

    Intended usage:

COMMON

    Restrictions on usage:

N/A

    Author:

Ben Harris, University of Cambridge <[email-masked]>

    Change controller:

Ben Harris, University of Cambridge <[email-masked]>
on behalf of Oren Ben-Kiki <[email-masked]>, Clark Evans 
<[email-masked]>, and Ingy döt Net <[email-masked]>

    Provisional registration? (standards tree only):

N/A

-- 
Ben Harris, University of Cambridge Information Services.

---

From: "Martin J. Dürst" <[email-masked]>
Date: Tue, 14 Jul 2015 14:00:42 +0900

Hello Ben,

On 2015/07/07 23:33, Ben Harris wrote:
> line-break requirements of RFC 2046, but I'm not sure whether that
> permits UTF-16 or UTF-32.

The answer is "it depends". For more details, see e.g.
http://tools.ietf.org/html/rfc7303#section-9.2 (or rather actually 
http://tools.ietf.org/html/rfc7303#section-9.1) or the somewhat older 
http://tools.ietf.org/html/rfc3023#section-8.2.

Because YAML is only rarely used to transmit actual human-readable prose 
(as opposed to structured data in textual form), a top-level type of 
application/, with less restrictions, may be much more appropriate.
That's the conclusion XML came to, after many years and some detours.

> vnd.yaml

I wonder whether the vnd. prefix here is really appropriate. YAML isn't 
a company in any way. Ideally, something like YAML should just be 
text/yaml (or actually application/yaml, see above). The spec at e.g. 
http://yaml.org/spec/1.2/spec.html definitely looks very detailed and 
well worked out, although I can't speak for the actual quality.

Regards,   Martin.

> identifies a version of the YAML specification to which the
> corresponding entity conforms.
>
> The "charset" parameter is not used: The YAML specifications define how
> a YAML processor should determine whether a YAML stream is encoded in
> UTF-8, UTF-16, or UTF-32.
>
>     Encoding considerations:
>
> binary
>
>     Security considerations:
>
> Applications consuming YAML from untrusted sources MUST restrict the
> range of object types that can be deserialised to those that are safe.
>
> having them refer to YAML anchor names is tempting, those are
> deliberately not unique within a stream and hence would not make good
> fragment identifiers.
>
>     Additional information:
>
> _______________________________________________
> media-types mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/media-types
>

---

From: Mark Baker <[email-masked]>
Date: Wed, 15 Jul 2015 08:49:25 -0400

I concur with Martin's comments, and have one of my own...

On Tue, Jul 7, 2015 at 10:33 AM, Ben Harris <[email-masked]> wrote:
>    Optional parameters:
>
> There is a single optional parameter, "version", whose value MUST match the
> ns-yaml-version production in YAML 1.1 or YAML 1.2.  If provided, it

In general, versioning and similar mechanisms don't belong in a
parameter because the media type itself is a compatibility statement,
i.e. it serves as a name given to a series of largely compatible
formats. Do you have a use case for it?

Mark.

---

From: Ben Harris <[email-masked]>
Date: Wed, 15 Jul 2015 17:24:31 +0100 (BST)

> formats. Do you have a use case for it?

I don't think I currently have a use case for the "version" parameter. 
I've never noticed any YAML libraries' having any means to select the 
version of YAML that they produce, so I doubt it would be of any use for 
content negotiation.  I'll remove it from the next draft.

-- 
Ben Harris, University of Cambridge Information Services.  Tel: (01223) 334728

---

From: Ben Harris <[email-masked]>
Date: Wed, 15 Jul 2015 18:40:44 +0100 (BST)

> http://tools.ietf.org/html/rfc3023#section-8.2.

I think that's slightly helpful, as is the sentence "See [RFC2046] for 
additional information on the restrictions MIME imposes." from RFC 6838. 
That suggests that, possibly with some extra notes about using only UTF-8 
with MIME, permitting UTF-16 and UTF-32 would be tolerable.

> Because YAML is only rarely used to transmit actual human-readable prose (as 
> opposed to structured data in textual form), a top-level type of 

The highest-priority design goal for YAML is stated to be "YAML is easily 
readable by humans" (YAML 1.2 section 1.1). So while not designed to 
transmit prose, it is designed to transmit human-readable data.  My 
experience is that even machine-generated YAML is generally more readable 
than XML, JSON, or CSV.

>>     Subtype name:
>> 
>> vnd.yaml
>
> I wonder whether the vnd. prefix here is really appropriate. YAML isn't a 
> company in any way. Ideally, something like YAML should just be text/yaml (or 
> actually application/yaml, see above). The spec at e.g. 
> http://yaml.org/spec/1.2/spec.html definitely looks very detailed and well 
> worked out, although I can't speak for the actual quality.

I would much prefer to be able to use the standards tree rather than the 
vendor tree, but RFC 6838 doesn't make this easy.  In the vendor tree, 
third-party registrations are explicitly permitted and "vendor" is 
described as being "construed very broadly", which I think is enough to 
let me register this type on behalf of the YAML authors.  The standards 
tree, on the other hand, would either require me to write an RFC or 
require the YAML authors to submit the request themselves and to be 
approved as a "standards-related organization" by the IESG.

I'll see if I can find a way to make either of the standards-tree routes 
work.  Is there any guidance (or history) on what the IESG considers to be 
a standards-related organization?

---

From: Ben Harris <[email-masked]>
Date: Wed, 15 Jul 2015 18:53:17 +0100 (BST)

On Tue, 14 Jul 2015, Chris Rebert wrote:

> (My apologies for replying off-list like this. I wasn't yet a
> subscriber when you posted your message, so I can't reply to it
> on-list properly. However, feel free to publicly reference or quote
> from this reply.)
>
> Based on YAML's entry in the de facto *nix MIME types database
> (http://cgit.freedesktop.org/xdg/shared-mime-info/tree/freedesktop.org.xml.in
> ), you might consider including the following among the list of
> deprecated aliases:
>
> * application/x-yaml
>
> * text/yaml
> * text/x-yaml

Thanks.  I'll add them.  While they're listed as "YAML document", I doubt 
the author was considering the technical distinction between a YAML 
document and a YAML stream when writing that.