Validation
A resource generates the schema of the requests it accepts, from its own field rules, paths, defaults and limits. There's no second contract to keep in sync, and server context such as the tenant stays out of it.
| Package | requestSchema | responseSchema |
|---|---|---|
drizzle-resource/zod | yes | yes |
drizzle-resource/valibot | yes | yes |
drizzle-resource/vine | yes | no |
Limits
Limits live on the resource, and the engine enforces them even when no schema is used:
import { createQueryEngine } from "drizzle-resource";
const engine = createQueryEngine({ db, schema, relations });
const orders = engine.defineResource("orders", {
query: {
validation: {
maxPageSize: 100,
maxFilterDepth: 5,
maxFilterNodes: 50,
maxFacetCount: 10,
maxFacetLimit: 50,
},
},
});
These are the defaults. Read the effective values back from the resource:
const maxPageSize = ordersResource.queryConfig.validation.maxPageSize;
Request schemas
Create the schema once and parse each body before calling the resource. The body can't contain context.
import { requestSchema } from "drizzle-resource/zod";
const parseOrdersRequest = requestSchema(ordersResource);
const body = parseOrdersRequest.parse({
pagination: { mode: "offset", pageIndex: 1, pageSize: 25 },
sorting: [{ key: "createdAt", dir: "desc" }],
filters: [],
search: { value: "ORD", fields: ["reference"] },
});
await ordersResource.query({
request: body,
context: { orgId: "acme" },
});
With Valibot, call parse(requestSchema(ordersResource), body). With Vine, compile the schema once:
import vine from "@vinejs/vine";
import { requestSchema } from "drizzle-resource/vine";
const validator = vine.compile(requestSchema(ordersResource));
const body = await validator.validate(payload);
Filter values on PostgreSQL enum columns, including relation paths such as customer.status, must be values of that enum for every operator except contains. An unknown value fails validation before any SQL runs.
Narrower rules for one endpoint
The second argument can only narrow the resource's rules. allow intersects the allowed fields, and each limit becomes the lower of the resource's and the endpoint's. It cannot expose a hidden field or raise a limit.
import { requestSchema } from "drizzle-resource/zod";
const publicOrdersRequest = requestSchema(ordersResource, {
defaults: { pagination: { pageSize: 50 } },
limits: { maxPageSize: 50 },
allow: {
filters: ["status", "customer.name"],
search: ["reference"],
facets: ["status"],
},
});
The default sorting is checked when the schema is created: a default that the endpoint no longer allows throws at startup, not on the first request.
Larger limits for server jobs
Background jobs may need larger pages than an interactive endpoint. Raise the limit for one server-side call with execution, instead of widening the resource:
await ordersResource.queryIds({
request: {
...request,
pagination: { mode: "cursor", cursor: null, pageSize: 5_000 },
},
context: { orgId: "acme" },
execution: { maxPageSize: 5_000 },
});
execution isn't in the request type or any generated schema, so a client can't set it. Set it in code, never from request data. Field rules, scope and every other check still apply.
Response schemas
responseSchema starts from Drizzle's createSelectSchema for each selected table and follows the resource's load default, a named profile, or a view. A one relation is nullable, a many relation is an array, as in Drizzle's output.
import { responseSchema } from "drizzle-resource/zod";
import { z } from "zod";
const ordersResponse = responseSchema(ordersResource, {
load: "detail",
override: {
columns: {
totalAmount: (schema) => schema.transform((value) => value.toFixed(2)),
},
relations: {
customer: {
columns: {
name: (schema) => schema.transform((value) => value.trim()),
},
},
},
},
});
type OrdersResponse = z.infer<typeof ordersResponse>;
type Order = OrdersResponse["rows"][number];
override changes validation and parsed output only. It doesn't change the SQL, the selected rows or authorization.
With a view and a summary
Pass view to validate a view's exact shape, and summary: true to include the summary:
import { count, sum } from "drizzle-orm";
import { createQueryEngine } from "drizzle-resource";
import { responseSchema } from "drizzle-resource/zod";
import { db } from "./db";
import { schema } from "./schema";
import { relations } from "./relations";
const resource = createQueryEngine({ db, schema, relations }).defineResource("orders", {
views: { list: { select: { id: true, reference: true } } },
summary: (order) => ({ rows: count(), total: sum(order.totalAmount) }),
});
const listResponse = responseSchema(resource, { view: "list", summary: true });
Private and hidden fields follow the model rules. Virtuals made with virtual.scalar need a column override, because their TypeScript type isn't available at runtime; the other virtual helpers carry their runtime type.