TOML Validator

TOML: Tom's Obvious Minimal Language and the rise of explicit config

TOML stands for Tom's Obvious, Minimal Language, designed by Tom Preston-Werner (co-founder of GitHub and creator of Jekyll) in 2013 as a reaction to the ambiguity of YAML and the verbosity of JSON. The current stable specification is TOML 1.0.0, released in January 2021 after seven years of iteration.

The design goal is crystal clear: a configuration file should be obvious to read for humans and unambiguous to parse for machines, with a 1:1 mapping to a hash table. No significant whitespace, no anchors, no tags — every TOML document can be mentally transformed into an equivalent JSON object without surprises.

Syntax in one minute

A TOML file is a sequence of key = value assignments, optionally grouped into [tables] (nested objects) and [[arrays of tables]] (lists of objects). Comments start with #. Supported types: string (basic, literal and multi-line variants), integer, float (including inf and nan), boolean, RFC 3339 datetime, array and inline table.

title = "TOML Example"

[server]
host = "localhost"
port = 8080

[database]
enabled = true
ports = [8001, 8001, 8002]
connection_max = 5000

[[clients]]
name = "Alice"
[[clients]]
name = "Bob"

Strings can be basic ("..." with escape sequences), literal ('...' with no escaping), or multi-line ("""...""" and '''...''') — perfect for paragraphs of help text in config files.

Where TOML actually shows up

• Rust's Cargo.toml: the canonical project manifest for every Rust crate. Includes dependencies, features, build profiles and workspace settings.
• Python's pyproject.toml: standardized by PEP 518 (2016) for build system requirements, PEP 517 for build backends and PEP 621 for project metadata. Tools like Poetry, Hatch, PDM, Ruff, Black, mypy and pytest read configuration from it.
• Hugo and Zola static sites: config.toml drives the entire build.
• Go's gopls, Helm, Vagrant, cloud-init and dozens of other CLI tools accept TOML.

TOML vs YAML vs JSON vs INI

• vs YAML: TOML is more explicit, has no significant whitespace, and avoids the famous Norway problem (no as boolean). YAML is denser for deeply nested structures.
• vs JSON: TOML allows comments, trailing commas, multi-line strings and explicit datetime types. JSON is universal but spartan.
• vs INI: TOML formalizes types and supports nested tables and arrays of tables. INI is informally specified and varies between implementations.
• vs XML: TOML is dramatically less verbose; XML retains an edge in mixed-content documents.

Parsers and validators by language

• Node.js: @iarna/toml (reference-grade), smol-toml (fast).
• Python: tomllib in the standard library since Python 3.11; tomli for older versions; tomli-w for writing.
• Rust: toml crate (by the language team itself); taplo for formatting and linting.
• Go: BurntSushi/toml, the de facto reference.
• CLI: taplo doubles as a formatter, validator and language server — runs locally and inside many editors.

Best practices for TOML files

• Stable key order: keep keys grouped within a table; reordering creates noisy git diffs.
• Prefer literal strings for Windows paths and regex: no escaping headaches.
• Document with comments: TOML allows them; YAML/JSON culture sometimes forgets they exist.
• Avoid heredoc abuse: if you're stuffing huge blobs into a config file, you probably want a separate asset.
• Run taplo fmt in CI to normalize formatting and surface syntax errors before merge.

FAQ

How does TOML compare to YAML?

TOML is more explicit: no significant whitespace, no implicit type coercion (no Norway problem), no anchors. YAML is denser and more popular generally, especially in the Kubernetes ecosystem, but TOML reads more like an INI file with proper types.

Is TOML mandatory for Python projects?

It's the strong trend. PEP 621 (2020) standardized project metadata in pyproject.toml, and modern tooling (Poetry, Hatch, Ruff, Black, mypy, pytest) reads configuration from there. setup.py still works, but new projects rarely start with it.

Is TOML truly readable?

Yes — Preston-Werner explicitly aimed for the same readability Markdown achieved for prose. Section headers [like.this] map naturally to mental "folders", and key = value is universally familiar.

Does TOML support nested structures?

Yes, via dotted table names ([servers.alpha]) and arrays of tables ([[clients]]). For deeply nested ad-hoc structures, however, JSON or YAML might feel more natural.

What version of TOML should I target?

TOML 1.0.0 (January 2021). Earlier 0.x drafts had subtle differences in datetime parsing and inline-table semantics. Any production parser from 2022 onward speaks 1.0 natively.