Ir al contenido principal
Español— Elegir un idioma
Menú

Zod con JavaScript

Lección 7 de 12 Actualizado el 30 de julio de 2026 Desarrollador
En esta página
  1. Salidas estructuradas en JavaScript
  2. Instalación
  3. Configuración del cliente
  4. Definición de un esquema con Zod
  5. Mapeo de tipos
  6. Ejemplo completo
  7. Esquemas anidados
  8. Campos opcionales con nullable
  9. Validación en el lado del cliente
  10. Puntos clave

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

ZodJSON SchemaPydantic (Python)
z.string()"type": "string"str
z.number()"type": "number"float
z.boolean()"type": "boolean"bool
z.array(z.string())array de cadenaslist[str]
z.object({...})"type": "object"BaseModel
z.enum([...])enumLiteral[...]
z.union([...])anyOfTipos Union
z.nullable()anyOf con nullstr | 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 ser null)
  • 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