TOML Schema
A TOML-native schema language
Validate TOML without leaving TOML.
TOML Schema describes the structure, names, value types, and constraints<br>of TOML configuration documents using TOML syntax itself.
Read the specification<br>View on GitHub
config.tosd
[toml-schema]<br>version = "1.0.0"
[elements.title]<br>type = "string"
[elements.database]<br>type = "table"
[elements.database.enabled]<br>type = "boolean"
[elements.database.ports]<br>type = "array"<br>arraytype = "integer"
Designed for TOML documents
TOML Schema is intentionally smaller than general-purpose schema systems.<br>It focuses on the TOML value model and keeps schemas readable for people<br>who already know TOML.
Native<br>TOML all the way down
Schemas are valid TOML files, conventionally stored with the required .tosd extension.
Practical<br>Validation-focused
Define required fields, scalar types, arrays, tables, dynamic collections, unions, ranges, and patterns.
Toolable<br>Reference implementations
Java, Go, and Rust implementations validate examples, self-schema behavior, and CLI workflows in CI.
A Quick Tour of TOML Schema
A schema starts with versioned metadata, then describes the TOML document<br>under [elements]. Reusable shapes live under [types].<br>The examples below are fragments of one schema, not standalone files.
Metadata<br>Declare the schema language version
Every schema document starts with [toml-schema] and a full SemVer version.
[toml-schema]<br>version = "1.0.0"
Elements<br>Describe document fields
Each entry under [elements] maps to a TOML key, table, or nested value.
[elements.title]<br>type = "string"
[elements.database]<br>type = "table"
[elements.database.enabled]<br>type = "boolean"
Arrays<br>Validate list contents
Arrays can validate homogeneous item types or reference reusable item schemas.
[elements.database.ports]<br>type = "array"<br>arraytype = "integer"<br>minlength = 1
Types<br>Reuse table shapes
Reusable [types] definitions keep repeated structures in one place.
[types.server]<br>type = "table"
[types.server.ip]<br>type = "string"<br>pattern = "^(?:[0-9]{1,3}\\.){3}[0-9]{1,3}$"
[types.server.role]<br>type = "string"
Collections<br>Handle dynamic table names
A collection validates user-defined keys, such as named servers or environments.
[elements.servers]<br>type = "collection"<br>typeof = "types.server"<br>minlength = 1
Constraints<br>Add rules where they matter
Values can be constrained with allowed values, numeric ranges, string lengths, or patterns.
[elements.environment]<br>type = "string"<br>allowedvalues = ["dev", "stage", "prod"]
[elements.retries]<br>type = "integer"<br>min = 0<br>max = 10
Specification highlights
The language is built around three top-level tables: [toml-schema],<br>optional reusable [types], and required document [elements].
Versioned metadata [toml-schema] declares SemVer language compatibility.
Type references typeof, itemtype, items, oneof, and anyof can reference built-in type names or reusable [types].
Dynamic keys collection validates user-provided table keys.
Union shapes oneof and anyof model alternative valid forms.
Arrays and tuples arraytype, itemtype, and items cover homogeneous and positional arrays.
Media type TOML Schema files use .tosd and application/tosd.
Read the full specification
Reference implementations
The repository includes implementation work for multiple ecosystems and<br>a shared conformance expectation for schema validation.
Java<br>Library and CLI
Uses Tomlj to parse TOML and validates documents against .tosd schemas.
Go<br>CLI
Uses go-toml and supports explicit schema validation and schema-location lookup.
Rust<br>Library and CLI
Uses the Rust toml crate and mirrors cross-language behavior.