JSON vs YAML vs TOML: which configuration format to choose

Between package.json, docker-compose.yml and Cargo.toml you live surrounded by three serialization formats solving the same problem with opposite philosophies. Choosing wrong breaks nothing... until it does: a Norway that YAML turns into a boolean, or a duplicated key silently accepted. This comparison gives you the decision criteria —and the exact traps of each format.

JSON: the lowest common denominator

Designed as a literal subset of JavaScript (though independent today), its virtue is absolute predictability:

{
  "server": {
    "port": 3000,
    "hosts": ["api.mydomain.com"],
    "tls": true
  }
}

• Strict typing: strings, numbers, booleans, null, arrays, objects. Nothing else.
• Duplicated keys: the spec says names SHOULD be unique but doesn't define duplicate behavior — every parser decides. A real trap.
• No comments: the most criticized absence. Creative workarounds ("//": "note") are hacks, not features.
• Mandatory commas between elements and forbidden trailing comma — an eternal source of hand-written syntax errors.

Where it shines: data exchange between systems, APIs, machine-read configuration. Where it hurts: files written and read by humans.

YAML: maximum human comfort, maximum surprise surface

YAML uses significant indentation and lets you write almost without quotes or braces:

server:
  port: 3000
  hosts:
    - api.mydomain.com
  tls: true

Readable and compact, yes. But its implicit type resolution is legendary:

country: NO          # ← boolean false (Norway's country code)
version: 1.30        # ← number; drops the trailing zero if it were 1.10
active: yes          # ← true in YAML 1.1, string in 1.2
id: 08765432X        # parse error on some parsers
octal: 0777          # ← 511 in YAML 1.1 (octal interpretation)

The full gotcha list includes: the Norway problem, duplicated keys silently accepted by many parsers (last wins, or first — implementation dependent), accidental nulls (key: empty = null), and the historic security risk: some parsers allowed arbitrary object instantiation during deserialization (the vector behind the famous Python attack years ago). Defensive rules: always quote strings starting with digits or ambiguous letters, use safe YAML 1.2 parsers, validate in CI.

Also, significant indentation makes copy-paste a risky sport: one extra space restructures the whole tree.

TOML: explicit with zero surprises

Created precisely because "YAML is insanely complicated and comment-less JSON is unbearable", TOML bets on total explicitness:

[server]
port = 3000
tls = true

[server.tls_config]
cert = "/etc/letsencrypt/live/mydomain/fullchain.pem"

[[hosts]]
name = "api.mydomain.com"

• Explicit typing: native ISO dates, typed arrays, [section] tables and [[item]] arrays of tables.
• First-class # comments.
• Duplicated keys = parse error. No ambiguity.
• No significant indentation: reformatting changes nothing.

Its weak point: deeply nested documents become verbose and array-of-tables syntax confuses beginners. It's the de facto standard in Rust (Cargo), modern Python (pyproject.toml) and Go (many tools).

Decision table

Distilled practical rules:

• Data traveling between programs: JSON always.
• DevOps configuration (k8s manifests, workflows): YAML for ecosystem reasons, with a CI validator.
• Project configuration (build tools, dependencies): TOML wherever the ecosystem offers it.
• Never generate YAML by concatenating strings: build structures and serialize; injecting text into YAML is how security bugs are born.

Validate before committing

A format linter prevents 90% of these problems. For JSON, our JSON formatter and validator detects broken syntax, shows the tree and formats on the fly; for conversions from CSV or other sources into JSON, the CSV to JSON converter avoids handwriting them. And if your daily life is Docker Compose, the Compose stack guide shows real working YAML.

FAQ

Can I put comments in JSON? Not in standard JSON. If your tool tolerates them (VS Code settings uses JSONC), it's a private extension, not interoperable. Need comments → use TOML or YAML.

What about XML? Alive in niches (legacy SOAP, Android, Office docs) but for modern configuration it lost to all three: verbose, complex namespaces, heavy parsing.

HJSON or JSON5? JSON extensions with comments and relaxed syntax. Useful internally, dangerous as a public interface: nobody else supports them out of the box.

Format and validate your JSON with our online JSON Formatter, free and right in your browser.