JSON vs YAML: which format should you use?
JSON and YAML both describe structured data, and every developer eventually has to pick between them — most often when a tool accepts both (Docker Compose, GitHub Actions, Kubernetes) or when a config file needs to become an API payload. This guide shows exactly where the formats differ, what each is good at, and how to convert safely.
01 — The same data, two shapes
One dataset, written both ways
Here is the same configuration in JSON:
{
"service": "api",
"replicas": 3,
"features": ["cache", "metrics"],
"debug": false
}and in YAML:
service: api
replicas: 3
features:
- cache
- metrics
debug: falseBoth parse to the identical data structure. The difference is philosophy: JSON spends characters on brackets and quotes so machines can parse it unambiguously; YAML spends indentation so humans can read it quickly.
02 — Trade-offs
Where each format wins
| Aspect | JSON | YAML |
|---|---|---|
| Readability at small scale | Dense; brackets add noise | Very clean — indentation carries structure |
| Machine parsing | Trivial and universal | Harder: whitespace-sensitive, many edge cases |
| Comments | Not supported | Yes — # comment |
| Error feedback | Precise: parsers point at the exact character | Often vague — a wrong indent breaks everything below it |
| Ecosystem | APIs, browsers, databases, logs | Config: Kubernetes, CI pipelines, Docker Compose |
| Size | Larger (explicit syntax) | Smaller for nested data |
| Safety | Predictable | Historic footguns (the "Norway problem": no parses as false) |
Rule of thumb: machines write and read JSON, humans write YAML. That is why most APIs speak JSON while most config files are YAML.
03 — Decision guide
When to use which
Use JSON when: data crosses a network boundary (APIs, webhooks, storage), when strict validation matters, or when the file is generated by a tool rather than edited by hand.
Use YAML when: humans maintain the file — CI/CD pipelines, Kubernetes manifests, Docker Compose, OpenAPI definitions — especially when it contains comments explaining why.
And when you need to move between the two — turning a hand-written YAML config into an API payload, or vice versa — conversion is lossless for the common subset: mappings, lists, strings, numbers, booleans, and nulls.
04 — Conversion pitfalls
What breaks during conversion
Type coercion: YAML treats on, yes, and no as booleans in some parsers — JSON has no such ambiguity. A version number like 1.20 becomes the number 1.2 in JSON unless quoted. When converting, quote anything that must stay a string.
Multi-document files: YAML allows several documents separated by ---; JSON allows exactly one. Convert documents one at a time.
Anchors and aliases: YAML’s &/* reuse syntax has no JSON equivalent — these must be expanded before converting.
FAQ
Frequently asked questions
Is YAML a superset of JSON?
Technically yes — standard YAML parsers accept flow-style JSON. In practice, tooling often accepts only one, so explicit conversion is the safe route.
Which is faster to parse?
JSON, by a wide margin. Its grammar is simple enough for highly optimized parsers, while YAML parsing is complex and whitespace-dependent.
Can I add comments to JSON?
Not in standard JSON. If you need comments in a config that must also parse as JSON, some ecosystems accept JSONC (JSON with comments) or rely on a sidecar documentation file.
Keep reading