JSON Schema gewann API-Schemas, indem es Validierung zu einem Vokabular machte

Die API-Tooling-Welt erlebte eine schmerzhafte Beinahe-Übereinstimmung: OpenAPI verwendete JSON-ähnliche Schemaobjekte, die aber keine vollständigen JSON Schemas waren. Validatoren, Codegeneratoren und Dokumentationswerkzeuge mussten subtile Unterschiede erlernen, sodass derselbe API-Vertrag in verschiedenen Stacks unterschiedliche Bedeutungen haben konnte.

Der elegante Schritt bestand nicht darin, eine weitere reine API-Sprache zu schaffen. JSON Schema machte das Schema selbst zu einem JSON-Medientyp, mit Vokabularen und Meta-Schemas, die deklarieren, welche Schlüsselwörter und Verhaltensweisen gelten. OpenAPI 3.1 konnte dann sagen: Verwende JSON Schema Draft 2020-12, keinen Nachahmer.

Das Ergebnis war ein Standard, der gewann, indem er zur Grammatik unter anderen Standards wurde. OpenAPI bezeichnete seine Version 3.1 als 100 % kompatibel mit dem neuesten JSON-Schema-Draft, während JSON Schema ein stabiles Erweiterungsmodell für Validierung, Codegenerierung, UI und Dokumentation erhielt.

Schemas zu erweiterbaren Vokabularen machen

Das Schema blieb gewöhnliches JSON, sodass Entwickler es mit vorhandenen Werkzeugen lesen, diffen und generieren konnten.

Vokabulare gaben Erweiterungen Namen und Grenzen, statt dass jede Plattform private Schlüsselwörter erfand.

Die OpenAPI-Adoption zog JSON Schema gleichzeitig in API-Dokumentation, Validierung und Codegenerierungs-Workflows.

Draft 2020-12 gab Implementierern ein stabiles Ziel, einschließlich Dialekten und Meta-Schemas.

Ein Format verbreitet sich, wenn Erweiterungen erstklassig und testbar sind, nicht in Prosa oder Herstellerkonventionen versteckt.

OpenAPI 3.1 wurde am 18. Februar 2021 mit vollständiger Kompatibilität zu JSON Schema Draft 2020-12 veröffentlicht. Damit wurde JSON Schema zur gemeinsamen Vertragsschicht für ein großes API-Tooling-Ökosystem und nicht nur zu einem eigenständigen Validator-Format.