Zod-schema's in TypeScript
Op deze pagina
Bijgewerkt op 3 november 2026 na compilatie met
@mistralai/mistralaiSDK 3.5.0, Zod 4.6 en TypeScript 7.0.2. Het oorspronkelijke voorbeeld importeerdeMistralstandaard, maar de SDK biedt alleen een named export. Het las ook een variabeleresponseinmain()die alleen bestond binnenextractBook(). Toegang totparsednegeerde datchoicesenmessageoptioneel zijn in de SDK-types, en behandeldeparsedals eenBookterwijl het type eigenlijkunknownis. De import vanZodErrorwas overbodig:chat.parse()valideert metsafeParseen gooit nooit een fout. De API-sleutel is niet langer hardcoded. Bronnen: Mistral TypeScript SDK · officieelchat.parsevoorbeeld.
Zod: het TypeScript-equivalent van Pydantic
Als u werkt met TypeScript of JavaScript, is Zod de bibliotheek voor schemavalidatie die door de Mistral SDK wordt gebruikt voor aangepaste gestructureerde uitvoer. Het speelt exact dezelfde rol als Pydantic in Python: het definiëren van een strikt schema dat het model moet volgen. Alles wat u over schema’s hebt geleerd, is hier van toepassing, met slechts syntactische verschillen.
Installeer zowel de SDK als Zod in één opdracht:
npm install @mistralai/mistralai zod
Zod werkt native met TypeScript en biedt automatische type-inferentie; dit is het grootste voordeel ten opzichte van het handmatig schrijven van interfaces.
Een eenvoudig schema definiëren
Bouw een Zod-schema met z.object() en wijs aan elk veld een validator toe. De regel z.infer maakt het verschil: deze leidt het TypeScript-type af van het schema, zodat u niet twee parallelle declaraties hoeft te onderhouden die uit elkaar kunnen lopen.
import { z } from "zod";
const ContactSchema = z.object({
name: z.string(),
email: z.string(),
phone: z.string(),
company: z.string(),
});
// TypeScript leidt het type automatisch af
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }
Typen die u nodig hebt
Zod dekt elke behoefte voor gestructureerde uitvoer. Het onderstaande ticketschema brengt veelvoorkomende gevallen samen: basisvelden, een nullable veld voor een niet-toegewezen ticket, een enum voor prioriteit en getypeerde arrays.
import { z } from "zod";
const TicketSchema = z.object({
// Basistypen
title: z.string(),
description: z.string(),
ticketId: z.number(),
confidence: z.number(),
isUrgent: z.boolean(),
// Optioneel (kan null zijn)
assignee: z.string().nullable(),
// Enum (beperkte waarden)
priority: z.enum(["low", "medium", "high", "critical"]),
// Lijsten
tags: z.array(z.string()),
relatedIds: z.array(z.number()),
});
type Ticket = z.infer<typeof TicketSchema>;
Eén nuance verdient aandacht: waar Python onderscheid maakt tussen int en float, kent Zod alleen z.number(). Houd deze mapping in gedachten wanneer u een schema van de ene taal naar de andere overzet.
| 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([...]) |
Geneste schema’s
Net als bij Pydantic kan een schema een ander bevatten: verwijz gewoon naar de constante. De compositie leest dan van binnen naar buiten: het adres binnen het bedrijf, het bedrijf binnen de persoon.
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>;
Een volledige aanroep met de Mistral SDK
Hier is dezelfde boekextractie uit de Python-les, overgezet naar TypeScript. Drie punten verdienen aandacht. De parameter is responseFormat in camelCase. U moet parsed testen voordat u het gebruikt: de SDK valideert het antwoord tegen het schema met safeParse en laat, als de JSON is afgekapt of niet overeenkomt met het schema, parsed als undefined in plaats van een fout te gooien. Tot slot draagt de SDK het type van uw schema niet mee: het declareert parsed als unknown. Door het object via BookSchema.parse() te halen, wordt het getypeerd als Book en tegelijkertijd opnieuw gevalideerd.
import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";
// 1. Definieer het schema
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. Maak de client
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
// 3. Roep chat.parse() aan
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. Toegang tot het geparseerde object
const message = response.choices?.[0]?.message;
if (!message?.parsed) {
throw new Error("Response missing, truncated, or non-compliant with schema");
}
// Ruwe JSON blijft beschikbaar in message.content
console.log(`Raw JSON: ${message.content}`);
// parsed is getypeerd als unknown: BookSchema.parse() retourneert een getypeerd Book
return BookSchema.parse(message.parsed);
}
// 5. Gebruik
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();
Velden beschrijven met .describe()
In Zod vervult .describe() dezelfde rol als Field(description=...) in Pydantic: het vertelt het model wat het veld moet bevatten, vooral wanneer de naam alleen dubbelzinnig is. Een score zonder beschrijving kan op een schaal van 0–100 terechtkomen; met een expliciet genoemd bereik volgt het uw conventie.
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"
),
});
Foutafhandeling
Het retry-patroon volgt dezelfde logica als in Python, met een generieke signatuur die het herbruikbaar maakt voor elk schema. Het is niet nodig een ZodError af te vangen: chat.parse() gooit deze niet; het laat parsed leeg. Dat geval, samen met netwerk- of HTTP-fouten, activeert een retry. De constraint z.ZodType<T> koppelt het schema dat als argument wordt doorgegeven aan het returntype: schema.parse() retourneert een T, zodat de aanroeper een correct getypeerd object krijgt zonder extra annotaties.
// Vervolg van hetzelfde bestand: client, z en BookSchema zijn al gedefinieerd
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); // herstelt type T
} catch (error) {
console.error(`Attempt ${attempt + 1} failed:`, error);
if (attempt === maxRetries) throw error;
}
}
throw new Error("Unexpected failure");
}
// Gebruik
try {
const book = await safeExtract("My text here", BookSchema);
console.log(book.title);
} catch (error) {
console.error("Extraction failed:", error);
}
Belangrijkste punten
- Zod is het TypeScript-equivalent van Pydantic voor aangepaste gestructureerde uitvoer
z.infer<typeof Schema>genereert automatisch het TypeScript-type.describe()voegt instructies per veld toe, zoalsField(description=...)in Python- De Mistral TypeScript SDK gebruikt
responseFormat(camelCase) in plaats vanresponse_format - Een niet-conform antwoord laat
parsedalsundefinedachter (geen uitzondering): test hierop en probeer het opnieuw indien nodig