Générer des types TypeScript depuis un Schema
L’essentiel : json-schema-to-typescript et quicktype émettent un .d.ts en une commande, mais c'est un brouillon : caractère facultatif, unions, additionalProperties et dates demandent une passe humaine.
L'essentiel : générez avec json-schema-to-typescript ou quicktype, puis corrigez à la main caractère facultatif, unions, additionalProperties et dates ; gardez Schema comme source et les types comme sortie, imposé par une étape types:check en CI.
Une commande vous donne un fichier. Elle ne vous donne pas des types corrects.
La ligne unique
npx json-schema-to-typescript schema.json > src/types/order.d.ts
Il gère $ref, allOf, oneOf, anyOf, et convertit description en JSDoc. Pour la génération par lots avec une bannière et un style choisi, appelez son API Node depuis un petit build-types.mjs.
quicktype est l'alternative, et peut aussi inférer un schéma depuis un JSON d'exemple :
npx quicktype -s schema schema.json -o order.ts --lang typescript
Quatre choses à corriger après
Le caractère facultatif. Tout ce qui n'est pas dans required devient ?. Mais « toujours présent, peut être null » et « peut être absent » sont des contrats différents :
interface Order {
remark?: string | null; // may be missing
status: string;
}
Si le backend envoie toujours remark: null, retirez le ? et cessez de faire garder undefined à chaque consommateur.
Les unions non discriminées. oneOf devient généralement A | B, que TypeScript ne peut pas rétrécir sans champ littéral. Ajoutez une propriété type fixe à chaque branche dans le Schema.
additionalProperties. Omis ou true produit parfois [k: string]: unknown, parfois any. Le premier est sûr, le second désactive silencieusement la vérification de type pour tout l'objet.
Les formats de date. format: "date-time" est une chaîne sur le fil. Le mapper sur Date signifie que vous devez aussi désérialiser, sinon la valeur à l'exécution reste une chaîne tandis que le type ment.
Gardez la direction fixe
Schema est la source, les types sont la sortie. Générer le Schema depuis des types écrits à la main n'est acceptable que si la régénération est obligatoire et imposée en CI — sinon les deux côtés dérivent et personne ne sait lequel fait autorité.
Mettez-le dans le pipeline
"types:gen": "json2ts -i schemas/ -o src/types/generated",
"types:check": "pnpm types:gen && git diff --exit-code src/types/generated"
types:check est la partie qui compte : changez le Schema sans régénérer et la CI échoue.
FAQ
Pourquoi le fichier généré contient-il any ?
Cela vient généralement de additionalProperties défini à true ou omis, que certains générateurs mappent sur [k: string]: any. Remplacez-le par unknown ou des champs explicites, car any désactive la vérification de type pour tout l'objet.
Comment corriger les champs facultatifs après génération ?
Tout ce qui est hors de required devient ?, mais « toujours présent, peut être null » diffère de « peut être absent ». Si le backend envoie toujours le champ, retirez le ?.
La CI doit-elle échouer quand Schema et types dérivent ?
Oui. Un script types:check qui régénère et lance git diff --exit-code fait échouer le build dès que le Schema change sans régénération.