Schema Validation as a Product Boundary

Contracts are product decisions written in code

A schema is not paperwork for the type checker. It is the product's public promise about what fields exist, which are required, what enumerations mean, and what happens when a payload is wrong. Teams that leave that promise implicit discover it in production when a client sends null, a partner adds a synonym field, or a model invents a key that looks almost right.

Staff-level ownership puts the contract at the boundary: ingress from clients, egress to partners, tool results into agents, and structured model outputs before they touch business logic. Inside the boundary you can refactor freely. Across it, change is deliberate, versioned, and measurable.

Validate once, fail closed, keep provenance

Parse at the edge and reject invalid input before it becomes half-processed state. Coercion that 'helps' by guessing types or dropping unknown fields hides product bugs until they become customer-visible. Prefer explicit errors with stable codes over silent repair.

When AI features emit structured JSON, treat the model as an untrusted producer. Validate against the same schema the rest of the system uses. If validation fails, route to retry, clarification, or a deterministic fallback—never to optimistic business writes based on a near-miss object.

• One canonical schema package shared by API, workers, and clients where practical
• Distinguish unknown-field policy: reject on write paths, log on read adapters
• Attach schema version to stored events and audit logs
• Alert on validation failure rate spikes after releases

Evolve without breaking trust

Additive optional fields are cheap; renaming or narrowing meaning is expensive. Publish a compatibility policy: what is additive, what requires a new version, and how long dual-read lasts. For multi-tenant SaaS, tenant-specific extensions belong behind clear namespaces, not free-form bag objects that defeat validation.

Schema tests should travel with the product. Golden payloads for happy paths and adversarial cases—extra fields, wrong enums, oversized strings, missing required keys—belong in CI. If a change breaks a partner integration or an AI tool contract, the suite should fail before customers do.

Make the boundary observable

Track validation outcomes as product health: acceptance rate, top failing paths, latency of parse, and how often AI structured outputs need repair. A rising failure rate after a model or client update is a release signal, not a logging curiosity.

The goal is not bureaucracy. The goal is a sharp line between 'this is our product language' and 'this is someone else's improvisation.' Schema validation is how engineering keeps that line enforceable while the system grows.

• JSON Schema — Spec
• Zod documentation
• OpenAI — Structured Outputs