JSON Schema: Daten online validieren (Draft 2020-12)

JSON Schema: Daten online validieren (Draft 2020-12)

API-Payloads und Config-Dateien gegen JSON Schema Draft 2020-12 prüfen — Fehler per JSON-Pointer-Pfad, im Browser.

12.08.2026
7 Min. Lektüre
Teilen Sie diesen Artikel:
json-schemavalidationAPIopenapiAnleitung

JSON-Daten gegen ein Schema validieren

Gültiges JSON ist nicht dasselbe wie gültig für Ihre API. Ein Payload kann fehlerfrei eingelesen werden und trotzdem ein Pflichtfeld auslassen, den falschen Typ enthalten oder eine format-Bedingung verletzen. Solche Fehler zeigen sich oft erst in Integrationstests oder in den Produktionsprotokollen. JSON Schema beantwortet eine andere Frage als die Syntaxprüfung: Entspricht diese Instanz dem Vertrag? Der Online-JSON-Schema-Validator von FastMinify führt die Validierung nach Draft-07 und 2020-12 in zwei Monaco-Editoren aus (Schema und Instanz), vollständig im Browser. Ist die Syntax fraglich, beginnen Sie mit dem JSON-Validator. Liegt der Vertrag in OpenAPI, nutzen Sie validate-openapi. Der API-Tools-Hub führt die Werkzeuge für Schema-Konvertierung und OpenAPI-Linting auf.

Schema und Syntax: fehlende Pflichtfelder und Typfehler erkennen, nachdem das JSON eingelesen ist
Draft-07 und 2020-12 über Ajv, mit instancePath- und Keyword-Fehlern pro Verletzung
Zwei Editoren mit Live-Validierung nach kurzer Debounce-Pause (~300 ms), ohne Installation und ohne Konto
Optionaler Strict-Modus für die Schema-Prüfung (Ajv strict: true beim Kompilieren)
100 % lokal: Schema und Payloads verlassen den Browser nie

Ehrliche Grenzen und wartbare Schemas

Was der Browser-Validator nicht tut

Ein grünes Ergebnis heißt: Die Instanz passt zum eingefügten Schema, nicht dass Ihre gesamte API-Plattform konform ist.

Keine Netzwerkabfragen: Externe $ref, auch mit https://, werden nie aufgelöst
Kein Mehrdatei-Bundle: Fügen Sie bei jedem Durchlauf ein eigenständiges Schema-JSON ein
Kein Lint der OpenAPI-Pfadoperationen: Nutzen Sie lint-openapi für operationId und Tags
Keine Abfrage von Live-Endpoints: Die Instanz muss ausdrücklich eingefügt werden
Schemas nach Draft-04, Draft-06 und 2019-09 werden abgelehnt: Migrieren oder konvertieren Sie die Drafts zuerst
Tipps für den Schema-Entwurf

Schemas, die im Browser sauber validieren, überstehen CI und SDK-Generierung besser.

Setzen Sie $schema in gemeinsam genutzten Dateien immer, um implizite Annahmen zu 2020-12 zu vermeiden
Verwenden Sie additionalProperties: false nur bei bewusst geschlossenen Objekten
Nutzen Sie examples in OpenAPI und fügen Sie sie bei Reviews als Instanzen in den Validator ein
Halten Sie Enums deckungsgleich mit dem Code und dokumentieren Sie veraltete Werte in description
Versionieren Sie inkompatible Schema-Änderungen, damit Konsumenten gegen das Schema-Tag validieren, das sie anvisieren
Wann Sie auf CI-Werkzeuge umsteigen

Browser-Prüfungen sparen Pipeline-Minuten, die Richtlinien der Organisation bleiben in der CI.

Ajv oder jsonschema in GitHub Actions / GitLab CI bei jeder PR
Breaking-Change-Detektoren zwischen Schema-Versionen
Pact oder Contract-Tests gegen echte Umgebungen
Schema-Registries (Apicurio, Buf) für die Governance über mehrere Teams
Mit unserem CI/CD-Leitfaden kombinieren

JSON-Syntax vs. JSON-Schema-Validierung

Zwei Validatoren, zwei Fragen

Wechseln Sie nicht mitten in der Fehlersuche das Werkzeug: Jedes zielt auf einen anderen Fehlertyp.

JSON-Validator (json-validator): nur Syntax, etwa abschließende Kommas, einfache Anführungszeichen oder ein abgeschnittenes Einfügen
JSON-Schema-Validator (json-schema-validator): der semantische Vertrag, also Typen, Pflichtfelder, Enums und Formate
Grüne Syntax bei rotem Schema bedeutet eine Vertragsverletzung, keinen Einlesefehler
Reparieren Sie defektes JSON zuerst mit json-repair
Die Validierung eines OpenAPI-Dokuments ist eine dritte Aufgabe: Nutzen Sie validate-openapi für die Hülle der Spezifikation
Unterstützte Drafts (und was abgelehnt wird)

FastMinify erkennt den Draft anhand von $schema, sofern vorhanden; ohne $schema gilt 2020-12 als Standard.

Draft 2020-12: https://json-schema.org/draft/2020-12/schema
Draft-07: http://json-schema.org/draft-07/schema#
Draft-04, Draft-06 und 2019-09 liefern einen eindeutigen Fehler unsupported-draft, ohne stille Umwandlung
Geben Sie den Draft in gemeinsam genutzten Schemas ausdrücklich an, damit im Team keine unterschiedlichen Annahmen entstehen
OpenAPI 3.1 entspricht 2020-12; OpenAPI 3.0 verwendet meist Draft-07 in components.schemas
instancePath und Keyword-Fehler

Bei einem Fehler zeigt Ajv, wo die Instanz das Schema verletzt, was bei großen API-Payloads unverzichtbar ist.

instancePath zeigt auf den fehlerhaften Wert (JSON-Pointer-Stil)
Der Name des Keywords zeigt die fehlgeschlagene Regel (required, type, format, …)
Mehrere Verletzungen werden einzeln aufgeführt: Beheben Sie sie von oben nach unten oder zuerst beim wichtigsten Feld
Leere Instanz mit required-Schema → Pfad / oder Pfade der fehlenden Eigenschaften
json-tree-viewer hilft bei der Navigation in tiefen Payloads

JSON Schritt für Schritt gegen ein Schema validieren

Den JSON-Schema-Validator nutzen

Der JSON-Schema-Validator bietet zwei Editoren: Schema und Instanz. Fügen Sie in jedes Feld JSON ein. YAML wird im Schema-Editor nicht akzeptiert, er liest nur JSON. Die Grenze liegt bei 512 KiB pro Feld.

Live-Validierung nach kurzer Debounce-Pause (~300 ms), sobald sich beide Seiten einlesen lassen
Ergebnispanel: gültig oder ungültig, Anzahl der Verletzungen, erkannter Draft
Pro Fehler: instancePath, Keyword und Meldung
Aktionen Kopieren und Erweitern (⌘⇧E) an jedem Editor-Bereich
Der Schalter Strict ist standardmäßig aus; aktivieren Sie ihn für Schema-Linting wie in der CI
Wann der Strict-Modus sinnvoll ist

Der Strict-Modus schaltet Ajv strict: true beim Kompilieren des Schemas ein. Unbekannte Schlüsselwörter und andere nicht strikte Muster scheitern dann schon vor der Validierung der Instanz.

Aus (Standard): pragmatische Fehlersuche bei realen Schemas mit zusätzlichen Schlüsseln
An: Schema-Prüfung vor der Veröffentlichung in einer Registry oder in components.schemas von OpenAPI
Strict-Kompilierfehler erscheinen im Ergebnispanel: Korrigieren Sie das Schema und testen Sie die Instanz erneut
Kombinieren Sie Strict mit format-openapi, wenn Schemas in großen Spezifikationen eingebettet sind
Kein Ersatz für Spectral im ganzen Unternehmen oder für eigene Regelwerke
Eine API-Antwort scheitert in der Staging-Umgebung

Der mobile Client stürzt bei einer neuen Feldform ab. Die Antwort ist gültiges JSON, bricht aber das veröffentlichte Schema.

1

JSON-Syntax bestätigen

Fügen Sie die Antwort in json-validator ein. Bei einem Syntaxfehler reparieren Sie zuerst.

2

Schema und Instanz einfügen

Öffnen Sie json-schema-validator. Fügen Sie das kanonische Schema (aus einem OpenAPI-Export oder einer Schema-Registry) und die Staging-Antwort ein.

3

instancePath-Fehler lesen

Korrigieren Sie die API oder aktualisieren Sie das Schema mit einem Deprecation-Plan. Validieren Sie nach dem Deployment erneut. Optional vergleichen Sie Staging- und Produktions-Payloads mit diff.

Eine Konfigurationsdatei vor kubectl apply

Ein Team teilt eine JSON-Konfiguration, die in der CI mit JSON Schema validiert wird. Sie brauchen eine schnelle lokale Prüfung, ohne die Pipeline zu klonen.

1

Schema aus dem Repository laden

Kopieren Sie das Schema-JSON. Es muss eigenständig sein, denn externe $ref werden im Browser nicht aufgelöst.

2

Ihre Änderung validieren

Fügen Sie die bearbeitete Konfiguration als Instanz ein. Aktivieren Sie Strict, wenn das Schema für eine strenge Prüfung geschrieben wurde.

3

Bei Bedarf mit den YAML-Werkzeugen verketten

Konfigurationen liegen oft als YAML vor. Konvertieren Sie sie mit yaml-to-json, prüfen Sie die Syntax und validieren Sie dann die JSON-Instanz gegen das Schema.

OpenAPI, components.schemas und Konvertierung

Wo Schemas in API-Verträgen leben

REST-Teams veröffentlichen ihre Strukturen oft in components.schemas von OpenAPI, während Schema-Registries eigenständige Dateien speichern. Der Validator akzeptiert beides, sobald es als JSON extrahiert ist. Der Ablauf beginnt mit validate-openapi für die Hülle der Spezifikation, extrahiert das Schema und prüft den Payload dann mit json-schema-validator dagegen. Siehe unseren OpenAPI-Validierungsleitfaden und den Lint- & Format-Leitfaden für die Spezifikationsseite des Vertrags.

Zwischen OpenAPI und JSON Schema konvertieren

Ist die OpenAPI-Datei die Quelle des Schemas, wechseln Sie die Formate im Hub ohne lokale CLI. Mit openapi-to-json-schema extrahieren Sie ein Schema aus den OpenAPI-Components. Mit json-schema-to-openapi verpacken Sie ein eigenständiges Schema in eine OpenAPI-Hülle für den Portalimport.

Die Denkweise beim Contract Testing

Die Validierung im Browser beschleunigt das Feedback, die Regressionstests bleiben in der CI. Fügen Sie repräsentative Instanzen ein: Normalfall, Null-Grenzfälle und Enum-Grenzen. Dokumentieren Sie den Draft in $schema neben jeder gemeinsam genutzten Schema-Datei in git.

Häufige Validierungsfehler

Typische Instanz-Fehler

Diese Fälle tauchen ständig in Support-Tickets und instabilen CI-Jobs auf.

Fehlende required-Eigenschaft: instancePath zeigt auf das übergeordnete Objekt oder auf die Wurzel /
Falscher type, etwa ein String, wo eine Ganzzahl erwartet wird (häufig nach der Serialisierung eines Formulars)
additionalProperties: false fängt überzählige Felder durch Fehler bei der Versionierung der API ab
format-Verletzungen wie date-time, email oder uuid (über ajv-formats)
Abweichung vom enum durch nicht dokumentierte Status- oder Regionscodes im Payload
Typische Fehler beim Kompilieren des Schemas

Strict-Modus und nicht unterstützte Drafts zeigen sich hier, bevor die Instanz validiert wird.

Nicht unterstützte $schema-URL: auf Draft-07 oder 2020-12 umstellen
Eine externe $ref ist ein harter Fehler: Lösen Sie die Verweise zuerst lokal auf oder bündeln Sie sie
YAML im Schema-Editor: Konvertieren Sie es in JSON oder fügen Sie nur JSON ein
Ein Schema über 512 KiB: Teilen Sie es auf oder nutzen Sie Bündelungswerkzeuge in der CI
Unbekannte Schlüsselwörter unter Strict: Entfernen Sie sie oder verschieben Sie sie je nach Richtlinie nach description oder in Herstellererweiterungen

Zusammenfassung

Die JSON-Schema-Validierung schließt die Lücke zwischen einlesbarem JSON und vertrauenswürdigen API-Daten. Prüfen Sie bei Bedarf zuerst die Syntax. Validieren Sie dann Instanzen gegen Schemas nach Draft-07 oder 2020-12 mit klaren instancePath-Fehlern, lokal vor der CI. Extrahieren Sie Schemas aus OpenAPI, wenn die Verträge in Spezifikationen liegen. Benennen Sie die Grenzen der Browser-Prüfung ehrlich: Referenzen, Drafts und Größe.

Zuerst die Syntax mit json-validator, danach die Schema-Validierung
Setzen Sie $schema in jeder gemeinsam genutzten Schema-Datei ausdrücklich
Aktivieren Sie Strict für die Schema-Prüfung vor dem Merge, nicht für die Fehlersuche bei lockeren Payloads
Bündeln Sie externe $ref lokal, denn das Browser-Werkzeug ruft nie URLs ab
Verketten Sie mit openapi-to-json-schema, wenn die Quelle eine OpenAPI-Datei ist
Teilen Sie diesen Artikel
Teilen Sie diesen Artikel: