概要: Zod v4.6.7 API リファレンスカタログ

本カタログは、Zod v4 (v4.6.7) のすべての公開パッケージエントリーポイント（zod、zod/mini、zod/v4/core、zod/locales、zod/compile、zod/v3）を対象としたシンボル索引付き API リファレンスです。左サイドバーのツリーまたは / キーのクイックフィルターを使用して、クラス、コンストラクタ関数、チェック関数、型定義を即座に検索できます。

00_overview_1
Zod v4.6.7 公開サブパスと 5 モジュール API リファレンスカタログの全体構成
Source Code 
from drawlib import canvas
from drawlib.diagrams.architecture import ArchitectureDiagram, Node, NodeGroup, PhosphorIcon
from drawlib.styles import Styles
from drawlib.text import text

canvas.clear()
canvas.setup(width=180, height=102, dpi=150)

text(
    (90, 97.0),
    "Zod v4.6.7 公開サブパス -> 5 カタログリファレンスモジュール",
    style=Styles.DarkBold.patch(text_size=13.0),
)

d = ArchitectureDiagram(
    node_style=Styles.PrimaryBold,
    node_text_style=Styles.DarkBold.patch(text_size=10.5),
    edge_style=Styles.PrimaryBold,
    edge_text_style=Styles.DarkBold.patch(text_size=10.0),
    node_card_style=Styles.Neutral,
)

# Left Group: Public Package Subpath Exports
pkg_group = d.add(
    NodeGroup(title="公開パッケージ (package.json)", padding=5.0),
    xy=(2.0, 4.0),
)

sub_classic = pkg_group.add(
    Node(
        "zod (.) / zod/v4\nクラシックメソッド API",
        width=48,
        height=14,
        icon=PhosphorIcon.PACKAGE,
        icon_size=6.0,
        style=Styles.WhiteBold,
        text_style=Styles.WhiteBold.patch(text_size=10.5),
        card_style=Styles.PrimaryFlat,
    ),
    xy=(29.0, 68.0),
)
sub_locales = pkg_group.add(
    Node(
        "zod/locales\n50 言語ロケールパック",
        width=48,
        height=14,
        icon=PhosphorIcon.GLOBE,
        icon_size=6.0,
        card_style=Styles.Neutral,
    ),
    xy=(29.0, 49.0),
)
sub_mini = pkg_group.add(
    Node(
        "zod/mini\nTree-Shakeable 関数 API",
        width=48,
        height=14,
        icon=PhosphorIcon.FEATHER,
        icon_size=6.0,
        card_style=Styles.PrimaryNeutral,
    ),
    xy=(29.0, 30.0),
)
sub_core = pkg_group.add(
    Node(
        "zod/v4/core & compile\n共通 $Zod* エンジン + AOT",
        width=48,
        height=14,
        icon=PhosphorIcon.CPU,
        icon_size=6.0,
        card_style=Styles.PrimaryNeutral,
    ),
    xy=(29.0, 11.0),
)

# Right Group: 5 API Reference Catalog Pages
cat_group = d.add(
    NodeGroup(title="API リファレンスカタログモジュール (01 - 05)", padding=5.0),
    xy=(88.0, 4.0),
)

mod01 = cat_group.add(
    Node(
        "01. プリミティブ・型変換・文字列形式\nz.string / number / iso / uuid",
        width=68,
        height=12.5,
        icon=PhosphorIcon.TEXT_AA,
        icon_size=5.5,
        card_style=Styles.Neutral,
    ),
    xy=(39.0, 71.0),
)
mod02 = cat_group.add(
    Node(
        "02. オブジェクト・コレクション・合成\nZodObject / Array / Union / Optional",
        width=68,
        height=12.5,
        icon=PhosphorIcon.CUBE,
        icon_size=5.5,
        card_style=Styles.Neutral,
    ),
    xy=(39.0, 55.0),
)
mod03 = cat_group.add(
    Node(
        "03. チェック・Refine・双方向 Codec\nz.check / refine / pipe / codec",
        width=68,
        height=12.5,
        icon=PhosphorIcon.ARROWS_LEFT_RIGHT,
        icon_size=5.5,
        card_style=Styles.PrimaryNeutral,
    ),
    xy=(39.0, 39.0),
)
mod04 = cat_group.add(
    Node(
        "04. パース・エラー・レジストリ・JSON Schema\nparse / ZodError / registry / toJSONSchema",
        width=68,
        height=12.5,
        icon=PhosphorIcon.FILE_CODE,
        icon_size=5.5,
        card_style=Styles.Neutral,
    ),
    xy=(39.0, 23.0),
)
mod05 = cat_group.add(
    Node(
        "05. Mini & Core エンジン・AOT コンパイラ\nzod/mini / $constructor / compile",
        width=68,
        height=12.5,
        icon=PhosphorIcon.LIGHTNING,
        icon_size=5.5,
        style=Styles.WhiteBold,
        text_style=Styles.WhiteBold.patch(text_size=10.5),
        card_style=Styles.AccentFlat,
    ),
    xy=(39.0, 7.0),
)

# Planar orthogonal bus channels (at x=78, x=71, and x=65) with zero crossings
sub_classic.fork([mod01, mod02, mod03, mod04], at_x=78.0, padding=1.5)
d.connect(sub_locales, mod04, padding=1.5).via((71.0, 53.0), (71.0, 27.0))
d.connect(sub_mini, mod05, style=Styles.AccentBold, padding=1.5).via((65.0, 34.0), (65.0, 11.0))
d.connect(sub_core, mod05, style=Styles.AccentBold, padding=1.5).via((65.0, 15.0), (65.0, 11.0))

d.draw(xy=(4.0, 2.0))
canvas.save()

packagezod (サブパスエクスポート一覧)#

Zod v4.6.7 は packages/zod/package.json で複数のサブパスエクスポートを提供しており、メソッドチェーン重視の標準開発（zod）、極限までバンドルサイズを削減する Tree-Shaking（zod/mini）、あるいはライブラリ作者向けの共通コアエンジン（zod/v4/core）を用途に応じて選択できます。

00_overview_2
パッケージサブパスエクスポート一覧 (packages/zod/package.json)
Source Code 
from drawlib.canvas import save, setup
from drawlib.smartarts import Table
from drawlib.styles import Colors, Styles
from drawlib.text import text

setup(width=184, height=68, dpi=150)

text(
    (92, 63.5),
    "Zod v4.6.7 サブパスエクスポートと対象モジュール対応表",
    style=Styles.DarkBold.patch(text_size=12.5),
)

table = Table(
    cell_style=Styles.White,
    text_style=Styles.Dark.patch(text_size=10.0),
    header_cell_style=Styles.PrimaryFlat,
    header_text_style=Styles.WhiteBold.patch(text_size=10.5),
    border_style=Styles.MutedThin,
)

table.set_style_cell_evenodd(
    even_color=Colors.Light,
    even_text_style=Styles.Dark.patch(text_size=10.0),
    odd_color=Colors.White,
    odd_text_style=Styles.Dark.patch(text_size=10.0),
)
table.set_style_cell_header(
    background_color=Colors.Primary,
    text_style=Styles.WhiteBold.patch(text_size=10.5),
)
table.set_style_cell(
    background_color=Colors.Light,
    text_style=Styles.PrimaryBold.patch(text_size=10.0),
    rows=[1, 2, 3, 4, 5, 6],
    columns=[0],
)

data = [
    ["サブパス", "ソースエントリーポイント", "主なエクスポートシンボル", "バンドル特性・ランタイム挙動"],
    ["zod (.) / zod/v4", "src/v4/classic/external.ts", "z, ZodType, ZodObject, toJSONSchema", "初回初期化時にデフォルト en() を登録"],
    ["zod/mini", "src/v4/mini/external.ts", "z, ZodMiniType, check, minLength", "副作用なし・Tree-Shaking 最適化"],
    ["zod/v4/core", "src/v4/core/index.ts", "$constructor, $ZodType, $ZodRegistry", "ロケール非依存の共通コアエンジン"],
    ["zod/locales", "src/v4/locales/index.ts", "en, ja, de, fr, es, zhCN (全50言語)", "遅延ロード対応エラーメッセージ辞書"],
    ["zod/compile", "src/compile.ts", "compile, withParser, CompileOptions", "グローバル JIT / AOT フックを有効化"],
    ["zod/v3", "src/v3/index.ts", "Zod v3 互換エクスポート群", "v3 から v4 への段階的マイグレーション"],
]

table.draw_flexible(
    xy=(4, 58),
    column_widths=[32, 42, 52, 50],
    row_heights=[8.0, 7.5, 7.5, 7.5, 7.5, 7.5, 7.5],
    data=data,
    align="top_left",
)

save()
インポートパス ソースファイル 主なエクスポート 推奨ユースケース
import { z } from "zod" packages/zod/src/index.ts ZodType, z.string(), z.object(), .parse(), .toJSONSchema() フル機能のメソッドチェーンとデフォルト英語ロケールを備えた標準アプリケーション開発。
import * as z from "zod/mini" packages/zod/src/mini/index.ts ZodMiniType, z.string(), z.check(), z.minLength(), z.parse() フロントエンドバンドルや Edge Worker など、厳格な Dead-Code Elimination（sideEffects: false）が求められる環境。
import * as core from "zod/v4/core" packages/zod/src/v4/core/index.ts $constructor, $ZodType, $ZodCheck, $ZodError, $ZodRegistry Classic と Mini の両方を受け入れるフレームワークアダプタや独自スキーマライブラリの構築。
import { ja } from "zod/locales" packages/zod/src/locales/index.ts 50 言語のロケールファクトリ（en(), ja(), de(), fr(), es(), ...） z.config(ja()) によるバリデーションエラーメッセージの多言語対応（i18n）。
import "zod/compile" packages/zod/src/compile.ts compile(schema), withParser(schema, fn) 高スループットが求められる検証パス向けの AOT / JIT JavaScript コード生成。
import * as z3 from "zod/v3" packages/zod/src/v3/index.ts 旧 Zod v3 クラス・メソッド互換レイヤー 大規模モノレポにおける Zod v3 から Zod v4 への段階的移行。

moduleカタログモジュール索引#

本 API リファレンスカタログは以下の 5 つのドメインモジュールで構成されています。

モジュールページ 対象スコープと網羅範囲 主要クラス・関数
01. プリミティブ・型変換・文字列フォーマット スカラープリミティブ、数値/BigInt ビット幅フォーマット、z.coerce、トップレベル文字列フォーマット、z.iso.* 日時型 z.string, z.number, z.int, z.bigint, z.boolean, z.stringbool, z.date, z.literal, z.enum, z.templateLiteral, z.coerce, z.email, z.uuid, z.url, z.jwt, z.ipv4, z.ipv6, z.iso
02. オブジェクト・コレクション・Union・ラッパー合成 オブジェクトスキーマ、コレクションコンテナ、Union / Intersection 合成、オプショナル・デフォルト等のラッパー型 ZodObject, z.object, z.strictObject, z.looseObject, ZodArray, ZodTuple, ZodRecord, ZodMap, ZodSet, ZodUnion, ZodXor, ZodDiscriminatedUnion, ZodIntersection, ZodOptional, ZodNullable, ZodDefault, ZodPrefault, ZodCatch, ZodReadonly, z.lazy, z.custom, ZodFunction, ZodPromise
03. チェック・Refinement・Transform・双方向 Codec 合成可能な $ZodCheck バリデータ、カスタム Refinement、単方向パイプライン、双方向 ZodCodec z.check, schema.check, schema.refine, schema.superRefine, schema.overwrite, z.transform, z.pipe, z.codec, z.invertCodec, z.preprocess, z.stringbool, 文字列/数値/サイズ各種チェック関数
04. パース・エラー整形・レジストリ・JSON Schema 順方向/逆方向パース実行（parse/decode/encode）、エラー整形ユーティリティ、メタデータレジストリ、JSON Schema 変換 z.parse, z.safeParse, z.encode, z.decode, ZodError, $ZodIssue, z.treeifyError, z.prettifyError, z.flattenError, z.registry, z.globalRegistry, schema.meta, z.toJSONSchema, z.fromJSONSchema, z.config, z.locales
05. zod/mini・zod/v4/core エンジン・AOT コンパイラ 関数型 ZodMiniType ラッパー、$constructor プロトタイプ基盤、Standard Schema v1 統合、AOT コード生成 ZodMiniType, core.$constructor, core.$ZodType, core.$ZodCheck, ~standard, z.compile, z.withParser, ZodCompileAsyncError, ZodCompileUnsupportedError, z.infer, z.input, z.output

ポータル間クロスリンク#

interfaceZodType<Output, Input, Internals>#

クラシック zod エントリーポイントのすべてのスキーマは ZodType<Output, Input, Internals> を継承します。ZodType は core.$ZodType を拡張し、プロトタイプ上にメソッドチェーン用のインスタンスメソッドを提供します。

export interface ZodType<
  out Output = unknown,
  out Input = unknown,
  out Internals extends core.$ZodTypeInternals<Output, Input> = core.$ZodTypeInternals<Output, Input>,
> extends core.$ZodType<Output, Input, Internals>
プロパティ / メソッド群 シグネチャ 説明
.def / .type Internals["def"] / Internals["def"]["type"] 不変のスキーマ定義オブジェクトおよび種別識別子文字列（"string", "object", "union" 等）を参照します。
["~standard"] ZodStandardSchemaWithJSON<this> Standard Schema v1 仕様（validate, vendor: "zod", jsonSchema.input/output）を実装します。
.parse(data, params?) (data: unknown, params?: ParseContext) => Output 順方向（forward）で同期バリデーションを実行し、Output 型の値を返すか ZodError をスローします。
.safeParse(data, params?) (data: unknown, params?: ParseContext) => ZodSafeParseResult<Output> 例外をスローせず { success: true, data: Output } | { success: false, error: ZodError } を返します。
.parseAsync(data, params?) (data: unknown, params?: ParseContext) => Promise<Output> 非同期 Refinement や非同期 Transform を含むスキーマを非同期バリデーションします。
.safeParseAsync(data, params?) / .spa (data: unknown, params?: ParseContext) => Promise<ZodSafeParseResult<Output>> 例外をスローしない非同期パース（schema.spa は直接のエイリアス）。
.encode(data, params?) / .decode(data, params?) encode(Output): Input / decode(Input): Output 双方向 Codec 実行。.encode() はパイプや Codec を逆方向（direction: "backward"）に実行します。
.check(...checks) / .with(...checks) (...checks: ($ZodCheck<Output> | CheckFn<Output>)[]) => this スキーマをクローンし、1 つ以上のバリデーションまたは値変換チェックを追加します。
.refine(fn, params?) / .superRefine(fn, params?) カスタム述語 / 複数 Issue 追加検証 スキーマのチェックパイプラインに同期・非同期のカスタム検証ロジックを追加します。
.optional() / .nullable() / .nullish() ラッパーコンビネータ this を ZodOptional、ZodNullable、または ZodOptional<ZodNullable<this>> でラップします。
.default(val) / .prefault(val) / .catch(val) フォールバック値ラッパー undefined 短絡評価（default）、入力側デフォルト注入（prefault）、パース失敗時リカバリ（catch）。
.pipe(target) / .transform(fn) ZodPipe<this, T> this の出力を target スキーマまたは ZodTransform ステージへ連結します。
.describe(text) / .meta(data?) / .register(reg, meta?) メタデータ & レジストリ登録 z.globalRegistry または任意の $ZodRegistry に説明文や JSON Schema 用メタデータを登録します。
.toJSONSchema(params?) (params?: ToJSONSchemaParams) => JSONSchema スキーマを Draft-2020-12 / Draft-07 / Draft-04 / OpenAPI 3.0 の JSON Schema に直接変換します。
.brand<T, Dir?>() <T extends PropertyKey, Dir = "out">() => $ZodBranded<this, T, Dir> 出力型・入力型・または双方向にコンパイル時の公称ブランド型（$brand）を付与します。

typeSchemaParams とエラーカスタマイズ#

Zod v4 のすべてのスキーマコンストラクタおよびチェック関数は、Zod v3 の invalid_type_error / required_error を統合した単一の params 引数（string | { error?: string | $ZodErrorMap, ... }）を受け取ります。

パラメータ項目 型 適用範囲 挙動
params（文字列省略形） string 全コンストラクタ・チェック関数 util.normalizeParams() により自動的に { error: params } に正規化されます。
error string | $ZodErrorMap<Issue> 全コンストラクタ・チェック関数 固定エラー文字列、または Issue ごとのコールバック (iss) => string | { message: string } | undefined。undefined を返すと有効なロケールにフォールバックします。
abort boolean .refine(), .superRefine(), 各種チェック true の場合、このチェックでエラーが発生した時点で後続チェックの実行を打ち切ります。
path PropertyKey[] .refine(), z.custom(), 各種チェック 生成される Issue に相対プロパティパスを追加します。
when (payload: ParsePayload) => boolean .refine(), $ZodCheck 指定したペイロードに対してチェックを実行するかどうかを判定する事前ガード関数。 
import { z } from "zod";

// 1. 文字列省略形によるエラーメッセージ指定
const NameSchema = z.string("名前は文字列で指定してください").min(2, "2文字以上で入力してください");

// 2. `iss.input` を検査する動的エラーマップ関数
const AgeSchema = z.int({
  error: (iss) =>
    iss.input === undefined ? "年齢は必須です" : `整数の年齢が必要ですが ${typeof iss.input} が渡されました`,
});