JSON vs YAML: differences, traps and when to use each
Updated
A JSON document is almost always a valid YAML 1.2 document. The reverse is where trouble starts: YAML lets you drop the quotes, and then the parser decides what your text means. Here is what differs, where values change meaning, and which format to pick.
The same data in JSON and YAML
{
"service": "billing",
"replicas": 3,
"debug": false,
"regions": ["eu-west-1", "us-east-1"],
"db": { "host": "db.internal", "port": 5432 }
}# billing service
service: billing
replicas: 3
debug: false
regions:
- eu-west-1
- us-east-1
db:
host: db.internal
port: 5432| Feature | JSON | YAML |
|---|---|---|
| Structure | Braces, brackets and commas | Indentation with spaces, or JSON-style {} and [] |
| Strings | Always in double quotes | Plain, single-quoted, double-quoted, or | and > blocks |
| Comments | None | # to the end of the line |
| Reuse | None | Anchors &, aliases *, merge key << |
| Several documents | One value per text | Separated by --- |
| Types | Six, fixed by the syntax | Guessed from unquoted text; 1.1 and 1.2 guess differently |
| Spec | RFC 8259, one version | YAML 1.1 (2005), 1.2 (2009, revised as 1.2.2 in 2021) |
Comments, anchors and several documents
YAML has # comments; JSON has none, and every workaround is a convention (comments in JSON). Converting YAML to JSON drops them. YAML can also reuse a block:
defaults: &defaults
timeout: 30
retries: 3
production:
<<: *defaults
timeout: 60&defaults names the block, *defaults refers to it, and << merges its keys, so production becomes {"timeout": 60, "retries": 3}. The merge key comes from the YAML 1.1 type list and isn’t part of YAML 1.2, but PyYAML, Psych and go-yaml v3 all support it. JSON has no references: in JSON every alias becomes a full copy, which is why converters limit how far aliases may expand. One YAML file can also hold several documents separated by ---, as Kubernetes manifests often do; a JSON text is one value.
The Norway problem: YAML 1.1 vs 1.2
In YAML 1.1, an unquoted yes, no, on or off, in any of their spellings, is a boolean. So a list of country codes [GB, NO, SE] loads as ["GB", false, "SE"]: Norway becomes false. YAML 1.2 cut booleans down to true and false, but many popular readers still implement 1.1. The same unquoted values, loaded by three of them:
country: NO
on: push
python: 3.10
zip: 0123
time: 12:30
exp: 1e3
date: 2026-11-06| Unquoted | PyYAML 6.0.3 (1.1) | Ruby Psych 3.1 (1.1) | go-yaml v3 (1.2) |
|---|---|---|---|
NO | False | false | "NO" |
on as a key | True | true | "on" |
3.10 | 3.1 | 3.1 | 3.1 |
0123 | 83 | 83 | 83 |
12:30 | 750 | 45000 | "12:30" |
1e3 | "1e3" | "1e3" | 1000 |
2026-11-06 | a date | a Date | a time.Time |
Three things follow. YAML 1.2 fixed the booleans, not everything: go-yaml v3 still reads 0123 as the octal number 83 and turns dates into timestamps. Readers of the same version disagree: 12:30 is 750 in PyYAML and 45000 in Psych. And a GitHub Actions file parsed with PyYAML has the key True instead of on. The only rule that works with every reader: if a string could look like anything else, quote it.
Numbers in JSON and YAML
A JSON number has one notation: an optional minus, digits without a leading zero, an optional fraction and exponent. No +, no hex, no NaN or Infinity. RFC 8259 leaves precision to the reader and only warns that beyond 64-bit doubles, interoperability ends. YAML 1.2 adds 0o17, 0x1F, .inf and .nan; YAML 1.1 adds 0b1010, 1_000, base-60 1:30 and octal 017. In both formats a loaded float forgets trailing zeros (1.10 is 1.1), and big integers survive only where the language keeps them: see big numbers in JSON.
How our JSON to YAML keeps values the same
JSON to YAML writes a string without quotes only when no YAML 1.1 or 1.2 reader can read it as something else. It quotes the words yes, no, on, off, y, n, true, false, null and ~ in any case; strings that start with a digit, +, . or a YAML indicator such as -, [, & or *; empty strings; strings with leading or trailing spaces, : or # inside. Multi-line strings become | blocks. Numbers are copied exactly as written, and keys keep their order. This JSON:
{"country": "NO", "enabled": "on", "python": "3.10", "zip": "0123",
"time": "12:30", "date": "2026-11-06", "version": 3.10, "exp": 1e3,
"note": "line one\nline two", "plain": "hello world"}country: "NO"
enabled: "on"
python: "3.10"
zip: "0123"
time: "12:30"
date: "2026-11-06"
version: 3.10
exp: 1e3
note: |-
line one
line two
plain: hello worldOne caveat, said plainly: numbers keep their JSON notation, so 1e3 stays 1e3. A YAML 1.2 reader sees the number 1000; a YAML 1.1 reader such as PyYAML or Psych sees the string "1e3", because 1.1 floats need a dot. The other direction is YAML to JSON: it reads YAML by 1.2 rules, so an unquoted no stays the string "no".
When to choose JSON and when YAML
- JSON for data between programs: API requests and responses, logs, storage, generated files. A parser ships with most languages, and a strict validator catches every typo.
- JSON when values must survive exactly. There are no implicit types:
"no"is always a string and"0123"always keeps its zero. - YAML for files people write and review: Kubernetes manifests, CI pipelines, Docker Compose, OpenAPI specs. Comments, multi-line strings and anchors pay for themselves there.
- YAML with discipline: quote strings that look like booleans, numbers or dates, indent with spaces only, and load untrusted files with a safe loader (
yaml.safe_loadin Python, notyaml.load).
Need both? Keep the source in one format and generate the other: JSON to YAML for configs that tools produce, YAML to JSON to see what a YAML file actually means before it reaches production.
JSON vs YAML FAQ
Is JSON valid YAML?
For YAML 1.2, almost always: the spec made JSON a subset on purpose. Edge cases are duplicate keys, which YAML forbids (go-yaml v3 fails with mapping key "a" already defined, PyYAML keeps the last value), and the \/ escape, which go-yaml v3 rejects.
Why does YAML read no as false?
Your YAML reader follows YAML 1.1, where yes, no, on and off are booleans. Quote the value ("NO") or switch to a YAML 1.2 reader.
What happens to comments and anchors in YAML to JSON?
Comments are dropped: JSON has no place for them. Every alias is expanded into a full copy, and merge keys << become ordinary keys.
Can I indent YAML with tabs?
No. YAML forbids tabs in indentation; PyYAML stops with found character '\t' that cannot start any token. Use spaces. Tabs inside quoted strings are fine.