Valid JSON is valid YAML — but not the reverse
This is the single most important fact in the comparison: any valid JSON document is also, by design, valid YAML — YAML 1.2 was specified as a strict superset of JSON's data model. The reverse isn't true: YAML's comments, anchors, multi-document files, and flexible scalar styles have no equivalent in JSON's much smaller grammar.
# This is a comment — not possible in plain JSON
name: ToolSphere
version: 2
tags:
- json
- yaml
{"name": "ToolSphere", "version": 2, "tags": ["json", "yaml"]}
Same data, but only the YAML version can carry the explanatory comment — which is exactly why config files (meant to be hand-edited and understood by humans) favor YAML, while API payloads (generated and consumed by code, not usually hand-edited) favor JSON's stricter, unambiguous grammar.
Why config files lean YAML
Config files benefit from everything JSON deliberately omits: comments explaining why a setting has a particular value, less visual noise (no mandatory quotes around every key, no trailing-comma restrictions to trip over), and multi-document support (separating several logical sections with --- in one file) — all genuinely useful for something a human edits directly and returns to months later.
Why APIs lean JSON
APIs benefit from exactly the opposite properties: strict, unambiguous parsing with no whitespace sensitivity, no multiple ways to represent the same value, and near-universal native support across every mainstream programming language's standard library — properties that matter far more when a machine, not a human, is both producing and consuming the data on every request.
The tradeoff: YAML's power is also its risk
YAML's flexibility is exactly why it's more failure-prone to hand-edit — indentation errors change structure silently rather than throwing an obvious error, and its multiple valid ways to write the same scalar (yes/true/on all potentially meaning boolean true, depending on parser and YAML version) can resolve unexpectedly if you're not deliberate about quoting. JSON's rigidity — no ambiguity, but also no comments or shorthand — trades human-friendliness for machine predictability.
Common mistakes
- Assuming JSON and YAML are interchangeable everywhere. Valid JSON is always valid YAML, but going the other direction (YAML with comments, anchors, or unquoted ambiguous scalars) doesn't reduce cleanly to JSON without loss.
- Not quoting YAML strings that look like other types. An unquoted
no,yes, or version-like string can silently resolve to a boolean or number instead of the intended string. - Choosing YAML for machine-to-machine API payloads "for readability." The added parsing ambiguity and lack of universal support work against exactly the properties APIs need most.
FAQ
Is every JSON file automatically valid YAML?
Yes — YAML 1.2 is specified as a strict superset of JSON's data model, so any valid JSON document parses correctly as YAML.
Why do config files usually use YAML instead of JSON?
Comments and a lighter, less rigid syntax matter more for something humans hand-edit and revisit — JSON deliberately omits both in favor of unambiguous, machine-predictable parsing.
Why does an unquoted yes or no sometimes cause bugs in YAML?
Certain YAML parsers interpret specific unquoted words as booleans rather than strings — quoting explicitly ("yes") avoids the ambiguity.
Convert between JSON and YAML and validate either format with the YAML Formatter and JSON Toolkit — both run client-side.