Apply different schemas to different folders

Real docs repos are not uniform. Your /api reference pages might need a type: api-reference field and an extra schema, while your /guides only need the baseline. docmeta handles this with overrides in your docmeta.config.yaml: each override maps a glob of files to its own schema set, so you can tighten the rules for one area without touching the rest.

This guide assumes you already have a working config. If not, start with Create your docmeta.config.yaml.

Assign a schema set per area

An overrides entry pairs a files glob with a schemas list. Any file matching the glob is validated against that override’s schemas instead of the default schemas.

docmeta.config.yaml

# The baseline every doc must satisfy.
schemas:
  - google:okf:0.1

# Area-specific rules.
overrides:
  - files: "api/**/*.md"
    schemas:
      - ./schemas/api-reference.json
  - files: "guides/**/*.md"
    schemas:
      - ./schemas/guide.json

With this config:

• Files under api/ are validated against ./schemas/api-reference.json.
• Files under guides/ are validated against ./schemas/guide.json.
• Everything else falls back to the default schemas — here, google:okf:0.1.

Note

An override replaces the default schemas for matching files — it does not add to them. If you want an area to satisfy the baseline and an extra schema, list both in that override (see Validate one file against multiple schemas below).

First matching override wins

docmeta evaluates overrides in order and stops at the first glob that matches a given file. Order your overrides from most specific to least specific, so a narrow rule is not shadowed by a broader one above it.

docmeta.config.yaml

overrides:
  # Specific first: deprecated API pages need their own schema.
  - files: "api/deprecated/**/*.md"
    schemas:
      - ./schemas/deprecated.json
  # General second: everything else under api/.
  - files: "api/**/*.md"
    schemas:
      - ./schemas/api-reference.json

Here, api/deprecated/v1.md matches the first override and is validated against deprecated.json. A file like api/auth.md falls through to the second override. If you reversed the two entries, the broad api/**/*.md glob would match the deprecated pages first and they would never reach their specific rule.

Tip

Globs match against POSIX-style paths (forward slashes), so write api/**/*.md even on Windows. docmeta normalizes path separators before matching.

Validate one file against multiple schemas

A schemas list — whether the default set or an override — applies as a set: the file must satisfy every schema in the list. List more than one to compose rules.

docmeta.config.yaml

overrides:
  - files: "api/**/*.md"
    schemas:
      - google:okf:0.1            # baseline: requires type
      - ./schemas/api-reference.json   # plus: requires the api-specific fields

A file under api/ must now pass both schemas. This lets you keep the shared baseline (OKF’s required type) while layering area-specific requirements on top, rather than duplicating the baseline rules in every custom schema.

Where overrides sit in schema resolution

Overrides are one link in docmeta’s schema-resolution chain. For any single file, docmeta picks the first source that applies, in this order:

1. CLI --schema flag — if you pass -s <ref> (repeatable), it overrides everything below for the whole run.

2. File $schema field — a $schema key in the file’s own frontmatter names its schema set and overrides the config.

3. Config overrides — the first matching override’s schemas, as described on this page.

4. Config schemas — the default set, when no override matches.

5. Built-in default — google:okf:0.1, when nothing else resolves.

So an override governs a file only when no --schema flag is set and the file has no $schema of its own. A contributor can always pin a specific file to a different schema with a $schema line, and you can always force a schema for a one-off run with --schema.

Schema resolution referenceThe full precedence chain and the three reference kinds — built-in id, file path, and URL — in detail.

Verify your overrides

After editing your config, confirm each area resolves to the schema set you expect. Run docmeta and read the per-file output, which reports the schemas applied to each file.

npx docmeta validate

If a file matches the wrong override, check the order of your overrides entries — remember the first matching glob wins.