JSONからZodスキーマのオプショナルフィールドを扱う

Zodのオプショナルフィールド

JSONでは、キーは存在するか存在しないかのどちらかです。Zodの.optional()修飾子は、バリデーション対象のオブジェクトからフィールドがundefinedまたは完全に欠落することを許可します。

JSON例

{
  "id": 1,
  "name": "Alice",
  "bio": "Full-stack developer",
  "website": "https://alice.dev"
}

生成されるZodスキーマ（optionalトグル使用）

import { z } from "zod";

const userSchema = z.object({
  id: z.number().int().optional(),
  name: z.string().optional(),
  bio: z.string().optional(),
  website: z.string().optional(),
});

type User = z.infer<typeof userSchema>;
// { id?: number; name?: string; bio?: string; website?: string }

.optional()を使うべき場合

• 部分更新エンドポイント — フィールドの任意のサブセットを送信できるPATCHリクエスト。
• ユーザープロフィールデータ — ユーザーが入力していない可能性のあるbio、website、avatarなどのフィールド。
• 後方互換スキーマ — 古いクライアントが送信しないAPIに追加された新しいフィールド。

選択的なオプショナルフィールド

実際には、一部のフィールドを必須に、他をオプショナルにしたいことが多いです。Zodはこのために.partial()を提供します：

// すべてのフィールドをオプショナルに
const partialUserSchema = userSchema.partial();

// 特定のフィールドのみオプショナルに
const updateUserSchema = userSchema.partial({
  bio: true,
  website: true,
});

デフォルト値

.optional()と.default()を組み合わせてフォールバック値を提供します：

const configSchema = z.object({
  theme: z.string().optional().default("dark"),
  pageSize: z.number().optional().default(20),
  showSidebar: z.boolean().optional().default(true),
});

フィールドが存在しない場合、Zodはパース時に自動的にデフォルトを代入します。これは設定オブジェクトやユーザー設定に特に有用です。

.optional() vs .nullable()

• .optional()はundefinedを受け入れる（フィールドが存在しなくてよい）
• .nullable()はnullを受け入れる（フィールドは存在するがnull）
• 最大限の柔軟性のために両方をチェーン：z.string().nullable().optional()