What is TOML?

TOML (Tom's Obvious, Minimal Language) is a configuration file format designed to be easy to read and write. It is commonly used for Rust projects (Cargo.toml), Python packaging (pyproject.toml), Hugo sites, and many other tools.

When to convert TOML ↔ JSON

Migrating a project from one config format to another
Feeding TOML config data into a JSON-only API or tool
Debugging TOML structure by viewing it as familiar JSON
Generating TOML from programmatic JSON output

Supported TOML features

String (basic, literal, multiline)
Integer (decimal, hex 0x, octal 0o, binary 0b)
Float (including inf, -inf, nan)
Boolean (true / false)
Datetime (offset, local, date-only)
Array and inline array
Table ([section])
Array of tables ([[section]])
Inline table ({ key = "val" })
Dotted keys (a.b.c = 1)

Limitations

JSON has no native equivalent for TOML datetimes. They are serialized to ISO 8601 strings. JSON null values are skipped when converting to TOML because TOML has no null type.

TOML vs. YAML vs. JSON comparison

Feature	TOML	YAML	JSON
Human readability	High	High	Moderate
Typed datetimes	Yes (native)	Via tag	No (strings only)
Comments	Yes (#)	Yes (#)	No
Multiline strings	Yes	Yes (complex)	Limited (escape only)
Anchors / aliases	No	Yes	No
Indentation-sensitive	No	Yes	No
Universal tooling support	Growing	Broad	Universal

TOML's key advantages are its explicit typed datetimes, its clear table and array-of-tables syntax, and its complete insensitivity to indentation. YAML's power comes from anchors and aliases (reuse of values) and its expressive multi-line syntax. JSON wins on universal tooling support and strictness.

Common conversion pitfalls

TOML datetimes -> JSON: TOML's native date/datetime/time types become ISO 8601 strings in JSON. Consumers must parse them explicitly.
Integers with underscores: TOML allows 1_000_000 for readability; these become plain integers in JSON with no underscores.
Inline tables -> JSON objects: TOML inline tables ({a = 1, b = 2}) convert cleanly to JSON objects.
JSON null: TOML has no null type. Null JSON values are dropped or cause an error when converting JSON -> TOML.

Ecosystem context

TOML is the configuration format of choice in several major ecosystems:

Rust / Cargo: Cargo.toml is the package manifest for every Rust project.
Python packaging: pyproject.toml is the standard build system configuration file (PEP 517/518/621).
Hugo: the static site generator uses TOML as its primary config format.
Gitea / Forgejo: self-hosted git platforms use TOML for their configuration files.
LLVM / Clang: several compiler configuration files use TOML.