JSON vs YAML

Both are human-readable formats for structured data, and YAML is technically a superset of JSON. In practice they are used for different things, and each has sharp edges the other avoids.

Side by side

// JSON
{
  "name": "api",
  "replicas": 3,
  "ports": [80, 443],
  "env": { "DEBUG": "false" }
}

# YAML
name: api
replicas: 3
ports: [80, 443]
env:
  DEBUG: "false"

Where JSON wins

Unambiguous. The grammar fits on one page. A value is what it looks like.
Universal parsing. Every language has a fast, correct parser built in. YAML parsers are large, slower, and historically had security issues (arbitrary object construction).
Machine interchange. APIs, logs, message queues, browser storage. Nobody sends YAML over HTTP.
Strict. A missing quote fails loudly instead of silently changing a type.

Where YAML wins

Comments. JSON has none. For a config file that humans maintain, this alone is often decisive.
Less noise. No braces, fewer quotes, no trailing-comma errors. Deeply nested configs (Kubernetes, CI pipelines) stay readable.
Multi-line strings with | and > blocks — scripts and certificates without escaping.
Anchors and references (&base / *base) to avoid repetition.

YAML pitfalls to know

The Norway problem

In YAML 1.1, country: NO is parsed as boolean false. So are yes, on, off. Version numbers like 1.10 become the float 1.1. Quote anything that must stay a string.

Indentation is syntax

Tabs are forbidden; a one-space misalignment silently moves a key to a different parent. JSON's braces make structure explicit.

Spec size

The YAML 1.2 spec is around 80 pages; implementations disagree on edge cases. Two tools reading the same file can produce different data.

Which should you use?

Use case	Pick
API request/response	JSON
Data files generated by code	JSON
Hand-edited config with comments	YAML (or JSONC/JSON5)
Kubernetes, GitHub Actions, docker-compose	YAML (the ecosystem decided)
package.json, tsconfig	JSON — the tooling expects it

Converting between them

Because YAML is a superset, any JSON document is already valid YAML. Going the other way requires a YAML parser; losing comments and anchors is expected. If your YAML tool complains about a document, paste the JSON-looking part into the validator first — a stray tab or trailing comma is the usual culprit.