YAML vs JSON: when to reach for each

You open two config files that hold the exact same settings. One is wrapped in braces and quotes; the other reads almost like an outline. They carry identical data, yet they feel nothing alike. That gap, strict versus readable, is the whole story of YAML against JSON, and it tells you which to reach for and when.

TL;DR: JSON and YAML describe the same shapes: maps, lists, and plain values. JSON is strict, brace-and-bracket, and ideal for APIs and machine-to-machine data where guaranteed parsing matters. YAML is indentation-based, allows comments, and is far kinder to hand-edit, which is why config files favor it. Any YAML converts to JSON and back. Pick JSON for data interchange, YAML for human-authored config.

What they have in common

Both formats represent the same three building blocks: mappings (key to value pairs), sequences (ordered lists), and scalars (plain values like text, numbers, and booleans). Nest those and you can describe almost any structured data. Because the underlying model matches, the two are interchangeable in content. A document in one can always be rewritten in the other.

YAML actually formalizes this overlap. The YAML specification defines the format as a superset of JSON, which means a valid JSON file is already valid YAML. You can paste JSON straight into a YAML parser and it works. The reverse needs a conversion step, since YAML has features JSON lacks, but no information is lost going either direction. That is why a YAML to JSON converter can round-trip your data cleanly: the shapes are the same, only the surface syntax changes.

So when people ask which format is more capable, the honest answer is that for ordinary data they tie. The differences live in ergonomics, not in what you can express.

Where JSON wins

JSON wins anywhere a machine reads the data. Its grammar is tiny and rigid: braces for objects, brackets for arrays, double quotes on every key and string, commas between items, and nothing else. That strictness is a feature. A parser has almost no ambiguity to resolve, so JSON parses fast, behaves identically across languages, and rarely surprises you.

That reliability is why APIs settled on it. When a server sends data to a browser or one service calls another, both sides need to agree on the meaning instantly, with no human in the loop to spot a mistake. JSON delivers that. Nearly every programming language ships JSON support in its standard library, and every HTTP client speaks it without extra setup.

The cost is comfort. JSON forbids comments, so you cannot annotate a config file inline. It also rejects trailing commas, the harmless comma after the last item in a list, which trips people up constantly during hand edits. And every string needs quotes, every key needs quotes, every level needs its braces closed. For a machine that is trivial. For a person typing it by hand, it is friction.

Where YAML wins

YAML wins anywhere a human writes and reads the file. It drops most of the punctuation: structure comes from indentation instead of braces and brackets, keys usually skip their quotes, and you separate items with line breaks rather than commas. The result reads more like a structured note than code, which is why it dominates configuration.

The headline feature is comments. YAML lets you start a line with a hash and explain a setting right next to it, something standard JSON cannot do. For a file a teammate will edit next month, that running commentary is worth a lot. YAML also supports anchors, a way to define a value once and reuse it, which trims repetition in long configs.

This is exactly why so much config tooling reaches for YAML: CI pipeline definitions, container orchestration manifests, and countless app settings files lean on it. The people maintaining those files are humans, editing by hand, who benefit from comments and a layout they can scan. The trade is that YAML asks more care while typing, which the next section covers.

YAML’s whitespace footguns

YAML’s flexibility comes with sharp edges, and most of them trace back to two sources: whitespace and overeager type guessing. Because structure depends on indentation, the spaces at the start of a line carry meaning. Get them wrong and the file either fails to parse or, worse, parses into a different shape than you intended while looking fine.

The biggest whitespace rule: never indent with tabs. The YAML spec disallows tab characters for indentation, so a stray tab that looks identical to spaces in your editor can break the whole document. Spaces only, consistently, every level.

Then there is type guessing, which produces the famous Norway problem. YAML tries to infer types from unquoted values, so it reads yes, true, and on as booleans. The country code for Norway, NO, gets parsed as the boolean false rather than the text you meant. Numbers with leading zeros, version strings, and dates can shift under you the same way. The defense is one habit: quote any scalar you need to stay a literal string. Quotes cost two characters and erase a whole class of bugs.

JSON sidesteps all of this. Its strictness means whitespace is decoration, never structure, and every string is quoted by definition, so nothing gets silently retyped.

How to choose

The rule fits in a sentence: use JSON for data interchange, YAML for human-authored config. If a machine is producing or consuming the data, especially across a network, reach for JSON and get its speed, universal support, and zero ambiguity. If a person is writing and maintaining the file, reach for YAML and get comments plus a readable layout.

Most teams end up using both, and that is correct rather than indecisive. Your API talks JSON because machines need a strict contract. Your deployment and pipeline settings live in YAML because humans tune them by hand. The two are not rivals so much as tools for different readers.

And when you need to move between them, the conversion is mechanical. Drop a YAML config into a YAML to JSON converter to feed a tool that only accepts JSON, or pretty-print a dense JSON blob as YAML to read it more easily. Because they share one data model, the round trip is lossless. The format you have never has to be the format you are stuck with.