JSON vs YAML for Config Files

JSON and YAML can describe the same data, and most tools happily accept either. So why do config files trend towards YAML while APIs stick with JSON? The answer is about who is reading the file — a machine or a human.

They describe the same thing

Both formats represent the same basic building blocks: key–value pairs, lists, and nesting. A YAML file and a JSON file can hold identical data, and converting losslessly between them is routine. In fact, any valid JSON is also valid YAML, because YAML was designed as a superset.

The difference is entirely in the syntax and what it optimises for.

JSON: strict, explicit, machine-first

JSON uses braces, brackets, quotes and commas to mark structure explicitly:

• Every string is quoted.
• Objects are wrapped in { }, arrays in [ ].
• Items are separated by commas.

That verbosity is a feature for machines. The structure is unambiguous, parsing is simple and fast, and there is exactly one way to write a given value. This is why JSON dominates APIs and data interchange — two different systems need zero room for interpretation.

The cost is human friction. A missing comma or a stray trailing comma breaks the whole file, and deeply nested JSON becomes a wall of punctuation that is tiring to read and edit by hand.

YAML: indentation, less noise, human-first

YAML throws out most of the punctuation and uses indentation to show structure, like Python code:

• No braces or brackets in the common case.
• Quotes are usually optional.
• Comments are allowed (JSON has none), which is invaluable in a config file.

The result reads cleanly and is pleasant to edit, which is why it took over configuration for tools like Docker Compose, Kubernetes and CI pipelines, where humans write and review the files constantly.

YAML's sharp edges

That human-friendliness comes with traps worth knowing:

• Indentation is significant. Mixing tabs and spaces, or getting a level wrong, changes the meaning or breaks the parse. Tabs are actually forbidden.
• The "Norway problem". Unquoted no, yes, on and off can be read as booleans, and an unquoted country code NO can become false. Quote strings that could be mistaken for something else.
• Numbers with leading zeros or colons can be misread. When in doubt, quote it.

JSON has none of these ambiguities, because it never tries to guess types from bare words.

Which to use

A simple rule of thumb:

• Machines talking to machines — APIs, data you send over the wire, anything generated and parsed by code → JSON. Strictness is a virtue here.
• Humans writing config — settings files, pipelines, infrastructure definitions → YAML, for the comments and readability. Just lint it.

For many projects the honest answer is "both": YAML for the files people edit, JSON for the data those tools exchange.

Converting and validating

Because the two map cleanly onto each other, moving between them is low-risk, and it is often the fastest way to debug a file. If a YAML file behaves oddly, converting it to JSON shows you exactly how the parser interpreted it — you will immediately spot that no became false or that a list nested one level too deep.

Likewise, formatting and validating JSON before you ship it catches the missing-comma class of error that would otherwise fail at runtime. Converting between JSON and YAML, formatting either one, and inspecting the parsed tree all run in your browser, so you can sanity-check a config file without pasting potentially sensitive values into an online service.