JSON vs YAML: when to use which

JSON and YAML can represent exactly the same data: objects, lists, strings, numbers, booleans and null. In fact, YAML 1.2 is a superset of JSON, so every valid JSON document is also valid YAML. The difference is who (or what) is going to read and write the file.

The same data, twice

Here's a small service config in JSON:

{
  "service": "billing",
  "replicas": 3,
  "ports": [8080, 9090],
  "env": { "LOG_LEVEL": "info", "FEATURE_X": false }
}

And the same thing in YAML:

service: billing
replicas: 3
ports:
  - 8080
  - 9090
env:
  LOG_LEVEL: info
  FEATURE_X: false

The YAML is shorter and has no brackets or quotes to balance. That's why people like it for files they edit by hand.

Choose JSON when machines are the main audience

• APIs and data exchange. Every language has a fast, strict JSON parser. There's one way to write a string and one way to write a number.
• Generated files. Lock files, build output and anything a program writes and another reads.
• Strictness is a feature. A missing comma is a parse error, not a silently different value.

JSON's weaknesses are mostly for humans: no comments, no trailing commas, and lots of quotes.

Choose YAML when humans edit the file

• Configuration that people read and change: CI pipelines, Kubernetes manifests, Docker Compose files.
• Comments. YAML has them (# like this), and config files need them.
• Long strings. Block scalars (| keeps line breaks, > folds them) make multi-line text readable.

The YAML gotchas

YAML's friendliness comes from guessing types, and the guesses are where it bites.

The Norway problem. In YAML 1.1, unquoted no, yes, on and off are booleans. So a list of country codes like this:

countries: [GB, IE, NO]

gives you "GB", "IE" and false in parsers that follow 1.1, which still includes some popular libraries. YAML 1.2 only treats true and false as booleans, but you can't always control which version a tool uses. Quote anything that could be misread: "NO", "on", "1.10".

Numbers that aren't. version: 1.10 is the number 1.1. Zip codes and phone numbers with leading zeros can lose them. Octal-looking values like 0755 may be read as numbers in base 8.

Indentation is structure. A wrong indent doesn't always fail; sometimes it quietly nests a key under the wrong parent. Tabs aren't allowed for indentation at all.

Duplicate keys. Many parsers keep the last value without complaint.

Converting safely

The JSON ⇄ YAML converter converts in both directions in your browser and quotes strings that YAML would otherwise turn into booleans or numbers, so a round trip gives you back the data you started with. When you convert YAML to JSON, read the output: it's the clearest way to see what a YAML parser actually understood.

If the JSON side is a mess, run it through the JSON formatter first. It validates and pretty-prints, and points to the line and column of the first error.

Validate the shape, not just the syntax

Valid syntax doesn't mean the config is right. replicas: "three" parses fine and breaks at deploy time. A JSON Schema describes what the data must look like (required keys, types, allowed values), and because YAML maps onto JSON, the same schema works for both. Paste your data and a schema into the JSON Schema validator to see every violation with its path.

Rule of thumb

• Programs talking to programs: JSON.
• People editing config: YAML, with quotes around anything ambiguous and a schema to catch mistakes.
• Not sure? JSON is the safer default. You can always convert later.