Validation

A route validates a part of the request by declaring a schema for it. The handler then gets that part typed from the schema’s output.

Declaring schemas

Any Standard Schema works. Zod, Valibot and ArkType support it directly, and TypeBox does through tb() from @tetsujs/typebox.

import { controller, route } from "@tetsujs/core";
import { z } from "zod";

const NoteId = z.object({ id: z.coerce.number().int().positive() });
const NoteChange = z.object({ title: z.string().min(1).optional(), body: z.string().optional() });

export const notesController = controller("Notes", () => ({
  change: route({
    method: "PATCH",
    path: "/notes/:id",
    schema: { params: NoteId, body: NoteChange },
    handler: (ctx) => ({ id: ctx.params.id, ...ctx.body }),
params: {
    id: number;
}
  }),
}));

A value the schema converts arrives converted: ctx.params.id is a number here.

The parts

Part	Validates	Adds
params	path parameters, as strings	ctx.params, narrowed
query	the query string: a record of strings, a repeated key as an array	ctx.query
headers	the request headers, names in lower case	ctx.headers
cookies	the request’s cookies, signed ones already verified	ctx.cookies
body	the parsed body — see Request bodies	ctx.body
response	what the handler returns	nothing; it checks what leaves

A part without a schema is neither read nor typed. Without a query schema the query string is not parsed and ctx.query does not exist. Without a body schema, bodyType or rawBody, the body is never read. Context explains why.

If a beforeValidation hook changes ctx.body or ctx.query, the schema validates the hook’s value.

Validation errors

All parts are checked, in the order params, query, headers, cookies, body, and their issues are collected. The client sees everything wrong with a request in one answer. A failure answers 422 before the handler runs:

{
  "status": 422,
  "message": "Validation failed",
  "error": "VALIDATION_FAILED",
  "issues": [
    { "message": "Invalid option: expected one of \"yes\"|\"no\"", "path": ["query", "draft"] },
    { "message": "Too small: expected string to have >=1 characters", "path": ["body", "title"] }
  ]
}

Each issue’s path starts with the part, then the keys inside it. The messages come from the validator and change with its version, so branch on error and path, and show message to people.

To answer 400 instead, set validation: { status: 400 } on createApp. A body that is not valid JSON is always a 400. To change the format of the answer, use an application onError hook; see Errors.

Converting strings

Path parameters, query values, headers, cookies and form fields all arrive as strings. The framework does not guess types; the schema converts them. With Zod, use z.coerce:

const Page = z.object({
  page: z.coerce.number().int().min(1).default(1),
  size: z.coerce.number().int().min(1).max(100).default(20),
});

Arrays need the same care. A key sent once is a string, and only a repeated key becomes an array: ?tag=a is "a", and ?tag=a&tag=b is ["a", "b"]. A plain z.array() refuses a single tag, so wrap a single value in an array first:

const one = (value: unknown) => (typeof value === "string" ? [value] : value);

const Filter = z.object({
  tag: z.preprocess(one, z.array(z.string())).optional(),
});

Form fields work the same way. With TypeBox, tb(…, { convert: true }) does both conversions: "42" to 42, and "a" to ["a"].

Validator libraries

Only the schema changes between libraries; the route and the handler’s types follow it:

import { route } from "@tetsujs/core";
import { type } from "arktype";
import * as v from "valibot";
import { z } from "zod";
import { Type, tb } from "@tetsujs/typebox";

const WithZod = z.object({ title: z.string().min(1), pinned: z.boolean() });

const WithValibot = v.object({
  title: v.pipe(v.string(), v.minLength(1)),
  pinned: v.boolean(),
});

const WithArkType = type({ title: "string > 0", pinned: "boolean" });

const WithTypeBox = tb(Type.Object({ title: Type.String({ minLength: 1 }), pinned: Type.Boolean() }));

route({
  method: "POST",
  path: "/notes",
  schema: { body: WithTypeBox },
  handler: (ctx) => ctx.body,
body: {
    title: string;
    pinned: boolean;
}
});

tb() options such as convert, clean and defaults are on the package page. For a schema to appear in the OpenAPI document it must also produce JSON Schema. Zod, ArkType and tb() do this themselves; Valibot needs toStandardJsonSchema from @valibot/to-json-schema. See @tetsujs/openapi.

Asynchronous validators work too.

Checking the response

schema.response checks what the handler returns, at compile time and at runtime, and the schema’s output is what gets sent: a schema that strips unknown keys keeps a field like passwordHash out of the response. A response that fails its schema is a 500, reported to reportError. Responses covers a schema per status, what is serialized, and turning the runtime check off with validateResponses: false.