application/x-yaml YAML Common

What it's for

YAML (YAML Ain't Markup Language) is a human-readable data serialization format widely used for configuration files — Docker Compose, Kubernetes manifests, CI/CD pipeline definitions (GitHub Actions, GitLab CI), and countless application config files all commonly use YAML specifically for its clean, indentation-based, comment-friendly syntax compared to JSON's stricter, more verbose structure.

The MIME type situation for YAML is genuinely a bit messy: application/x-yaml has been the commonly used convention for years, but application/yaml (without the x- experimental prefix) was later registered as the more "correct" IANA type per RFC 9512. In practice, you'll see both in active use, and most YAML-consuming tools accept either without issue — this is one of the few MIME types on the web where there's a genuinely unsettled, evolving convention rather than one clearly correct answer.

Format & syntax

Content-Type: application/x-yaml
Content-Type: application/yaml

YAML's syntax uses significant whitespace/indentation to represent structure (similar in spirit to Python), supports comments (unlike JSON), and can represent the same fundamental data types JSON does (objects/maps, arrays/lists, strings, numbers, booleans, null) plus some YAML-specific features like anchors/references and multi-document files.

How it's used in practice

• Infrastructure and DevOps configuration — Docker Compose files, Kubernetes manifests, Ansible playbooks, and CI/CD pipeline definitions (GitHub Actions workflows, GitLab CI, CircleCI) are overwhelmingly authored in YAML, making it one of the most-encountered formats in modern DevOps and infrastructure work.
• Application configuration files — many application frameworks and tools use YAML for configuration (some Laravel packages, Symfony's configuration system, and many others) specifically for its readability advantage over JSON for hand-edited config.
• API responses in YAML-preferring contexts — some APIs support returning YAML as an alternative to JSON via content negotiation, though this is a distinctly smaller use case than YAML's dominance in configuration file contexts.
• Documentation and static site generator frontmatter — many static site generators and content systems use YAML frontmatter (a YAML block at the top of a Markdown file) for page metadata, a very common pattern in modern content-driven site architectures.

Common mistakes & gotchas

• Whitespace/indentation errors breaking parsing silently or confusingly — YAML's significant-whitespace syntax means inconsistent indentation (mixing tabs and spaces, or simply miscounting spaces) is one of the most common sources of YAML parsing errors, and error messages can sometimes point to a confusing location relative to where the actual mistake is.
• YAML's implicit type coercion causing unexpected values — YAML automatically interprets certain unquoted strings as other types (yes/no/true/false as booleans, numbers without quotes as actual numbers), which has caused real, well-documented bugs — the classic example being country code "NO" (Norway) being interpreted as boolean false if left unquoted in certain YAML parsers, a famous enough issue it has its own nickname ("Norway problem") in YAML circles.
• Not knowing which MIME type convention a given tool expects — given the application/x-yaml vs application/yaml split, it's worth checking what a specific API or tool actually expects rather than assuming, since some strict implementations may only recognize one of the two.
• Assuming YAML and JSON are always trivially interchangeable — while YAML is technically a superset of JSON in terms of what it can represent (valid JSON is actually valid YAML), YAML's additional features (anchors, multi-document files, implicit typing) mean round-tripping between the two formats isn't always perfectly lossless or straightforward in every direction.

Comparison & FAQ

Should I use application/x-yaml or application/yaml?

There's genuine inconsistency in practice — application/yaml is the more recently, formally IANA-registered type (RFC 9512), while application/x-yaml remains widely used from convention. Check what your specific consuming tool or API expects if it matters for your use case; many tools accept either.

Why did my YAML config file misinterpret a value unexpectedly?

Check for YAML's implicit type coercion — unquoted values like yes, no, true, false, or bare numbers get automatically interpreted as their respective types rather than staying as strings, which is a well-known source of surprising bugs (quote values explicitly if you want them treated as plain strings).

Is YAML just JSON with different syntax?

Not exactly — while valid JSON happens to also be valid YAML (a genuinely useful compatibility property), YAML adds its own additional features (comments, anchors/references, multi-document files, implicit type coercion) that don't have direct JSON equivalents, so the two aren't perfectly interchangeable in every direction.

Why is YAML so dominant in DevOps/infrastructure tooling specifically?

Its comment support and cleaner, less verbose syntax compared to JSON make it noticeably more pleasant for humans to hand-write and review configuration files, which matters a lot in infrastructure-as-code and CI/CD contexts where config files are frequently read and edited directly by engineers.