Choosing a configuration format: JSON, YAML or TOML

What it is

JSON as defined in RFC 8259 has objects, arrays, strings, numbers, true, false and null, and no comments. The RFC says that names within an object SHOULD be unique, and that the behavior of software receiving duplicate names is unpredictable: some implementations report only the last pair, others report an error. According to its specification, YAML 1.2 was designed with the main goal of being a strict superset of JSON, and it removed many of the problematic implicit-typing recommendations. In the Core Schema, unquoted scalars are still resolved by pattern, so true, True and TRUE are booleans, while loaders following the older 1.1 model also treat yes, no, on and off that way. TOML 1.0 states its own goal as a minimal configuration format that is easy to read thanks to obvious semantics and maps unambiguously to a hash table. It has comments, explicit types (string, integer, float, boolean, date and time), tables in square brackets, dotted keys, and inline tables that are meant to stay on one line.

Why it matters

A configuration file is written by people and read by programs, and the format determines at which end the errors occur. Indentation mistakes and silent type coercion are the YAML class of errors (version: 1.10 becomes the number 1.1, and the country code NO becomes false in a 1.1 loader). Missing comments and duplicate keys are the JSON class of errors. With TOML, deep nesting forces long table paths.

How to apply

• Machine to machine (APIs, caches, exports): use JSON, validated against a JSON Schema.
• Hand-maintained configuration with a flat to moderately nested structure: use TOML. Python (pyproject.toml), Rust (Cargo) and many tools use it.
• Use YAML where the ecosystem prescribes it (CI pipelines, Kubernetes, Compose): quote strings that look like numbers, booleans or times; choose a loader that follows the 1.2 Core Schema; do not load custom tags.
• Regardless of format, convert the parsed result into a typed model, reject unknown keys, and abort with a clear message (file, line, key).
• When switching formats, convert with a tool and compare the parsed results of both files, not the text.

Pitfalls

According to the RFC, a JSON parser may accept extensions; comments or trailing commas that one tool tolerates will cause the next tool to fail. YAML anchors and multi-document files are hard for people to review. TOML inline tables do not allow a trailing comma. 1e3 is a float in the YAML 1.2 Core Schema but a string in 1.1 loaders, which is one more reason to quote.