JSON Schemaが検証を語彙にすることでAPIスキーマを制した理由

APIツールの世界には、惜しいすれ違いがあった。OpenAPIはJSONに似たスキーマオブジェクトを使っていたが、それは完全なJSON Schemaではなかった。バリデータ、コード生成ツール、ドキュメントツールは微妙な違いを学ぶ必要があり、同じAPIコントラクトが異なるスタックで異なる意味を持ち得た。

優雅な一手は、API専用の別言語を新たに作ることではなかった。JSON Schemaはスキーマ自体をJSONメディアタイプとし、どのキーワードと振る舞いが有効かを宣言する語彙とメタスキーマを備えた。これによりOpenAPI 3.1は、似て非なるものではなく、JSON Schema draft 2020-12を使う、と言えるようになった。

その結果は、他の標準の下にある文法となることで勝ち取った標準だった。OpenAPIは3.1リリースを最新のJSON Schemaドラフトと100%互換と称し、一方のJSON Schemaは検証、コード生成、UI、ドキュメントのための安定した拡張モデルを手に入れた。

スキーマを拡張可能な語彙にした

スキーマは通常のJSONのままだったので、開発者は既存のツールで読んだり、差分を取ったり、生成したりできた。

語彙は、各プラットフォームが独自のキーワードを発明するのではなく、拡張に名前と境界を与えた。

OpenAPIの採用により、JSON SchemaはAPIドキュメント、検証、コード生成のワークフローに一挙に引き込まれた。

Draft 2020-12は、方言やメタスキーマを含め、実装者に安定した目標を与えた。

拡張が散文やベンダーの慣習に隠されるのではなく、第一級でテスト可能であるとき、フォーマットは広がる。

OpenAPI 3.1は2021年2月18日に、JSON Schema draft 2020-12との完全な互換性を備えて出荷された。これによりJSON Schemaは、単なる独立したバリデータ形式ではなく、大規模なAPIツールエコシステムの共有コントラクト層となった。