---
title: "TOML (page.toml)"
description: "Minimal, human-friendly config."
canonical: "https://geordy.ai/formats/toml"
---
# TOML

**Minimal, human-friendly config.**

An alternative to YAML with cleaner type rules: a date is a date, not a string that looks like one. The shape to hand your own tooling when it has to read page metadata without guessing.

TOML (Tom's Obvious, Minimal Language) is a configuration file format created by Tom Preston-Werner in 2015. It emphasizes human readability and simple structure while providing explicit data types and unambiguous mapping to dictionaries. Supports nested tables, arrays, comments, and includes built-in support for strings, integers, floats, booleans, and datetime values.

## At a glance

- File: `page.toml`
- First released: 2015
- Created by: Tom Preston-Werner
- Specification: https://toml.io/en/v1.0.0
- Read by: Every major language's TOML parser, Your own build and content tooling

## Why it matters for AI

TOML is an explicitly-typed, line-oriented config format whose grammar is small enough to be parsed unambiguously by every major language, which is why it has become the default for tooling configs (Cargo, pyproject.toml, Hugo). For anything that has to read or rewrite human-edited metadata without a schema in hand, TOML's typed values remove the YAML-style guesswork: no date silently becoming a string, no "no" silently becoming false.

## Example

```
# page.toml for https://geordy.ai/features
title = "Features"
description = "The structured files AI systems actually read."
url = "https://geordy.ai/features"
updated = 2026-10-20

[owner]
name = "Geordy"
url = "https://geordy.ai"
```

## Benefits

- Human readability with explicit types
- Fast parsing
- Adopted by major tools (Cargo.toml, pyproject.toml)

## Limitations

- Reduced flexibility for complex nested structures versus YAML

## Best practices

- Quote all string values; use bare keys for identifiers (`name = "foo"`) and reserve quoted keys for those containing dots or special characters.
- Prefer `[table]` headers and `[[array.of.tables]]` over deeply nested inline tables for readability and clean diffs.
- Use offset date-time literals (RFC 3339, e.g. `1979-05-27T07:32:00Z`) rather than strings so consumers get real timestamps.
- Pin to the spec version your parser supports (TOML 1.0.0 is current stable) and run files through a validator like `taplo` in CI.

## Pitfalls

- Re-defining the same key or table twice in one file - TOML 1.0 makes this an explicit error, not a silent override.
- Mixing types inside an array in TOML 1.0 parsers that haven't adopted heterogeneous arrays.
- Putting a sub-table after later keys in its parent table - once `[a.b]` is opened you can no longer add bare keys to `[a]` below it.

## Use cases

- **Configuration files (Cargo, pyproject)**
- **Developer tooling**
- **Data exchange**

## Adopters

- Cargo (Rust) (https://doc.rust-lang.org/cargo/reference/manifest.html)
- Python packaging (https://peps.python.org/pep-0518/)
- Hugo (https://gohugo.io/getting-started/configuration/)
- Poetry (https://python-poetry.org/docs/pyproject/)
- Black formatter (https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html)
---

Source: https://geordy.ai/formats/toml
This is a machine-readable markdown version of that page, generated by Geordy.