zod

Zod

Zod による検証、スキーマ設計、型推論、エラー処理、JSON Schema、AOT コンパイル、Zod Mini、Zod Core、または Zod 3 から Zod 4 への移行に関わる作業では、このスキルを使用してください。

スナップショット：[email protected] / @zod/[email protected]（2026-10-01 に確認済み）。Zod 4 の latest を使用してください。canary は使用しないでください。バージョンが異なる場合は、source-map.md を参照して情報を更新してください。

ワークフロー

1. コードを変更する前に、ローカルの Zod の使用状況を確認します。
   • zod、任意の @zod/mini、検証アダプター、フォームライブラリ、API レイヤー、コードジェネレーター、TypeScript のパッケージバージョン。
   • インポート：zod、zod/v4、zod/mini、@zod/mini、zod/v4/core、zod/compile、または zod/v3。
   • スキーマの役割：信頼できない境界の検証、API コントラクト、フォーム値、環境変数の解析、永続化、JSON Schema/OpenAPI、ホットパスのコンパイル、ライブラリ連携、または移行。
   • 型の流れ：z.input<>、z.output<>、z.infer<> がどこで使われているか。特に、トランスフォーム、コーデック、強制変換、デフォルト値、前処理の周辺を確認します。
2. ユーザーが最新または現在の動作を求めている場合、インストール済みのバージョンが不明な場合、または移行の影響を受ける API を扱う場合は、ドキュメントを更新します。source-map.md から確認を始めてください。
3. インストール、インポート、parse／validate／compile、型推論、パッケージのバリエーション、境界設計については、setup-core.md を参照してください。
4. スキーマのプリミティブ、文字列形式、オブジェクト、レコード、配列、ユニオン、再帰スキーマ、関数、ブランド、z.toZod、インスタンスのプロパティチェックについては、schema-api.md を参照してください。
5. リファインメント、.check()、トランスフォーム、パイプ、前処理、コーデック、デフォルト値、事前入力値、catch 値、エラーについては、effects-errors.md を参照してください。
6. メタデータ、レジストリ、JSON Schema への変換、Zod Mini、Zod Core、ライブラリ作成者向けのサポート、Zod 4／4.5／4.6 の移行確認については、metadata-jsonschema-migration.md を参照してください。
7. 既存のプロジェクトのスタイルに合わせて実装します。
   • バージョン境界によって異なるサブパスが必要な場合を除き、ローカルのインポート規約に従います。
   • 広範な z.any() や未検証の型キャストより、明示的な境界スキーマを優先します。
   • API、フォーム、環境変数、ストレージの境界では、解析と変換の動作が明確に分かるようにします。
   • canary 限定の動作を導入しないでください。npm の canary は latest より古い状態です。

Zod の判断基準

• スキーマは、単なる TypeScript 型ファクトリーではなく、実行時の契約として扱います。
• 回復可能なユーザー入力や入力データのエラーには safeParse を使用し、無効なデータを例外的な事態として扱う場合は parse を使用します。
• ZodError を発生させず、ブール値の型ガードだけが必要な場合は、.validate() ／ z.validate() を使用します。
• リファインメント、変換、または codec の処理経路が非同期の場合は、parseAsync、safeParseAsync、または validateAsync を使用します。
• coerce、preprocess、transform、pipe、codec、default、prefault、または catch を使う場合は、z.input<> と z.output<> を区別します。実行時の z.input(schema) ／ z.output(schema) は codec ／ pipe の各側を取り出します。
• 新しいコードを書く場合は、非推奨のメソッド形式ではなく、Zod 4 のトップレベル文字列形式 API（z.email()、z.uuid()、z.hash("sha256")、z.creditCard()、z.iban()、z.iso.datetime()）を優先します。
• z.object() はデフォルトで未知のキーを削除します。z.strictObject()、z.looseObject()、または .catchall() を意図的に使い分けてください。__proto__ は常に削除されます。
• enum をキーとするレコードについて、Zod 4 は網羅性をチェックします。キーが enum のマップを省略可能にするには、z.partialRecord() を使用します。
• オブジェクトの合成にはオブジェクトスプレッドまたは .extend() を優先し、リファインメントを含むスキーマを拡張する場合は .safeExtend() を使用します。
• 双方向のシリアライズには codec を使用し、一方向のパースには変換を使用します。
• ホットパスとなるオブジェクト／配列／ユニオンの処理は、z.compile()（またはアプリでは import "zod/compile"）でコンパイルします。最終スキーマをコンパイルしてください。ライブラリではコンパイルしないでください。
• クラスのインスタンスは、z.object() ではなく、z.instanceof(C).properties({ ... }) でその場で検証します。
• ライブラリの作成者は、Zod と Zod Mini の両方に対応する場合、zod/v4/core とトップレベルのパースヘルパーを使用します。新しいライブラリでは、ピア依存関係を zod@^4.0.0 のみにしてください。

検証

リポジトリに既存のチェックがあれば、それを優先してください。重要な Zod の変更では、関連する項目を組み合わせて実施します。

• 推論される入力／出力の型、スキーマの合成、ブランド、z.toZod<T>()、およびライブラリのジェネリック制約について、型チェックを行います。
• 有効な入力、無効な入力、未知のキー、デフォルト／prefault、変換、codec、非同期処理経路、およびエラー処理経路を対象に、焦点を絞ったテストを行います。
• API ハンドラー、環境変数ローダー、フォーム、サーバーアクション、CLI、永続化アダプターなど、境界で使われるパーサーのランタイムスモークテストを行います。
• ホットスキーマのコンパイルチェックを行います。有効な入力の処理速度が維持され、無効な入力では同じ issue が生成されることを確認します。派生スキーマ（.extend()、.refine()）で高速処理経路が必要な場合は、再コンパイルします。
• スキーマメタデータまたは変換の挙動を変更する場合は、JSON Schema ／ OpenAPI 出力のスナップショットテストまたはコントラクトテストを行います。
• 非推奨の Zod 3 API、4.5／4.6 の健全性修正（日付時刻の秒、文字列のコードポイント、z.emoji()、JSON Schema の境界値）、オブジェクトのデフォルト、enum レコード、関数、削除された内部機能について、移行チェックを行います。