Configuration

Starter config

# dollarlint configuration
version = 1

[configs]
mode = "single"

[discovery]
exclude = []
useDefaultExcludes = true
respectGitIgnore = true
forceExclude = false
followSymlinks = false

[parsing.json]
mode = "auto"

[schemas]
maxDepth = 8
concurrency = 8
requireCoverage = false

[schemas.optimizations]
enabled = true

[schemas.optimizations.azure]
pruneResources = true

[schemas.fetch]
enabled = true
cache = true
timeout = "10s"
retries = 2
retryMinWait = "250ms"
retryMaxWait = "2s"
allowedDomains = []
blockedDomains = []

[schemas.compile]
timeout = "30s"

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

[[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

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

# [[schemas.associations]]
# file = "settings/*.toml"
# schema = "./schemas/settings.schema.json"

[output]
showSkipped = false
verbose = false
quiet = false
locations = false
branchErrors = "best"
issueHints = "auto"

# [[ignore]]
# file = "fixtures/*.json"
# keyword = "required"
# property = "legacyName"
# reason = "legacy fixture kept for compatibility"

Format and output file are per-run choices — use --format and --output on dollarlint validate whenever you need JSON, SARIF, or a file artifact.

Config selection

Discovery

Leave include unset to use the built-in JSON, JSONC, JSON5, JSON Lines, YAML, YML, and TOML discovery defaults. Set it only when you want to replace that default set with custom discovery globs.

Discovery, exclude, association, and ignore-file globs in config are matched against slash-separated paths relative to the config file's directory. CLI globs are relative to the validation root. A glob without a slash matches basenames at any depth, so *.json matches both package.json and config/settings.json. Use slashes when you want to match a particular relative path shape.

Default excludes are intentionally not written out by dollarlint init. Keep project-specific ignores in exclude.

Relative schema paths in associations and local catalog source paths are resolved from the directory containing .dollarlint.toml.

Nested configs

Set configs.mode = "nearest" in the run root config when a parent-directory run should apply nested .dollarlint.toml files. Each file uses the closest config at or above its directory. A nested config does not inherit parent settings unless it declares extends.

[configs]
mode = "nearest"

# in packages/api/.dollarlint.toml
extends = "../../.dollarlint.toml"

Passing --config keeps single-config behavior for that run and suppresses nested config discovery.

Parsing

JSON parsing defaults to auto: .json files are parsed as strict JSON first, then retried as JSONC when strict parsing fails, so comments and trailing commas work in projects whose existing tools accept them. Files ending in .jsonc always use JSONC parsing.

Schemas

Associations

Associations map discovered files to schemas when the file does not declare one itself. DollarLint also has a built-in association for .dollarlint.toml, backed by the embedded config schema; explicit in-file declarations and user associations still win.

[[schemas.associations]]
file = "settings/*.toml"
schema = "./schemas/settings.schema.json"

Association globs in config are matched relative to the config file's directory and use the same basename-any-depth behavior as discovery globs. In-file declarations win over associations.

Fetch and compile

Optimizations

Optimizations reduce expensive schema work without changing validation semantics. They are enabled by default and can be turned off globally or one optimization at a time when you need to debug schema behavior exactly as fetched.

Catalogs

Catalogs map well-known filenames to schemas when a file doesn't declare $schema and no explicit or built-in association matches. SchemaStore and RubySchema are built-in catalog sources, and custom sources can use the same catalog shape as SchemaStore. Explicit in-file schemas still report schema load or compile failures as issues; the catalog failure policy only applies to catalog loading and catalog-inferred schemas.

The default config includes the SchemaStore and RubySchema sources but keeps catalog matching disabled until you enable schemas.catalogs.enabled or pass --catalogs. The generated config from dollarlint init enables both sources by default.

When the built-in SchemaStore source is enabled, DollarLint adds a small curated layer for known filename gaps and drift. The current curated associations cover rustfmt.toml / .rustfmt.toml, release-plz.toml / .release-plz.toml, and .NET's launchSettings.json / Properties/launchSettings.json.

The built-in RubySchema source covers common Ruby and Rails project configs. Ambiguous Rails and Ruby filenames require nearby project evidence, so they can be reported as skipped catalog candidates instead of guessed blindly.

Catalog matches are reported with schemaMatch metadata in JSON output and with explanatory text hints for catalog-sourced issues. When the inferred schema is correct, add the suggested [[schemas.associations]] rule to make it explicit. When a file should never be inferred from a catalog, use schemas.catalogs.ignore.

Recognized config files without a usable built-in or catalog schema are reported with schemaGap metadata. This marks known high-signal gaps such as netlify.toml, .cargo/config.toml, .terraform-docs.yml, and .asf.yaml without pretending DollarLint has a schema for them.

Ignore rules

[[ignore]]
file = "fixtures/*.json"
keyword = "required"
schemaSource = "config-association"
property = "legacyName"
reason = "legacy fixture kept for compatibility"

Ignore rules match validation issues by file glob, JSON Schema keyword, schema source, and property. All configured fields must match; omitted fields act like wildcards. Ignored issues are still reported as ignored and do not make the run fail.

Output preferences

Config can set issue-reporting and text-output preferences. Machine-readable formats and output files are intentionally per-run choices.