JSON vs YAML: which should you use, and when?
JSON and YAML describe the same kinds of data, but they target different jobs. JSON is the wire format for APIs; YAML is the format people hand-edit for config. Here is how they actually differ.
| JSON | YAML | |
|---|---|---|
| Primary use | API payloads, data interchange | Config files (CI, Kubernetes, etc.) |
| Comments | Not supported | Supported with # |
| Syntax | Braces and brackets | Indentation (whitespace-significant) |
| Readability | Good for machines | Better for humans |
| Parse speed | Very fast | Slower (more complex grammar) |
| Footguns | Trailing commas, quoting | Indentation errors, the "Norway problem" |
The big differences
YAML is a superset of JSON — any valid JSON is valid YAML. The reverse is not true. YAML adds comments, anchors, and indentation-based structure that JSON lacks.
JSON’s rigidity is a feature for machines: there is exactly one way to write it, so parsers are tiny and fast. YAML’s flexibility is a feature for humans but a source of subtle bugs.
YAML’s famous footguns
The "Norway problem": country: NO parses as the boolean false, not the string "NO". Unquoted yes, on, and version numbers like 1.10 also surprise people.
The verdict
Use JSON for anything a program produces or consumes — APIs, logs, storage. Use YAML for files humans edit by hand, where comments and readability matter. Need to move between them? The JSON ↔ YAML converter does it in your browser.
Frequently asked questions
- Is YAML faster than JSON?
- No. JSON parses faster because its grammar is simpler. YAML trades speed for human readability and features like comments.
- Can I convert JSON to YAML losslessly?
- Yes for data — every JSON document is valid YAML. Converting YAML to JSON can lose comments and anchors, which JSON cannot represent.
- Why does YAML turn "NO" into false?
- YAML interprets several unquoted words (no, yes, on, off) as booleans. Quote the value ("NO") to keep it a string.
Try it yourself
Free, in-browser tools for everything above.