What Is YAML? Configuration File Format Explained
YAML (YAML Ain't Markup Language, recursively) is a human-readable data serialisation format heavily used for configuration files in software: Docker Compose, Kubernetes manifests, GitHub Actions workflows, Ansible playbooks, and many others. It is a superset of JSON, meaning valid JSON is valid YAML.
Core YAML Syntax
Mappings (objects): key: value pairs, one per line. Sequences (arrays): lines starting with - . Nesting via indentation (2 spaces is convention). Strings need no quotes unless they contain special characters. Multiline strings: | (literal block, preserves newlines) or > (folded block, newlines become spaces). Anchors (&name) and aliases (*name) avoid repetition. Comments start with #.
YAML Pitfalls
The Norway Problem: the two-letter ISO code 'NO' is parsed as the boolean false in YAML 1.1. Other surprise booleans: yes, no, true, false, on, off. YAML 1.2 (used by most modern tools) restricts booleans to true/false. Indentation errors are silent and hard to debug. Duplicate keys: allowed by spec but ambiguous — most parsers use the last value. Always quote strings that look like YAML special values.
YAML vs JSON vs TOML
JSON: strict syntax, no comments, excellent for APIs and data interchange. YAML: comments allowed, more readable for humans, complex due to implicit typing. TOML: designed for config files, explicit scalar types, no indentation-based nesting, less flexible than YAML but very predictable. For config files, YAML and TOML are both good choices; JSON is better for API payloads.