TOML (Tom's Obvious Minimal Language)

TOML (Tom's Obvious Minimal Language) is a minimal, human-readable data serialization format created in 2013 by Tom Preston-Werner (co-founder of GitHub). Engineered specifically for software application configuration files, TOML aims to be completely unambiguous while cleanly mapping to native dictionary and hash table data structures. Today, TOML serves as the premier configuration format for Rust's package manager (Cargo.toml), modern Python packaging standards (pyproject.toml per PEP 518/621), Go tooling, Hugo static sites, and container runtimes.

Convert, validate, and reformat TOML into JSON or YAML using our fast TOML Converter tool.

---

Technical Specifications at a Glance

Specification	Details
Creator & Year	Tom Preston-Werner (2013)
Current Specification	TOML v1.0.0 (Released January 2021)
File Extension	.toml
MIME Media Type	application/toml
Character Encoding	Strict UTF-8
Case Sensitivity	Case-sensitive keys and strings
Primary Ecosystems	Rust (Cargo), Python (Poetry, Flit, Ruff), Hugo, Deno, Docker Compose

---

Format Syntax & Core Data Structures

TOML avoids significant whitespace and complex nesting hierarchies by adopting straightforward table sections denoted with square brackets [...].

# Top-level key-value pairs
title = "DevFlow Gateway Configuration"
version = "2.4.0"
enabled = true
port = 8080
latency_budget = 45.5

# Sub-table (Dictionary)
[database]
server = "192.168.1.1"
ports = [ 8001, 8002, 8003 ]
connection_max = 5000
enabled = true

# Nested table
[database.credentials]
user = "app_service"
# ISO 8601 Datetime is a first-class citizen in TOML
rotated_at = 2026-09-01T12:00:00Z

# Array of Tables (denoted by double brackets)
[[services]]
name = "auth-service"
endpoint = "https://auth.internal:4000"

[[services]]
name = "billing-service"
endpoint = "https://billing.internal:5000"

---

TOML vs YAML vs JSON: Choosing the Right Configuration Format

Feature	TOML	YAML	JSON
Primary Focus	Human-edited configurations	DevOps manifests & CI/CD	Machine-to-machine data interchange
Whitespace Sensitivity	No (Indentation is purely cosmetic)	Yes (Significant indentation)	No
Native Datetime Type	Yes (RFC 3339 timestamps)	Yes (Implicit / inferred)	No (String serialization only)
Comments	Supported (# comment)	Supported (# comment)	Forbidden in strict RFC 8259
Ambiguity Level	Zero (Strict, explicit syntax)	High (Implicit type coercion like no → false)	Low
Deep Nesting Ergonomics	Moderate (Awkward for deeply nested trees)	Excellent (Clean indentation)	Verbose (Nested curly braces)

---

Code Examples: Parsing TOML

Modern JavaScript (Node.js & Browser using @iarna/toml or smol-toml)

import { parse, stringify } from 'smol-toml';

const rawToml = `
[project]
name = "devflow-tools"
version = "1.0.0"
dependencies = ["react", "lucide-react"]
`;

// Parse TOML string into JavaScript Object
const config = parse(rawToml);
console.log(`Package Name: ${config.project.name}`);

// Serialize Object back to TOML string
const serialized = stringify({
  server: {
    host: "0.0.0.0",
    port: 3000,
  }
});

Python 3.11+ (Built-in tomllib)

import tomllib  # Built into standard library since Python 3.11

with open("pyproject.toml", "rb") as f:
    pyproject_data = tomllib.load(f)

project_name = pyproject_data.get("project", {}).get("name")
print(f"Loaded Python Project: {project_name}")

---

Common Developer Pitfalls

1. Duplicate Table Declarations: Defining the same table [server] twice in the same file throws a parse error. Unlike JSON objects which allow key overrides in loose parsers, TOML mandates absolute uniqueness for table definitions.
2. Treating Indentation as Hierarchy: TOML does not care about your indentation levels. Writing a indented key under [server] does not place it in a sub-dictionary; explicit dot notation ([server.limits]) or inline tables (limits = { cpu = 2 }) are required.
3. Array of Tables vs Standard Array: Forgetting double brackets [[items]] when declaring a sequence of objects turns the second item into a duplicate key error. Single brackets [items] declare a single dictionary table.

---

Frequently Asked Questions

Why did Rust and Python standardize on TOML for package manifests?

Both language steering committees chose TOML because it eliminates YAML's infamous "Norway Problem" (where unquoted country code NO is parsed as boolean false) and solves JSON's inability to store comments and trailing commas. TOML provides crystal-clear configuration files that humans can easily edit without accidental parsing bugs.

Does TOML support multiline strings?

Yes. TOML supports two flavors of multiline strings: triple double-quotes ("""...""") which allow backslash escaping, and triple single-quotes ('''...''') which preserve raw text without escaping (ideal for regular expressions or shell commands).

How can I convert existing TOML files to JSON or YAML?

You can convert files instantly with our client-side TOML Converter or cross-check formatting alongside our YAML Converter.