Auto Sorting

One of Tombi's most distinctive features is automatic sorting.

Taplo and toml-sort specify one sorting method and apply it consistently across a document. Tombi is designed differently: shared schema information specifies the sorting method for each item, so those fine-grained sorting policies are shared with everyone who uses the schema.

Also, it can automatically sort content including comments, using its own unique treatment of comments.

How to Specify Auto Sorting Methods

Tombi does not perform automatic sorting unless a sorting method is specified.

Sorting methods are available in the following order of priority:

Comment Directives

You can specify auto sorting methods using comment directives. This has higher priority than Configuration and JSON Schema specifications.

⚠️Warning

For files that have a schema assigned, the same can also be specified in tombi.toml with Configuration. Use comment directives for temporary overrides, such as working around errors in JSON Schemas registered in the Schema Store, or for local adjustments in files that have no schema.

Configuration

You can specify auto sorting methods in tombi.toml using schemas[*].overrides[*]. This has lower priority than Comment Directives and higher priority than JSON Schema specifications.

This is the recommended way to set a stable rule for the whole project. You do not need to edit the JSON Schema or add x-tombi-* keys to it.

For example, the following configuration sorts the root table keys of example.toml in ascending order and the items array values in descending order.

[[schemas]]
path = "https://example.com/schema.json"
include = ["example.toml"]

[[schemas.overrides]]
targets = [""]
format.rules.table-keys-order = "ascending"

[[schemas.overrides]]
targets = ["items"]
format.rules.array-values-order = "descending"

See schemas[*].overrides[*].format.rules for the available targets and values.

JSON Schema

This is probably the method you'll benefit from the most.

When schemas automatically retrieved from the JSON Schema Store contain the following keys, automatic sorting is performed according to that schema:

Files like Cargo.toml and pyproject.toml registered in the JSON Schema Store have these keys specified.

Additionally, you can specify JSON Schema files using configuration files or comment directives, allowing you to apply schemas from sources other than the JSON Schema Store.

How to Stop Auto Sorting

Auto sorting is defined for each JSON Schema file, and can be disabled for all schemas at once or for each schema in the configuration file.

Disable Auto Sorting for All Schemas

To disable schema-based auto sorting regardless of which schema applies, use schema.format.rules.

[schema.format.rules]
array-values-order.enabled = false
table-keys-order.enabled = false

This global setting is a fallback with lower priority than the same setting in schemas[*].format.rules. For example, you can disable sorting globally and re-enable it for a specific schema.

[schema.format.rules]
array-values-order.enabled = false
table-keys-order.enabled = false

[[schemas]]
path = "tombi://www.schemastore.org/cargo.json"
include = ["Cargo.toml"]
format.rules.table-keys-order.enabled = true

Comment directives and schemas[*].overrides[*] are still applied on top of this setting.

Disable Auto Sorting for Each Schema

If you want to disable automatic sorting for typical Cargo.toml and pyproject.toml files, please create the following configuration file.

[[schemas]]
path = "tombi://www.schemastore.org/cargo.json"
include = ["Cargo.toml"]
format.rules.array-values-order.enabled = false
format.rules.table-keys-order.enabled = false

[[schemas]]
path = "tombi://www.schemastore.org/pyproject.json"
include = ["pyproject.toml"]
format.rules.array-values-order.enabled = false
format.rules.table-keys-order.enabled = false

If you want to keep automatic sorting only for specific keys after disabling it for a schema, use schemas[*].overrides[*] to re-enable sorting for those targets.

For example, the following configuration disables sorting for Cargo.toml as a whole, but keeps sorting only under [dependencies], [dev-dependencies], and [build-dependencies].

[[schemas]]
path = "tombi://www.schemastore.org/cargo.json"
include = ["Cargo.toml"]
format.rules.array-values-order.enabled = false
format.rules.table-keys-order.enabled = false

[[schemas.overrides]]
targets = ["dependencies", "dev-dependencies", "build-dependencies"]
format.rules = {
  table-keys-order = "ascending"
}