Zod Schema Skill

Crea schemas de validacion Zod para backend y frontend.

When to Activate

• Validar input de un endpoint backend
• Crear schema de validacion para un formulario frontend
• Validar documentos espanoles (DNI, NIE, CIF, CCC, NSS)
• Agregar validaciones cruzadas entre campos
• Conectar validacion Zod con React Hook Form

Backend — Schema Inline en Controller

import { z } from "zod";

const createEmployeeSchema = z.object({
  nombre: z.string().min(1, "Nombre requerido"),
  primer_apellido: z.string().min(1, "Primer apellido requerido"),
  segundo_apellido: z.string().optional(),
  email: z.string().email("Email invalido"),
  telefono: z.string().regex(/^[0-9]{9}$/, "Telefono debe tener 9 digitos").optional(),
  tipo_documento: z.enum(["DNI", "NIE", "Pasaporte", "Tarjeta de residencia"]),
  numero_documento: z.string().min(1, "Documento requerido"),
  fecha_nacimiento: z.string().refine(val => !isNaN(Date.parse(val)), "Fecha invalida"),
  sexo: z.enum(["H", "M"]),
  companyId: z.number().int().positive().or(z.string().transform(Number)),
});

// Uso en controller:
export const createEmployee = async (req, res) => {
  try {
    const validated = createEmployeeSchema.parse(req.body);
    // ... logica
  } catch (error) {
    if (error instanceof z.ZodError) {
      return res.status(400).json({
        success: false,
        error: "Datos invalidos",
        details: error.errors,
      });
    }
    // ...
  }
};

Frontend — Schema en Archivo Separado

Schema (src/schemas/{modulo}Schema.ts)

import { z } from "zod";

export const employeeSchema = z.object({
  nombre: z.string().min(2, "Minimo 2 caracteres"),
  primer_apellido: z.string().min(2, "Minimo 2 caracteres"),
  segundo_apellido: z.string().optional(),
  tipo_documento: z.enum(["DNI", "NIE", "Pasaporte", "Tarjeta de residencia"]),
  numero_documento: z.string().min(1, "Documento requerido"),
  email: z.string().email("Email invalido"),
  telefono: z.string().regex(/^[0-9]{9}$/, "9 digitos").optional().or(z.literal("")),
  fecha_nacimiento: z.string()
    .refine(val => /^\d{2}\/\d{2}\/\d{4}$/.test(val), "Formato DD/MM/YYYY"),
}).superRefine((data, ctx) => {
  // Validaciones cruzadas por tipo de documento
  if (data.tipo_documento === "DNI" && !/^[0-9]{8}[A-Z]$/.test(data.numero_documento)) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: "DNI invalido (8 digitos + letra)",
      path: ["numero_documento"],
    });
  }
  if (data.tipo_documento === "NIE" && !/^[XYZ][0-9]{7}[A-Z]$/.test(data.numero_documento)) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: "NIE invalido (X/Y/Z + 7 digitos + letra)",
      path: ["numero_documento"],
    });
  }
});

// Tipo inferido para TypeScript
export type EmployeeFormData = z.infer<typeof employeeSchema>;

Integracion con React Hook Form

import { zodResolver } from "@hookform/resolvers/zod";
import { useForm } from "react-hook-form";
import { employeeSchema, type EmployeeFormData } from "../../schemas/employeeSchema";

const { register, handleSubmit, formState: { errors } } = useForm<EmployeeFormData>({
  resolver: zodResolver(employeeSchema),
});

Patrones de Validacion para Documentos Espanoles

Campo	Regex	Descripcion
DNI	/^[0-9]{8}[A-Z]$/	8 digitos + 1 letra mayuscula
NIE	/^[XYZ][0-9]{7}[A-Z]$/	X/Y/Z + 7 digitos + 1 letra
CIF	/^[A-Z][0-9]{7}[A-Z0-9]$/	Letra + 7 digitos + letra/digito
CCC	/^[0-9]{11}$/	11 digitos (Codigo Cuenta Cotizacion)
NSS	/^[0-9]{12}$/	12 digitos (Numero Seguridad Social)
Telefono	/^[0-9]{9}$/	9 digitos
Cod. Postal	/^[0-9]{5}$/	5 digitos
Fecha	DD/MM/YYYY o ISO 8601	Formato espanol o estandar

Validaciones Avanzadas

Letra de Control DNI

const validarLetraDNI = (dni: string): boolean => {
  const letras = "TRWAGMYFPDXBNJZSQVHLCKE";
  const numero = parseInt(dni.slice(0, 8));
  const letra = dni.charAt(8);
  return letras[numero % 23] === letra;
};

// En schema:
numero_documento: z.string()
  .regex(/^[0-9]{8}[A-Z]$/, "Formato DNI invalido")
  .refine(validarLetraDNI, "Letra de control DNI incorrecta"),

Campo Opcional que Puede ser String Vacio

// Permitir string vacio o valor valido
telefono: z.string()
  .regex(/^[0-9]{9}$/, "9 digitos")
  .optional()
  .or(z.literal("")),

Transformar String a Number

// Aceptar string o number, siempre devolver number
companyId: z.number().int().positive()
  .or(z.string().transform(Number)),

Convenciones

Concepto	Convencion
Backend	Schemas inline en el controller
Frontend	Archivos separados en src/schemas/{modulo}Schema.ts
Errores	Mensajes en espanol
Opcionales	.optional() o .nullable()
Transformaciones	.transform() para coercion de tipos
Validacion cruzada	.superRefine() para validaciones entre campos
Tipos	z.infer<typeof schema> para TypeScript

Checklist

• Schema definido con todos los campos requeridos
• Mensajes de error en espanol
• Validaciones regex para documentos espanoles
• Validaciones cruzadas con .superRefine() si aplica
• Tipo inferido exportado (type FormData = z.infer<typeof schema>)
• Integrado con React Hook Form via zodResolver (frontend)
• Manejo de z.ZodError en catch (backend)