Zum Inhalt springen
Numio

TypeScript in JSON Schema umwandeln — Numio

Erzeugt mit ts-json-schema-generator ein draft-07 JSON Schema aus TypeScript-Typen. Jeder Typ landet unter "definitions"; optionale Properties fehlen in "required", und Objekte erhalten "additionalProperties": false.

Deine Request- und Response-Typen sind TypeScript-Interfaces, und du brauchst JSON Schema für Ajv-Validierung oder ein API-Gateway.

TypeScript

JSON Schema

Wann sie hilft

  • Deine Request- und Response-Typen sind TypeScript-Interfaces, und du brauchst JSON Schema für Ajv-Validierung oder ein API-Gateway.
  • Du willst ein Schema für eine JSON-Konfigurationsdatei veröffentlichen, deren Struktur bereits als TypeScript-Typ definiert ist.

Anwendung

  1. Füge TypeScript-Interfaces oder Typaliase ein. JSDoc-Tags wie @minimum, @format oder @pattern werden ins Schema übernommen.
  2. Der Quelltext wird an /api/typescript-to-json-schema gesendet, auf dem Server in eine temporäre Datei geschrieben und mit allen Typen als exponiert verarbeitet.
  3. Kopiere das JSON Schema. Enthält die Eingabe nur einen Typ, erhält die Wurzel zusätzlich einen $ref darauf.

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"
…

Details und Einschränkungen

Die Seite sendet deine Eingabe zur Konvertierung an eine Server-Route (/api/typescript-to-json-schema); sie wird nicht nur im Browser verarbeitet. Next.js-API-Routen akzeptieren standardmäßig Request-Bodys bis 1 MB.

JSDoc wird im erweiterten Modus geparst: Ein Beschreibungskommentar wird zu "description", und Tags wie @minimum 0 oder @minLength 1 werden zu Schlüsselwörtern.

Methoden in Interfaces werden übersprungen. Date wird zu einem string mit format date-time, und Literal-Unions werden zu enum.

bigint wird nicht unterstützt und liefert einen "Unknown node"-Fehler. Map und Set werden über ihr Interface beschrieben, ein Objekt mit nur einem numerischen size; verwende für JSON-Daten daher Record<string, T> oder Arrays.

FAQ

Werden nicht exportierte Typen einbezogen?

Ja. Jeder Typ in der Eingabe, exportiert oder nicht, wird zu "definitions" hinzugefügt, und Verweise untereinander verwenden $ref.

Wie werden optionale und nullable Properties dargestellt?

Optionale Properties fehlen in "required". Eine Union mit null wird zu anyOf mit {"type": "null"}.

Warum gibt es an der Wurzel einen $ref?

Bei einem einzigen Typ lässt der Generator die Wurzel per $ref darauf verweisen. Bei mehreren Typen wird nur "definitions" ausgegeben.

Spezifikationen und Referenzen