Frozen document. Dates and status refer to its original source. Private resources and unreviewed images are unavailable.

status: accepted

Use TypeBox for Fastify boundary contracts

On September 30, 2026, the owner confirmed TypeBox for Atlas schema validation. Retain Fastify from ADR 0008, and use TypeBox with @fastify/type-provider-typebox to define code-owned HTTP request and response schemas and infer their TypeScript types. Use Fastify's JSON Schema validation and response serialization. Select and lock compatible package versions in the implementation slice; this decision does not claim that TypeBox is installed today.

The alternative is continuing independent handwritten TypeScript types, request checks and OpenAPI schemas. TypeBox reduces drift between these definitions, but requires migration and compatibility tests. Derived OpenAPI must describe the same wire contracts. Existing published paths, error codes, status codes, idempotency behavior and persisted record shapes remain acceptance guards.

Browser transport amendment, September 30, 2026: ADR 0013 selects tRPC over HTTPS for SPA experience calls. Keep TypeBox for those procedure envelopes and outputs through explicit compatible parsers. Fastify route validation alone does not validate nested tRPC input. REST compatibility paths retain their schema/OpenAPI contract.

Preserve server-driven UI ownership

ADR 0004 remains authoritative. TypeBox defines the supported content-definition vocabulary and transport envelopes. Contentful supplies each form's fields and declarative constraints; the release compiler checks that content against the vocabulary and retains an immutable bilingual release. At runtime the BFF applies that pinned release's rules to answers and joins them with authorized business data and Camunda task state. Do not create code-authored product forms that duplicate CMS constraints.

Treat CMS definitions and submitted answers as untrusted input. Never pass arbitrary Contentful JSON Schema, references, expressions or scripts to Fastify's schema compiler. Keep the reviewed component/rule allowlist, publication size/depth limits and constrained rule evaluator. Any derived validator must use that reviewed compiler and be keyed to the immutable release, not compiled anew from a request. TypeBox does not make arbitrary remote schemas safe.

Boundary policy

Explicitly bound objects, arrays, strings and payload sizes. Reject unexpected command fields rather than silently stripping them; do not coerce command answers, inject defaults or mutate the captured payload used for retry identity. Query coercion, if needed, is an explicit route contract. Translate validation failures into Atlas's existing stable, redacted field errors. Preserve authentication and non-disclosure behavior before returning record-specific information. Perform asynchronous membership, task, revision and business checks in owner services after structural checks, not inside a schema validator.

Response schemas define authorized serialization fields; they do not grant access or replace owner projection checks. Test response conformance and sensitive-field exclusion. TypeBox validation is separate from domain rules, MFA evidence, task eligibility and malware scanning.

Adopt this pattern for new routes and migrate existing routes in behavior-preserving tracer bullets. The boundary design and rollout defines the validation gate. Fastify type providers support TypeBox inference; Fastify validation guidance explains schema compilation and asynchronous-check boundaries.