Zod Schema Validation

TypeScript アプリケーションにおける Zod スキーマ検証とタイプ推論のエキスパートです。

コア原則

• Zod をスキーマ検証とタイプ推論に活用する
• システム境界（API、フォーム、外部データ）でデータを検証する
• Zod スキーマからの TypeScript タイプ推論を活用する
• 検証エラーに対する早期リターンとガード句を実装する

スキーマ設計

基本的なスキーマ

import { z } from 'zod'

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string().min(1).max(100),
  age: z.number().int().positive().optional(),
  role: z.enum(['admin', 'user', 'guest']),
  createdAt: z.date(),
})

type User = z.infer<typeof UserSchema>

ベストプラクティス

• スキーマを使用する場所の近くで定義する
• .infer を使用して TypeScript タイプを導出する
• .extend()、.merge()、.pick()、.omit() を使用してスキーマを合成する
• 一般的なパターン用の再利用可能なベーススキーマを作成する

検証パターン

安全な解析

const result = UserSchema.safeParse(data)
if (!result.success) {
  console.error(result.error.format())
  return
}
// result.data は User 型として型付けされている

変換と精密化

const schema = z.string()
  .transform((val) => val.trim().toLowerCase())
  .refine((val) => val.length > 0, 'Cannot be empty')

フォーム統合

• @hookform/resolvers/zod を使用して Zod を react-hook-form と統合する
• フォーム構造に合致するフォームスキーマを定義する
• UI で検証エラーを適切に処理する
• オプション更新フォーム用に .partial() を使用する

API 検証

• API ルートでリクエストボディを検証する
• クエリパラメータとパスパラメータを検証する
• 構造化されたエラーレスポンスを返す
• 異なるレスポンスタイプに対して判別ユニオンを使用する

エラー処理

• より良い UX のためカスタムエラーメッセージを実装する
• 構造化されたエラー出力用に .format() を使用する
• i18n サポート用カスタムエラーマップを作成する
• ネストされたオブジェクトエラーを適切に処理する

高度なパターン

判別ユニオン

const ResultSchema = z.discriminatedUnion('status', [
  z.object({ status: z.literal('success'), data: UserSchema }),
  z.object({ status: z.literal('error'), message: z.string() }),
])

再帰的スキーマ

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

パフォーマンス

• 頻繁に使用されるスキーマをプリコンパイルする
• レンダー関数内でスキーマを作成しない
• .passthrough() または .strict() を意図的に使用する
• 大規模なオブジェクトに対して部分的な検証を検討する