feat(atomic-a11y): openACR schema validation

[y-lakhdar]

Summary

Adds schema validation to the OpenACR pipeline. Every generated openacr.yaml is now validated against the official GSA JSON Schema before VPAT generation proceeds.

Why validation over type generation

2 approaches were evaluated to stay aligned with the official Open ACR schema, and chose runtime schema validation. Here's why:

Type generation solves the wrong problem. It ensures our TypeScript compiles against the schema shape at build time, but doesn't verify that our actual YAML output conforms at runtime. A refactor could introduce a bug where resolveConformance() returns an unexpected value or a required field is conditionally undefined , types wouldn't catch it, validation does.

The generated types are too loose to be useful. The GSA schema marks almost everything optional (required: ["title", "product", "author"]). Auto-generated interfaces would have string | undefined on nearly every field, forcing us to either accept loose types everywhere or maintain manual extensions on top — partially defeating the purpose.

The schema is stable. OpenACR is at v0.1.0 and hasn't changed since 2020. Adding a code generation pipeline, a build step, and a generated file to track a spec that doesn't move is overhead with no payoff.

Validation gives a stronger compliance guarantee. The pitch: "Every OpenACR YAML we produce is validated against the official GSA schema. If it doesn't conform, the pipeline fails and no VPAT is generated." That's a concrete, auditable guarantee — not a compile-time hope.

What changed

• scripts/validate-openacr.mjs — Fetches the official GSA JSON Schema, loads the generated openacr.yaml, validates with Ajv, and exits with code 1 on failure (listing all validation errors).
• package.json — Added ajv@8.18.0 as a devDep. Added standalone a11y:validate script. Wired validation into a11y:vpat between YAML generation and VPAT rendering.

Pipeline flow

json-to-openacr.mjs → openacr.yaml
                     → validate-openacr.mjs (fails fast if schema mismatch)
                     → @openacr/openacr output → VPAT markdown

Usage

# Standalone validation
pnpm a11y:validate

# Custom path
node scripts/validate-openacr.mjs path/to/openacr.yaml

# Full pipeline (validation runs automatically)
pnpm a11y:vpat