Comparison to JSON and YAML

The feature matrix

Ambiguity is the real difference

TOML and JSON have no type coercion. A value's type is determined entirely by its syntax, and there is no set of characters that means one thing to one parser and another to the next.

# YAML: every one of these is a trap
country: NO         # false under a 1.1 parser
mode: 0644          # 420 under a 1.1 parser
version: 1.10       # the float 1.1
time: 12:30         # 750 under a 1.1 parser

# TOML: syntax decides, nothing infers
country = "NO"      # a string, always
mode = 0o644        # 420, explicitly octal
version = "1.10"    # a string, always
time = 12:30:00     # a local time, seconds required

TOML also has no duplicate-key ambiguity. Redefining a key or a table is an error, so a config never silently loses a value. YAML's answer varies by parser, and PyYAML's answer is to keep the last one silently.

Where each one wins

TOML's design goal is a config file that is obvious to a human reading it without the spec open. That trade shows up as verbosity once you nest deeply, which is the one genuine argument for YAML.

The nesting cost

TOML's headers stop paying off around four levels. Compare a Kubernetes-shaped document:

spec:
  template:
    spec:
      containers:
        - name: api
          image: api:1.2
          resources:
            limits:
              cpu: 500m

[[spec.template.spec.containers]]
name = "api"
image = "api:1.2"

[spec.template.spec.containers.resources.limits]
cpu = "500m"

The TOML is valid and produces the same structure, but the second header repeats six segments and gives no visual clue that it belongs to the container above it. This is exactly why Kubernetes is YAML and pyproject.toml is TOML.

Who uses what

Python packaging moving to TOML in PEP 518 and PEP 621 is the single biggest reason TOML matters today. tomllib landed in the standard library in Python 3.11.

Reading and converting

import tomllib

with open("pyproject.toml", "rb") as f:   # note "rb", bytes not text
    cfg = tomllib.load(f)

print(cfg["project"]["name"])

# TOML -> JSON
yq -p toml -o json '.' pyproject.toml
python -c "import tomllib,json,sys; \
  print(json.dumps(tomllib.load(sys.stdin.buffer), default=str))" < pyproject.toml

tomllib.load requires a binary file object. Passing a text-mode file raises TypeError: File must be opened in binary mode. tomllib.loads takes a str, and the standard library ships no TOML writer, so use tomli-w for plain output or tomlkit when you need to edit a file and preserve its comments and formatting.