Aller au contenu
Numio

Convertir TypeScript en JSON Schema — Numio

Génère un JSON Schema draft-07 à partir de types TypeScript avec ts-json-schema-generator. Chaque type est placé sous "definitions" ; les propriétés optionnelles sont exclues de "required" et les objets reçoivent "additionalProperties": false.

Vos types de requête et de réponse sont des interfaces TypeScript et vous avez besoin d’un JSON Schema pour la validation avec Ajv ou pour une passerelle API.

TypeScript

JSON Schema

Quand l’utiliser

  • Vos types de requête et de réponse sont des interfaces TypeScript et vous avez besoin d’un JSON Schema pour la validation avec Ajv ou pour une passerelle API.
  • Vous voulez publier un schéma pour un fichier de configuration JSON dont la forme est déjà définie par un type TypeScript.

Mode d’emploi

  1. Collez des interfaces ou des alias de type TypeScript. Les balises JSDoc comme @minimum, @format ou @pattern sont reprises dans le schéma.
  2. Le source est envoyé à /api/typescript-to-json-schema, écrit dans un fichier temporaire sur le serveur et traité avec tous les types exposés.
  3. Copiez le JSON Schema. Si l’entrée ne contient qu’un seul type, la racine reçoit aussi un $ref vers celui-ci.

TypeScript

/** A product in the catalog */
export interface Product {
  /** @minimum 0 */
  price: number;
  name: string;
  tags?: string[];
}

JSON Schema (draft-07)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$ref": "#/definitions/Product",
  "definitions": {
    "Product": {
      "type": "object",
      "properties": {
        "price": {
          "type": "number",
          "minimum": 0
        },
        "name": {
          "type": "string"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "price",
        "name"
…

Détails et limites

La page envoie votre saisie à une route serveur (/api/typescript-to-json-schema) pour la conversion ; elle n’est pas traitée uniquement dans le navigateur. Par défaut, les routes API de Next.js acceptent des corps de requête jusqu’à 1 Mo.

La JSDoc est analysée en mode étendu : un commentaire de description devient "description", et des balises comme @minimum 0 ou @minLength 1 deviennent des mots-clés.

Les méthodes des interfaces sont ignorées. Date devient une chaîne avec format date-time, et les unions de littéraux deviennent enum.

bigint n’est pas pris en charge et renvoie une erreur "Unknown node". Map et Set sont décrits par leur interface, un objet avec seulement une propriété size numérique ; utilisez donc Record<string, T> ou des tableaux pour des données JSON.

FAQ

Les types non exportés sont-ils inclus ?

Oui. Chaque type de l’entrée, exporté ou non, est ajouté à "definitions", et les références entre eux utilisent $ref.

Comment les propriétés optionnelles et nullables sont-elles représentées ?

Les propriétés optionnelles sont exclues de "required". Une union avec null devient anyOf avec {"type": "null"}.

Pourquoi y a-t-il un $ref à la racine ?

Avec un seul type, le générateur fait pointer la racine vers lui avec $ref. Avec plusieurs types, seul "definitions" est produit.

Spécifications et références