Zod Core

이 하위 패키지는 Zod와 Zod Mini에서 사용하는 코어 클래스와 유틸리티를 내보냅니다. 직접 사용하기 위한 패키지가 아니라 다른 패키지가 확장하도록 설계되었습니다. 다음 항목을 구현합니다.

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

// the base class for all Zod schemas
z.$ZodType;

// subclasses of $ZodType that implement common parsers
z.$ZodString
z.$ZodObject
z.$ZodArray
// ...

// the base class for all Zod checks
z.$ZodCheck;

// subclasses of $ZodCheck that implement common checks
z.$ZodCheckMinLength
z.$ZodCheckMaxLength

// the base class for all Zod errors
z.$ZodError;

// issue formats (types only)
{} as z.$ZodIssue;

// utils
z.util.isValidJWT(...);

스키마

모든 Zod 스키마의 기본 클래스는 $ZodType입니다. 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 and $ZodPreprocess extend this
  | $ZodSuccess
  | $ZodCatch
  | $ZodFile;

상속 다이어그램

다음은 코어 스키마 클래스의 전체 상속 다이어그램입니다.

- $ZodType
    - $ZodString
        - $ZodStringFormat
            - $ZodGUID
            - $ZodUUID
            - $ZodEmail
            - $ZodURL
            - $ZodEmoji
            - $ZodNanoID
            - $ZodCUID
            - $ZodCUID2
            - $ZodULID
            - $ZodXID
            - $ZodKSUID
            - $ZodISODateTime
            - $ZodISODate
            - $ZodISOTime
            - $ZodISODuration
            - $ZodIPv4
            - $ZodIPv6
            - $ZodCIDRv4
            - $ZodCIDRv6
            - $ZodBase64
            - $ZodBase64URL
            - $ZodE164
            - $ZodJWT
    - $ZodNumber
        - $ZodNumberFormat
    - $ZodBigInt
        - $ZodBigIntFormat
    - $ZodBoolean
    - $ZodSymbol
    - $ZodUndefined
    - $ZodNull
    - $ZodAny
    - $ZodUnknown
    - $ZodNever
    - $ZodVoid
    - $ZodDate
    - $ZodArray
    - $ZodObject
    - $ZodUnion
        - $ZodDiscriminatedUnion
    - $ZodIntersection
    - $ZodTuple
    - $ZodRecord
    - $ZodMap
    - $ZodSet
    - $ZodEnum
    - $ZodLiteral
    - $ZodFile
    - $ZodTransform
    - $ZodOptional
    - $ZodNullable
    - $ZodDefault
    - $ZodPrefault
    - $ZodNonOptional
    - $ZodSuccess
    - $ZodCatch
    - $ZodNaN
    - $ZodPipe
        - $ZodCodec
        - $ZodPreprocess
    - $ZodReadonly
    - $ZodTemplateLiteral
    - $ZodCustom

내부 구조

모든 zod/v4/core 하위 클래스에는 _zod라는 속성 하나만 있습니다. 이 속성은 스키마의 내부 정보를 담은 객체입니다. zod/v4/core는 최대한 확장 가능하면서 특정 사용 방식을 강요하지 않도록 설계되었습니다. 따라서 다른 라이브러리는 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

파싱

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");

검사

모든 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에는 존재하지 않습니다.

// as a type
z.email().parse("user@example.com");

// as a check
z.string().check(z.email()).parse("user@example.com")

오류

Zod에서 모든 오류의 기본 클래스는 $ZodError입니다.

성능상의 이유로 $ZodError는 내장 Error 클래스를 확장하지 않습니다! 따라서 instanceof Error를 사용하면 false를 반환합니다.

• zod 패키지는 $ZodError를 확장하고 몇 가지 편의 메서드를 추가한 ZodError 클래스를 구현합니다.
• zod/mini 하위 패키지는 $ZodError를 직접 사용합니다.

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

이슈

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;

각 타입의 자세한 내용은 구현을 참조하세요.