Ratgeber · JSON Schema 2020-12
OpenAPI und JSON Schema: wie sie zusammenhängen
OpenAPI 3.0 hatte einen JSON-Schema-Subset. OpenAPI 3.1 ist Draft-2020-12-kompatibel. Migration und Tooling-Status im Überblick.
Die kurze Antwort
Seit OpenAPI 3.1 (Februar 2021) ist die Schema-Sprache in OpenAPI identisch mit JSON Schema Draft 2020-12. Vorher: OpenAPI 3.0 hatte ein eigenes Subset, mit einigen Inkompatibilitäten.
Die längere Geschichte
| OpenAPI-Version | JSON-Schema-Relation |
|---|---|
| Swagger 2.0 | Eigenes Subset von Draft 04 |
| OpenAPI 3.0 | Modifiziertes Subset, mit eigenen Erweiterungen (nullable, discriminator) |
| OpenAPI 3.1 | 100 % kompatibel mit Draft 2020-12 + eigene Erweiterungen (discriminator) |
Was sich konkret von 3.0 → 3.1 geändert hat
1. nullable wurde abgeschafft
# OpenAPI 3.0
type: string
nullable: true
# OpenAPI 3.1
type: [string, null]3.1 nutzt JSON-Schema-Stil. nullable wird in 3.1 zwar als Alias akzeptiert von manchen Tools, ist aber deprecated.
2. exclusiveMinimum / exclusiveMaximum als Number
# OpenAPI 3.0
minimum: 0
exclusiveMinimum: true
# OpenAPI 3.1 (= JSON Schema)
exclusiveMinimum: 03. type ist optional
In 3.0 musste jedes Schema ein type haben. In 3.1 (folgt JSON Schema) ist type optional - ein Schema ohne type passt zu allen Typen, die anderen Constraints (z.B. enum, const) bestimmen die Validation.
4. Items-Array für Tupel
In 3.1: prefixItems für Tupel-Validation. In 3.0 ging das nicht.
discriminator: die OpenAPI-Erweiterung
Auch in 3.1: das discriminator-Keyword ist OpenAPI-spezifisch und nicht Teil von JSON Schema. Es hilft Validators bei oneOf-Performance:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
discriminator:
propertyName: petType
mapping:
cat: '#/components/schemas/Cat'
dog: '#/components/schemas/Dog'Migration 3.0 → 3.1 Praxis
Tools die helfen:
- openapi-3.1-migrator (npm): konvertiert nullable, exclusiveMinimum etc.
- Redocly CLI: hat einen migrate-Befehl
- Manuell: für kleine Specs reicht Search & Replace
Tooling-Status 2026
| Tool | OpenAPI 3.1 Support |
|---|---|
| openapi-typescript | Voll (seit 6.x) |
| Redocly | Voll |
| Swagger UI | Voll (seit 5.x) |
| Postman | Voll |
| OpenAPI Generator (Code-Gen) | Teilweise - Sprachen-abhängig |
| AWS API Gateway | Eingeschränkt - eigene Erweiterungen |
Was bedeutet das für deine Schemas?
Wenn du eine OpenAPI-3.1-Spec hast, sind alle components.schemas-Einträge gültige JSON-Schema-Draft-2020-12-Dokumente. Du kannst sie direkt mit Ajv validieren - kein Conversion-Step nötig.
Wenn du noch auf 3.0 bist und Schemas extern nutzen willst: erst auf 3.1 migrieren, dann extrahieren. Manuelle Conversions sind fehleranfällig (besonders bei nullable).
Reine JSON-Schema-Use-Cases
Nicht jedes Schema-Use-Case braucht OpenAPI. Reines JSON Schema reicht für:
- Konfigurations-Dateien-Validation (.eslintrc, package.json)
- Interne Datenstrukturen ohne HTTP-Kontext
- Message-Bus-Payloads (RabbitMQ, Kafka)
- IDE-Autocomplete (VSCode liest .json/.schema)
OpenAPI wird relevant sobald HTTP-Pfade, Status-Codes, Auth-Mechanismen mitdokumentiert werden müssen.