TOML Schema is now available for testing and evaluation, and now has a home: https://toml-schema.org
TOML Schema is a schema language for TOML that is itself written in TOML. It lets a project describe the expected structure, names, value types, and constraints of a TOML file without asking users or tools to switch mental models or formats such as JSON Schema.
That means a schema can look like this:
[toml-schema]
version = "1.0.0"
[elements.database]
type = "table"
[elements.database.enabled]
type = "boolean"
[elements.database.ports]
type = "array"
arraytype = "integer"
If your project already uses TOML, the schema is still TOML. It is readable, diffable, and friendly to the same tooling habits people already use around configuration files.
A project that started in 2020
TOML Schema began in June 2020. The first repository commits created the initial README, example TOML document, and example schema. The work started from a human-authored idea: TOML should have a compact, TOML-native way to describe and validate TOML configuration files.
The original motivation has stayed steady:
- Catch misconfiguration before it reaches production.
- Give tools and editors a concrete source of truth for validation, completion, and hints.
- Keep the format approachable for people who already know TOML.
Over time, the project evolved from an idea and examples into a fuller specification. The current spec defines top-level schema structure, metadata, reusable types, document elements, collections, unions, arrays, tuples, constraints, file extension, MIME type, and schema lookup from a TOML document.
The language design and most of the conceptual work were human-authored. The recent acceleration with a coding agent did not replace that. It helped turn the old idea into a more complete, tested, and shareable project, with reference implementations and a public website.
Why TOML-native matters
TOML is popular for configuration because it is explicit without being noisy. It has a small, practical value model: strings, integers, floats, booleans, date and time values, arrays, tables, inline tables, and arrays of tables.
A schema language for TOML does not need to become a general-purpose data modeling universe. TOML Schema intentionally stays close to TOML's shape:
-
[toml-schema]declares metadata such as the schema language version. -
[elements]describes the expected document structure. -
[types]defines reusable shapes. -
collectionsupports dynamic table names. -
oneofandanyofsupport alternative valid forms. -
min,max,minlength,maxlength,allowedvalues, andpatternexpress practical constraints. -
itemtype,arraytype, anditemscover arrays, arrays of structured values, and positional arrays.
The goal of TOMLS chema is to make TOML files safer and easier to modify.
What is live now
The repository now includes:
- A human-readable specification in
SPEC.md. - A formal ABNF companion grammar in
toml-schema.abnf. - A self-schema in
toml-schema.tosd. - A worked example pair:
config.tosdandconfig.toml. - Reference implementations in Java, Go, and Rust.
- A GitHub Pages website at https://toml-schema.org.
The reference implementations share the same practical expectations: parse TOML using language-native TOML parsers, validate checked-in examples, support schema lookup through [toml-schema].location, validate the example schema against the self-schema, and keep vocabulary aligned with the ABNF and self-schema.
Where Coding Agents helped
To bring the project to the finish line, I relied on GitHub Copilot. Its role has been practical and implementation-focused:
- Generate and iterate on reference implementations.
- Add and refine tests across Java, Go, and Rust.
- Help build the GitHub Pages website.
- Help close a few issues and review findings.
- Assist with CI and documentation cleanup.
It is important to clarify that TOML Schema did not begin as an AI-generated concept, and most of the schema idea was not invented with AI. The project started in 2020 with the bulk of the specification written down and reviewed by members of the TOML project itself.
Try it
The new site is live at https://toml-schema.org.
The repository is at https://github.com/brunoborges/toml-schema.
If you work with TOML files, take a look at the specification, try the examples, and open an issue with feedback. The project is ready for people to kick the tires, compare it with real configuration files, and help shape what a TOML-native schema format should become.
