Openapi To Zod

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 / 入力の確認

1. Ask the user for the OpenAPI definition file path / OpenAPI定義ファイルのパスを確認する
2. Read the file and check the OpenAPI version (2.0 / 3.0 / 3.1) / ファイルを読み取り、OpenAPIバージョンを確認する
3. 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:

1. Component Schemas (components/schemas/*)

• Order all schema definitions by dependency / 全スキーマ定義を依存関係順に並べる
• Resolve $ref references / $refによる参照を解決する

1. 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

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パターンやエッジケースに遭遇した場合:

1. Read references/conversion-rules.md
2. If the pattern is not listed, determine the appropriate conversion rule based on the OpenAPI spec and Zod v4 documentation
3. Execute the conversion, then append the new rule to references/conversion-rules.md
4. 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 / チェック方法

1. Fetch the following pages and compare against references/zod-v4-api-snapshot.md:

• https://zod.dev/basics
• https://zod.dev/api
• https://zod.dev/error-customization
• https://zod.dev/error-formatting
• https://zod.dev/json-schema
• https://zod.dev/codecs

1. 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

1. 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ysknsid25
• Source: ysknsid25/Skills
• License: MIT

Install and usage instructions live in the source repository linked above.