Vai al contenuto
Numio

Schema da TypeScript a JSON — Numio

Genera un JSON Schema draft-07 da tipi TypeScript con ts-json-schema-generator. Ogni tipo va in "definitions"; le proprietà facoltative restano escluse da "required" e gli oggetti ricevono "additionalProperties": false.

I tipi di richiesta e risposta sono interfacce TypeScript e hai bisogno dello schema JSON per la convalida Ajv o di un gateway API.

TypeScript

JSON Schema

Quando usarlo

  • I tipi di richiesta e risposta sono interfacce TypeScript e hai bisogno dello schema JSON per la convalida Ajv o di un gateway API.
  • Desideri pubblicare uno schema per un file di configurazione JSON la cui forma è già definita come tipo TypeScript.

Come si usa

  1. Incolla le interfacce TypeScript o digita gli alias. I tag JSDoc come @minimum, @format o @pattern vengono letti nello schema.
  2. Il sorgente viene elaborato in un Web Worker del browser. Il compilatore usa file virtuali in memoria ed espone tutti i tipi; non viene creato alcun file temporaneo su un server.
  3. Copia lo schema JSON. Se l'input ha un solo tipo, anche la root riceve un $ref.

TypeScript

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

Schema JSON (bozza-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"
…

Dettagli e limiti

La conversione avviene localmente in un Web Worker del browser; l’input non viene caricato su un server. Al primo utilizzo il browser scarica il modulo di conversione necessario.

JSDoc viene analizzato in modalità estesa: un commento descrittivo diventa "description" e tag come @minimum 0 oppure @minLength 1 diventano parole chiave.

I metodi nelle interfacce vengono saltati. La data diventa una stringa con il formato data-ora e le unioni letterali diventano enum.

bigint non è supportato e restituisce "Unknown node". Map e Set vengono descritti dalla loro interfaccia, un oggetto con il solo campo numerico size; usa quindi Record<string, T> o array per i dati JSON.

FAQ

Sono incluse le tipologie non esportate?

Sì. Ogni tipo dell’input, esportato o meno, viene aggiunto a "definitions" e i riferimenti tra tipi usano $ref.

Come vengono rappresentate le proprietà facoltative e nullable?

Le proprietà facoltative vengono escluse da "required". Un’unione con null diventa anyOf con {"type": "null"}.

Perché c'è un $ref alla radice?

Con un solo tipo, il generatore lo indica alla radice tramite $ref. Con più tipi, viene prodotto soltanto "definitions".

Specifiche e riferimenti