JSON-Schema-Generator

Erzeugen Sie ein JSON Schema aus einem Beispiel-Payload. Standardmäßig Draft 2020-12, wahlweise 2019-09 und Draft-07.

Ein Schema aus einer einzigen Stichprobe zu erzeugen ist Inferenz, und Inferenz ist die Stelle, an der solche Werkzeuge leise lügen. Jede Vermutung, die hier getroffen wird, wird Ihnen gemeldet, und die größte davon wird anders behandelt als bei den meisten Generatoren.

Das Problem mit den Pflichtfeldern

Die meisten Generatoren lesen das erste Element eines Arrays und nehmen dessen Schlüssel als die Gestalt. Daraus entsteht ein Schema, das gültige Daten ablehnt, sobald ein späterer Datensatz ein optionales Feld hat, das dem ersten fehlte.

Dieser Generator führt alle Elemente zusammen. Ein Schlüssel, der in allen vorkommt, landet in required; einer, der nur in manchen vorkommt, erscheint in properties, aber nicht in required. Dieser eine Unterschied ist der Grund, einen Generator zu benutzen, statt das Schema nach einem Blick auf das Payload von Hand zu schreiben.

Die übrigen Vermutungen, alle gemeldet

integer gegen number

Ein Feld wird nur dann als integer typisiert, wenn jeder beobachtete Wert einer war. Eine einzige Dezimalzahl irgendwo macht das ganze Feld zu number.

Nullable Felder

Ein Feld, das sowohl als Zeichenkette als auch als null gesehen wurde, wird zu "type": ["string", "null"] - kein weggelassenes Feld und kein bloßes "string".

format

Wird nur ausgegeben, wenn jeder beobachtete Wert passt: date-time, date, time, email, uuid, ipv4 oder uri. Ein einziger unpassender Wert, und die Annotation entfällt.

enum

Wird vorgeschlagen statt angenommen, und nur wenn sich eine kleine Wertemenge wiederholt. Standardmäßig aus, denn ein aus einer Stichprobe abgeleitetes enum ist eine Vermutung über einen Wertebereich, den Sie nicht vollständig gesehen haben.

Unsichere Ganzzahlen

Werden als integer typisiert und gemeldet, denn ein Validator auf einem JavaScript-Parser hat den Wert bereits verloren, bevor die Validierung überhaupt beginnt.

Das Schlüsselwort format validiert nichts

Das überrascht viele und bringt kaputte Validierung in Produktion. In Draft 2019-09 und Draft 2020-12 ist format standardmäßig eine ANNOTATION und keine Zusicherung. Die meisten Validatoren nehmen bereitwillig "keine-email" für ein Feld mit "format": "email" an, solange die Format-Assertion nicht ausdrücklich eingeschaltet ist.

Wenn Sie es erzwingen wollen, ergänzen Sie neben dem format ein ausdrückliches pattern, oder stellen Sie Ihren Validator auf Assertion-Verhalten um und prüfen Sie, ob er das überhaupt unterstützt.

Ein Vorbehalt zum Validieren des Ergebnisses

Wenn Sie dieses Schema zu Ajv tragen, dem verbreitetsten JavaScript-Validator, achten Sie auf den Einstiegspunkt. Der voreingestellte ajv-Export unterstützt nur Draft-07. Draft 2020-12 braucht ajv/dist/2020 und 2019-09 braucht ajv/dist/2019.

Macht man das falsch, wird ein 2020-12-Schema mit prefixItems unter Draft-07-Semantik validiert, wo prefixItems ein unbekanntes Schlüsselwort ist und ignoriert wird. Ihr Validator meldet dann „gültig“ für Daten, die es nicht sind. Das ist schlimmer als ein Fehler, und es passiert leicht aus Versehen.

How to do this in code

Erzeugen und validieren im Code.

// The entry point matters. This is the 2020-12 one.
import Ajv2020 from 'ajv/dist/2020';
import addFormats from 'ajv-formats';

const ajv = new Ajv2020({ allErrors: true });
addFormats(ajv);   // without this, "format" does nothing at all

const validate = ajv.compile(schema);
if (!validate(data)) console.error(validate.errors);

from jsonschema import Draft202012Validator

validator = Draft202012Validator(schema)
for error in sorted(validator.iter_errors(data), key=lambda e: e.path):
    print(list(error.path), error.message)

# Format checking is opt-in here too
from jsonschema import FormatChecker
Draft202012Validator(schema, format_checker=FormatChecker()).validate(data)

import "github.com/santhosh-tekuri/jsonschema/v6"

c := jsonschema.NewCompiler()
sch, err := c.Compile("schema.json")
if err := sch.Validate(data); err != nil {
    fmt.Println(err)
}

Häufige Fragen

Welchen Draft soll ich nehmen?

Draft 2020-12 für alles Neue; er ist der aktuell veröffentlichte Draft und das, woran sich OpenAPI 3.1 ausrichtet. Draft-07 bleibt der in älterem Tooling am breitesten unterstützte. Beachten Sie, dass sich die Kennung 2020-12 auf den Zeitpunkt bezieht, zu dem der Draft geschnitten wurde: Die Dokumente unter dieser URI wurden zuletzt im Juni 2022 neu veröffentlicht, was ein Patch ist und keine neue Version.

Warum fehlt ein Feld in required?

Weil es in mindestens einer Stichprobe fehlte. Damit sagt Ihnen der Generator etwas Nützliches. Ist das Feld wirklich verpflichtend, geben Sie ihm eine Stichprobe, in der jeder Datensatz es hat, oder tragen Sie es von Hand in required ein.

Kann er aus mehreren Stichproben erzeugen?

Ja, und Sie sollten das tun. Legen Sie Ihre Stichproben in ein Array und fügen Sie das Array ein. Über viele Datensätze zusammenzuführen ist genau das, was required und Nullbarkeit richtig macht.