How to Convert JSON to YAML (and Back) Correctly

Why convert between JSON and YAML

YAML is a superset of JSON in spirit: it can represent the same maps, lists, and scalars, but with indentation instead of braces and far less punctuation. Developers convert JSON to YAML to make machine-generated data comfortable to read and edit, and YAML to JSON to feed human-authored config into tools and code that expect strict JSON. Converting YAML to JSON is also a quick way to validate it with the broader JSON toolchain.

How the data models map

{ "service": "api", "ports": [80, 443], "tls": { "enabled": true } }

service: api
ports:
  - 80
  - 443
tls:
  enabled: true

• A JSON object becomes a YAML mapping (key: value pairs by indentation)
• A JSON array becomes a YAML sequence (dash-prefixed list items)
• JSON strings, numbers, booleans, and null map to the corresponding YAML scalars
• Nesting that JSON expresses with braces and brackets, YAML expresses with indentation

Multi-line strings and readability

One of YAML's biggest wins over JSON is multi-line strings. JSON must cram long text onto one line with escaped newline sequences; YAML offers literal and folded block scalars that keep multi-line content readable. When converting JSON to YAML, a good converter can render long string values as block scalars, which is a major reason the YAML version is easier to maintain.

Anchors, aliases, and features JSON lacks

YAML has features with no JSON equivalent: anchors and aliases for reusing a block, comments, and multiple documents in one file separated by triple dashes. When you convert YAML to JSON, these are flattened or dropped — aliases are expanded to their full value, comments disappear, and only one document survives unless handled explicitly. Going from JSON to YAML never invents these features; it produces straightforward YAML you can then enhance by hand.

Gotchas that cause silent corruption

country: NO      # parsed as the boolean false!
country: "NO"    # correct: the string "NO"
zip: "01234"     # quote to keep the leading zero

• The Norway problem — unquoted NO, YES, ON, OFF can be read as booleans in YAML; quoting preserves them as strings.
• Numeric-looking strings — a ZIP code or version like 1.10 may lose a trailing zero or be read as a number unless quoted.
• Comments are lost when converting YAML to JSON, since JSON cannot represent them.
• Indentation errors — YAML is whitespace-sensitive, so a converter must emit consistent indentation to stay valid.

Converting safely in both directions

For a reliable round trip, convert with a tool that parses and validates rather than doing find-and-replace on text. The JSON to YAML tool turns API payloads and data into readable YAML, and the YAML to JSON tool turns config into strict JSON for code and validation. After converting YAML to JSON, run the result through a validator or formatter to confirm it parsed as you expected and to inspect the structure.