Ratgeber · JSON Schema 2020-12
Welche JSON-Schema-Draft-Version soll ich nutzen?
Default für neue Projekte: Draft 2020-12. OpenAPI 3.1 ist mit 2020-12 kompatibel. Draft 07 noch dominant in der Praxis, sollte aber nicht neu gewählt werden.
Von Mateusz Viola
Betreiber & redaktionelle Verantwortung json-validator.de
Veröffentlicht
Aktualisiert:
Die Draft-Geschichte im Überblick
JSON Schema wurde 2009 von Kris Zyp gestartet und durchläuft seitdem mehrere Draft-Versionen. Anders als "fertige" Standards ist JSON Schema permanent in Draft-Status (der nächste wird Spec heißen, das ist die geplante 1.0).
| Draft | Jahr | Was Neues |
|---|---|---|
| Draft 04 | 2013 | Erste breit eingesetzte Version |
| Draft 06 | 2017 | const, contains, exclusiveMinimum/Maximum als eigene Keywords |
| Draft 07 | 2018 | if/then/else, readOnly, writeOnly, contentEncoding |
| Draft 2019-09 | 2019 | definitions → $defs umbenannt, recursiveRef, unevaluatedProperties |
| Draft 2020-12 | 2020 | $dynamicRef ersetzt $recursiveRef, prefixItems statt Array-form-items |
Aktuell empfohlene Version
Für neue Projekte: Draft 2020-12. Begründung:
- OpenAPI 3.1 (seit 2021) nutzt exakt diese Version
- Tooling-Support ist stabil (Ajv 8+, python-jsonschema 4+)
- $defs ersetzt definitions sauber, $dynamicRef für rekursive Schemas eleganter als $recursiveRef
Migration Draft 07 → 2020-12
Falls dein Projekt noch Draft 07 nutzt, sind drei Änderungen relevant:
- definitions → $defs: einfach umbenennen, semantisch identisch.
- items als Array → prefixItems: Für Tupel-Validation. Wenn du nur Schema-pro-Element-Type hast (häufigster Fall), keine Änderung nötig.
- dependencies → dependentRequired + dependentSchemas: dependencies wurde aufgespalten in zwei separate Keywords.
Was sich NICHT geändert hat
Die meisten Keywords sind stabil seit Draft 04:
- type, properties, required, additionalProperties
- minLength, maxLength, pattern, format
- minimum, maximum, multipleOf
- minItems, maxItems, uniqueItems
- allOf, anyOf, oneOf, not
- enum, const
Welche Drafts in der Praxis genutzt werden
| Draft | Verbreitung 2026 | Empfehlung |
|---|---|---|
| 04 | Legacy (CloudFormation, alte Schemas) | Migrieren |
| 06 | Selten | Skippen |
| 07 | Noch dominant (Swagger, ältere OpenAPI-3.0) | OK für Bestand |
| 2019-09 | Mittelmäßig | Direkt auf 2020-12 |
| 2020-12 | Wachsend (OpenAPI 3.1) | Neue Projekte hier starten |
Wie das Tool die Version bestimmt
Der Validator oben liest das $schema-Keyword aus deinem Schema-Input. Ist es gesetzt, wird die entsprechende Draft-Version verwendet. Fehlt es, fällt das Tool auf Draft 2020-12 zurück.
Best-Practice: $schema immer explizit setzen. Damit ist klar, gegen welche Spec validiert wird - auch für andere Tools die das Schema später konsumieren.