zod

Zod

重要： zod に関する学習データは古くなっていたり、誤っていたりする可能性があります。Zod v4 では、文字列フォーマット、列挙型、エラー処理、再帰型に破壊的変更が導入されています。常に、このスキルのルールファイルとプロジェクトの実際のソースコードを正しい情報源として参照してください。取得したリファレンスと矛盾する場合、記憶した v3 のパターンに頼らないでください。

Zod を使用する場面

Zod は 実行時の型検証 に使用します。API 入力、フォームデータ、環境変数、外部サービスなど、システム境界で信頼できないデータを解析します。コンパイル時のみ必要な型には、通常の TypeScript で十分です。

必要なもの	推奨ツール
API 入出力の検証	Zod
フォームの検証（React、Vue）	Zod（react-hook-form、formik などと併用）
環境変数の解析	Zod（t3-env または手動）
コンパイル時の型のみ	通常の TypeScript
より小さなバンドル（約 1kb）	Valibot
最大限の型推論	ArkType

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	接頭辞
1	解析と型安全性	CRITICAL	parse-
2	スキーマ設計	CRITICAL	schema-
3	リファインメントと変換	HIGH	refine-
4	エラー処理	HIGH	error-
5	パフォーマンスと構成	MEDIUM	perf-
6	v4 への移行	MEDIUM	migrate-
7	高度なパターン	MEDIUM	pattern-
8	アーキテクチャと境界	CRITICAL/HIGH	arch-
9	可観測性	HIGH/MEDIUM	observe-

クイックリファレンス

1. 解析と型安全性（CRITICAL）

• parse-use-safeParse — ユーザー入力には、例外をスローする parse() ではなく safeParse() を使用します
• parse-async-required — スキーマに非同期リファインメントがある場合は、parseAsync()／safeParseAsync() を使用する必要があります
• parse-infer-types — 出力型には z.infer<typeof Schema> を使用し、型を手動で重複定義しないでください

2. スキーマ設計（CRITICAL）

• schema-object-unknowns — z.object() は不明なキーを除去します。strictObject または looseObject を使用してください
• schema-union-discriminated — タグ付きユニオンには z.union() ではなく z.discriminatedUnion() を使用してください
• schema-coercion-pitfalls — z.coerce.boolean() は "false" を true に変換します。z.stringbool() を使用してください
• schema-recursive-types — 再帰スキーマにはゲッターパターンを使用してください。z.lazy() は v4 で削除されています

3. リファインメントと変換（HIGH）

• refine-never-throw — .refine() または .transform() 内で例外をスローしないでください。ctx.addIssue() を使用してください
• refine-vs-transform — 検証には .refine()、変換には .transform()、段階的な処理には .pipe() を使用してください
• refine-cross-field — フィールド間の検証には、path を指定して親オブジェクトで .superRefine() を使用してください

4. エラー処理（HIGH）

• error-custom-messages — v4 の error パラメーターを使用してください。required_error／invalid_type_error は削除されています
• error-formatting — フォームには z.flattenError()、ネストされたエラーには z.treeifyError() を使用してください。formatError は非推奨です
• error-input-security — 本番環境では reportInput: true を使用しないでください。機密データが漏えいします

5. パフォーマンスと構成（MEDIUM）

• perf-extend-spread — 大規模なスキーマでは、.extend() のチェーンより { ...Schema.shape } によるスプレッドを使用してください
• perf-reuse-schemas — スキーマを一度定義し、.pick()、.omit()、.partial() で派生させてください
• perf-zod-mini — バンドルサイズが重要なクライアントアプリでは、zod/v4/mini（1.88kb）を使用してください

6. v4 への移行（MEDIUM）

• migrate-string-formats — z.string().email() ではなく、z.email()、z.uuid()、z.url() を使用してください
• migrate-native-enum — TS の列挙型には統一された z.enum() を使用してください。z.nativeEnum() は非推奨です
• migrate-error-api — すべての箇所で error パラメーターを使用してください。message と errorMap は削除されています

7. 高度なパターン（MEDIUM）

• pattern-branded-types — 名目的型付け（USD と EUR の区別）には .brand<"Name">() を使用してください
• pattern-codecs — 双方向変換（解析＋シリアライズ）には z.codec() を使用してください
• pattern-pipe — 段階的な解析（文字列 → 数値 → 範囲の検証）には .pipe() を使用してください

8. アーキテクチャと境界（CRITICAL/HIGH）

• arch-boundary-parsing — システム境界（API ハンドラー、環境変数、フォーム、fetch）で解析し、型付きデータをドメインロジックに渡します
• arch-schema-organization — スキーマをその境界レイヤーと同じ場所に配置します。ドメイン型には z.infer を使用します
• arch-schema-versioning — 互換性を損なわない進化のため、変更は追加のみとします。新しいフィールドには .optional() を使用します

9. オブザーバビリティ（HIGH/MEDIUM）

• observe-structured-errors — リクエスト相関 ID を含むコンパクトな構造化ログには z.flattenError() を使用します
• observe-error-metrics — 失敗時にスキーマおよびフィールドごとのカウンターを増やす trackedSafeParse() ラッパー

スキーマ型のクイックリファレンス

型	構文
文字列	z.string()
数値	z.number()、z.int()、z.float()
ブール値	z.boolean()
BigInt	z.bigint()
日付	z.date()
Undefined	z.undefined()
Null	z.null()
Void	z.void()
Any	z.any()
Unknown	z.unknown()
Never	z.never()
リテラル	z.literal("foo")、z.literal(42)
Enum	z.enum(["a", "b"])、z.enum(TSEnum)
メールアドレス	z.email()
URL	z.url()
UUID	z.uuid()
文字列→ブール値	z.stringbool()
ISO 日時	z.iso.datetime()
ファイル	z.file()
JSON	z.json()
配列	z.array(schema)
タプル	z.tuple([a, b])
オブジェクト	z.object({})
厳密なオブジェクト	z.strictObject({})
緩やかなオブジェクト	z.looseObject({})
レコード	z.record(keySchema, valueSchema)
マップ	z.map(keySchema, valueSchema)
セット	z.set(schema)
Union	z.union([a, b])
判別可能な Union	z.discriminatedUnion("key", [...])
Intersection	z.intersection(a, b)

使用方法

詳しい説明やコード例については、個々のルールファイルを参照してください。

rules/parse-use-safeParse.md
rules/schema-object-unknowns.md

各ルールファイルには、以下の内容が含まれています。

• 重要な理由の簡単な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 追加のコンテキストと判断表

参考資料

優先度	参考資料	読むタイミング
1	references/schema-types.md	すべてのプリミティブ、文字列形式、数値、列挙型、日付
2	references/parsing-and-inference.md	parse、safeParse、z.infer、型強制
3	references/objects-and-composition.md	オブジェクト、配列、Union、pick/omit/partial、再帰
4	references/refinements-and-transforms.md	refine、superRefine、transform、pipe、デフォルト値
5	references/error-handling.md	ZodError、flattenError、treeifyError、エラーのカスタマイズ
6	references/advanced-features.md	Codec、ブランド型、JSON Schema、レジストリ
7	references/anti-patterns.md	よくある間違いと BAD/GOOD の例
8	references/boundary-architecture.md	Zod の適用箇所：Express、tRPC、Next.js、React Hook Form、環境変数、外部 API
9	references/linter-and-ci.md	ESLint ルール、CI スキーマスナップショット、未使用スキーマの検出、循環依存
10	references/testing.md	スキーマのテスト：テストでの safeParse、境界値、エラーのアサーション、モックデータ、プロパティベーステスト
11	references/testing-api.md	スキーマテスト向け Jest および Vitest API リファレンス
12	references/testing-anti-patterns.md	テストにおける間違いと BAD/GOOD の例

Zod 4.6 の主な機能

Zod 4.6 の新機能（最新：4.6.7）。詳細は公式リリースノートを参照してください。

.validate() — 低コストのブール値検証

.validate() は、結果や ZodError を構築せずに、「この入力は有効か」を判定します。最初の問題で処理を打ち切り、スキーマの入力型に対する型ガードを返します。スキーマを z.compile() でコンパイルした場合、無効な入力に対して .safeParse().success より最大 35 倍高速です（未コンパイルの場合は 5.9 倍）。

const Player = z.object({ username: z.string(), xp: z.number() })

if (Player.validate(data)) {
  data.username // narrowed: string
}

解析済みの値や問題の情報が必要な場合は .safeParse() を使用し、はい／いいえの判定だけが必要な場合は .validate() を使用します。非同期の refine には validateAsync() を使用します。

z.properties() — プロパティをその場で検証する

z.object()とは異なり、.properties()はオブジェクトの特定のプロパティをその場で検証します。プレーンオブジェクトを返すのではなく、クラスのインスタンスとプロトタイプを保持します。

const okResponse = z.instanceof(Response).properties({
  ok: z.literal(true),
  status: z.number().min(200).max(299),
})

const res = await fetch('/api/user')
okResponse.parse(res) === res // true: still a Response, methods intact

ZodInstanceOf.properties()はメソッド形式です。Zod Miniでは、チェックとしてz.properties()を使用できます。

z.withParser() — 別の場所で作成したパーサーをインストールする

z.compile()はnew Functionを使ってパーサーを作成しますが、厳格なContent Security Policyではブロックされます。z.withParser()は、CSPで制限された環境向けに、ビルド時（またはネイティブコンパイラー）に生成したパーサーを同じ契約のもとでインストールします。

z.iban()と拡張されたfromJSONSchema()

z.iban()は、ISO 7064 MOD 97-10チェックサムを含む電子形式のIBANを検証します。fromJSONSchema()は、minProperties／maxProperties、uniqueItems、contains／minContains／maxContainsにも対応しました。

2つの動作上の注意点

• エラーマップは遅延実行されます。 グローバル、ロケール、スキーマごとのerrorマップは、パース時ではなく、result.errorを初めて読み取るときに実行されるようになりました。パースと読み取りの間にz.config()を切り替えるコードでは、新しい設定が適用されます。例外をスローするパース（.parse()）には影響しません。
• z.emoji()には絵文字が必要です。 コンポーネントだけの文字列（単独のゼロ幅接合子、異体字セレクター、肌の色の修飾子、数字）は、合格しなくなりました。

4.6ではこのほか、@zod/miniがzodと連動するバージョンのスタンドアロンパッケージとして提供され、CommonJSのrequire()によるz.validate()が約3倍高速化され、再帰スキーマでのメモリー保持に関するリグレッションが修正されました。

コンパイル済みドキュメント全文

すべてのルールを展開した完全なガイドについては、AGENTS.mdを参照してください。