TOML vs JSON vs YAML for config files

Pick a configuration format and you inherit its trade-offs for the life of the project. The TOML vs YAML debate, with JSON as the third option, comes up every time a new tool needs a config file. Each format optimises for something different, so the right choice depends on who edits the file and what consumes it.

What each format optimises for

JSON optimises for machines. It maps directly onto data structures, parses everywhere and has a tiny specification, which makes it the perfect interchange format. It is a poor hand-edited config format though, because it forbids comments, demands quotes around every key then rejects trailing commas. YAML optimises for human readability, stripping punctuation down to indentation so a config reads almost like prose. TOML optimises for low surprise: readable like YAML, but with explicit structure and types so the file means exactly what it looks like it means.

YAML's two sharp edges

YAML is the most pleasant to read until two features turn on you. The first is significant whitespace: a single misaligned space changes the structure and the error message rarely points at the real line. The second is implicit typing, the famous case where an unquoted no or off becomes a boolean and a value like 1.0 becomes a float when you wanted a string. These are not bugs in YAML—they are deliberate conveniences—but they cause a steady drip of subtle config errors that are hard to spot in review.

Why TOML gained ground

TOML answered exactly those pain points. There is no significant whitespace, so structure comes from explicit [table] headers rather than indentation. Types are explicit, so a string stays a string and TOML even has first-class dates. The result is config that means what it appears to mean, which is why a wave of modern tooling adopted it. The trade-off is verbosity: deeply nested data is clunkier in TOML than in YAML, so it suits flat-to-moderate config better than sprawling hierarchies. For a deeper tour see what is TOML.

Converting between the three

Because all three describe the same shapes—objects, arrays and scalars—moving between them is routine rather than fraught. Teams commonly write config in TOML or YAML for humans then convert to JSON for a tool that only speaks JSON. The lossy corners are predictable: comments survive only in TOML and YAML and native dates survive only in TOML. The TOML to JSON converter handles one leg in your browser and the YAML ⇄ JSON converter handles the other, with the JSON formatter to tidy whatever comes out.

Frequently asked questions

Is TOML better than YAML for config?
TOML is harder to misread because it avoids significant whitespace and implicit typing, YAML's two main bug sources. YAML is more compact for deep nesting. For human-edited flat config, many teams now prefer TOML.

Why does JSON make a poor config format?
It has no comments, requires quoting every key and forbids trailing commas, so hand-edited config is noisy. It shines as machine interchange instead.

Bottom line

The TOML vs YAML choice, with JSON in the mix, is about who edits the file. Use JSON for machine interchange, YAML for compact or deeply nested config you trust yourself to indent and TOML when you want explicit, comment-friendly, low-surprise settings. Convert at the boundary with the TOML to JSON converter and no single format locks you in.