YAML to JSON

YAML is a superset of JSON

Every valid JSON document is already valid YAML, which is why JSON to YAML is always clean. The reverse loses things YAML has and JSON does not: comments, anchors and aliases, multiple documents in one file, and several distinct multi-line string styles. In a configuration file the comments are frequently the most valuable content, and they vanish silently.

The Norway problem

YAML 1.1 reads a set of unquoted scalars as booleans: yes, no, on, off, true, false and their capitalised forms. The country code for Norway is NO, so an unquoted list of country codes converts Norway to the boolean false. The same class of bug turns version 1.10 into the number 1.1, and reads a time like 12:30 as a sexagesimal number in older parsers. Quote any scalar whose type you care about.

Indentation is the syntax

YAML uses indentation for structure and forbids tabs entirely, because tab width is ambiguous. A single stray tab produces a parse error that most editors render invisible. Configure your editor to insert spaces and to show whitespace before debugging anything else.

Anchors expand

An anchor marks a node and an alias reuses it, which avoids repetition in long configurations. JSON has no equivalent, so each alias is expanded into a full copy. The output is correct and longer, and the shared relationship is gone, so round-tripping back to YAML will not restore it.

Multi-line strings

The literal style with a pipe preserves newlines; the folded style with a greater-than sign joins lines into a paragraph. Each takes a chomping indicator controlling trailing newlines. Getting this wrong is how an embedded shell script in a CI configuration ends up with its lines concatenated into one unrunnable command.