ADR Precursor: Reduce supply-chain exposure of the JSON Schema validation toolchain (ajv → Rust jsonschema / Python)

[zircote]

ADR Precursor — Structured MADR seed. This is a pre-decision discussion seed in Structured MADR shape. It is deliberately undecided (status: proposed, Decision: PENDING) and exists to mature the options — including the keep-current option — before anything is written into an accepted ADR under adr/. When it matures, it drops into adr/ADR-NNN-...md (next free number) with the frontmatter below.

title: "Validation Toolchain: Reduce Supply-Chain Exposure of JSON Schema Validation"
description: "Whether to replace the unpinned npm ajv-cli/ajv-formats CI validator with a Rust (jsonschema/boon) validator or the already-vendored Python jsonschema stack to shrink the validation toolchain's supply-chain surface."
type: adr
category: security
tags:
  - supply-chain
  - validation
  - json-schema
  - ci
  - tooling
  - rust
status: proposed
created: 2026-06-28
updated: 2026-06-28
author: MIF Maintainers
project: MIF
technologies:
  - ajv
  - rust
  - jsonschema
  - boon
  - python
audience:
  - developers
  - architects
related:
  - ADR-015-attested-release-orchestration.md
  - ADR-012-okf-conformance-tested-invariant.md

ADR Precursor: Reduce Supply-Chain Exposure of the JSON Schema Validation Toolchain

Status

Proposed — precursor / undecided. No option is selected. This seed exists to gather input and converge on the trade-offs before an ADR is written.

Context

Background and Problem Statement

MIF treats JSON Schema validation as a gating CI invariant (ADR-012): every derived JSON-LD projection MUST validate against the canonical 2020-12 schemas. That gate is implemented in .github/workflows/validate.yml. The validation step is:

# .github/workflows/validate.yml
- name: Install ajv-cli
  run: npm install -g ajv-cli ajv-formats          # L76–77

- name: Validate every projection against schema/mif.schema.json
  run: |
    ajv validate -s schema/mif.schema.json \
      -r "schema/definitions/*.schema.json" \
      -d "$json" --spec=draft2020 -c ajv-formats    # L93–95

Separately, the ontology and memory gates already run a different validator — Python jsonschema (Draft202012Validator) in scripts/validate-ontologies.py, scripts/validate-memories.py, and scripts/validate-namespaces.py. So the project already maintains two validator stacks: ajv (JS, for projection validation) and Python jsonschema (for ontology/memory/namespace validation).

Current Limitations

1. Unpinned, mutable supply-chain entry in an otherwise SHA-pinned gate. Every uses: in validate.yml is SHA-pinned (actions/checkout@9c091bb…, actions/setup-node@48b55a0…), per the org's pin-everything posture. The one exception is npm install -g ajv-cli ajv-formats (L77): a global, version-floating install that resolves ajv-cli, ajv-formats, and their transitive npm dependencies fresh at CI time, with no lockfile and no integrity pin. This is the softest link in a gate that ADR-015 otherwise hardens to SLSA L3.

2. Two validator stacks, two trust roots. The projection gate trusts the npm registry + ajv's transitive tree; the ontology/memory gates trust PyPI + jsonschema's tree. Divergent behavior between the two stacks (e.g. format-assertion handling) is possible and unmonitored.

3. No attestation over the validator itself. MIF attests its release artifacts (ADR-015) but the tool that asserts schema conformance is pulled unattested at run time.

Decision Drivers

Primary Decision Drivers

1. Minimize the validation path's third-party transitive surface — the stated primary motivation. Fewer, pinned, attestable dependencies in the gate that asserts conformance.
2. Coherence with the attested-delivery posture (ADR-015). The validator should be pinnable (ideally a single, attestable binary) rather than a floating global npm install.
3. No loss of conformance. Whatever runs the gate MUST cover JSON Schema 2020-12 with format assertion parity to today's ajv-formats behavior, and must keep external $ref resolution against schema/definitions/*.schema.json.

Secondary Decision Drivers

1. Consolidation onto a single validator stack (one trust root, one conformance profile) rather than two.
2. Reproducibility / pinning — lockfile or vendored binary so CI is deterministic.
3. Performance — secondary; the corpus is small.

Considered Options

Option 1: Adopt the Rust jsonschema crate (jsonschema-cli), pinned + attested

Description: Replace ajv with the Rust jsonschema validator (v0.42 at time of writing, Rust ≥ 1.83) via its jsonschema-cli, built and attested like other release artifacts, or vendored as a pinned binary.

Advantages:

• Full Draft 2020-12 support; custom format validators; external $ref resolution.
• Compiles to a single binary that can be SHA-pinned and attested — directly addresses the primary driver.
• High performance (the crate benchmarks well above boon).

Disadvantages:

• Adds a Rust build/toolchain step to the validation pipeline (or a vendored-binary management story).
• Newer-draft keyword coverage has documented gaps; format-assertion parity with ajv-formats must be verified against the 2020-12 conformance suite.
• A third language toolchain in the repo (alongside Node and Python).

Risk Assessment: Technical: Medium (format/keyword parity must be proven). Schedule: Medium. Ecosystem: Low–Medium (actively maintained, recent release).

Option 2: Adopt boon (pure-Rust validator/CLI)

Description: Use boon (library + CLI), draft 2020-12 / 2019-09 / 7 / 6 / 4.

Advantages:

• Pure Rust, no C deps; library + CLI; pinnable/attestable single binary.
• Broad draft coverage including 2020-12.

Disadvantages:

• Slower than the jsonschema crate (reported 2–52× in the maintainers' comparison); performance is a secondary driver so this is minor.
• Smaller ecosystem/userbase than ajv; format-assertion parity still needs verification.

Risk Assessment: Technical: Medium. Schedule: Medium. Ecosystem: Medium.

Option 3 (exculpatory — keep current): Keep ajv-cli + ajv-formats, harden the install

Description: Retain the canonical JS reference validator but remove the floating-global weakness: pin via a committed lockfile / npm ci from a small dedicated manifest, prefer exact versions, enable npm provenance, and let Dependabot bump deliberately.

Advantages:

• ajv is the most widely used, most conformance-complete 2020-12 validator with mature ajv-formats; zero behavioral risk — the gate keeps doing exactly what it does today.
• No new toolchain; smallest change.
• The supply-chain concern is largely mitigable in place: the actual defect is the unpinned global install (L77), not ajv itself — a lockfile + pinned versions + provenance closes most of the gap without swapping validators.

Disadvantages:

• Even pinned, the npm transitive tree remains larger than a single Rust binary, and the second (Python) stack still exists.
• Does not advance the consolidation driver.

Risk Assessment: Technical: Low. Schedule: Low. Ecosystem: Low.

Option 4 (exculpatory alternative — consolidate): Drop ajv, use the already-vendored Python jsonschema

Description: Validate projections with the Python jsonschema (Draft202012Validator) the repo already depends on for ontology/memory/namespace gates. Add a thin projection-validation script; remove the npm validator entirely.

Advantages:

• Eliminates the npm validator and L77 outright with no new toolchain — Python is already set up in the same workflow (actions/setup-python, pip install).
• Collapses two validator stacks into one trust root and one conformance profile (the consolidation driver).
• Pinnable via a pinned pip install jsonschema==X / lockfile.

Disadvantages:

• Python jsonschema's 2020-12 + format-assertion coverage differs from ajv-formats; parity must be checked (formats are opt-in and require format checkers / fqformat extras).
• Still a PyPI dependency surface (smaller, but not a single attestable binary like Options 1–2).
• Need to confirm equivalent external $ref resolution against schema/definitions/*.

Risk Assessment: Technical: Medium (format parity). Schedule: Low. Ecosystem: Low.

Decision

PENDING. Deliberately undecided. This precursor records the option space; the eventual ADR will select one after the open questions are answered.

Open Questions

1. Format-assertion parity: which ajv-formats formats does the gate actually rely on, and does each candidate (Rust jsonschema, boon, Python jsonschema) assert them identically under 2020-12?
2. $ref resolution: does each candidate resolve -r "schema/definitions/*.schema.json" equivalently?
3. Conformance evidence: run the candidates against the official JSON Schema 2020-12 test suite and compare pass rates before committing.
4. Attestable binary vs. pinned package: is a single attested binary (Options 1–2) worth the extra toolchain over a pinned package (Options 3–4)?
5. Consolidate or not: is collapsing to one validator stack (Option 4) preferable to a best-of-breed-per-language split?
6. Scope of "supply chain": is the goal "remove npm from the gate," or "everything in the gate is pinned + attested" (which Option 3 can satisfy without a validator swap)?

Links

• validate.yml — the gate
• Rust jsonschema crate · jsonschema-cli
• boon (santhosh-tekuri)
• ajv JSON Schema validator · ajv-formats
• ADR-015 (attested release orchestration) · ADR-012 (OKF conformance as a tested invariant)

[zircote]

🙄