What is YAML?

A superset of JSON, optimised for reading

YAML 1.2 is formally a superset of JSON: any valid JSON document is valid YAML. What YAML adds is a second, indentation-based syntax that drops most punctuation, plus comments, multi-line strings, anchors and aliases for reuse, and multiple documents in one file separated by ---.

Structure comes from indentation rather than braces. A nested mapping is indented under its key; a sequence entry begins with a dash. That is why YAML dominates configuration — Kubernetes manifests, CI pipelines, Docker Compose — where a human edits the file more often than a program writes it.

service: checkout-api
orders:
- id: ord_101
  status: paid
  total: 129.5
  currency: USD
- id: ord_102
  status: failed
  total: 42
  currency: USD

Implicit typing is the classic trap

YAML infers a scalar's type from its shape, and the inference has famous corner cases. Unquoted no is a boolean in YAML 1.1, which is why country code NO became false in more than one production system. A version number written as 1.20 is a float and loses its trailing zero. A MAC address or a git SHA made only of digits and colons can be read as a sexagesimal number.

The defence is mechanical: quote any scalar whose value matters as text. When you convert YAML to JSON, the types you get are the types YAML inferred, so it is worth inspecting the result rather than assuming it round-tripped.

Whitespace is structure

Because indentation carries meaning, a single misplaced space changes the shape of the document rather than raising a syntax error. Tabs are forbidden as indentation entirely. This is the cost of the readability, and it is why converting a hand-edited YAML file to JSON is a useful way to see the structure a parser actually derived, as opposed to the one you intended.

Anchors and aliases add another asymmetry: YAML can express a reference to a shared node, and JSON cannot. Converting to JSON expands every alias, so a file that used an anchor five times becomes five copies.