JSON vs YAML: what's the difference?

Both formats represent structured data (objects, arrays, strings, numbers, booleans, null), but they have different syntaxes:

JSON: Strict, machine-friendly. Uses curly braces, square brackets, and double-quoted strings. The de-facto format for APIs.
YAML: Human-friendly. Uses indentation instead of brackets. Supports comments (#). Common in configuration files (Docker Compose, GitHub Actions, Kubernetes).

YAML is a superset of JSON; all valid JSON is valid YAML, but YAML has many additional features.

When to use each format

JSON: REST APIs, data interchange, package manifests (package.json)
YAML: CI/CD pipelines (.github/workflows), Docker Compose, Kubernetes, Ansible, configuration files

YAML gotchas

Indentation matters: use spaces, never tabs.
Reserved words: yes, no, on, off are parsed as booleans unless quoted.
The Norway problem: country codes like NO are parsed as boolean false in YAML 1.1 parsers. Always quote ISO country codes and other short uppercase strings.
Strings that look like numbers: leading zeros (007) may be interpreted as octal in YAML 1.1 parsers (the number 7). YAML 1.2 removes this behavior, but many tools still use 1.1 parsers.
Date auto-parsing: bare date strings like 2024-01-15 are parsed as Date objects, not strings, by many YAML parsers. Quote them if you need string values.
Colons in strings: a colon followed by a space (: ) starts a new mapping key, so such strings must be quoted.

YAML anchors and aliases

YAML supports anchors (&name) and aliases (*name) to reuse content without repetition:

defaults: &defaults
  retries: 3
  timeout: 30

production:
  <<: *defaults
  host: prod.example.com

staging:
  <<: *defaults
  host: staging.example.com

The <<: merge key merges the referenced mapping into the current object. This is widely used in Docker Compose files and CI/CD pipelines to avoid repeating shared configuration. Note that JSON has no equivalent, so anchors are expanded during YAML->JSON conversion.