JSON vs YAML vs TOML: Configuration Format Comparison & Selection Guide

The Verdict First: Choose by Scenario

There is no "best format", only "which one is least likely to bite in this scenario". Decision order: high-frequency machine exchange → JSON; human-maintained config → pick by depth, TOML for shallow and YAML for deep; either way it can be converted to JSON for the program. One engineering constraint on top: choose a format your toolchain can validate—config that lints in CI is more reliable than a theoretically elegant format nobody will actually write.

JSON: The Lingua Franca of Machine Exchange

JSON's advantage comes from its limits: small grammar, fast parsing, an implementation in every language, and no inferential tolerance—the same text yields the same result everywhere. The price is that humans have nowhere to record "why this value", so explanations live in an extra _comment field or in repository docs. Conversely, config that needs heavy commenting and frequent hand edits should not be JSON: _comment cannot hold an inline note and may be read downstream as a business field. Number precision is the old trap too: IDs beyond 2^53 get rewritten by floating point (mechanism in the complete JSON guide), so large integer keys in config must be strings.

YAML: Human Config, With Guaranteed Pitfalls

YAML expresses hierarchy by indentation and supports comments, anchors and multiple documents, reading almost like a natural-language checklist. Anchors reuse one structure (&default to define, *default to reference) and cut duplication, but they expand into copies, leaving downstream no trace that two places shared a source. The price is implicit typing: unquoted values are guessed by the parser. This is not "might go wrong"—it will.

Forms That Always Break

Form Parsed result
version: 1.10 number 1.1; the trailing zero disappears
enabled: no boolean false (YAML 1.1 literal)
country: NO boolean false (the Norway problem)
port: 0800 512 (octal in YAML 1.1)
Tab indentation parse failure; YAML accepts spaces only
Duplicate keys at one level forbidden by spec; parsers error or last-wins
Misaligned multi-line block attaches to the parent, the value is swallowed

One rule covers most of it: quote anything whose meaning is a string. The other two (tabs, alignment) are solved by turning on whitespace rendering in the editor.

TOML: Config for Shallow Trees

TOML uses [section] and key = value; hierarchy comes from table headers rather than indentation, so no amount of missing spaces silently reparents a value. It has native date-times, comments, clear arrays and deterministic parsing; it has no null, and deeply nested arrays need [[table]] expansion, getting verbose fast. To express "unset", omit the key and let the consumer fall back to a default; substituting an empty string or a sentinel conflates "not configured" with "configured as empty".

The Same Config, Three Ways

# YAML: indentation is hierarchy, comments inline
server:
  host: "0.0.0.0"
  port: 8080
  features: ["cache", "metrics"]
# TOML: headers define hierarchy, types explicit
[server]
host = "0.0.0.0"
port = 8080
features = ["cache", "metrics"]
{"server":{"host":"0.0.0.0","port":8080,"features":["cache","metrics"]}}

Same content: JSON is shortest but carries no comments; YAML reads most like a document but depends on indentation; TOML sits between them and starts repeating headers as depth grows.

Comparison

Dimension JSON YAML TOML
Readability Good Best Good
Comments ❌ ✅ ✅
Explicit types ✅ ❌ (implicit) ✅
Hierarchy braces indentation table headers
Date-time string string native type
null ✅ ✅ ❌
Parse speed Fast Slow Fast
Typical use API / storage K8s / CI / complex config Project config (Cargo, pyproject)

What Conversion Loses

Information After conversion to JSON
Comments Nowhere to live; lost outright
Key order Not guaranteed; may be rearranged on round trip
Anchors and references Expanded into duplicated copies; cannot be restored
Date-time type Becomes a string; type information lost

So conversion suits a one-way handoff to a program, not round-trip editing of config. To keep comments and structure, maintain them in YAML/TOML and convert at runtime.

Reproducible Results

Implicit typing is not folklore; two Python lines reproduce it (PyYAML required):

import yaml
print(yaml.safe_load("version: 1.10"))   # → {'version': 1.1}
print(yaml.safe_load("enabled: no"))     # → {'enabled': False}
print(yaml.safe_load('version: "1.10"')) # → {'version': '1.10'}  quoting keeps the string

The three outputs map to three endings: the number is rewritten, the boolean is inferred, quoting is the only safe move. Expand the same config with YAML to JSON and a JSON formatter side by side to see how each format reads the same text.

Frequently Asked Questions

What is the core difference between the three formats?

In one line: JSON is built for machine interchange, YAML for human authoring, TOML for configuration files. JSON has strict syntax, no comments, and universal native support. YAML expresses hierarchy through indentation and supports comments and anchors, but indentation errors and type inference are constant traps. TOML uses explicit table headers in square brackets, making both types and hierarchy obvious — a good fit for mid-to-large config files.

What is the YAML Norway problem?

Under YAML 1.1, no, yes, on and off are inferred as booleans, so the country code NO for Norway parses as false. By the same rule the version string 1.10 becomes the float 1.1. The fix is to quote such values: 'NO' or '1.10'. YAML 1.2 narrowed the boolean literals, but many parsers still follow 1.1 behaviour, so do not gamble on it.

What gets lost when converting between them?

Three kinds of information are lost most often: comments (JSON has none, so they vanish in both directions), key order (JSON objects are theoretically unordered, so a YAML round-trip may reshuffle keys), and data types (YAML datetimes and binary blobs degrade to strings in JSON, and long integers can lose precision). Before converting, check whether the target format actually needs to carry that information — do not assume a round-trip is lossless.

Should a project standardise on just one?

No — split by purpose: JSON for external APIs and data interchange, YAML for hand-written infrastructure config (Kubernetes, CI), and TOML or JSON for an application's own settings. Forcing uniformity usually costs more friction than it returns. For conversions, use the [YAML to JSON](/yaml-to-json.html), [JSON to YAML](/json-to-yaml.html) and [TOML to JSON](/toml-to-json.html) tools.

← Back to Blog