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.

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

By specifying object instead of string, you can individually define sorting methods for the different groups: properties, additionalProperties, and patternProperties.

{
  "x-tombi-table-keys-order": {
    "properties": "schema",
    "patternProperties": "version-sort",
    "additionalProperties": "descending"
  }
}

The order of the object's properties is significant. Sorting is performed sequentially for each group starting from the first property, and the results are then combined.

x-tombi-array-values-order

This key controls the automatic sorting of array values.

Available sorting strategies:

• ascending
• descending
• version-sort

By specifying object instead of string, you can individually define sorting methods for the different groups: oneOf, anyOf.

The following example, sorts the first schema of oneOf with version-sort, and the second schema with ascending after that.

{
  "type": "array",
  "items": {
    "oneOf": [
      { "type": "string" },
      { "type": "number" }
    ]
  },
  "x-tombi-array-values-order": {
    "oneOf": [
      "version-sort",
      "ascending"
    ]
  }
}

The following is the sorting result.

# Before
key = [1, "2", 3, "4"]

# After
key = ["2", "4", 1, 3]

{
  "oneOf": [
    {
      # Cannot use nested `oneOf` / `anyOf`
      "oneOf": [
        { "type": "string" },
        { "type": "number" }
      ]
    },
    ...
  ],
  "x-tombi-array-values-order": {
    "oneOf": [...]
  }
}

x-tombi-array-values-order-by

This key specifies which key to use as the sorting key when the array element is a table.

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "age": {
        "type": "number"
      }
    },
    "x-tombi-array-values-order-by": "name"
  },
  "x-tombi-array-values-order": "ascending"
}

The following is the sorting result.

# Before
key = [
  { name = "Bob", age = 30 },
  { name = "Charlie", age = 25 },
  { name = "Alice", age = 20 },
]

# After
key = [
  { name = "Alice", age = 20 },
  { name = "Bob", age = 30 },
  { name = "Charlie", age = 25 },
]

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:

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

Language Server

Use RefreshCache command to clear the cache.

Cache Location Search Priority

1. $XDG_CACHE_HOME/tombi
2. ~/.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"
      }
    ]
  }
}