Configuration files are written by people and read by programs, and the format you pick affects both. JSON, YAML and TOML are the three most common options for modern projects. Each makes a different trade-off.
The same configuration three ways
JSON:
{
"title": "Docento",
"debug": false,
"server": { "host": "localhost", "ports": [80, 443] }
}
YAML:
title: Docento
debug: false
server:
host: localhost
ports: [80, 443]
TOML:
title = "Docento"
debug = false
[server]
host = "localhost"
ports = [80, 443]
Comparison
| JSON | YAML | TOML | |
|---|---|---|---|
| Comments | No | Yes | Yes |
| Whitespace matters | No | Yes (indentation) | No |
| Quoting strings | Always | Often optional | Always |
| Date and time types | No | Depends on version and parser | Yes, built in |
| Deep nesting | Fine | Fine | Gets awkward |
| Implicit type surprises | None | Several | Few |
| Spec complexity | Small | Large | Small |
| Hand-editing comfort | Low | High | High |
| Parser availability | Everywhere | Very wide | Wide and growing |
JSON for config
Strengths: supported by every language, unambiguous, easy to generate, and trivially validated.
Weaknesses: no comments, strict about trailing commas and quotes, and noisy to read. Fine when files are generated; tiresome when a human edits them. Variants such as JSONC add comments but only for tools that accept them; see JSON with comments.
YAML for config
Strengths: very readable for nested data, supports comments, multiline strings and reuse through anchors. It is the convention for many CI and infrastructure tools.
Weaknesses: indentation is syntax, so alignment errors break files; unquoted values are guessed, so NO or 3.10 can change meaning; and the specification is large, with parsers that disagree in edge cases. See YAML gotchas.
TOML for config
Strengths: reads like an INI file with proper types. No indentation rules, explicit strings, native dates, comments, and errors on duplicate keys. Very hard to misread.
Weaknesses: deeply nested structures and large arrays of records become verbose. It is a configuration format, not a general data interchange format, and some ecosystems have fewer tools for it.
How to choose
- A small or medium settings file edited by people: TOML is a strong default.
- Complex, deeply nested configuration, especially where the ecosystem already uses it: YAML, with quoting discipline and validation.
- Machine-generated or machine-consumed data: JSON.
- Whatever the tool requires. If your build tool reads
pyproject.tomlor a.ymlpipeline file, the choice is made for you.
Practical advice for any format
- Validate on every edit. Docento's Text & Markdown Editor checks JSON, YAML and TOML syntax and shows the line of the first error.
- Validate the schema too, which a syntax check cannot do.
- Keep secrets out of config files that go into version control.
- Comment the reasons, where the format allows.
Converting
Because all three describe maps, lists and scalars, conversion is usually straightforward. Comments, anchors, and TOML's date types do not survive a trip through JSON, and TOML cannot express a null.
Takeaway
Choose TOML for hand-edited settings with simple structure, YAML for complex nested configuration where it is the ecosystem standard, and JSON for machine-to-machine data. Whichever you pick, validate before you commit.
