Ir al contenido principal
Español— Elegir un idioma
Menú

Validación con JSON Schema y Zod

Lección 11 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Validación con JSON Schema y Zod
  2. Por qué validar tras la recepción
  3. Validación en Python con jsonschema
  4. Validación con Pydantic
  5. Validación con Zod (TypeScript/Node.js)
  6. Patrón: reintento con corrección
  7. Banco de pruebas para invitaciones de calendario
  8. Puntos clave

Lección actualizada el 3 de noviembre de 2026 según la documentación de OpenAI: temperature y top_p solo se aceptan con un esfuerzo de razonamiento de none, mientras que los modelos GPT-5.6 razonan por defecto (medium). Por tanto, las llamadas que establezcan estos parámetros deben especificar reasoning={"effort": "none"} (API de Responses) o reasoning_effort="none" (Chat Completions). Fuentes: Uso de GPT-6 · GPT-5.6 Terra.

Validación con JSON Schema y Zod

La Salida Estructurada garantiza la estructura de la respuesta, pero no la validez semántica de los datos. Un campo «email» podría contener una cadena que no sea una dirección de correo válida. La validación del lado del cliente mediante JSON Schema o Zod es el complemento esencial para construir una canalización robusta.

Por qué validar tras la recepción

Si haces balance de lo que garantiza la API, la división del trabajo queda clara. La Salida Estructurada de OpenAI asegura que el JSON sea sintácticamente válido, que se respeten los tipos declarados (una cadena sigue siendo una cadena, un entero sigue siendo un entero), que todos los campos obligatorios estén presentes y que los valores restringidos por un enum pertenezcan a la lista. En estos cuatro puntos, puedes escribir tu código con confianza.

Todo lo demás corre de tu cuenta, abarcando cuatro familias de problemas. Las restricciones de formato escapan al esquema estricto: nada impide que el modelo devuelva jean.dupont(at)example.fr en un campo email, o una fecha en formato 15/03/2026 cuando esperas ISO. Los límites tampoco se comprueban, ni para la longitud de cadenas ni para el rango numérico: una edad de 350 años pasará sin pestañear. La coherencia entre campos queda fuera de alcance: un end_date anterior al start_date es JSON perfectamente válido. Y la validez empresarial no tiene por qué preocupar a la API: un SIRET (identificador fiscal francés) debe tener catorce dígitos, pero eso es conocimiento de tu dominio, no del decodificador.

Estas cuatro familias comparten un rasgo alarmante: no provocan errores visibles. Un correo mal formado guardado en la base de datos no se manifestará hasta que la campaña de emailing rebote semanas después. De ahí la regla: valida antes de persistir, nunca después.

Validación en Python con jsonschema

La consecuencia práctica es que necesitas dos esquemas para los mismos datos. El primero va a la API, intencionadamente austero, limitado a lo que el modo estricto acepta. El segundo se queda contigo y lleva las restricciones de grano fino: format, pattern, minimum, maximum. Esta aparente duplicidad es una separación de responsabilidades: uno enmarca la generación, el otro defiende tu almacenamiento. En el ejemplo siguiente, solo el enum de rol aparece en ambos, porque es la única restricción que ambos niveles pueden expresar.

import json
from jsonschema import validate, ValidationError

# Esquema para la API de OpenAI (estricto, sin format/pattern)
api_schema = {
    "type": "object",
    "properties": {
        "email": {"type": "string"},
        "age": {"type": "integer"},
        "role": {"type": "string", "enum": ["admin", "user", "viewer"]}
    },
    "required": ["email", "age", "role"],
    "additionalProperties": False
}

# Esquema extendido para validación del lado del cliente
validation_schema = {
    "type": "object",
    "properties": {
        "email": {
            "type": "string",
            "format": "email",
            "pattern": r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z]{2,}$"
        },
        "age": {
            "type": "integer",
            "minimum": 0,
            "maximum": 150
        },
        "role": {"type": "string", "enum": ["admin", "user", "viewer"]}
    },
    "required": ["email", "age", "role"]
}

def validate_response(data: dict) -> tuple[bool, str]:
    """Valida la respuesta del LLM contra el esquema extendido."""
    try:
        validate(instance=data, schema=validation_schema)
        return True, "Válido"
    except ValidationError as e:
        return False, f"Error: {e.message}"

Validación con Pydantic

Pydantic suele ser más cómodo que jsonschema para validar en Python, y la diferencia radica en lo que obtienes a la salida. jsonschema te dice sí o no y te deja con un diccionario, manipulado vía data["email"] sin ayuda del editor. Pydantic devuelve un objeto tipado: el autocompletado funciona, un error tipográfico en el nombre de un atributo se detecta en tiempo de escritura y los datos circulan después sin conversión.

El modelo ContactExtraction expresa los límites directamente en las declaraciones de campo. El field_validator sobre date_extraction cubre el caso que ninguna anotación de tipo puede capturar: la cadena es efectivamente una cadena, pero debe representar una fecha real; 2026-02-31 satisface cualquier pattern razonable, pero no existe. La función de extracción muestra la cadena completa, desde el esquema austero enviado a la API hasta la instanciación validada.

from pydantic import BaseModel, Field, field_validator
from pydantic import EmailStr
from datetime import date

class ContactExtraction(BaseModel):
    """Esquema de validación para extracción de contactos."""
    last_name: str = Field(min_length=2, max_length=100)
    first_name: str = Field(min_length=2, max_length=100)
    email: EmailStr
    phone: str = Field(pattern=r"^\+?[0-9\s\-\.]{10,15}$")
    company: str
    title: str
    extraction_date: str

    @field_validator("extraction_date")
    @classmethod
    def validate_date(cls, v):
        try:
            date.fromisoformat(v)
            return v
        except ValueError:
            raise ValueError(f"Fecha no válida: {v}")

def extract_and_validate(text: str) -> ContactExtraction:
    """Extrae un contacto y valida los datos."""
    # Esquema para la API (sin restricciones de grano fino)
    api_schema = {
        "type": "object",
        "properties": {
            "last_name": {"type": "string"},
            "first_name": {"type": "string"},
            "email": {"type": "string"},
            "phone": {"type": "string"},
            "company": {"type": "string"},
            "title": {"type": "string"},
            "extraction_date": {"type": "string"}
        },
        "required": ["last_name", "first_name", "email", "phone",
                      "company", "title", "extraction_date"],
        "additionalProperties": False
    }

    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions="Extrae la información de contacto. "
                     "Formato de fecha: AAAA-MM-DD.",
        input=text,
        text={
            "format": {
                "type": "json_schema",
                "name": "contact",
                "schema": api_schema,
                "strict": True
            }
        }
    )

    data = json.loads(response.output_text)
    # Validación con Pydantic con restricciones de grano fino
    return ContactExtraction(**data)

Validación con Zod (TypeScript/Node.js)

Si tu backend está en TypeScript, Zod es la herramienta de referencia, y aporta una ventaja que Pydantic no necesita ofrecer: z.infer deriva el tipo de TypeScript directamente del esquema de validación. Describes la forma una vez y el compilador conoce entonces la estructura de Invoice sin que tengas que mantener una interfaz paralela, por lo que no hay riesgo de divergencia.

El esquema de factura siguiente ilustra la división del trabajo: del lado de la API, siret es solo una cadena; del lado de Zod, debe tener exactamente catorce caracteres y contener solo dígitos. El parse final lanza una excepción si los datos no encajan, y ese es el comportamiento deseado: un error estridente que interrumpe el procesamiento del documento es preferible a una factura con un SIRET fantasma almacenada en la base de datos entre otras diez mil.

import { z } from "zod";
import OpenAI from "openai";

const client = new OpenAI();

// Esquema Zod con validaciones de grano fino
const InvoiceSchema = z.object({
  number: z.string().regex(/^[A-Z]{2}-\d{4}-\d{4}$/),
  date: z.string().date(),
  amount_excl_tax: z.number().positive(),
  vat_rate: z.number().min(0).max(100),
  amount_incl_tax: z.number().positive(),
  supplier: z.object({
    name: z.string().min(2),
    siret: z.string().length(14).regex(/^\d+$/),
  }),
});

type Invoice = z.infer<typeof InvoiceSchema>;

async function extractInvoice(text: string): Promise<Invoice> {
  const response = await client.responses.create({
    model: "gpt-5.6-terra",
    instructions: "Extrae los datos de la factura.",
    input: text,
    text: {
      format: {
        type: "json_schema",
        name: "invoice",
        schema: {
          type: "object",
          properties: {
            number: { type: "string" },
            date: { type: "string" },
            amount_excl_tax: { type: "number" },
            vat_rate: { type: "number" },
            amount_incl_tax: { type: "number" },
            supplier: {
              type: "object",
              properties: {
                name: { type: "string" },
                siret: { type: "string" },
              },
              required: ["name", "siret"],
              additionalProperties: false,
            },
          },
          required: ["number", "date", "amount_excl_tax",
                     "vat_rate", "amount_incl_tax", "supplier"],
          additionalProperties: false,
        },
        strict: true,
      },
    },
  });

  const data = JSON.parse(response.output_text);

  // Validación Zod con restricciones de grano fino
  return InvoiceSchema.parse(data);
}

Patrón: reintento con corrección

Cuando la validación falla, devuelve el error al modelo para que lo corrija. Este reflejo cambia la naturaleza del fallo: una fecha en formato incorrecto deja de ser una excepción que burbujea hasta el usuario para convertirse en una ida y vuelta adicional de unos pocos cientos de milisegundos que nadie nota. El mecanismo es simple: reinyectamos el mensaje de validación en el prompt del siguiente intento, de modo que el modelo sepa exactamente qué ha salido mal en lugar de adivinar a ciegas una segunda vez.

Esta comodidad requiere límites, sin embargo. Pon un tope al número de intentos, o una restricción imposible (un pattern demasiado estricto para números extranjeros, por ejemplo) te costará llamadas en bucle. Y monitoriza la tasa de reintentos: si una cuarta parte de tus extracciones pasa por un reintento, el problema está en el prompt inicial o en el esquema, no en el modelo.

def extract_with_retry(prompt: str, schema: dict,
                       validator, max_retries: int = 3) -> dict:
    """Extrae y valida con reintento automático."""
    last_error = None

    for attempt in range(max_retries):
        input_text = prompt
        if last_error:
            input_text += (f"\n\nADVERTENCIA: Tu respuesta anterior tuvo "
                          f"este error de validación: {last_error}\n"
                          f"Corrige e inténtalo de nuevo.")

        response = client.responses.create(
            model="gpt-5.6-terra",
            reasoning={"effort": "none"},  # temperature requiere effort none
            input=input_text,
            text={"format": {"type": "json_schema",
                             "name": "data",
                             "schema": schema,
                             "strict": True}},
            temperature=0.1
        )

        data = json.loads(response.output_text)
        is_valid, error = validator(data)

        if is_valid:
            return data
        last_error = error

    raise ValueError(f"Fallo tras {max_retries} intentos: {last_error}")

Banco de pruebas para invitaciones de calendario

Construye un esquema Pydantic para extraer eventos (título, fecha, hora, ubicación, participantes) y conéctalo tras una llamada de Salida Estructurada. Prueba con cinco correos que contengan invitaciones, asegurándote de incluir al menos uno donde la hora esté escrita («jueves a media mañana») y otro donde la ubicación sea implícita («como siempre en la sala de juntas»). Estos son los casos que rompen la validación y dominan en una bandeja de entrada real.

Añade luego el reintento automático y mide dos cifras: la tasa de éxito al primer intento y la tasa posterior al reintento. La segunda te dice qué gana la corrección; la primera, si deberías rehacer tus instrucciones en lugar de contar con una segunda oportunidad.

Puntos clave

  • La Salida Estructurada garantiza la estructura, no la validez semántica
  • Usa dos esquemas: uno para la API (estricto) y otro para validación del cliente
  • Pydantic (Python) y Zod (TypeScript) son las herramientas de referencia
  • El patrón de reintento con retroalimentación corrige la mayoría de errores de validación
  • Valida siempre del lado del cliente antes de persistir los datos