JSON vs YAML: what is the difference
Use JSON when machines talk to machines, and YAML when humans write config. JSON is the de facto interchange format — fast to parse and supported natively everywhere. YAML expresses nesting through indentation, which reads and writes much better, but one misplaced space breaks the parse. The two convert losslessly in either direction.
Key differences
| Aspect | JSON | YAML |
|---|---|---|
| Readability | Fair — dense with brackets | Good — close to natural language |
| Comments | Not supported | Supported with # |
| Parse speed | Fast, native JSON.parse | Slower, needs an extra library |
| Language / tool support | Native on every platform | Needs a YAML package in most languages |
| Risk of breaking | Low — structure is explicit | High — sensitive to indentation and tabs |
| Typical use | API payloads, logs, storage | Kubernetes / CI / Docker Compose config |
JSON
JSON grew out of JavaScript object literals and is now the de facto standard for data interchange. Its structure is fully defined by brackets and commas — indentation is irrelevant — which makes machine generation and parsing extremely stable, and every browser ships JSON.parse natively. The trade-off is verbosity: no comments, and trailing commas will bite you when writing by hand.
YAML
YAML expresses hierarchy with indentation and dashes, dropping almost all brackets. It reads and writes noticeably better and supports comments, which is exactly why Kubernetes, GitHub Actions and Docker Compose all chose it. The trade-off is indentation sensitivity: a single wrong space or a stray tab fails the parse, and most languages need an extra dependency.
How to choose
- API responses, service-to-service transport, log storage → JSON
- Config that humans edit often and need to annotate → YAML
- Inside the K8s / CI / Ansible ecosystem → Follow the ecosystem — use YAML
Related tools
FAQ
Is YAML a superset of JSON
Very nearly, syntactically: valid JSON can usually be read by a YAML parser. The reverse is not true — YAML anchors, comments and multi-line strings have no JSON equivalent.
Which one should a config file use
It depends on who edits it. Machine-generated and machine-read: JSON. Edited daily by humans who want to leave notes: YAML.
Can they be converted into each other
Yes, and near-losslessly. YAML anchors and comments are dropped when going to JSON, but everything else maps across cleanly.