YAML vs JSON: when to reach for each

Short version: use JSON when a machine produces or reads the data, and use YAML when a human edits the file by hand. They describe the same thing, so the choice is not about power. It is about which one is safer to type and which one is safer to parse.

TL;DR: JSON and YAML model the same shapes: maps, lists, and plain values. In fact JSON is a subset of YAML, so every JSON file is already valid YAML. JSON is strict and predictable, which is what you want for APIs and machine-to-machine data. YAML drops the punctuation and adds comments, which is what you want for config a person edits. YAML’s convenience comes with real traps: it guesses types (the Norway problem) and it breaks on tabs. Pick JSON for interchange, YAML for human-authored config.

The thing most comparisons skip: JSON is a subset of YAML

People frame this as “YAML versus JSON” like they are two rival formats. They are not really rivals. The YAML spec defines the format as a superset of JSON, which means any valid JSON document is also a valid YAML document. Paste this into a YAML parser and it loads fine:

{ "name": "web", "ports": [80, 443], "tls": true }

That is JSON. It is also legal YAML. The braces, the brackets, the quoted keys, the commas: YAML accepts all of it. So when someone asks which format can express more, the answer for ordinary data is that they tie, and YAML is technically the bigger one. Every difference you care about lives in ergonomics, not capability. A YAML to JSON converter can round-trip your data because the underlying shapes are identical; only the surface syntax changes.

Where JSON wins: strictness

JSON’s grammar is tiny and rigid. Braces for objects, brackets for arrays, double quotes on every key and string, commas between items, and nothing else. No comments, no shortcuts, no ambiguity. That rigidity is the point. A parser has almost nothing to guess, so JSON reads the same way in every language and rarely surprises you.

This is why APIs run on it. When a server sends data to a browser or one service calls another, both sides need to agree on the meaning right away, with no human around to catch a mistake. Every mainstream language ships JSON support in its standard library, and every HTTP client speaks it without setup.

The cost is comfort. You cannot put a comment in a JSON file, so you cannot explain a setting inline. JSON also rejects a trailing comma, the harmless one after the last item in a list, which trips people up during hand edits. And everything needs quotes. For a machine that is nothing. For a person typing it out, it is friction.

Where YAML wins: readability

YAML strips most of the punctuation. Structure comes from indentation instead of braces, keys usually skip their quotes, and line breaks replace commas. The result reads like an outline, which is why it took over configuration:

name: web
ports:
  - 80
  - 443
tls: true  # terminate TLS at the edge

The headline feature is that comment on the last line. Standard JSON cannot do that. For a file a teammate opens next month, a running commentary next to each setting is worth a lot. YAML also has anchors, a way to define a value once and reuse it, which cuts repetition in long files. CI pipelines, container manifests, and app config lean on YAML for exactly these reasons: the people maintaining them are humans, editing by hand.

The catch is that all this convenience is also where YAML bites you.

YAML’s real traps

The Norway problem

YAML tries to infer the type of an unquoted value, and it is too eager about it. Try this yourself. Put one line in a file called test.yaml:

country: NO

Now load it. In Python:

import yaml
print(yaml.safe_load(open("test.yaml")))
# {'country': False}

You wrote the country code for Norway and you got back the boolean false. That is the Norway problem, and it is not just NO. YAML reads yes, no, on, and off as booleans, so a config that lists norway: no under a set of countries quietly becomes norway: false. Numbers get coerced too. 1.20 loads as 1.2, so a version string loses its trailing zero, and 010 can load as the octal number 8. None of this throws an error. The file looks correct and parses into the wrong thing.

The fix is one habit: quote any scalar you need to stay a literal string.

country: "NO"   # stays the string "NO"
version: "1.20" # stays the string, not the number 1.2

Two quote characters erase a whole class of silent bugs.

Tabs break it

YAML structure depends on indentation, and the spec forbids tab characters for indentation. A tab looks identical to spaces in most editors, so you can stare at a file that reads fine and get a parse error you cannot see. Load a file that indents a list item with a tab and you get:

yaml.scanner.ScannerError: found character '\t' that cannot start any token

Spaces only, the same width at every level. Tell your editor to insert spaces for YAML, and this one stops happening.

Whitespace carries meaning

Because indentation defines structure, a stray space can reshape your data without failing. Indent a key one level too far and it becomes a child of the wrong parent. The file parses. It just parses into something you did not mean. JSON sidesteps all of this: whitespace there is pure decoration, and every string is quoted by definition, so nothing gets silently retyped or reparented.

This is the honest downside of YAML. It is more pleasant to read and more error-prone to hand-edit, for the same reason: it is doing more work to guess what you meant.

How to choose

The rule fits in a sentence: use JSON for machine-to-machine data and APIs, use YAML for config a human edits by hand.

If a machine is producing or consuming the data, especially across a network, reach for JSON. You get speed, universal support, and one unambiguous meaning. If a person is writing and maintaining the file, reach for YAML. You get comments and a layout you can scan, and you accept that you have to quote your strings and mind your spaces.

Most teams use both, and that is correct rather than indecisive. Your API talks JSON because machines need a strict contract. Your deployment and pipeline config lives in YAML because people tune it by hand. When you need to move between them, the conversion is mechanical: drop a YAML file 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. They share one data model, so the round trip loses nothing. The format you have is never the format you are stuck with.