Configuration formats are not interchangeable aesthetics. The right one depends on whether machines generate it, humans edit it under pressure, and whether a surprising implicit type can deploy the wrong thing.
Short answer: use JSON for machine-oriented APIs and generated files, TOML for small human-maintained application config, and YAML when an ecosystem requires it—then keep YAML deliberately boring.
| Format | Best at | Most annoying trait |
|---|---|---|
| JSON | APIs, generated config, strict parsers | No comments; punctuation-heavy |
| TOML | Human app settings | Less suited to deeply nested data |
| YAML | Existing infrastructure ecosystems | Indentation and implicit typing surprises |
[server]
port = 8080
allowed_origins = ["https://app.example.com"]
YAML's flexibility is exactly why it needs discipline: quote ambiguous strings, avoid clever anchors, and validate it in CI. A value that looks like a date or boolean should never be a deployment surprise.
Pick the format your consumers already understand, add a schema or startup validation, and fail loudly on unknown or invalid keys. The best configuration format is the one that makes a wrong production value hard to express.
Cover photo by Pixabay on Pexels.