A TOML-native schema language

Validate TOML without leaving TOML.

TOML Schema describes the structure, names, value types, and constraints of TOML configuration documents using TOML syntax itself.

Read the specification View on GitHub

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 files, conventionally stored with the required .tosd extension.

Practical

Validation-focused

Define required fields, scalar types, arrays, tables, dynamic collections, unions, ranges, and patterns.

Toolable

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 under [elements]. Reusable shapes live under [types].

Metadata

Declare the schema language version

Every schema document starts with [toml-schema] and a full SemVer version.

[toml-schema]
version = "1.0.0"
Elements

Describe document fields

Each entry under [elements] maps to a TOML key, table, or nested value.

[elements.title]
type = "string"

[elements.database]
type = "table"

  [elements.database.enabled]
  type = "boolean"
Arrays

Validate list contents

Arrays can validate homogeneous item types or reference reusable item schemas.

[elements.database.ports]
type = "array"
arraytype = "integer"
minlength = 1
Types

Reuse table shapes

Reusable [types] definitions keep repeated structures in one place.

[types.server]
type = "table"

  [types.server.ip]
  type = "string"
  pattern = "^(?:[0-9]{1,3}\\.){3}[0-9]{1,3}$"

  [types.server.role]
  type = "string"
Collections

Handle dynamic table names

A collection validates user-defined keys, such as named servers or environments.

[elements.servers]
type = "collection"
typeof = "types.server"
minlength = 1
Constraints

Add rules where they matter

Values can be constrained with allowed values, numeric ranges, string lengths, or patterns.

[elements.environment]
type = "string"
allowedvalues = ["dev", "stage", "prod"]

[elements.retries]
type = "integer"
min = 0
max = 10

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.
Reusable types[types] definitions keep schemas compact and consistent.
Dynamic keyscollection validates user-provided table keys.
Union shapesoneof and anyof model alternative valid forms.
Arrays and tuplesarraytype, itemtype, and items cover homogeneous and positional arrays.
Media typeTOML Schema files use .tosd and application/tosd.

Reference implementations

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

Java

Library and CLI

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

Go

CLI

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

Rust

Library and CLI

Uses the Rust toml crate and mirrors cross-language behavior.