JSON Schema a remporté la victoire sur les schémas d'API en faisant de la validation un vocabulaire

L'outillage des API a frôlé une occasion manquante douloureuse : OpenAPI utilisait des objets de schéma de type JSON, mais ils n'étaient pas pleinement JSON Schema. Les validateurs, les générateurs de code et les outils de documentation devaient apprendre des différences subtiles, si bien qu'un même contrat d'API pouvait signifier des choses différentes selon les piles techniques.

Le geste élégant n'a pas été de créer un autre langage réservé aux API. JSON Schema a fait du schéma lui-même un type de média JSON, avec des vocabulaires et des méta-schémas qui déclarent quels mots-clés et quels comportements sont en jeu. OpenAPI 3.1 pouvait alors dire : utilisez JSON Schema draft 2020-12, et non un ersatz.

Le résultat fut une norme qui l'a emporté en devenant la grammaire sous-jacente d'autres normes. OpenAPI a qualifié sa version 3.1 de 100 % compatible avec le dernier draft de JSON Schema, tandis que JSON Schema obtenait un modèle d'extension stable pour la validation, la génération de code, l'interface utilisateur et la documentation.

Faire des schémas des vocabulaires extensibles

Le schéma est resté du JSON ordinaire, de sorte que les développeurs pouvaient le lire, le comparer et le générer avec les outils existants.

Les vocabulaires ont donné aux extensions des noms et des frontières au lieu de laisser chaque plateforme inventer des mots-clés privés.

L'adoption d'OpenAPI a tiré JSON Schema dans les flux de travail de documentation d'API, de validation et de génération de code, tous à la fois.

Le draft 2020-12 a donné aux implémenteurs une cible stable, y compris des dialectes et des méta-schémas.

Un format se répand lorsque les extensions sont de première classe et testables, et non dissimulées dans de la prose ou des conventions de fournisseur.

OpenAPI 3.1 est sorti le 18 février 2021 avec une compatibilité complète avec JSON Schema draft 2020-12. Cela a fait de JSON Schema la couche de contrat partagée d'un vaste écosystème d'outillage d'API, plutôt qu'un simple format de validateur autonome.