Validateur et Formateur TOML

What is TOML?

TOML (Tom's Obvious Minimal Language) is a configuration file format designed to be easy to read and write due to its clear, minimal semantics. Created by Tom Preston-Werner (co-founder of GitHub), TOML maps unambiguously to a hash table and is intended to be parsed into data structures across a wide variety of languages. Unlike JSON, which was designed for data interchange between machines, or YAML, which prioritizes human readability at the cost of complexity, TOML occupies a deliberate middle ground: it is simple enough for humans to author by hand yet strict enough that parsers can implement it without ambiguity. The TOML specification reached version 1.0 in January 2021, establishing a stable foundation for tooling and library support across all major programming languages.

This tool validates TOML documents against the official specification, reports syntax errors with precise line and column information, and formats valid TOML into a consistent, readable style. Whether you are editing a Cargo.toml for Rust, a pyproject.toml for Python, or a Hugo site configuration, this validator ensures your file conforms to the spec before deployment.

TOML Syntax: Core Data Types and Structures

TOML defines a rich set of native data types that map directly to common programming language constructs. Strings support four forms: basic (double-quoted with escape sequences), multi-line basic (triple double-quoted), literal (single-quoted, no escaping), and multi-line literal (triple single-quoted). Integers support decimal, hexadecimal (0x), octal (0o), and binary (0b) notation, with optional underscores as visual separators (e.g., 1_000_000). Floats follow IEEE 754 double precision and support inf and nan as special values.

Tables are the primary structuring mechanism in TOML, defined by headers enclosed in square brackets. A table header like [database] creates a named hash map that groups related key-value pairs. Dotted keys allow nested access without explicit table headers: server.host = "localhost" is equivalent to defining a [server] table with a host key. Arrays of tables use double brackets ([[products]]) to define repeated structured entries — a pattern heavily used in Cargo.toml for specifying multiple dependencies or build targets.

Inline tables provide compact syntax for small groupings: point = { x = 1, y = 2 }. Unlike standard tables, inline tables must appear on a single line and cannot be extended after definition. TOML also natively supports RFC 3339 datetime values, including offset date-times (2024-01-15T10:30:00Z), local date-times, local dates, and local times — a feature absent from both JSON and YAML without custom extensions.

TOML vs YAML vs JSON: Choosing the Right Format

Each configuration format serves a different design philosophy. JSON excels at machine-to-machine data interchange: it is universally supported, strictly defined by RFC 8259, and trivial to parse. However, JSON lacks comments, requires quoting all keys, and uses verbose syntax for nested structures — making it awkward for hand-edited configuration files. YAML prioritizes human readability with its indentation-based structure, but this introduces significant complexity: implicit type coercion (the infamous Norway problem where NO becomes boolean false), significant whitespace sensitivity, and multiple ways to express the same structure (flow vs block style) create subtle bugs in production configurations.

TOML avoids both extremes. It requires explicit typing (no implicit coercion), uses unambiguous syntax (no significant whitespace), supports comments (with #), and provides native datetime support. The trade-off is that TOML is less suitable for deeply nested hierarchies — documents with more than 3-4 levels of nesting become harder to read than their YAML equivalents. For configuration files, which typically have shallow structures with well-defined schemas, TOML is an excellent fit.

Feature	TOML	YAML	JSON
Comments	Yes (#)	Yes (#)	No
Native datetimes	Yes (RFC 3339)	Partial	No
Implicit type coercion	No	Yes	No
Multi-line strings	Yes (4 forms)	Yes	No
Deep nesting	Awkward	Natural	Verbose
Trailing commas	Allowed (arrays)	N/A	No

Common Use Cases and Ecosystem

TOML has become the standard configuration format for several major ecosystems. In Rust, Cargo.toml defines package metadata, dependencies, build profiles, and workspace configuration. In Python, pyproject.toml (defined in PEP 518 and PEP 621) has replaced setup.py and setup.cfg as the standard project configuration file, used by tools like pip, poetry, flit, and hatch. Hugo, the popular static site generator written in Go, supports TOML as its primary configuration format. The Go module system also uses TOML-inspired syntax in go.sum and related files.

Other notable adopters include Deno (for deno.json alternatives), Pipenv (Pipfile uses TOML), Black (the Python formatter), and numerous CI/CD systems. The format's deterministic parsing guarantees make it ideal for configuration that must behave identically across different tools and platforms — a property that YAML's complex specification cannot always guarantee.

Validation Rules and Common Errors

TOML validation goes beyond basic syntax checking. A conformant validator enforces several semantic rules: table headers cannot be defined more than once, keys within a table must be unique, inline tables cannot be extended after their initial definition, and arrays of tables must not conflict with static table definitions. These rules prevent ambiguous configurations that could be interpreted differently by different parsers.

Common errors encountered when writing TOML files include: using tabs for indentation in multi-line basic strings (tabs are allowed only at the beginning of lines in multi-line literal strings), forgetting that bare keys can only contain ASCII letters, digits, dashes, and underscores (keys with spaces or special characters must be quoted), attempting to add keys to an inline table after its definition, mixing array-of-tables syntax with regular table syntax for the same path, and using invalid datetime formats (TOML requires strict RFC 3339 compliance — no short forms like 2024-1-5).

This tool reports validation errors with precise line numbers, column positions, and contextual suggestions to help you fix issues quickly. The formatter normalizes whitespace, aligns values within tables for readability, and orders sections consistently.

Code Examples

A complete Cargo.toml configuration for a Rust project

# Package metadata
[package]
name = "my-web-server"
version = "0.3.1"
edition = "2021"
authors = ["Alice <alice@example.com>"]
description = "A fast, lightweight HTTP server"
license = "MIT OR Apache-2.0"
repository = "https://github.com/alice/my-web-server"

# Dependencies with version constraints
[dependencies]
tokio = { version = "1.35", features = ["full"] }
axum = "0.7"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

[dev-dependencies]
reqwest = { version = "0.11", features = ["json"] }
tokio-test = "0.4"

# Build profiles
[profile.release]
opt-level = 3
lto = true
strip = true
codegen-units = 1

# Binary targets
[[bin]]
name = "server"
path = "src/main.rs"

[[bin]]
name = "cli"
path = "src/cli.rs"

A pyproject.toml for a Python library with Poetry

[project]
name = "data-pipeline"
version = "2.1.0"
description = "ETL pipeline for processing analytics events"
requires-python = ">=3.11"
license = { text = "MIT" }
authors = [
    { name = "Bob", email = "bob@example.com" },
]

[project.optional-dependencies]
dev = ["pytest>=7.0", "ruff>=0.1.0", "mypy>=1.5"]
docs = ["sphinx>=7.0", "furo"]

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W"]

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v --tb=short"

[build-system]
requires = ["hatchling>=1.18"]
build-backend = "hatchling.build"

Standards & Specifications

• TOML Specification v1.0.0 — The official TOML language specification defining all syntax rules, data types, and parsing behavior
• RFC 3339 (Date and Time on the Internet) — The datetime format standard used by TOML for all date and time values