openapi-to-zod options

Every configuration option of @spartaficial/openapi-to-zod: its type, its default and where it may be set. This page is generated from the generator's configuration schema, so it cannot drift from the code. For how the options combine, read the Zod generator guide; for where the options go, read Configuration files; for what the other generators accept, read Option parity.

Spec entry options

Each entry in specs accepts these options. The 2 required options come first, then the rest alphabetically. The "In defaults" column says whether the option may also be set once, under defaults, for every entry.

Option	Type	Default	In defaults	Description
input	string	required	no	Path to OpenAPI specification file (YAML or JSON)
outputTypes	string	required	no	Output file path for the generated schemas and types, or for the types alone when outputZodSchemas is set
batchSize	number > 0	10	yes	Batch size for parallel execution
cacheSize	number > 0	1000	yes	Cache size for pattern regex compilation
customDateTimeFormatRegex	string | RegExp	—	yes	Custom regex pattern for date-time format validation
defaultNullable	boolean	false	yes	Treat all properties as nullable by default when not explicitly specified
emptyObjectBehavior	"strict" | "loose" | "record"	"loose"	yes	Behavior for empty object schemas (objects with no properties defined)
enumFormat	"union" | "const-object"	"const-object"	yes	Format for generating enums in TypeScript types (when using outputZodSchemas)
fileHeader	string[]	—	yes	Custom comment lines to add at the very top of generated files
ignoreHeaders	string[]	—	yes	Header parameters to ignore during schema generation
includeDescriptions	boolean	true	yes	Include JSDoc comments from schema descriptions
mode	"strict" | "normal" | "loose"	"strict"	yes	Object validation mode
name	string	—	no	A label for this specification entry
operationFilters	object	—	yes	Filter which operations to include/exclude from generation (see the table below)
output	string	—	no	Deprecated. Former name of outputTypes, accepted for backward compatibility
outputZodSchemas	string	—	no	Output path for Zod schemas when using separate type/schema files
prefix	string	—	yes	Prefix to add to all generated type/schema names
refMappings	Record<string, string>	—	yes	Redirect remote $ref documents to local files, keyed by URL prefix
request	object	—	yes	Request-specific options that override the top-level options (see the table below)
response	object	—	yes	Response-specific options that override the top-level options (see the table below)
schemaType	"all" | "request" | "response"	"all"	yes	Generate the request shape, the response shape, or everything
showStats	boolean	true	yes	Show generation statistics in output file
showWarnings	boolean	true	yes	Enable or disable warning messages during generation
stripPathPrefix	string	—	yes	Strip a common prefix from all paths before generating operation-derived type names
stripSchemaPrefix	string | string[]	—	yes	Strip a common prefix from all schema names before processing
suffix	string	—	yes	Suffix to add to generated type/schema names
typeAssertionThreshold	integer >= 0	0	yes	Complexity threshold for switching to the double assertion (as unknown as) in generated schema declarations (only applies when outputZodSchemas is used)
useDescribe	boolean	false	yes	Whether to add .describe() calls for better error messages
useOperationId	boolean	true	yes	Whether to use operationId from OpenAPI spec for operation-derived naming
uuidFormat	"uuid" | "guid" | "uuidv1" | "uuidv2" | "uuidv3" | "uuidv4" | "uuidv5" | "uuidv6" | "uuidv7" | "uuidv8"	"uuid"	yes	UUID/GUID format for Zod validation

operationFilters

Options of the operationFilters object. These are the operation filters every generator shares.

Option	Type	Default	Description
excludeDeprecated	boolean	false	Exclude operations marked as deprecated
excludeMethods	string[]	—	Exclude operations with one of these HTTP methods
excludeOperationIds	string[]	—	Exclude operations whose operationId matches one of these patterns
excludePaths	string[]	—	Exclude operations whose path matches one of these patterns
excludeTags	string[]	—	Exclude operations that carry any of these tags
includeMethods	string[]	—	Include only operations with one of these HTTP methods
includeOperationIds	string[]	—	Include only operations whose operationId matches one of these patterns
includePaths	string[]	—	Include only operations whose path matches one of these patterns
includeTags	string[]	—	Include only operations that carry at least one of these tags

request and response

The request and response objects accept the same options, each applying to its own side of the exchange.

Option	Type	Default	Description
defaultNullable	boolean	the top-level defaultNullable	Accepted for symmetry with the top-level option, but not applied: the top-level defaultNullable governs both contexts
emptyObjectBehavior	"strict" | "loose" | "record"	the top-level emptyObjectBehavior	Accepted for symmetry with the top-level option, but not applied: the top-level emptyObjectBehavior governs both contexts
includeDescriptions	boolean	the top-level includeDescriptions	Whether to include descriptions as JSDoc comments
mode	"strict" | "normal" | "loose"	the top-level mode	Object validation mode
useDescribe	boolean	the top-level useDescribe	Whether to add .describe() calls for better error messages

Config file

The generator reads openapi-to-zod.config.ts, openapi-to-zod.config.json or an "openapi-to-zod" key in package.json. Whatever the format, the file has this shape:

import { defineConfig } from "@spartaficial/openapi-to-zod";

export default defineConfig({
	// Optional. Any of the 25 options marked "yes" above, applied to every entry in specs
	defaults: {},
	// Required. One entry per specification; an entry's own options override defaults
	specs: [{ input: "openapi.yaml", outputTypes: "src/schemas.ts" }],
	// Optional. How several entries are processed: "parallel" or "sequential"; default "parallel"
	executionMode: "parallel",
});

defaults takes the options marked "yes" in the "In defaults" column; paths and name are always per entry. executionMode only matters when specs has more than one entry.