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

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[svcsnykcoveo]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[fbeaudoincoveo]

👌

[alexprudhomme]

Hey @y-lakhdar 👋 ✅ This PR does not need a changeset file — you don't have one currently, so it's perfect. This PR only affects @coveo/atomic-a11y, which is a private package and is not published to npm. For more info on when changesets are needed, see the Changesets README.