JSONからZodスキーマのNullableフィールドを扱う

ZodのNullableフィールド

JSONは明示的に値としてnullをサポートしています。Zodの.nullable()修飾子は、フィールドが基本型に加えてnullを受け入れることを許可します。

JSON例

{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com",
  "deletedAt": null,
  "lastLoginAt": null,
  "avatar": null
}

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

import { z } from "zod";

const userSchema = z.object({
  id: z.number().int().nullable(),
  name: z.string().nullable(),
  email: z.string().nullable(),
  deletedAt: z.null().nullable(),
  lastLoginAt: z.null().nullable(),
  avatar: z.null().nullable(),
});

type User = z.infer<typeof userSchema>;

実践的なパターン：Nullable日付

APIの一般的なパターンとして、まだ設定されていない場合にnullになる日付フィールドがあります：

const taskSchema = z.object({
  id: z.number(),
  title: z.string(),
  createdAt: z.string(),
  completedAt: z.string().nullable(), // 完了していない場合はnull
  deletedAt: z.string().nullable(),   // 削除されていない場合はnull
});

nullable() vs null()

• z.null()は値nullのみを受け入れます。
• z.string().nullable()は文字列またはnullを受け入れます。
• この区別は、サンプルでは常にnullだが本番環境では文字列になりうるフィールドに重要です。

.optional()との組み合わせ

// フィールド：string、null、または完全に欠如可能
z.string().nullable().optional()

// フィールド：stringまたは欠如（ただしnullは不可）
z.string().optional()

// フィールド：stringまたはnull（ただし存在必須）
z.string().nullable()

Nullishの省略形

Zodは.nullable().optional()の省略形として.nullish()を提供します：

// これらは同等：
z.string().nullable().optional()
z.string().nullish()

フィールドがnull、undefined、または基本型のいずれかになりうる場合に.nullish()を使用します。これはSQLデータベースでカラムがNULLになり得、ORMクエリが選択されていないフィールドを省略する可能性がある一般的なパターンです。