Zod Validation Utilities

概要

本番環境対応の Zod v4 パターンで、最小限のボイラープレートで再利用可能で型安全な検証を実現します。最新の API、予測可能なエラーハンドリング、フォーム統合に焦点を当てています。

使用する場合

• TypeScript サービスでリクエスト/レスポンス検証スキーマを定義する場合
• API、フォーム、環境変数、外部システムからの信頼できない入力をパースする場合
• 型強制、変換、クロスフィールド検証を標準化する場合
• チーム全体で再利用可能なスキーマユーティリティを構築する場合
• React Hook Form を Zod と統合する場合（zodResolver を使用）

手順

1. 厳密なオブジェクトスキーマから始め、明示的なフィールド制約を指定する
2. 最新の Zod v4 API とエラーメッセージ用の error オプションを優先する
3. 入力型が不確実な場合、境界で型強制を使用する（z.coerce.*）
4. ビジネスルール検証を refine/superRefine でスキーマ定義の近くに保つ
5. スキーマと推論型の両方をエクスポートする（z.input/z.output）一貫性のため
6. ユーティリティスキーマ（メール、ID、日付、ページネーション）を再利用して重複を削減する

検証ワークフロー

検証を API ハンドラーまたはサービスに統合する場合：

1. 定義 スキーマを境界で定義する（ハンドラー、キュー、設定ローダー）
2. パース safeParse でエラーを適切に処理する
3. 確認 result.success で失敗/成功を分岐する
4. 使用 成功パスで result.data を完全な型推論で使用する
5. 返却 フォーマットされたエラーを返すか、検証済みデータで進める

完全なパターンについてはサンプル 7 （safeParse ワークフロー）を参照してください。

サンプル

1) 最新の Zod v4 プリミティブとオブジェクトエラー

import { z } from "zod";

export const UserIdSchema = z.uuid({ error: "Invalid user id" });
export const EmailSchema = z.email({ error: "Invalid email" });
export const WebsiteSchema = z.url({ error: "Invalid URL" });

export const UserProfileSchema = z.object(
  {
    id: UserIdSchema,
    email: EmailSchema,
    website: WebsiteSchema.optional(),
  },
  { error: "Invalid user profile payload" }
);

2) 型強制、前処理、変換

import { z } from "zod";

export const PaginationQuerySchema = z.object({
  page: z.coerce.number().int().min(1).default(1),
  pageSize: z.coerce.number().int().min(1).max(100).default(20),
  includeArchived: z.coerce.boolean().default(false),
});

export const DateFromUnknownSchema = z.preprocess(
  (value) => (typeof value === "string" || value instanceof Date ? value : undefined),
  z.coerce.date({ error: "Invalid date" })
);

export const NormalizedEmailSchema = z
  .string()
  .trim()
  .toLowerCase()
  .email({ error: "Invalid email" })
  .transform((value) => value as Lowercase<string>);

3) 複雑なスキーマ構造

import { z } from "zod";

const TagSchema = z.string().trim().min(1).max(40);

export const ProductSchema = z.object({
  sku: z.string().min(3).max(24),
  tags: z.array(TagSchema).max(15),
  attributes: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])),
  dimensions: z.tuple([z.number().positive(), z.number().positive(), z.number().positive()]),
});

export const PaymentMethodSchema = z.discriminatedUnion("type", [
  z.object({ type: z.literal("card"), last4: z.string().regex(/^\d{4}$/) }),
  z.object({ type: z.literal("paypal"), email: z.email() }),
  z.object({ type: z.literal("wire"), iban: z.string().min(10) }),
]);

4) refine と superRefine

import { z } from "zod";

export const PasswordSchema = z
  .string()
  .min(12)
  .refine((v) => /[A-Z]/.test(v), { error: "Must include an uppercase letter" })
  .refine((v) => /\d/.test(v), { error: "Must include a number" });

export const RegisterSchema = z
  .object({
    email: z.email(),
    password: PasswordSchema,
    confirmPassword: z.string(),
  })
  .superRefine((data, ctx) => {
    if (data.password !== data.confirmPassword) {
      ctx.addIssue({
        code: "custom",
        path: ["confirmPassword"],
        message: "Passwords do not match",
      });
    }
  });

5) オプション、nullable、nullish、デフォルト値

import { z } from "zod";

export const UserPreferencesSchema = z.object({
  nickname: z.string().min(2).optional(),      // undefined を許可
  bio: z.string().max(280).nullable(),         // null を許可
  avatarUrl: z.url().nullish(),                // null または undefined を許可
  locale: z.string().default("en"),           // 不在時のフォールバック
});

6) React Hook Form 統合（zodResolver）

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";

const ProfileFormSchema = z.object({
  name: z.string().min(2, { error: "Name too short" }),
  email: z.email({ error: "Invalid email" }),
  age: z.coerce.number().int().min(18),
});

type ProfileFormInput = z.input<typeof ProfileFormSchema>;
type ProfileFormOutput = z.output<typeof ProfileFormSchema>;

const form = useForm<ProfileFormInput, unknown, ProfileFormOutput>({
  resolver: zodResolver(ProfileFormSchema),
  criteriaMode: "all",
});

7) safeParse を用いたエラーハンドリングワークフロー

import { z } from "zod";
import type { ZodError } from "zod";

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

function parseAndHandle(input: unknown) {
  const result = ResultSchema.safeParse(input);

  if (!result.success) {
    const error = result.error as ZodError;
    console.error("Validation failed:", error.errors);
    return { success: false as const, error: error.format() };
  }

  return { success: true as const, data: result.data };
}

ヒント: 高度な discriminated union パターンと複雑な React Hook Form ワークフローについては、references/advanced-patterns.md を参照してください。

ベストプラクティス

• スキーマを境界の近くに保つ（HTTP ハンドラー、キュー、設定ローダー）
• 回復可能なフローには safeParse を、fail-fast 実行には parse を優先する
• 小さなスキーマユーティリティ（ID、メール、スラッグ）を共有して一貫性を強制する
• 変換/型強制が実行時の形状を変更する場合、z.input と z.output を使用する
• preprocess の過度な使用を避け、可能な限り明示的な z.coerce.* を優先する
• 外部ペイロードを信頼されていないものとして扱い、使用前に必ず検証する

制約と警告

• サンプルがインストール済みの zod メジャーバージョン（v4 API を表示）と一致することを確認する
• error は Zod v4 パターンではカスタムエラー用の推奨オプション
• Discriminated union には、バリアント全体で安定した discriminator キーが必要
• 型強制は悪い上流データを隠す可能性があるため、防御的に境界値と refinement を追加する