Framework Integration Points
Every part of KickJS that reads a schema goes through @forinda/kickjs-schema:
- request validation
- the Swagger spec
- MCP and AI tools
- AI structured output
- env loading
kick typegen
At runtime, each of these calls detectSchema(schema) and works with the KickSchema it returns — that's why one Zod, Valibot, Yup or Standard Schema object works everywhere without extra config. kick typegen is the exception: it reads your source without running it, finds the schemas your routes and env reference, and types them through InferSchemaOutput (see Type Generation). This page describes what each integration does with the schema.
Request Validation
Route decorators take body, query and params schemas. When a route declares any of them, KickJS adds the validate() middleware to that route on every runtime (Express, Fastify, h3 and the web/fetch entry):
import { Controller, Post, type Ctx } from '@forinda/kickjs'
import { z } from 'zod'
const createUserSchema = z.object({
email: z.email(),
name: z.string().min(1),
})
@Controller()
export class UserController {
@Post('/', { body: createUserSchema })
create(ctx: Ctx<KickRoutes.UserController['create']>) {
ctx.created(ctx.body)
}
}For each declared target, in the order body → query → params, validate():
- wraps the schema with
detectSchema()and calls.safeParse()on the raw input - on failure, stops and passes a 422
HttpExceptionto the error handler. The later targets are not checked - on success, replaces
req.body/req.query/req.paramswith the parsed output, so defaults, coercions and transforms apply
The error message depends on the target:
| Target | Message |
|---|---|
body | the first issue's message (falls back to Validation failed) |
query | Invalid query parameters |
params | Invalid path parameters |
Each issue becomes { field, message }, where field is the issue path joined with dots. The response is a Problem Details body:
{
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank",
"detail": "Invalid email address",
"errors": [{ "field": "email", "message": "Invalid email address" }]
}With NODE_ENV=production, errors is left out of the response, because the details can reveal the shape of the request; detail and the rest stay.
To change this shape, handle the error yourself with bootstrap({ onError }). A validation failure arrives there as an HttpException with status 422 and the { field, message }[] list in details:
import { bootstrap, HttpException } from '@forinda/kickjs'
import { modules } from './modules'
bootstrap({
modules,
onError: (err, _req, res) => {
if (err instanceof HttpException && err.status === 422) {
res.status(422).json({ message: err.message, issues: err.details })
return
}
res.status(err.status ?? 500).json({ message: err.message })
},
})See Validation and Error Handling for the full guides.
Swagger / OpenAPI
@forinda/kickjs-swagger converts schemas with its default parser. That parser calls:
detectSchema(schema).toJsonSchema({ target: 'openapi-3.0', io })io is 'input' for body, query and params, and 'output' for declared response schemas. The two differ for fields with defaults, coercions and transforms. A field with a default is optional on input but always present on output.
The spec is built the first time the spec endpoint (/openapi.json by default) is requested, and then cached.
Component names
Request bodies and responses go into components.schemas and are referenced by $ref. Each one gets the first free name from this list:
- Explicit: the route's
nameoption, with aBodysuffix.@Post('/', { body: schema, name: 'CreateUser' })registersCreateUserBody. - Title: the converted JSON Schema's
title. For Zod, that's.meta({ title: '…' }). - Fallback:
<Controller><Handler>Body, with the handler's first letter capitalised. For example,UserController.creategivesUserControllerCreateBody.
Names are stripped of anything that isn't a letter or a digit.
A name that's free, or that already holds the same schema, is reused, so a schema shared by several routes appears once. If an explicit name or a title already holds a different schema, the builder logs a warning and uses the fallback. Two fallbacks can only clash when two controllers with the same class name have the same handler, and those get numbered (_2, _3, …).
A body schema on GET, HEAD, DELETE or OPTIONS is left out of the spec, because OpenAPI 3 allows no request body there. KickJS warns once per route. Validate those inputs with query instead.
Custom parsers (deprecated)
SwaggerAdapter({ schemaParser }) still accepts a SchemaParser (name, supports(schema), toJsonSchema(schema, { io })) for libraries detectSchema can't read. It's deprecated: register an adapter with registerAdapter() instead (see Schema Adapters), so validation and tools pick the library up too. registerAdapter() works at runtime only: typegen infers a route's types from the schema's static type, so a raw schema from a custom library stays untyped unless the value you pass to the route carries a type InferSchemaOutput recognises — for example const body = detectSchema(rawSchema) as KickSchema<CreateUser>.
See Swagger for the adapter itself.
MCP and AI Tools
@forinda/kickjs-mcp and @forinda/kickjs-ai both turn routes into tools with buildRouteTool() from @forinda/kickjs-schema, so a route is exposed the same way to both. The tool's input schema is one JSON Schema object (converted with io: 'input') that merges:
- path parameters: always required. Each one is typed from the route's
paramsschema, or as a string if there is none - body fields: from
bodyon POST, PUT and PATCH. A body that isn't an object (an array, say) becomes a singlebodyproperty - query fields: from
query
An inputSchema option on @McpTool / @AiTool replaces the query or body part (body on POST/PUT/PATCH, query otherwise). Path parameters are still added. When the tool is called, toRequest() splits the arguments back into a URL and a JSON body. The request then goes through the normal HTTP pipeline, so the route's own validation checks the arguments.
Which routes become tools:
- MCP: methods decorated with
@McpToolby default, or every route withmode: 'auto'. You can also expose routes through route flags withexposeWhen. AnoutputSchemais converted withio: 'output'. - AI: methods decorated with
@AiTool, or routes matched byexposeWhen. Tool names default to<Controller>_<handler>.
In both adapters, hideWhen wins over every other rule.
AI structured output
provider.chat({ messages, schema }) and chatObject() take any schema detectSchema reads. The schema is sent to the model as toJsonSchema({ io: 'output' }), and the answer is checked with safeParse() before it lands in response.object. See AI → Structured output.
See MCP and AI for the adapters.
Environment Validation
There are two loaders:
loadEnvFromSchema(schema)takes any schemadetectSchemareads. It parsesprocess.envwithsafeParse()and throws a plainErrorthat lists every failing key. Thekick newtemplates for Zod, Valibot and Yup all use it.defineEnv()+loadEnv()are Zod-only.defineEnvmerges your keys over the base schema (PORT,NODE_ENV,LOG_LEVEL).
// src/config/index.ts
import { loadEnvFromSchema } from '@forinda/kickjs/config'
import { fromValibot } from '@forinda/kickjs-schema/valibot'
import * as v from 'valibot'
const envSchema = fromValibot(
v.object({
PORT: v.optional(v.pipe(v.string(), v.transform(Number)), '3000'),
DATABASE_URL: v.pipe(v.string(), v.url()),
}),
)
loadEnvFromSchema(envSchema) // side effect: registers the schema; read values with getEnv('KEY')
export default envSchemaThe loader registers the schema with the env cache that ConfigService and @Value() read. That only happens if the file runs before bootstrap(), so src/index.ts must import it first:
// src/index.ts
import './config'
import { bootstrap } from '@forinda/kickjs'kick typegen reads the default export to generate the KickEnv type. See Configuration.
Type Generation
kick typegen (also run by kick dev) scans your controllers without executing them and types each route for Ctx<KickRoutes.UserController['create']>:
body,query,params: from the schemas in the route decorator. Without a schema,paramsfalls back to the URL pattern,queryto the@ApiQueryParamsshape orunknown, andbodytounknown.response: from a declaredresponseschema, or else from the handler's return type.
A schema is only resolved if typegen can find it statically: it must be a named identifier that is exported from the controller file or imported with a static specifier. Otherwise typegen warns and uses the fallback.
Which schemas are understood depends on typegen.schemaValidator in kick.config.ts:
| Value | Types from |
|---|---|
'kickjs-schema' | InferSchemaOutput<typeof schema> — every supported library |
'zod' | z.infer<typeof schema> — Zod only |
false | no schema-driven types |
kick new and kick g config both write 'kickjs-schema'. If the option is missing, it defaults to 'zod', so projects that use Valibot or Yup must set it.
InferSchemaOutput<T> checks, in order:
- a
KickSchema<O>— its declared outputO - a Standard Schema's output type — Zod 4, Valibot, Yup, ArkType and others
- Zod 3's and Yup's own output types
- otherwise
unknown
Typed handlers
A plain ctx: RequestContext doesn't type ctx.body. To get the validated types, annotate the handler with the generated entry:
import { Controller, Post, type Ctx } from '@forinda/kickjs'
import { createUserSchema } from './user.dtos'
@Controller()
export class UserController {
@Post('/', { body: createUserSchema })
create(ctx: Ctx<KickRoutes.UserController['create']>) {
ctx.body.email // string, inferred from createUserSchema
ctx.created(ctx.body)
}
}See Type Generation.
Library Notes
- Standard Schema: any object, or callable (ArkType, for example), with a
~standardproperty is detected. If the library also implements Standard JSON Schema, itsjsonSchema.input()/output()is called with the caller'starget(defaultdraft-2020-12,openapi-3.0from Swagger).io: 'input'selectsinput()and anything elseoutput(). See Standard Schema. - Valibot: JSON Schema conversion uses the optional peer
@valibot/to-json-schema, whichkick newinstalls with the Valibot template. Without it, Valibot schemas are described as{ type: 'object' }, so Swagger and AI tools show no fields, and a one-time console warning says so. Validation still works.