Zod con JavaScript
En esta página
Salidas estructuradas en JavaScript
Si desarrollas en JavaScript o TypeScript, Zod es el equivalente a Pydantic. Esta biblioteca de validación de esquemas se integra perfectamente con la API de Grok para generar salidas estructuradas con tipos definidos.
Instalación
npm install zod openai
El SDK de OpenAI para JavaScript funciona directamente con la API de Grok; solo tienes que apuntarlo al endpoint correcto.
Configuración del cliente
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "your-xai-key",
baseURL: "https://api.x.ai/v1"
});
Definición de un esquema con Zod
Zod utiliza una API fluida para definir esquemas. Cada método se asigna a un tipo JSON:
import { z } from "zod";
const MovieReview = z.object({
title: z.string(),
rating: z.number(),
summary: z.string(),
recommend: z.boolean()
});
Mapeo de tipos
| 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 de cadenas | list[str] |
z.object({...}) | "type": "object" | BaseModel |
z.enum([...]) | enum | Literal[...] |
z.union([...]) | anyOf | Tipos Union |
z.nullable() | anyOf con null | str | None |
Ejemplo 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
Esquemas anidados
Al igual que Pydantic, Zod gestiona el anidamiento de forma natural:
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())
});
Campos opcionales con nullable
Para hacer que un campo sea opcional (capaz de ser null), utiliza .nullable():
const Produit = z.object({
nom: z.string(),
prix: z.number(),
description: z.string().nullable(),
promotion: z.number().nullable()
});
Validación en el lado del cliente
Una ventaja de Zod es que puedes validar datos en el lado del cliente utilizando el mismo esquema:
const rawData = JSON.parse(response.choices[0].message.content);
// Validación con Zod
const result = Analyse.safeParse(rawData);
if (result.success) {
console.log(result.data.titre);
} else {
console.error("Validation error:", result.error);
}
En la práctica, la validación siempre tendrá éxito porque la API garantiza el cumplimiento del esquema. No obstante, esta capa adicional resulta útil para garantizar la robustez en entornos de producción.
Puntos clave
- Zod es el equivalente en JavaScript/TypeScript de Pydantic
- La sintaxis es fluida:
z.string(),z.number(),z.object({...}) .nullable()hace que un campo sea opcional (puede sernull)- Pasa los esquemas de Zod en
response_format.json_schema.schema safeParse()permite una validación defensiva en el lado del cliente- El SDK de OpenAI para JavaScript funciona directamente con la API de Grok