Validation with Zod

The API uses Zod 4.4.2. Every input that crosses the HTTP boundary is parsed by a schema from the module’s *.schema.ts before any other code reads it.

Where parsing happens

Controllers parse. Services receive typed values and trust them.

const update = async (req: Request, res: Response) => {
  const { id } = idParam.parse(req.params);
  const body = updateProductBody.parse(req.body);
  ok(res, req, await service.update(studioIdOf(req), id, body));
};

parse throws a ZodError. Express 5 forwards the rejection to errorMiddleware, which answers:

{
  "ok": false,
  "code": "VALIDATION",
  "message": "validation failed",
  "details": [{ "path": ["priceAgorot"], "message": "Too small: expected number to be >=0" }],
  "requestId": "01J..."
}

Status is 422. There is no validation middleware and no wrapper. The pattern is one schema.parse(...) per input source at the top of the handler.

Naming

Input	Name	Example
Create body	`create<Entity>Body`	`createProductBody`
Update body	`update<Entity>Body`	`updateProductBody`
List query	`<entity>ListQuery`	`productListQuery`
Path params	`idParam`, or a named one	`idParam`, `studioIdParam`, `typeParam`
Inferred type	PascalCase of the schema	`export type CreateProductBody = z.infer<typeof createProductBody>`

Each module declares its own idParam. It is one line and keeps modules independent.

Patterns used in the codebase

Coerce query strings, not bodies

req.query is strings, so query schemas use z.coerce:

page: z.coerce.number().int().positive().default(1),
pageSize: z.coerce.number().int().positive().max(500).default(20),
active: z.coerce.boolean().optional(),

z.coerce.boolean() uses JavaScript truthiness. The string "false" coerces to true. productListQuery.active behaves that way today: ?active=false filters for active plans. For a query flag that must accept false, use an enum of 'true' and 'false' with a transform, the way config.ts handles boolean env values.

JSON bodies are not coerced. A number sent as a string fails validation, which is what you want from a typed client.

One value or many in a query

A repeated query key arrives as an array, a single one as a string. Normalize with a union and a transform:

clientIds: z
  .union([z.string().min(1), z.array(z.string().min(1))])
  .transform((value) => (Array.isArray(value) ? value : [value]))
  .optional(),

`null` and `undefined` mean different things

Update bodies are partial, so every field is .optional(). A field that can be cleared is also .nullable():

displayName: z.string().nullable().optional(),

Key absent: leave the stored value alone.
Key present with null: clear it.

The workspace compiles with exactOptionalPropertyTypes. A property typed x?: string does not accept an explicit undefined. That is why repository code builds objects with conditional spreads instead of passing possibly undefined values through:

const data: Prisma.ProgramFolderUncheckedUpdateInput = {
  ...(input.name !== undefined ? { name: input.name } : {}),
  ...(input.color !== undefined ? { color: input.color } : {}),
};

Defaults in the schema

Defaults belong in the schema so the inferred type is non optional for the service: durationUnit: durationUnit.default('MONTHS'), active: z.boolean().default(true).

Bounded arrays

Bulk endpoints cap their arrays in the schema. assignProductBulkBody.clientIds is .min(1).max(500). Add a bound to every array a client can send.

Enums

Use z.enum([...]) with string literals that match the Prisma enum. Do not write TypeScript enums. Shared constants such as StudioRole and ErrorCode are as const objects with a derived union type in @perform/types.

Dates

z.coerce.date() turns an ISO string into a Date. For a date only string such as 2026-08-01, that is UTC midnight. Columns that hold a civil day rely on that. See Time zones and day keys.

Stored JSON

JSON columns are validated on the way out as well as on the way in. readCoachPermissions runs coachPermissions.safeParse(stored) and falls back to a safe value when the stored blob does not match. messagesOf does the same for notification messages. Never cast a JSON column straight to a type.

Parsing with `safeParse`

Use safeParse when a failure is not a client error or needs a custom response: env parsing in defineEnv, stored JSON, and the public waitlist route, which answers a bare 400 without details on purpose.

Semantic rules live in the service

Zod checks shape. A rule that needs the database or depends on other fields in context belongs in the service and throws AppError:

“The linked form must exist in this studio and be an onboarding form” is a service rule (assertForms).
“name must be at least one character” is a schema rule.

A few modules validate a normalized structure after parsing and return a list of issues with stable codes instead of throwing on the first one. normalizeSetting in lib/notification-messages.ts returns { issues, value } with codes such as tooManyMessages, titleRequired and offsetOutOfRange so the settings screen can mark each field.

Lanes with different validation output

/v1/automation turns a ZodError into a single sentence. See Responses and errors.
/v1/public/sign answers 400 with a fixed Hebrew message and code: 'VALIDATION'.
MCP tools validate with the tool’s inputSchema in the MCP SDK before the HTTP call is made. The automation lane validates again.

Env and tool schemas

Zod is also the schema language for:

Environment variables (apps/core-api/src/config.ts).
LLM structured output. generateObject from the AI SDK takes a Zod schema, for example analysisSchema in ai/nutrition-analyzer.ts.
MCP tool inputs (packages/mcp-tools/src/tools.ts). .describe(...) text on each field is what the model reads.
oRPC procedure inputs in @repo/api.
Generated model schemas in @repo/database (prisma/zod/), produced by prisma-zod-generator.

​Where parsing happens

​Naming

​Patterns used in the codebase

​Coerce query strings, not bodies

​One value or many in a query

​null and undefined mean different things

​Defaults in the schema

​Bounded arrays

​Enums

​Dates

​Stored JSON

​Parsing with safeParse

​Semantic rules live in the service

​Lanes with different validation output

​Env and tool schemas

Where parsing happens

Naming

Patterns used in the codebase

Coerce query strings, not bodies

One value or many in a query

`null` and `undefined` mean different things

Defaults in the schema

Bounded arrays

Enums

Dates

Stored JSON

Parsing with `safeParse`

Semantic rules live in the service

Lanes with different validation output

Env and tool schemas