Esquemas Zod en TypeScript
En esta página
Actualizado el 3 de noviembre de 2026 tras compilar con el SDK
@mistralai/mistralai3.5.0, Zod 4.6 y TypeScript 7.0.2. El ejemplo original importabaMistralpor defecto, pero el SDK solo ofrece una exportación con nombre. Además, leía una variableresponseenmain()que solo existía dentro deextractBook(). Al acceder aparsedse ignoraba quechoicesymessageson opcionales en los tipos del SDK, y se tratabaparsedcomo unBookcuando su tipo es realmenteunknown. La importación deZodErrorera innecesaria:chat.parse()valida consafeParsey nunca lanza excepciones. La clave de API ya no está hardcodeada. Fuentes: Mistral TypeScript SDK · ejemplo oficial dechat.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) |
|---|---|
str | z.string() |
int, float | z.number() |
bool | z.boolean() |
list[str] | z.array(z.string()) |
Optional[str] | z.string().nullable() |
Enum | z.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, comoField(description=...)en Python- El SDK de TypeScript de Mistral usa
responseFormat(camelCase) en lugar deresponse_format - Una respuesta no conforme deja
parsedcomoundefined(sin excepción): compruébalo y reintenta si es necesario