YAML vs JSON: Which Config Format?
YAML is a human-friendly configuration format supporting comments and anchors; JSON is a strict, ubiquitous data-interchange format with no comments.
YAML uses indentation and supports comments, anchors, and multiline strings, making it popular for configuration (CI workflows, Kubernetes, Compose). JSON is stricter, has no comments, and is the lingua franca for APIs and machine interchange. YAML favors human authoring; JSON favors unambiguous machine parsing. Note YAML is a superset of JSON, so JSON is valid YAML.
| YAML | JSON | |
|---|---|---|
| Readability | High (indentation) | Moderate (braces) |
| Comments | Yes | No |
| Reuse | Anchors / aliases | None |
| Strictness | Looser, footguns | Strict, predictable |
| Best for | Config, CI workflows | APIs, data interchange |
Use case and pitfalls
YAML suits hand-edited configuration where comments and structure aid readability, but watch for footguns: significant whitespace, the Norway problem (no parsed as false), and tab errors. JSON suits API payloads and generated data where strictness and universal parsing matter. Many tools accept both.
In CI
Lint YAML (yamllint) and validate against schemas to catch indentation and type pitfalls early; JSON validates against JSON Schema. Both run on managed runners, where faster runners shorten lint and schema-validation steps.
The verdict
Human-authored configuration with comments and reuse: YAML, watching for whitespace and type footguns. Machine interchange and API payloads needing strict, unambiguous parsing: JSON. Config tends toward YAML; data interchange tends toward JSON.