Schémas Zod dans TypeScript
Sellel lehel
Mis à jour le 3 novembre 2026 après compilation avec le SDK
@mistralai/mistralai3.5.0, Zod 4.6 et TypeScript 7.0.2. L’exemple original importaitMistralpar défaut, mais le SDK ne propose qu’un export nommé. Il lisait également une variableresponsedansmain()qui n’existait que dansextractBook(). L’accès àparsedignorait le fait quechoicesetmessagesont optionnels dans les types du SDK, et traitaitparsedcomme unBookalors que son type est en réalitéunknown. L’import deZodErrorétait inutile :chat.parse()valide avecsafeParseet ne lance jamais d’exception. La clé API n’est plus codée en dur. Sources : Mistral TypeScript SDK · exemple officielchat.parse.
Zod : l’équivalent TypeScript de Pydantic
Si tu travailles en TypeScript ou en JavaScript, Zod est la bibliothèque de validation de schémas utilisée par le SDK Mistral pour les sorties structurées personnalisées. Elle joue exactement le même rôle que Pydantic en Python : définir un schéma strict que le modèle doit respecter. Tout ce que tu as appris sur les schémas s’applique ici, avec seulement des différences de syntaxe.
Installe le SDK et Zod en une seule commande :
npm install @mistralai/mistralai zod
Zod fonctionne nativement avec TypeScript et offre une inférence de type automatique — son principal avantage par rapport à l’écriture manuelle d’interfaces.
Définir un schéma simple
Construis un schéma Zod avec z.object(), en assignant un validateur à chaque champ. La ligne z.infer fait toute la différence : elle déduit le type TypeScript à partir du schéma, ce qui t’évite de maintenir deux déclarations parallèles susceptibles de diverger.
import { z } from "zod";
const ContactSchema = z.object({
name: z.string(),
email: z.string(),
phone: z.string(),
company: z.string(),
});
// TypeScript infère automatiquement le type
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }
Les types dont tu auras besoin
Zod couvre tous les besoins pour les sorties structurées. Le schéma de ticket ci-dessous rassemble des cas courants : champs de base, champ nullable pour un ticket non assigné, énumération pour la priorité et tableaux typés.
import { z } from "zod";
const TicketSchema = z.object({
// Types de base
title: z.string(),
description: z.string(),
ticketId: z.number(),
confidence: z.number(),
isUrgent: z.boolean(),
// Optionnel (peut être null)
assignee: z.string().nullable(),
// Énumération (valeurs contraintes)
priority: z.enum(["low", "medium", "high", "critical"]),
// Listes
tags: z.array(z.string()),
relatedIds: z.array(z.number()),
});
type Ticket = z.infer<typeof TicketSchema>;
Une nuance mérite attention : là où Python distingue int et float, Zod ne connaît que z.number(). Garde cette correspondance en tête lorsque tu portes un schéma d’un langage à l’autre.
| 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([...]) |
Schémas imbriqués
Comme avec Pydantic, un schéma peut en contenir un autre : il suffit de référencer la constante. La composition se lit alors de l’intérieur vers l’extérieur : l’adresse dans l’entreprise, l’entreprise dans la personne.
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>;
Un appel complet avec le SDK Mistral
Voici la même extraction de livre que dans la leçon Python, portée en TypeScript. Trois points nécessitent ton attention. Le paramètre est responseFormat en camelCase. Tu dois tester parsed avant de l’utiliser : le SDK valide la réponse contre le schéma avec safeParse et, si le JSON est tronqué ou ne correspond pas au schéma, laisse parsed comme undefined au lieu de lancer une erreur. Enfin, le SDK ne transporte pas le type de ton schéma : il déclare parsed comme unknown. Faire passer l’objet par BookSchema.parse() le type comme Book et le revalide au passage.
import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";
// 1. Définir le schéma
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. Créer le client
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
// 3. Appeler 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. Accéder à l'objet analysé
const message = response.choices?.[0]?.message;
if (!message?.parsed) {
throw new Error("Response missing, truncated, or non-compliant with schema");
}
// Le JSON brut reste disponible dans message.content
console.log(`Raw JSON: ${message.content}`);
// parsed est typé comme unknown : BookSchema.parse() renvoie un Book typé
return BookSchema.parse(message.parsed);
}
// 5. Utilisation
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();
Décrire les champs avec .describe()
Dans Zod, .describe() remplit le même rôle que Field(description=...) dans Pydantic : indiquer au modèle ce que le champ doit contenir, surtout lorsque le nom seul est ambigu. Un score sans description pourrait atterrir sur une échelle de 0 à 100 ; avec une plage explicite mentionnée, il suit ta convention.
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"
),
});
Gestion des erreurs
Le motif de nouvelle tentative suit la même logique qu’en Python, avec une signature générique qui le rend réutilisable pour n’importe quel schéma. Inutile d’attraper une ZodError : chat.parse() n’en lance pas ; il laisse parsed vide. Ce cas, ainsi que les erreurs réseau ou HTTP, déclenche une nouvelle tentative. La contrainte z.ZodType<T> lie le schéma passé en argument au type de retour : schema.parse() renvoie un T, de sorte que l’appelant obtient un objet correctement typé sans annotations supplémentaires.
// Suite du même fichier : client, z et BookSchema sont déjà définis
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); // restaure le type T
} catch (error) {
console.error(`Attempt ${attempt + 1} failed:`, error);
if (attempt === maxRetries) throw error;
}
}
throw new Error("Unexpected failure");
}
// Utilisation
try {
const book = await safeExtract("My text here", BookSchema);
console.log(book.title);
} catch (error) {
console.error("Extraction failed:", error);
}
Peamised punktid
- Zod est l’équivalent TypeScript de Pydantic pour les sorties structurées personnalisées
z.infer<typeof Schema>génère automatiquement le type TypeScript.describe()ajoute des instructions par champ, commeField(description=...)en Python- Le SDK TypeScript de Mistral utilise
responseFormat(camelCase) au lieu deresponse_format - Une réponse non conforme laisse
parsedcommeundefined(pas d’exception) : teste-le, puis réessaie si nécessaire