Zod 4

TypeScript ファーストのスキーマ検証。2kb のコアバンドル（gzip 圧縮）。ゼロ依存。

重要: Zod 4 は現在の安定版です（zod@^4.0.0）。常に Zod 4 コードを作成してください。非推奨の Zod 3 パターンは使用しないでください。

インポート

import * as z from "zod";

ツリーシェイク可能なバリアント（より小さいバンドル）の場合:

import * as z from "zod/mini";

コアパターン

パース

schema.parse(data);           // 失敗時に ZodError をスロー
schema.safeParse(data);       // { success, data?, error? } を返す
await schema.parseAsync(data);
await schema.safeParseAsync(data);

型推論

type MyType = z.infer<typeof mySchema>;    // 出力型
type MyInput = z.input<typeof mySchema>;   // 入力型
type MyOutput = z.output<typeof mySchema>; // z.infer と同じ

プリミティブ

z.string();
z.number();      // 有限数のみ（無限大と NaN は不可）
z.bigint();
z.boolean();
z.symbol();
z.undefined();
z.null();
z.date();
z.nan();

強制変換

z.coerce.string();    // String(input)
z.coerce.number();    // Number(input)
z.coerce.boolean();   // Boolean(input)
z.coerce.bigint();    // BigInt(input)
z.coerce.date();      // new Date(input)

文字列フォーマット（トップレベル）

メソッドではなくトップレベル関数を使用してください。z.string().email() のようなメソッドは非推奨です。

// 正しい (Zod 4)
z.email();
z.uuid();
z.url();
z.httpUrl();
z.hostname();
z.emoji();
z.base64();
z.base64url();
z.hex();
z.jwt();
z.nanoid();
z.cuid();
z.cuid2();
z.ulid();
z.ipv4();
z.ipv6();
z.mac();
z.cidrv4();
z.cidrv6();
z.hash("sha256");     // "sha1" | "sha384" | "sha512" | "md5"
z.e164();              // 電話番号
z.iso.date();
z.iso.time();
z.iso.datetime();
z.iso.duration();

// 非推奨 (Zod 3 スタイル — 使用しないでください)
z.string().email();    // ❌
z.string().uuid();     // ❌
z.string().url();      // ❌

UUID バージョン

z.uuid();                    // あらゆる RFC 9562/4122 UUID
z.uuid({ version: "v4" });  // 特定のバージョン
z.uuidv4();                  // 便利関数
z.uuidv6();
z.uuidv7();
z.guid();                    // あらゆる 8-4-4-4-12 16 進数パターン（厳密さが低い）

カスタムメールレジックス

z.email();                                     // デフォルト (Gmail ルール)
z.email({ pattern: z.regexes.html5Email });    // ブラウザスタイル
z.email({ pattern: z.regexes.rfc5322Email });  // RFC 5322
z.email({ pattern: z.regexes.unicodeEmail });  // 国際対応メール

JWT

z.jwt();
z.jwt({ alg: "HS256" });

数値と整数

z.number();      // あらゆる有限数
z.int();         // 安全な整数範囲
z.int32();       // int32 範囲
z.float32();     // float32 範囲
z.float64();     // float64 範囲

// bigint バリアント
z.bigint();
z.int64();
z.uint64();

数値検証

z.number().gt(5);
z.number().gte(5);          // エイリアス: .min(5)
z.number().lt(5);
z.number().lte(5);          // エイリアス: .max(5)
z.number().positive();
z.number().nonnegative();
z.number().negative();
z.number().nonpositive();
z.number().multipleOf(5);   // エイリアス: .step(5)

文字列検証

z.string().max(5);
z.string().min(5);
z.string().length(5);
z.string().regex(/pattern/);
z.string().startsWith("abc");
z.string().endsWith("xyz");
z.string().includes("---");
z.string().uppercase();
z.string().lowercase();
z.string().trim();
z.string().toLowerCase();
z.string().toUpperCase();
z.string().normalize();

オブジェクト

z.object({ name: z.string(), age: z.number() });          // 不明なキーを削除
z.strictObject({ name: z.string() });                      // 不明なキーでエラー
z.looseObject({ name: z.string() });                       // 不明なキーをパス

非推奨: .strict()、.passthrough()、.strip()、.merge()、.deepPartial()。

オブジェクトメソッド

schema.extend({ newField: z.string() });    // フィールドを追加
schema.pick({ name: true });                // フィールドを選択
schema.omit({ age: true });                 // フィールドを除外
schema.partial();                           // すべてオプション
schema.partial({ name: true });             // 一部オプション
schema.required();                          // すべて必須
schema.keyof();                             // キーから ZodEnum を作成
schema.shape.name;                          // 内部スキーマにアクセス

最適な tsc パフォーマンスのためにスプレッド構文を推奨:

z.object({ ...Base.shape, ...Extra.shape, newField: z.string() });

再帰的オブジェクト

const Category = z.object({
  name: z.string(),
  get subcategories() {
    return z.array(Category);
  },
});

列挙型

z.enum(["A", "B", "C"]);               // 文字列列挙型
z.enum(MyTSEnum);                       // TypeScript 列挙型（z.nativeEnum() の代わり）
z.enum({ A: 0, B: 1 } as const);       // 列挙型様オブジェクト

非推奨: z.nativeEnum()。代わりに z.enum() を使用してください。

配列、タプル、セット、マップ

z.array(z.string());
z.array(z.string()).min(1).max(10).length(5);
z.tuple([z.string(), z.number()]);
z.tuple([z.string()], z.number());    // 可変長: [string, ...number[]]
z.set(z.number());
z.map(z.string(), z.number());

ユニオンと交差

z.union([z.string(), z.number()]);
z.discriminatedUnion("status", [
  z.object({ status: z.literal("ok"), data: z.string() }),
  z.object({ status: z.literal("err"), error: z.string() }),
]);
z.xor([z.string(), z.number()]);          // 排他的ユニオン（ちょうど 1 つマッチ）
z.intersection(schemaA, schemaB);

レコード

z.record(z.string(), z.number());                    // Record<string, number>
z.record(z.enum(["a", "b"]), z.string());            // 全網羅: { a: string; b: string }
z.partialRecord(z.enum(["a", "b"]), z.string());     // 部分的: { a?: string; b?: string }
z.looseRecord(z.string().regex(/^x_/), z.number());  // マッチしないキーをパス

重大な変更: z.record(z.string()) 単一引数形式は削除されました。常にキーと値の両方のスキーマを渡してください。

リテラル

z.literal("hello");
z.literal(42);
z.literal(true);
z.literal(["a", "b", "c"]);   // 複数値リテラル (Zod 4 の新機能)

ファイル

z.file();
z.file().min(10_000);                          // バイト単位の最小サイズ
z.file().max(1_000_000);                       // バイト単位の最大サイズ
z.file().mime("image/png");                    // 単一 MIME
z.file().mime(["image/png", "image/jpeg"]);    // 複数 MIME

Stringbool

z.stringbool();    // "true"/"yes"/"1"/"on"/"y"/"enabled" → true、逆は → false
z.stringbool({ truthy: ["yes", "y"], falsy: ["no", "n"] });
z.stringbool({ case: "sensitive" });

テンプレートリテラル

z.templateLiteral(["hello, ", z.string()]);                    // `hello, ${string}`
z.templateLiteral([z.number(), z.enum(["px", "em", "rem"])]);  // `${number}px` | ...

オプショナル、ナラブル、デフォルト

z.optional(z.string());          // または z.string().optional()
z.nullable(z.string());          // または z.string().nullable()
z.nullish(z.string());           // optional + nullable

z.string().default("hello");     // undefined で短絡、出力型を返す
z.string().prefault("hello");    // パース前のデフォルト、検証を通して実行
z.number().catch(42);            // あらゆる検証エラー時のフォールバック

重大な変更: .default() は入力型ではなく出力型を期待するようになりました。旧動作には .prefault() を使用してください。

変換とパイプ

z.transform((val) => String(val));                      // スタンドアロン変換
z.string().transform((val) => val.length);              // 文字列 → 変換をパイプ
z.preprocess((val) => String(val), z.string());         // 変換 → スキーマにパイプ
z.string().pipe(z.transform((val) => val.length));      // 明示的パイプ

// .overwrite() — 推論型を変更せずに変換
z.number().overwrite((val) => val ** 2);

コーデック（双方向変換）

Zod 4.1 の新機能。エンコード/デコードペアを定義:

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

stringToDate.decode("2024-01-15T10:30:00.000Z");  // → Date
stringToDate.encode(new Date());                    // → string
stringToDate.parse("2024-01-15T10:30:00.000Z");    // → Date (実行時はデコードと同じ)

エラーカスタマイズ

統一された error パラメータを使用（message、errorMap、invalid_type_error、required_error に代わるもの）:

z.string().min(5, { error: "Too short" });
z.string({ error: (issue) => issue.input === undefined ? "Required" : "Not a string" });
z.string({ error: (issue) => {
  if (issue.code === "too_small") return `Min ${issue.minimum}`;
}});

非推奨: message、errorMap、invalid_type_error、required_error。

メタデータとレジストリ

z.string().meta({ id: "email", title: "Email", description: "User email" });
z.string().describe("A description");      // .meta({ description: ... }) の省略形

// カスタムレジストリ
const myReg = z.registry<{ description: string }>();
z.string().register(myReg, { description: "..." });

JSON スキーマ

z.toJSONSchema(schema);                                        // Zod → JSON スキーマ
z.toJSONSchema(schema, { target: "draft-07" });                // 特定のドラフト
z.toJSONSchema(schema, { target: "openapi-3.0" });             // OpenAPI 3.0
z.fromJSONSchema(jsonSchema);                                  // JSON スキーマ → Zod (実験的)

リファインメント

z.string().refine((val) => val.includes("@"), { error: "Must contain @" });
z.string().refine((val) => val.includes("@"), { error: "...", abort: true }); // 失敗時に停止
z.array(z.string()).superRefine((val, ctx) => {
  ctx.addIssue({ code: "custom", message: "...", input: val });
});

リファインメントはスキーマ内に存在するようになりました（ZodEffects ラッパーではなく）。.refine() を他のメソッドと組み合わせることができます:

z.string().refine(v => v.includes("@")).min(5);  // Zod 4 で動作します!

エラー整形表示

z.prettifyError(zodError);   // フォーマットされた複数行文字列
z.treeifyError(zodError);    // ツリー構造 (.format() と .flatten() に代わるもの)

参考資料

• Zod Mini: references/zod-mini.md でツリーシェイク可能な API の差異、.check() の使用方法、バンドルサイズのトレードオフを参照してください
• コーデック: references/codecs.md で双方向変換、エンコード動作、一般的なコーデックパターン（stringToDate、jsonCodec など）を参照してください
• JSON スキーマ: references/json-schema.md で z.toJSONSchema() オプション、フォーマット変換、レジストリベースの複数スキーマ、z.fromJSONSchema() を参照してください
• 高度なパターン: references/advanced.md でレジストリ、リファインメント when、.superRefine()、.check()、関数、ブランド型、読み取り専用、カスタムスキーマ、高度な文字列/オブジェクト/レコード/ユニオンオプションを参照してください
• Zod 3 からのマイグレーション: references/migration.md で全ての重大な変更と非推奨 API を参照してください