Przejdź do treści
Numio

Konwerter TypeScript na JSON Schema — Numio

Generuje JSON Schema draft-07 z typów TypeScript przy użyciu ts-json-schema-generator. Każdy typ trafia do "definitions"; właściwości opcjonalne są pomijane w "required", a obiekty otrzymują "additionalProperties": false.

Twoje typy żądań i odpowiedzi to interfejsy TypeScript i potrzebujesz schematu JSON do sprawdzania poprawności Ajv lub bramy API.

TypeScript

JSON Schema

Kiedy go używać

  • Twoje typy żądań i odpowiedzi to interfejsy TypeScript i potrzebujesz schematu JSON do sprawdzania poprawności Ajv lub bramy API.
  • Chcesz opublikować schemat pliku konfiguracyjnego JSON, którego kształt jest już zdefiniowany jako typ TypeScript.

Jak używać

  1. Wklej interfejsy TypeScript lub wpisz aliasy. Tagi JSDoc, takie jak @minimum, @format lub @pattern, są wczytywane do schematu.
  2. Kod jest przetwarzany lokalnie w przeglądarce przez kompilator z wirtualnym systemem plików w pamięci i opcją expose: "all". Nie powstaje plik tymczasowy na serwerze.
  3. Skopiuj schemat JSON. Jeśli dane wejściowe mają tylko jeden typ, root również otrzymuje do niego $ref.

TypeScript

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

Schemat JSON (wersja robocza 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"
…

Szczegóły i ograniczenia

Konwersja odbywa się lokalnie w Web Workerze w przeglądarce. Dane wejściowe nie są wysyłane na serwer konwersji. Wymagane moduły są pobierane przy pierwszym użyciu narzędzia.

JSDoc jest analizowany w trybie rozszerzonym: komentarz opisowy staje się "description", a znaczniki, np. @minimum 0 lub @minLength 1, stają się słowami kluczowymi.

Metody interfejsów są pomijane. Date staje się string z formatem date-time, a unie literałów stają się enum.

bigint nie jest obsługiwany i zwraca błąd "Unknown node". Map i Set są opisywane przez interfejs jako obiekt wyłącznie z liczbowym size, dlatego dla danych JSON użyj Record<string, T> lub tablic.

FAQ

Czy uwzględnione są typy niewyeksportowane?

Tak. Każdy typ w danych wejściowych, eksportowany lub nie, jest dodawany do "definitions", a odwołania między nimi używają $ref.

W jaki sposób reprezentowane są właściwości opcjonalne i dopuszczające wartość null?

Właściwości opcjonalne są pomijane w "required". Unia z null staje się anyOf z {"type": "null"}.

Dlaczego w katalogu głównym znajduje się $ref?

Przy jednym typie generator wskazuje go jako korzeń za pomocą $ref. Przy kilku typach wynik zawiera tylko "definitions".

Specyfikacje i referencje