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:
#:schema
directive in the TOML file's top comment (compatible with Taplo)- JSON Schema specified in the Tombi configuration file
- 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.
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
When using the schema
strategy, we recommend avoiding additionalProperties
or patternProperties
as they are not sorted with properties
and will appear at the end.
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
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.
x-tombi-string-formats
In Tombi default behavior, the format
used in JSON Schema's โtypeโ: โstring"
only recognizes conversions to the following built-in types:
date-time
date-time-local
date
time-local
By adding the x-tombi-string-formats
key to the root of the JSON Schema, you can add the format
of the string to the validation target.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"x-tombi-string-formats": [
"email",
"hostname",
"uri",
"uuid"
]
}
Currently supported format
targets are as follows:
format | Specification |
---|---|
email | RFC 5322 |
hostname | RFC 1034 |
uri | RFC 3986 |
uuid | RFC 4122 |
If you want to support additional format
in Tombi, please check if it exists in JSON Schema Specification or OpenAPI Format Registry.
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.
JSON Catalog/Schema Cache
Tombi caches JSON Catalog/Schemas in the file system to avoid unnecessary network requests.
How to Clear Cache
CLI
Use --no-cache
option to disable using caches for a CLI command.
tombi format --no-cache
--no-cache
option does not use caches, but saves the latest catalogs/schemas to the file caches.
(This behavior is the same as HTTP's Cache-Control: no-cache
)
It only applies to catalogs/schemas used by the command, and does not update other files.
Language Server
Use RefreshCache
command to clear the cache.
It removes all file caches and fetches the latest schema over the network for the editing TOML file.
Cache Location Search Priority
$XDG_CACHE_HOME/tombi
~/.cache/tombi
VSCode Extension
As with Taplo, extensions can associate their own schemas using tomlValidation
.
You can specify fileMatch
, which associates the schema with documents whose file matches the given pattern (same as jsonValidation).
{
"contributes": {
"tomlValidation": [
{
"fileMatch": "^.*foo.toml$",
"url": "https://json.schemastore.org/foo.json"
}
]
}
}