Warum automatisch generierte JSON Schemas echte Daten ständig ablehnen

Kurz gesagt: Grenzen Sie zuerst die Grenze zwischen required und optional von Hand ein – geben Sie 5–20 Datensätze mit unterschiedlichen Formen ein, mit ausgeschaltetem „alles erforderlich“ –, dann generieren Sie das Schema und ergänzen format, enum und additionalProperties manuell; ein einzelnes Beispiel mit allen Feldern ist immer zu streng.

Der Generator sieht nur den einzelnen Datensatz, den Sie hineinkopiert haben. Er liest „dieser Datensatz hat eine E-Mail“ als „jeder Datensatz muss eine E-Mail haben“, je vollständiger Ihre Beispiele also werden, desto mehr verlangt er.

1. Ein Generator macht strukturelle Abbildung, kein Geschäftsverständnis

Geben Sie einem Generator ein Stück JSON, und er tut genau eine Sache: die Struktur der Werte durchlaufen und jeden Knoten in Schema-Schlüsselwörter übersetzen. Die ganze Abbildungstabelle ist fest:

Der ganze Ärger steckt in der letzten Zeile. required leitet sich nicht aus Typen ab; es leitet sich aus „dieser Schlüssel existiert in diesem Beispiel“ ab. Ist das Beispiel ein einzelner Datensatz, entspricht diese Aussage „jeder Schlüssel ist Pflicht“.

Und von echten APIs zurückgegebene Daten haben fast immer die Hälfte der Felder optional. Dort beginnt der Konflikt.

2. Fünf gleichförmige Datensätze, fünf Akzeptanzraten

Zuerst messen. Jeder, der die fünf Datensätze unten ansieht, würde sagen „die haben dieselbe Form“:

复制[
  {
    "id": 1,
    "name": "Ada",
    "email": "ada@example.com",
    "tags": ["a"],
    "score": 10
  },
  { "id": 2, "name": "Bob", "tags": [], "score": 7 },
  {
    "id": 3,
    "name": "Cy",
    "email": "cy@example.com",
    "tags": ["a", "b"],
    "score": 8.5
  },
  { "id": 4, "name": "Dee", "email": null, "tags": ["c"], "score": 9 },
  {
    "id": 5,
    "name": "Eve",
    "email": "eve@example.com",
    "tags": ["d"],
    "score": 6,
    "admin": true
  }
]

email erscheint in 3 der 5 Datensätze, admin nur einmal, und Datensatz 2 hat ein leeres tags-Array.

Generieren Sie nun ein Schema aus jedem Datensatz einzeln und verwenden Sie jedes Ergebnis, um alle fünf Datensätze zu validieren (Validator: ajv 8):

Keines der fünf Schemas ist korrekt, aber das einzige, das alle Daten akzeptiert, stammt aus Datensatz 2 – dem Datensatz, dem email fehlt. Es gewinnt aus einem schlichten Grund: Schlüssel, die nie erscheinen, werden nie in required geschrieben.

Datensatz 4 ist noch lehrreicher: Sein email-Wert ist null, der Generator schreibt also {"type": "null"} fest, und die anderen vier Datensätze mit String-E-Mails werden alle abgelehnt.

3. Warum „den vollständigsten Datensatz einfügen“ die schlechteste Wahl ist

Die Intuition ist „füge das Beispiel mit den meisten Feldern ein, und das Schema wird vollständig“. Die Messungen zeigen das genaue Gegenteil – und ein Dritter führte einen größeren kontrollierten Test durch.

absurdtools verwendete 3000 zufällige „Datenfamilien“, 8 Datensätze pro Familie, wobei jedes optionale Feld etwa die Hälfte der Zeit vorhanden war, und maß, wie viele Daten ein aus Beispielen mit unterschiedlichen Schlüsselzahlen generiertes Schema akzeptieren konnte:

Die Schlussfolgerung ist nicht „ein leichter Rückgang“, sondern eine vollständige Umkehr: Das minimale Beispiel erzeugte in 95 % der Familien das lockerste Schema, während das vollständigste Beispiel das nur in 0,1 % der Fälle schaffte.

Der Grund liegt in der Semantik von required, das „alle“ bedeutet; Optionalität lässt sich nur durch Abwesenheit beobachten. Einen Datensatz mit jedem Feld einzufügen sagt dem Generator „keiner dieser Schlüssel darf fehlen“; einen Datensatz mit einem fehlenden Feld einzufügen gibt ihm den Beleg, dass „dieser Schlüssel fehlen kann“.

Merken Sie es sich in einem Satz: Der Wert eines Beispiels ist nicht Vollständigkeit, sondern welche Abwesenheiten es abdeckt.

Wie viele Datensätze genügen

Dieselbe Versuchsreihe maß auch die Konvergenzgeschwindigkeit: Sammelt man Datensätze einzeln unter der Regel „ein Schlüssel bleibt nur erforderlich, wenn jeder bisherige Datensatz ihn hat“, liegt die Median-Zahl der Datensätze, bis required zur wahren erforderlichen Menge konvergiert, bei 3; 6 Datensätze decken etwa neunzig Prozent der Familien ab, und 12 decken alle ab.

Im Alltag 5–10 Datensätze zu beproben ist also das beste Preis-Leistungs-Verhältnis; zwanzig oder mehr zu erzwingen bringt sehr wenig zusätzlich.

Es gibt aber eine Vorbedingung: Diese Datensätze müssen aus wirklich unterschiedlichen Situationen stammen. Fünf aus derselben Vorlage kopierte Datensätze liefern ab dem zweiten keinen neuen Informationen mehr – ihre Feldsätze sind identisch, und required kann nicht um einen einzigen Schlüssel enger werden.

4. Die Lösung: mehrere Datensätze auf einmal eingeben und die Abwesenheiten sprechen lassen

Da Einzeldatensatz-Sampling zwangsläufig zu streng ist, besteht der richtige Ansatz darin, den Generator mehrere Datensätze auf einmal ansehen zu lassen und required mit der Regel „erforderlich nur, wenn jeder Datensatz ihn hat“ zu konvergieren.

Der Generator dieser Website akzeptiert direkt ein Array und hat einen Schalter „alles erforderlich“. Schalten Sie ihn aus, und er entscheidet nach Vorkommenszahl: Nur Schlüssel, die jeder Datensatz trägt, werden in required geschrieben.

Noch dieselben fünf Datensätze – diesmal als Array kombinieren und gemeinsam inferieren, dann items als Elementvertrag nehmen:

required konvergiert, sobald der vierte Datensatz hinzugefügt wird, und ändert sich danach nicht mehr. email und admin werden korrekt in properties platziert, aber nicht in required. Und weil die E-Mail von Datensatz 4 null ist, kombiniert die Mehrfachdatensatz-Inferenz sie zu {"type": ["string", "null"]}, sodass sowohl Strings als auch null bestehen – etwas, das Einzeldatensatz-Sampling nie kann.

Das ist dieselbe Größenordnung wie absurdtools' Befund, dass „required nach einem Median von 3 Datensätzen konvergiert“.

Die Mehrfachdatensatz-Inferenz hat jedoch eigene blinde Flecken: Ist die email in diesen Datensätzen zufällig in jedem null (etwa alle aus Konten ohne ausgefülltes Profil), wird das Inferenzergebnis {"type": "null"}, und String-E-Mails werden weiterhin abgelehnt. Ebenso lässt sich der Elementtyp nicht inferieren, wenn jeder tags-Wert ein leeres Array ist.

Das Sampling hat also eine weitere harte Anforderung: Jede Form jedes Feldes muss mindestens einmal erscheinen. Bringen Sie einen String, eine Zahl, ein null und ein leeres Array; lassen Sie keine Form vollständig fehlen.

Konkret:

1. Ziehen Sie 5–20 Antworten aus Logs, Mocks oder echten Anfragen, und beziehen Sie unbedingt die anomalen Zeilen ein (die mit leeren Feldern, die mit null, die mit leerem Array);
2. Setzen Sie sie zu einem JSON-Array zusammen und fügen Sie es in den Generator ein;
3. Schalten Sie „alles erforderlich“ aus und wählen Sie draft 2020-12;
4. Das Ergebnis ist type: array plus items; nehmen Sie den items-Abschnitt als Vertrag für einen einzelnen Datensatz;
5. Validieren Sie sofort die ursprünglichen Beispiele mit diesem Schema – 100 % müssen bestehen. Scheitert auch nur eines, reicht Ihr Sampling nicht; gehen Sie zurück und ergänzen Sie Datensätze.

Schritt 5 ist die günstigste Selbstprüfung. Kann der Generator nicht einmal die Daten aufnehmen, die Sie ihm gegeben haben, ist Ihre Sampling-Methode falsch, und weiterzumachen ist sinnlos.

5. Vier Dinge, die ein Generator nicht ausfüllen kann – die müssen Sie von Hand schreiben

Selbst nach Eingabe mehrerer Datensätze lässt sich Folgendes weiterhin nicht inferieren und muss manuell ergänzt werden:

Die dritte Zeile verdient eine eigene Erwähnung: Der Standardwert von additionalProperties ist „erlaubt“. Das bedeutet, eine Konfigurationsdatei, die timeout als timeuot schreibt, besteht die Validierung und tut zur Laufzeit dann stillschweigend nichts. Für Konfigurationsschemas ist das ein Punkt, den Sie ausdrücklich abschalten müssen.

format hat auch eine Falle: Seit Draft 2019-09 gehört format zum Annotationsvokabular und annotiert standardmäßig nur, statt zu erzwingen. Haben Sie format: "email" ergänzt und illegale Werte bestehen trotzdem, hat der Validator in acht von zehn Fällen validateFormats oder das entsprechende Format-Plugin nicht aktiviert – nicht das Schema ist falsch.

Noch ein Hinweis zur Draft-Wahl: Geht das Schema in OpenAPI 3.1, muss es Draft 2020-12 sein, weil 3.1 diese Version direkt einbettet; ältere Toolchains (das Swagger-2.0-Ökosystem und manche $ref-Implementierungen) orientieren sich weiterhin an draft-07. Beide verhalten sich bei $ref-Schwester-Schlüsselwörtern und bei arraybezogenen Schlüsselwörtern unterschiedlich, mischen Sie sie also nicht in einem Schemaset.

6. Für undokumentierte Drittanbieter-APIs den Vertrag aus Antwortbeispielen rekonstruieren

Einen Drittanbieter-Callback integrieren, mit einem Partner arbeiten, der keine Dokumentation schreibt, oder ein zehn Jahre altes Legacy-System pflegen – all das heißt „die Daten sind zur Hand, die Spezifikation nicht“. Hier ist ein Generator nicht bloß eine Bequemlichkeit; er ist der schnellste Weg zu einem Vertrag.

Die Methode ist dieselbe wie oben, mit zwei zusätzlichen Pflichten:

Erstens: über Zeit und über Zustände hinweg beproben. Drittanbieterfelder ändern sich oft mit dem Geschäftszustand – eine Aktion fügt einen discount hinzu, eine Rückerstattung einen refundAt, und eine Fehlerantwort hat gar keine data. Eine einzelne Momentaufnahme zu greifen heißt, nur einen Zustand zu sehen.

Geben Sie einige Erfolge, einige Fehler und einige leere Ergebnisse gemeinsam ein: error und data erscheinen oft gegenseitig ausschließlich, und die Mehrfachdatensatz-Inferenz legt beide in properties und lässt sie aus required heraus – genau wie die Realität.

Zweitens: das Schema im Repository speichern und eine tägliche Prüfung anhängen. Validieren Sie die echten Antworten von heute dagegen, und Sie erfahren von stillschweigend verschwindenden oder typwechselnden Feldern, bevor Ihre Nutzer es tun.

复制// Run once a day: contract-drift alert
const drifted = records.filter((record) => !validate(record));

if (drifted.length > 0) {
  console.warn(
    `${drifted.length} responses do not match the contract; first difference:`,
    validate.errors,
  );
}

Der Wert dieser Praxis ist nicht „die Mühe des Handschreibens sparen“, sondern eine mündliche Absprache in einen ausführbaren Alarm zu verwandeln. Ein Drittanbieter sagt Ihnen nie vorher, dass er ein Feld geändert hat, aber die Änderung zeigt sich sicher in Ihren Logs.

Eine Grenze klar zu ziehen: Das rekonstruierte Schema beschreibt, was die andere Seite jetzt zurückgibt, nicht was sie verspricht zurückzugeben. Ersteres dient der Überwachung; nur Letzteres gehört in einen Vertrag oder eine API-Dokumentation.

7. Nach der Ergänzung Validierungsfehler auf konkrete Felder zurückführen

Sobald das Schema brauchbar ist, ist lesbare Fehlermeldung das nächste Anliegen. Ein ajv-Fehlerobjekt hat fünf Felder, und die ersten vier sind die nützlichen:

Eine Asymmetrie ist am leichtesten zu übersehen: Scheitert required, zeigt instancePath auf das Elternobjekt (meist den leeren String, also die Wurzel), nicht auf das fehlende Feld. Der Name des fehlenden Schlüssels steht in params.missingProperty. Ebenso steht bei einem additionalProperties-Fehler der Name des zusätzlichen Schlüssels in params.additionalProperty.

Behandeln Sie beim Abbilden von Fehlern auf „Feld → Meldung“ also zuerst diese beiden Sonderfälle:

复制import Ajv from "ajv";

const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(schema);

/** Convert the ajv error array into { fieldPath: [message] } for form highlighting */
function groupByField(errors) {
  const grouped = {};

  for (const error of errors) {
    // For required and additionalProperties, the offending field lives in params, not in instancePath
    const field =
      error.keyword === "required"
        ? error.params.missingProperty
        : error.keyword === "additionalProperties"
          ? error.params.additionalProperty
          : error.instancePath.replace(/^\//u, "").split("/").join(".") ||
            "(root)";

    (grouped[field] ??= []).push(error.message);
  }

  return grouped;
}

if (!validate(data)) console.log(groupByField(validate.errors));

allErrors: true ist nicht optional. In der Standardkonfiguration stoppt ajv beim ersten Fehler, der Nutzer korrigiert ein Feld, sendet erneut, bekommt den nächsten Fehler und braucht drei Roundtrips, nur um ein Formular auszufüllen. Verwenden Sie zusätzlich ajv-errors für eigene Meldungen, ersetzt das Plugin ohne dieses Flag stillschweigend nur einige der Meldungen.

8. Ein wiederverwendbarer Einführungsprozess

Fügen Sie die obigen Schritte zu einer festen Routine zusammen und folgen Sie ihr bei jeder Integration einer neuen API:

1. Beproben: 5–20 echte Antworten greifen und bewusst die mit leeren Feldern, nulls, leeren Arrays und zusätzlichen Feldern auswählen;
2. Inferieren: sie als Array gemeinsam in den Generator einfügen, „alles erforderlich“ ausschalten und items nehmen;
3. Die Semantik ergänzen: format, enum, minimum/maximum, minItems und additionalProperties eines nach dem anderen ergänzen;
4. Selbstprüfung: die ursprünglichen Beispiele müssen zu 100 % bestehen, sonst zurück zu Schritt 1 und Beispiele ergänzen;
5. Negativbeweis: für jede Beschränkung eine „muss scheitern“-Eingabe vorbereiten und bestätigen, dass sie wirklich scheitert – nur den bestehenden Pfad zu testen ist wie nicht zu testen;
6. Committen: das Schema in die Versionskontrolle legen, die scheiternden Beispiele als Testfälle behalten und bei jeder Feldänderung der API zuerst die Tests ausführen.

Das Negativtesten in Schritt 5 wird am leichtesten übersprungen. Einen Schlüssel zu required hinzuzufügen, ohne je zu prüfen, dass ein fehlender Schlüssel einen Fehler erzeugt, heißt zu wetten, dass der Validator mit Ihrem mentalen Modell übereinstimmt.

复制import { describe, expect, it } from "vitest";

describe("user schema", () => {
  it("accepts a complete record", () => {
    expect(validate({ id: 1, name: "Ada", tags: [], score: 10 })).toBe(true);
  });

  it("rejects a record without name", () => {
    expect(validate({ id: 2, tags: [], score: 7 })).toBe(false);
    // Also assert the reason, so the test doesn't pass because some other field failed
    expect(
      validate.errors?.some((e) => e.params?.missingProperty === "name"),
    ).toBe(true);
  });
});

Die letzte Zusicherung zählt. Nur false zu prüfen kann grün bleiben, selbst nachdem das Schema kaputt gemacht wurde – der Fehler kann dann aus einer völlig anderen Ursache kommen.

9. FAQ

Kann das von einem Generator erzeugte Schema direkt in die Produktion

Nein. Es ist nur eine Momentaufnahme der Struktur. Sie müssen mindestens Formate, Bereiche, Enums und eine Richtlinie für unbekannte Felder ergänzen und dann sowohl die ursprünglichen Beispiele als auch die Negativbeispiele durchlaufen lassen. Der Generator löst „ properties von Hand zu tippen ist mühsam“, nicht „er entscheidet die Geschäftsregeln“.

Zum Schlüsselwortsystem der Schemaerstellung, zum $ref-Aufteilen und zu Kompositions-Schlüsselwörtern siehe JSON Schema: von den Grundlagen bis zur Produktion.

Warum lehnt der Datensatz mit den meisten Feldern mehr Daten ab

Weil required aus „was im Beispiel erschien“ gesammelt wird. Ein Beispiel mit allen Feldern macht jeden optionalen Schlüssel zu einem Pflichtschlüssel, während die meisten dieser Schlüssel in echten Daten fehlen. Mehrere Datensätze einzugeben oder einen Datensatz, der Feld bewusst weglässt, bringt Sie näher an die Wahrheit als das vollständigste Beispiel.

Wird eine Ganzzahl als integer inferiert

Der Generator dieser Website tut das nicht: Ganzzahlen und Floats werden beide als number ausgegeben, ein aus {"price": 5} generiertes Schema akzeptiert also 5.99. Das vermeidet Unfälle wie „das Beispiel war zufällig eine Ganzzahl, also lehnt die Produktion Preise mit Dezimalstellen ab“. Manche Drittanbieterwerkzeuge inferieren integer tatsächlich aus dem Wert, seien Sie bei Geldbetragsfeldern also besonders vorsichtig.

Zu Details von Zahlenpräzision und Typgrenzen siehe Die sechs JSON-Datentypen und Fallen der Zahlenpräzision.

Ich habe format ergänzt, aber es hat keine Wirkung

Seit Draft 2019-09 ist format standardmäßig reine Annotation. Aktivieren Sie entweder ausdrücklich Formatprüfungen im Validator (ajv braucht ajv-formats) oder verwenden Sie pattern für eine harte Beschränkung. Nehmen Sie nicht an, dass das Hinzufügen irgendetwas blockiert.

required meldet einen Fehler, aber das Feld ist offensichtlich in den Daten vorhanden

Sehen Sie zuerst instancePath an. Ein required-Fehler zeigt auf das Elternobjekt, was bedeutet, dass der fehlende Schlüssel nicht auf dieser Ebene liegt – häufige Ursachen sind eine falsche Verschachtelungsebene (/profile/name ist nicht dasselbe wie name auf der Wurzel), unterschiedliche Groß-/Kleinschreibung (userId versus userID) oder die Upstream-Serialisierung, die undefined ganz verwirft.

Prüfen Sie vor der Untersuchung, ob das Dokument selbst gültiges JSON ist: Kommentare, nachfolgende Kommas und ähnliche Probleme scheitern in der Parsing-Phase, bevor das Schema überhaupt eine Chance bekommt. JSON parsen und formatieren zeigt direkt auf die fehlerhafte Zeile.

Wie viele Datensätze sollte ich beproben, und welchen Draft sollte ich verwenden?

Im Alltag 5–10 Datensätze zu beproben hat das beste Preis-Leistungs-Verhältnis; required konvergiert bei einem Median von 3 Datensätzen, und 12 Datensätze decken jede Familie ab. Jeder Datensatz muss aus einer wirklich anderen Situation stammen, und jede Form jedes Feldes muss mindestens einmal erscheinen. Legen Sie den Draft auf 2020-12 fest, weil OpenAPI 3.1 nur diese Version akzeptiert.

Warum ist ein permissiver Standard für additionalProperties gefährlicher?

Der Standard gibt gar kein Schlüsselwort aus, ein falsch geschriebener Schlüssel wird also stillschweigend akzeptiert, besteht die Validierung und scheitert dann zur Laufzeit – schwerer zu diagnostizieren als ein direkter Fehler. Konfigurationsschemas müssen "additionalProperties": false ausdrücklich setzen, während API-Schemas zuerst die Kompatibilitätskosten abwägen sollten.

Sollte ich ein rekonstruiertes Schema als harte Sperre verwenden?

Nein. Ein rekonstruiertes Schema beschreibt, was die andere Seite jetzt zurückgibt, nicht was sie verspricht zurückzugeben, es gehört also in Überwachung und Drift-Alarme. Was in einen Vertrag oder eine API-Dokumentation geht, muss der versprochene Vertrag sein.