JSON スキーマのアーキテクチャスコープ

最近、JSON スキーマのアーキテクチャにおける位置について考えるきっかけとなるいくつかの会話がありました。今日はそれらの考えの一部を共有したいと思います。

JSON スキーマとは？

JSON スキーマは、JSON 値を記述するメカニズムを定義する仕様であり、その値の検証とアノテーションに使用できます。このメカニズムは、それぞれが定義された動作を提供するいくつかのキーワードに編成されています。

キーワードの単一セットは「スキーマ」を構成します。

このシステムは、それ自体が JSON 値として表現可能なスキーマと、スキーマ内のルールが適用される JSON 値（「インスタンス」と呼びます）を入力として受け取ります。この記事では、これらのルールの適用を「評価」と呼びます。（つまり、スキーマはインスタンスを「評価」します。）

評価の出力は、各ルールの個々のエラーと／またはアノテーションの集計です。

しかし、一般的に、動作のシステムはやや抽象的であり、実際には役に立ちません。必要なのは、コードにおけるこのシステムの実現です。必要なのは実装です。

JSON スキーマを有効に活用する

JSON スキーマを有効に活用するには、まず誰にとって有用であるべきかを問う必要があります。その答えを得るには、そもそも JSON スキーマが存在する理由を知る必要があります。

前のセクションで説明したように、スキーマはインスタンスを評価して、インスタンスがスキーマによって表されるすべてのルールに準拠していることを確認します。インスタンスがスキーマ内のルールに準拠している場合、そのスキーマに対して「有効」であると言います。

有効な JSON データを確保する理由は数多くあります。プログラムモデルへの逆シリアル化の前にデータをチェックする、送信前にフォーム入力をチェックするなどです。これらはアプリケーションのニーズです。

そのため、アプリケーションは JSON スキーマのコンシューマーです。

では、アノテーションはどうでしょうか？アノテーションは、アプリケーションが追加の動作を提供できるように意図的に設計されています。したがって、ここでもアプリケーションがコンシューマーです。

しかし、アプリケーションは、仕様がコードに実現されていない限り、仕様を利用できません。そこで実装が登場します。

JSON スキーマの実装とは、アプリケーションが直接利用できる仕様の具現化です。

微妙な点

最近よく見かけることであり、私の議論の中で生じた混乱の原因だと思うのは、アプリケーションが実装を単なる実行可能ラッパーに過ぎないことです。これは、アプリケーション自体が実装であるように見えがちであり、その場合、アプリケーションは仕様の要件の対象となります。しかし、私はそうは考えていません。これらの場合でも、実際には非常に曖昧であっても、アプリケーションと実装の間に区別が存在します。

注記 この区別が実際には曖昧であることを認識することが重要です。これは現在議論中の項目であり、この分野ではまだ公式に何も定義されていません。

アプリケーションには、一般的にインターフェース（UX または API）、ビジネスロジック、データ永続化の3つの基本的なコンポーネントがあります。すべてのアプリケーションはインターフェースを持っています。しかし、ビジネスロジックとデータ永続化コンポーネントは、一方または両方、あるいは両方とも省略可能です。（UX のみが含まれるアプリケーションは、一般的にあまり役に立ちません。）

アプリケーションは、データ永続化を介してインターフェースのみを提供する場合があります（例：Postgres Web サービス）。つまり、ビジネスロジックは必要ありません。逆に、別のアプリケーションは、データを永続化する必要がない計算サービス（例：画像処理）を提供する場合があります。

私が最近行った会話では、この2番目のシナリオが当てはまるようです。つまり、スキーマに対してインスタンスを評価するだけのアプリケーションが作成されています。しかし、これはアプリケーションと実装が同じものであるという意味ではありません。

これらのアプリケーション内では、これらのアプリケーションにとってビジネスロジックである実装は、インターフェースとは依然として別個のコンポーネントです。そして、JSON スキーマという仕様は、実装部分のみをカバーできることを認識することが重要です。

なぜこれが重要なのか

すべては、冒頭で触れたことに帰着します。JSON スキーマは、入力と出力を定義する必要があります。これは、実装とアプリケーションがお互いに通信するために使用できる最小限の API を構成します。

実装とアプリケーションの境界が曖昧になると、仕様がアプリケーションがユーザーとどのように通信するかについての要件を課していると思うのは当然です。しかし、そうではありません。

JSON スキーマは、アプリケーションのユーザーのニーズを知ることは不可能であるため、アプリケーションが準拠する必要がある入力と出力の要件を定義しようとするのは非現実的です。

異なるアプリケーションのユーザーには、異なるニーズがあります。本質的に実装の UX を提供する2つのアプリケーション（Web アプリと CLI など）を考えたとしても、2つのアプリケーションが基本的に同じことを行っているにもかかわらず、ユーザーの UX ニーズは大きく異なります。

仕様書の範囲

上記すべてを踏まえると、仕様の入力と出力の要件は、アプリケーションと JSON スキーマの実装の間に明確な通信の境界がある場合にのみ適用されることがわかります。

仕様書では、プログラミング言語やフレームワークはテキスト形式の JSON を扱わない可能性が高く、むしろその言語の制限内で定義されたデータモデルを使用することになることを認識しています。そのため、実装が利用可能なものを自由に使用できるように、抽象的な JSON データと JSON スキーマモデルの観点から入力と出力を定義しています。

具体的には、これらの要件は、JSON スキーマ仕様の汎用表現として提供され、不明な当事者によって消費されるスタンドアロン実装にのみ関係します。

実装を統合しているアプリケーション、または特別な契約を持つアプリケーション／実装ペアは、これらの取り決めは仕様の範囲外であるため、これらの要件に準拠する必要はありません。

表紙写真は私撮影です 😁