ComparisonData formats
JSON vs YAML
JSON vs YAML for config files and APIs: which is easier to read, which is safer to parse, and when to use each.
Last updated
The short answer
JSON is the safer default for anything machines write and parse — APIs, saved app state, data interchange between services. YAML is worth its extra risk only for files humans hand-edit often, like CI configs, provided everyone remembers to quote values that look like booleans or numbers.
| Dimension | JSON | YAML |
|---|---|---|
| Comments | Not supported | # comments allowed |
| Whitespace | Irrelevant | Significant — indentation is structure |
| Parsing speed | Fast, simple grammar | Slower, far larger spec |
| Data types | Strings, numbers, bool, null | Same, plus dates, anchors, multi-doc |
| Failure mode | Fails loud on a syntax error | Can silently misparse (Norway problem) |
| Best for | APIs, saved app state | Hand-edited config, CI files |
Choose JSON when
- →You're serializing data between programs — an API response, a database export, anything a machine writes and another machine reads.
- →You need every mainstream language to parse it the same way with zero ambiguity.
- →The file is generated, not hand-typed, so YAML's readability advantage doesn't apply.
Choose YAML when
- →Humans edit the file directly and often — Kubernetes manifests, GitHub Actions workflows, docker-compose.yml.
- →You need comments explaining why a value is set the way it is.
- →You want anchors and references (&, *) to avoid repeating the same block twice.
The catch nobody mentions
YAML's famous 'Norway problem': an unquoted NO (Norway's ISO country code) parses as the boolean false under YAML 1.1, and short tokens like no, on, off and yes still trip up parsers that keep that behavior. Always quote string-typed values that happen to look like booleans, numbers, or dates.