What is TOML? — Tom's Obvious Minimal Language Explained

Definition

TOML (Tom's Obvious Minimal Language) is a configuration file format designed to be easy to read and write due to its straightforward, human-readable semantics. Created by Tom Preston-Werner (co-founder of GitHub) in 2013, TOML was built as a response to the complexity of XML and the ambiguity of YAML, while remaining less strict than JSON for configuration purposes.

TOML maps clearly to a hash table (dictionary) and is intentionally minimal — the entire specification fits on one page. Its design goal is to be "obvious" so that a reader can understand the structure without needing prior knowledge of the language.

TOML Syntax Rules

TOML syntax is built around three core structures: key-value pairs, tables, and arrays of tables:

1. Key-value pairs — key = "value" on their own line
2. Tables — section headers with [table] brackets
3. Arrays of tables — multiple named sections with [[array]] brackets
4. Comments — start with # and extend to end of line
5. Quoted keys — use "quoted key" for keys with special characters
6. Dotted keys — a.b.c = value for shorthand nesting
7. Keys must be unique per table level
8. Case-sensitive keys and values
9. Strict datetime format (ISO 8601 required)
10. No null type — omit keys instead

TOML Data Types

Example TOML Document

Below is a real-world style TOML configuration that could belong to a Rust crate's Cargo.toml or a Python project's pyproject.toml:

[package]
name = "my-app"
version = "0.1.0"
edition = "2021"
description = "A sample application"
authors = ["Alice <alice@example.com>"]
license = "MIT"
 
[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.35", features = ["full"] }
reqwest = "0.11"
 
[profile.release]
opt-level = 3
lto = true
codegen-units = 1
 
[workspace]
members = ["crates/*"]
 
[[bench]]
name = "parse-bench"
harness = false

Nested Tables

TOML supports nesting through dotted keys inside table headers. This creates hierarchical structures without deep indentation:

[server]
host = "localhost"
port = 8080
 
[server.database]
url = "postgres://localhost:5432/app"
pool_size = 10
ssl = true
 
[server.database.pool]
min = 2
max = 20
timeout = 30

This is equivalent to the following JSON structure:

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "database": {
      "url": "postgres://localhost:5432/app",
      "pool_size": 10,
      "ssl": true,
      "pool": {
        "min": 2,
        "max": 20,
        "timeout": 30
      }
    }
  }
}

Inline Tables

For simpler nested values, TOML offers inline table syntax:

database = { url = "postgres://localhost:5432/app", pool_size = 10, ssl = true }

Table Arrays ([[array]])

Table arrays let you define a list of tables with identical structure — perfect for collections of similar objects:

[[products]]
name = "Hammer"
sku = 738594937
price = 12.99
 
[[products]]
name = "Nails"
sku = 738594938
quantity = 100
price = 3.99

This maps to an array of objects:

{
  "products": [
    { "name": "Hammer", "sku": 738594937, "price": 12.99 },
    { "name": "Nails", "sku": 738594938, "quantity": 100, "price": 3.99 }
  ]
}

TOML vs YAML vs JSON

Common TOML Use Cases

Rust Cargo (Cargo.toml)

Every Rust project uses Cargo.toml for package metadata, dependencies, build configuration, and workspace management. TOML was practically adopted as the Rust community standard.

Python pyproject (pyproject.toml)

Modern Python packaging (PEP 517/518/621) uses pyproject.toml for build system configuration, dependencies, and tool settings for tools like Black, Ruff, and Pytest.

Static Site Generators

• Hugo uses hugo.toml for site configuration (themes, menus, languages, params)
• Zola uses config.toml extensively for content structure

JavaScript / TypeScript Runtimes

• Deno uses deno.json (JSON) but also fully supports deno.jsonc — however, tools like fresh.land leverage TOML
• Bun uses bun.lock (binary) but supports bunfig.toml for configuration

Go Modules

Go's module system originally used Gopkg.toml (during the dep era) before migrating to Go modules.

Homebrew Formulae

Homebrew package formulas are written in Ruby, but many Homebrew tap configurations use TOML.

Why Use TOML Over Alternatives?

Over JSON

• Native comment support for documentation
• Dates and times as first-class types
• Cleaner, less punctuation-heavy syntax
• Multi-line string support without escaping

Over YAML

• No indentation sensitivity — tabs and spaces mix safely
• Predictable type resolution — yes, no, on, off are strings, not booleans
• Simpler spec — fewer surprises and edge cases
• Faster to parse

LangStop TOML Tools

• TOML to JSON — Convert TOML documents to JSON
• TOML to YAML — Convert TOML documents to YAML
• TOML to XML — Convert TOML documents to XML
• YAML Formatter — Pretty print and beautify YAML
• JSON Formatter — Pretty print and beautify JSON
• JSON Validator — Validate and lint JSON documents