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

Inhalt
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
itemsnur anhand des ersten Elements erzeugt. Sind die Typen gemischt, listetanyOffür jeden Typ ein Beispiel auf. ③ Ist „Alle Eigenschaften als Pflichtfelder festlegen" angehakt, landen alle Schlüssel des jeweiligen Objekts unverändert inrequired. 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]
}
- Der oberste Wert ist ein Objekt, daher beginnt das Schema mit
"type": "object", und unterpropertiestragen Sie die Schlüssel einzeln ein. idist eine Zahl ohne Anführungszeichen, also number.zipCodesteht in Anführungszeichen und ist daher string. Ob der Wert Anführungszeichen hat oder nicht, ist das einzige Kriterium.- Ist ein Wert wie bei
addresswiederum ein Objekt, wiederholen Sie darintype: objectundproperties. - Haben bei einem Array wie
tagsalle Elemente denselben Typ, nehmen Sie eines als Vertreter und tragen nur diesen einen Typ initemsein. Sind die Elementtypen wie beihistorygemischt, setzen Sie initemseinanyOfund listen für jeden vorkommenden Typ ein eigenes Schema auf. - Welche Schlüssel in den Daten tatsächlich immer vorhanden sein müssen, entscheiden Sie selbst und tragen sie in das Array
requiredein. Das kann nur beurteilen, wer nicht nur ein Beispiel, sondern die gesamten realen Daten kennt. - Schreiben Sie ganz oben
"$schema": "http://json-schema.org/draft-07/schema#"hinein und ergänzen Sie bei Bedarf einentitle.
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.
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ändnis | Tatsächliches Verhalten |
|---|---|
| Auch reine Zahlenwerte wie „06236" werden als number erkannt | Steht ein Wert in Anführungszeichen, ist er immer vom Typ string |
| Ganzzahlen werden als integer, Dezimalzahlen als number unterschieden | Maßgeblich ist typeof, daher steht immer number, egal ob Ganz- oder Dezimalzahl |
| Das Häkchen bei required wählt nur die nötigen Felder aus | Mit Häkchen landen ausnahmslos alle Schlüssel des Objekts in required |
| Bei mehreren Array-Elementen werden alle geprüft und zusammengeführt | Haben alle Elemente denselben Typ, wird items nur anhand des ersten Elements erzeugt |
| Das erzeugte Schema deckt alle möglichen Datenformen ab | Es 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
itemsnur anhand des ersten Elements erzeugt. Bei gemischten Typen listetanyOffür jeden Typ ein Beispiel auf. requiredentsteht 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.
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