YAML vs JSON: which to use when, and what changes during conversion

YAML and JSON are the two dominant data-serialization formats in modern software. They solve essentially the same problem — representing nested structured data as plain text — but they make almost opposite choices in how they do it. JSON optimizes for being machine-easy at the cost of being human-painful; YAML optimizes for being human-easy at the cost of being machine-painful.

If you're converting between them, knowing why you'd pick one over the other matters as much as knowing how the conversion works. This guide covers both.

The core difference

JSON is strict, regular, and verbose. Every string is quoted, every key-value pair uses a colon, every list element is comma-separated, and braces or brackets surround every block. Parsing JSON is a near-trivial exercise; you can write a JSON parser in a weekend.

YAML is permissive, irregular, and compact. Strings often don't need quotes, indentation defines structure, lists use dashes, and the same data can be written in several ways. Parsing YAML correctly is famously tricky — the spec is large, and edge cases are everywhere.

When to choose JSON

• API requests and responses. HTTP APIs almost universally use JSON. Every language has a fast, battle-tested JSON parser in its standard library. The format is the lingua franca of the web.
• Machine-to-machine data exchange. When two systems need to swap data and humans rarely look at it, JSON's strictness is a feature — there's no ambiguity about what was meant.
• Persistent storage where humans rarely edit. Document databases, log lines, message queues — anywhere data is written by code and read by code, JSON is the right choice.
• Performance-sensitive parsing. Large data sets parse faster as JSON than as YAML by a meaningful margin, often 5–10× faster.

When to choose YAML

• Configuration files humans edit by hand. Kubernetes manifests, GitHub Actions workflows, Ansible playbooks, Docker Compose files — everywhere a human writes the file directly, YAML is far more pleasant to read and edit.
• Files that benefit from comments. YAML supports # comments, JSON does not. For human-edited config, comments are essential — explaining why a value is set is often more important than the value itself.
• Documents with substantial multi-line strings. YAML's block-scalar syntax (| and >) makes multi-line text vastly more readable than JSON's escaped newlines.
• References and anchors. YAML lets you define a value once and reuse it elsewhere with &anchor and *alias. JSON requires copy-paste.

What conversion preserves

Both YAML and JSON can represent the same data structures: scalars (strings, numbers, booleans, null), lists, and nested objects. Converting between them losslessly preserves the data tree itself.

Things that survive conversion in both directions

• Object structure (keys, nested objects, arrays).
• Numeric values (integers, floats).
• Boolean values.
• Null values.
• Strings, including Unicode.

What conversion changes

Some YAML features have no JSON equivalent and are inevitably lost when converting YAML to JSON:

• Comments. JSON has no comments. Any # comments in YAML are dropped. If your YAML's comments are important, the JSON conversion loses something irreversible.
• Anchors and aliases. YAML's &anchor/*alias mechanism for re-using values is expanded inline during conversion. The resulting JSON has duplicated values rather than references — the data is equivalent, but the structure is no longer DRY.
• Multi-document YAML. A single YAML file can contain multiple documents separated by ---. JSON cannot. When converting, multi-document YAML usually becomes a JSON array of objects, or only the first document survives — depending on the converter.
• Custom tags. YAML supports type tags like !!python/tuple for language-specific types. JSON has no tag system, so these are dropped or coerced to plain values.

Going JSON → YAML, almost everything survives. The output may be ambiguous (was a key meant as a string or a number?), but information is not lost.

Common gotchas during conversion

The 'Norway problem'

YAML 1.1 (still widely used) treats unquoted yes, no, on, off, and several country-code abbreviations (most famously NO for Norway) as boolean values. Convert that to JSON and you get true/false where you expected the strings "yes"/"NO". The fix is to quote string values that look booleanish, or use a YAML 1.2 parser which is stricter.

Type coercion of unquoted scalars

Unquoted 01234 in YAML may be interpreted as octal in some parsers and as a string in others. Versions written as 1.0 become floats. Phone numbers written without quotes lose leading zeros and dashes. When in doubt, quote everything.

Indentation matters

YAML uses indentation to define structure. A misplaced space can change the meaning entirely — the wrong indentation level can turn a sibling into a child, or vice versa. JSON has no such trap because it uses explicit braces. If your YAML conversion produces unexpected output, the first thing to check is the indentation of the source.

Practical workflow recommendation

Pick the right format for the right job:

• Write configs and human-edited documents in YAML. Take advantage of comments and references.
• Send and store machine data in JSON. Take advantage of strictness and parser speed.
• Convert at the boundary, not in the middle. If a build pipeline writes YAML configs and the runtime reads JSON, convert once during build, then leave it alone.

Convert YAML to JSON or convert JSON to YAML — free, instant, with all the data preserved that the formats can preserve. Quote your booleanish strings and you'll have no surprises.