160

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
  • 30,436
  • 41
  • 178
  • 315
Jon Cram
  • 16,609
  • 24
  • 76
  • 107

9 Answers9

98

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
  • 26,737
  • 24
  • 105
  • 146
Vinko Vrsalovic
  • 330,807
  • 53
  • 334
  • 373
  • 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
  • 98
    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
  • 10
    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
  • `application/yaml` seems to be the future: https://stackoverflow.com/a/72362686/4136669 – Fabian S. May 25 '22 at 10:17
36

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
  • 26,737
  • 24
  • 105
  • 146
djb
  • 4,930
  • 1
  • 34
  • 37
  • 17
    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
  • 2
    The proposal has been updated to application/yaml. They are deprecating text/yaml and 'x-' is discouraged. But text/yaml causes the browser to display instead of download, so I think they're wrong to deprecate that media type. – carlin.scott Nov 23 '22 at 18:35
  • There is also a proposal for `application/yaml`: https://www.ietf.org/archive/id/draft-ietf-httpapi-yaml-mediatypes-00.html#name-media-type-application-yaml – Adam B May 10 '23 at 19:29
19

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
  • 27,717
  • 28
  • 128
  • 190
Greg
  • 316,276
  • 54
  • 369
  • 333
  • 1
    It's human readable but its intent is to communicate applications... XML is under application – Vinko Vrsalovic Dec 01 '08 at 20:54
  • And also under text. It seems you'd have to have both text/x-yaml and application/x-yaml... http://www.rfc-editor.org/rfc/rfc3023.txt – Vinko Vrsalovic Dec 01 '08 at 20:56
  • For what it's worth, this is what Django's TastyPie REST implementation understands. – Michael Scheper Mar 03 '17 at 17:36
  • 3
    ... but isn't JSON human readable, too? I think it would be more consistent to say `application/yaml`, just as we might say `application/json` and `applicaiton/xml`. – Anthony Rutledge Nov 19 '19 at 03:11
  • @AnthonyRutledge - JSON is readable in the same was that assembler code in hex is - very painfully (certainly in comparison to YAML). I'd say the same is true of XML. YAML is very widely used for config files precisely because its easy to read and write bu humans. – dsz Apr 13 '23 at 05:55
18

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

Giulio
  • 469
  • 5
  • 15
11

The IETF is working to register the application/yaml media type and the +yaml structured syntax suffix.

Currently, we are not registering text/yaml. https://github.com/ietf-wg-httpapi/mediatypes/blob/main/draft-ietf-httpapi-yaml-mediatypes.md

Feel free to participate in the discussion.

Roberto Polli
  • 701
  • 7
  • 10
10

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

Community
  • 1
  • 1
Julian Reschke
  • 40,156
  • 8
  • 95
  • 98
  • So that would be `application/vnd.yaml` or `text/vnd.yaml` (text seems better) – wires Nov 21 '15 at 16:01
  • 5
    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

I'm unsure whether to post this as an answer or as a comment to another answer. (Posting as separate answer as it's rather long.) However, I was wondering the same thing and I searched the IANA listing.

There's currently (2023-05-13) a draft entry for registering YAML in the IANA listing. Registering it under the mime-type:

application/yaml

However, it's not been added yet and I do not know how long the rest of the process is going to last.

Draft 06 IANA state:

IANA review state:
  Version Changed - Review Needed

IANA expert review state:
  Need IANA Expert(s)

Where: Review Needed, means: Document has not yet been reviewed by IANA. [ review-state ]

Update (2023-06-06)

Draft 07 Review State changed to:

IANA review state               IANA OK - Actions Needed
IANA action state               In Progress
IANA expert review state        Expert Reviews OK

Where IANA OK - Actions Needed, means: Document requires IANA actions, and the IANA Considerations section indicates the details of the actions correctly. and, In Progress means: IANA is currently processing the actions for this document and, Expert Reviews OK means: All expert reviews have been completed with no blocking issues.

I.e. seems like we'll get a media-type before the end of this year (2023).

Byebye
  • 934
  • 7
  • 24
0

I read this after similar really interesting conversation related to about MIME type for TOML file format.

application/* vs text/*

From RFC (https://tools.ietf.org/html/rfc2046#section-3)

Other subtypes are to be used for enriched text in forms where application software may enhance the appearance of the text, but such software must not be required in order to get the general idea of the content. Possible subtypes of "text" thus include any word processor format that can be read without resorting to software that understands the format.

From comment https://github.com/toml-lang/toml/issues/465#issuecomment-306231107

Based on that, I think subtypes of text is intended to be used more for unstructured (but possibly formatted) text, whereas application seems to be more appropriate for structured data, like TOML. While TOML emphasizes human-readability, it's still primarily a data format, intended to be read by applications. As a contrast, a markdown file (text/markdown) conveys its full meaning without being processed further by an application, whereas a TOML files are generally meaningless outside of the context of the application they are configuring.

We can say the same about YAML format so personally I would prefer application/*.

Another argument for application/* is that YAML is a superset of JSON and MIME type application/json is used for JSON.

application/yaml vs application/x-yaml

Unless the MIME type has officially been registered (assuming that anyone even plans to do that), application/x-* should be used.

Since YAML (as well as TOML) is not registred officially it's better to use x- prefix so we have application/x-yaml as a result.

Interesting fact: TOML official docs suggest using application/toml even if it's not official yet. But not everyone thinks that this is a right decision.

Postman uses application/x-yaml

Just another reason to use such MIME type :) Postman uses application/x-yaml

Max Starling
  • 967
  • 8
  • 8
-1

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

The Godfather
  • 4,235
  • 4
  • 39
  • 61