Quand utiliser Zod plutôt qu'une simple interface ?

Utilisez **Zod** (ou un autre validateur runtime comme Yup, Valibot, ArkType) quand les données **entrent dans votre app depuis l'extérieur** : réponse d'API, soumission de formulaire, **localStorage**, paramètre de requête. Une interface TypeScript est **effacée à la compilation**, elle n'arrête pas un serveur qui retourne des poubelles. Un **schéma Zod tourne au runtime** : parsez la réponse avec `schema.parse(data)` et vous obtenez soit un objet typé soit une vraie erreur à montrer à l'utilisateur. Avec **`z.infer `**, vous obtenez aussi le type statique, donc **une seule source de vérité** alimente runtime et compile time. Les interfaces simples restent bien pour les types internes qui ne franchissent jamais de frontière.

Pourquoi le générateur fait-il un type séparé pour chaque objet imbriqué ?

**Lisibilité et réutilisation.** Les types inline s'imbriquent visuellement comme ça : `{ customer: { id: number, name: string, address: { street: string, city: string } } }`, un mur d'accolades. Les types nommés vous laissent scanner la structure : **`Customer`**, **`Address`**, **`Order`**, vous voyez immédiatement ce qu'il y a dans vos données. La réutilisation vient gratuitement : si deux parties différentes de votre JSON ont la **même forme** (par ex. une `billingAddress` et une `shippingAddress`), le générateur **détecte le doublon** par signature structurelle et réutilise la même interface **`Address`** pour les deux.

Mon API retourne parfois `null` pour un champ. Dois-je le marquer optionnel ?

Trois options, trois sens différents : - **`field: string`** : le champ est **toujours là, toujours une string**. Utilisez quand le contrat le garantit. - **`field: string | null`** : le champ est **toujours là**, mais la valeur peut être **`string`** ou **explicitement null** (comme "pas encore de valeur"). Utilisez quand null signifie quelque chose. - **`field?: string`** : le champ est **parfois entièrement manquant** de l'objet. Utilisez quand l'API omet la clé. L'interrupteur **"Mark optional based on null"** vous donne la troisième forme : il suppose que **null = manquant** pour vos besoins. Désactivez-le si vous tenez à distinguer **manquant** de **explicitement null** (par ex. dans un JSON Patch ou des updates style MongoDB).

Que fait réellement "merge similar shapes" ?

Disons que votre JSON est `[{ "id": 1, "name": "A" }, { "id": 2, "title": "B" }]`. Deux objets, le second a **`title`** là où le premier a **`name`**. **Avec la fusion désactivée** : le type de tableau devient **`(Item1 | Item2)[]`**, deux types séparés, vous devez narrow avant de lire l'un ou l'autre champ. **Avec la fusion activée** : vous obtenez **un** type **`Item`** avec **`id: number, name?: string, title?: string`**, les deux champs sont optionnels parce qu'ils n'apparaissent que dans certains éléments. La fusion est plus accueillante pour les réponses d'API du monde réel où le backend ajoute paresseusement de nouveaux champs et les anciens enregistrements ont des nulls. Elle est plus permissive : si la différence entre deux éléments de tableau compte vraiment (différents discriminateurs `type` par exemple), désactivez la fusion et utilisez une union discriminée à la main.

Tableau vide `[]` en JSON : quel type j'obtiens ?

Un tableau vide ne contient **aucune valeur d'élément** donc le générateur **ne peut pas inférer le type d'élément**. Par défaut, il émet **`unknown[]`** (si vous avez activé "Use `unknown` over `any`") ou **`any[]`**. **Pourquoi c'est important : `any[]` vous laisse appeler n'importe quelle méthode sur l'élément sans avertissement** (source courante de bugs au runtime) ; **`unknown[]` vous force à narrow** (`if (typeof x === "string")`) avant de lire les champs. **Astuce pratique** : si vous connaissez le type d'élément mais que l'exemple JSON a juste un tableau vide, **éditez le type à la main après génération** (`Tag[]` au lieu de `unknown[]`), ou **collez un JSON exemple plus riche** avec au moins un élément dans le tableau pour que le générateur fasse ce qu'il faut.

Comment brancher la sortie Zod dans un formulaire existant ?

Trois lignes en plus de ce que le générateur émet : ```ts import { useForm } from 'react-hook-form'; import { zodResolver } from '@hookform/resolvers/zod'; import { rootSchema, type Root } from './generated'; const { register, handleSubmit, formState } = useForm ({ resolver: zodResolver(rootSchema), }); ``` Vous obtenez aussi des **erreurs de validation automatiquement** (plus de boilerplate "name must be a string") et des **valeurs de formulaire typées** gratuitement.

Mon JSON a des clés dupliquées avec des types différents. D'où ça vient ?

JSON lui-même n'autorise pas les clés dupliquées au même niveau (le parser garde la **dernière valeur**), vous ne voyez donc pas ça directement. Mais si **différents éléments de tableau ont un champ avec des types différents** (par ex. `[{ "id": 1 }, { "id": "two" }]`), le générateur produit une **union** : **`id: number | string`**. **Habituellement signe que votre API est désordonnée** : id devrait être un type. Corrigez sur le backend, régénérez. Si vous voulez vraiment les deux, c'est à ça que servent les unions, le type est correct.

Le générateur gère-t-il du JSON profondément imbriqué ?

Oui. Le walker est **depth-first** sans limite de récursion câblée, les objets profondément imbriqués (10+ niveaux) génèrent proprement. **Une chose à surveiller** : les structures récursives (un arbre où chaque nœud contient un tableau d'enfants du même type) sont émises comme **types séparés par niveau** par défaut. Si vous voulez un vrai type récursif (**`type Node = { children: Node[] }`**), tweakez les noms de types après coup, le générateur ne peut pas détecter "c'est le même type que le parent" depuis un seul exemple JSON.

Sortie JSON Schema : quel draft et est-ce compatible avec AJV ?

La sortie est en **Draft 2020-12** (le dernier draft stable), utilise **`$defs`** (le remplacement moderne de `definitions`) et **`$ref`** pour les formes partagées. **AJV** supporte 2020-12 avec le point d'entrée **`ajv-2020`** : `import Ajv from "ajv/dist/2020"`. **OpenAPI 3.1 est compatible** avec ce draft, collez le schéma directement dans la section **`components.schemas`** de votre spec. **OpenAPI 3.0** utilise une variante plus ancienne (il faudrait remplacer `$defs` par `definitions` et ajuster quelques mots-clés), le plus simple est d'upgrader la spec en 3.1.

JSON vers TypeScript - gratuit

export interface Customer { id: number; name: string; email: string; verified: boolean; phone?: null; } export interface Item { sku: string; title: string; qty: number; price: number; tags: string[]; } export interface Item2 { sku: string; title: string; qty: number; price: number; tags: unknown[]; } export interface Item3 { sku: string; title: string; qty: number; price: number; tags: string[] | unknown[]; } export interface Totals { subtotal: number; shipping: number; tax: number; grand: number; } export interface Root { id: string; created_at: string; customer: Customer; items: Item3[]; totals: Totals; notes?: null; }

Transformer un exemple JSON en types TypeScript prêts à l'emploi

Vous avez une réponse JSON d'une API et il vous faut un type TypeScript pour elle. Maintenant. Sans écrire chaque champ à la main, sans rater un objet imbriqué trois niveaux plus profond, sans oublier que le champ est parfois `null`. Collez le JSON à gauche, obtenez une `interface` propre à droite.

Le générateur détecte les objets imbriqués et donne à chacun son propre type nommé. Il parcourt les tableaux, choisit le type d'élément et émet `User[]` au lieu d'une longue forme inline. Si les clés sont parfois manquantes ou parfois null, il ajoute un `?`. Si votre tableau contient des objets aux champs légèrement différents, il les fusionne en une super-forme et marque les différences comme optionnelles.

Quatre formats de sortie : une `interface` TypeScript, un alias `type` TypeScript, un schéma runtime Zod (avec `z.infer` pour le type statique), ou un document JSON Schema (pour OpenAPI, AJV, tests de contrat). Tout s'exécute dans votre navigateur, rien ne quitte votre appareil.

Comment l'utiliser

Collez votre JSON dans le panneau de gauche. L'exemple par défaut est une réponse d'API de commande typique pour que vous voyiez le générateur en action tout de suite.
Choisissez un format de sortie : interface (le quotidien), alias type (pour les unions ou types mappés), Zod (quand il vous faut aussi de la validation runtime), ou JSON Schema (pour les specs OpenAPI et tests de contrat).
Définissez le nom du type racine (par défaut `Root`). Bons noms : `User`, `Order`, `ApiResponse`. Le générateur utilise votre nom pour le type top-level et dérive les noms enfants depuis les clés (par ex. `customer` devient `Customer`).
Activez `unknown` plutôt que `any` pour des types plus sûrs : les tableaux vides deviennent `unknown[]` au lieu de `any[]`, le système de types vous force à narrow avant utilisation.
Marquer optionnel basé sur null si votre API envoie parfois `"phone": null` : le générateur ajoute `phone?: string` au lieu de `phone: string | null`. Désactivez-le si vous voulez null explicite dans le type.
Convertir les clés en camelCase si votre JSON utilise du snake_case (`created_at`) et que votre code TypeScript utilise du camelCase (`createdAt`). La clé originale reste en commentaire pour que vous vous souveniez de ce qui est passé sur le réseau.
Fusionner les formes similaires quand un tableau contient des objets aux champs légèrement différents. Sans ça, vous obtenez une union verbeuse ; avec, vous obtenez une forme propre avec des `?` sur les différences.
Cliquez sur `Copy` pour mettre le résultat dans le presse-papiers ou `Download` pour le sauvegarder en fichier `.ts` (ou `.json` pour JSON Schema). Collez dans votre projet, terminé.

Quand c'est utile

Cinq situations où ça vous épargne 10 minutes de saisie manuelle :

Câbler un nouvel endpoint d'API. Vous frappez `/api/orders` et récupérez une grosse réponse JSON. Vous collez ici, obtenez les interfaces `Order`, `Customer`, `Item` en trois secondes. Vous les déposez dans `types.ts`, votre code autocomplète maintenant chaque champ correctement.
Migrer du JavaScript non typé vers TypeScript. L'ancien code lit des fichiers JSON et suppose la forme. Vous collez un exemple ici, obtenez les types, collez-les en haut du fichier : le compilateur trouve chaque endroit qui touche un champ manquant ou faux.
Construire un schéma Zod pour un formulaire. Vous connaissez la forme voulue (depuis un JSON exemple), il vous faut de la validation runtime. Basculez en mode Zod, obtenez `z.object({...})` avec les bons validateurs primitifs, déposez dans votre bibliothèque de formulaire (React Hook Form, Formik, TanStack Form).
Écrire une spec OpenAPI depuis une vraie réponse. Le backend retourne déjà du JSON, il vous faut le décrire en OpenAPI. Basculez en mode JSON Schema, obtenez un document Draft 2020-12 avec `$defs`, collez sous la section de réponse de votre endpoint. Terminé.
Partager un contrat avec une équipe frontend. Vous avez un payload JSON, vous devez dire à l'autre côté à quoi s'attendre. Générez l'interface, collez-la dans un message Slack ou un doc, les deux équipes ont la même source de vérité.

Vous partez d'une vraie spec ? Utilisez OpenAPI to TypeScript pour des types de requête/réponse complets ou GraphQL to TypeScript pour SDL.

Questions et réponses

Pour des formes d'objet simples, fonctionnellement identiques en TypeScript : les deux décrivent les champs, les deux marchent avec l'autocomplétion, les deux sont vérifiés de la même façon. La différence : `interface` peut être étendue (`interface User extends Person`) et fusionnée entre fichiers (declaration merging). `type` est plus flexible : il peut être une union (`type Status = "active" | "off"`), un type mappé, une intersection. Pour une sortie de cet outil, interface est le défaut le plus sûr : c'est ce que la plupart des équipes écrivent à la main. Utilisez `type` si vous voulez le combiner avec des unions ou des types utilitaires juste après.

Transformer un exemple JSON en types TypeScript prêts à l'emploi

Comment l'utiliser

Collez votre JSON dans le panneau de gauche. L'exemple par défaut est une réponse d'API de commande typique pour que vous voyiez le générateur en action tout de suite.

Choisissez un format de sortie : interface (le quotidien), alias type (pour les unions ou types mappés), Zod (quand il vous faut aussi de la validation runtime), ou JSON Schema (pour les specs OpenAPI et tests de contrat).

Définissez le nom du type racine (par défaut `Root`). Bons noms : `User`, `Order`, `ApiResponse`. Le générateur utilise votre nom pour le type top-level et dérive les noms enfants depuis les clés (par ex. `customer` devient `Customer`).

Activez `unknown` plutôt que `any` pour des types plus sûrs : les tableaux vides deviennent `unknown[]` au lieu de `any[]`, le système de types vous force à narrow avant utilisation.

Marquer optionnel basé sur null si votre API envoie parfois `"phone": null` : le générateur ajoute `phone?: string` au lieu de `phone: string | null`. Désactivez-le si vous voulez null explicite dans le type.

Convertir les clés en camelCase si votre JSON utilise du snake_case (`created_at`) et que votre code TypeScript utilise du camelCase (`createdAt`). La clé originale reste en commentaire pour que vous vous souveniez de ce qui est passé sur le réseau.

Fusionner les formes similaires quand un tableau contient des objets aux champs légèrement différents. Sans ça, vous obtenez une union verbeuse ; avec, vous obtenez une forme propre avec des `?` sur les différences.

Cliquez sur `Copy` pour mettre le résultat dans le presse-papiers ou `Download` pour le sauvegarder en fichier `.ts` (ou `.json` pour JSON Schema). Collez dans votre projet, terminé.

Quand c'est utile

Cinq situations où ça vous épargne 10 minutes de saisie manuelle :

Câbler un nouvel endpoint d'API. Vous frappez `/api/orders` et récupérez une grosse réponse JSON. Vous collez ici, obtenez les interfaces `Order`, `Customer`, `Item` en trois secondes. Vous les déposez dans `types.ts`, votre code autocomplète maintenant chaque champ correctement.
Migrer du JavaScript non typé vers TypeScript. L'ancien code lit des fichiers JSON et suppose la forme. Vous collez un exemple ici, obtenez les types, collez-les en haut du fichier : le compilateur trouve chaque endroit qui touche un champ manquant ou faux.
Construire un schéma Zod pour un formulaire. Vous connaissez la forme voulue (depuis un JSON exemple), il vous faut de la validation runtime. Basculez en mode Zod, obtenez `z.object({...})` avec les bons validateurs primitifs, déposez dans votre bibliothèque de formulaire (React Hook Form, Formik, TanStack Form).
Écrire une spec OpenAPI depuis une vraie réponse. Le backend retourne déjà du JSON, il vous faut le décrire en OpenAPI. Basculez en mode JSON Schema, obtenez un document Draft 2020-12 avec `$defs`, collez sous la section de réponse de votre endpoint. Terminé.
Partager un contrat avec une équipe frontend. Vous avez un payload JSON, vous devez dire à l'autre côté à quoi s'attendre. Générez l'interface, collez-la dans un message Slack ou un doc, les deux équipes ont la même source de vérité.

Vous partez d'une vraie spec ? Utilisez OpenAPI to TypeScript pour des types de requête/réponse complets ou GraphQL to TypeScript pour SDL.

Questions et réponses

JSON vers TypeScript

Transformer un exemple JSON en types TypeScript prêts à l'emploi

Comment l'utiliser

Quand c'est utile

Questions et réponses

Outils similaires

Formateur JSON

Convertisseur JSON / YAML / TOML

Convertisseur JSON ↔ CSV

JSON vers TypeScript

Transformer un exemple JSON en types TypeScript prêts à l'emploi

Comment l'utiliser

Quand c'est utile

Questions et réponses

Outils similaires

Formateur JSON

Convertisseur JSON / YAML / TOML

Convertisseur JSON ↔ CSV