YAML vs JSON: Differences Explained (with Examples)

YAML and JSON both describe the same kinds of data: scalars, lists, and key/value maps. In fact, YAML is a superset of JSON, which means valid JSON is also valid YAML. The reason both exist is that they optimise for different readers. JSON optimises for machines and strict parsing; YAML optimises for humans hand-editing configuration.

The Same Data, Both Ways

JSON:

{
  "service": "web",
  "replicas": 3,
  "ports": [80, 443],
  "env": { "DEBUG": false }
}

YAML:

# Deployment settings
service: web
replicas: 3
ports:
  - 80
  - 443
env:
  DEBUG: false

Notice YAML drops the braces, quotes, and commas, using indentation and dashes instead. It also allows that # comment on the first line, which JSON cannot express at all.

Side-by-Side Comparison

Where YAML Shines

YAML is the format of choice for configuration files in modern tooling because it is comfortable to write and read by hand:

• Comments let you explain why a value is set, which is essential for shared config.
• Less punctuation means fewer stray commas and unbalanced braces.
• Anchors and references (& and *) let you reuse blocks to avoid repetition.
• Multi-line strings are first-class, so embedding a script or a certificate reads naturally.

Where JSON Shines

JSON's strictness is a feature when a machine is on the other end:

• Unambiguous parsing. There is essentially one way to read a JSON document, so parsers are simple and fast.
• Universal support. Every language ships a JSON parser, and it is the native format of the web.
• No whitespace traps. Because indentation is meaningless, copy-paste and minification never change the data.

When you are inspecting or cleaning up a JSON payload, a JSON Formatter will pretty-print and validate it so structural errors are obvious before you ship.

Common YAML Gotchas

YAML's friendliness hides some sharp edges. Watch for these:

1. Tabs are illegal. YAML requires spaces for indentation; a stray tab throws a parse error.
2. The Norway problem. Unquoted no, yes, on, and off may be read as booleans. Country code NO can become false. Quote such strings.
3. Numbers with leading zeros or version strings like 1.10 can be coerced unexpectedly. Quote them to be safe.
4. Indentation mistakes silently change nesting rather than failing loudly.

Because of these, many teams edit in YAML but convert to JSON for anything a program consumes directly.

Converting Between Them

You do not have to choose once and for all. Keep human-friendly YAML in your repo, then produce JSON for tools and APIs with YAML to JSON. If a service hands you JSON and you want a readable, comment-able version, run it through JSON to YAML. Round-tripping is safe for data, though comments are lost when you convert YAML to JSON and back.

Takeaway

Use YAML for configuration that people edit by hand, where comments and readability matter. Use JSON for data interchange, APIs, and anything a machine parses, where strictness and universal support win. Since YAML is a superset of JSON, you can convert freely and let each layer of your stack use the format that suits it best.