165

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

9 Answers 9

99

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.

9
  • 102
    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. Oct 13, 2011 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 5, 2015 at 19:44
  • 4
    @RyanParman Not true. 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 6, 2016 at 10:04
  • 10
    RFC 3023, including the encoding handling has been obsoleted in 2014 by 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 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 8, 2016 at 0: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 8, 2016 at 0:58
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 :-)

3
  • 17
    It seems that proposal as gone nowhere as of Jan 2018, and my attempts to contact the author have gone unanswered
    – djb
    Jan 4, 2018 at 13:32
  • 3
    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. Nov 23, 2022 at 18:35
  • 1
    There is also a proposal for application/yaml: ietf.org/archive/id/…
    – Adam B
    May 10, 2023 at 19:29
20

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.

5
  • 1
    It's human readable but its intent is to communicate applications... XML is under application
    – Vinko Vrsalovic
    Dec 1, 2008 at 20:54
  • And also under text. It seems you'd have to have both text/x-yaml and application/x-yaml... rfc-editor.org/rfc/rfc3023.txt
    – Vinko Vrsalovic
    Dec 1, 2008 at 20:56
  • For what it's worth, this is what Django's TastyPie REST implementation understands. Mar 3, 2017 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. Nov 19, 2019 at 3: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, 2023 at 5:55
19

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

0
13

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.

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.

2
1

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

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.

Update (2024-01-30)

Currently in draft version 10, not moving as fast as I had expected, fingers crossed for a registration in 2024.

-1

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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.