JSON and YAML solve overlapping problems — representing structured data as text — but they make very different trade-offs. JSON dominates APIs; YAML dominates configuration. Knowing the strengths and the surprising pitfalls of each helps you pick the right one and avoid some genuinely famous bugs.
Where JSON wins
JSON is strict, unambiguous and universally supported. Its rigid syntax — quotes, braces, no comments — makes it easy for machines to parse and hard to get subtly wrong. That strictness is exactly what you want for data exchange between systems, which is why it is the lingua franca of APIs.
Where YAML wins
YAML is built for humans to read and write. It uses indentation instead of braces, allows comments, and is far less noisy for large configuration files. This is why tools like Docker Compose, Kubernetes and CI pipelines use it — humans edit those files by hand, and readability matters more than machine strictness.
The YAML gotchas
- The "Norway problem" — the unquoted value no is interpreted as the boolean false, so a country code NO becomes false.
- Numbers with leading zeros may be read as octal.
- Indentation must use spaces, never tabs, and mistakes are easy to miss.
- Strings that look like dates or numbers get auto-converted unless quoted.
These quiet type coercions cause real outages. The defence is simple: quote any string that could be misread.
How to choose
Use JSON for data exchanged between programs and APIs, where strictness and ubiquity matter. Use YAML for configuration that humans write and read, accepting its quirks in exchange for readability and comments. And when you need to move between them, convert rather than hand-translate, since the structures map cleanly.