JSON-Schema erstellen: So werden Typen erkannt (Draft-07)

VeröffentlichtToolJSON-Schema-Generator

Inhalt
  1. Sie haben eine API-Antwort und müssen das Schema von Hand schreiben?
  2. Draft-07-Schema ohne Tool von Hand schreiben
  3. Häufige Missverständnisse beim Lesen des Ergebnisses
  4. Zusammenfassung
  5. Häufig gestellte Fragen

Wenn Sie JSON-Daten einfügen und sofort ein JSON-Schema nach Draft-07 erhalten, liegt das daran, dass das Tool jeden einzelnen Wert rekursiv durchläuft und seinen Typ automatisch bestimmt.

Dieser Artikel richtet sich an Entwicklerinnen und Entwickler, die aus einer API-Antwort oder einer Konfigurationsdatei schnell Validierungsregeln ableiten müssen, und an alle, die wissen möchten, was Felder wie required und anyOf im Ergebnis genau bedeuten.

Behandelt werden nur die Regeln zur Typbestimmung und das Lesen des Ergebnisses. Wie ein Schema gut entworfen wird, ist nicht Thema dieses Artikels.

Zusammenfassung ① Der Typ eines Werts wird automatisch in dieser Reihenfolge bestimmt: null → Array → object/string/number/boolean. Zahlen in Anführungszeichen werden grundsätzlich als String behandelt. ② Haben alle Array-Elemente denselben Typ, wird items nur anhand des ersten Elements erzeugt. Sind die Typen gemischt, listet anyOf für jeden Typ ein Beispiel auf. ③ Ist „Alle Eigenschaften als Pflichtfelder festlegen" angehakt, landen alle Schlüssel des jeweiligen Objekts unverändert in required. Das Schema selbst ist nur eine Schätzung auf Grundlage des einen eingegebenen Beispiels.

Sie haben eine API-Antwort und müssen das Schema von Hand schreiben?

Stellen Sie sich vor, Sie haben vom Backend nur ein einziges Beispiel einer JSON-Antwort. Daraus sollen Sie ein JSON-Schema für Frontend-Validierung oder API-Dokumentation erstellen.

Schwierig wird es, sobald aus zehn Feldern zwanzig werden. Wenn Sie verschachtelte Objekte, Arrays und Werte mit null einzeln von Hand übertragen, vergessen Sie leicht eine Klammer oder ein Komma.

Besonders bei Arrays mit gemischten Typen sind die Syntax von anyOf und die Entscheidung, welche Felder in required gehören, jedes Mal eine Stolperstelle.

Draft-07-Schema ohne Tool von Hand schreiben

Ein JSON-Schema nach Draft-07 besteht aus einigen wenigen Schlüsselwörtern, die Sie kombinieren. So übertragen Sie einen Wert in ein Schema:

  • String → { "type": "string" }
  • Zahl (ohne Unterscheidung zwischen Ganz- und Dezimalzahl) → { "type": "number" }
  • Wahr/Falsch → { "type": "boolean" }
  • null → { "type": "null" }
  • Objekt → { "type": "object", "properties": { ... } }
  • Array → { "type": "array", "items": { ... } }

Die Regeln auf ein Beispiel-JSON anwenden

Wenden wir diese Regeln auf ein Beispiel-JSON an.

{
  "id": 1024,
  "zipCode": "06236",
  "name": "홍길동",
  "isActive": true,
  "note": null,
  "address": { "city": "서울", "district": "강남구" },
  "tags": ["vip", "return"],
  "history": [1, "pending", true]
}
  1. Der oberste Wert ist ein Objekt, daher beginnt das Schema mit "type": "object", und unter properties tragen Sie die Schlüssel einzeln ein.
  2. id ist eine Zahl ohne Anführungszeichen, also number. zipCode steht in Anführungszeichen und ist daher string. Ob der Wert Anführungszeichen hat oder nicht, ist das einzige Kriterium.
  3. Ist ein Wert wie bei address wiederum ein Objekt, wiederholen Sie darin type: object und properties.
  4. Haben bei einem Array wie tags alle Elemente denselben Typ, nehmen Sie eines als Vertreter und tragen nur diesen einen Typ in items ein. Sind die Elementtypen wie bei history gemischt, setzen Sie in items ein anyOf und listen für jeden vorkommenden Typ ein eigenes Schema auf.
  5. Welche Schlüssel in den Daten tatsächlich immer vorhanden sein müssen, entscheiden Sie selbst und tragen sie in das Array required ein. Das kann nur beurteilen, wer nicht nur ein Beispiel, sondern die gesamten realen Daten kennt.
  6. Schreiben Sie ganz oben "$schema": "http://json-schema.org/draft-07/schema#" hinein und ergänzen Sie bei Bedarf einen title.

Von Hand übertragen, sieht das Ergebnis so aus:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": { "type": "number" },
    "zipCode": { "type": "string" },
    "name": { "type": "string" },
    "isActive": { "type": "boolean" },
    "note": { "type": "null" },
    "address": {
      "type": "object",
      "properties": {
        "city": { "type": "string" },
        "district": { "type": "string" }
      }
    },
    "tags": { "type": "array", "items": { "type": "string" } },
    "history": {
      "type": "array",
      "items": {
        "anyOf": [
          { "type": "number" },
          { "type": "string" },
          { "type": "boolean" }
        ]
      }
    }
  }
}

Bei wenigen Feldern reicht es, diese Schritte einfach nachzuvollziehen. Je mehr Felder und je tiefer die Verschachtelung, desto mehr Arbeit macht es jedoch, dieselben Regeln von Hand immer wieder anzuwenden.

Mit unserem JSON-Schema-Generator prüfen.

JSON-Schema-Generator

Fügen Sie Ihr JSON ein, und der JSON-Schema-Generator erzeugt direkt im Browser ein Draft-07-Schema. Ihre Daten werden nicht an einen Server übertragen.

Häufige Missverständnisse beim Lesen des Ergebnisses

Hier sind die Stellen zusammengefasst, an denen beim Prüfen des erzeugten Schemas häufig Missverständnisse entstehen.

Häufiges MissverständnisTatsächliches Verhalten
Auch reine Zahlenwerte wie „06236" werden als number erkanntSteht ein Wert in Anführungszeichen, ist er immer vom Typ string
Ganzzahlen werden als integer, Dezimalzahlen als number unterschiedenMaßgeblich ist typeof, daher steht immer number, egal ob Ganz- oder Dezimalzahl
Das Häkchen bei required wählt nur die nötigen Felder ausMit Häkchen landen ausnahmslos alle Schlüssel des Objekts in required
Bei mehreren Array-Elementen werden alle geprüft und zusammengeführtHaben alle Elemente denselben Typ, wird items nur anhand des ersten Elements erzeugt
Das erzeugte Schema deckt alle möglichen Datenformen abEs ist nur das Ergebnis einer Schlussfolgerung aus dem einen eingegebenen Beispiel

Arrays aus Objekten und einige Ausnahmen

Bei Arrays, die nur aus Objekten bestehen, fällt diese Regel besonders auf. Werden alle Elemente als gleicher Typ „object" eingestuft, wird items.properties allein aus den Schlüsseln des ersten Objekts erzeugt.

Schlüssel, die nur im zweiten oder in späteren Objekten vorkommen, erscheinen im Schema überhaupt nicht. Wenn ein Feld in Ihren echten Daten vorhanden ist, im erzeugten Schema aber fehlt, liegt es meist an dieser Regel.

Bei einem leeren Array wird items mit {} befüllt, das keinerlei Einschränkung enthält. Ohne Elemente gibt es schlicht keine Grundlage, einen Typ zu bestimmen.

Lassen Sie das Eingabefeld für den Titel (title) leer, enthält das erzeugte Schema gar keinen title-Schlüssel. Erst wenn Sie einen Wert eintragen, wird title direkt unter $schema eingefügt.

Zusammenfassung

  • Der Typ eines Werts wird automatisch in der Reihenfolge null → Array → object/string/number/boolean bestimmt. Ob Anführungszeichen vorhanden sind, ist das einzige Kriterium zwischen String und Zahl.
  • Ganz- und Dezimalzahlen werden nicht unterschieden und immer als number ausgegeben.
  • Haben alle Elemente eines Arrays denselben Typ, wird items nur anhand des ersten Elements erzeugt. Bei gemischten Typen listet anyOf für jeden Typ ein Beispiel auf.
  • required entsteht nur bei aktiviertem Kontrollkästchen und enthält dann ausnahmslos alle Schlüssel des Objekts.
  • Das erzeugte Schema ist eine Schlussfolgerung aus dem einen eingegebenen Beispiel und deckt daher keine Felder oder Typkombinationen ab, die in diesem Beispiel nicht vorkamen.
JSON-Schema-Generator

Fügen Sie Ihr JSON ein, und der JSON-Schema-Generator erzeugt direkt im Browser ein Draft-07-Schema. Ihre Daten werden nicht an einen Server übertragen.

Häufig gestellte Fragen

Wie wird ein Wert, der nur aus Ziffern besteht (etwa eine Postleitzahl), im Schema dargestellt?

Entscheidend ist allein, ob der Wert in Anführungszeichen steht. Steht er wie bei "06236" in Anführungszeichen, wird er als String erkannt und ergibt { "type": "string" }.

Schreiben Sie den Wert ohne Anführungszeichen als 06236, ist das gar keine gültige JSON-Zahl (Zahlen mit einer führenden 0 sind in JSON ein Syntaxfehler). Dann wird bereits beim Parsen eine Fehlermeldung angezeigt.

Was passiert, wenn ein Array Werte unterschiedlicher Typen enthält?

Enthalten die Array-Elemente mehrere Typen, wird für jeden Typ ein Beispielwert herangezogen und daraus jeweils ein eigenes Schema erstellt. Diese Schemas werden in items als anyOf-Array zusammengefasst.

Enthält ein Array zum Beispiel Zahlen, Strings und Booleans, stehen in anyOf drei Typ-Schemas nebeneinander.

Was genau ändert das Kontrollkästchen „Alle Eigenschaften als erforderlich festlegen“?

Ist es aktiviert, werden für jeden Objektknoten sämtliche Schlüsselnamen dieses Objekts unverändert in das required-Array übernommen.

Eine Auswahl einzelner Schlüssel ist dabei nicht möglich. Wenn Sie das Kontrollkästchen deaktivieren, entsteht bei keinem Objekt ein required-Array.

Kann ich mit einem generierten Schema alle echten Daten validieren?

Das generierte Schema ist das Ergebnis der Analyse eines einzigen JSON-Beispiels, das Sie in das Eingabefeld eingefügt haben. In echten Daten kann dasselbe Feld mit einem anderen Typ auftreten, oder es kommen Felder hinzu, die im Beispiel nicht vorhanden waren.

Das Schema deckt daher nicht automatisch alle Fälle in Ihren echten Daten ab. Benötigen Sie ein Schema, das mehrere Situationen abdeckt, können Sie mehrere repräsentative Beispiele nacheinander eingeben und die Ergebnisse miteinander vergleichen.

Dieser Artikel basiert auf unserem koreanischen Original. Koreanisches Original lesen

Ähnliche Artikel

  1. JSON Syntaxfehler: Ursachen anhand der Fehlermeldung findenWas die Position in JSON-Fehlermeldungen bedeutet und wie Sie typische Syntaxfehler wie Trailing Comma, einfache Anführungszeichen und Kommentare erkennen.
  2. JSON in TypeScript umwandeln: ? und | in Interfaces lesenWann steht in einem aus JSON erzeugten TypeScript-Interface ein Fragezeichen (optional) oder ein Union-Typ mit |? Die Regeln, gezeigt an einem JSON-Beispiel.
  3. JSON zu YAML: Regeln für Arrays und EinrückungWie aus JSON-Arrays YAML-Listen mit Bindestrich werden, was 2 oder 4 Leerzeichen Einrückung ändern und welche Fehler bei Kubernetes und Docker oft passieren.
  4. JSONPath-Syntax erklärt: Was $, [*] und .. auswählenWas $, .Eigenschaft, [Zahl], [*] und .. in JSONPath auswählen, gezeigt an einem Beispiel-JSON. Dazu: warum Filterausdrücke und Slices hier nicht greifen.
  5. JWT dekodieren: Aufbau, Payload lesen und exp in DatumJWT ist nur Base64URL-kodiert, nicht verschlüsselt. So lesen Sie Header und Payload aus und wandeln exp und iat in ein lesbares Datum um.
  6. JWT-Signatur prüfen: Warum die Verifizierung fehlschlägtSo funktioniert die JWT-Prüfung mit HMAC-SHA256: Aufbau des Tokens, Signaturberechnung und die zwei Ursachen für fehlgeschlagene Verifizierung.

Passende Tools