JSON Schema

JSON Schema ist ein Standard, um zu beschreiben, wie ein gültiges JSON-Dokument aussieht: welche Properties es gibt, welche Typen sie haben, welche Pflicht sind, erlaubte Werte und Formate. Ein Validator prüft dann echte Daten gegen das Schema und meldet jede Verletzung. Für API-Tester wird aus „die Response sieht richtig aus“ eine einzige, wiederholbare Prüfung der gesamten Response-Struktur. Die aktuelle Version der Spezifikation ist Draft 2020-12; Draft-07 ist nach wie vor sehr verbreitet.

Beispiel

Ein Schema für einen Nutzer, den GET /users/{id} zurückgibt:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email", "role", "createdAt"],
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "role": { "enum": ["admin", "member", "viewer"] },
    "createdAt": { "type": "string", "format": "date-time" },
    "nickname": { "type": ["string", "null"] }
  },
  "additionalProperties": false
}

Validierung in Node mit Ajv (ajv/dist/2020 unterstützt Draft 2020-12, und ajv-formats ergänzt email und date-time):

import Ajv2020 from 'ajv/dist/2020';
import addFormats from 'ajv-formats';

const ajv = new Ajv2020({ allErrors: true });
addFormats(ajv);
const validate = ajv.compile(userSchema);

if (!validate(responseBody)) {
  console.log(validate.errors);
}

In Java bietet das Modul json-schema-validator von REST Assured matchesJsonSchemaInClasspath("schemas/user.json") zur Verwendung innerhalb von .body(...). Prüfen Sie, welchen Draft Ihr Validator unterstützt, bevor Sie neuere Keywords verwenden.

Warum das wichtig ist

• Eine Assertion deckt die ganze Struktur ab. Fehlende Felder, falsche Typen und unerwartete nulls werden erkannt, ohne für jedes Feld eine Prüfung zu schreiben.
• Es findet Datenlecks. "additionalProperties": false schlägt fehl, wenn die Response plötzlich etwas wie passwordHash enthält.
• Es dokumentiert den Contract. OpenAPI-Spezifikationen nutzen JSON Schema, um Request- und Response-Bodies zu beschreiben.

Häufige Fehler

• Schemas, die alles akzeptieren. Ein Schema ohne required lässt {} durch. Listen Sie Pflichtfelder immer auf.
• Annehmen, dass format durchgesetzt wird. Viele Validatoren behandeln format nur als Annotation, solange die Formatvalidierung nicht eingeschaltet ist.
• Nur das Schema validieren. Eine Response kann zum Schema passen und trotzdem den falschen Nutzer enthalten. Behalten Sie Wert-Assertions für die Daten, auf die es ankommt.