Aller au contenu
Numio

Convertir JSON Schema en types TypeScript — Numio

Compile un JSON Schema en interfaces TypeScript avec json-schema-to-typescript. Les propriétés absentes de "required" deviennent optionnelles, et les objets reçoivent une signature d’index sauf si additionalProperties vaut false.

Votre API publie des fichiers JSON Schema et vous voulez des interfaces correspondantes pour le code client qui les consomme.

JSON Schema

TypeScript

Quand l’utiliser

  • Votre API publie des fichiers JSON Schema et vous voulez des interfaces correspondantes pour le code client qui les consomme.
  • Vous maintenez des fichiers de configuration validés par un schéma et voulez une vérification de types là où la configuration est chargée.

Mode d’emploi

  1. Collez un JSON Schema dans le panneau JSON Schema. Un "title" définit le nom de l’interface ; sans lui, la racine s’appelle MySchema.
  2. La conversion s’exécute dans le navigateur pendant la saisie ; la page n’a aucun paramètre et n’ajoute pas de commentaire d’en-tête.
  3. Copiez les interfaces du panneau TypeScript. La page les formate avec Prettier : indentation de deux espaces et pas de points-virgules.

JSON Schema

{
  "title": "Address",
  "type": "object",
  "properties": {
    "street": { "type": "string", "minLength": 1 },
    "zip": { "type": "string", "pattern": "^[0-9]{5}$" },
    "country": { "enum": ["US", "CA"], "default": "US" },
    "unit": { "type": ["integer", "null"] },
    "lines": { "type": "array", "items": { "type": "string" }, "maxItems": 3 },
    "geo": { "type": "object", "required": ["lat", "lng"],
      "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }
  },
  "required": ["street", "zip"]
}

Interfaces TypeScript

export interface Address {
  street: string
  zip: string
  country?: "US" | "CA"
  unit?: number | null
  lines?: [] | [string] | [string, string] | [string, string, string]
  geo?: {
    lat: number
    lng: number
    [k: string]: unknown
  }
  [k: string]: unknown
}

Détails et limites

Les objets sans "additionalProperties": false reçoivent [k: string]: unknown, si bien que le type autorise toujours des clés supplémentaires.

maxItems sur un tableau est développé en union de tuples, comme pour "lines" dans l’exemple.

Les entrées $ref locales comme #/definitions/Tag deviennent des interfaces exportées distinctes.

La page passe le résultat dans Prettier sans points-virgules, ce qui supprime aussi les parenthèses superflues autour d’unions comme "US" | "CA".

FAQ

Comment les valeurs null sont-elles typées ?

"type": ["integer", "null"] devient (number | null). integer et number sont tous deux mappés vers number.

Comment me débarrasser de [k: string]: unknown ?

Ajoutez "additionalProperties": false à chaque schéma d’objet ; la signature d’index est alors omise.

Comment l’interface racine est-elle nommée ?

À partir du "title" du schéma converti en PascalCase ("Example Schema" devient ExampleSchema). Sans title, le nom est MySchema.

Le schéma est-il envoyé à un serveur ?

Non. La fonction compile de json-schema-to-typescript s’exécute dans le navigateur sur cette page.

Spécifications et références