YAML MIME Type – Free, Online, Private

What .yaml is

YAML is a data language with indentation, anchors, and more than one document per stream, separated by a line of three dashes. A file may start with --- or directly with a mapping. It is easy to read and easy to turn into a different structure than the author intended, because Norway's country code and the word yes have a history of becoming booleans. RFC 9512 registers application/yaml. The older unofficial values are text/yaml and application/x-yaml. .yml is the same format with a shorter extension. Map both if you accept both. This page is the .yaml spelling.

IANA registers application/yaml in RFC 9512. .yml is the other common extension and is the same type. The media type is application/yaml. Extensions that use it on this page: .yaml. A client compares the type, not the filename, once the response has arrived. The filename still matters on disk and in Content-Disposition, which is why a wrong extension and a wrong header are two different bugs.

What sends application/yaml

What sends application/yaml: Send application/yaml; charset=utf-8 for a document you want a client to parse as YAML. Kubernetes manifests, GitHub Actions workflows, and OpenAPI documents are often YAML on disk and JSON on the wire. If your API returns JSON, the response is application/json even when the source file was YAML. Do not label a JSON body as application/yaml. A client that runs a YAML parser will accept a JSON subset and may also accept anchors you did not mean to allow. If you do not want anchors and custom tags, parse with a safe loader or publish JSON. The file on disk is still .yaml. Once the response exists, a client trusts application/yaml, not the filename. OpenAPI can be YAML or JSON. The HTTP response type tells the client which parser to run. A documentation site that statically serves openapi.yaml should send application/yaml. A gateway that converts the file to JSON should send application/json and a different URL, so caches do not mix them.

Content-Type for .yaml

Send application/yaml; charset=utf-8. The charset parameter names the encoding of the body. Leaving it off forces the client to guess, and for several text types the registered default is not UTF-8. Do not send a charset on a redirect. The header belongs on the response that contains the bytes.

Content-TypeContent-Type: application/yaml; charset=utf-8

nginx, Apache, and Express

These snippets map .yaml to application/yaml. nginx reads the types block when it picks a type from the URL's extension. A location that sets default_type, or an application that sets the header itself, overrides that map. Apache AddType applies in the directory context where you put it. The Express static example writes the header for files ending in .yaml so a stale mime database in the framework cannot disagree with the type on this page.

nginx# /etc/nginx/mime.types, inside the types { } block
application/yaml            yaml;
charset utf-8;
charset_types application/yaml;

ApacheAddType application/yaml .yaml
AddCharset UTF-8 .yaml

Expressimport express from "express";

const app = express();
app.use(express.static("public", {
  setHeaders(res, filePath) {
    if (filePath.endsWith(".yaml")) {
      res.setHeader("Content-Type", "application/yaml; charset=utf-8");
    }
  },
}));

Pitfalls for application/yaml

Pitfalls that show up for application/yaml, and not for a neighboring type with a similar extension: A safe-load versus a full load is the security boundary. Full loaders have executed arbitrary objects from tags. The Content-Type will not select the safe loader. Another trap is indentation that changed when a proxy reformatted the body as HTML. Serve the bytes unmodified. Another is a multi-document stream fed to a parser that returns only the first document and reports success. Say when you emit more than one. A fourth is tabs used for indentation. YAML forbids tabs in indentation. The file is then invalid, and the type being correct does not help.

• text/yaml and application/x-yaml are unofficial. RFC 9512's type is application/yaml.
• .yml and .yaml should be one types line: application/yaml yaml yml.
• A JSON file is valid YAML 1.2 in the JSON subset. Calling it application/yaml is still a contract change.
• Custom tags such as !!python are a reason to reject the document, not a reason to change the media type.