YAML vs JSON — key differences with real examples

JSON is the lingua franca of APIs and browsers: strict, easy to parse, and ubiquitous. YAML optimizes for humans writing config: fewer quotes, readable structure, comments — plus features JSON does not have (anchors, aliases, tags). Both serialize structured data; they differ in ergonomics and foot-guns.

Syntax: noise vs intent

JSON requires double quotes around keys and strings, commas between properties, and no trailing commas — see common JSON mistakes. YAML often lets you drop quotes when strings look unambiguous and uses indentation instead of braces for nesting.

// JSON — explicit punctuation
{
  "service": "payments",
  "timeout_ms": 3000,
  "regions": ["iad", "pdx"]
}

# YAML — indentation defines scope (use spaces; tabs are messy)
service: payments
timeout_ms: 3000
regions:
  - iad
  - pdx

Comments

Standard JSON has no comments. YAML supports # line comments — invaluable for explaining flags in Kubernetes manifests and CI configs. Tools that claim “JSON with comments” are extensions (JSONC), not RFC 8259 JSON.

Types and surprises

YAML 1.1 treats unquoted yes/no/on/off as booleans in some parsers — a notorious source of Kubernetes bugs when a country code like NO disappeared into a boolean. JSON only has explicit true/false.

YAML also exposes multiple numeric forms (sexagesimal in older specs, plain integers vs floats). JSON numbers are decimal only. For interoperable configs, quote ambiguous scalars in YAML and validate with a schema (JSON Schema / OpenAPI).

Anchors and aliases — YAML-only power

YAML can deduplicate structures with anchors (&) and aliases (*), reducing repetition in large documents. JSON has no equivalent — you duplicate or generate JSON programmatically.

defaults: &defaults
  timeout_ms: 3000
  retries: 2

payments:
  <<: *defaults
  path: /pay

refunds:
  <<: *defaults
  path: /refund

Streams and documents

YAML can concatenate multiple documents in one file separated by ---. JSON is typically one value per file — joining objects requires JSON Lines or wrapping arrays (unless you use extensions).

JSON inside YAML

Many pipelines embed JSON strings inside YAML for opaque blobs — Kubernetes annotations, CI matrices — because downstream APIs expect JSON. You still validate twice: YAML structure plus inner JSON text.

When to choose which

• Prefer JSON for HTTP APIs, browser fetch, WebSockets, and anywhere unknown parsers must interoperate without ambiguity.
• Prefer YAML for hand-written infra and app config where humans iterate daily — after linting and schema validation.
• Machine-generated config often stays JSON end-to-end to avoid YAML’s implicit typing edge cases.

Validate before you ship

Paste YAML into a formatter that rejects tabs and fixes indentation, and keep JSON on the narrow path from editor to CI so trailing commas never reach production parsers.