JSON vs YAML

The relationship

Since YAML 1.2, every valid JSON document is also a valid YAML document. YAML then adds comments, anchors and references, multiple documents in one file, multi-line string styles, and indentation instead of brackets.

So JSON to YAML always succeeds. YAML to JSON succeeds only if the YAML uses nothing JSON lacks — which is exactly the features people choose YAML for.

What YAML has that JSON does not

• Comments — the single most common reason a config file is YAML.
• Anchors (&name) and aliases (*name) for reusing a block. JSON has no reference mechanism; conversion must expand them, which duplicates the data.
• Multiple documents in one file, separated by ---. JSON is one value per document, so this becomes an array or separate files.
• Block scalars (| and >) for readable multi-line text. Conversion turns these into one string with \n escapes.
• Unquoted strings, which is convenient and is also where the surprises live.

What JSON has that YAML does not

Unambiguity, and speed. JSON has one way to write each value; YAML has several, and its type inference is famously sharp-edged. In YAML 1.1 parsers — still widespread — the unquoted values no, off and y become booleans, a version number like 1.10 becomes the float 1.1, and a MAC address or a git SHA can be read as a number. Quote anything you mean as a string.

JSON parsers are also considerably faster and much simpler, which is why APIs use JSON on the wire and YAML in the repository.

country: NO        # boolean false in YAML 1.1
version: 1.10      # the float 1.1
port: 08080        # invalid octal in some parsers
time: 12:30        # a sexagesimal number in YAML 1.1

Which to use

• API payloads, logs, anything machine-to-machine: JSON. Faster, unambiguous, universally supported.
• Configuration a human edits and reviews: YAML. Comments alone justify it.
• Anything you will diff in code review: YAML reads better in a diff, as long as the indentation is stable.
• Anything embedded in a URL, a header or a database column: JSON, minified.

Converting

Going from JSON to YAML, the only real choices are indentation and whether to keep the flow style. Going from YAML to JSON, expect to lose comments (JSON cannot hold them), to have anchors expanded into duplicated data, and to have multi-line blocks collapsed into escaped strings. Check the result rather than assuming the round trip is clean — it is not.