Zod Core

このサブパッケージは、Zod と Zod Mini で使用されるコアクラスとユーティリティをエクスポートします。直接使用することを意図したものではなく、他のパッケージによって拡張されるように設計されています。これは以下を実装します：

import * as z from "zod/v4/core";
 
// すべての Zod スキーマの基底クラス
z.$ZodType;
 
// 一般的なパーサーを実装する $ZodType のサブクラス
z.$ZodString
z.$ZodObject
z.$ZodArray
// ...
 
// すべての Zod チェックの基底クラス
z.$ZodCheck;
 
// 一般的なチェックを実装する $ZodCheck のサブクラス
z.$ZodCheckMinLength
z.$ZodCheckMaxLength
 
// すべての Zod エラーの基底クラス
z.$ZodError;
 
// イシュー (問題) の形式 (型のみ)
{} as z.$ZodIssue;
 
// ユーティリティ
z.util.isValidJWT(...);

スキーマ (Schemas)

すべての Zod スキーマの基底クラスは $ZodType です。これは2つのジェネリックパラメータ Output と Input を受け入れます。

export class $ZodType<Output = unknown, Input = unknown> {
  _zod: { /* internals */}
}

zod/v4/core は、いくつかの一般的なパーサーを実装する多数のサブクラスをエクスポートします。すべてのファーストパーティサブクラスのユニオンは z.$ZodTypes としてエクスポートされます。

export type $ZodTypes =
  | $ZodString
  | $ZodNumber
  | $ZodBigInt
  | $ZodBoolean
  | $ZodDate
  | $ZodSymbol
  | $ZodUndefined
  | $ZodNullable
  | $ZodNull
  | $ZodAny
  | $ZodUnknown
  | $ZodNever
  | $ZodVoid
  | $ZodArray
  | $ZodObject
  | $ZodUnion // $ZodDiscriminatedUnion extends this
  | $ZodIntersection
  | $ZodTuple
  | $ZodRecord
  | $ZodMap
  | $ZodSet
  | $ZodLiteral
  | $ZodEnum
  | $ZodPromise
  | $ZodLazy
  | $ZodOptional
  | $ZodDefault
  | $ZodTemplateLiteral
  | $ZodCustom
  | $ZodTransform
  | $ZodNonOptional
  | $ZodReadonly
  | $ZodNaN
  | $ZodPipe // $ZodCodec extends this
  | $ZodSuccess
  | $ZodCatch
  | $ZodFile;

zod/v4/core のすべてのサブクラスには、単一のプロパティ _zod のみが含まれています。このプロパティは、スキーマの 内部 (internals) を含むオブジェクトです。目的は、zod/v4/core を可能な限り拡張可能で、意見を持たない (unopinionated) ものにすることです。他のライブラリは、zod/v4/core がインターフェースを混乱させることなく、これらのクラスの上に「独自の Zod」を構築できます。これらのクラスを拡張する方法の例については、zod と zod/mini の実装を参照してください。

_zod 内部プロパティには、いくつかの注目すべきプロパティが含まれています。

.def — スキーマの定義：これは、インスタンスを作成するためにクラスのコンストラクターに渡すオブジェクトです。スキーマを完全に記述し、JSON シリアル化可能です。
- .def.type — スキーマのタイプを表す文字列。例："string", "object", "array" など。
- .def.checks — 解析後にスキーマによって実行される チェック の配列。
.input — スキーマの 推論された入力タイプ を「格納」する仮想プロパティ。
.output — スキーマの 推論された出力タイプ を「格納」する仮想プロパティ。
.run() — スキーマの内部パーサー実装。

Zod スキーマを走査する必要があるツール（たとえば、コードジェネレーター）を実装している場合は、任意のスキーマを $ZodTypes にキャストし、def プロパティを使用してこれらのクラスを区別できます。

export function walk(_schema: z.$ZodType) {
  const schema = _schema as z.$ZodTypes;
  const def = schema._zod.def;
  switch (def.type) {
    case "string": {
      // ...
      break;
    }
    case "object": {
      // ...
      break;
    }
  }
}

$ZodString のサブクラスには、さまざまな 文字列形式 を実装するものがいくつかあります。これらは z.$ZodStringFormatTypes としてエクスポートされます。

export type $ZodStringFormatTypes =
  | $ZodGUID
  | $ZodUUID
  | $ZodEmail
  | $ZodURL
  | $ZodEmoji
  | $ZodNanoID
  | $ZodCUID
  | $ZodCUID2
  | $ZodULID
  | $ZodXID
  | $ZodKSUID
  | $ZodISODateTime
  | $ZodISODate
  | $ZodISOTime
  | $ZodISODuration
  | $ZodIPv4
  | $ZodIPv6
  | $ZodCIDRv4
  | $ZodCIDRv6
  | $ZodBase64
  | $ZodBase64URL
  | $ZodE164
  | $ZodJWT

パース (Parsing)

Zod Core スキーマクラスにはメソッドがないため、データを解析するためのトップレベル関数があります。

import * as z from "zod/v4/core";
 
const schema = new z.$ZodString({ type: "string" });
z.parse(schema, "hello");
z.safeParse(schema, "hello");
await z.parseAsync(schema, "hello");
await z.safeParseAsync(schema, "hello");

チェック (Checks)

すべての Zod スキーマには、チェック の配列が含まれています。これらは、推論された型に 影響を与えない 解析後の詳細化（および場合によっては変更）を実行します。

const schema = z.string().check(z.email()).check(z.min(5));
// => $ZodString
 
schema._zod.def.checks;
// => [$ZodCheckEmail, $ZodCheckMinLength]

すべての Zod チェックの基底クラスは $ZodCheck です。これは単一のジェネリックパラメータ T を受け入れます。

export class $ZodCheck<in T = unknown> {
  _zod: { /* internals */}
}

_zod 内部プロパティには、いくつかの注目すべきプロパティが含まれています。

.def — チェックの定義：これは、チェックを作成するためにクラスのコンストラクターに渡すオブジェクトです。チェックを完全に記述し、JSON シリアル化可能です。
- .def.check — チェックのタイプを表す文字列。例："min_length", "less_than", "string_format" など。
.check() — チェックの検証ロジックが含まれています。

zod/v4/core は、いくつかの一般的な詳細化を実行する多数のサブクラスをエクスポートします。すべてのファーストパーティサブクラスは、z.$ZodChecks と呼ばれるユニオンとしてエクスポートされます。

export type $ZodChecks =
  | $ZodCheckLessThan
  | $ZodCheckGreaterThan
  | $ZodCheckMultipleOf
  | $ZodCheckNumberFormat
  | $ZodCheckBigIntFormat
  | $ZodCheckMaxSize
  | $ZodCheckMinSize
  | $ZodCheckSizeEquals
  | $ZodCheckMaxLength
  | $ZodCheckMinLength
  | $ZodCheckLengthEquals
  | $ZodCheckProperty
  | $ZodCheckMimeType
  | $ZodCheckOverwrite
  | $ZodCheckStringFormat

._zod.def.check プロパティを使用して、これらのクラスを区別できます。

const check = {} as z.$ZodChecks;
const def = check._zod.def;
 
switch (def.check) {
  case "less_than":
  case "greater_than":
    // ...
    break;
}

スキーマタイプと同様に、さまざまな 文字列形式 を実装する $ZodCheckStringFormat のサブクラスがいくつかあります。

export type $ZodStringFormatChecks =
  | $ZodCheckRegex
  | $ZodCheckLowerCase
  | $ZodCheckUpperCase
  | $ZodCheckIncludes
  | $ZodCheckStartsWith
  | $ZodCheckEndsWith
  | $ZodGUID
  | $ZodUUID
  | $ZodEmail
  | $ZodURL
  | $ZodEmoji
  | $ZodNanoID
  | $ZodCUID
  | $ZodCUID2
  | $ZodULID
  | $ZodXID
  | $ZodKSUID
  | $ZodISODateTime
  | $ZodISODate
  | $ZodISOTime
  | $ZodISODuration
  | $ZodIPv4
  | $ZodIPv6
  | $ZodCIDRv4
  | $ZodCIDRv6
  | $ZodBase64
  | $ZodBase64URL
  | $ZodE164
  | $ZodJWT;

異なる文字列形式チェックを区別するには、ネストされた switch を使用します。

const check = {} as z.$ZodChecks;
const def = check._zod.def;
 
switch (def.check) {
  case "less_than":
  case "greater_than":
  // ...
  case "string_format":
    {
      const formatCheck = check as z.$ZodStringFormatChecks;
      const formatCheckDef = formatCheck._zod.def;
 
      switch (formatCheckDef.format) {
        case "email":
        case "url":
          // do stuff
      }
    }
    break;
}

これらの文字列形式の チェック の一部が、上記の文字列形式の タイプ と重複していることに気付くでしょう。これは、これらのクラスが $ZodCheck と $ZodType の両方のインターフェースを実装しているためです。つまり、チェックとしてもタイプとしても使用できます。これらの場合、解析中に ._zod.parse（スキーマパーサー）と ._zod.check（チェック検証）の両方が実行されます。実際には、インスタンスは独自の checks 配列の前に追加されます（ただし、._zod.def.checks には実際には存在しません）。

// 型として
z.email().parse("[email protected]");
 
// チェックとして
z.string().check(z.email()).parse("[email protected]")

エラー (Errors)

Zod のすべてのエラーの基底クラスは $ZodError です。

パフォーマンス上の理由から、$ZodError は組み込みの Error クラスを継承 しません！したがって、instanceof Error を使用すると false が返されます。

zod パッケージは、いくつかの追加の便利なメソッドを持つ ZodError と呼ばれる $ZodError のサブクラスを実装しています。
zod/mini サブパッケージは $ZodError を直接使用します。

export class $ZodError<T = unknown> implements Error {
 public issues: $ZodIssue[];
}

イシュー (Issues)

issues プロパティは、$ZodIssue オブジェクトの配列に対応します。すべてのイシューは z.$ZodIssueBase インターフェースを拡張します。

export interface $ZodIssueBase {
  readonly code?: string;
  readonly input?: unknown;
  readonly path: PropertyKey[];
  readonly message: string;
}

Zod は、以下のイシューサブタイプを定義しています。

export type $ZodIssue =
  | $ZodIssueInvalidType
  | $ZodIssueTooBig
  | $ZodIssueTooSmall
  | $ZodIssueInvalidStringFormat
  | $ZodIssueNotMultipleOf
  | $ZodIssueUnrecognizedKeys
  | $ZodIssueInvalidUnion
  | $ZodIssueInvalidKey
  | $ZodIssueInvalidElement
  | $ZodIssueInvalidValue
  | $ZodIssueCustom;

各タイプの詳細については、実装を参照してください。

スキーマ (Schemas)

内部 (Internals)

パース (Parsing)

チェック (Checks)

エラー (Errors)

イシュー (Issues)

On this page

Zod Core

スキーマ (Schemas)

継承図

内部 (Internals)

パース (Parsing)

チェック (Checks)

エラー (Errors)

イシュー (Issues)

On this page