JSON vs YAML: Which One to Use
YAML expresses nesting through indentation with barely any quotes or brackets — genuinely pleasant for configs. But its cleverness ships a set of famous traps. This guide lays out the trade-off and what conversion loses.
The same config, two styles
In the example above YAML is clearly cleaner: no brackets, quotes or commas, the hierarchy is visible at a glance, and comments are supported — which is why it rules the config world (Docker Compose, Kubernetes and most CI configs are YAML).
{ "server": { "host": "localhost", "ports": [80, 443] } }
server:
host: localhost
ports:
- 80
- 443Where JSON wins
The rules fit in your head in minutes, every parser behaves identically, and there is no type guessing; a wrong indent is an immediate syntax error rather than a silently different structure. For data exchanged between programs, JSON’s strictness is a feature.
YAML’s famous traps
The two lines above are real incident material: Norway’s country code NO parses as boolean false, and 1.10 parses as the number 1.1. Mixing tabs and spaces, or one indent level off, silently changes the structure. The standard advice: quote every string value and never rely on bare-value type guessing.
country: NO # 挪威的国家码,却被解析成布尔 false / parsed as boolean false version: 1.10 # 想要字符串版本号,却被解析成数字 1.1 / parsed as number 1.1
What to watch when converting
YAML to JSON drops comments and anchor references, and multi-document streams keep only one document; JSON to YAML is essentially lossless, though block vs flow style affects readability. Always validate converted configs in the target environment — especially strings that used to be quoted.
Bottom line
Configs written and maintained by humans: YAML (quote your strings). Data generated and consumed by machines: JSON. Conversion is cheap — no need to pick a side permanently.