Comparisons Development

TOML vs YAML vs JSON

Three configuration formats compared: comments, readability, data types, pitfalls and typical uses, with the same configuration written in all three and checked to parse to identical data.

Last reviewed:

AdSense Placeholder
Slot: header_reference_page
On this page

The same settings can be written in TOML, YAML or JSON. The three examples below hold identical data: parsed with Python's tomllib, PyYAML and json, they produce equal results. Convert between them with the TOML to JSON Converter, the JSON to TOML Converter, the JSON to YAML Converter and the YAML to JSON Converter.

The same configuration three ways

TOML

title = "Demo"
debug = false
ports = [8000, 8001]

[database]
host = "localhost"
max_connections = 50

YAML

title: Demo
debug: false
ports: [8000, 8001]
database:
  host: localhost
  max_connections: 50

JSON

{
  "title": "Demo",
  "debug": false,
  "ports": [8000, 8001],
  "database": {
    "host": "localhost",
    "max_connections": 50
  }
}

At a glance

TOML YAML JSON
Comments Yes (#) Yes (#) No
Structure Tables and keys; no indentation rules Indentation Braces and brackets
Dates and times Native types Native (version-dependent) Strings only
Trailing commas Allowed in arrays Not applicable Not allowed
Duplicate keys Error Parser-dependent Parser-dependent
Null value None null or ~ null
Best for Hand-edited configuration Large nested configuration and manifests Data exchange and APIs

Pitfalls

  • YAML 1.1 parsers (PyYAML, many older tools) read NO as false, 01234 as the number 668 (octal) and 12:30 as 750 (base 60). Quote anything meant to stay a string.
  • JSON has no comments and many parsers store numbers as doubles, so 9007199254740993 becomes 9007199254740992 in JavaScript.
  • TOML is awkward for deeply nested data and for long arrays of mixed objects; repeating doubled-bracket table headers gets verbose.
  • Duplicate keys are an error in TOML and silently overwritten in some YAML and JSON parsers.

Which to choose

  • Hand-written application settings: TOML.
  • Kubernetes manifests, CI pipelines and other ecosystems built on it: YAML.
  • Browser, API and machine-to-machine data: JSON. Check that a document is valid with the JSON Validator & Online Debugger.

Try these tools

TOML to JSON Converter

Convert TOML to JSON online.

JSON to TOML Converter

Convert JSON to TOML online.

JSON to YAML Converter

Convert JSON data into clean, indented YAML instantly in your browser.

YAML to JSON Converter

Convert YAML configuration files into standard JSON instantly in your browser.

JSON Validator & Online Debugger

Check if your JSON is valid according to RFC 8259 standards.

See also

  • Cheat sheet TOML Syntax Cheat Sheet
    Every TOML value type, tables, arrays of tables, dotted keys, strings and dates on one page.
  • Cheat sheet YAML Syntax Cheat Sheet
    Quick reference for YAML: scalars, strings, lists, mappings, multi-line text, anchors.
  • Comparison JSON vs YAML vs XML
    JSON for APIs and data exchange, YAML for hand-edited configuration, XML for documents and schema-heavy standards.
  • Glossary TOML
    TOML is a small configuration file format with clear types and sections.
  • Glossary YAML
    YAML is a human-friendly data format that uses indentation instead of brackets, popular for configuration files.
  • Guide How JSON Works
    The six JSON value types, why parsing fails, traps with big integers and key order, JSONPath queries and converting JSON to TypeScript.

Frequently Asked Questions

For a hand-edited file, TOML is the safest choice: it is small, strict and allows comments. YAML suits deeply nested files already tied to YAML tools such as Kubernetes. Use JSON for data exchanged between programs.

Older YAML 1.1 parsers turn unquoted words such as NO into booleans, read 01234 as octal and 12:30 as a number. Quote strings that must stay text.

Back to the comparisons
AdSense Placeholder
Slot: footer_leaderboard