What is YAML?
YAML ("YAML Ain't Markup Language") is a human-friendly data serialisation format used extensively for configuration files. It's designed to be readable without the visual clutter of braces, brackets, and quotes that JSON requires. Indentation defines structure, making well-written YAML look almost like an outline.
YAML is the configuration language of choice for Docker Compose, Kubernetes, GitHub Actions, Ansible, Swagger/OpenAPI, and countless other DevOps and CI/CD tools. It's technically a superset of JSON — any valid JSON document is also valid YAML — but in practice, YAML files look nothing like JSON.
The trade-off for YAML's readability is fragility: it's whitespace-sensitive, has surprising type coercion rules, and small indentation errors can completely change the document's structure without producing a parse error.
YAML gotchas
The Norway problem. YAML 1.1 coerces bare values like NO, yes, on, and off into booleans. The string "NO" (as in Norway's country code) becomes false. Always quote strings that could be misinterpreted: "NO".
Indentation sensitivity. YAML uses spaces (never tabs) for indentation, and the indentation level defines the document's structure. A single extra or missing space can move a value to the wrong level in the hierarchy — sometimes without causing a parse error, producing a silently incorrect document.
Tabs are forbidden. Unlike Python (which accepts both), YAML explicitly forbids tab characters for indentation. If your editor inserts tabs, your YAML will fail to parse. Always configure your editor to use spaces for YAML files.
Implicit type coercion. Beyond booleans, YAML aggressively coerces types: 1.0 becomes a float, 010 becomes octal (8 in decimal), and timestamps like 2026-04-15 become date objects. If you mean a string, quote it. When in doubt, quote it.
Multiline strings. YAML has multiple multiline string syntaxes (| for literal blocks, > for folded blocks) with subtle differences in how trailing newlines are handled. The | block preserves newlines exactly; > folds them into spaces. The - and + suffixes control the final trailing newline.