Häufige Fehler beim Erstellen von JSON-Schemata

Das erforderliche Array vergessen

Wenn Sie unter Eigenschaften eine Eigenschaft hinzufügen, beschreiben Sie nur deren Form, nicht deren Anwesenheit. Wenn das erforderliche Array diesen Schlüssel auslässt, validiert eine Instanz ohne dieses Feld erfolgreich. Dies ist ein stilles Übergehen, da der Validator die Eigenschaft als optional behandelt. Ich habe Teams gesehen, die APIs ausgeliefert haben, bei denen ein kritischer Identifikator in der erforderlichen Liste fehlte, was zu nachgelagerten Nullzeigern-Fehlern führte, die nur in der Produktion auftraten.

Zum Beispiel sollte ein Benutzerschema, das eine ID erwartet, Folgendes enthalten:

{ "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id"] } Ohne die Zeile "required" würde ein Objekt mit nur {"name":"Ada"} erfolgreich validieren, obwohl die API später die ID als obligatorisch behandelt.

AdditionalProperties offen lassen

Der Standardwert von additionalProperties ist true. Dies ermöglicht es jedem Schlüssel, der nicht in properties definiert ist, die Validierung zu passieren. Ein Tippfehler wie "user_name" anstelle von "username" wird dann zu einem stillschweigend akzeptierten Feld, das das Datenmodell verunreinigt und spätere Migrationen erschwert. Ich habe gesehen, wie Teams Wochen damit verbracht haben, verirrte Schlüssel zu bereinigen, die in die Datenbank gelangt sind, weil das Schema sie nie abgelehnt hat.

Hier ist eine strenge Version eines Produktschemas:

{ "type": "object", "properties": { "sku": { "type": "string" }, "price": { "type": "number", "minimum": 0 } }, "required": ["sku","price"], "additionalProperties": false } Mit diesem Schema schlägt eine Instanz, die {"sku":"ABC","price":10,"extra":1} enthält, die Validierung fehl, wodurch der Tippfehler frühzeitig erkannt wird.

Falsche Verwendung von Typ-Unionen

Das Schlüsselwort "type" erwartet entweder eine Zeichenkette oder ein Array von Zeichenketten. Das Schreiben von "type": "string, number" ist ungültiges JSON-Schema; der Parser behandelt den gesamten Wert als einen einzelnen unbekannten Typ, den viele Validator stillschweigend ignorieren und es somit ermöglichen, dass jeder Wert akzeptiert wird. Ein weiterer häufiger Fehler ist das Auslassen des Typs für ein optionales Feld, was dazu führt, dass der Validator die Typprüfung für diesen Schlüssel überspringt.

Beispiel für ein nullable Datum-Feld:

{ "type": "object", "properties": { "issuedAt": { "type": ["string","null"], "format": "date-time" } }, "required": ["issuedAt"] } Hier ist null erlaubt, sodass {"issuedAt":null} akzeptiert wird, während {"issuedAt":"not-a-date"} fehlschlägt.

$ref-Fallen und Versiondrift

Ein $ref, der zu einem fehlenden Speicherort aufgelöst wird, verursacht, dass das gesamte Schema bei der Ladezeit fehlschlägt, was laut und leicht zu erkennen ist. Das ruhigere Problem ist ein Verweis, der aufgelöst wird, aber auf die falsche Definition verweist, weil die Entwurfsversion geändert wurde oder die Ordnerstruktur verschoben wurde. Im Entwurf 2020-12 wurde das Schlüsselwort für wiederverwendbare Blöcke von definitions zu $defs verschoben. Wenn Sie den alten Schlüssel beibehalten, validiert das Schema immer noch (das ältere Schlüsselwort wird ignoriert), aber Sie verlieren die Fähigkeit, Definitionen wiederverwendbar zu machen, was zu dupliziertem Code und Drift führt.

Beispiel für einen korrekten Verweis:

{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$defs": { "address": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" } }, "required": ["street","city"] } }, "type": "object", "properties": { "billing": { "$ref": "#/$defs/address" }, "shipping": { "$ref": "#/$defs/address" } }, "required": ["billing","shipping"] } Wenn Sie versehentlich "$ref": "#/definitions/address" schreiben, würde der Verweis auf undefined aufgelöst und der Validator würde einen Fehler werfen, der Sie auf die Fehlstelle hinweist.

Validieren Sie mit Beispielen vor der Veröffentlichung

Die günstigste Vertrauensprüfung besteht darin, eine Handvoll repräsentativer JSON-Instanzen durch den Validator zu führen, bevor Sie das Schema als Vertrag behandeln. Ein gutes Testpaket enthält mindestens ein gültiges Beispiel, das der beabsichtigten Verwendung entspricht, und ein ungültiges Beispiel, das jede Regel, die Ihnen wichtig ist, absichtlich bricht. Wenn das Schema das gute Beispiel akzeptiert und das schlechte ablehnt, haben Sie Beweise dafür, dass es nicht zu nachsichtig ist. Ich habe Teams gesehen, die diesen Schritt übersprungen haben und später entdeckt haben, dass ein fehlendes erforderliches Feld wie z.B. die Bestellnummer ohne Produkt-ID durchrutschen konnte und somit Fehler bei der Erfüllung verursachte.

const Ajv = require('ajv'); const ajv = new Ajv({allErrors: true}); const schema = require('./user-schema.json'); const gut = { "id": "123", "name": "Ada" }; const schlecht = { "name": "Ada" }; // fehlende ID const validate = ajv.compile(schema); console.log('Gutes Beispiel:', validate(gut)? 'bestanden' : 'fehlgeschlagen'); if (!validate(gut)) console.error(validate.errors); console.log('Schlechtes Beispiel:', validate(schlecht)? 'bestanden' : 'fehlgeschlagen'); if (validate(schlecht)) console.error('Unerwartet akzeptiertes schlechtes Beispiel'); Das Ausführen dieses Codes in der CI gewährleistet, dass ein nachsichtiger Fehler nie die Produktion erreicht.

Was dies nicht ist

Dieser Leitfaden verspricht nicht, dass das Befolgen dieser Punkte Ihr Schema vor jedem möglichen Fehler schützt. JSON Schema ist eine flexible Sprache, und neue Fallstricke können auftauchen, wenn Sie es mit benutzerdefinierten Schlüsselwörtern erweitern oder es mit anderen Tools wie OpenAPI kombinieren. Ich behaupte nicht, dass die vier aufgeführten Fehler die einzigen sind, die wichtig sind; sie sind einfach diejenigen, die am häufigsten in den Code-Reviews auftauchen, die ich gesehen habe. Die hier gegebenen Ratschläge basieren auf meiner Erfahrung bei der Wartung von SchemaSafe und auf öffentlich verfügbaren Spezifikationen; sie sind kein Ersatz für das Lesen der offiziellen Spezifikation oder für das Ausführen eigener Validierungstests.

Referenzen

https://ajv.js.org/json-schema.html

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse

https://json-schema.org

https://json-schema.org/draft/2020-12/json-schema-core.html

Häufig gestellte Fragen

Das Deklarieren einer Eigenschaft in properties macht sie nicht erforderlich. Sie müssen sie in dem erforderlichen Array auflisten. Das Array ist ein Geschwister von properties und nicht darin verschachtelt.

Es ist standardmäßig auf true gesetzt, sodass unbekannte Schlüssel akzeptiert werden. Setzen Sie additionalProperties: false, wo es auf Strenge ankommt, oder beschränken Sie es mit einem Schema für Erweiterungsfelder. Offene Schemas lassen Tippfehler stillschweigend durch.

Lassen Sie es im erforderlichen Array weg und fügen Sie "null" in das Typ-Array hinzu, beispielsweise ["string", "null"]. Das Schreiben eines durch Komma getrennten Typ-Strings ist ungültig und kann die Einschränkung aufheben.

Unter $defs. Der ältere definitions-Schlüssel funktioniert noch, markiert aber einen alten Entwurf. Pin sempre $schema, damit der Validator den Entwurf anwendet, den Sie beabsichtigt haben.

Probieren Sie das Produkt: SchemaSafe

2026-09-16 · nur primäre Quellen · keine erfundenen Traffic-Metriken

Verwandte Artikel

JSON-Schema-Validierung ohne LLM (2026)

Erkunden Sie die vollständige AI-Micro-SaaS-Themenmatrix →