openapi-to-zod

name

openapi-to-zod

description

Generate Zod v4 TypeScript schemas from OpenAPI (openapi.yaml / openapi.json) definitions. This skill exists because npm packages like openapi-zod-client do not support Zod v4 — Claude reads the YAML/JSON directly and writes the conversion. Use this skill whenever the user wants to convert OpenAPI/Swagger definitions to Zod schemas, generate TypeScript types from API specs, or create validation schemas from openapi.yaml. Trigger on keywords: 'openapi', 'swagger', 'zod', 'API schema', 'yaml to types', 'schema generation', 'validation generation'. OpenAPI定義からZodスキーマを生成するスキル。openapi.yamlから型を作りたい、APIスキーマをTypeScriptの型にしたい、Zodバリデーションを作りたい、といったリクエストで使う。「openapi」「swagger」「zod」「APIスキーマ」「yamlから型」「スキーマ生成」「バリデーション生成」などのキーワードが出たら積極的にこのスキルを使うこと。

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による参照を解決する

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

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

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

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