JSON vs YAML vs TOML: Which Config Format Should You Use?
6minYour config format is a contract between you and your team. JSON is everywhere but fights comments; YAML reads beautifully until indentation eats a day; TOML is friendly but young.
The choice is rarely about what is possible: all three can express the same data. It is about what your team reads, writes, and debugs most comfortably.
JSON
Universal, strict, no comments. The interchange format everything else must interoperate with.
YAML
Human-first, indentation-based, comments supported. Powerful but famously footgunny around type inference.
TOML
INI done right: brackets, key-value pairs, explicit types, comments. Minimal syntax, harder to write deeply nested structures.
| Aspect | JSON | YAML | TOML |
|---|---|---|---|
| Comments | No | Yes | Yes |
| Typing | Explicit: strings, numbers, booleans, null | Implicit: "yes" can become true, "0123" can become 123 | Explicit, with typed date and time literals |
| Deep nesting | Natural | Natural (indentation) | Painful: every level adds brackets |
| Tooling everywhere | Yes: every language has a parser | Yes, but parser quirks differ between implementations | Yes, and implementations are stricter about spec compliance |
| Multi-line strings | Awkward (\n escapes) | Excellent (literal blocks) | Good (""" or """) |
| Config files in the wild | package.json, tsconfig, .eslintrc | docker-compose, GitHub Actions, Kubernetes manifests | Cargo.toml, pyproject.toml, Go modules |
Use JSON when the file is generated or consumed by tools: it is the only format with zero ambiguity. Use YAML when humans hand-write complex nested configs (CI pipelines, infra). Use TOML for flat, comment-friendly settings files that users will open and edit. When in doubt, prefer the format your ecosystem already standardized on: fighting Cargo.toml or package.json conventions is a losing battle.
- •YAML: values like "yes", "no", "on", "off", and leading zeros being silently coerced into booleans or numbers.
- •YAML: mixing tabs and spaces for indentation: invalid in the spec, confusing in every parser.
- •JSON: trying to add comments to config and breaking the parser: use JSONC or move to TOML/YAML instead.
- •TOML: using it for deeply nested structures and ending up with bracket soup that is harder to read than JSON.