YAML vs JSON

JSON and YAML describe the same data structures — maps, lists, strings, numbers, booleans — with opposite priorities. JSON optimizes for machines: strict, minimal, unambiguous. YAML optimizes for humans: readable, comment-friendly, and quietly full of traps.

The same data, two dialects

JSON:

{ "server": { "host": "example.com", "port": 8080 },
  "features": ["auth", "logging"] }

YAML:

server:
  host: example.com
  port: 8080
features:
  - auth
  - logging

No braces, no quotes, no commas — indentation carries the structure. YAML is technically a superset of JSON: any valid JSON document is valid YAML, which is why conversion YAML→JSON always succeeds while the reverse direction merely loses comments.

What YAML adds

• Comments (#) — the killer feature for config files; JSON has none.
• Anchors & aliases — define a block once, reference it elsewhere (docker-compose uses this heavily).
• Multi-line strings — | preserves line breaks, > folds them.
• Multiple documents in one file, separated by --- (how Kubernetes manifests stack).

The traps: YAML guesses types

Unquoted YAML scalars are type-guessed, and the guesses are famous:

• The Norway problem: country: NO parses as boolean false in YAML 1.1 parsers (NO/no/off/on/yes are booleans).
• version: 3.10 becomes the number 3.1 — trailing zero gone.
• zip: 01234 may parse as octal, and time: 12:30 as sexagesimal in older parsers.

The fix is always the same: quote anything that must stay a string. And the fastest way to seehow a parser interpreted your file is to convert it to JSON, where every type is explicit — a debugging move worth remembering whenever a config is “valid but behaving strangely.”

Indentation: power and peril

YAML's structure lives in spaces (never tabs — they're illegal for indentation). One accidental extra level re-nests a section silently: the file stays valid, the meaning changes. In CI pipelines this is a legendary source of “why didn't my step run” incidents. JSON's braces are noisier but can't fail this way.

Choosing between them

• APIs and data interchange: JSON — universal parsing, no ambiguity.
• Files humans edit: YAML — comments alone settle it (Kubernetes, CI configs, docker-compose).
• Generated/machine-written config: JSON — safety beats readability when no human reads it.

Convert and inspect

The YAML ↔ JSON convertertranslates both directions with real parser errors and a round-trip button — ideal for the “what did YAML think I meant?” check. The JSON formatter validates and pretty-prints the result, and JSON to CSV flattens it for spreadsheets.