スキーマ

Thing Interaction Framework でステートやコマンドを扱う場合、これらのデータ形式を事前に定めておく必要があります。Thing Interaction Framework では、これらのデータ形式の定義ことをスキーマと呼びます。

スキーマは Thing Interaction Framework を適用するサービスごとに決まる設計情報で、モバイルアプリと Thing の間で共有する必要があります。

スキーマの定義

Thing Interaction Framework で使用するステートのデータ形式や、送信するコマンド（アクション）のパラメータ形式を、スキーマとして定めておきます。

スキーマの例を以下に示します。

• ステート

  Thing のセンサーによる観測値や、現在の設定値などを ステート として扱う際の形式を定めます。

  Thing が Thing Interaction Framework 上のステートを更新する際には、JSON 形式のステートをアップロードします。スキーマでは、フィールドの名前や値の型などを定めます。

• コマンド

  モバイルアプリから Thing に対して コマンド を送信する際の形式を定めます。

  コマンドはアクションの配列として構成されます。また、各アクションは独自のパラメータを持っています。各アクションでは、アクション名と、パラメータのフィールド名や型などを定める必要があります。実行するコマンドに応じてアクションの組み合わせは異なりますが、スキーマの定義はすべてのアクションを対象とします。

  アクションリザルトは名前だけを定めます。形式は成功可否のステータスとエラーメッセージのみで、変更することはできません。

ステートとコマンドを定義したら、スキーマ名とスキーマバージョンをつけて設計を完了します。

Android では、これらの設計情報を SDK の API に渡して利用します（実装方法は スキーマの定義 をご覧ください）。iOS や Thing では設計のヒントとしてのみ利用しますが、後述するようにスキーマ名とスキーマバージョンは実装でも利用します。

現在の Thing Interaction Framework では、特にスキーマの詳細を Thing Interaction Framework 上の設定値としてアップロードしていませんが、設計上、スキーマに合ったデータを扱う必要があります。将来のバージョンでは、スキーマを Thing Interaction Framework 上で管理する可能性もあります。

スキーマのバージョン

スキーマ名とスキーマバージョンによって、実行モジュールのバージョン移行時の問題を回避できます。

モバイルアプリのプログラムと Thing のプログラムは、バージョンアップに伴って不一致が発生する可能性があります。特に、コマンドを受け取る Thing 側の実装では、理解できるスキーマとは異なるコマンドの受信を想定する必要があります。

• モバイルアプリが更新されなかった場合、古いスキーマバージョンのコマンドを受け取ることがあります。
• Thing が更新されなかった場合、Thing にとって未知の新しいスキーマバージョンのコマンドを受け取ることがあります。

Thing 側の SDK では、コマンドと同時にスキーマ名とスキーマバージョンが届くため、これを検出できます。

以下に例を示します。下記 2 の状況では、Thing は Ver.1 と Ver.2 の両方のコマンドを受け取る可能性があります。

バージョンの不一致が発生した場合の実装は、サービスの仕様次第です。影響が少なく安全な方法を選択して実装します。

なお、ステートについては、特にスキーマバージョンの管理を行いません。バージョンアップが行われた際、モバイルアプリで認識できないフィールドが Thing から登録されても、そのフィールドを参照できないことになります。

Thing での解析方法は アクションの解析 をご覧ください。