TOML vs JSON vs YAML for config files
Comparing TOML, JSON and YAML for configuration—readability, comments, data types and failure modes—so you can pick the right format and convert between them.
Quick Answer
JSON is universal but has no comments and is fussy to hand-edit. YAML is highly readable but its whitespace and implicit typing cause subtle bugs. TOML aims for the middle: readable, commentable and explicit, which is why modern tooling adopted it. Convert between them at the boundary.
Search Snapshot
- Format
- Engineering
- Reading time
- 4 min
- Last updated
- June 12, 2026
- Primary topic
- TOML vs YAML
- Intent
- informational
Key Takeaways
Point 1
JSON is the machine lingua franca but a poor hand-edited config format—no comments.
Point 2
YAML reads beautifully but its indentation and implicit typing invite subtle errors.
Point 3
TOML trades some brevity for explicit, comment-friendly, low-surprise config.
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.
| Feature | TOML | JSON | YAML |
|---|---|---|---|
| Comments | Yes | No | Yes |
| Data types | Explicit (incl. dates) | Explicit (no dates) | Implicit, can surprise |
| Significant whitespace | No | No | Yes |
| Hand-editing | Pleasant | Awkward | Pleasant until it bites |
| Deep nesting | Verbose | Verbose | Compact |
| Best role | App config | Machine interchange | Config and pipelines |
TOML, JSON and YAML across the things that matter for config.
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.
Get new playbooks weekly
Actionable guides, market updates and shipping notes — once a week.