draft-07 oder 2020-12
Fazit: 2020-12 ist aktuell und bringt $defs, prefixItems und unevaluatedProperties, aber viele Werkzeuge sprechen nur draft-07. Wählen Sie nach dem, was Ihre gesamte Toolchain unterstützt.
Kurz gesagt: Verwenden Sie 2020-12 für neue Projekte, fallen Sie auf draft-07 zurück, sobald irgendein Validator, Codegenerator oder OpenAPI-Werkzeug nur es unterstützt, und nageln Sie den Draft immer mit $schema fest.
Kurze Antwort: 2020-12 für neue Arbeit, draft-07, wenn eine alte Komponente es erzwingt.
Zeitleiste
| Draft | Jahr | Bemerkenswertes |
|---|---|---|
| draft-04 | 2013 | id statt $id; in älteren APIs noch verbreitet |
| draft-06 | 2017 | const, propertyNames |
| draft-07 | 2018 | if/then/else, readOnly, contentMediaType; beste Kompatibilität |
| 2019-09 | 2019 | $defs ersetzt definitions, unevaluatedProperties |
| 2020-12 | 2020 | prefixItems, $dynamicRef; aktuelle Empfehlung |
Was 2020-12 verbessert
Array-Tupel sind kein Sonderfall mehr. draft-07 drückt „erstes Element ist A, zweites ist B“ mit items: [{...}, {...}] plus additionalItems aus. 2020-12 verwendet prefixItems für positionsspezifische Schemas und items für den Rest.
$defs ist der Standardname. Nach 2019 geschriebene Tooling sucht standardmäßig dort.
unevaluatedProperties funktioniert mit Komposition. Mit allOf weist additionalProperties: false Felder zurück, die von Schwester-Zweigen definiert werden. unevaluatedProperties: false berücksichtigt nur Eigenschaften, die tatsächlich vom gesamten Schema ausgewertet wurden, was Komposition braucht.
Wann draft-07 die richtige Antwort ist
| Situation | Grund |
|---|---|
| OpenAPI 3.0 | Sein Schemaobjekt ist eine draft-04/07-Teilmenge |
| Ältere Validatoren (ajv 6, manche Java-Bibliotheken) | Sie kennen prefixItems oder $dynamicRef nicht |
| Plattform schreibt eine Version vor | Manche Low-Code-Plattformen und Gateways nageln sie fest |
| Codegeneratoren, die bei 07 enden | Unbekannte Schlüsselwörter werden stillschweigend ignoriert |
Testen Sie den letzten Fall direkt: Geben Sie Ihrem Validator ein prefixItems-Schema. Geht es ohne Beschwerde durch, statt ein unbekanntes Schlüsselwort zu melden, ignoriert es die Beschränkung – das gefährlichste Ergebnis von allen.
Versionen mischen
$schema immer deklarieren. Standards unterscheiden sich: ajv nimmt draft-07 an, mehrere Python-Bibliotheken nehmen 2020-12 an. Dieselbe Datei validiert dann an zwei Stellen unterschiedlich.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/order.json",
"type": "object"
}
Kein $ref über Drafts hinweg. Das Verhalten ist undefiniert.
In Batches aktualisieren. Zwei Drafts in einem Repository machen aus „welche Regeln gelten hier“ Stammeswissen.
FAQ
Wie prüfe ich, ob mein Validator 2020-12 unterstützt?
Geben Sie dem Validator ein Schema, das prefixItems verwendet. Ein Fehler über ein unbekanntes Schlüsselwort bedeutet, dass er den Draft nicht unterstützt; stilles Durchgehen bedeutet, dass er die Beschränkung ignoriert, was schlimmer ist.
Warum sollte ein Projekt einen einzigen Draft verwenden?
Zwei Drafts in einem Repository machen aus „welche Regeln gelten hier“ Stammeswissen. Aktualisieren Sie in Batches, damit jede Datei dieselbe Interpretation teilt.
Sollte ich immer $schema deklarieren?
Ja. Standards unterscheiden sich: ajv nimmt draft-07 an, während mehrere Python-Bibliotheken 2020-12 annehmen, dieselbe Datei kann also an zwei Stellen unterschiedlich validieren.