TOML Formatter

TOML: Configuration That Reads Like Configuration

TOML was created in 2013 by Tom Preston-Werner to be "a config format that humans don't hate and machines can parse without ambiguity." It avoids JSON's lack of comments, YAML's whitespace-sensitivity gotchas, and INI's lack of nesting. The result is a format that dominates Rust (Cargo.toml), modern Python packaging (pyproject.toml), and many Go projects. This formatter cleans up TOML files without needing to install a CLI tool.

Quick Tour of the Syntax

Key-value pairs

Strings double-quoted by default. Numbers, booleans, dates unquoted.

Tables

Each [name] starts a new table; all subsequent keys until the next [ header belong to it.

Nested tables (dotted)

Produces { servers: { alpha: {...}, beta: {...} } }.

Inline tables

Like JSON object. Single line. Good for short structures.

Arrays

Multi-line OK; trailing commas allowed.

Array of tables

[[name]] (double brackets) appends a table to an array.

Comments

# starts a comment; continues to end of line.

Strings

Numbers

Dates and times

RFC 3339 format. Native type, parsers return actual Date objects, not strings.

Common Real-World TOML

Cargo.toml (Rust)

pyproject.toml (Python, PEP 518/621)

.taplo.toml (TOML formatter config)

What `terraform fmt`'s TOML Equivalent (`taplo`) Does

taplo (the standard Rust-based TOML formatter):

• Indents consistently (2 spaces default).
• Aligns = within a table if configured.
• Wraps long inline tables to multi-line.
• Adds blank lines between top-level tables.
• Sorts keys (optional, per-table or globally, usually NOT default).
• Validates syntax and emits clear errors with line numbers.

This formatter applies similar rules in the browser.

Subtle TOML Rules

Tables can't be redefined

But you CAN add to existing tables via dotted headers:

Keys with dots in them

Quote keys when the literal name contains dots, spaces, or special characters.

Array of tables can't conflict with single table

Inline tables are immutable

For mutable / nested expansion, use header tables.

Whitespace and blank lines

Within a table: blank lines between assignments are allowed. Between tables: convention is one blank line.

Trailing commas

Allowed in arrays and inline tables (added in TOML 1.0).

Common Mistakes

Using YAML conventions in TOML

Right:

Forgetting quotes on strings

Boolean capitalization

Mixed types in array (TOML < 1.0)

Pre-TOML 1.0, arrays had to be homogeneous. TOML 1.0 allows heterogeneous arrays, but many older parsers reject them. Check your parser's TOML version.

Comments mid-value

OK in TOML 1.0.

Trailing whitespace in keys

TOML vs YAML vs JSON

Rule of thumb: TOML for flat-ish config with explicit types; YAML for nested data (k8s manifests); JSON for machine-to-machine data exchange.

Tooling

Validators

• taplo, Rust-based, CLI + LSP. Format, lint, validate.
• tomli, Python parser; standard library in 3.11+ as tomllib.
• go-toml, Go parser.
• @iarna/toml, Node parser.

Editor support

• VS Code: Even Better TOML extension uses taplo LSP.
• JetBrains: built-in TOML support.
• Vim/Neovim: toml filetype + taplo LSP.

Schemas

TOML files can be validated against JSON Schema:

• Cargo.toml: schema published by Rust team.
• pyproject.toml: schema in packaging.python.org.
• Custom schemas: write your own; Taplo can validate against them.

Pre-commit

Cargo Versioning Cheatsheet

TOML for Cargo.toml dependencies has its own version syntax:

The caret is the default, "1.0" means "^1.0" means "1.x, no breaking change."

Privacy

TOML formatting runs entirely in JavaScript in your browser: tokenize, parse, validate, reformat. Open DevTools Network during use: zero outbound requests. Config files often hold infrastructure context, DB hosts, internal service URLs, private registry sources, sometimes embedded credentials. A formatter that uploaded would be leaking architectural information. This tool keeps everything local; what you paste stays in the tab.

# Inline-table form
package = { metadata = { docs = { features = ["full"] } } }

[package.metadata.docs]
features = ["full"]

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

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

{
  "bin": [
    { "name": "server", "path": "src/server.rs" },
    { "name": "worker", "path": "src/worker.rs" }
  ]
}

offset_dt    = 1979-05-27T07:32:00-08:00
local_dt     = 1979-05-27T07:32:00
local_date   = 1979-05-27
local_time   = 07:32:00

offset_dt    -> OffsetDateTime  (timezone-aware, RFC 3339)
local_dt     -> LocalDateTime   (no zone; "wall-clock")
local_date   -> LocalDate
local_time   -> LocalTime