JSON Schema

While TOML itself may introduce schema specifications in the future, Tombi, like Taplo, is implementing validation features in its linter that support JSON Schema.

Currently, we are extending JSON Schema with special annotations using the x-tombi-* prefix.

Schema Priority

This section explains how Tombi prioritizes the application of x-tombi-* keys in your JSON Schema:

  1. #:schema directive in the TOML file's top comment (compatible with Taplo)
  2. JSON Schema specified in the Tombi configuration file
  3. JSON Schema from the JSON Schema Store

Formatting

x-tombi-toml-version

This key automatically determines the TOML version to use. Currently, we support:

  • v1.0.0 (stable)
  • v1.1.0-preview (experimental)

The preview version includes exciting features like trailing comma support in Inline Tables.

🗒️Note

Until v1.1.0 is officially released, we recommend using v1.0.0.

For experimental purposes, the JSON Schema in tombi.toml is specified as v1.1.0-preview.

x-tombi-table-keys-order

This key controls the automatic sorting of table keys (e.g., [dependencies]).

Available sorting strategies:

  • ascending
  • descending
  • version-sort
  • schema
🗒️Note

When using the schema strategy, we recommend avoiding additionalProperties or patternProperties as they are not sorted with properties and will appear at the end.

🗒️Note

The version-sort strategy is based on the Rust style guide.

x-tombi-array-values-order

This key controls the automatic sorting of array values.

Available sorting strategies:

  • ascending
  • descending
  • version-sort
🗒️Note

The version-sort strategy is based on the Rust style guide.

Linting

Strict Mode

By default, Tombi operates in strict mode. In this mode, objects without additionalProperties are treated as if additionalProperties: false was specified. This differs from the standard JSON Schema specification but provides more precise validation by eliminating ambiguity.

To disable strict mode, add schema.strict = false to your tombi.toml configuration.

Language Gap

While TOML and JSON are different languages, JSON Schema remains a valuable tool for representing TOML structures, especially given the abundance of existing schema assets.

Tombi bridges this language gap by using abbreviations to represent JSON Schema concepts that don't have direct equivalents in TOML.

For more details on how Tombi represents these concepts, check out the Hover section.

← ConfigurationExtensions →