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.