JSON vs YAML: Which to Use for Config Files

Should your config file be JSON or YAML? It's one of those questions that sounds like a matter of taste and turns out to have real answers, because the two formats were built for different jobs even though they can hold the exact same data. Pick the wrong one and you either fight unnecessary braces in a file you edit fifty times a day, or you inherit whitespace bugs in a file a machine should have generated.

Here's how to decide, starting with the thing most comparisons skip: JSON and YAML aren't rivals so much as two notations for the same underlying structure.

Same data, two notations

Think of a recipe. You can write it as a tidy printed index card — every measurement in a fixed column, punctuation strict, nothing left to interpretation. Or you can write it as the handwritten note you keep by the stove: fewer marks, a comment in the margin (“use less salt than this says”), easier to scan while your hands are full. Same recipe. Different notation, chosen for who's reading it.

JSON is the index card. An object is wrapped in braces, keys and strings are quoted, items are comma-separated, and there is exactly one way to write a given value. YAML is the margin note: indentation shows structure instead of braces, quotes are usually optional, and you can annotate with comments. In fact YAML is a strict superset of JSON — paste valid JSON into a YAML parser and it works, which is the cleanest proof that they're describing the same thing. You can watch that equivalence directly by running a document through our JSON to YAML converter and comparing the two side by side.

Where YAML wins: files humans edit

The moment a file's primary reader is a person, YAML's advantages start paying off. Two of them matter most.

First, comments. YAML lets you write # this timeout is high on purpose — the upstream is slow, and JSON simply doesn't. For configuration that encodes decisions — why a value is what it is — losing comments is losing institutional memory. Second, the reduced syntax. A Kubernetes manifest or a CI pipeline written in YAML has no closing-brace pileups and few quotes, so the structure you see is the indentation, and the indentation is the structure.

This is why the tools you configure by hand — Docker Compose, GitHub Actions, Kubernetes, Ansible — landed on YAML. Those files are read and tweaked by humans far more often than they're generated, and YAML optimizes for exactly that reader.

Where JSON wins: data machines exchange

Flip the reader and the verdict flips. When the primary consumer is a program — an API response, a message on a queue, a document in a store — JSON's strictness becomes the feature.

Every language ships a fast, battle-tested JSON parser, and they all agree on what a JSON document means, because the grammar leaves almost no room for interpretation. There's no significant whitespace to get wrong, no implicit typing to surprise you, no ambiguity about whether yes is a string or a boolean. That predictability is precisely what you want when two systems written by two teams in two languages have to agree on a payload. When a JSON response comes back unreadable, you drop it into a JSON formatter to indent it, and a JSON validator to confirm it's well-formed — and that's usually the end of the investigation, because JSON has few places to hide a bug.

The fundamentals of that format, if you want them from the ground up, are in our primer on what JSON is.

The gotchas that bite either way

Both formats have sharp edges, and they're different edges.

JSON's are mostly about strictness: no comments, no trailing commas, and every string must be double-quoted. Those rules are also why JSON errors are easy to fix once you know them — our guide on how to fix invalid JSON walks through the five that account for nearly all of them.

YAML's edges are subtler and, honestly, nastier, because they're about implicit behavior. Indentation is significant, so a single stray space changes the structure. And YAML tries to guess types, which produces the infamous “Norway problem”: the country code NO written unquoted is read as the boolean false. version: 1.10 can lose its trailing zero by becoming a number. The defense is boring but reliable — quote any scalar that could be mistaken for a boolean, number, or null. YAML gives you power and hands you the responsibility that comes with it.

You don't have to marry one

The practical escape hatch is that conversion is cheap and lossless for ordinary data. Author your config in YAML because it's pleasant to edit, then convert to JSON at build time for the machine to consume. Or receive a JSON API payload and convert it to YAML with our YAML to JSON converter (and back) when you want to read a gnarly nested response without counting braces.

The verdict

Choose by asking who reads the file most. If it's a human editing by hand and comments would help — YAML. If it's a machine exchanging or storing data where strictness and universal support matter — JSON. And when a project needs both, let one be the source of truth and generate the other; the formats are two notations for the same data, so the conversion is just a change of handwriting, not a change of meaning.