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.
Questions
Is YAML really a superset of JSON?
Since YAML 1.2, yes — any valid JSON document is valid YAML, so a YAML parser will read your JSON. The reverse is not true, and plenty of parsers in the wild still implement 1.1, where the compatibility is imperfect.
What is the Norway problem?
In YAML 1.1, the unquoted values NO, ON, OFF, YES and Y are booleans, so a country list containing NO for Norway silently becomes false. YAML 1.2 removed that, but many widely used parsers still behave the old way — quote your strings.
Why does JSON not support comments?
Douglas Crockford removed them deliberately, having seen people put parsing directives in them. It is the most-requested missing feature, and the usual workarounds are a dummy key or a format like JSON5 that is not JSON.
Is YAML safe to parse from untrusted input?
Not by default in several languages. PyYAML's load can construct arbitrary Python objects and has been a real remote-code-execution vector; safe_load exists for that reason. Treat YAML from outside your system as executable until proven otherwise.
Which should a config file use?
YAML when humans edit it often and comments matter, JSON when a machine writes it and exactness matters. The significant whitespace that makes YAML readable is also what makes a merge conflict in it genuinely dangerous.
What about TOML?
It occupies the middle ground — comments and readability without significant whitespace — and is the default for Rust and modern Python packaging. Worth considering when the choice is genuinely open rather than dictated by an existing ecosystem.