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

Esquemas Zod en TypeScript

Lección 9 de 12 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Zod: el equivalente en TypeScript de Pydantic
  2. Definición de un esquema sencillo
  3. Tipos que necesitarás
  4. Esquemas anidados
  5. Una llamada completa con el SDK de Mistral
  6. Descripción de campos con .describe()
  7. Gestión de errores
  8. Puntos clave

Actualizado el 3 de noviembre de 2026 tras compilar con el SDK @mistralai/mistralai 3.5.0, Zod 4.6 y TypeScript 7.0.2. El ejemplo original importaba Mistral por defecto, pero el SDK solo ofrece una exportación con nombre. Además, leía una variable response en main() que solo existía dentro de extractBook(). Al acceder a parsed se ignoraba que choices y message son opcionales en los tipos del SDK, y se trataba parsed como un Book cuando su tipo es realmente unknown. La importación de ZodError era innecesaria: chat.parse() valida con safeParse y nunca lanza excepciones. La clave de API ya no está hardcodeada. Fuentes: Mistral TypeScript SDK · ejemplo oficial de chat.parse.

Zod: el equivalente en TypeScript de Pydantic

Si trabajas con TypeScript o JavaScript, Zod es la biblioteca de validación de esquemas que utiliza el SDK de Mistral para las salidas estructuradas personalizadas. Desempeña exactamente el mismo papel que Pydantic en Python: definir un esquema estricto que el modelo debe seguir. Todo lo que has aprendido sobre esquemas se aplica aquí, con únicas diferencias de sintaxis.

Instala tanto el SDK como Zod en un solo comando:

npm install @mistralai/mistralai zod

Zod funciona de forma nativa con TypeScript y ofrece inferencia automática de tipos; esta es su principal ventaja frente a escribir interfaces a mano.

Definición de un esquema sencillo

Construye un esquema Zod con z.object(), asignando un validador a cada campo. La línea z.infer marca la diferencia: deduce el tipo de TypeScript a partir del esquema, de modo que no tienes que mantener dos declaraciones paralelas que podrían divergir.

import { z } from "zod";

const ContactSchema = z.object({
  name: z.string(),
  email: z.string(),
  phone: z.string(),
  company: z.string(),
});

// TypeScript infiere automáticamente el tipo
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }

Tipos que necesitarás

Zod cubre todas las necesidades para salidas estructuradas. El esquema de ticket siguiente reúne casos comunes: campos básicos, un campo anulable para un ticket sin asignar, una enumeración para la prioridad y arrays tipados.

import { z } from "zod";

const TicketSchema = z.object({
  // Tipos básicos
  title: z.string(),
  description: z.string(),
  ticketId: z.number(),
  confidence: z.number(),
  isUrgent: z.boolean(),

  // Opcional (puede ser null)
  assignee: z.string().nullable(),

  // Enum (valores restringidos)
  priority: z.enum(["low", "medium", "high", "critical"]),

  // Listas
  tags: z.array(z.string()),
  relatedIds: z.array(z.number()),
});

type Ticket = z.infer<typeof TicketSchema>;

Un matiz merece atención: mientras que Python distingue entre int y float, Zod solo conoce z.number(). Ten presente esta correspondencia al portar un esquema de un lenguaje a otro.

Pydantic (Python)Zod (TypeScript)
strz.string()
int, floatz.number()
boolz.boolean()
list[str]z.array(z.string())
Optional[str]z.string().nullable()
Enumz.enum([...])

Esquemas anidados

Al igual que con Pydantic, un esquema puede contener a otro: basta con referenciar la constante. La composición se lee entonces desde lo más interno hacia lo más externo: la dirección dentro de la empresa, la empresa dentro de la persona.

import { z } from "zod";

const AddressSchema = z.object({
  street: z.string(),
  city: z.string(),
  postalCode: z.string(),
  country: z.string(),
});

const CompanySchema = z.object({
  name: z.string(),
  industry: z.string(),
  address: AddressSchema,
});

const PersonSchema = z.object({
  firstName: z.string(),
  lastName: z.string(),
  email: z.string(),
  role: z.string(),
  company: CompanySchema,
});

type Person = z.infer<typeof PersonSchema>;

Una llamada completa con el SDK de Mistral

Aquí tienes la misma extracción de libros de la lección de Python, portada a TypeScript. Tres puntos requieren atención. El parámetro es responseFormat en camelCase. Debes comprobar parsed antes de usarlo: el SDK valida la respuesta frente al esquema con safeParse y, si el JSON está truncado o no coincide con el esquema, deja parsed como undefined en lugar de lanzar un error. Por último, el SDK no transporta el tipo de tu esquema: declara parsed como unknown. Pasar el objeto por BookSchema.parse() lo tipa como Book y lo revalida en el proceso.

import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";

// 1. Definir el esquema
const BookSchema = z.object({
  title: z.string().describe("Book title"),
  authors: z.array(z.string()).describe("List of authors"),
  year: z.number().nullable().describe("Publication year"),
  genre: z.string().describe("Main literary genre"),
  summary: z.string().describe("Summary in 2-3 sentences"),
});

type Book = z.infer<typeof BookSchema>;

// 2. Crear el cliente
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

// 3. Llamar a chat.parse()
async function extractBook(text: string): Promise<Book> {
  const response = await client.chat.parse({
    model: "mistral-large-latest",
    messages: [
      {
        role: "system",
        content: "You are an expert librarian. Extract book information.",
      },
      { role: "user", content: text },
    ],
    responseFormat: BookSchema,
    temperature: 0,
  });

  // 4. Acceder al objeto parseado
  const message = response.choices?.[0]?.message;
  if (!message?.parsed) {
    throw new Error("Response missing, truncated, or non-compliant with schema");
  }
  // El JSON crudo sigue disponible en message.content
  console.log(`Raw JSON: ${message.content}`);
  // parsed tiene tipo unknown: BookSchema.parse() devuelve un Book tipado
  return BookSchema.parse(message.parsed);
}

// 5. Uso
async function main() {
  const book = await extractBook(
    "I loved '1984' by George Orwell, published in 1949. A dystopian classic."
  );

  console.log(`Title: ${book.title}`);
  console.log(`Authors: ${book.authors.join(", ")}`);
  console.log(`Year: ${book.year}`);
  console.log(`Genre: ${book.genre}`);
}

main();

Descripción de campos con .describe()

En Zod, .describe() cumple la misma función que Field(description=...) en Pydantic: indicar al modelo qué debe contener el campo, especialmente cuando el nombre por sí solo es ambiguo. Un score sin descripción podría caer en una escala de 0 a 100; con un rango explícito mencionado, seguirá tu convención.

const SentimentSchema = z.object({
  sentiment: z.enum(["positive", "negative", "neutral"]).describe(
    "Overall sentiment of the text"
  ),
  score: z.number().describe(
    "Confidence score between 0.0 and 1.0"
  ),
  keywords: z.array(z.string()).describe(
    "The 3–5 main keywords"
  ),
  summary: z.string().describe(
    "Summary in one sentence maximum"
  ),
});

Gestión de errores

El patrón de reintentos sigue la misma lógica que en Python, con una signatura genérica que lo hace reutilizable para cualquier esquema. No hace falta capturar un ZodError: chat.parse() no lo lanza; deja parsed vacío. Ese caso, junto con errores de red o HTTP, desencadena un reintento. La restricción z.ZodType<T> vincula el esquema pasado como argumento con el tipo de retorno: schema.parse() devuelve un T, de modo que quien llama recibe un objeto correctamente tipado sin anotaciones extra.

// Continuación del mismo archivo: client, z y BookSchema ya están definidos

async function safeExtract<T>(
  text: string,
  schema: z.ZodType<T>,
  maxRetries = 2
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await client.chat.parse({
        model: "mistral-large-latest",
        messages: [
          { role: "system", content: "Extract the requested information." },
          { role: "user", content: text },
        ],
        responseFormat: schema,
        temperature: 0,
      });

      const parsed = response.choices?.[0]?.message?.parsed;
      if (!parsed) {
        throw new Error("Response missing or non-compliant with schema");
      }
      return schema.parse(parsed); // restaura el tipo T
    } catch (error) {
      console.error(`Attempt ${attempt + 1} failed:`, error);
      if (attempt === maxRetries) throw error;
    }
  }
  throw new Error("Unexpected failure");
}

// Uso
try {
  const book = await safeExtract("My text here", BookSchema);
  console.log(book.title);
} catch (error) {
  console.error("Extraction failed:", error);
}

Puntos clave

  • Zod es el equivalente en TypeScript de Pydantic para salidas estructuradas personalizadas
  • z.infer<typeof Schema> genera automáticamente el tipo de TypeScript
  • .describe() añade instrucciones por campo, como Field(description=...) en Python
  • El SDK de TypeScript de Mistral usa responseFormat (camelCase) en lugar de response_format
  • Una respuesta no conforme deja parsed como undefined (sin excepción): compruébalo y reintenta si es necesario