Cartridge Schema Validation

Cartridge schema validation

This page is the operator's guide to the schema validator that guards cartridges/. The in-tree authority is tools/validate-cartridges/README.md; this wiki page extends it with end-to-end usage, drift-inventory anatomy, and the path to strict mode.

What it validates

Every cartridge.json under cartridges/ is validated against the pinned mirror at schemas/cartridge-v1.json. The validator is a zero-dependency Deno script (only jsr:@std/fs + jsr:@std/path) covering the JSON-Schema subset the cartridge schema actually uses: type, enum, pattern, required, properties, items, minItems.

If the schema ever starts using oneOf / anyOf / $ref, the validator is the right place to upgrade — swap in a fuller implementation at that point.

Command surface

Run all commands from tools/validate-cartridges/:

cd tools/validate-cartridges

deno task audit            # one-line summary per cartridge; ALWAYS exits 0
deno task audit-verbose    # same as audit, plus expand every schema violation
deno task strict           # exits non-zero on any violation (CI-blocking once enabled)
deno task test             # run the validator's unit tests

When to use which

Mode	Use it when
audit	You want the current health snapshot. Safe to run in CI today; it never fails the run.
audit-verbose	You're triaging the drift inventory and need per-manifest violation detail.
strict	You believe all manifests pass and want a hard gate. CI flips to this once drift is zero.
test	You're modifying the validator itself, or want to confirm the rule engine is sane.

How to read the output

audit mode prints a header and a top-N-recurring-issues block, then a per-manifest section listing each violation:

# Cartridge manifest validation report
Schema: schemas/cartridge-v1.json
Manifests: 139 total / 13 passing / 126 failing

## Top recurring issues
- 126× category: required field missing
- 21× auth.method: value "bearer_token"
- 8× api: required field missing
...

## Per-manifest failures

### cartridges/cross-cutting/agentic/agent-mcp/cartridge.json
- `category` — required field missing

### cartridges/cross-cutting/agentic/claude-ai-mcp/cartridge.json
- `category` — required field missing
- `auth.method` — value "api_key_header" not in enum ["none","api-key","oauth2","vault"]

Three things to look at on a fresh run:

1. Header counters — totals tell you the big picture in one glance: 139 total / 13 passing / 126 failing.
2. Top recurring issues — a frequency-sorted histogram of the violation kinds. This is where you find batchable fixes (e.g., the 126× missing category is one PR).
3. Per-manifest failures — once you know what you're fixing, jump to the path you care about.

Drift inventory structure

The current drift baseline lives at audits/cartridge-schema-2026-06-01.md. It is the captured output of deno task audit-verbose at a moment in time, frozen so that progress can be measured deterministically. The file has three sections:

1. Header — schema path, manifest counters.
2. Top recurring issues — frequency histogram of violation kinds.
3. Per-manifest failures — one section per failing manifest, each listing the specific field-level violations.

Remediation is tracked under three issues:

• #18 — missing category field (126 manifests after the gossamer template fix). Single batch PR.
• #19 — auth.method enum mismatches: bearer_token (21), api_key (5), and stragglers (api_key_header, session-token, api_token, optional_api_key, optional_bearer, basic, bearer) vs canonical api-key / oauth2 / vault / none.
• #20 — canonical-only cartridges + other missing top-level fields (protocols, api, auth.env_var, auth.credential_source, tools[*].inputSchema).

A new audit file (audits/cartridge-schema-YYYY-MM-DD.md) is captured each time the inventory shrinks meaningfully, so the trajectory is auditable.

Path to strict mode

The CI gate (.github/workflows/cartridge-schema.yml) runs deno task audit today. Once the drift inventory at audits/cartridge-schema-2026-06-01.md records 139 total / 139 passing / 0 failing:

1. Replace the deno task audit step with deno task strict.
2. Drop the audit-mode tee to $GITHUB_STEP_SUMMARY (or keep it; both are fine).
3. Lock the workflow as a required status check in the Base ruleset.

From that point on, any PR that introduces a non-validating cartridge fails CI.

CI gate behaviour (audit mode, today)

.github/workflows/cartridge-schema.yml runs on every push to main/master and every pull request. It performs three steps in order:

1. Schema mirror SHA-256 verification. Computes sha256sum schemas/cartridge-v1.json and compares it against content_sha256 in schemas/PINNED-SHA. Fails the job loudly if they disagree — silent drift between the pinned record and the file content is a CI red. This is the single hard gate that exists today.
2. Validator unit tests. Runs deno task test inside tools/validate-cartridges/. Fails the job on any failing test.
3. Audit all manifests. Runs deno task audit and tees the report into the GitHub step summary. Does not fail the job — this is audit mode.

When strict mode flips on, step 3 becomes the blocking gate too.

Adding a new cartridge

cp -r cartridges/templates/gossamer-mcp cartridges/domains/<your-domain>/<your-cartridge-name>
cd cartridges/domains/<your-domain>/<your-cartridge-name>
# edit cartridge.json — name, version, category, role, protocols, api, auth, tools

Then from the repo root:

cd tools/validate-cartridges
deno task audit-verbose | less    # confirm your new manifest passes

A manifest that passes validation today must have, at minimum:

• name matching /^[a-z0-9]+(-[a-z0-9]+)*-(mcp|lsp|dap|bsp|debug|format|lint|build|nesy|agentic|fleet)$/
• version (semver string)
• category (the field that 126 of 139 current manifests are missing)
• protocols array
• api object
• auth.method ∈ ["none","api-key","oauth2","vault"]
• auth.env_var and auth.credential_source (unless auth.method = "none")
• Every tools[i] carries an inputSchema

For the full normative list, read the schema directly: schemas/cartridge-v1.json.

Open a PR; auto-merge is enabled by default for this repo. Once strict mode is on, the audit step will block your PR if your manifest fails — fix locally before pushing.