JSON vs YAML: Which One Should You Actually Use
The real differences between JSON and YAML, where each one falls apart in practice, and how to pick without overthinking it.
Published January 20, 2026
JSON and YAML both describe the same kinds of data: objects, arrays, strings, numbers, booleans, null. The choice between them almost never comes down to what they can represent. It comes down to who's going to read the file, how it's going to be generated, and how forgiving you need the format to be about mistakes.
What's actually different
JSON is strict on purpose. Every string needs quotes, trailing commas are a syntax error, and there's exactly one way to write most things. That rigidity is a feature for machine-to-machine communication: two different parsers on two different platforms will agree on what a JSON document means, every time, with no ambiguity.
YAML trades that strictness for readability. No quotes required on simple strings, comments are allowed (JSON has none), and indentation carries structural meaning instead of braces and brackets. That makes YAML pleasant to hand-write and read in a diff, which is exactly why config files gravitated toward it.
Where each one actually gets used
APIs, webhooks, and anything two programs exchange over a network is almost always JSON. It's the native data format of JavaScript, every language has a fast built-in or near-built-in parser for it, and its strictness means there's very little room for a subtly malformed payload to silently mean something different than intended.
Config files that a human is going to write and maintain by hand lean YAML: CI pipelines, Docker Compose, Kubernetes manifests, Ansible playbooks. The ability to add comments explaining why a value is set the way it is turns out to matter a lot once a config file has been edited by five different people over two years.
The YAML gotchas worth knowing before you commit to it
YAML's flexibility creates a specific class of bug that JSON simply can't have: implicit typing surprises. The bare word `no` parses as the boolean `false` in YAML 1.1 (the version most tools still use), which has bitten real projects that used `no` or `yes`, or country codes like `NO` for Norway, as plain strings. Indentation errors are also silent in a way JSON's braces aren't: a misplaced two spaces can move a key into the wrong parent object without throwing any error at all.
None of this makes YAML unsafe to use, but it does mean YAML files benefit from being validated by a schema or linter rather than just eyeballed, especially in anything that reaches production.
How to decide
If a machine is generating it and a machine is consuming it, use JSON. If a person is going to write it, edit it by hand, and benefit from comments explaining intent, use YAML, and run it through a linter. If you're not sure which camp a given file falls into, default to JSON: it's harder to get subtly wrong, and converting a JSON file to YAML later is a much smaller job than untangling a YAML file's implicit typing after the fact.