Validation
KickJS validates request data through the @forinda/kickjs-schema abstraction, so any wrapped schema — Zod, Valibot, Yup, or anything implementing Standard Schema v1 — works without changing the route decorator. Validation can be declared inline on route decorators or applied manually with the validate() middleware. Failed validation returns a 422 response with structured error details.
One pipeline, three libraries
Under the hood the validate middleware calls detectSchema(schema).safeParse(payload). The same KickSchema flows into the swagger spec generator and loadEnvFromSchema() — so picking Valibot for one DTO and Yup for another in the same project Just Works, no extra config. See the schema-agnostic validation guide for the adapter surface.
Validate with your database tables
With @forinda/kickjs-db, insertSchema(users) / updateSchema(users) build the route schema from the table itself — no second declaration to keep in step. See Validation from Tables.
Scaffold one
kick g dto <name> writes a schema plus its inferred type, in the shape the route decorators below expect — in whichever of the three libraries the project depends on.
pnpm exec kick g dto create-user-m, --module <module> places it in a module's dtos/ folder. Full flag list: Generators.
Inline Validation on Route Decorators
The route decorators (@Get, @Post, @Put, @Delete, @Patch) accept a second argument with body, query, and params schemas. Pass a Zod, Valibot, or Yup schema directly — detectSchema() routes each one to the right adapter:
import { Controller, Post, Put, Get, type Ctx } from '@forinda/kickjs'
import { z } from 'zod'
const createTodoSchema = z.object({
title: z.string().min(1, { error: 'Title is required' }).max(200),
priority: z.enum(['low', 'medium', 'high']).default('medium'),
})
const updateTodoSchema = z.object({
title: z.string().min(1).max(200).optional(),
priority: z.enum(['low', 'medium', 'high']).optional(),
})
const searchQuerySchema = z.object({
q: z.string().optional(),
status: z.enum(['active', 'completed']).optional(),
})
@Controller()
export class TodoController {
@Post('/', { body: createTodoSchema })
async create(ctx: Ctx<KickRoutes.TodoController['create']>) {
// ctx.body is validated AND typed as { title: string; priority: 'low' | 'medium' | 'high' }
ctx.created(ctx.body)
}
@Put('/:id', { body: updateTodoSchema })
async update(ctx: Ctx<KickRoutes.TodoController['update']>) {
ctx.json(ctx.body)
}
@Get('/search', { query: searchQuerySchema })
async search(ctx: Ctx<KickRoutes.TodoController['search']>) {
ctx.json({ query: ctx.query })
}
}When validation is declared on a route, KickJS automatically inserts the validate() middleware before any class-level or method-level middleware. The Ctx<KickRoutes.X['method']> annotation also makes ctx.body, ctx.params, and ctx.query typed at compile time via the generated KickRoutes namespace — see Type Generation.
Validating Params
Path parameters can also be validated:
const idParamsSchema = z.object({
id: z.uuid({ error: 'Invalid ID format' }),
})
@Get('/:id', { params: idParamsSchema })
async getById(ctx: Ctx<KickRoutes.TodoController['getById']>) {
ctx.json({ id: ctx.params.id })
}Combining Body, Query, and Params
All three can be validated on the same route:
@Put('/:id', {
params: z.object({ id: z.uuid() }),
body: updateTodoSchema,
query: z.object({ notify: z.coerce.boolean().optional() }),
})
async update(ctx: Ctx<KickRoutes.TodoController['update']>) {
// ctx.params.id, ctx.body, ctx.query.notify are all validated AND typed
}The validate() Middleware
Under the hood, route validation uses the validate() function from @forinda/kickjs. You can also use it directly as Express middleware:
import { validate } from '@forinda/kickjs'
// As standalone Express middleware
app.post('/custom', validate({ body: createTodoSchema }), (req, res) => res.json(req.body))The validate() function accepts a ValidationSchema:
interface ValidationSchema {
body?: any // Zod schema (or any object with .safeParse())
query?: any
params?: any
}It works with any validation library that implements the .safeParse(data) protocol returning { success: true, data } or { success: false, error: { issues } }. Zod is the recommended choice.
Validated Data Replacement
On successful validation, the raw request data is replaced with the parsed output. This means Zod transforms, defaults, and coercions are applied:
const schema = z.object({
count: z.coerce.number().default(10),
active: z.coerce.boolean().optional(),
})
@Get('/', { query: schema })
async list(ctx: RequestContext) {
// ctx.query.count is a number (coerced from string "10")
// ctx.query.active is a boolean if provided
}Error Response Format
When validation fails, the response is a 422 in RFC 9457 problem details (application/problem+json):
{
"type": "about:blank",
"title": "Unprocessable Entity",
"status": 422,
"detail": "Title is required",
"errors": [
{ "field": "title", "message": "Title is required" },
{ "field": "priority", "message": "Invalid enum value" }
]
}- detail — the first issue's message for a body. For query errors it reads
"Invalid query parameters", and for path parameters"Invalid path parameters". - errors — one entry per issue:
fieldis the dotted path ("address.zip"for nested objects),messagethe schema's message. Kept in production — a form needs them to say which field is wrong — with every other member dropped; other errors' details stay out of production responses.
Custom Validation Errors
To control what a failed validation throws — a different status, your own message format, extra fields — pass validationError to bootstrap() (or createWebApp()). It receives the failure and returns the error:
import { bootstrap, ProblemException } from '@forinda/kickjs'
bootstrap({
modules,
validationError: ({ source, issues }) =>
new ProblemException({
status: 400,
title: `Invalid ${source}`,
fields: Object.fromEntries(issues.map((i) => [i.path.join('.'), i.message])),
}),
})sourceis'body','query'or'params';issuesis the schema's list ({ path, message, code }) whatever library produced it;reqis the request.- Return
undefinedto use the default response for that failure — for example, to customise only body errors. - Returning or throwing a
ProblemExceptionorHttpExceptionkeeps the problem-details response. Anything else goes to youronErrorlike any other error. defaultValidationError(failure)builds the default, so a factory can start from it and adjust.- It applies to that app's routes. A standalone
validate()takes the same function:validate(schema, { validationError }). - With Inertia, keep the default shape for form routes: the page's
errorsare read from its[{ field, message }]details.
Defining Reusable DTOs
Define schemas in dedicated DTO files and extract the TypeScript type with the library's native infer helper. The three adapters round-trip identically through the validate middleware — pick whichever you prefer:
// application/dtos/create-todo.dto.ts — Zod (recommended default)
import { z } from 'zod'
export const createTodoSchema = z.object({
title: z.string().min(1, { error: 'Title is required' }).max(200),
priority: z.enum(['low', 'medium', 'high']).default('medium'),
})
export type CreateTodoDTO = z.infer<typeof createTodoSchema>// application/dtos/create-todo-valibot.dto.ts — Valibot
import * as v from 'valibot'
export const createTodoSchema = v.object({
title: v.pipe(v.string(), v.minLength(1, 'Title is required'), v.maxLength(200)),
priority: v.optional(v.picklist(['low', 'medium', 'high']), 'medium'),
})
export type CreateTodoDTO = v.InferOutput<typeof createTodoSchema>// application/dtos/create-todo-yup.dto.ts — Yup
import * as yup from 'yup'
export const createTodoSchema = yup
.object({
title: yup.string().required('Title is required').max(200),
priority: yup.string().oneOf(['low', 'medium', 'high']).default('medium'),
})
.required()
export type CreateTodoDTO = yup.InferType<typeof createTodoSchema>Pass any of those schemas to the route decorator and use the matching type in your use case — detectSchema() figures out the right adapter at startup, no fromZod / fromValibot / fromYup wrap is required on the route side:
@Post('/', { body: createTodoSchema })
async create(ctx: RequestContext) {
const dto: CreateTodoDTO = ctx.body
await this.createTodoUseCase.execute(dto)
}Adapter caveats
- Zod — broadest ecosystem, default for
kick new. - Valibot — smaller bundle; transforms validate the default through the pipe, so
v.optional(v.pipe(v.string(), v.transform(Number)), '3000')lands at3000: number(not the raw'3000'string). - Yup — classic API;
.url()only matches http/https (use.string().required()forpostgres://-style connection strings), and__outputTypetypes required strings asstring | undefinedbecause.required()is enforced at runtime, not in the type. The validate middleware still rejects undefined at runtime.
See Schema-agnostic validation for the adapter detection order and how to register a custom one.
OpenAPI Integration
When the @forinda/kickjs-swagger adapter is active, schemas passed to route decorators are used to generate OpenAPI request body and parameter documentation automatically — Zod, Valibot, and Yup all flow through the same detectSchema().toJsonSchema() pipeline, so no additional annotations are needed. Each adapter implements toJsonSchema(); Zod uses the built-in toJSONSchema(), Valibot delegates to @valibot/to-json-schema, and Yup walks describe() output. See @forinda/kickjs-swagger for the spec-generation surface.