Catalogs

Enable catalog matching

dollarlint validate . --catalogs

Catalog matching is optional at runtime unless it is enabled in .dollarlint.toml. The starter config from dollarlint init enables the built-in catalogs by default; pass --catalogs=false or set schemas.catalogs.enabled = false when you want catalog matching off. Explicit in-file schemas, config associations, and DollarLint's built-in .dollarlint.toml association still take precedence.

The default schemas.catalogs.match = "auto" skips low-confidence generic bare filename matches such as tasks.json. Use "all" when you intentionally want every catalog filename match applied.

When the built-in SchemaStore source is enabled, DollarLint supplements it with a small set of curated filename associations for known catalog gaps and drift, including Rust's rustfmt.toml / .rustfmt.toml, release-plz.toml / .release-plz.toml, and .NET's launchSettings.json / Properties/launchSettings.json.

The built-in RubySchema source covers Ruby and Rails project configs such as RuboCop, Standard, Rails config/database.yml, Sidekiq, Shoryuken, Packwerk, i18n, Mongoid, Kamal, and related monitoring configs. Generic Ruby/Rails filenames require nearby project evidence before they are associated.

Some important config files do not currently have a built-in or catalog schema that DollarLint can use. When DollarLint recognizes one of those known gaps, such as netlify.toml, .cargo/config.toml, .terraform-docs.yml, or .asf.yaml, JSON output includes schemaGap context and skipped-file text explains the gap instead of treating the file as an unknown blob.

Understand and lock in matches

Catalog decisions are explainable. JSON output includes schemaMatch on files and catalog-backed issues, and text hints for catalog-sourced issues include why DollarLint chose that schema. The explanation names the matched catalog fileMatch, the confidence, and a suggested [[schemas.associations]] rule you can add when the match is correct.

When a low-confidence catalog candidate is intentionally not a schema match, or a context-gated RubySchema candidate is not this kind of config, add a catalog ignore rule so future runs make that choice explicit:

[[schemas.catalogs.ignore]]
file = "data/tasks.json"
reason = "application data, not a tool config"

Use a custom catalog

dollarlint validate . --catalog-source ./catalog.json

In config, use schemas.catalogs and one or more schemas.catalogs.sources. Sources follow the SchemaStore catalog format, including a top-level schemas array with fileMatch and url entries.

[schemas.catalogs]
enabled = true
failure = "warn"
match = "auto"

[[schemas.catalogs.sources]]
name = "company"
format = "schemastore"
path = "./catalog.json"
enabled = true

[[schemas.catalogs.sources]]
name = "schemastore"
format = "schemastore"
url = "https://www.schemastore.org/api/json/catalog.json"
enabled = true

[[schemas.catalogs.sources]]
name = "rubyschema"
format = "rubyschema"
enabled = true

A SchemaStore-shaped source must use exactly one of url or path. Relative schema URLs inside a catalog are resolved relative to that catalog. The built-in rubyschema format is declared without a URL or path because its catalog entries are bundled.

Choose what happens when catalog validation can't run

dollarlint validate . --catalogs --catalog-failure error

If schemas.fetch.enabled = false, remote catalogs are unavailable. With the default warn policy, DollarLint warns and keeps validating explicit or configured local schemas. The same policy applies when a catalog loads but the schema it matched cannot be fetched or compiled. Files that explicitly declare remote schemas still report schema-loading issues when remote fetching is disabled.