ADR-019 — JSON schema validation on PR via ajv

Status · Accepted Date · 2026-04-28 TA anchor · §stack · §contracts

Context

Mission data lives in JSON files editable by contributors without JavaScript knowledge. A malformed mission file (missing required field, wrong type) currently fails silently at runtime. At production scale with external contributors, this needs to fail loudly at PR time.

Decision

JSON schema validation runs in CI on every PR that touches data/. The validator is ajv (Another JSON Schema Validator) — a Node library, no external service. A JSON Schema file at data/schemas/mission.schema.json defines the required shape. The CI step fails if any mission file does not conform.

Rationale

ajv is the standard Node JSON Schema validator — well-maintained, fast, no runtime dependency in the browser. A failed validation produces a clear error message naming the file and field. Combined with the doc-system checks from the guide's §18 checklist, a contributor's PR gets mechanical correctness feedback without any human review.

Alternatives considered

• TypeScript interfaces only — catches type errors in code but not in JSON files at rest; rejected as sole approach.
• Zod at runtime — validates at fetch time; errors reach the browser; rejected in favour of catching at PR time.
• Manual review — does not scale; rejected.

Consequences

Positive: malformed mission files never reach main; contributor feedback is immediate and specific; schema is documentation. Negative: schema must be kept in sync with the data client's TypeScript interfaces (two sources of truth for the same shape — mitigated by generating one from the other via ts-json-schema-generator).

Implementation notes

data/schemas/mission.schema.json defines required fields and types. scripts/validate-data.ts runs ajv against all files in data/missions/. CI step: npx tsx scripts/validate-data.ts. Runs on PR and on push to main.