TOML all the way down
Schemas are valid TOML documents and use the required .tosd filename extension.
Validate TOML without leaving TOML.
TOML Schema describes structure, value types, reusable constraints, and common semantic relationships using TOML syntax itself.
Designed for TOML documents
TOML Schema is intentionally smaller than general-purpose schema systems. It focuses on the TOML value model and keeps schemas readable for people who already know TOML.
Validation-focused
Define required fields, types, conditional branches, collections, unions, composition, sibling rules, uniqueness, defaults, and deprecations.
Reference implementations
Java, Go, .NET, Python, Rust, and Node.js/TypeScript libraries validate examples and self-schema behavior in CI; Rust also exercises the canonical CLI end to end.
A visual editor for a language that stays readable.
Open a .tosd file as a schema map, edit its properties,
and inspect the generated TOML without leaving the GitHub Copilot App.
Validate from the command line.
The canonical tosd CLI validates TOML against an explicit
schema or follows the document's [toml-schema].location.
Release downloads support Linux x86_64 and arm64, Apple Silicon macOS,
and Windows x86_64.
Install, then validate
tosd 1.0.0-rc.2
curl --proto '=https' --tlsv1.2 -sSfL \
https://github.com/brunoborges/toml-schema/releases/download/rust-v1.0.0-rc.2/install-tosd.sh |
bash -s -- --version 1.0.0-rc.2
tosd validate config.tosd config.tomlA Quick Tour of TOML Schema
A schema includes versioned metadata and describes the TOML document
under [elements]. Reusable shapes live under [types].
Each example pairs a schema fragment with the TOML it describes. The
schema fragments form one schema and are not standalone files.
Metadata
Declare the schema language version
Every schema document must contain [toml-schema] with a full SemVer version.
Schema (.tosd)
[toml-schema]
version = "1.0.0"
TOML
[toml-schema]
location = "config.tosd"
version = "1.0.0"
Elements
Describe document fields
Each entry under [elements] maps to a TOML key, table, or nested value.
Schema (.tosd)
[elements.title]
type = "string"
[elements.database]
type = "table"
[elements.database.enabled]
type = "boolean"
TOML
title = "Example"
[database]
enabled = true
Arrays
Validate list contents
Arrays can validate homogeneous item types or reference reusable item schemas.
Schema (.tosd)
[elements.database.ports]
type = "array"
itemtype = "integer"
minlength = 1
TOML
[database]
ports = [8000, 8001]
Types
Reuse table shapes
Reusable [types] definitions keep repeated structures in one place.
Schema (.tosd)
[types.server]
type = "table"
[types.server.ip]
type = "string"
pattern = "^(?:[0-9]{1,3}\\.){3}[0-9]{1,3}$"
[types.server.role]
type = "string"
TOML
[servers.primary]
ip = "10.0.0.1"
role = "frontend"
Conditionals
Select a shape from a field value
Choose between reusable table shapes using a direct child value. Each branch can require its own fields and reject fields from the other shape.
Schema (.tosd)
[types.sqliteDatabase]
type = "table"
[types.sqliteDatabase.engine]
type = "string"
[types.sqliteDatabase.path]
type = "string"
[types.serverDatabase]
type = "table"
[types.serverDatabase.engine]
type = "string"
[types.serverDatabase.host]
type = "string"
[types.serverDatabase.port]
type = "integer"
[types.database]
if = { key = "engine", equals = "sqlite" }
then = "types.sqliteDatabase"
else = "types.serverDatabase"
[elements.storage]
type = "types.database"
optional = true
TOML
[storage]
engine = "postgresql"
host = "db.internal"
port = 5432
Collections
Handle dynamic table names
A collection validates values stored under user-defined keys, such as named servers or environments.
Schema (.tosd)
[elements.servers]
type = "collection"
itemtype = "types.server"
minlength = 1
TOML
[servers.primary]
ip = "10.0.0.1"
role = "frontend"
[servers.backup]
ip = "10.0.0.2"
role = "backend"
Constraints
Add rules where they matter
Values can be constrained with allowed values, numeric ranges, string lengths, or patterns.
Schema (.tosd)
[elements.environment]
type = "string"
allowedvalues = ["dev", "stage", "prod"]
[elements.retries]
type = "integer"
min = 0
max = 10
TOML
environment = "prod"
retries = 3Specification highlights
The language is built around three top-level tables: [toml-schema],
optional reusable [types], and required document [elements].
Versioned metadata
[toml-schema] declares SemVer language compatibility.Type referencesReferences used by
type, itemtype, items, oneof, anyof, allof, then, and else select or compose built-in types and reusable [types] definitions.Dynamic entries
collection validates dynamically named values; keypattern can constrain their keys.Alternative types
oneof requires exactly one matching type; anyof requires at least one.Conditional shapes
if selects a reusable then or else definition from a direct child's parsed value.Semantic rules
dependentrequired, mutuallyexclusive, and exactlyone constrain direct sibling presence.Annotations
default is non-mutating metadata; deprecated produces warnings without invalidating a document.Containers and tuples
itemtype validates homogeneous array and collection members; items defines positional arrays.Media typeTOML Schema files use
.tosd and the registered application/toml media type.Reference implementations
The repository includes implementation work for multiple ecosystems and a shared conformance expectation for schema validation.
Library
Uses Tomlj to parse TOML and validates documents against .tosd schemas.
Library
Uses go-toml and supports explicit schema validation and schema-location lookup.
Library
Uses Tomlyn to parse TOML and validates documents against .tosd schemas.
Library
Uses the standard-library tomllib parser and supports schema validation and schema-location lookup.
Library and canonical CLI
Uses the Rust toml crate and provides validation, schema discovery, and schema extraction commands.
TypeScript 6 library
Uses smol-toml and provides validation, schema discovery, and schema extraction through an ESM API.