ライブラリ作成者向け (For library authors)

// package.json
{
  "peerDependencies": {
    "zod": "^3.25.0 || ^4.0.0"
  }
}

このページは、主に Zod 上にツールを構築している ライブラリ作成者 向けです。

Zod に依存する必要がありますか？ (Do I need to depend on Zod?)

まず最初に、Zod に依存する必要があるかどうかを確認してください。

ブラックボックス検証を実行するためにユーザー定義スキーマを受け入れるライブラリを構築している場合は、Zod と具体的に統合する必要はないかもしれません。代わりに Standard Schema を検討してください。これは、Zod を含む TypeScript エコシステムの最も人気のある検証ライブラリによって実装された共有インターフェースです（完全なリスト を参照）。

ユーザー定義スキーマを受け入れ、それらを「ブラックボックス」バリデーターのように扱う場合、この仕様はうまく機能します。準拠したライブラリがあれば、推論された入力/出力タイプを抽出し、入力を検証し、標準化されたエラーを取得できます。

Zod 固有の機能が必要な場合は、読み続けてください。

ピア依存関係の設定方法 (How to configure peer dependencies?)

Zod 上に構築されたライブラリはすべて、"peerDependencies" に "zod" を含める必要があります。これにより、ユーザーは「独自の Zod を持ち込む」ことができます。

// package.json
{
  // ...
  "peerDependencies": {
    "zod": "^3.25.0 || ^4.0.0" // the "zod/v4" subpath was added in 3.25.0
  }
}

開発中は、独自のピア依存関係要件を満たす必要があります。そのためには、"devDependencies" にも "zod" を追加します。

// package.json
{
  "peerDependencies": {
    "zod": "^3.25.0 || ^4.0.0"
  },
  "devDependencies": {
    // generally, you should develop against the latest version of Zod
    "zod": "^3.25.0 || ^4.0.0"
  }
}

Zod 4 のサポート方法 (How to support Zod 4?)

Zod 4 をサポートするには、"zod" ピア依存関係の最小バージョンを ^3.25.0 || ^4.0.0 に更新します。

// package.json
{
  // ...
  "peerDependencies": {
    "zod": "^3.25.0 || ^4.0.0"
  }
}

v3.25.0 以降、Zod 4 コアパッケージは "zod/v4/core" サブパスで利用可能です。このバージョン管理アプローチの完全なコンテキストについては、Versioning in Zod 4 の記事をお読みください。

import * as z4 from "zod/v4/core";

これらのサブパスからのみインポートしてください。それらをそれぞれの Zod バージョンへの「パーマリンク」と考えてください。これらは永久に利用可能なままになります。

• "zod/v3" for Zod 3 ✅
• "zod/v4/core" for the Zod 4 Core package ✅

通常、他のパスからインポートすべきではありません。Zod Core ライブラリは、Zod 4 Classic と Zod 4 Mini の両方を支える共有ライブラリです。どちらか一方に固有の機能を実装することは、一般的に悪い考えです。これらのサブパスからインポートしないでください：

• "zod" — ❌ 3.x リリースでは、これは Zod 3 をエクスポートします。4.x リリースでは、これは Zod 4 をエクスポートします。代わりにパーマリンクを使用してください。
• "zod/v4" および "zod/v4/mini" — ❌ これらのサブパスは、それぞれ Zod 4 Classic と Mini のホームです。ライブラリを Zod と Zod Mini の両方で動作させたい場合は、"zod/v4/core" で定義された基本クラスに対して構築する必要があります。"zod/v4" モジュールからクラスを参照すると、ライブラリは Zod Mini で動作せず、その逆も同様です。これは強く推奨されません。代わりに、Zod Classic と Zod Mini によって拡張される $ 接頭辞付きのサブクラスをエクスポートする "zod/v4/core" を使用してください。classic と mini サブクラスの内部は同一です。それらは実装するヘルパーメソッドのみが異なります。

新しいメジャーバージョンを公開する必要がありますか？ (Do I need to publish a new major version?)

いいえ、Zod 4 をサポートするためにライブラリの新しいメジャーバージョンを公開する必要はありません（Zod 3 のサポートを終了する場合を除く、これは推奨されません）。

ピア依存関係を ^3.25.0 にバンプする必要があるため、ユーザーは npm upgrade zod を行う必要があります。しかし、[email protected] と [email protected] の間で Zod 3 に破壊的な変更はありませんでした。実際、コードの変更はまったくありませんでした。ユーザー側でのコード変更が必要になるため、これは破壊的な変更には当たらないと考えています。新しいメジャーバージョンの公開は推奨しません。

Zod 3 と Zod 4 を同時にサポートする方法 (How to support Zod 3 and Zod 4 simultaneously?)

v3.25.0 以降、パッケージにはそれぞれのサブパスに Zod 3 と Zod 4 の両方のコピーが含まれています。これにより、両方のバージョンを同時に簡単にサポートできます。

import * as z3 from "zod/v3";
import * as z4 from "zod/v4/core";
 
type Schema = z3.ZodTypeAny | z4.$ZodType;
 
function acceptUserSchema(schema: z3.ZodTypeAny | z4.$ZodType) {
  // ...
}

実行時に Zod 3 と Zod 4 のスキーマを区別するには、"_zod" プロパティを確認します。このプロパティは Zod 4 スキーマでのみ定義されています。

import type * as z3 from "zod/v3";
import type * as z4 from "zod/v4/core";
 
declare const schema: z3.ZodTypeAny | z4.$ZodType;
 
if ("_zod" in schema) {
  schema._zod.def; // Zod 4 schema
} else {
  schema._def; // Zod 3 schema
}

Zod と Zod Mini を同時にサポートする方法 (How to support Zod and Zod Mini simultaneously?)

ライブラリコードは "zod/v4/core" からのみインポートする必要があります。このサブパッケージは、Zod と Zod Mini 間で共有されるインターフェース、クラス、ユーティリティを定義します。

// library code
import * as z4 from "zod/v4/core";
 
export function acceptObjectSchema<T extends z4.$ZodObject>(schema: T){
  // parse data
  z4.parse(schema, { /* somedata */});
  // inspect internals
  schema._zod.def.shape;
}

共有ベースインターフェースに対して構築することで、両方のサブパッケージを同時に確実にサポートできます。この関数は、Zod と Zod Mini の両方のスキーマを受け入れることができます。

// user code
import { acceptObjectSchema } from "your-library";
 
// Zod 4
import * as z from "zod";
acceptObjectSchema(z.object({ name: z.string() }));
 
// Zod 4 Mini
import * as zm from "zod/mini";
acceptObjectSchema(zm.object({ name: zm.string() }))

コアサブライブラリの内容の詳細については、Zod Core ページを参照してください。

ユーザー定義スキーマを受け入れる方法 (How to accept user-defined schemas?)

ユーザー定義スキーマを受け入れることは、Zod 上に構築されたライブラリにとって基本的な操作です。このセクションでは、そのためのベストプラクティスについて説明します。

最初に、次のような Zod スキーマを受け入れる関数を作成したくなるかもしれません。

import * as z4 from "zod/v4/core";
 
function inferSchema<T>(schema: z4.$ZodType<T>) {
  return schema;
}

このアプローチは正しくなく、TypeScript が引数を適切に推論する能力を制限します。何を渡しても、schema の型は $ZodType のインスタンスになります。

inferSchema(z.string());
// => $ZodType<string>

このアプローチでは、型情報、つまり入力が実際には どのサブクラス （この場合は ZodString）であるかという情報が失われます。つまり、inferSchema の結果に対して .min() などの文字列固有のメソッドを呼び出すことはできません。代わりに、ジェネリックパラメータはコア Zod スキーマインターフェースを拡張する必要があります。

function inferSchema<T extends z4.$ZodType>(schema: T) {
  return schema;
}
 
inferSchema(z.string());
// => ZodString ✅

入力スキーマを特定のサブクラスに制約するには：

 
import * as z4 from "zod/v4/core";
 
// only accepts object schemas
function inferSchema<T>(schema: z4.$ZodObject) {
  return schema;
}

入力スキーマの推論された出力タイプを制約するには：

 
import * as z4 from "zod/v4/core";
 
// only accepts string schemas
function inferSchema<T extends z4.$ZodType<string>>(schema: T) {
  return schema;
}
 
inferSchema(z.string()); // ✅ 
 
inferSchema(z.number()); 
// ❌ The types of '_zod.output' are incompatible between these types. 
// // Type 'number' is not assignable to type 'string'

スキーマでデータを解析するには、トップレベルの z4.parse/z4.safeParse/z4.parseAsync/z4.safeParseAsync 関数を使用します。z4.$ZodType サブクラスにはメソッドがありません。通常の解析メソッドは Zod と Zod Mini によって実装されていますが、Zod Core では利用できません。

function parseData<T extends z4.$ZodType>(data: unknown, schema: T): z4.output<T> {
  return z.parse(schema, data);
}
 
parseData("sup", z.string());
// => string