YAML vs JSON

YAML and JSON describe the same kinds of data: nested maps, lists, strings, numbers, booleans, and nulls. The difference is who they are written for. JSON is optimized for machines and interchange. YAML is optimized for people who read and edit the file. This guide compares them concretely so you can pick the right one.

The same data in both formats

JSON:

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

YAML:

# Web API deployment
name: api
replicas: 3
env:
  LOG_LEVEL: info
ports:
  - 80
  - 443

YAML drops the braces, brackets, quotes, and commas, uses indentation for structure, and lets you add a comment. JSON is more explicit and has fewer ways to go wrong.

Side-by-side comparison

	YAML	JSON
Comments	Yes, with #	No
Structure	Indentation	Braces and brackets
Quoting strings	Optional	Required
Multiline strings	| and > blocks	\n escapes only
References / reuse	Anchors and aliases	No
Multiple documents per file	Yes, separated by ---	No
Data types	Inferred from text (can surprise)	Explicit
Dates	Native timestamp type	Strings
Parser size and speed	Larger, slower	Small, very fast
Browser support	Needs a library	Built in (JSON.parse)
Typical use	Config: Kubernetes, Compose, CI, Ansible	APIs, package manifests, data files

Where YAML wins

• Readability. Less punctuation means the data stands out. Deeply nested config is far easier to scan.
• Comments. You can explain why a setting exists. This alone is why most config formats chose YAML.
• Multiline text. Embedding a shell script or a certificate is clean with a | block. See multiline strings.
• Reuse. Anchors and aliases let you define a block once and reference it many times.

Where JSON wins

• Predictability. A string is always quoted, so "no" can never become false and "1.10" can never become 1.1.
• Ubiquity. Every language parses JSON natively. No dependency, no version differences.
• Speed. JSON parsers are orders of magnitude faster, which matters at API scale.
• No indentation errors. Whitespace is insignificant. YAML files break when a single space is off.

YAML's type inference, the biggest practical difference

Because YAML values are usually unquoted, the parser guesses their type. Most of the time it guesses right. The failure cases are well known:

country: NO        # false in YAML 1.1 parsers (the "Norway problem")
version: 1.10      # float 1.1
zip: 01234         # int 1234, leading zero lost
time: 12:30        # sexagesimal 750 in YAML 1.1
ok: yes            # boolean in YAML 1.1, string in YAML 1.2

JSON has none of these problems because types are explicit. In YAML, quote anything that must stay a string. The YAML parser shows you the inferred type of every value.

Which should you use?

• Configuration edited by hand: YAML. Comments and readability pay for themselves.
• Data exchanged between programs: JSON. Faster, stricter, universally supported.
• The ecosystem already decided: follow it. Kubernetes, Docker Compose, GitHub Actions, and Ansible expect YAML; npm, TypeScript, and most REST APIs expect JSON.

Because YAML 1.2 is a superset of JSON, you never have to commit fully. Convert with the YAML to JSON and JSON to YAML tools whenever you need to switch.