YAML and JSON both describe the same kind of structured data — objects, arrays, strings, numbers, booleans — but they encode it so differently that a document can be perfectly valid in one format and silently mean something different once converted. Most of the surprises come down to a handful of specific YAML quirks.
Why Two Formats for the Same Job
JSON was designed to be simple and unambiguous for machines to parse — every object and array is explicitly wrapped in braces or brackets, so there's little room for a parser to guess wrong. YAML was designed to be easier for humans to read and write by hand, favoring indentation and minimal punctuation over explicit delimiters, which is why configuration files (Docker Compose, Kubernetes manifests, CI pipelines) are so often written in YAML while APIs almost always exchange JSON. The tradeoff is that YAML's human-friendliness comes with a much larger, more surprising rule set underneath.
Why YAML's Indentation Rules Are Strict
Unlike JSON, which uses braces and brackets to mark where an object or array begins and ends, YAML uses the indentation level itself to represent that nesting — so a single misplaced space genuinely changes what a document means, rather than just being a style issue. YAML also forbids literal tab characters for indentation entirely, which is a common source of "invalid indentation" errors when copying YAML from an editor or terminal that used tabs instead of spaces.
The Norway Problem
This is a famous, real gotcha in YAML 1.1 (the version most parsers implement): an unquoted value like NO — commonly used as the ISO country code for Norway — gets automatically interpreted as the boolean false, because YAML treats several unquoted words, including no, yes, on, off, true, and false, as booleans rather than as plain text. The same applies to things that look like numbers or dates. The fix is always the same: quote any value that could plausibly be mistaken for a boolean, number, or null, e.g. country: "NO".
Anchors, Aliases, and What Gets Lost
YAML supports anchors (&name) and aliases (*name), which let one part of a document reuse a value defined elsewhere, avoiding repetition. JSON has no equivalent concept, so converting YAML with anchors into JSON resolves them away — the output contains the fully expanded, repeated data rather than a reference back to the original anchor. Comments are lost entirely in either direction, since JSON has no comment syntax at all to preserve them in.
Converting Instantly
Paste YAML or JSON into our free YAML to JSON Converter to convert it instantly using a real parser (js-yaml) — with a real error message, including line and column, if something's actually invalid.
FAQ
Why is YAML so strict about indentation? Unlike JSON, which uses braces and brackets to mark where an object or array begins and ends, YAML uses indentation level itself to represent that nesting — so a single misplaced space genuinely changes what a document means, rather than just being a style issue. YAML also forbids literal tab characters for indentation entirely, which is a common source of "invalid indentation" errors when copying YAML from somewhere that used tabs.
What is the YAML "Norway Problem"? It's a famous YAML gotcha where an unquoted value like NO (commonly used as the ISO country code for Norway) gets automatically interpreted as the boolean false, because YAML treats several unquoted words — including no, yes, on, off, true, and false — as booleans rather than as plain text. The fix is always to quote any value that could be mistaken for a boolean, number, or null.
Does converting YAML to JSON lose any information? Comments are always lost, since JSON has no comment syntax at all. YAML-specific features like anchors and aliases (reusable references within the same document) are also resolved away — the JSON output contains the fully expanded data, not a reference back to the original anchor, since JSON has no equivalent concept.
Why did my conversion fail with a specific line and column number? That's the real parser error message, pointing to exactly where the YAML or JSON syntax is invalid — usually inconsistent indentation (YAML is indentation-sensitive) or a missing comma or quote (for JSON).