Zod Schema

Esquema Zod (Zod Schema)

Use esta capacidad siempre que un cambio involucre a Zod — ya sea que se esté escribiendo un esquema, colocando un análisis, decodificando una carga útil o manejando un error. Es propietaria de la capa de esquema: la forma, la llamada de análisis, el tipo que esa forma produce, el error que genera y el códec que transporta datos entre un formato de cable y un modelo de dominio.

No es propietaria de cuatro preguntas vecinas, cada una perteneciente a su propia capacidad:

• Si una entrada no es confiable y, por lo tanto, debe verificarse — un criterio de la capacidad de seguridad de la aplicación. Esta habilidad asume que ese criterio ya se ha tomado y explica cómo Zod lo ejecuta.
• Que existe un gancho para que el análisis se ubique dentro — un manejador de ruta, una función de servidor, una acción de formulario — un hecho de la capacidad del framework.
• Cuándo se vuelve a obtener, almacenar en caché o invalidar una carga útil obtenida — una preocupación de la capacidad de estado del servidor. Esta habilidad solo coloca un análisis dentro de la función de consulta de la que es propietaria.
• Cómo un componente recibe, renderiza y se prueba contra el resultado analizado — una preocupación de la capacidad de desarrollo de componentes.

Cuando una regla aquí tiene una contraparte en alguna de esas, esta habilidad expresa el mecanismo de Zod y nombra al otro como propietario.

Disciplina de versiones. Esta habilidad está escrita para Zod 4 únicamente. Zod 3 está fuera del alcance como línea compatible: no hay ruta de migración, ni guía de zod/v3, ni regla expresada en su forma de Zod 3. El único lugar donde aparece Zod 3 es como una señal de detección — una lista de modismos obsoletos, para que el código desactualizado pueda ser reconocido y reemplazado con la forma actual. Esa es una regla de Zod 4 sobre un código base de Zod 4, no una cobertura de Zod 3. El límite importa más de lo habitual aquí, porque las respuestas de Zod 3 todavía superan a las de Zod 4 en tutoriales, publicaciones de foros y recuperación del modelo — y la mayoría de los modismos de Zod 3 aún se compilan contra una instalación de Zod 4, por lo que "funciona" no es evidencia de que una regla esté actualizada. Zod 4 también se mueve dentro de su propio major: z.xor, z.invertCodec y el parámetro de dirección .brand llegaron después de 4.0. Cada declaración sensible a la versión aquí nombra contra qué fue verificada, y donde se sabe que una superficie se mueve, la regla es una consulta — consulte la documentación de la versión instalada en https://zod.dev/ — en lugar de un nombre de API congelado. Trate cualquier afirmación no versionada sobre una API de Zod, en esta habilidad o en cualquier otro lugar, como sospechosa.

Verificado contra [email protected], publicado el 2026-05-04 — https://zod.dev/ — con TypeScript 5.5+ y strict: true como requisitos previos indicados. Cada archivo de referencia lleva su propia línea Verificado contra con la página ascendente contra la que se verificaron sus reglas.

Fuera del alcance. Zod 3 en cualquier forma. La línea 4.5.0-canary, contra la que no se derivó ninguna regla aquí. Otras bibliotecas de validación, excepto cuando se comparte un límite con una — la interoperabilidad con Standard Schema está cubierta, las API propias de Valibot o ArkType no lo están. Las herramientas de generación de código que emiten esquemas Zod se nombran donde cambian lo que aún debe escribir a mano, pero su propia configuración es suya.

Las palabras clave "DEBE", "NO DEBE", "REQUERIDO", "DEBERÍA", "NO DEBERÍA", "RECOMENDADO", "PUEDE" y "OPCIONAL" en este documento deben interpretarse como se describe en RFC 2119.

El Límite de Validación

Consulte validation-boundary.md para:

• colocar el único análisis en el borde donde entran los datos, y nunca volver a analizar hacia adentro del mismo
• unknown aguas arriba del análisis y z.infer<typeof Schema> aguas abajo, nunca una interfaz escrita a mano
• qué preguntas pertenecen a una capacidad de seguridad de la aplicación, framework, estado del servidor o componente
• los casos en los que un esquema cuesta sin comprar — datos internos, un valor ya analizado, un bucle por elemento
• ejecutar Zod junto a un segundo validador y convertir entre ellos en un solo lugar

Versión y Paquetes

Consulte version-and-packages.md para:

• distinguir zod.dev (Zod 4) de v3.zod.dev (Zod 3) antes de confiar en una página
• elegir entre zod, zod/mini, zod/locales y los enlaces permanentes zod/v4/*
• el supuesto TypeScript 5.5+ y strict: true, sin los cuales la opcionalidad inferida no es sólida
• los pisos de versión menor para z.xor, z.invertCodec, .safeExtend, z.property y la dirección .brand
• los modismos de Zod 3 que aún se compilan contra Zod 4, como señal de desactualización

Módulos de Esquema

Consulte schema-modules.md para:

• las convenciones de nomenclatura const X / type X y zX, y elegir una por repositorio
• primitivas compartidas EntityId, Timestamp y NonEmptyString como el vocabulario del que se componen otros esquemas
• .brand<"Name">(), su dirección "out"/"in"/"inout", y los fixtures que obliga a pasar por un análisis
• derivar con .shape, .extend, .safeExtend, .pick, .omit y el lanzamiento de .merge() en 4.4 en refinamientos
• elevar cada esquema al ámbito del módulo en lugar de reconstruirlo por solicitud o renderizado

Primitivas y Formatos

Consulte primitives-and-formats.md para:

• los métodos de nivel superior z.email(), z.url(), z.uuid() y z.iso.datetime() que reemplazaron los métodos z.string().x()
• elegir z.uuid() estricto sobre z.guid() permisivo, y z.httpUrl() sobre z.url() para una URL obtenida
• z.stringFormat() para un formato propio del proyecto y z.templateLiteral() para un tipo de literal de plantilla
• el rango de enteros seguros de z.int(), el rechazo de Infinity, y los de ancho fijo z.int32() y z.float64()
• z.enum() sobre el obsoleto z.nativeEnum(), con .exclude() y .extract()

Objetos y Colecciones

Consulte objects-and-collections.md para:

• z.object() eliminando claves no modeladas, y z.strictObject(), z.looseObject() y .catchall() cambiando eso
• autorreferencia a través de un getter, y la anotación de tipo de retorno que necesita un error de circularidad
• los dos argumentos requeridos de z.record(), claves de enumeración exhaustivas y z.partialRecord()
• z.tuple() donde .nonempty() ya no produce un tipo de tupla, además de z.file() y z.json()
• analizar un esquema de matriz una vez en lugar de un esquema de elemento por elemento

Uniones

Consulte unions.md para:

• z.discriminatedUnion() para estrechamiento, calidad de error y velocidad de análisis sobre una z.union() simple
• el discriminador literal que cada rama debe fijar, y las uniones anidadas y tuberías que Zod 4 permite dentro de una
• z.xor() para el caso en que un valor que coincide con dos ramas es un defecto
• z.intersection() lanzando un Error simple en lugar de un ZodError en un resultado no fusionable
• la unión de formas de campo opcional que deberían haber sido un solo objeto

Opcionalidad y Valores Predeterminados

Consulte optionality-and-defaults.md para:

• elegir .optional(), .nullable() o .nullish() según lo que el productor realmente emite
• .default() cortocircuitando en el tipo de salida versus .prefault() analizando en el tipo de entrada
• .catch() convirtiendo un fallo de análisis en un valor alternativo, y cuándo eso oculta un productor a la deriva
• .nullish().transform((v) => v ?? null) para colapsar un productor mixto de nulo e indefinido
• lo que exactOptionalPropertyTypes hace al tipo inferido de una propiedad opcional

Refinamientos

Consulte refinements.md para:

• .refine(), .superRefine() y .check(), y la regla de que ninguno de ellos puede lanzar una excepción
• ctx.addIssue(), z.NEVER y la path que coloca un error en un campo específico
• abort para detener una cadena, y el when de 4.4 para omitir una verificación cuyas entradas ya no son válidas
• un refinamiento asíncrono que fuerza .parseAsync() en cada llamador existente del esquema compuesto
• una regla de permiso, cuota o unicidad que pertenece al dominio en lugar del esquema

Transformaciones y Tuberías

Consulte transforms-and-pipes.md para:

• .transform() después de la validación, z.preprocess() antes de ella, y .pipe() entre dos esquemas
• .overwrite() donde el valor cambia pero el tipo y su introspeccionabilidad no deben hacerlo
• z.input versus z.output/z.infer, y los errores de forma y fixture por confundirlos
• ctx.issues.push o ctx.addIssue de 4.4 con z.NEVER para fallar desde dentro de una transformación
• dónde termina la remodelación de los datos del productor y comienza una decisión de dominio

Códecs

Consulte codecs.md para:

• z.codec(input, output, { decode, encode }) para un límite que .transform() no puede revertir
• .decode() y .encode() con sus formas safe* y *Async, además de z.invertCodec()
• las plantillas documentadas isoDatetimeToDate, json, stringToURL y base64ToBytes — copiadas, no importadas
• valores predeterminados y .catch() aplicándose solo en la decodificación, y un .transform() haciendo que la codificación lance un error que no es ZodError
• el códec total que no puede fallar, y la garantía de forma que, por lo tanto, no proporciona

Coerción y Configuración

Consulte coercion-and-config.md para:

• z.coerce.number().parse("") devolviendo 0, y z.coerce.boolean().parse("false") devolviendo true
• z.stringbool() como la construcción que rechaza un valor que no está ni en el conjunto verdadero ni en el falso
• cadenas de consulta, datos de formulario y variables de entorno como las tres fuentes con valores de cadena
• analizar la configuración una vez al inicio y terminar en lugar de mostrar undefined más tarde
• mantener la configuración secreta fuera de los registros y fuera del paquete del cliente

Análisis

Consulte parsing.md para:

• .parse() cuando un fallo es un defecto, .safeParse() cuando es un resultado sobre el que bifurcar
• .parseAsync() siendo obligatorio en lugar de opcional una vez que cualquier verificación en el esquema es asíncrona
• la clonación profunda que devuelve un análisis, y la identidad de referencia que, por lo tanto, rompe
• reasignar ZodError a un error de dominio para que Zod permanezca fuera de las firmas de dominio
• registrar el límite y las rutas de los problemas, nunca la entrada que falló

Errores

Consulte errors.md para:

• error.issues con su code y path, y los alias eliminados .errors y .formErrors
• z.treeifyError(), z.flattenError() y z.prettifyError(), elegidos por el consumidor
• el parámetro unificado error que reemplazó a message, invalid_type_error y errorMap
• la precedencia — esquema, por análisis, z.config({ customError }), locale — que se invirtió en Zod 4
• reportInput poniendo entrada no confiable en un error que viaja a un rastreador o a un cliente

Metadatos y Esquema JSON

Consulte metadata-and-json-schema.md para:

• .meta(), z.registry(), z.globalRegistry y extender GlobalMeta mediante fusión de declaraciones
• el enlace de metadatos a una instancia de esquema, por lo que .optional() o .extend() lo huérfanan
• las opciones target, io, unrepresentable, cycles, reused y uri de z.toJSONSchema()
• io: "input" produciendo un documento diferente de la vista de salida predeterminada
• los tipos date, map, set, transform y bigint sin representación en Esquema JSON

Salida Estructurada del Modelo

Consulte model-structured-output.md para:

• un esquema como contrato de generateObject o herramienta, y satisfies z.ZodRawShape donde se desea una forma sin procesar
• el texto de .describe() que llega al modelo como instrucción en lugar de como documentación
• .nullable() sobreviviendo al modo estricto de un proveedor donde .optional() y .nullish() son rechazados
• reutilizar .shape.field para que la salida del modelo no pueda desviarse del tipo de dominio al que alimenta
• volver a preguntar desde un ZodError bajo un reintento limitado, en lugar de parchear la salida no válida

Formularios

Consulte forms.md para:

• un resolvedor específico de Zod para los detalles de problema de Zod, o uno de Standard Schema para independencia de bibliotecas
• z.input para los valores y valores predeterminados del formulario, z.output para el manejador de envío
• path en un refinamiento entre campos como la única forma en que un error llega a la entrada correcta
• la cadena vacía que envía un campo numérico en blanco, y la clave ausente que envía una casilla de verificación no marcada
• el nuevo análisis del lado del servidor que un esquema del lado del cliente nunca reemplaza

Límites del Almacén de Datos

Consulte data-store-boundaries.md para:

• la forma almacenada y el modelo de dominio como dos esquemas con una transformación entre ellos
• las mitades de lectura y escritura escritas como un par, para que un campo renombrado no pueda desviarse entre ellas
• .partial() para un parche y .omit().extend() para una entrada de creación que lleva centinelas del almacén
• z.instanceof() para los tipos propios de un controlador y z.property() para restringir uno de sus campos
• una carga útil que varía según la profundidad de la consulta, el estado del borrador o la configuración regional — y el esquema completamente opcional que no es la respuesta

Rendimiento y Huella

Consulte performance-and-footprint.md para:

• las ganancias de análisis publicadas de ~14x, ~7x y ~6.5x, y la caída de ~25,000 a ~175 en instanciaciones de tipos
• la API funcional de zod/mini y su núcleo de 1.88 kB, y por qué un servidor no debería adoptarlo
• la construcción del esquema elevada fuera de una ruta crítica, y una colección analizada una vez en lugar de por elemento
• .check() sobre .refine() y una unión discriminada sobre una lineal, en una ruta medida
• z.looseObject() saltándose el paso de eliminación de claves, y la protección que eso intercambia

Postura de Seguridad

Consulte security-posture.md para:

• la eliminación de z.object() como protección contra asignación masiva, y lo que z.looseObject() readmite
• que un análisis exitoso no es escape de HTML, parametrización SQL ni una garantía de obtención segura
• .max() colocado antes de un .regex() o un refinamiento costoso, para limitar el trabajo controlado por el atacante
• matrices ilimitadas, profundidad de recursión ilimitada y entrada cíclica que se repite para siempre
• un esquema de respuesta de listas permitidas, sin el cual un campo privado se va con la carga útil

Pruebas de Esquemas

Consulte testing-schemas.md para:

• por qué afirmar que z.email() rechaza "nope" prueba a Zod en lugar del esquema
• z.input<typeof Schema> como el tipo fixture, construido a partir de una carga útil observada