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 vs YAML vs TOML: which config format should you use?

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

JSONYAMLTOML
CommentsNoYes, #Yes, #
Strings need quotesAlwaysUsually notAlways
Nullnullnull or ~No null at all
Dates and timesNo (strings)YAML 1.1 parsers turn 2026-10-01 into a dateFirst-class date and date-time types
Multi-line textEscaped \nBlock scalars | and >Triple-quoted """ strings
NestingBraces, any depthIndentation, any depth[tables] and dotted keys; deep nesting gets verbose
Lists of objects[{…}, {…}]- items[[array.of.tables]]
Several documents in one fileNoYes, ---No
Reuse (anchors)NoYes, &anchor / *aliasNo
Typical homeAPIs, data exchangeKubernetes, CI/CD, Docker Compose, OpenAPICargo.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.

← Blog