Web & APIs · 4 min read
YAML vs JSON: When to Use Each
YAML and JSON both represent structured data, and any valid JSON is also valid YAML. So why do both exist, and when should you reach for each? The short answer: JSON is for machines, YAML is for humans.
This guide covers the practical differences and the YAML quirks worth knowing.
Try it yourself with the related tool.
Convert YAML and JSON →Advertisement
JSON: compact and universal
JSON uses braces, brackets, and quotes, which makes it unambiguous and easy for programs to parse. It is the default format for APIs and data interchange because virtually every language can read and write it out of the box. The trade-off is that it is noisy to write and edit by hand, and it does not allow comments.
YAML: readable and comment-friendly
YAML uses indentation instead of braces and allows comments, which makes it far more pleasant for configuration that humans edit — think CI pipelines, Docker Compose, and Kubernetes. The cost of that flexibility is that YAML has subtle rules that can surprise you.
The YAML gotchas
Indentation must use spaces, never tabs. Unquoted values like yes, no, and on can be read as booleans, and a value like 09 can be interpreted as a number. When a value must stay an exact string, quote it. Converting YAML to JSON is a quick way to see how it was actually parsed.
How to choose
Use JSON when a program produces or consumes the data. Use YAML for configuration a person reads and edits. Converting between them lets you author in friendly YAML and hand a service the JSON it expects.