Understanding JSON ⇄ YAML
Indentation as syntax.
YAML is a superset of JSON. Converting between them is mostly mechanical — the surprises come from YAML's leniency.
YAML is a superset of JSON.
Every valid JSON document is also a valid YAML document. That's by design: YAML 1.2 explicitly absorbed JSON's grammar so that JSON config files would parse as-is. Going the other way isn't always clean — YAML supports references, multiline strings, comments, and unquoted strings, none of which JSON allows. The converter strips those features as it serialises to JSON.
name: "AnytimeConvert" version: 1 ⇄ { "name": "AnytimeConvert", "version": 1 }
Indentation matters — and only spaces work.
YAML uses indentation to express nesting. Two spaces is the de-facto convention (this tool emits two on output). Tabs are explicitly forbidden by the spec, and inconsistent indentation is the single most common cause of broken YAML. When in doubt, paste your YAML into the converter and let the round-trip through JSON normalise the indentation.
The Norway problem and other type traps.
Bare YAML strings are interpreted: yes, no, true, false, on, and off all parse as booleans. The country code NO for Norway parsed as false until YAML 1.2 narrowed the rule. The safe habit: quote any string that could be misread as a boolean, a number, or a date — "NO" instead of NO.
What JSON loses on the way back.
Comments, anchor / alias references (&ref and *ref), and folded multi-line strings vanish when YAML becomes JSON. Document separators (---), which let one YAML file contain multiple objects, collapse to whichever document the tool ends up parsing. If those features matter, treat YAML as the source of truth.
When to use which.
YAML for human-edited config: Kubernetes manifests, CI pipelines, OpenAPI specs, Ansible playbooks. JSON for machine-to-machine transport, anything embedded in HTTP bodies, anywhere a parser without YAML support might land. Most teams maintain config in YAML and serve it as JSON through a build step.