129

What is the most appropriate media type (formally MIME type) to use when sending data structured with YAML over HTTP and why?

There is no registered application type or text type that I can see.

Example:

> GET /example.yaml

< Content-Type: ????
<
< --- # Favorite movies
< - Casablanca
< - North by Northwest
< - Notorious

Possible options:

  • text/x-yaml
  • text/yaml
  • text/yml
  • application/x-yaml
  • application/x-yml
  • application/yaml
  • application/yml
Dave Jarvis
  • 28,853
  • 37
  • 164
  • 291
Jon Cram
  • 15,309
  • 21
  • 72
  • 105

6 Answers6

79

Ruby on Rails uses application/x-yaml with an alternative of text/yaml (source).

I think it's just a matter of convention, there is no technical why, as far as I can tell.

Martin Tournoij
  • 23,567
  • 24
  • 90
  • 127
Vinko Vrsalovic
  • 244,143
  • 49
  • 315
  • 361
  • Weird, google for "yaml mime" gives a ruby link as the first hit, with text/x-yaml and no mention of application/x-yaml – Greg Dec 01 '08 at 20:53
  • 88
    This isn't _quite_ true. Mime types that start with `text/` are to be processed as ISO-8859-1 unless another mime type is explicitly declared (e.g. `text/html; charset=utf-8`). Mime types that start with `application/` are processed as UTF-8 unless another mime type is explicitly declared. For example, `text/x-yaml` cannot use UTF-8 characters while `text/x-yaml; charset=utf-8` and `application/x-yaml` can. IIRC, this is defined in RFC 3023. – Ryan Parman Oct 13 '11 at 21:16
  • 3
    @RyanParman You're confusing character set and MIME type a bit. You're right that `text/*`, without an explicit `charset=` parameter is presumed to be ISO-8859-1, but things in `application/*` aren't necessarily text. (The RFC you linked is about XML, not sure how it is relevant.) – Thanatos Feb 05 '15 at 19:44
  • 4
    @RyanParman Not true. https://tools.ietf.org/html/rfc6838#section-4.2.1 says: `If a "charset" parameter is specified, it SHOULD be a required parameter, eliminating the options of specifying a default value. If there is a strong reason for the parameter to be optional despite this advice, each subtype MAY specify its own default value, or alternatively, it MAY specify that there is no default value. Finally, the "UTF-8" charset [RFC3629] SHOULD be selected as the default.`. There is no formal definition of `text/yaml` nor `text/x-yaml`, so the default is UTF-8. – aef May 06 '16 at 10:04
  • @Thanatos: You're right. I understood that, but I failed to explain that adequately. – Ryan Parman May 07 '16 at 16:59
  • @aef: I know that RFC 3023 is about XML, but I had understood that all file types under the "text" mime type group were implicitly treated as ISO-8859-1. The same is true for text/plain and text/javascript. My impression was that it also applied to text/yaml as well. – Ryan Parman May 07 '16 at 17:04
  • 9
    RFC 3023, including the encoding handling has been obsoleted in 2014 by https://tools.ietf.org/html/rfc7303#section-3. The rule to default to `US-ASCII` (note: not `ISO-8859-1`) for `text/*` media types in RFC 2046 has been obsoleted by `Regardless of what approach is chosen, all new text/* registrations MUST clearly specify how the charset is determined; relying on the US-ASCII default defined in Section 4.1.2 of [RFC2046] is no longer permitted.` in https://tools.ietf.org/html/rfc6838#section-4.2.1 in January 2013. Neither RFC 3023 nor RFC 7303 say anything generic about `text/*` AFAIK. – aef May 08 '16 at 00:45
  • 6
    @RyanParman So your conclusion was probably correct back then but you mistakenly referenced RFC 3023, while the rule came from RFC 2046. Today however, `UTF-8` is the default for every `text/*` media type that doesn't state something different in its IANA registration. – aef May 08 '16 at 00:58
25

Although another answer was accepted, please refer to this Proposed media type registration for YAML thread on the IANA mailing list for reviewing Media Type in which Ben Harris, University of Cambridge Information Services, proposed in July 2015 on behalf of the YAML team the media type:

text/vnd.yaml

with (suggested) deprecated aliases:

text/yaml
text/x-yaml
application/x-yaml

That is still proposed/pending (the thread does not indicate status of the proposal) so this answer is no more definitive than the others :-)

Martin Tournoij
  • 23,567
  • 24
  • 90
  • 127
djb
  • 4,569
  • 1
  • 31
  • 35
  • 15
    It seems that proposal as gone nowhere as of Jan 2018, and my attempts to contact the author have gone unanswered – djb Jan 04 '18 at 13:32
18

I'd say text/x-yaml:

text over application because it's a human-readable

x-yaml over yaml because it hasn't been accepted into the registered list of mime types.

Edit: from RFC 3023 (XML Media Types):

The top-level media type "text" has some restrictions on MIME entities and they are described in [RFC2045] and [RFC2046]. In particular, the UTF-16 family, UCS-4, and UTF-32 are not allowed (except over HTTP[RFC2616], which uses a MIME-like mechanism).

Interesting... Not exactly sure what it means, but food for thought.

Liam
  • 22,818
  • 25
  • 93
  • 157
Greg
  • 295,929
  • 52
  • 357
  • 326
12

On Chrome application/yaml will download, while text/yaml will display.

Giulio
  • 182
  • 2
  • 12
9

"x-" media types are discouraged, see RFC 4288, Section 3.4. The right thing to do is to use the personal tree, the vendor tree, or to actually attempt a proper media type registration.

Julian Reschke
  • 35,455
  • 7
  • 78
  • 83
  • So that would be `application/vnd.yaml` or `text/vnd.yaml` (text seems better) – wires Nov 21 '15 at 16:01
  • 3
    Not entirely true as well. The only subtype tree which is intended for use without registration with IANA is `x.`. `vnd.` and `prs.` require registration. See https://tools.ietf.org/html/rfc6838#section-3.2 and https://tools.ietf.org/html/rfc6838#section-3.3 . – aef May 06 '16 at 16:18
1

As per MIME Types list it's text/yaml, even though it's not in official IANA MIME list

The Godfather
  • 3,138
  • 2
  • 33
  • 49