Zod con JavaScript
In questa pagina
Output strutturati in JavaScript
Se sviluppi in JavaScript o TypeScript, Zod è l’equivalente di Pydantic. Questa libreria di validazione degli schemi si integra perfettamente con le API di Grok per produrre output strutturati tipizzati.
Installazione
npm install zod openai
L’SDK OpenAI per JavaScript funziona direttamente con le API di Grok: devi solo puntarlo all’endpoint corretto.
Configurazione del client
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "your-xai-key",
baseURL: "https://api.x.ai/v1"
});
Definizione di uno schema con Zod
Zod utilizza un’API fluida per definire gli schemi. Ogni metodo corrisponde a un tipo JSON:
import { z } from "zod";
const MovieReview = z.object({
title: z.string(),
rating: z.number(),
summary: z.string(),
recommend: z.boolean()
});
Mappatura dei tipi
| Zod | JSON Schema | Pydantic (Python) |
|---|---|---|
z.string() | "type": "string" | str |
z.number() | "type": "number" | float |
z.boolean() | "type": "boolean" | bool |
z.array(z.string()) | array di stringhe | list[str] |
z.object({...}) | "type": "object" | BaseModel |
z.enum([...]) | enum | Literal[...] |
z.union([...]) | anyOf | Tipi Unione |
z.nullable() | anyOf con null | str | None |
Esempio completo
import OpenAI from "openai";
import { z } from "zod";
const client = new OpenAI({
apiKey: "your-xai-key",
baseURL: "https://api.x.ai/v1"
});
const Analyse = z.object({
titre: z.string(),
resume: z.string(),
sentiment: z.enum(["positif", "negatif", "neutre"]),
score: z.number(),
mots_cles: z.array(z.string()),
recommandation: z.boolean()
});
const response = await client.chat.completions.create({
model: "grok-4.20-0309-reasoning",
messages: [{
role: "user",
content: "Analyze the following text: Sales increased by 25% this quarter."
}],
response_format: {
type: "json_schema",
json_schema: {
name: "analyse",
schema: Analyse
}
}
});
const data = JSON.parse(response.choices[0].message.content);
console.log(data.sentiment); // "positive"
console.log(data.score); // 0.92
Schemi annidati
Come Pydantic, Zod gestisce l’annidamento in modo naturale:
const Adresse = z.object({
rue: z.string(),
ville: z.string(),
code_postal: z.string(),
pays: z.string()
});
const Contact = z.object({
nom: z.string(),
email: z.string(),
telephone: z.string().nullable(),
adresse: Adresse,
tags: z.array(z.string())
});
Campi opzionali con nullable
Per rendere un campo opzionale (capace di essere null), usa .nullable():
const Produit = z.object({
nom: z.string(),
prix: z.number(),
description: z.string().nullable(),
promotion: z.number().nullable()
});
Validazione lato client
Un vantaggio di Zod è la possibilità di validare i dati lato client utilizzando lo stesso schema:
const rawData = JSON.parse(response.choices[0].message.content);
// Validazione con Zod
const result = Analyse.safeParse(rawData);
if (result.success) {
console.log(result.data.titre);
} else {
console.error("Validation error:", result.error);
}
In pratica, la validazione avrà sempre successo perché l’API garantisce la conformità allo schema. Tuttavia, questo livello aggiuntivo è utile per garantire robustezza in produzione.
Punti chiave
- Zod è l’equivalente di Pydantic per JavaScript/TypeScript
- La sintassi è fluida:
z.string(),z.number(),z.object({...}) .nullable()rende un campo opzionale (può esserenull)- Passa gli schemi Zod in
response_format.json_schema.schema safeParse()abilita la validazione difensiva lato client- L’SDK OpenAI per JavaScript funziona direttamente con le API di Grok