Lintel Catalog Builder (Lintel) JSON Schema

Type	object
File match	`lintel-catalog.toml` `**/lintel-catalog.toml`
Schema URL	https://catalog.lintel.tools/schemas/lintel/lintel-catalog-toml/latest.json

Validate with Lintel

npx @lintel/lintel check

Type: object

Configuration file for the Lintel catalog builder.

Defines how to build a JSON Schema catalog from local schema definitions and external sources. The catalog builder reads this file, fetches schemas, organizes them into groups, and writes the output to one or more targets.

Place this file at the root of your catalog repository.

Properties

catalog object required

Metadata for the catalog, specified in the [catalog] section.

This section is required even if empty.

2 nested properties

title string | null

Human-readable title for the catalog, included in the generated catalog.json output.

Default: null

Examples: "Lintel Schema Catalog"

source-base-url string | null

Base URL for local schema source files.

When set, local schemas (those without a url) get their x-lintel source field constructed as {source-base-url}/schemas/{group}/{key}.json. This is typically a raw GitHub URL pointing to the catalog repository.

When omitted, local schemas use a relative path like schemas/{group}/{key}.json.

Default: null

Examples: "https://raw.githubusercontent.com/lintel-rs/catalog/master"

target Record<string, object>

Named build targets that control where output files are written.

Each key is a target name (e.g. local, pages) and the value specifies the target type and its options. Multiple targets can be built in a single run.

Corresponds to [target.<name>] sections in TOML.

groups Record<string, object>

Named schema groups.

Each key is a group identifier (used as the output directory name) and the value defines the group's display name, description, and schema definitions.

Corresponds to [groups.<name>] sections in TOML.

sources Record<string, object>

Named external catalog sources to import schemas from.

Each key is a source identifier and the value specifies the catalog URL and optional organization rules that route imported schemas into groups.

Corresponds to [sources.<name>] sections in TOML.

Definitions

CatalogMeta object

Metadata for the catalog, specified in the [catalog] section.

This section is required even if empty.

title string | null

Human-readable title for the catalog, included in the generated catalog.json output.

Default: null

Examples: "Lintel Schema Catalog"

source-base-url string | null

Base URL for local schema source files.

When omitted, local schemas use a relative path like schemas/{group}/{key}.json.

Default: null

Examples: "https://raw.githubusercontent.com/lintel-rs/catalog/master"

TargetConfig object

Output target configuration.

Each target specifies where the built catalog and schema files are written. When site.github is present, GitHub Pages files (.nojekyll, CNAME) are written automatically.

dir string required

Output directory path (relative to the catalog repository root).

Examples: "../catalog-generated"

base-url string required

Base URL where the catalog will be hosted. Schema URLs in catalog.json are constructed relative to this URL.

Examples: "https://raw.githubusercontent.com/org/catalog/master/"

site SiteConfig | null

Site-level configuration for description and hosting options.

SiteConfig object

Site-level configuration for a build target.

Controls metadata and hosting options that apply to the generated static site.

description string | null

Human-readable description for the site, used in the HTML meta description tag and JSON-LD structured data.

Default: null

ga-tracking-id string | null

Google Analytics tracking ID (measurement ID).

When set, the generated site includes the Google Analytics Global Site Tag (gtag.js) snippet in every page's <head>. The snippet loads the gtag.js library and configures it with the provided measurement ID.

The injected markup looks like:

<!-- Google tag (gtag.js) -->
<script async src="<https://www.googletagmanager.com/gtag/js?id=GA_TRACKING_ID>"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'GA_TRACKING_ID');
</script>

where GA_TRACKING_ID is replaced with the value of this field (e.g. G-XXXXXXXXXX).

Leave unset (or omit) to disable Google Analytics entirely.

Default: null

Examples: "G-XXXXXXXXXX"

github GitHubPagesConfig | null

GitHub Pages hosting options.

GitHubPagesConfig object

Options for GitHub Pages hosting.

When present on a dir target, a .nojekyll file is created and an optional CNAME file is written.

cname string | null

Custom domain for GitHub Pages. When set, a CNAME file is written to the output directory with this value.

Default: null

Examples: "catalog.example.com"

GroupConfig object

A named collection of related schema definitions.

Groups organize schemas into directories in the built catalog. Each group has a display name and description that appear in the catalog index, and contains one or more schema definitions.

Corresponds to a [groups.<id>] section in TOML.

name string required

Human-readable display name for this group.

Examples: "GitHub", "Claude Code"

description string required

Short description of the schemas in this group, shown in the catalog index.

schemas Record<string, object>

Schema definitions within this group.

Each key is a schema identifier (used as the filename, e.g. agent -> agent.json) and the value describes the schema source, display name, and file-match patterns.

Corresponds to [groups.<group>.schemas.<id>] sections in TOML.

SchemaDefinition object

An individual schema entry within a group.

Defines where to obtain the schema, its display metadata, and which files it should match in the catalog.

The name and description fields are optional overrides. When omitted, they are auto-populated from the underlying JSON Schema's title and description properties. If the schema has no title, the entry key is used as a fallback name.

url string | null

URL to download the schema from.

If omitted, the schema is expected to already exist locally at schemas/<group>/<key>.json.

name string | null

Human-readable display name for this schema.

When omitted, defaults to the title property from the JSON Schema.

Default: null

Examples: "GitHub Workflow", "devenv.yaml"

description string | null

Short description of what this schema validates.

When omitted, defaults to the description property from the JSON Schema.

Default: null

file-match string[]

Glob patterns for files this schema should be auto-associated with.

Editors and tools use these patterns to automatically apply the schema when a matching file is opened.

Default:

[]

Examples: ["**/.github/workflows/*.yml"], ["devenv.yaml"]

versions Record<string, string>

Alternate versions of this schema, keyed by version identifier. Values are URLs to the versioned schema.

Default:

{}

SourceConfig object

An external schema catalog to import schemas from.

The catalog builder fetches the JSON catalog from the given URL, then uses the organize rules to route matching schemas into local groups.

Corresponds to a [sources.<id>] section in TOML.

url string required

URL to the external catalog JSON file (in SchemaStore format: {"schemas": [...]}).

Examples: "https://www.schemastore.org/api/json/catalog.json"

exclude-matches string[]

Filenames to exclude from this source.

If any of a schema's fileMatch entries match one of these patterns (using the same glob logic as organize), the schema is skipped entirely. Use this to suppress source schemas that duplicate explicitly configured group entries.

Default:

[]

Examples: ["biome.jsonc"]

organize Record<string, object>

Rules for routing schemas from this source into local groups.

Each key is a group identifier (matching a key in [groups]) and the value contains glob patterns. Schemas whose names or URLs match any pattern are placed into that group.

Corresponds to [sources.<source>.organize.<group>] sections in TOML.

OrganizeEntry object

Routing rule that assigns schemas from an external source to a local group.

Contains glob patterns to match against schema names or URLs. Group metadata (display name, description) is defined in the corresponding [groups] entry.

match string[] required

Glob patterns matched against schema names or URLs from the external catalog.

Schemas matching any pattern are imported into the corresponding group directory.

Examples: ["**.github**"], ["*docker*"]