TOML Schema

Validate TOML without leaving TOML.

TOML Schema describes structure, value types, reusable constraints, and common semantic relationships using TOML syntax itself.

Explore the editorRead the specification

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.

Native

TOML all the way down

Schemas are valid TOML documents and use the required .tosd filename extension.

Practical

Validation-focused

Define required fields, types, string formats, conditional branches, collections, unions, composition, sibling rules, uniqueness, defaults, and deprecations.

Toolable

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 validatetosd 1.0.0-rc.2

curl -fsSL https://tomlschema.org/cli/releases/rust-v1.0.0-rc.2/install-tosd.sh | bash

tosd validate config.tosd config.toml

A 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"
format = "ipv4"

[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"
format = "hostname"

[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 standardized string formats, 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

[elements.contact]
type = "string"
format = "email"
optional = true

TOML

environment = "prod"
retries = 3
contact = "ops@example.com"

Specification 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 entriescollection validates dynamically named values; keypattern can constrain their keys.

Alternative typesoneof requires exactly one matching type; anyof requires at least one.

Conditional shapesif selects a reusable then or else definition from a direct child's parsed value.

Semantic rulesdependentrequired, mutuallyexclusive, and exactlyone constrain direct sibling presence.

String formatsformat validates strings as email, uuid, uri, hostname, ipv4, or ipv6.

Annotationsdefault is non-mutating metadata; deprecated produces warnings without invalidating a document.

Containers and tuplesitemtype validates homogeneous array and collection members; items defines positional arrays.

Media typeTOML Schema files use .tosd and the registered application/toml media type.

Read the full specification

Reference implementations

The repository includes implementation work for multiple ecosystems and a shared conformance expectation for schema validation.

Java

Library

Uses Tomlj to parse TOML and validates documents against .tosd schemas.

Go

Library

Uses go-toml and supports explicit schema validation and schema-location lookup.

.NET

Library

Uses Tomlyn to parse TOML and validates documents against .tosd schemas.

Python

Library

Uses the standard-library tomllib parser and supports schema validation and schema-location lookup.

Rust

Library and canonical CLI

Uses the Rust toml crate and provides validation, schema discovery, and schema extraction commands.

Node.js

TypeScript 7 library

Uses smol-toml and provides validation, schema discovery, and schema extraction through an ESM API.

Build and use an implementation