Web APIのフォーマットとしてJSONの採用が増えています。JSONは軽量な記述言語で手軽に扱える反面、そのデータ内容に対する保証がしづらいのが問題視されています。そこで注目を集めているのがJSONの構造を定義するJSON Schemaです。JSONデータに対して型やメタ情報を付与することでフォーマットに対するルールを追加します。
JSON Schemaは現在仕様として策定が進められています。詳細はJSON Schema and Hyper-Schemaにて確認することができます。
今回はJSON Schemaを導入することでどのような可能性が見えてくるのか考えてみたいと思います。
1. バリデーション
まず最初に思いつくのはバリデーションです。これはクライアント、サーバ両方について行えます。データをポストする前に検証したり、受け取ったデータについてバリデーションを自動的に行えるようになります。
検証結果がエラーであれば、それをそのまま返せば良いでしょう。検証後の利用についてはデータ構造や型が保証されるので安心してコードを組めるようになります。
2. データを扱うライブラリの生成
こちらはWebサービスでよくあったスキーマ（WSDLなど）からコードを自動生成するのに似ています。Javaや.NETであればスケルトンコードを生成する形に、RubyやPHP、Pythonなどのスクリプト言語であればメソッドを自動生成する形になるでしょう。
JSONはパースした後、ハッシュや連想配列で扱うことが多いですが、予めコードを生成することでより扱いやすいデータとして使えるようになります。
3. ドキュメント生成
さらにJSON Schemaではデータ構造やURLに対する記述やパラメータの説明も行いますのでAPIドキュメントを生成するのにも使えます。実際のコードとは分離しますので整合性を保つ必要はありますが、後述するテストする仕組みと組み合わせることで最新の状態に保つことができるでしょう。
APIドキュメントを参照する開発者は多いので、このようなアウトプットがあることでJSON Schemaを適切にメンテナンスしていこうというモチベーションにもつながるはずです。
4. ダミーサーバ
Web APIを扱うライブラリのテスト用サーバのベースとしてJSON Schemaが利用できます。サーバ内のロジック部分について保証できるわけではありませんが、ダミーサーバがあることでローカルでの開発やテスト環境下での実行が容易になります。
ただしダミーサーバでは入力値の必須や型などのチェックはできても、トークンの妥当性といったようなロジックのチェックはできません。あくまでも開発時の補助ツールとして使うのが良いでしょう。
5. テストの自動化
そしてWeb API自体のテストを行う際にもJSON Schemaが使えます。予め定義した値をポストして、予定されている結果が得られるかどうかを検証できます。Web APIの拡張を行っていて、例えば新しい必須項目を追加したためにこれまでWeb APIを使っていたシステムが突然動かなくなることがあります。そうした点においてもJSON Schemaをバージョン管理し、全てのバージョンで動き続けているかをチェックできるのは重要です。
Web APIを使ったソフトウェアは完成後、自動運転のフェーズになることが多々あります。そうした時でも結果を担保するためにJSON Schemaが利用できるでしょう。
6. 開発時のエラーチェック
IDEなどであればJSON Schemaを取り込むことで予め警告を表示できるようになるでしょう。JSONの構造はテキストのままでは可読性が低く、読み違えることが多々あります。そうしたミスを防ぐのに使えるはずです。
JSON Schemaは幾つかのメリットがありますが、元々がWSDLなどの複雑さや面倒さから逃れるために生まれたこともあってなかなか普及していません。しかし今後エンタープライズレベルでWeb APIが使われていく中では重要な要素になってくるはずです。
単にやるべきだからやる、ではなくJSON Schemaを使って開発生産性を高めたり、ドキュメントを自動生成するなど負担を軽減することができれば、もっと使われていくのではないでしょうか。
