OpenAPI to Zod v4 Schema Generator
Generate Zod v4 schema code in TypeScript by reading OpenAPI definition files (YAML/JSON).
OpenAPI定義ファイル（YAML/JSON）を読み取り、Zod v4のスキーマコードをTypeScriptで生成する。
Why this skill exists
Existing npm packages (openapi-zod-client, etc.) do not support Zod v4. This skill has Claude read OpenAPI definitions directly and generate code conforming to the Zod v4 API.
既存のnpmパッケージ（openapi-zod-clientなど）はZod v4に対応していない。このスキルではClaudeがOpenAPI定義を直接読み取り、Zod v4のAPIに準拠したコードを生成する。
Workflow
Step 1: Confirm inputs / 入力の確認
- Ask the user for the OpenAPI definition file path / OpenAPI定義ファイルのパスを確認する
- Read the file and check the OpenAPI version (2.0 / 3.0 / 3.1) / ファイルを読み取り、OpenAPIバージョンを確認する
- Ask for the output file path — if not specified, always ask the user / 出力先ファイルパスを確認する（指定がなければ必ずユーザーに聞き返す）
Step 2: Parse the schema / スキーマの解析
Extract the following from the OpenAPI definition:
-
Component Schemas (components/schemas/*)
- Order all schema definitions by dependency / 全スキーマ定義を依存関係順に並べる
- Resolve
$ref references / $refによる参照を解決する
-
Path Operations (paths/*)
- Request bodies (
requestBody) for each endpoint
- Responses (
responses) for each endpoint
- Path parameters and query parameters
Step 3: Generate Zod v4 code / Zod v4コードの生成
Refer to references/conversion-rules.md for the mapping between OpenAPI types and the Zod v4 API.
生成するコードは以下の構造にする:
import { z } from "zod/v4";
// ============================================
// Component Schemas
// ============================================
// ... schema definitions in dependency order
// ============================================
// Request / Response Schemas
// ============================================
// ... request/response types per path
// ============================================
// Inferred Types
// ============================================
// ... type exports via z.infer<typeof ...>
Step 4: Output / 出力
- Write the generated code to the specified file path (default:
schema.ts)
- Verify dependency order is correct (referenced schemas are defined before their references)
Naming Conventions
| OpenAPI | Zod schema variable | Inferred type |
|---|
components/schemas/User | userSchema | User |
components/schemas/UserResponse | userResponseSchema | UserResponse |
POST /users request body | postUsersRequestSchema | PostUsersRequest |
POST /users 200 response | postUsersResponseSchema | PostUsersResponse |
GET /users/{id} query params | getUsersByIdQuerySchema | GetUsersByIdQuery |
- Schema variable: convert PascalCase schema name to camelCase, append
Schema
- Inferred type: keep PascalCase as-is
- Path-derived names: HTTP method + path converted to camelCase
Self-Extension Protocol / 自己拡張プロトコル
When encountering an OpenAPI pattern or edge case not covered by this skill:
カバーされていないOpenAPIパターンやエッジケースに遭遇した場合:
- Read
references/conversion-rules.md
- If the pattern is not listed, determine the appropriate conversion rule based on the OpenAPI spec and Zod v4 documentation
- Execute the conversion, then append the new rule to
references/conversion-rules.md
- Report the addition to the user
This way the skill's conversion rules grow richer with each use.
使えば使うほどスキルの変換ルールが充実していく。
Zod v4 API Update Check / Zod v4 API更新チェック
This skill bundles an API snapshot at references/zod-v4-api-snapshot.md taken from the official Zod docs. To keep the skill's output accurate as Zod evolves, run this check periodically.
このスキルは references/zod-v4-api-snapshot.md にZod公式ドキュメントのAPIスナップショットを持っている。Zodの進化に追従するため、定期的に以下のチェックを実行する。
When to check / いつチェックするか
- When the user explicitly asks to update or verify the skill / ユーザーが明示的に更新・検証を依頼した場合
- When generated code causes type errors that suggest an API change / 生成コードがAPI変更を示唆する型エラーを起こした場合
How to check / チェック方法
-
Fetch the following pages and compare against references/zod-v4-api-snapshot.md:
-
Look for:
- New APIs not in the snapshot (new schema types, methods, options)
- Changed APIs (renamed methods, changed signatures, deprecated features)
- Removed APIs no longer in the docs
-
If differences are found:
- Update
references/zod-v4-api-snapshot.md with the new state and today's date
- Update
references/conversion-rules.md if any changes affect OpenAPI → Zod mappings
- Report the changes to the user
Important Notes
- Zod v4 import: use
import { z } from "zod/v4" (not "zod")
z.lazy() is only needed for mutually recursive types (Zod v4 does not require it for normal forward references)- Keep generated code comments minimal — only section dividers and non-obvious conversions