Zod
Officialv5.10.0@kubb/plugin-zod
Options
Pass these options to pluginZod(). Shared options link to Shared plugin options.
Options overview
| Option | Purpose | Default |
|---|---|---|
output | Where files are written. | { path: 'zod', barrel: { type: 'named' } } |
group | Split output by tag or path. | None |
importPath | Module the generated files import z from. | 'zod', or 'zod/mini' with mini |
inferred | Export a type next to each schema. | false |
coercion | Coerce input before validation. | false |
guidType | Validator for format: uuid. | 'uuid' |
regexType | How an OpenAPI pattern is written. | 'literal' |
oneOfType | How a oneOf is validated. | 'union' |
compile | Wrap schemas in z.compile for fast-path validation. | false |
mini | Generate Zod Mini schemas. | false |
typeGuards | Generate is* type guards and assert* assertions. | false |
printer | Replace the handler for a schema type. | None |
include | Keep only operations and schemas that match. | None |
exclude | Skip operations and schemas that match. | [] |
override | Apply different options per pattern. | [] |
resolver | Customize generated names and file paths. See resolver members. | resolverZod |
macros | Rewrite AST nodes before printing. | [] |
Option details
importPath
Module the generated files import z from, such as your own module that re-exports Zod.
| Type | 'zod' | 'zod/mini' | string |
| Required | false |
| Default | mini ? 'zod/mini' : 'zod' |
'zod' and 'zod/mini' are imported as import * as z. Any other module is imported as import { z }, so export z by name.
inferred
Exports a type next to each schema, so you do not need @kubb/plugin-ts.
| Type | boolean | 'codec' | 'direction' |
| Required | false |
| Default | false |
z.infer<typeof schema> for every schema.z.input for request schemas and z.output for response schemas, for codecs. See Type codecs on each side.'codec'.export type PetSchemaType = z.infer<typeof petSchema>export type PutEventBodySchemaType = z.input<typeof putEventBodySchema>'codec', set validator: { request: 'zod', params: 'zod' } in @kubb/plugin-fetch or @kubb/plugin-axios, or the client sends the domain value unencoded.coercion
Wraps schemas in z.coerce to convert input, such as form data and query params, before validation.
| Type | boolean | { dates?: boolean, strings?: boolean, numbers?: boolean } |
| Required | false |
| Default | false |
format: int64 fields, which use z.coerce.bigint().pipe(z.int64()) with the adapter's default integerType: 'bigint'.Coerced fields lose some format checks, such as jwt. See Coerce input with Zod.
guidType
Validator for format: uuid.
| Type | 'uuid' | 'guid' |
| Required | false |
| Default | 'uuid' |
z.uuid(), for a standard RFC 4122 UUID.z.guid(), which also accepts Microsoft-style GUIDs.regexType
How an OpenAPI pattern is written inside .regex(...). Use 'constructor' when a regex literal breaks your build or you need a string pattern.
| Type | 'literal' | 'constructor' |
| Required | false |
| Default | 'literal' |
.regex(/^[a-z]+$/)..regex(new RegExp("^[a-z]+$")).oneOfType
How a oneOf without a discriminator is validated. Use 'xor' when values may carry extra keys.
| Type | 'union' | 'xor' |
| Required | false |
| Default | 'union' |
z.union([...]) with strict object members, so extra keys fail, even keys the spec allows.z.xor([...]), which passes only when exactly one member matches. Needs Zod 4.2 or later.compile
Wraps schemas in z.compile(...), which generates validation code instead of interpreting the schema on each call. Needs Zod 4.5 or later.
| Type | boolean | { strict?: boolean } |
| Required | false |
| Default | false |
Circular schemas and coerced fields, int64 included, stay on the interpreter. See Compile Zod schemas.
mini
Generates Zod Mini schemas, which use functions instead of method chains so bundlers can drop unused validators. It sets the importPath default to 'zod/mini'. In beta.
| Type | boolean |
| Required | false |
| Default | false |
status: z.string().optional(),status: z.optional(z.string()),typeGuards
Generates is* type guards and assert* assertions with Zod's validate API. Needs Zod 4.6 or later.
| Type | boolean | { is?: boolean, assert?: boolean } |
| Required | false |
| Default | false |
is<Schema> and assert<Schema>.true, so { assert: false } writes only the is* guards.export const isPet = (data: unknown): data is z.infer<typeof petSchema> => petSchema.validate(data)
export function assertPet(data: unknown): asserts data is z.infer<typeof petSchema> {
if (!petSchema.validate(data)) {
petSchema.parse(data)
}
}printer
Replaces the handler for a schema type such as 'integer'. Each handler returns the Zod expression as a string, in Zod Mini syntax when mini is true. this.base(node) returns the built-in output, and this.transform(node) recurses into nested nodes. See the printer guide.
| Type | { nodes?: PrinterZodNodes | PrinterZodMiniNodes } |
| Required | false |
import { pluginZod } from '@kubb/plugin-zod'
pluginZod({
printer: {
nodes: {
integer() {
return 'z.number()'
},
},
},
})To convert requests and responses differently, branch on this.options.direction, as in Encode custom types.
Resolver members
Besides the shared members of resolver, resolverZod has these. Members you leave out keep the default.
type ResolverZodPatch = {
schema?: {
typeName?(name: string): string
type?(name: string): string
inputName?(name: string): string
inputTypeName?(name: string): string
isName?(name: string): string
assertName?(name: string): string
}
param?: {
name?(node: OperationNode, param: ParameterNode): string
path?(node: OperationNode, param: ParameterNode): string
query?(node: OperationNode, param: ParameterNode): string
headers?(node: OperationNode, param: ParameterNode): string
cookies?(node: OperationNode, param: ParameterNode): string
}
response?: {
status?(node: OperationNode, statusCode: StatusCode): string
headers?(node: OperationNode, statusCode: StatusCode): string
body?(node: OperationNode): string
responses?(node: OperationNode): string
response?(node: OperationNode): string
error?(node: OperationNode): string
options?(node: OperationNode): string
}
}Format and type mappings
Kubb maps each OpenAPI format to its Zod v4 call, such as format: email to z.email(). See Zod validators for OpenAPI formats.
