Reference notes
Short, specific reference notes on the parts of JSON and YAML that cause trouble, written for the moment when something has already gone wrong.
Start here
The pages below are reference notes rather than tutorials. Each one exists because it answers a question that comes up repeatedly when people are converting configuration between formats — usually at the point where something has already gone wrong.
The three-minute version
If you only read one thing: JSON and YAML describe the same data model — mappings, sequences, and scalars. JSON writes that model with punctuation. YAML writes it with whitespace, and adds comments, anchors, and multi-document files on top.
Converting from JSON to YAML is lossless. Converting from YAML to JSON is not, because comments and anchors have nowhere to go. That asymmetry is the single most useful thing to know about the two formats, and it decides which one should be your source of truth: keep the YAML, generate the JSON.
The tools follow from that: JSON to YAML and YAML to JSON for the conversion itself, and the YAML validator when a file will not parse.
The most common bug when hand-writing YAML is not a syntax error. It is a value that parses as the wrong type — a version number that loses a trailing zero, a country code that becomes a boolean. When a scalar is meant to be text and could be read as something else, quote it.