[media-types] Proposed media type registration for YAML

[Ben Harris]

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 <yaml-***@lists.sourceforge.net>

Intended usage:

COMMON

Restrictions on usage:

N/A

Author:

Ben Harris, University of Cambridge <***@cam.ac.uk>

Change controller:

Ben Harris, University of Cambridge <***@cam.ac.uk>
on behalf of Oren Ben-Kiki <***@ben-kiki.org>, Clark Evans
<***@clarkevans.com>, and Ingy döt Net <***@ingy.net>

Provisional registration? (standards tree only):

N/A

[Martin J. Dürst]

Hello Ben,

Post by Ben Harris
Below is a media type registration I'm proposing to submit for YAML. I
* 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.

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.

Post by Ben Harris
text
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.

Post by Ben Harris
None
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.
binary
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.
N/A
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.
A wide variety of implementations are listed at <http://yaml.org>.
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.
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
COMMON
N/A
N/A
_______________________________________________
media-types mailing list
https://www.ietf.org/mailman/listinfo/media-types

[Ben Harris]

Post by Martin J. Dürst

Post by Ben Harris
Below is a media type registration I'm proposing to submit for YAML. I
* 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.

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.

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.

Post by Martin J. Dürst
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.

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.

Post by Martin J. Dürst

Post by Ben Harris
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?

[Ben Harris]

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

[Mark Baker]

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

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.

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.

[Ben Harris]

Post by Mark Baker
I concur with Martin's comments, and have one of my own...

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.

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?

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.