Générer des types TypeScript à partir de JSON : un guide pratique

Comment fonctionne l'inférence JSON-vers-TypeScript

Un générateur parcourt l'arbre de valeurs JSON et mappe chaque type JavaScript vers son équivalent TypeScript : string reste string, number reste number, boolean reste boolean, null devient null (ou fusionne dans une union), les tableaux deviennent T[] où T est déduit des éléments, et les objets deviennent des interfaces imbriquées.

{
  "id": 42,
  "email": "ada@example.com",
  "isActive": true,
  "roles": ["admin", "editor"],
  "profile": {
    "displayName": "Ada",
    "avatarUrl": null
  }
}

interface Root {
  id: number;
  email: string;
  isActive: boolean;
  roles: string[];
  profile: {
    displayName: string;
    avatarUrl: string | null;
  };
}

Là où l'inférence doit deviner

Champs optionnels contre toujours présents : un seul échantillon JSON ne peut pas dire à un générateur si avatarUrl est parfois totalement absent (auquel cas ce devrait être avatarUrl?: string | null) ou toujours présent mais parfois null. Donnez au générateur quelques échantillons représentatifs, ou marquez manuellement un champ optionnel après génération si vous savez que l'API l'omet dans certaines conditions.

Nombres qui sont en réalité des identifiants contre des quantités : JSON n'a qu'un type number, mais TypeScript ne peut pas distinguer un identifiant entier d'un prix à virgule flottante sans contexte supplémentaire. Certains générateurs proposent des types brandés ou des unions littérales pour cela ; la plupart se contentent d'émettre number et vous laissent la distinction.

Tableaux vides : un tableau sans aucun exemple dedans ("tags": []) ne donne au générateur rien pour déduire le type des éléments — il retombe typiquement sur unknown[] ou any[]. Pointez le générateur vers un échantillon où le tableau est rempli, ou annotez-le manuellement ensuite.

Unions de littéraux de chaînes : un champ status toujours égal à "pending" | "active" | "closed" sera déduit en simple string, sauf si le générateur voit toutes les valeurs possibles dans l'échantillon — et même alors, la plupart des générateurs choisissent par défaut le type plus large string, sauf si vous activez explicitement l'inférence d'unions littérales.

Dates : JSON n'a pas de type date — les horodatages sont toujours des chaînes (ISO 8601) ou des nombres (epoch Unix). Un générateur typera un champ date en string ou number, pas Date ; vous devez toujours l'analyser vous-même après la récupération.

La même idée dans d'autres langages

La logique d'inférence — parcourir l'arbre, mapper les types, nommer les objets imbriqués — est identique quel que soit le langage cible ; seule la syntaxe de sortie change. Un struct Go reçoit la même correspondance de champs avec des tags de struct pour les noms de clés JSON ; une dataclass Python reçoit des indications de type et éventuellement un enveloppement Optional[...] ; une classe Java ou C# reçoit des champs typés et des accesseurs ou des records. Si votre équipe travaille sur plusieurs langages contre la même API, générer les types de chacun depuis le même échantillon JSON les garde alignés entre eux.

type Root struct {
	ID       int     `json:"id"`
	Email    string  `json:"email"`
	IsActive bool    `json:"isActive"`
	Roles    []string `json:"roles"`
	Profile  struct {
		DisplayName string  `json:"displayName"`
		AvatarURL   *string `json:"avatarUrl"`
	} `json:"profile"`
}

Avant de faire confiance aux types générés

Les types générés sont un bon point de départ, pas un contrat final. Avant de les committer : confirmez les champs optionnels contre la vraie documentation de l'API (pas juste un échantillon), remplacez les champs string trop lâches qui sont en réalité des enums par des unions littérales, vérifiez que les champs à tableau vide ont bien reçu un vrai type d'élément depuis un meilleur échantillon, et régénérez chaque fois que l'API en amont ajoute ou renomme un champ, plutôt que de retoucher l'interface à la main.