JSON vs YAML: Which Should You Use for Configuration?
Updated · 5 min read · MetaSol Technologies
YAML 1.2 is (almost) a superset of JSON, so every JSON document is also valid YAML. In practice the two are used very differently: JSON for data exchange between programs, YAML for configuration edited by people.
Side by side
{
"service": "api",
"replicas": 3,
"ports": [8080, 8443],
"env": { "LOG_LEVEL": "info" }
}
service: api
replicas: 3
ports:
- 8080
- 8443
env:
LOG_LEVEL: info
YAML's advantages
- Comments with
#, the main reason people choose YAML for config. - Less punctuation: no braces, fewer quotes, no commas.
- Multi-line strings with
|and>blocks. - Anchors and aliases (
&default,*default) to reuse sections.
YAML's pitfalls
- Indentation is syntax. One misplaced space changes the structure, and tabs are not allowed for indentation.
- Implicit typing. In YAML 1.1 parsers (still common), unquoted
yes,no,on,offbecome booleans, so the country codeNOturns intofalse. This is known as the "Norway problem". Values like0123or1e3may also become numbers. - Complexity. The full YAML specification is long, and parsers differ in edge cases.
JSON's advantages
- One obvious way to write everything, with no ambiguity.
- Fast, strict parsers in every language.
- Safe to generate: escaping rules are simple.
Choosing
| Use case | Usually best |
|---|---|
| API requests and responses | JSON |
| Data stored or exchanged between programs | JSON |
| Kubernetes, CI pipelines, Docker Compose | YAML (it's the ecosystem standard) |
| App config edited by people who need comments | YAML |
| App config generated by tools | JSON |
Converting JSON to YAML safely
A careful converter quotes any string YAML might misread. The JSON to YAML converter quotes values such as "yes", "NO", "0123", "1e3" and strings containing : or #, and writes numbers with their exact original digits. The result therefore means the same thing in YAML 1.1 and 1.2 parsers.