| name | schema-source-of-truth |
| description | One canonical Zod schema per entity, reused across the stack instead of redeclared at each layer. Use whenever defining or changing a data shape, a TypeScript type or interface for an entity, an API request/response validator, an Express body/query/params check, a frontend form validator, or a DB document shape. Catches the same-entity-defined-four-times drift. TypeScript-first, derive types and per-layer variants from one base instead of hand-writing parallel copies. |
| when_to_use | - Defining or editing an entity's shape (a User, Order, etc.) in types, an API, a form, or the DB
- Writing API request/response validation or Express middleware that checks req.body / query / params
- Writing a frontend form validator, or a TypeScript interface/type for data that also lives on the backend
- Any moment you're about to write a second definition of a shape that already exists somewhere
- Do NOT use for one-off internal types with no cross-layer counterpart
|
Schema as a Single Source of Truth
A data entity should be defined once, as a Zod schema, and everything else derived from it. The failure pattern to kill: declaring the same entity separately at each layer, a frontend interface User, a backend interface User, a hand-written API validator, and a manual Mongo $jsonSchema. Four shapes for one entity, kept in sync by hand, guaranteed to drift the first time a field is added or renamed.
One schema per entity, derive the rest
Define the canonical schema once and generate every other representation from it:
- TypeScript type:
type User = z.infer<typeof UserSchema>. Never hand-write an interface that parallels a schema, infer it so it can't fall out of sync.
- API validation: parse
req.body / req.query / req.params through the schema in middleware. safeParse and return 400 on failure, no field-by-field if checks.
- Frontend forms: the same schema drives form validation (
zodResolver with react-hook-form), so client and server reject the same inputs by the same rules.
- Pre-write guard: parse before writing to the DB. See the
mongodb-rules skill for the Mongo-specific parse-before-write and $jsonSchema floor.
- OpenAPI and
$jsonSchema: generate them from the schema (zod-to-openapi, zod-to-json-schema) rather than maintaining them by hand.
Zod is TypeScript-first with zero runtime dependencies, so this costs one small library and removes every duplicated definition.
One base, many variants (they are not identical)
"Same schema everywhere" is the goal, but a create payload is not the stored document and a response is not the request, so don't pretend they're one object. Model it honestly: one base schema, with per-layer variants derived from it, sharing a single origin while differing where they genuinely must.
const UserSchema = z.object({
_id: z.string(),
email: z.string().email(),
name: z.string().min(1),
createdAt: z.date(),
});
const CreateUser = UserSchema.omit({ _id: true, createdAt: true });
const UpdateUser = CreateUser.partial();
const UserResponse = UserSchema.extend({ displayName: z.string() });
type User = z.infer<typeof UserSchema>;
Derive variants with .omit(), .partial(), .pick(), .extend(). When the base gains a field, every variant inherits it automatically, which is the entire point. A hand-copied variant is just the drift problem at smaller scale.
Make it physically shared
Single source of truth only holds if there is literally one file. Put entity schemas in a shared module both sides import, a packages/schemas workspace, or a shared src/schemas/ reachable by frontend and backend. If each side keeps its own copy, they diverge no matter how disciplined the intent. The shared import is the enforcement, not the convention.
