Convertisseur JSON vers TypeScript : interfaces et types (guide 2026)
Le moyen le plus rapide de passer de JSON à TypeScript consiste à coller votre charge utile dans un convertisseur JSON vers TypeScript et à copier l’interface générée. Rien à installer, rien à téléverser, tout se passe dans votre navigateur. Cela couvre le cas « j’ai besoin de types tout de suite ».
Mais générer des types et générer de bons types sont deux choses différentes. Un convertisseur doit deviner : ce champ est-il optionnel, ou simplement absent d’un seul échantillon ? Ce tableau contient-il toujours des chaînes, ou parfois aussi des nombres ? La chaîne de date doit-elle devenir un Date ? Ce guide explique comment l’inférence fonctionne réellement, quand opter pour interface plutôt que type, et les pièges qui vous attendent lorsqu’on transforme des réponses d’API en direct en types dignes de confiance.
Comment convertir JSON en TypeScript
Convertir JSON en TypeScript se fait en trois étapes :
- Collez votre JSON. Déposez un objet, un tableau ou une réponse d’API brute dans la zone de saisie. La conversion s’exécute instantanément, entièrement côté client.
- Ajustez le résultat. Choisissez
interfaceoutype, définissez un nom racine commeUserouApiResponse, activez ou non le mot-cléexport, et optez pour?:ou| nullpour les champs optionnels. - Copiez ou téléchargez. Récupérez le TypeScript généré en un clic et collez-le directement dans votre base de code.
Voilà pour le chemin transactionnel. Le convertisseur JSON vers TypeScript lit la saisie, infère une arborescence de types et affiche les définitions à droite, sans que rien ne quitte la page. Le reste de ce guide vise à comprendre ce qu’il a produit, afin que vous puissiez corriger les cas qu’il ne peut pas deviner.
Comment les types JSON correspondent à TypeScript
Chaque valeur JSON a son équivalent TypeScript. La correspondance est presque toujours biunivoque :
| Valeur JSON | Type TypeScript |
|---|---|
"text" | string |
42, 3.14 | number |
true / false | boolean |
null | null |
[1, 2, 3] | number[] |
{ ... } | interface ou type |
C’est avec les objets que le travail commence. Prenons une charge utile REST typique pour un utilisateur :
{
"id": 101,
"name": "Ada Lovelace",
"email": "ada@example.com",
"active": true,
"roles": ["admin", "user"]
}Un convertisseur produit cette interface TypeScript à partir du JSON :
export interface User {
id: number;
name: string;
email: string;
active: boolean;
roles: string[];
}Chaque scalaire correspond à son type primitif, et le tableau roles devient string[]. Déposez cela dans votre client d’API et vous obtenez d’emblée l’autocomplétion et les vérifications à la compilation.
Comment le convertisseur infère les types
La partie intéressante, c’est l’algorithme d’inférence. Quatre règles couvrent presque tout ce que vous lui soumettrez.
Inférence structurelle : une interface nommée par objet
Chaque forme d’objet distincte devient sa propre interface nommée. Les objets imbriqués ne s’effondrent pas en types en ligne ; ils sont extraits dans des définitions séparées et référencées :
{
"order": {
"id": "A-1",
"total": 42.5,
"customer": { "name": "Sam", "vip": false }
}
}export interface Root {
order: Order;
}
export interface Order {
id: string;
total: number;
customer: Customer;
}
export interface Customer {
name: string;
vip: boolean;
}Les formes identiques sont dédupliquées : deux champs ayant la même structure partagent donc une seule interface au lieu de produire des copies.
Fusion de tableaux : inférer les champs optionnels
Lorsque vous passez un tableau d’objets, le convertisseur les fusionne clé par clé. Si une clé apparaît dans certains éléments mais pas dans d’autres, elle est marquée comme optionnelle :
{
"users": [
{ "id": 1, "nick": "x" },
{ "id": 2 }
]
}export interface Root {
users: User[];
}
export interface User {
id: number;
nick?: string;
}id est présent dans chaque élément, il reste donc obligatoire. nick est absent du second utilisateur, il devient donc nick?: string. C’est pourquoi un seul échantillon suffit rarement, comme le montre la section des pièges ci-dessous.
Types union pour les tableaux mixtes
Les tableaux n’ont pas à être homogènes. Lorsque les éléments ont des types différents, le convertisseur les rassemble en une union :
{
"tags": ["a", "b"],
"meta": [1, "two"]
}export interface Root {
tags: string[];
meta: (string | number)[];
}tags ne contient que des chaînes, d’où string[]. meta mélange un nombre et une chaîne, produisant (string | number)[]. Un tableau vide ne peut pas être inféré du tout et retombe sur unknown[], ce qui reste honnête : il n’y a rien à apprendre de zéro élément.
Optionnel vs null : ?: versus | null
Ces deux notations se ressemblent mais ont des sens différents. Un champ marqué ?: peut être totalement absent de l’objet. Un champ typé | null est toujours présent mais peut contenir la valeur null :
{ "score": null }export interface Root {
score: number | null;
}Ici, score est présent avec un null explicite, il est donc typé number | null : la valeur existe, elle est simplement null. Comparez cela avec nick?: string de l’exemple de tableau, où la clé peut être totalement absente. Optez pour ?: lorsque l’API peut omettre la clé, et pour | null lorsqu’elle envoie la clé avec une valeur null. La plupart des convertisseurs vous laissent contrôler ce rendu à l’aide d’un commutateur.
interface vs type : lequel utiliser ?
Les deux peuvent décrire la forme d’un objet. Voici comment décider :
| Besoin | Utiliser |
|---|---|
| Forme d’objet simple issue de JSON | interface |
Union (A | B) ou intersection (A & C) | type |
| Fusion de déclarations / extension entre fichiers | interface |
| Types mappés ou conditionnels | type |
| Messages d’erreur de l’éditeur légèrement plus propres | interface |
Pour des données issues d’un objet JSON, interface est le choix conventionnel et produit des erreurs de compilation un peu plus agréables. Dès que vous avez besoin d’une union, par exemple un Result qui est soit un succès, soit une erreur, vous devez passer à un type, car les interfaces ne peuvent pas exprimer d’unions :
type ApiResult =
| { status: "ok"; data: User }
| { status: "error"; message: string };Un bon réglage par défaut : générer une interface pour les objets JSON simples, et convertir en type lorsque la forme nécessite une union ou une intersection. Le manuel TypeScript couvre les cas particuliers si vous voulez la comparaison complète. Lorsque vous avez besoin d’un alias json to typescript type plutôt que d’une interface, la plupart des convertisseurs proposent un simple commutateur pour basculer l’intégralité du résultat.
quicktype vs json-to-ts vs outils en ligne vs manuel
Il n’existe pas de seule meilleure façon de générer des types TypeScript : tout dépend de l’endroit où vit le JSON et de la fréquence à laquelle il change.
| Approche | Idéal pour | Compromis |
|---|---|---|
| quicktype | Sortie multi-langages, génération de code de validation à l’exécution | Plus lourd ; davantage de sortie que ce dont vous avez souvent besoin |
| json-to-ts (bibliothèque) | Génération de code à la compilation, intégrée à un script ou un pipeline | Nécessite une configuration et une chaîne d’outils Node |
| Outil en ligne dans le navigateur | Conversions ponctuelles, charges utiles sensibles, zéro installation | Collage manuel à chaque fois |
| Écrire les types à la main | Petits objets, apprentissage du système de types | Fastidieux et sujet aux erreurs à grande échelle |
Choisissez quicktype lorsque vous avez besoin de types dans plusieurs langages ou que vous voulez qu’il émette des validateurs en plus des types. Choisissez la bibliothèque json-to-ts lorsque la conversion fait partie d’une étape de build. Pour une conversion rapide, surtout d’une charge utile contenant des jetons, des identifiants client ou tout ce que vous préféreriez ne pas coller dans un service distant, un outil dans le navigateur reste imbattable côté confidentialité et rapidité. Notre convertisseur JSON vers TypeScript s’exécute entièrement côté client : le JSON ne quitte jamais la page, et il n’y a rien à installer ni à mettre à jour.
Les types ne sont pas de la validation : faire le pont avec les vérifications à l’exécution
Cela fait trébucher beaucoup d’équipes, alors disons-le clairement : les types TypeScript sont effacés à la compilation et ne font rien à l’exécution. Une interface User générée ne vérifiera pas qu’une véritable réponse d’API y correspond. Si le serveur envoie id sous forme de chaîne au lieu d’un nombre, TypeScript croit volontiers votre annotation de type pendant que les données réelles mentent.
Pour generate typescript types et les faire respecter sur des données en direct, associez les types à un validateur à l’exécution :
- zod — définissez un schéma une fois, inférez-en le type statique, et analysez les réponses à l’exécution.
- io-ts — validation basée sur des codecs, populaire dans les bases de code fonctionnelles.
- JSON Schema + Ajv — schémas agnostiques au langage, validés à l’exécution, utiles lorsque le contrat est partagé entre services.
Un schéma courant consiste à générer l’interface pour le support de l’éditeur, puis à écrire un schéma zod correspondant comme véritable vérification de frontière :
import { z } from "zod";
const UserSchema = z.object({
id: z.number(),
name: z.string(),
email: z.string().email(),
active: z.boolean(),
roles: z.array(z.string()),
});
type User = z.infer<typeof UserSchema>;
// Lève une erreur si la réponse réelle ne correspond pas au schéma.
const user = UserSchema.parse(await res.json());Si vous partez sur la voie des schémas, notre guide de validation JSON Schema explique comment écrire et faire respecter des schémas de bout en bout.
Pièges courants lors du typage de JSON
Les types générés sont un point de départ, pas un produit fini. Méfiez-vous de ce qui suit.
snake_case vs camelCase. Les convertisseurs conservent les clés telles quelles. Une charge utile de style GitHub avec public_repos produit public_repos: number, et non publicRepos. Si votre base de code préfère le camelCase, vous devrez soit composer avec les types en snake_case, soit ajouter une couche de mappage qui renomme les champs à l’entrée.
Les chaînes de date restent des string. Un champ comme "2026-06-01T00:00:00Z" est typé string, et non Date. C’est délibéré : JSON n’a pas de type date, et deviner faux est pire qu’être honnête. La conversion de chaîne en Date revient à votre couche d’analyse, là où vous la contrôlez.
Fuites de any et unknown. Les tableaux vides deviennent unknown[] et les structures profondément mixtes peuvent se dégrader en types lâches. Ce ne sont pas des bugs ; c’est le convertisseur qui admet qu’il ne peut pas inférer à partir de données insuffisantes. Resserrez-les à la main une fois que vous connaissez la forme réelle.
Explosion d’imbrication profonde. Une charge utile fortement imbriquée génère une longue chaîne de petites interfaces. C’est généralement très bien et plus lisible qu’un unique type en ligne géant, mais il vaut la peine d’aplatir les formes qui ne méritent pas leur propre nom.
Le piège de l’échantillon unique. C’est le grand piège. Les champs optionnels ne peuvent être inférés qu’à partir de plusieurs éléments de tableau : un seul objet ne peut pas indiquer au convertisseur quelles clés sont parfois absentes. Rassemblez d’abord un tableau représentatif de réponses. Un formateur JSON est pratique pour coller et inspecter plusieurs échantillons côte à côte avant de convertir, et si vous alimentez une entrée non standard comme du JSONC, lisez notre guide JSON5 / JSONC, car le convertisseur a besoin d’un JSON strictement valide.
Foire aux questions
Comment convertir JSON en interface TypeScript ?
Collez votre JSON dans un convertisseur JSON vers TypeScript. Il lit la saisie dans votre navigateur et génère une interface TypeScript instantanément. Cliquez sur Copier pour récupérer le résultat : aucun téléversement, aucun compte, aucun plugin à installer.
Dois-je utiliser interface ou type pour des données JSON ?
Utilisez interface pour les formes d’objet simples issues de JSON : c’est conventionnel et cela donne des erreurs d’éditeur un peu plus claires. Passez à type lorsque vous avez besoin d’une union ou d’une intersection, car les interfaces ne peuvent pas les exprimer.
Comment les objets et tableaux imbriqués sont-ils gérés ?
Les objets imbriqués deviennent des interfaces séparées et nommées (un champ address produit une interface Address). Les tableaux d’objets sont fusionnés clé par clé en une seule interface d’élément ; les tableaux de primitifs deviennent des tableaux typés comme string[].
Comment les champs optionnels et null sont-ils typés ?
Une clé absente de certains éléments de tableau est marquée comme optionnelle (nick?: string). Une clé toujours présente mais qui contient null est typée avec | null (score: number | null). Les deux décrivent des situations différentes : absente, versus présente mais null.
Les types TypeScript valident-ils le JSON à l’exécution ?
Non. Les types TypeScript sont effacés à la compilation et ne vérifient pas les données à l’exécution. Pour valider une véritable réponse d’API, associez les types générés à un validateur à l’exécution comme zod, io-ts, ou JSON Schema avec Ajv.
quicktype vs json-to-ts vs un convertisseur en ligne : lequel est le meilleur ?
quicktype convient à la sortie multi-langages et aux validateurs à l’exécution ; la bibliothèque json-to-ts convient à la génération de code à la compilation ; un convertisseur en ligne convient aux conversions rapides, privées et ponctuelles avec zéro installation. Pour les charges utiles sensibles, un outil de navigateur côté client garde les données hors de tout serveur.
Pourquoi les chaînes de date sont-elles typées string au lieu de Date ?
JSON n’a pas de type date, donc une date n’est qu’une chaîne sur le réseau. La typer en string est honnête et stable ; la convertir en Date est une décision pour votre couche d’analyse, là où vous contrôlez le format et la gestion des erreurs.
Mes données JSON sont-elles privées avec un convertisseur en ligne ?
Avec un outil côté client, oui. La conversion s’exécute entièrement dans votre navigateur à l’aide de JavaScript, de sorte que le JSON (y compris les jetons, les identifiants et les données client) ne quitte jamais la page et n’est jamais envoyé à un serveur.