Zod v4.6.7 ユーザーガイド — 概要 & クイックスタート

Zod v4.6.7 ユーザーガイドへようこそ。Zodは静的型推論を備えたTypeScriptファーストのスキーマ宣言・バリデーション・双方向変換ライブラリです。バージョン4.6.7では、共通のzod/v4/coreエンジンを中心に、2種類のファサード（zodおよびzod/mini）、ネイティブJSON Schema双方向変換、双方向Codec、JITオブジェクトコンパイル、49言語のエラーロケールを備えた新アーキテクチャへと刷新されました。

index_1
Zod v4.6.7 アーキテクチャ — デュアルファサード・コアエンジン・主要機能
Source Code 
from drawlib.canvas import save, setup
from drawlib.icons import phosphor
from drawlib.smartarts import CardList, KpiCards, Panel
from drawlib.styles import Styles

setup(width=168, height=74)

left_panel = Panel(
    "Zod v4.6.7 コア & デュアルファサード構成",
    "Unified Engine",
    style=Styles.Neutral,
    header_style=Styles.PrimaryNeutral.patch(shape_line_width=1.2),
    text_style=Styles.DarkBold.patch(text_size=11.5),
    description_style=Styles.Muted.patch(text_size=10.0),
    icon=phosphor.stack,
    icon_style=Styles.PrimaryBold,
    header_variant="filled",
    header_height=9.0,
)
left_panel.draw((5.0, 5.0), width=98.0, height=64.0, align="bottom_left")
c_xy, c_w, c_h = left_panel.get_content_box((5.0, 5.0), width=98.0, height=64.0, padding=(3.5, 3.0))

facade_list = CardList(
    style=Styles.White,
    text_style=Styles.DarkBold.patch(text_size=10.5),
    description_style=Styles.Muted.patch(text_size=10.0),
    badge_shape="rounded_rect",
    badge_style=Styles.PrimaryNeutral,
    badge_text_style=Styles.DarkBold.patch(text_size=10.0),
    spacing=2.2,
)
facade_list.add(
    "Classic ファサード (zod)",
    "直感的なメソッドチェーン (.min(), .refine(), .transform())",
    badge_text="FULL",
    style=Styles.PrimaryFlat,
    text_style=Styles.WhiteBold.patch(text_size=10.5),
    description_style=Styles.White.patch(text_size=10.0),
    badge_style=Styles.White,
    badge_text_style=Styles.PrimaryBold.patch(text_size=10.0),
)
facade_list.add(
    "Tree-Shakeable ファサード (zod/mini)",
    "関数型チェック合成 (z.check() によりバンドル約85%削減)",
    badge_text="MINI",
)
facade_list.add(
    "共通コアエンジン (zod/v4/core)",
    "$constructor トレイト・JITコンパイラ・Codec・Standard Schema",
    badge_text="CORE",
)
facade_list.draw(c_xy, width=c_w, height=c_h)

kpi = KpiCards(
    style=Styles.Neutral,
    metric_style=Styles.PrimaryBold.patch(text_size=12.5),
    text_style=Styles.DarkBold.patch(text_size=10.5),
    description_style=Styles.Muted.patch(text_size=10.0),
    accent_style=Styles.PrimaryFlat,
    accent_position="left_pill",
    metric_layout="left_column",
    metric_width_ratio=0.35,
    spacing=2.5,
)
kpi.add("z.infer<T>", "静的型推論", "Input / Output 型を自動抽出")
kpi.add("Draft-2020", "JSON Schema", "to/fromJSONSchema 標準搭載")
kpi.add("49 Locales", "多言語 i18n", "49言語のエラーメッセージ")
kpi.add(
    "JIT Speed",
    "高速オブジェクト検証",
    "動的コード生成による高速化",
    metric_style=Styles.AccentBold.patch(text_size=12.5),
    accent_style=Styles.AccentFlat,
)
kpi.draw((107.0, 5.0), width=56.0, height=64.0, columns=1, align="bottom_left")

save()

なぜ Zod v4.6.7 なのか？

TypeScriptの型システムはビルド時に完全に消去されます。ネットワーク越しのAPIレスポンス、JSON.parse()の出力、環境変数、フォーム入力、LLMのツール呼び出し引数などはすべて、実行時には信頼できないunknown値として流入します。Zod v4.6.7は単一の宣言的スキーマからコンパイル時のTypeScript型と実行時のデータ不変条件を一元管理します。

  1. 共通コア上のデュアルファサード（zod & zod/mini）: メソッドチェーンが充実したimport { z } from "zod"と、不要なコードを極限までTree-Shakingできる関数型API import * as z from "zod/mini"の2つの入り口を提供し、どちらも同一のzod/v4/core（$ZodType）上で動作します。
  2. トップレベル文字列フォーマット＆固定幅数値型: z.email()、z.uuid()、z.url()、z.jwt()、z.ipv4()、z.cidrv4()、z.iso.datetime()などがトップレベル関数に昇格し、z.int()、z.int32()、z.uint32()、z.float32()、z.float64()、z.int64()といった厳密な数値スキーマも標準提供されます。
  3. 双方向Codec（z.codec()）: 単方向のみの.transform()とは異なり、z.codec(inputSchema, outputSchema, { decode, encode })によってデコード（z.decode()）と逆方向のシリアライズ（z.encode()）を型安全に双方向実行できます。
  4. メタデータレジストリ＆ネイティブJSON Schema: z.registry<Meta>()や.meta()で型付きメタデータを付与し、z.toJSONSchema()およびz.fromJSONSchema()で外部ライブラリなしにJSON Schemaと相互変換できます。
  5. 構造化エラー整形＆49言語ロケール: バリデーション失敗時の$ZodIssueをツリー構造（z.treeifyError()）、CLI向けテキスト（z.prettifyError()）、フォーム向けフラット構造（z.flattenError()）に整形でき、日本語（z.locales.ja()）を含む49言語のロケールを同梱しています。

バリデーションライフサイクルの全体像

Zod v4におけるすべてのスキーマ検証は、zod/v4/coreが管理する決定論的なパイプラインを通過します。

index_2
Zod v4 実行時バリデーションパイプライン — 未検証入力から型付き SafeParseResult まで
Source Code 
from drawlib.canvas import save, setup
from drawlib.diagrams.flow import Decision, End, FlowDiagram, Process, Start
from drawlib.styles import Colors, Styles

setup(width=166, height=70)

flow = FlowDiagram(
    node_style=Styles.Neutral.patch(text_size=10.5),
    edge_style=Styles.DarkBold,
    edge_text_style=Styles.DarkBold.patch(text_size=10.0),
    title="Zod v4 実行時バリデーション & SafeParse パイプライン",
    title_style=Styles.DarkBold.patch(text_size=13.0),
)

inp = flow.add(
    Start(
        "未検証の入力データ\n(unknown)",
        width=26,
        height=13,
        style=Styles.PrimaryFlat.patch(text_color=Colors.White, text_size=10.5),
    ),
    xy=(15, 31),
)
entry = flow.add(
    Process("schema.safeParse()\nParsePayload 初期化", width=29, height=14, style=Styles.PrimaryNeutral.patch(text_size=10.5)),
    xy=(49, 31),
)
checks = flow.add(
    Process("基本型 & チェック実行\n($ZodCheck パイプライン)", width=30, height=14, style=Styles.Neutral.patch(text_size=10.5)),
    xy=(86, 31),
)
dec = flow.add(
    Decision("issues.length\n=== 0 ?", width=24, height=16, style=Styles.SecondaryNeutral.patch(text_size=10.5)),
    xy=(120, 31),
)
ok = flow.add(
    End("検証成功 (Success)\n{ success: true, data: T }", width=30, height=13, style=Styles.SuccessNeutral.patch(text_size=10.5)),
    xy=(146, 50),
)
err = flow.add(
    End("検証失敗 (Error)\n{ success: false, error }", width=30, height=13, style=Styles.DangerNeutral.patch(text_size=10.5)),
    xy=(146, 12),
)

inp.connect(entry, padding=1.0)
entry.connect(checks, padding=1.0)
checks.connect(dec, padding=1.0)
dec.connect(ok, label="Yes", start_side="top", end_side="left", padding=1.0)
dec.connect(err, label="No", start_side="bottom", end_side="left", padding=1.0)

flow.draw(xy=(3.0, 3.0))
save()

60秒クイックスタート

スキーマを1回定義するだけで、z.infer<typeof Schema>による静的TypeScript型の抽出、.safeParse()による例外を投げない安全な実行時検証、z.toJSONSchema()によるJSON Schema出力まで一気通貫で行えます。

import { z } from "zod";

// 1. v4のトップレベル形式とメタデータを用いてスキーマを定義
const UserSchema = z
  .object({
    id: z.uuid(),
    email: z.email(),
    username: z.string().min(3).max(24).trim(),
    role: z.enum(["admin", "editor", "viewer"]).default("viewer"),
    age: z.int().min(18).optional(),
    createdAt: z.iso.datetime(),
  })
  .meta({
    id: "User",
    title: "Application User Account",
  });

// 2. 静的な TypeScript の Output 型と Input 型を抽出
type User = z.infer<typeof UserSchema>;
type UserInput = z.input<typeof UserSchema>; // Input型では `role` は省略可能 (optional)

// 3. 例外をスローせずに未検証データを安全に検証
const result = UserSchema.safeParse({
  id: "550e8400-e29b-41d4-a716-446655440000",
  email: "alice@example.com",
  username: "  alice_dev  ",
  createdAt: "2026-11-10T10:00:00Z",
});

if (!result.success) {
  console.error(z.prettifyError(result.error));
} else {
  // result.data は `User` 型に絞り込まれ、username の前後空白除去や role のデフォルト適用も完了
  console.log(result.data.username, result.data.role);
}

// 4. Draft-2020-12 JSON Schema を直接生成
const jsonSchema = z.toJSONSchema(UserSchema);

サブパスの選び方（zod vs zod/mini vs zod/v4/core）

Zod v4.6.7のpackage.jsonは、バックエンドサーバー、バンドルサイズ制約の厳しいブラウザ・Edge環境、フレームワーク開発者のそれぞれに最適化されたサブパスエクスポートを提供しています。

サブパス Import 主な対象ユースケース APIスタイル バンドルサイズ & Tree-Shaking特性
zod (zod/v4) フルスタック・バックエンド開発 メソッドチェーン（z.string().min(5).trim()）＋トップレベル関数 スキーマプロトタイプに便利なメソッド群を実装。初回構築時に英語（en）ロケールを自動設定
zod/mini (zod/v4/mini) フロントエンドSPA、Edge Workers、軽量CLI 関数型合成（z.string().check(z.minLength(5), z.trim())） ラッパーメソッドを最小化。未使用のチェック関数やロケールをバンドラが完全に除去（約85%軽量）
zod/v4/core ライブラリ・フレームワーク作者 低レベル$ZodTypeインターフェース、$constructor、_safeParse zodとzod/miniの双方が共有するファサード非依存のコア基盤
zod/locales 多言語対応アプリケーション 49言語のロケールパック（z.config(z.locales.ja())） zod/v4/locales/ja.jsのように個別言語のみをTree-Shakeしてインポート可能

ガイドの構成と各章のロードマップ

本ポータルは、基礎的なセットアップから高度な構造化スキーマ、最適化手法まで3つのパート・全8章で構成されています。

Part I — はじめに

  • 1. インストール・Strict設定・型推論: zod@4.6.7のインストール、tsconfig.jsonで"strict": trueが必須である技術的理由、parse / safeParse / parseAsync / encode / decodeの使い分け、およびz.infer<T>・z.input<T>・z.output<T>による型抽出。
  • 2. プリミティブ・リテラル・文字列フォーマット: Zod v4プリミティブ型（string、int、float32、float64、bigint、boolean、date、literal、enum）の体系、トップレベル文字列フォーマット（z.email()、z.uuid()、z.url()、z.jwt()、z.ipv4()、z.iso.*）、z.templateLiteral()、z.coerce.*、環境変数向けz.stringbool()。

Part II — 構造化スキーマと合成

Part III — エラー処理・相互運用・最適化

関連ドキュメントポータル

API全体の網羅的なシグネチャ一覧、内部エンジンの設計詳細、パフォーマンス診断レポートについては以下の関連ポータルを参照してください。

  • APIリファレンスカタログ: すべてのスキーマコンストラクタ、チェック関数、Codecヘルパー、エラー整形関数、JSON Schemaプロセッサの完全なAPIリファレンス。
  • 内部アーキテクチャガイド: zod/v4/core、$constructorプロトタイプ合成、ParsePayloadステートマシン、JITコード生成の内部構造解説。
  • PNI501 診断レポート: Zod v4.6.7のパフォーマンス特性、バンドルサイズベンチマーク、エッジケース挙動に関する技術分析レポート。