Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Zod con JavaScript

Lezione 7 di 12 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Output strutturati in JavaScript
  2. Installazione
  3. Configurazione del client
  4. Definizione di uno schema con Zod
  5. Mappatura dei tipi
  6. Esempio completo
  7. Schemi annidati
  8. Campi opzionali con nullable
  9. Validazione lato client
  10. Punti chiave

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

ZodJSON SchemaPydantic (Python)
z.string()"type": "string"str
z.number()"type": "number"float
z.boolean()"type": "boolean"bool
z.array(z.string())array di stringhelist[str]
z.object({...})"type": "object"BaseModel
z.enum([...])enumLiteral[...]
z.union([...])anyOfTipi Unione
z.nullable()anyOf con nullstr | 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ò essere null)
  • 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