Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Zod com JavaScript

Aula 7 de 12 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Saídas estruturadas em JavaScript
  2. Instalação
  3. Configuração do cliente
  4. Definição de um esquema com Zod
  5. Mapeamento de tipos
  6. Exemplo completo
  7. Esquemas aninhados
  8. Campos opcionais com nullable
  9. Validação no lado do cliente
  10. Pontos-chave

Saídas estruturadas em JavaScript

Se está a desenvolver em JavaScript ou TypeScript, o Zod é o equivalente ao Pydantic. Esta biblioteca de validação de esquemas integra-se perfeitamente com a API do Grok para produzir saídas estruturadas tipadas.

Instalação

npm install zod openai

O SDK da OpenAI para JavaScript funciona diretamente com a API do Grok — basta apontá-lo para o endpoint correto.

Configuração do cliente

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-xai-key",
  baseURL: "https://api.x.ai/v1"
});

Definição de um esquema com Zod

O Zod utiliza uma API fluente para definir esquemas. Cada método mapeia para um tipo JSON:

import { z } from "zod";

const MovieReview = z.object({
  title: z.string(),
  rating: z.number(),
  summary: z.string(),
  recommend: z.boolean()
});

Mapeamento de tipos

ZodEsquema JSONPydantic (Python)
z.string()"type": "string"str
z.number()"type": "number"float
z.boolean()"type": "boolean"bool
z.array(z.string())array de stringslist[str]
z.object({...})"type": "object"BaseModel
z.enum([...])enumLiteral[...]
z.union([...])anyOfTipos Union
z.nullable()anyOf com nullstr | None

Exemplo 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 aninhados

Tal como o Pydantic, o Zod gere o aninhamento 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 opcionais com nullable

Para tornar um campo opcional (capaz de ser null), utilize .nullable():

const Produit = z.object({
  nom: z.string(),
  prix: z.number(),
  description: z.string().nullable(),
  promotion: z.number().nullable()
});

Validação no lado do cliente

Uma vantagem do Zod é a possibilidade de validar dados no lado do cliente utilizando o mesmo esquema:

const rawData = JSON.parse(response.choices[0].message.content);

// Validação com Zod
const result = Analyse.safeParse(rawData);

if (result.success) {
  console.log(result.data.titre);
} else {
  console.error("Validation error:", result.error);
}

Na prática, a validação será sempre bem-sucedida porque a API garante a conformidade com o esquema. No entanto, esta camada adicional é útil para garantir robustez em produção.

Pontos-chave

  • O Zod é o equivalente em JavaScript/TypeScript do Pydantic
  • A sintaxe é fluente: z.string(), z.number(), z.object({...})
  • .nullable() torna um campo opcional (pode ser null)
  • Passe esquemas Zod em response_format.json_schema.schema
  • safeParse() permite uma validação defensiva no lado do cliente
  • O SDK da OpenAI para JavaScript funciona diretamente com a API do Grok