YAML vs JSON — when to use which, and converting between them

YAML and JSON describe the same kinds of data — objects, lists, strings, numbers — and you can mechanically convert one into the other. But they've drifted into different jobs, and the reasons are practical. Knowing which fits where (and where YAML quietly bites) saves real time.

They're solving the same problem differently

JSON is built for machines talking to machines. It's strict, unambiguous, every brace and quote required — which is exactly what you want for an API response a program has to parse reliably. The cost is that it's noisy for a human to write, with all those {, }, ", and ,.

YAML is built for humans to write by hand. It drops the braces and quotes and uses indentation to show structure, which is why almost every config format you touch — Docker Compose, Kubernetes, GitHub Actions, CI pipelines — is YAML. It reads like an outline. The cost is that "indentation is structure" turns whitespace into a minefield.

Rough rule: data on the wire → JSON. Config a person edits → YAML.

The YAML traps everyone hits

YAML's friendliness hides a few sharp edges:

• Tabs are illegal. YAML wants spaces, and a single stray tab throws an error that doesn't always point at the tab. Set your editor to insert spaces.
• Indentation has to be consistent. Mixing two-space and four-space nesting, or being off by one space, silently changes the structure or breaks the parse.
• The "Norway problem." Unquoted no, yes, on, off, true get read as booleans. The country code for Norway, NO, famously becomes false. Country code no? Boolean. Quote strings that could be mistaken for something else.
• Numbers with leading zeros or version strings like 1.20 can get coerced in surprising ways. When in doubt, quote it.

Most "my YAML is valid but wrong" bugs are one of these.

The mental model that prevents most YAML bugs: YAML tries to be helpful by guessing types for unquoted values. That guess is occasionally wrong (the Norway problem). When a value's meaning matters and it could look like a boolean, number, or date — quote it, and the guessing stops.

Converting between them

You'll often need to go both ways: paste a JSON API response and want it as readable YAML config, or take a YAML file and need strict JSON for a tool that demands it. Doing it by hand is exactly where the indentation and quoting mistakes creep in.

Primova's YAML ↔ JSON converter does it both directions and preserves keys, nesting, lists, and primitive types — so a round trip gives you back what you started with. It runs in your browser, which matters since config files are full of hostnames, keys, and other things you'd rather not paste into a random server. Next time you're hand-translating braces into indentation, let the YAML ↔ JSON converter do it.