Zod: TypeScript-First Schema Validation

Overview

Zodは、開発者がデータを実行時に検証するためのスキーマを定義しながら、静的なTypeScriptの型を自動的に推論できるTypeScript-firstな検証ライブラリです。依存なしで、2kbのコア バンドル(gzipped)により、不変で構成可能な検証を包括的なエラー処理とともに提供します。

Installation

bun add zod
# or
bun add zod
# or
bun add zod
# or
yarn add zod

Requirements:

• TypeScript v5.5+ with "strict": true in tsconfig.json
• Zod 4.x (4.1.12+)

Important: このスキルはZod 4.xの機能を説明しています。以下のAPIはZod 4を必要とし、Zod 3.xでは利用できません:

• z.codec() - 双方向の変換
• z.iso.date(), z.iso.time(), z.iso.datetime(), z.iso.duration() - ISO形式バリデータ
• z.toJSONSchema() - JSON Schemaの生成
• z.treeifyError(), z.prettifyError(), z.flattenError() - 新しいエラーフォーマットヘルパー
• .meta() - 拡張メタデータ(Zod 3.xは.describe()のみ)
• 統一されたerrorパラメータ - message, invalid_type_error, required_error, errorMapを置き換え

Zod 3.xの互換性または移行ガイダンスについては、https://zod.devを参照してください。

Zod v3からv4への移行

完全なv3からv4への移行ドキュメントはreferences/migration-guide.mdをロードしてください。

クイックサマリー

Zod v4はパフォーマンス向上のための破壊的変更を導入しています:

• エラーカスタマイズ: 統一されたerrorパラメータを使用(message, invalid_type_error, required_errorを置き換え)
• 数値検証: より厳密 - Infinityと安全でない整数を拒否
• 文字列フォーマット: トップレベル関数に(z.string().email()ではなくz.email())
• オブジェクトデフォルト: オプショナルフィールドでも適用
• 非推奨API: .extend()を使用(.merge()ではなく)、z.treeifyError()(error.format()ではなく)
• 関数検証: .implement()メソッドを使用
• UUID検証: より厳密なRFC 9562/4122準拠

→ references/migration-guide.mdをロード: 完全な破壊的変更、移行チェックリスト、段階的な移行戦略、ロールバック手順

コアコンセプト

基本的な使用パターン

import { z } from "zod";

// スキーマを定義
const UserSchema = z.object({
  username: z.string(),
  age: z.number().int().positive(),
  email: z.string().email(),
});

// TypeScriptの型を推論
type User = z.infer<typeof UserSchema>;

// データを検証(エラー時は例外をスロー)
const user = UserSchema.parse(data);

// データを検証(結果オブジェクトを返す)
const result = UserSchema.safeParse(data);
if (result.success) {
  console.log(result.data); // 型付き!
} else {
  console.error(result.error); // ZodError
}

解析メソッド

エラー処理のニーズに基づいて、適切な解析メソッドを使用してください:

• .parse(data) - 無効な入力時にZodErrorをスロー、成功時に強く型付けされたデータを返す
• .safeParse(data) - { success: true, data }または{ success: false, error }を返す(例外なし)
• .parseAsync(data) - 非同期のrefinementsまたはtransformsを使用するスキーマ用
• .safeParseAsync(data) - 例外をスローしない非同期版

Best Practice: try-catchブロックを避け、判別された共用体を活用するために.safeParse()を使用してください。

プリミティブ型

文字列

z.string()                    // 基本的な文字列
z.string().min(5)            // 最小の長さ
z.string().max(100)          // 最大の長さ
z.string().length(10)        // 正確な長さ
z.string().email()           // メール検証
z.string().url()             // URL検証
z.string().uuid()            // UUID形式
z.string().regex(/^\d+$/)    // カスタムパターン
z.string().startsWith("pre") // プレフィックスチェック
z.string().endsWith("suf")   // サフィックスチェック
z.string().trim()            // 自動トリム
z.string().toLowerCase()     // 自動小文字化
z.string().toUpperCase()     // 自動大文字化

// ISO形式(Zod 4+)
z.iso.date()                 // YYYY-MM-DD
z.iso.time()                 // HH:MM:SS
z.iso.datetime()             // ISO 8601 datetime
z.iso.duration()             // ISO 8601 duration

// ネットワーク形式
z.ipv4()                     // IPv4アドレス
z.ipv6()                     // IPv6アドレス
z.cidrv4()                   // IPv4 CIDR表記
z.cidrv6()                   // IPv6 CIDR表記

// その他の形式
z.jwt()                      // JWTトークン
z.nanoid()                   // Nanoid
z.cuid()                     // CUID
z.cuid2()                    // CUID2
z.ulid()                     // ULID
z.base64()                   // Base64エンコード
z.hex()                      // 16進数

数値

z.number()                   // 基本的な数値
z.number().int()             // 整数のみ
z.number().positive()        // > 0
z.number().nonnegative()     // >= 0
z.number().negative()        // < 0
z.number().nonpositive()     // <= 0
z.number().min(0)            // 最小値
z.number().max(100)          // 最大値
z.number().gt(0)             // より大きい
z.number().gte(0)            // 以上
z.number().lt(100)           // より小さい
z.number().lte(100)          // 以下
z.number().multipleOf(5)     // 5の倍数である必要がある
z.int()                      // z.number().int()の短縮形
z.int32()                    // 32ビット整数
z.nan()                      // NaN値

型の強制(型変換)

z.coerce.string()            // 文字列に変換
z.coerce.number()            // 数値に変換
z.coerce.boolean()           // ブール値に変換
z.coerce.bigint()            // BigIntに変換
z.coerce.date()              // Dateに変換

// 例: クエリパラメータを解析
const QuerySchema = z.object({
  page: z.coerce.number().int().positive(),
  limit: z.coerce.number().int().max(100).default(10),
});

// "?page=5&limit=20" -> { page: 5, limit: 20 }

その他のプリミティブ型

z.boolean()                  // ブール値
z.date()                     // Dateオブジェクト
z.date().min(new Date("2020-01-01"))
z.date().max(new Date("2030-12-31"))
z.bigint()                   // BigInt
z.symbol()                   // Symbol
z.null()                     // Null
z.undefined()                // Undefined
z.void()                     // Void(undefined)

複雑な型

オブジェクト

const PersonSchema = z.object({
  name: z.string(),
  age: z.number(),
  address: z.object({
    street: z.string(),
    city: z.string(),
    country: z.string(),
  }),
});

type Person = z.infer<typeof PersonSchema>;

// オブジェクトメソッド
PersonSchema.shape                 // シェイプにアクセス
PersonSchema.keyof()              // キーの共用体を取得
PersonSchema.extend({ role: z.string() })  // フィールドを追加
PersonSchema.pick({ name: true }) // 特定フィールドを選択
PersonSchema.omit({ age: true })  // フィールドを除外
PersonSchema.partial()            // すべてのフィールドをオプションに
PersonSchema.required()           // すべてのフィールドを必須に
PersonSchema.deepPartial()        // 再帰的にオプション化

// 厳密 vs ルーズなオブジェクト
z.strictObject({ ... })           // 余分なキーは許可されない(スロー)
z.object({ ... })                 // 余分なキーを削除(デフォルト)
z.looseObject({ ... })            // 余分なキーを許可

配列

z.array(z.string())              // 文字列配列
z.array(z.number()).min(1)       // 最低1要素
z.array(z.number()).max(10)      // 最大10要素
z.array(z.number()).length(5)    // ちょうど5要素
z.array(z.number()).nonempty()   // 最低1要素

// ネストされた配列
z.array(z.array(z.number()))     // number[][]

タプル

z.tuple([z.string(), z.number()]) // [string, number]
z.tuple([z.string(), z.number()]).rest(z.boolean()) // [string, number, ...boolean[]]

Enumとリテラル

// Enum
const RoleEnum = z.enum(["admin", "user", "guest"]);
type Role = z.infer<typeof RoleEnum>; // "admin" | "user" | "guest"

// リテラル値
z.literal("exact_value")
z.literal(42)
z.literal(true)

// ネイティブTypeScript enum
enum Fruits {
  Apple,
  Banana,
}
z.nativeEnum(Fruits)

// Enumメソッド
RoleEnum.enum.admin              // "admin"
RoleEnum.exclude(["guest"])      // 値を除外
RoleEnum.extract(["admin", "user"]) // 特定の値のみを含める

共用体

// 基本的な共用体
z.union([z.string(), z.number()])

// 判別された共用体(より良いパフォーマンスと型推論)
const ResponseSchema = z.discriminatedUnion("status", [
  z.object({ status: z.literal("success"), data: z.any() }),
  z.object({ status: z.literal("error"), message: z.string() }),
]);

type Response = z.infer<typeof ResponseSchema>;
// { status: "success", data: any } | { status: "error", message: string }

インターセクション

const BaseSchema = z.object({ id: z.string() });
const ExtendedSchema = z.object({ name: z.string() });

const Combined = z.intersection(BaseSchema, ExtendedSchema);
// 以下と同等: z.object({ id: z.string(), name: z.string() })

RecordとMap

// Record: 型付けされたキーと値を持つオブジェクト
z.record(z.string())             // { [key: string]: string }
z.record(z.string(), z.number()) // { [key: string]: number }

// 部分的なRecord(いくつかのキーがオプション)
z.partialRecord(z.enum(["a", "b"]), z.string())

// Map
z.map(z.string(), z.number())    // Map<string, number>
z.set(z.string())                // Set<string>

高度なパターン

完全な高度な検証と変換パターンについてはreferences/advanced-patterns.mdをロードしてください。

クイックリファレンス

Refinements(カスタム検証):

z.string().refine((val) => val.length >= 8, "Too short");
z.object({ password, confirmPassword }).superRefine((data, ctx) => { /* ... */ });

変換(データを修正):

z.string().transform((val) => val.trim());
z.string().pipe(z.coerce.number());

Codecs(双方向変換 - v4.1の新機能):

const DateCodec = z.codec(
  z.iso.datetime(),
  z.date(),
  {
    decode: (str) => new Date(str),
    encode: (date) => date.toISOString(),
  }
);

再帰的な型:

const CategorySchema: z.ZodType<Category> = z.lazy(() =>
  z.object({ name: z.string(), subcategories: z.array(CategorySchema) })
);

オプション/Nullable:

z.string().optional()            // string | undefined
z.string().nullable()            // string | null
z.string().default("default")    // undefinedの場合はデフォルトを提供

ReadonlyとBrand:

z.object({ ... }).readonly()     // 読み取り専用プロパティ
z.string().brand<"UserId">()     // 名目上の型付け

→ references/advanced-patterns.mdをロード: 完全なrefinementパターン、非同期検証、codecの例、構成可能なスキーマ、条件付き検証、パフォーマンス最適化

エラーハンドリング

完全なエラーフォーマットとカスタマイズガイドについてはreferences/error-handling.mdをロードしてください。

クイックリファレンス

エラーフォーマット方法:

// フォーム用
const { fieldErrors } = z.flattenError(error);

// ネストされたデータ用
const tree = z.treeifyError(error);
const nameError = tree.properties?.user?.properties?.name?.errors?.[0];

// デバッグ用
console.log(z.prettifyError(error));

カスタムエラーメッセージ(3つのレベル):

// 1. スキーマレベル(最優先)
z.string({ error: "Custom message" });
z.string().min(5, "Too short");

// 2. パースごとのレベル
schema.parse(data, { error: (issue) => ({ message: "..." }) });

// 3. グローバルレベル
z.config({ customError: (issue) => ({ message: "..." }) });

ローカライゼーション(40以上の言語):

z.config(z.locales.es());  // スペイン語
z.config(z.locales.fr());  // フランス語

→ references/error-handling.mdをロード: 完全なエラーフォーマット例、カスタムエラーパターン、ローカライゼーション設定、エラーコード参照

型推論

完全な型推論とメタデータドキュメントについてはreferences/type-inference.mdをロードしてください。

クイックリファレンス

基本的な型推論:

const UserSchema = z.object({ name: z.string() });
type User = z.infer<typeof UserSchema>; // { name: string }

入力と出力(変換用):

const TransformSchema = z.string().transform((s) => s.length);
type Input = z.input<typeof TransformSchema>;   // string
type Output = z.output<typeof TransformSchema>; // number

JSON Schemaへの変換:

const jsonSchema = z.toJSONSchema(UserSchema, {
  target: "openapi-3.0",
  metadata: true,
});

メタデータ:

// メタデータを追加
const EmailSchema = z.string().email().meta({
  title: "Email Address",
  description: "User's email address",
});

// カスタムレジストリを作成
const formRegistry = z.registry<FormFieldMeta>();

→ references/type-inference.mdをロード: 完全な型推論パターン、JSON Schemaオプション、メタデータシステム、カスタムレジストリ、ブランド型

関数

関数の入力と出力を検証してください:

const AddFunction = z.function()
  .args(z.number(), z.number())  // 引数
  .returns(z.number());           // 戻り値の型

// 型付き関数を実装
const add = AddFunction.implement((a, b) => {
  return a + b; // 型チェック済み!
});

// 非同期関数
const FetchFunction = z.function()
  .args(z.string())
  .returns(z.promise(z.object({ data: z.any() })))
  .implementAsync(async (url) => {
    const response = await fetch(url);
    return response.json();
  });

よくあるパターン

環境変数

const EnvSchema = z.object({
  NODE_ENV: z.enum(["development", "production", "test"]),
  DATABASE_URL: z.string().url(),
  PORT: z.coerce.number().int().positive().default(3000),
  API_KEY: z.string().min(32),
});

// スタートアップ時に検証
const env = EnvSchema.parse(process.env);

// 型付きenvを使用
console.log(env.PORT); // number

API要求検証

const CreateUserRequest = z.object({
  username: z.string().min(3).max(20),
  email: z.string().email(),
  password: z.string().min(8),
  age: z.number().int().positive().optional(),
});

// Expressの例
app.post("/users", async (req, res) => {
  const result = CreateUserRequest.safeParse(req.body);

  if (!result.success) {
    return res.status(400).json({
      errors: z.flattenError(result.error).fieldErrors,
    });
  }

  const user = await createUser(result.data);
  res.json(user);
});

フォーム検証

const FormSchema = z.object({
  firstName: z.string().min(1, "First name required"),
  lastName: z.string().min(1, "Last name required"),
  email: z.string().email("Invalid email"),
  age: z.coerce.number().int().min(18, "Must be 18+"),
  agreeToTerms: z.literal(true, {
    errorMap: () => ({ message: "Must accept terms" }),
  }),
});

type FormData = z.infer<typeof FormSchema>;

部分的な更新

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
});

// PATCHリクエスト用: id以外をすべてオプションに
const UpdateUserSchema = UserSchema.partial().required({ id: true });

type UpdateUser = z.infer<typeof UpdateUserSchema>;
// { id: string; name?: string; email?: string }

構成可能なスキーマ

// ベーススキーマ
const TimestampSchema = z.object({
  createdAt: z.date(),
  updatedAt: z.date(),
});

const AuthorSchema = z.object({
  authorId: z.string(),
  authorName: z.string(),
});

// より大きなスキーマに構成
const PostSchema = z.object({
  id: z.string(),
  title: z.string(),
  content: z.string(),
}).merge(TimestampSchema).merge(AuthorSchema);

エコシステムの統合

完全なフレームワークとツール統合ガイドについてはreferences/ecosystem-integrations.mdをロードしてください。

クイックリファレンス

ESLintプラグイン:

• eslint-plugin-zod-x - ベストプラクティスを強制
• eslint-plugin-import-zod - インポートスタイルを強制

フレームワーク統合:

• tRPC - エンドツーエンド型安全API
• React Hook Form - フォーム検証(react-hook-form-zodスキルを参照)
• Prisma - データベースモデルからZodを生成
• NestJS - DTOと検証パイプ

コード生成:

• orval - OpenAPI → Zod
• Hey API - OpenAPI to TypeScript + Zod
• kubb - APIツールキット(コード生成付き)

→ references/ecosystem-integrations.mdをロード: セットアップ手順、統合例、Honoミドルウェア、Drizzle ORMパターン

トラブルシューティング

完全なトラブルシューティングガイド、パフォーマンスのヒント、ベストプラクティスについてはreferences/troubleshooting.mdをロードしてください。

クイックリファレンス

一般的な問題:

1. TypeScript strict modeが必須 → tsconfig.jsonで有効化
2. 大きなバンドルサイズ → z.lazy()を使用するコード分割
3. 遅い非同期refinements → キャッシュまたはデバウンス
4. 循環依存 → z.lazy()を使用
5. 遅い共用体 → z.discriminatedUnion()を使用
6. transformとrefineの混同 → .refine()を検証用に、.transform()を修正用に

パフォーマンスのヒント:

• .discriminatedUnion()を使用(.union()より5～10倍高速)
• スキーマインスタンスをキャッシュ
• .safeParse()を使用(try-catchのオーバーヘッドなし)
• 大きなスキーマを遅延ロード

ベストプラクティス:

• モジュールレベルでスキーマを定義
• 型推論を使用(z.infer)
• カスタムエラーメッセージを追加
• システム境界で検証
• 小さなスキーマを構成
• .meta()でドキュメント化

→ references/troubleshooting.mdをロード: 詳細なソリューション、パフォーマンス最適化、ベストプラクティス、テストパターン

クイックリファレンス

// プリミティブ
z.string(), z.number(), z.boolean(), z.date(), z.bigint()

// コレクション
z.array(), z.tuple(), z.object(), z.record(), z.map(), z.set()

// 特殊な型
z.enum(), z.union(), z.discriminatedUnion(), z.intersection()
z.literal(), z.any(), z.unknown(), z.never()

// モディファイア
.optional(), .nullable(), .nullish(), .default(), .catch()
.readonly(), .brand()

// 検証
.min(), .max(), .length(), .regex(), .email(), .url(), .uuid()
.refine(), .superRefine()

// 変換
.transform(), .pipe(), .codec()

// パース
.parse(), .safeParse(), .parseAsync(), .safeParseAsync()

// 型推論
z.infer<typeof Schema>, z.input<typeof Schema>, z.output<typeof Schema>

// エラーハンドリング
z.flattenError(), z.treeifyError(), z.prettifyError()

// JSON Schema
z.toJSONSchema(schema, options)

// メタデータ
.meta(), .describe()

// オブジェクトメソッド
.extend(), .pick(), .omit(), .partial(), .required(), .merge()

リファレンスをロードするべき時

以下の場合はreferences/migration-guide.mdをロード:

• Zod v3からv4へアップグレード
• 破壊的変更についての質問
• 移行チェックリストまたはロールバック戦略が必要
• 非推奨API(.merge(), error.format()など)に関連するエラー
• Infinityまたは安全でない整数に関する数値検証問題

以下の場合はreferences/error-handling.mdをロード:

• フォームまたはUIのエラーをフォーマットする必要
• カスタムエラーメッセージを実装
• z.flattenError(), z.treeifyError(), z.prettifyError()についての質問
• エラーメッセージのローカライゼーションをセットアップ
• エラーコード参照またはパターン例が必要

以下の場合はreferences/advanced-patterns.mdをロード:

• カスタムrefinementsまたは非同期検証を実装
• 双方向変換(codecs)が必要
• 再帰的な型または自己参照データを処理
• .refine(), .transform(), .codec()についての質問
• パフォーマンス最適化パターンが必要
• 条件付き検証を実装

以下の場合はreferences/type-inference.mdをロード:

• TypeScript型推論についての質問
• OpenAPIまたはAI用にJSON Schemaを生成する必要
• フォームまたはドキュメント用メタデータシステムを実装
• フォーム用カスタムレジストリが必要
• z.infer, z.input, z.outputについての質問
• ID安全性のためブランド型を使用

以下の場合はreferences/ecosystem-integrations.mdをロード:

• tRPC、React Hook Form、Prisma、またはNestJsと統合
• ESLintプラグインをベストプラクティス向けに設定
• OpenAPIからZodスキーマを生成(orval、Hey API、kubb)
• Honoミドルウェアまたはdrizzle ORMについての質問
• フレームワーク固有の統合例が必要

以下の場合はreferences/troubleshooting.mdをロード:

• TypeScript strict modeエラーが発生
• バンドルサイズの懸念または遅延ロードのニーズ
• 大きな共用体または非同期refinementsのパフォーマンス問題
• 循環依存についての質問
• ベストプラクティスまたはテストパターンが必要
• .refine()と.transform()の混同

追加リソース

• 公式ドキュメント: https://zod.dev
• GitHub: https://github.com/colinhacks/zod
• TypeScript Playground: https://zod-playground.vercel.app
• ESLintプラグイン(ベストプラクティス): https://github.com/JoshuaKGoldberg/eslint-plugin-zod-x
• tRPC統合: https://trpc.io
• エコシステム: https://zod.dev/ecosystem

---

本番環境上の注記:

• パッケージバージョン: 4.1.12+(Zod 4.x安定版)
• 依存なし
• バンドルサイズ: 2kb(gzipped)
• TypeScript 5.5+が必須
• Strict modeが必須
• 最後に確認: 2025-11-17
• スキルバージョン: 2.0.0(v4.1強化で更新)

このバージョンの新機能:

• ✨ v3からv4への包括的な移行ガイド(破壊的変更を含む)
• ✨ 3レベルシステムを備えた強化されたエラーカスタマイズ
• ✨ レジストリシステムを備えた拡張メタデータAPI
• ✨ 実用的な例を備えた改善されたエラーフォーマット
• ✨ 40以上のロケール向け組み込みローカライゼーションサポート
• ✨ 実世界のパターンを備えた詳細なcodecドキュメント
• ✨ パフォーマンス改善とアーキテクチャ変更の説明