YAML vs JSON
YAML and JSON both represent structured data as human-readable text, and YAML is actually a superset of JSON - any valid JSON is valid YAML. The practical difference is in syntax style and where each has become the convention.
YAML has become the convention for configuration files (Kubernetes, CI/CD pipelines, Docker Compose) because of its readability and comment support - genuinely useful for files humans edit by hand.
Side by side
| YAML | JSON | |
|---|---|---|
| Syntax style | Indentation-based, minimal punctuation | Braces, brackets, and quoted keys |
| Comments | Supported (# comment) | Not supported natively |
| Readability for config | Generally considered more readable for humans | More verbose but unambiguous |
| Whitespace sensitivity | Sensitive - indentation errors break parsing | Not sensitive to whitespace |
| Native support in JavaScript | Requires a library to parse | Native - JSON.parse() built in |
| Common use case | Config files (Docker Compose, Kubernetes, CI pipelines) | APIs, data interchange, JavaScript-heavy contexts |
The verdict
YAML has become the convention for configuration files (Kubernetes, CI/CD pipelines, Docker Compose) because of its readability and comment support - genuinely useful for files humans edit by hand. JSON remains the standard for API responses and anywhere JavaScript is directly consuming the data, thanks to its native parsing support and lack of whitespace-sensitivity bugs.
Try it yourself
Frequently asked questions
01Is YAML valid JSON, or the other way around?
YAML is a superset of JSON - any valid JSON document is also valid YAML, but not every YAML document (like one using comments or anchors) is valid JSON.
02Why do Kubernetes and Docker Compose use YAML instead of JSON?
Mainly readability and comment support - config files are hand-edited often, and YAML's lack of braces/quotes and support for comments makes that easier than JSON.
03What's the biggest risk with YAML?
Whitespace sensitivity - an incorrect indentation level can silently change the meaning of a document or cause a parse error, which doesn't happen with JSON's explicit braces.