Zod avec JavaScript

Les structured outputs en JavaScript

Si vous développez en JavaScript ou TypeScript, Zod est l’équivalent de Pydantic. Cette bibliothèque de validation de schémas s’intègre parfaitement avec l’API Grok pour produire des sorties structurées typées.

Installation

npm install zod openai

Le SDK OpenAI pour JavaScript fonctionne directement avec l’API Grok — il suffit de pointer vers le bon endpoint.

Configuration du client

import OpenAI from "openai";

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

Définir un schéma avec Zod

Zod utilise une API fluide pour définir des schémas. Chaque méthode correspond à un type JSON :

import { z } from "zod";

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

Correspondance des types

Exemple complet

import OpenAI from "openai";
import { z } from "zod";

const client = new OpenAI({
  apiKey: "votre-cle-xai",
  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-reasoning",
  messages: [{
    role: "user",
    content: "Analyse le texte suivant : Les ventes ont augmenté de 25% ce trimestre."
  }],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "analyse",
      schema: Analyse
    }
  }
});

const data = JSON.parse(response.choices[0].message.content);
console.log(data.sentiment);  // "positif"
console.log(data.score);      // 0.92

Schémas imbriqués

Comme Pydantic, Zod gère naturellement l’imbrication :

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())
});

Champs optionnels avec nullable

Pour rendre un champ optionnel (pouvant valoir null), utilisez .nullable() :

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

Validation côté client

Un avantage de Zod : vous pouvez valider les données côté client avec le même schéma :

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

// Validation avec Zod
const result = Analyse.safeParse(rawData);

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

En pratique, la validation réussira toujours puisque l’API garantit la conformité au schéma. Mais cette couche supplémentaire est utile pour la robustesse en production.

Points clés à retenir

• Zod est l’équivalent JavaScript/TypeScript de Pydantic
• La syntaxe est fluide : z.string(), z.number(), z.object({...})
• .nullable() rend un champ optionnel (peut valoir null)
• Les schémas Zod se passent dans response_format.json_schema.schema
• safeParse() permet une validation défensive côté client
• Le SDK OpenAI pour JavaScript fonctionne directement avec l’API Grok