JSON bis JSON Schema: von der Beispielnutzlast bis zum Vertrag

Welche Schlussfolgerung kann man sehen und welche nicht?

Aus einem einzelnen Dokument leitet ein guter Konverter Typen, Verschachtelungen, Array-Elementformen und Eigenschaftsnamen präzise ab. Was daraus nicht abgeleitet werden kann, ist Absicht. Es weiß nicht, dass ein Feld optional ist, weil dieser bestimmte Datensatz es zufällig enthielt, dass eine Zeichenfolge eine E-Mail-Adresse ist, dass eine Zahl eine positive Ganzzahl ist oder dass ein Wert aus einer festen Menge stammt. Alles, was abgeleitet wird, wird daher mit `required` gekennzeichnet, was die richtige Vorgabe für einen Vertragsentwurf und die falsche Sache ist, ungeprüft zu versenden.

Härten des generierten Schemas

1. Vergleichen Sie zwei oder drei echte Proben: Schlüssel, die in einer Probe fehlen, sollten aus `required` herausfallen.
2. Fügen Sie `format` hinzu, wenn die Bedeutung bekannt ist – `date-time`, `email`, `uri`, `uuid`, `ipv4`.
3. Wandeln Sie offene Mengen in `enum`-Werte um, wenn das Feld wirklich ein festes Vokabular hat, wie zum Beispiel einen Status oder eine Region.
4. Zahlen mit `minimum`, `maximum` und `multipleOf` verschärfen, damit eine negative Menge nicht validiert werden kann.
5. Fügen Sie `additionalProperties: false` nur hinzu, wenn unbekannte Schlüssel abgelehnt werden müssen – andernfalls lassen Sie das Schema aus Gründen der Vorwärtskompatibilität offen.

Erforderlich ist ein Versprechen, keine Beobachtung. Das Markieren eines Felds als erforderlich, weil Ihr einziges Beispiel es enthielt, ist die häufigste Art und Weise, wie ein abgeleitetes Schema eine echte Integration unterbricht.

Wo das Schema seinen Lebensunterhalt verdient

Der praktische Wert zeigt sich an Grenzen: Validieren einer Webhook-Nutzlast, bevor man ihr vertraut, Überprüfen von Fixture-Dateien in CI, sodass Tests bei fehlerhaften Daten und nicht bei verwirrenden Nullfehlern fehlschlagen, Dokumentieren einer API-Antwort für Personen, die den Servercode niemals lesen werden, und Generieren typisierter Clients. Ein JSON-Schema ist auch die günstigste Möglichkeit, zu verhindern, dass eine Konfigurationsänderung stillschweigend eine öffentliche Antwort ändert, da der Validator sie zur Build-Zeit und nicht in der Produktion abfängt.

                {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "email": { "type": "string", "format": "email" },
    "plan": { "type": "string", "enum": ["free", "pro", "team"] }
  }
}
              

Behalten Sie die Versionskontrolle bei

Generierte Schemata verschieben sich, sobald sie niemandem mehr gehören. Übertragen Sie die gehärtete Datei neben den Code, der die Daten erzeugt, referenzieren Sie sie vom Validator in CI und generieren Sie sie nur dann neu, wenn sich der Vertrag tatsächlich ändert. Dabei wird das Schema als Quelle der Wahrheit für die Form und das Beispiel als Beweis behandelt, nicht umgekehrt.

Rückschluss im Browser

Echte Nutzlasten sind voll von Identifikatoren, E-Mails und Tokens, sodass eine Schemakonvertierung von JSON in JSON, die das Beispiel hochlädt, Produktionsdaten für einen rein mechanischen Vorgang übergibt. Durch die lokale Ableitung bleibt die Nutzlast auf der Registerkarte erhalten, Sie können ohne Bedenken einen Kundendatensatz einfügen und arbeiten auch bei abgeschaltetem Netzwerk.