# JSON vs YAML: differences, traps and when to use each

> Learn how JSON vs YAML really differ: syntax, comments, anchors, the YAML 1.1 Norway problem, numbers, and when to choose which format.

- URL: https://jsonstatham.dev/guides/json-vs-yaml/
- Language: English (en)
- Russian version: https://jsonstatham.dev/ru/guides/json-vs-yaml.md
- Updated: 2026-11-08

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

```json
{
  "service": "billing",
  "replicas": 3,
  "debug": false,
  "regions": ["eu-west-1", "us-east-1"],
  "db": { "host": "db.internal", "port": 5432 }
}
```

```yaml
# 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](https://jsonstatham.dev/guides/json-comments/)). Converting YAML to JSON drops them. YAML can also reuse a block:

```yaml
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:

```yaml
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](https://jsonstatham.dev/guides/json-big-numbers/).

## How our JSON to YAML keeps values the same

[JSON to YAML](https://jsonstatham.dev/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:

```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"}
```

```yaml
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 world
```

One 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](https://jsonstatham.dev/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_load` in Python, not `yaml.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.
