Zod 4 : le guide complet de la validation TypeScript

Zod est devenu, discrètement, le tissu conjonctif de la stack TypeScript moderne. Il valide les corps de requêtes de vos API, type vos variables d'environnement, façonne la sortie structurée des appels aux modèles d'IA et alimente les bibliothèques de formulaires, de React Hook Form à TanStack Form. Quand la bibliothèque de schémas la plus utilisée de l'écosystème publie une version majeure, toute équipe qui touche à TypeScript devrait y prêter attention.

Zod 4 est cette version majeure, et ce n'est pas un simple rafraîchissement cosmétique. Ses entrailles ont été réécrites pour des gains de vitesse spectaculaires, le bundle a été réduit de moitié et une vague de nouvelles API vient combler des lacunes anciennes. Ce guide passe en revue ce qui a changé, les fonctionnalités à adopter en premier et la façon de migrer depuis Zod 3 sans casser la production.

Pourquoi Zod 4 compte

Le titre, c'est la performance. Zod 4 analyse les chaînes environ 14 fois plus vite que Zod 3, les tableaux environ 7 fois plus vite et les objets environ 6,5 fois plus vite. Plus important encore pour les grandes bases de code, il réduit les instanciations de types TypeScript d'environ 100 fois : l'autocomplétion de l'éditeur et les builds tsc cessent de ramper sur les schémas profondément imbriqués. Le bundle d'exécution principal a fondu d'environ 57 pour cent.

Ce dernier chiffre mérite d'être souligné. Si vous expédiez Zod dans le navigateur au sein d'un flux de validation de formulaire ou d'une fonction edge, vous payiez une véritable taxe sur la taille du bundle. Zod 4 la divise par deux, et la nouvelle variante tree-shakable la réduit bien davantage.

Formats de chaînes au niveau supérieur

Dans Zod 3, les formats de chaînes étaient des méthodes chaînées : z.string().email(). Zod 4 les promeut en fonctions de niveau supérieur, plus rapides à l'analyse et mieux tree-shakées.

import * as z from "zod";
 
// Nouvelle forme, préférée
const Email = z.email();
const Id = z.uuidv7();
const Link = z.url();
const Token = z.jwt();
const Address = z.ipv4();
 
// Vous pouvez toujours personnaliser le motif de validation
const StrictEmail = z.email({ pattern: z.regexes.html5Email });

Les anciennes méthodes chaînées comme z.string().email() fonctionnent toujours mais sont dépréciées : le nouveau code devrait donc privilégier les fonctions de niveau supérieur. Zod 4 ajoute aussi des formats numériques précis comme z.int32(), z.uint32(), z.float64() et z.int64() pour les cas où la largeur en bits compte réellement.

Fichiers et coercition booléenne natifs

Deux ajouts pratiques suppriment du code répétitif que chaque équipe écrivait à la main. La validation de fichiers est désormais native, idéale pour les points de téléversement :

const Upload = z.file()
  .min(10_000)              // octets
  .max(1_000_000)
  .mime(["image/png", "image/webp"]);

Et z.stringbool() fait enfin ce que vous avez toujours voulu en lisant des variables d'environnement ou des chaînes de requête, en convertissant des valeurs textuelles approximatives en véritables booléens :

const FeatureFlag = z.stringbool();
FeatureFlag.parse("true");   // true
FeatureFlag.parse("yes");    // true
FeatureFlag.parse("0");      // false

Codecs : transformations bidirectionnelles

Les codecs sont l'idée la plus authentiquement nouvelle de Zod 4. Un codec décrit comment convertir entre deux représentations dans les deux sens : vous pouvez ainsi décoder un format entrant et le ré-encoder en sortie avec un seul schéma. L'exemple classique est une date au format ISO que vous voulez manipuler comme un véritable objet Date.

const ISODate = z.codec(
  z.iso.datetime(),   // schéma d'entrée
  z.date(),           // schéma de sortie
  {
    decode: (str) => new Date(str),
    encode: (date) => date.toISOString(),
  }
);
 
z.decode(ISODate, "2026-06-19T10:00:00Z"); // objet Date
z.encode(ISODate, new Date());             // chaîne ISO

Comme z.encode() et z.decode() fonctionnent avec n'importe quel schéma, pas seulement les codecs, vous pouvez construire une source de vérité unique pour analyser les données en entrée et les sérialiser en sortie. Cela élimine toute une catégorie de mappeurs manuels incohérents.

Des types récursifs plus propres

Les schémas récursifs exigeaient autrefois un appel z.lazy() malcommode et une annotation de type explicite. Zod 4 prend en charge la syntaxe getter : un arbre de catégories se type donc lui-même sans aucun cast.

const Category = z.object({
  name: z.string(),
  get subcategories() {
    return z.array(Category);
  },
});

Le type inféré est entièrement récursif, et votre éditeur le comprend.

Métadonnées, registres et JSON Schema

Zod 4 ajoute un système de métadonnées structuré via .meta() et un registre global, puis construit dessus une vraie interopérabilité. Vous pouvez attacher des titres et des descriptions à n'importe quel schéma et le convertir entièrement en JSON Schema, exactement ce qu'il faut pour les documents OpenAPI, la génération dynamique de formulaires ou les définitions d'appel de fonctions des modèles d'IA.

const User = z.object({
  id: z.uuidv7().meta({ description: "Clé primaire" }),
  email: z.email(),
  age: z.int().min(0).meta({ title: "Âge en années" }),
});
 
const jsonSchema = z.toJSONSchema(User);
// Prêt à alimenter OpenAPI ou la définition d'un outil d'IA

Cela dépasse de loin la documentation. Le schéma même qui valide vos données peut désormais générer le JSON Schema dont un modèle d'IA a besoin pour produire une sortie structurée, supprimant la duplication qui vivait jadis entre votre couche de validation et vos définitions d'outils.

De meilleures erreurs

La personnalisation des erreurs était éparpillée entre message, invalid_type_error, required_error et errorMap dans Zod 3. Zod 4 unifie le tout sous un unique paramètre error qui accepte une chaîne ou une fonction.

const Name = z.string({
  error: (issue) =>
    issue.input === undefined ? "Le nom est requis" : "Doit être une chaîne",
});

Pour présenter les échecs aux humains, z.prettifyError() transforme une erreur brute en une chaîne multiligne propre, et z.config(z.locales.en()) permet de traduire les messages dans les langues prises en charge, un vrai atout pour les produits multilingues courants sur les marchés de la région MENA.

Zod Mini pour l'edge

Si la taille du bundle est votre contrainte, zod/mini expose le même moteur de validation via une API fonctionnelle entièrement tree-shakable. Vous n'importez que les pièces que vous utilisez, et la logique du parseur reste partagée.

import * as z from "zod/mini";
 
const Schema = z.object({
  name: z.string(),
  email: z.optional(z.email()),
});

Le compromis porte sur l'ergonomie. Vous écrivez z.optional(z.string()) au lieu de z.string().optional(). Pour une fonction edge ou un bundle client sensible à la taille, c'est un juste prix pour une empreinte nettement plus petite.

Migrer depuis Zod 3

La plupart du code Zod 3 tourne sur Zod 4 sans changement, mais quelques motifs demandent de l'attention :

Paramètres d'erreur. Remplacez message, invalid_type_error, required_error et errorMap par le paramètre unifié error.
Formats de chaînes. Les méthodes chaînées comme .email() et .uuid() fonctionnent encore mais sont dépréciées. Migrez vers z.email() et z.uuidv4() au fil de vos modifications.
Refinements. .refine() n'enveloppe plus les schémas dans ZodEffects : vous pouvez donc chaîner librement des méthodes comme .min() après un refinement.
Littéraux. Utilisez z.literal([200, 201, 202]) au lieu d'envelopper plusieurs littéraux dans une union.

L'approche pragmatique consiste à mettre à jour la dépendance, lancer le vérificateur de types et la suite de tests, puis corriger la poignée d'avertissements de dépréciation de manière incrémentale plutôt que de tout réécrire d'un coup.

En conclusion

Zod 4 fait partie de ces rares versions majeures à la fois plus rapides et plus capables sans imposer de réécriture douloureuse. Les gains de performance et de taille de bundle justifient à eux seuls la mise à niveau, et les nouveaux codecs, l'export JSON Schema et le système de métadonnées positionnent Zod comme la colonne vertébrale des schémas pour les applications de l'ère de l'IA, où la même définition doit valider les données, documenter une API et décrire un outil à un modèle.

Si vous construisez des produits TypeScript aujourd'hui, la validation de schémas n'est plus une réflexion après coup boulonnée aux bords de votre application. C'est le contrat qui tient ensemble vos données, vos API et vos intégrations d'IA. Zod 4 rend ce contrat plus rapide à faire respecter et bien plus facile à réutiliser. Chez Noqta, nous considérons le typage fort et les frontières validées comme le fondement d'un logiciel fiable, et Zod 4 fait désormais partie par défaut de ce fondement.