JSON-Validierung: JSON Schema, Validierungsfehler

1. Warum man JSON validieren sollte

Stellen wir uns vor: Sie haben die Klasse User geschrieben und erwarten, dass Ihnen immer folgender JSON geschickt wird:

{
  "id": 42,
  "name": "Alice",
  "email": "alice@example.com"
}

Doch plötzlich kommt Folgendes an:

{
  "id": "zweiundvierzig",
  "name": 123,
  "email": null,
  "admin": true
}

Oder sogar:

{
  "username": "Alice"
}

Im besten Fall werfen Jackson oder Gson beim Deserialisieren eine Ausnahme. Im schlechtesten Fall weisen sie Feldern stillschweigend Standardwerte zu, und Ihr Business-Code beginnt, falsch zu funktionieren. Und wenn das die Konfiguration für Ihren Dienst ist – können unangenehme Bugs entstehen, die dann das gesamte Team lange sucht.

JSON-Validierung ist der Prozess der Prüfung, dass Struktur, Typen und Werte der Daten in JSON bestimmten Regeln (einer Schema) entsprechen. Es ist wie Passkontrolle für Daten: Wer sie nicht besteht – kommt nicht an Bord!

2. JSON Schema: was es ist und wie es aussieht

In der JSON-Welt gibt es einen offiziellen Standard zur Beschreibung von Datenstrukturen – JSON Schema. Das ist eine „Checkliste“, mit der man prüfen kann, ob ein JSON den Anforderungen Ihres Programms entspricht.

JSON Schema ist ebenfalls JSON, nur mit speziellen Schlüsseln: type, properties, required und so weiter.

Beispiel für das einfachste Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id":    { "type": "integer" },
    "name":  { "type": "string" },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["id", "name"]
}

Was hier passiert:

• Es wird ein Objekt erwartet (type: "object").
• Das Objekt kann die Felder "id", "name", "email" haben (beschrieben in properties).
• "id" – muss eine ganze Zahl sein (type: "integer").
• "name" – muss eine Zeichenkette sein (type: "string").
• "email" – eine Zeichenkette, die wie eine E‑Mail aussieht (Schlüssel format mit Wert "email").
• required gibt die Liste der Pflichtfelder an: "id" und "name".

Fehlen in JSON "id" oder "name" oder haben sie den falschen Typ – schlägt die Validierung fehl.

Kurz zu den Möglichkeiten von JSON Schema

• Typangabe (type: "string", "integer", "array", "object", "boolean", "null").
• Beschreibung verschachtelter Objekte und Arrays (properties, items).
• Pflicht- und optionale Felder (required).
• Prüfung der Stringlänge, Zahlenbereiche (minLength, maximum u. a.).
• Formatprüfung (format: "email", "date", "uri" u. a.).
• Aufzählungen (enum: Liste zulässiger Werte).
• Reguläre Ausdrücke für Strings (pattern).
• Komplexe Bedingungen: anyOf, oneOf, allOf (für fortgeschrittene Fälle).

3. JSON-Validierung in Java: Bibliotheksüberblick

In der Java-Standardbibliothek ist die Schema-Validierung für JSON nicht enthalten. Es gibt jedoch beliebte Drittanbieter-Bibliotheken. Die bekanntesten sind:

• everit-org/json-schema – einfach, kostenlos und beliebt.
• networknt/json-schema-validator – schnell, unterstützt die neuesten Standards.
• Jackson-module-jsonSchema – Erweiterung für Jackson (unterstützt jedoch keine vollständige Validierung).
• Justify, Java JSON Tools – es gibt weitere, kommen jedoch seltener vor.

In dieser Vorlesung betrachten wir everit-org/json-schema – sie ist für Einsteiger einfach, gut dokumentiert und erfordert keine Verrenkungen.

Installation von everit-org/json-schema

Fügen Sie die Abhängigkeit zu Ihrer pom.xml hinzu (Maven):

<dependency>
  <groupId>org.everit.json</groupId>
  <artifactId>org.everit.json.schema</artifactId>
  <version>1.14.2</version>
</dependency>

Oder mit Gradle:

implementation 'org.everit.json:org.everit.json.schema:1.14.2'

4. Beispiel: JSON-Validierung anhand eines Schemas (Schritt für Schritt)

Probieren wir die Validierung in der Praxis. Dafür brauchen wir das Schema selbst, den JSON und etwas Code.

Beispielschema (user-schema.json):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id":    { "type": "integer" },
    "name":  { "type": "string", "minLength": 2, "maxLength": 30 },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["id", "name"]
}

Beispiel für gültigen JSON (user.json):

{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com"
}

Beispiel für ungültigen JSON:

{
  "id": "eins",
  "name": "",
  "email": "not-an-email"
}

Validierungscode

import org.everit.json.schema.Schema;
import org.everit.json.schema.loader.SchemaLoader;
import org.json.JSONObject;
import org.json.JSONException;
import org.json.JSONTokener;
import org.everit.json.schema.ValidationException;

import java.nio.file.Files;
import java.nio.file.Paths;

public class JsonValidationExample {
    public static void main(String[] args) throws Exception {
        // Schema aus Datei laden
        String schemaString = new String(Files.readAllBytes(Paths.get("user-schema.json")));
        JSONObject rawSchema = new JSONObject(new JSONTokener(schemaString));
        Schema schema = SchemaLoader.load(rawSchema);

        // JSON zum Prüfen laden
        String jsonString = new String(Files.readAllBytes(Paths.get("user.json")));
        JSONObject json = new JSONObject(new JSONTokener(jsonString));

        // Validierung
        try {
            schema.validate(json); // Wenn alles ok ist – passiert nichts
            System.out.println("JSON ist gültig!");
        } catch (ValidationException e) {
            System.out.println("JSON ist NICHT gültig!");
            for (String msg : e.getAllMessages()) {
                System.out.println("Fehler: " + msg);
            }
        }
    }
}

Anmerkungen zum Code:

• Es werden die Klasse Schema und der Loader SchemaLoader.load(...) verwendet.
• Die Methode schema.validate(json) wirft bei Nichtübereinstimmung mit der Schema eine Ausnahme.
• Im catch-Block können alle Fehler über getAllMessages() abgerufen werden.

Wie in eine Anwendung integrieren?

Üblicherweise liegt das Schema als Ressource (z. B. im Ordner resources). Sie validieren den JSON vor der Deserialisierung in ein Java-Objekt. Wenn alles passt – deserialisieren und weiterarbeiten.

5. Umgang mit Validierungsfehlern

Wenn JSON die Prüfung nicht besteht, wirft die Bibliothek die Ausnahme ValidationException. In der Meldung befindet sich eine Liste von Fehlern: was genau nicht der Schema entspricht.

Beispiel für die Fehlerausgabe

Für den oben ungültigen JSON sieht die Ausgabe etwa so aus:

JSON ist NICHT gültig!
Fehler: #: required key [id] not found
Fehler: #/name: expected minLength: 2, actual: 0
Fehler: #/email: String [not-an-email] is invalid against requested format [email]
Fehler: #/id: expected type: Integer, found: String

Wie die Fehler zu interpretieren sind:

• required key [id] not found – fehlendes Pflichtfeld.
• expected minLength: 2, actual: 0 – Zeichenkette ist zu kurz.
• String [...] is invalid against requested format [email] – ungültige E‑Mail-Adresse.
• expected type: Integer, found: String – falscher Typ.

Wichtig! Die Meldungen können auf Englisch sein, sind aber gut verständlich.

Wie zeigt man die Fehler dem Benutzer?

Sie können die Fehler in einer Liste sammeln und dem Benutzer beispielsweise in einem REST‑API oder GUI zurückgeben. So lässt sich schnell erkennen, was an den Eingabedaten nicht stimmt.

6. Praxis: Validierung eines Arrays von Objekten

Häufig muss nicht ein einzelnes Objekt, sondern ein Array validiert werden:

[
  { "id": 1, "name": "Alice", "email": "alice@example.com" },
  { "id": 2, "name": "Bob" },
  { "id": "Was ist das?", "name": 123, "email": "not-an-email" }
]

Schema:

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id":    { "type": "integer" },
      "name":  { "type": "string", "minLength": 2, "maxLength": 30 },
      "email": { "type": "string", "format": "email" }
    },
    "required": ["id", "name"]
  }
}

Validierung funktioniert genauso, nur dass Sie als JSON ein Array übergeben. Fehler enthalten die Indizes der Elemente, in denen etwas nicht stimmt (zum Beispiel [#/2/id]).

7. Typische Fehler bei der JSON-Validierung

Fehler Nr. 1: Typen passen nicht zusammen. Sehr oft kommt eine Zeichenkette statt einer Zahl ("id": "123"), während die Schema ein Integer erwartet. Die Validierung schlägt fehl. Wenn Sie die Datenquelle nicht kontrollieren – passen Sie entweder die Schema an oder konvertieren Sie die Daten vorab.

Fehler Nr. 2: Fehlende Pflichtfelder. Wenn in der Schema steht, dass ein Feld obligatorisch ist ("required": ["id","name"]), es im JSON aber fehlt – erhalten Sie einen Fehler. Das ist manchmal überraschend: Das Frontend hat das Feld vergessen zu senden oder das API hat sich geändert.

Fehler Nr. 3: Zusätzliche Felder im JSON. Standardmäßig erlaubt JSON Schema zusätzliche Felder. Wenn Sie eine strenge Schema möchten, vergessen Sie nicht, "additionalProperties": false hinzuzufügen. Ohne das können im JSON beliebige „fremde“ Felder stehen.

Fehler Nr. 4: Falsche Schemaspezifikation oder Syntax. Wenn Sie Schlüssel verwenden, die es in Ihrer Schemaversion nicht gibt, oder Tippfehler machen, kann der Validator die Schema nicht laden. Prüfen Sie die Schema auf https://www.jsonschemavalidator.net/ oder ähnlichen Diensten.

Fehler Nr. 5: Schlechter Umgang mit Fehlern. Wenn Sie nur die erste Ausnahme fangen und dem Benutzer keine Details zeigen, ist es schwer zu verstehen, was genau am JSON falsch ist. Verwenden Sie getAllMessages(), um alle Fehler auszugeben.

Fehler Nr. 6: Zu strenge Formate. Die Prüfung von "format": "email" oder "date" ist oft recht „oberflächlich“. Wenn Sie eine strengere Validierung benötigen, verwenden Sie zusätzliche Prüfungen im Code.