/compare /yaml/json-vs-yaml-vs-toml

JSON vs YAML vs TOML: which format for config and data

updated 2026-10-20

tool: YAML
compares: JSON vs YAML / TOML

Use JSON for data exchanged between programs (APIs, lock files): every language parses it and it has no ambiguity, but it allows no comments. Use TOML for configuration that people edit (pyproject.toml, Cargo.toml): explicit types and comments. Use YAML where the ecosystem expects it (Kubernetes, GitHub Actions, Ansible), and quote values that look like booleans or numbers.

The same data in three formats

bash

cat > app.json <<'EOF'
{"name": "api", "port": 8080, "debug": false, "hosts": ["a.example.com", "b.example.com"], "db": {"user": "app", "pool": 5}}
EOF
cat > app.yaml <<'EOF'
name: api
port: 8080
debug: false
hosts:
  - a.example.com
  - b.example.com
db:
  user: app
  pool: 5
EOF
cat > app.toml <<'EOF'
name = "api"
port = 8080
debug = false
hosts = ["a.example.com", "b.example.com"]

[db]
user = "app"
pool = 5
EOF
python -c "
import json, yaml, tomllib
a = json.load(open('app.json'))
b = yaml.safe_load(open('app.yaml'))
c = tomllib.load(open('app.toml', 'rb'))
print('identical:', a == b == c)
print(a)"

Output

identical: True
{'name': 'api', 'port': 8080, 'debug': False, 'hosts': ['a.example.com', 'b.example.com'], 'db': {'user': 'app', 'pool': 5}}

Criterion by criterion

Criterion	JSON	YAML	TOML
Comments	no	yes (#)	yes (#)
Types	explicit (string, number, bool, null)	inferred: no, on, 1.10 can surprise	explicit, plus dates and times
Deep nesting	braces, verbose but clear	indentation, compact	possible but awkward ([a.b.c] tables)
Multiline strings	escapes only (\n)	\| and > block scalars	triple-quoted strings
Parser in standard libraries	nearly every language	usually a third-party library	Python 3.11+ (tomllib, read-only); others third-party
Typical use	APIs, package.json, lock files	Kubernetes, CI pipelines, Ansible	pyproject.toml, Cargo.toml

Sources

cheat sheets · yamlYAML cheat sheet: syntax, multiline strings and gotchasYAML cheat sheet: maps, lists, scalars, block strings with | and >, anchors and aliases, and the YAML 1.1 traps where no becomes false and 012 is octal.errors · jsonSyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSONJSON.parse fails with Unexpected token '<' when the response is an HTML page, usually an error or login page, not JSON. Check the status and content type first.compat · semverVersion range syntax: ^ and ~ in npm, Cargo, Composer and pipCaret and tilde differ by ecosystem: npm and Composer support ^ and ~, Cargo reads a bare version as a caret range, pip uses ~= from PEP 440. Side by side.

The same data in three formats

Criterion by criterion

Sources

Related pages