Readable by design
YAML was created to be pleasant for people to read and write, and it largely succeeds. Nesting is shown by indentation, lists by leading dashes, and mappings by a key followed by a colon and a value — so a configuration file reads almost like an outline. Comments are allowed, long strings can be folded across lines, and you can reference repeated chunks with anchors and aliases to avoid duplication. This comfort is why Docker Compose, Kubernetes manifests, GitHub Actions and other CI systems, and Ansible playbooks are all written in YAML rather than something more rigid.
Because YAML 1.2 is designed as a superset of JSON, any valid JSON document is also valid YAML, which makes the two easy to interchange. But the friendliness has a cost: the format is large and subtle, with several ways to express the same thing, and full parsers are correspondingly complex. For configuration that complexity is usually invisible, which is exactly why the sharp edges catch people out.
The famous pitfalls
Two traps account for most YAML grief. The first is significant whitespace: indentation defines structure, tabs are forbidden as indentation, and a single misaligned space can silently change which block a value belongs to or cause a parse error with an unhelpful message. The second is aggressive type coercion. An unquoted value that looks like a number or a boolean becomes one, so the country code for Norway, written as the word no, can be read as the boolean false — the notorious “Norway problem”. Strings such as yes, on, off and version-like numbers can be reinterpreted the same way. The defence is simple once you know it: quote any string whose meaning matters, and treat indentation with the same care you would give code.
Strengths
- Genuinely readable, with comments, multi-line strings and reusable anchors.
- A superset of JSON, so it interoperates with the wider JSON ecosystem.
- Concise — no closing brackets or quotation noise for everyday config.
- The de facto standard for container, CI and automation tooling.
Limitations
- Significant whitespace makes indentation errors easy and confusing.
- Implicit type coercion can turn strings into booleans or numbers unexpectedly.
- The full specification is large and parsers vary in what they accept.
- Tabs are not allowed for indentation, a frequent surprise.
When to use YAML
Choose YAML for human-edited configuration — infrastructure manifests, pipelines and application settings — where readability and comments matter more than machine strictness.
YAML FAQ
- What is the difference between YAML and JSON?
- YAML aims at human authoring with indentation, comments and looser syntax, while JSON is a stricter, bracket-based format aimed at machines. Since YAML 1.2 is a superset of JSON, valid JSON is valid YAML, but YAML adds features — and pitfalls — that JSON does not have.
- Why does my YAML break on indentation?
- Almost always because of mixed tabs and spaces, or a value indented to the wrong level. YAML forbids tabs for indentation and uses spacing to define structure, so a single stray space can change the meaning; align everything with spaces and keep nesting consistent.
- Why did my value no or yes become true or false?
- That is the type-coercion trap — unquoted words like no, yes, on and off are read as booleans. Wrap any such value in quotes when you mean it as text, for example a country code or a plain answer.