Rule schemas

Apply this rule whenever work touches:

• *.ts

Zod is the runtime validation library for this project. Schemas serve a dual purpose: they validate data at runtime boundaries and provide the canonical type definition via z.infer.

Schema definition

Define schemas close to the types they describe. A common pattern is to export both from the same file:

ts
1import { z } from 'zod';
2
3export const VehicleSchema = z.object({
4  plate: z.string().min(7),
5  weightKg: z.number().positive(),
6  type: z.enum(['truck', 'van', 'car']),
7});
8
9export type Vehicle = z.infer<typeof VehicleSchema>;

Never create a separate interface Vehicle that duplicates the schema shape.

Validation strategy

Choose the right parse method based on the trust level of the data:

ts
1// External input (API payload, S3 object, SQS message) - handle errors
2const result = VehicleSchema.safeParse(rawPayload);
3if (!result.success) {
4  logger.warn('Invalid vehicle payload', result.error.flatten());
5  return { error: 'INVALID_INPUT' };
6}
7const vehicle = result.data;
8
9// Internal data (already validated upstream) - let it throw
10const vehicle = VehicleSchema.parse(trustedData);

Schema composition

Reuse schemas through composition rather than copy-pasting fields:

ts
1const BaseDocumentSchema = z.object({
2  id: z.string().uuid(),
3  createdAt: z.string().datetime(),
4});
5
6const CertificateSchema = BaseDocumentSchema.extend({
7  issuer: z.string(),
8  validUntil: z.string().datetime(),
9});

Test data generation

Use zocker and the shared testing utilities to generate test data from schemas:

ts
1import { createStubFromSchema } from '@carrot-fndn/shared/testing';
2
3const stubVehicle = createStubFromSchema(VehicleSchema);

This ensures test data always conforms to the current schema shape and evolves automatically when the schema changes.