@seiya8bit/otz

otz is a command-line tool that generates Zod schemas from your OpenAPI definitions. Maps OpenAPI types and formats to Zod schemas, and generates validation messages useful for UI forms.

Zod Version Compatibility

| otz version | Zod version | | ----------- | ----------- | | 3.x | Zod v4 | | 2.x | Zod v3 |

If you are using Zod v3, install the v2 release:

npm install -D @seiya8bit/otz@2

Requirements

• Node.js >= 22

Install

npm install -D @seiya8bit/otz

Quick start

otz -i path/to/openapi.yaml -o path/to/output.ts -c -p -q -n optional

Features

• Type & Format Conversion: Translates OpenAPI type (e.g., integer) and format (e.g., email) properties into the appropriate Zod schema types.
• Validation Rule Mapping: Converts OpenAPI validation keywords like minimum, exclusiveMinimum, etc., into Zod validation checks (e.g., .min(), .max()).
• Customizable Null Handling: Choose how nullable: true properties are handled – map them to either .nullish() or .optional() in the generated Zod schemas.
• Validation Message Generation: Option to automatically include validation messages within the generated Zod schemas, perfect for displaying feedback in forms.
• Split Definition Support: Seamlessly handles OpenAPI definitions that are split across multiple files using $ref.

Zod v4 Schema Support (Generated Output)

• Base types: string, number, bigint, boolean, date, symbol, undefined, null, void, any, unknown, never
• Objects/arrays: object -> z.object({ ... }), array -> z.array(...)
• Enums: string enums -> z.enum([...]); non-string enums -> z.union([z.literal(...), ...])
• Unions: anyOf / oneOf -> z.union([...])
• Composition: allOf (object only) -> .merge(...)
• Nullability: nullable: true -> .nullish() or .optional() (configurable)
• Defaults: default -> .default(...) (bigint defaults for int64/uint64)
• Constraints: minItems/maxItems, minLength/maxLength, minimum/maximum (+ exclusive*) -> .min/.max/.gt/.gte/.lt/.lte
• Regex: pattern -> .regex(new RegExp(pattern))
• OpenAPI string formats:
  • email, uuid, uuidv4, uuidv6, uuidv7
  • uri/url -> z.url()
  • hostname, ipv4, ipv6, cidrv4, cidrv6
  • byte -> z.base64(), base64url, nanoid, cuid, cuid2, ulid, guid, emoji
  • date, time, date-time, duration -> z.iso.date/time/datetime/duration
• OpenAPI number formats:
  • integer -> z.int()
  • int32, int64, uint32, uint64, float/float32, double/float64
• additionalProperties: true -> z.record(z.unknown()), false -> .strict(), schema -> .catchall(schema) or z.record(schema)

Usage

Run the otz command, specifying the input OpenAPI file, the desired output path, and any relevant options.

Command-Line Options

The following options are available for the otz command:

| Options | Description | Required | Default | | --------------------- | ------------------------------------------------------------------- | -------- | -------- | | -i, --input | Path to the root OpenAPI definition file (YAML or JSON). | ✅ | N/A | | -o, --output | Output file path for the generated Zod schema. | ✅ | N/A | | -c, --components | Generate schemas for definitions in components/schemas. | | false | | -p, --paths | Generate schemas for request bodies and responses defined in paths. | | false | | -q, --queries | Generate schemas for query parameters defined in paths. | | false | | -n, --nullable-mode | Set null handling mode: nullish or optional. | | optional |

Split OpenAPI Definitions

For OpenAPI definitions split across multiple files, specify the root file in the --input option.

Guides

• For OpenAPI users: See the OpenAPI Usage Guide for details on converting existing OpenAPI files.
• For TypeSpec users: See the TypeSpec Usage Guide for integrating otz into your TypeSpec workflow.

Examples

• Petstore(basic)
• with Hono(advanced)

Contributing

Contributions are welcome!

If you find a bug or have a feature request, feel free to open an issue or submit a pull request.

License

This project is licensed under the MIT License.