They Model the Same Data

Both YAML and JSON describe the same four things: scalars (strings, numbers, booleans), arrays/lists, objects/maps, and null. Anything you can write in one, you can write in the other. So the choice is never about capability — it's about who's reading and who's writing.

When JSON Clearly Wins

APIs and data exchange. Every HTTP client, every database, every message queue speaks JSON. There is no "JSON parser bug" the way there are YAML parser bugs. Performance is roughly 5–10x faster for parsing, which matters once you're handling thousands of requests per second.

Strict structures. JSON's brackets make malformed data fail loudly. YAML can silently mis-parse and give you back something that looks valid but isn't.

Generated output. If a tool emits the format, JSON is almost always the right answer. Machines don't care about readability, and JSON is faster to serialize.

Example — same data, JSON form:

{ "name": "api-server", "replicas": 3, "env": { "PORT": "8080", "LOG_LEVEL": "info" }, "ports": [80, 443]
}

When YAML Clearly Wins

Hand-written config. Kubernetes, Docker Compose, GitHub Actions, Ansible — every modern DevOps tool picked YAML for the same reason: humans write the file, and JSON's bracket noise gets in the way fast.

Comments. JSON doesn't allow comments. For a config file, that's brutal — you cannot leave a "this is set high because of the bug in v2.3" note. YAML has # comments that survive round-trips.

Multi-line strings. YAML's | (literal) and > (folded) blocks let you embed shell scripts, templates, or paragraphs of text without escaping every newline. JSON forces you to use \n escapes everywhere.

Same data, YAML form:

name: api-server
replicas: 3
env: PORT: "8080" # quoted so it stays a string LOG_LEVEL: info
ports: - 80 - 443

YAML's Real Gotchas

  • Indentation. Tabs vs spaces, mixed levels, off-by-one — all silent failures or weird parses. Use a linter (yamllint) in CI.
  • The Norway problem. Unquoted NO, YES, ON, OFF become booleans in YAML 1.1. Always quote ambiguous strings.
  • Numbers vs strings. A version like 1.10 parses as the number 1.1. Quote it.
  • Anchors at scale.&defaults and *defaults are powerful but turn a 200-line file into a maze. Use sparingly.

Converting Between Them

Conversion is mechanical and you'll do it constantly when bridging API responses (JSON) into configs (YAML) or vice versa. The YAML to JSON converter handles standard YAML 1.2 documents; for the other direction, the JSON to YAML tool preserves all data exactly. Both are free and run in the browser — no upload, no signup.

The 5-Second Decision Rule

Ask one question: who edits this file? If it's a human typing in vim, use YAML. If it's a service writing output, use JSON. That single rule resolves 95% of cases. The remaining 5% (config that's both human-edited AND machine-generated) usually ends up in TOML or HCL — which exist precisely because YAML and JSON each have weaknesses at the boundary.