JSON vs YAML vs TOML, Explained

Last reviewed 2026-04-27. Open the JSON parser or JSON to CSV for in-browser JSON work.

The three formats side by side

Same config, three ways:

JSON                        YAML                  TOML
{                           server:               [server]
  "server": {                 host: "localhost"   host = "localhost"
    "host": "localhost",      port: 8080          port = 8080
    "port": 8080
  }
}                                                 

JSON - strict and unambiguous

JSON's design goal was a format that any language could parse identically. The grammar is small (six data types, well-defined whitespace rules). Every parser produces the same tree. That uniformity is why JSON dominates APIs, configuration files for tools that ship with a JSON parser, and machine-to-machine serialization.

Where JSON is awkward: comments are not allowed, trailing commas are syntax errors, and nested deep config gets unreadable for humans. The fix is JSON5 (JSON with comments and trailing commas) for human-edited config, while keeping pure JSON for transport.

YAML - readable, sometimes too clever

YAML reads like outline notes. Indentation creates structure; lists use dashes; values do not need quotes. The fields are short and the file is dense. That is why YAML dominates Kubernetes, GitHub Actions, Docker Compose, and CI configs - all places where humans edit the file daily.

Where YAML hurts: whitespace is significant and tabs break the parser. The string "yes" parses as the boolean true. Norway country code "NO" parses as false. Numbers with leading zeros parse as octal. Multi-line strings have four different syntaxes. The format is human-readable but not human-safe; subtle parse bugs are common in production. The fix is to lint every YAML file in CI and to quote any string that looks like it could be misinterpreted.

TOML - simple, shallow

TOML targets the config-file niche where YAML is too loose and JSON is too verbose. Sections in square brackets, key-value pairs with equals signs, native date and time types. Cargo (Rust's package manager), pyproject.toml in modern Python, and several config tools use it.

Where TOML is awkward: deeply nested data. The syntax for arrays of tables is verbose and not visually obvious. For nesting more than 2-3 levels, YAML or JSON read better. TOML wins when the config is naturally flat - a list of dependencies, a list of build settings, a small set of named sections.

Decision rule

Machine-to-machine: JSON. Human config edited daily, with mostly-flat structure: TOML. Human config edited daily, with deeply nested structure: YAML, with linting in CI. When in doubt, JSON - the strictness is cheap insurance.

For converting between formats, see JSON to CSV or the JSON parser. For other developer tooling, the developer tools hub.