YAML vs JSON: which should you use?
JSON is a strict data-interchange format; YAML is a human-friendly superset built for files people edit by hand. The right choice depends on who reads the file more often — programs or humans.
At a glance
| YAML | JSON | |
|---|---|---|
| Comments | Yes (#) | No |
| Syntax | Indentation-based | Braces and quotes |
| Superset | YAML 1.2 is a superset of JSON | — |
| Parsing | Slower, more complex | Fast, ubiquitous |
| Typical use | Config files (CI, Kubernetes, Docker) | APIs, data exchange, storage |
| Gotchas | Indentation errors, implicit typing | No comments, trailing commas invalid |
When YAML wins
Use YAML for files humans maintain: CI pipelines, Kubernetes manifests, app config. Comments alone justify it — you can document why a setting exists next to the setting itself.
When JSON wins
Use JSON for anything programs produce or consume: API payloads, data storage, lockfiles. Parsers are faster, stricter and available everywhere, and there's no whitespace ambiguity. Since YAML 1.2 is a superset of JSON, any valid JSON document is also valid YAML.
Tools used in this guide
Related guides
YAML vs JSON: which should you use? — FAQ
Yes — YAML 1.2 parses any valid JSON document. The reverse is not true.