zod-validation

Zod バリデーション（v4）

TypeScript 用の型安全なスキーマバリデーションです。Zod v4 では、トップレベルのフォーマット関数、z.stringbool()、z.iso.* 日付フォーマット、z.overwrite() 変換、z.file()、z.toJSONSchema()、ゲッターベースの再帰型、.meta()、統一された error 関数が導入されました。

パッケージ： zod（小さなバンドル向けの zod/mini もあります）

クイックリファレンス

パターン	用途
z.object({ ... })	オブジェクトスキーマを定義する
z.string()、z.number()	プリミティブ型
z.email()、z.url()、z.uuid()	トップレベルの文字列フォーマット（v4）
z.iso.date()、z.iso.datetime()	ISO 日付／時刻フォーマット（v4）
z.int()、z.float32()、z.int32()	固定幅の数値フォーマット（v4）
z.templateLiteral([...])	テンプレートリテラル型のバリデーション（v4）
z.enum([...])、z.literal()	列挙型とリテラル
z.union([...])、z.discriminatedUnion()	ユニオン型
z.array()、z.tuple()	配列型とタプル型
z.record()、z.map()	キーと値のコレクション
.optional()、.nullable()	オプションおよび nullable 修飾子
.default()、.catch()	デフォルト値とフォールバック
.prefault()	解析前のデフォルト値（スキーマを通して解析、v4）
z.coerce.number()	バリデーション前の型変換
z.stringbool()	文字列からブール値への解析（v4）
.transform()、.overwrite()	出力の変換
z.pipe()	スキーマを連結する（出力が次の入力になる）
.refine()、.superRefine()	カスタムバリデーションロジック
.parse()、.safeParse()	データを検証して取り出す
z.infer<typeof Schema>	スキーマから TypeScript 型を抽出する
z.input<>、z.output<>	変換を伴う場合の入力型と出力型
z.file()	ファイルインスタンスのバリデーション（v4）
z.toJSONSchema()	スキーマを JSON Schema に変換する（v4）
.meta()、.describe()	スキーマにメタデータを付与する（v4）
z.prettifyError()	人が読みやすいエラー形式（v4）
z.treeifyError()	構造化されたエラーツリー（.format() に代わる、v4）
z.registry()	型付きスキーマレジストリ（v4）
{ error: (issue) => ... }	統一されたエラーのカスタマイズ（v4）
ゲッターベースの再帰	z.lazy() を使わない再帰型（v4）
z.globalRegistry	グローバルスキーマメタデータレジストリ（v4）
z.config(z.locales.en())	国際化されたエラーメッセージ（v4）

よくある間違い

間違い	修正
z.string().email()	z.email()（v4 のトップレベル形式）
z.string().url()	z.url()（v4 のトップレベル形式）
try/catch を使わずに parse を使用する	エラー処理には safeParse を使用します
.optional() を忘れる	フィールドが undefined になる可能性がある場合は追加します
不明なデータに z.any() を使用する	型安全な不明値には z.unknown() を使用します
同じ型の変更に .transform() を使用する	.overwrite() を使用します（イントロスペクション可能、v4）
文字列に .min(1) を指定し忘れる	デフォルトでは空文字列も z.string() を通過します
z.number().parse(Infinity)	v4 では z.number() は Infinity を拒否します
浮動小数点数に z.number().safe() を使用する	v4 では .safe() は .int() と同じです（浮動小数点数は不可）
再帰型に z.lazy() を使用する	v4 ではゲッター構文を使用します（オブジェクトのメソッドを保持）
required_error / invalid_type_error	v4 では統一された error 関数を使用します
.refine(fn, (val) => ({ message }))	第2引数に関数を渡すオーバーロードは削除されました。.superRefine() を使用します
スキーマで errorMap を使用する	v4 では error 関数に置き換えられています
引数が1つの z.record(z.string())	v4 では2つの引数が必要です：z.record(z.string(), z.string())
ZodError の .format() / .flatten()	非推奨です。v4 では z.treeifyError(err) を使用します
入力型の値を .default() に指定する	v4 の .default() は出力型を使用します。入力には .prefault() を使用します

委譲

Zod スキーマの定義、検証、解析、型推論、強制変換、エラーの書式設定、メタデータ、JSON Schema への変換には、このスキルを使用してください。フォーム連携については、tanstack-form スキルに委譲してください。

参考資料

• スキーマ型 — プリミティブ、文字列形式、数値形式、テンプレートリテラル、オブジェクト、配列、列挙型、ユニオン、レコード、オプショナル、nullable
• 変換と解析 — 強制変換、stringbool、変換、overwrite、pipe、リファインメント、解析、型推論
• エラー処理 — 統一された error 関数、prettifyError、treeifyError、ZodError、エラーの書式設定、国際化
• よくあるパターン — フォーム検証、API レスポンス、環境変数、スキーマ合成、再帰型、ブランド型
• メタデータと JSON Schema — meta、describe、globalRegistry、toJSONSchema、ファイル検証、Zod Mini