Zod Core

Este subpaquete exporta las clases y utilidades centrales que consumen Zod y Zod Mini. No está pensado para ser usado directamente; en su lugar, está diseñado para ser extendido por otros paquetes. Implementa:

import * as z from "zod/v4/core";
 
// la clase base para todos los esquemas de Zod
z.$ZodType;
 
// subclases de $ZodType que implementan analizadores comunes
z.$ZodString
z.$ZodObject
z.$ZodArray
// ...
 
// la clase base para todas las comprobaciones de Zod
z.$ZodCheck;
 
// subclases de $ZodCheck que implementan comprobaciones comunes
z.$ZodCheckMinLength
z.$ZodCheckMaxLength
 
// la clase base para todos los errores de Zod
z.$ZodError;
 
// formatos de problemas (solo tipos)
{} as z.$ZodIssue;
 
// utilidades
z.util.isValidJWT(...);

Esquemas

La clase base para todos los esquemas de Zod es $ZodType. Acepta dos parámetros genéricos: Output e Input.

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

zod/v4/core exporta una serie de subclases que implementan algunos analizadores comunes. Una unión de todas las subclases de origen se exporta como z.$ZodTypes.

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

Internos

Todas las subclases de zod/v4/core solo contienen una única propiedad: _zod. Esta propiedad es un objeto que contiene los internos del esquema. El objetivo es hacer que zod/v4/core sea tan extensible y no opinado como sea posible. Otras bibliotecas pueden "construir su propio Zod" sobre estas clases sin que zod/v4/core abarrote la interfaz. Consulta las implementaciones de zod y zod/mini para ver ejemplos de cómo extender estas clases.

La propiedad interna _zod contiene algunas propiedades notables:

.def — La definición del esquema: este es el objeto que pasas al constructor de la clase para crear una instancia. Describe completamente el esquema y es serializable a JSON.
- .def.type — Una cadena que representa el tipo del esquema, por ejemplo, "string", "object", "array", etc.
- .def.checks — Una matriz de comprobaciones que son ejecutadas por el esquema después del análisis.
.input — Una propiedad virtual que "almacena" el tipo de entrada inferido del esquema.
.output — Una propiedad virtual que "almacena" el tipo de salida inferido del esquema.
.run() — La implementación del analizador interno del esquema.

Si estás implementando una herramienta (digamos, un generador de código) que debe recorrer esquemas de Zod, puedes convertir cualquier esquema a $ZodTypes y usar la propiedad def para discriminar entre estas clases.

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;
    }
  }
}

Hay una serie de subclases de $ZodString que implementan varios formatos de cadena. Estos se exportan como 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

Análisis (Parsing)

Como las clases de esquema de Zod Core no tienen métodos, hay funciones de nivel superior para analizar datos.

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

Comprobaciones (Checks)

Cada esquema de Zod contiene una matriz de comprobaciones. Estas realizan refinamientos post-análisis (y ocasionalmente mutaciones) que no afectan el tipo inferido.

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

La clase base para todas las comprobaciones de Zod es $ZodCheck. Acepta un único parámetro genérico T.

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

La propiedad interna _zod contiene algunas propiedades notables:

.def — La definición de la comprobación: este es el objeto que pasas al constructor de la clase para crear la comprobación. Describe completamente la comprobación y es serializable a JSON.
- .def.check — Una cadena que representa el tipo de la comprobación, por ejemplo, "min_length", "less_than", "string_format", etc.
.check() — Contiene la lógica de validación de la comprobación.

zod/v4/core exporta una serie de subclases que realizan algunos refinamientos comunes. Todas las subclases de origen se exportan como una unión llamada z.$ZodChecks.

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

Puedes usar la propiedad ._zod.def.check para discriminar entre estas clases.

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

Al igual que con los tipos de esquema, hay una serie de subclases de $ZodCheckStringFormat que implementan varios formatos de cadena.

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;

Usa un switch anidado para discriminar entre las diferentes comprobaciones de formato de cadena.

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":
          // hacer cosas
      }
    }
    break;
}

Notarás que algunas de estas comprobaciones de formato de cadena se superponen con los tipos de formato de cadena anteriores. Esto se debe a que estas clases implementan tanto las interfaces $ZodCheck como $ZodType. Es decir, se pueden usar como una comprobación o un tipo. En estos casos, tanto ._zod.parse (el analizador del esquema) como ._zod.check (la validación de la comprobación) se ejecutan durante el análisis. En efecto, la instancia se antepone a su propia matriz checks (aunque en realidad no existirá en ._zod.def.checks).

// como un tipo
z.email().parse("[email protected]");
 
// como una comprobación
z.string().check(z.email()).parse("[email protected]")

Errores

La clase base para todos los errores en Zod es $ZodError.

Por razones de rendimiento, $ZodError no extiende la clase Error incorporada. Por lo tanto, usar instanceof Error devolverá false.

El paquete zod implementa una subclase de $ZodError llamada ZodError con algunos métodos de conveniencia adicionales.
El subpaquete zod/mini usa directamente $ZodError

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

Problemas (Issues)

La propiedad issues corresponde a una matriz de objetos $ZodIssue. Todos los problemas extienden la interfaz z.$ZodIssueBase.

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

Zod define los siguientes subtipos de problemas:

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

Para obtener detalles sobre cada tipo, consulta la implementación.