JSON vs YAML vs TOML: which config format should you use?
The same config in JSON, YAML and TOML, compared on comments, types, dates, nesting and tooling, with a clear rule for when each format fits.
Comparisons By Convert JSON to YAML Team
JSON, YAML and TOML all describe the same kind of data: maps, lists, strings, numbers and booleans. They differ in who they were designed for, and that shows up in every detail, from comments to dates. Here is one small service config in all three.
{
"name": "web-api",
"port": 8080,
"debug": false,
"database": { "host": "db.internal", "pool": 10 },
"allowed_origins": ["https://example.com", "https://admin.example.com"]
}
# YAML: indentation instead of braces, comments allowed
name: web-api
port: 8080
debug: false
database:
host: db.internal
pool: 10
allowed_origins:
- https://example.com
- https://admin.example.com
# TOML: key = value pairs, sections in [brackets]
name = "web-api"
port = 8080
debug = false
allowed_origins = ["https://example.com", "https://admin.example.com"]
[database]
host = "db.internal"
pool = 10
The comparison
| JSON | YAML | TOML | |
|---|---|---|---|
| Comments | No | Yes, # | Yes, # |
| Strings need quotes | Always | Usually not | Always |
| Null | null | null or ~ | No null at all |
| Dates and times | No (strings) | YAML 1.1 parsers turn 2026-10-01 into a date | First-class date and date-time types |
| Multi-line text | Escaped \n | Block scalars | and > | Triple-quoted """ strings |
| Nesting | Braces, any depth | Indentation, any depth | [tables] and dotted keys; deep nesting gets verbose |
| Lists of objects | [{…}, {…}] | - items | [[array.of.tables]] |
| Several documents in one file | No | Yes, --- | No |
| Reuse (anchors) | No | Yes, &anchor / *alias | No |
| Typical home | APIs, data exchange | Kubernetes, CI/CD, Docker Compose, OpenAPI | Cargo.toml, pyproject.toml, Hugo |
JSON: the safest for machines
JSON’s grammar fits on a business card, and every language ships a parser. There is no type guessing: a string is
always quoted, so "NO" is never a boolean. That strictness is why APIs and data files use it. The cost is
readability: no comments, and a lot of punctuation for people to scan past.
Use JSON when a program writes the file and another program reads it, or when you exchange data over HTTP.
YAML: the most readable, with sharp edges
YAML is the most pleasant to read and edit by hand, and it handles deep nesting, long text and repeated blocks
(anchors) well. That is why Kubernetes, GitHub Actions and Docker Compose chose it. Its weakness is the flip side of
optional quotes: the parser guesses types. In YAML 1.1 parsers, no is false, 1.10 is the number 1.1 and
22:22 is a base-60 integer. Our article on YAML gotchas covers each case.
Use YAML for configuration that people maintain, especially deeply nested or multi-document files, and keep ambiguous strings quoted.
TOML: explicit and flat
TOML (stable since version 1.0.0 in 2021) aims for an obvious mapping to a hash table. Strings are always quoted, so there is no type guessing, and dates are real types. Comments are allowed. It shines for flat or two-level configuration such as package manifests. It becomes awkward for deep nesting, and it has no null: a missing key is the only way to say “no value”.
Use TOML for application and package settings that are mostly flat and edited by hand, when the ecosystem already expects it (Rust’s Cargo, Python’s pyproject.toml).
Converting between them
- JSON to YAML is lossless. YAML 1.2 is a superset of JSON, so every JSON document has an exact YAML equivalent. The JSON to YAML converter also quotes strings that YAML would otherwise misread.
- YAML to JSON is lossless for data, but comments are dropped and anchors are expanded into copies. Use the YAML to JSON converter.
- JSON or YAML to TOML can lose information. TOML has no null, its root must be a table (not a list), and multi-document YAML has no TOML equivalent. Check those three points before converting.
The short rule
Machines on both ends: JSON. People editing nested config: YAML, with quotes where values could be misread. People editing flat settings in an ecosystem that expects it: TOML.