Converters6 min read
JSON and YAML can represent the same data, so the choice between them is about readability and purpose rather than capability. This guide compares their syntax side by side, explains where each shines — YAML for hand-edited configuration, JSON for data interchange — and covers the YAML gotchas that catch people out. Any JSON can be turned into YAML, and back, with the JSON to YAML converter.
The same data, two syntaxes
The clearest way to see the difference is side by side. JSON marks structure with braces, brackets, quotes, and commas; YAML uses indentation and drops most of the punctuation.
# JSON
{
"name": "app",
"ports": [80, 443],
"debug": false
}
# YAML
name: app
ports:
- 80
- 443
debug: falseKey differences
The formats differ in a handful of practical ways that determine which is more pleasant to work with for a given task.
| Aspect | JSON | YAML |
|---|---|---|
| Structure | Braces and brackets | Indentation |
| Quotes | Required on strings | Usually optional |
| Comments | Not allowed | Allowed with # |
| Trailing commas | Invalid | Not applicable |
| Readability | Compact | Easier for humans |
| Parsing speed | Faster, simpler | Slower, more complex |
When to use JSON
JSON is the better choice for data interchange between systems. It is unambiguous, fast to parse, supported natively in every language and by every browser, and its strictness leaves little room for surprises. APIs, message payloads, and anything a program produces for another program should generally use JSON.
When to use YAML
YAML is the better choice for configuration that people edit by hand. No braces or commas, support for comments, and indentation-based structure make it easier to read and maintain, which is why tools like Docker Compose, Kubernetes, and GitHub Actions use it. The trade-off is that its flexibility introduces subtle pitfalls.
YAML gotchas to watch for
Because YAML infers types, some values are read differently than you might expect. Quote a value whenever its meaning could be ambiguous.
- Unquoted yes, no, on, and off can be parsed as booleans.
- A leading zero or a value like 1.0 may be read as a number, not a string.
- Indentation must use spaces, never tabs.
- A colon inside an unquoted value can break parsing.
Frequently asked questions
Is YAML a superset of JSON?+
Effectively yes — most valid JSON is also valid YAML, and both can represent the same data structures. The difference is syntax and readability, not capability.
Can I convert JSON to YAML without losing data?+
Yes. The two formats represent the same structures, so keys, values, arrays, and nesting are preserved when converting in either direction.
Why is YAML used for configuration files?+
It is easier to read and edit by hand, supports comments, and uses indentation instead of braces, which suits human-maintained configuration better than JSON.
Does JSON support comments like YAML?+
No. Standard JSON has no comments, which is one of the main reasons YAML is preferred for configuration.