WoT Thing Description とは
WoT Thing Descriptionは、IoT (Internet of Things) にとっての「Webサイトにおけるindex.html (HTML)」のような基本的記述モデルであり、物理的もしくは仮想的なモノ/デバイスのエントリポイントとみなされるものです。
ここでは、Thing Descriptionの概要と記述方法をRaspberryPiでThingを作るで作成したモノのThing Descriptionを通してみていきます(RaspberryPiでThingを作る Thing Description全体のダウンロード)。
仕様の詳細は、Web of Things (WoT) Thing Description 原文または日本語訳をご覧ください。
Thing Descriptionの構成#
WoTの相互作用モデルでは、3種類の相互作用のアフォーダンスが定義されています。
| プロパティー(Property) | Thingの状態を公開する相互作用のアフォーダンス。そして、この公開された状態は、取得 (読み取り) することができる。また、オプションで更新 (書き込み) することができる。Thingは、変更後の新しい状態をプッシュすることにより、プロパティーを監視可能にすることも選択できる。 |
|---|---|
| アクション(Action) | 状態を操作したり (例えば、照明のオン/オフを切り替える)、Thingにおけるプロセスを始動させる (例えば、時間の経過とともに照明を暗くする) といった、Thingの機能の呼び出しを可能にする相互作用のアフォーダンス。 |
| イベント(Event) | イベント (例えば、オーバーヒートの警報) の出どころを記述している相互作用のアフォーダンスで、当該イベントのデータをConsumerに非同期でプッシュする。 |
これらの3種類(プロパティー・アクション・イベント)の相互作用のアフォーダンスと、
- Thing自身に関するテキスト形式のメタデータ
- Thingと交換されるデータの機械が理解できるスキーマ
- ウェブ上の他のThingやドキュメントとの形式的または非形式的な関係を表すためのウェブリンク
の4つの主要コンポーネントから下図のようにThing Descriptionは構成されています。
Thing Descriptionの記述方法#
Web of Thingsでは、Thing Descriptionという共通フォーマットをつかって記述することで、機械にも人にも読むことができる仕様書として示すことができます。
Thing DescriptionはJSON-LDをベースとしたフォーマットになっています。
Thingのルートオブジェクト・メタデータの記述#
はじめに、Thingのルートオブジェクトを記述します。 Thing Descriptionは、Thing型のオブジェクトをルートとするデータ構造です。
{ "@context": [ "https://www.w3.org/2019/wot/td/v1", ],ルート要素として、@contextでこのファイルがThing Descriptionであることを示します。
"id": "urn:dev:mac:00c141ffff25084e", "title": "MyFirstLEDLamp", "titles": { "en": "MyFirstLEDLamp", "ja": "私の最初のLEDランプ" }, "description": "Simple LED Lamp using Node-RED", "descriptions": { "en": "Simple LED Lamp using Node-RED", "ja": "Node-REDをつかったシンプルなLEDランプ" },title,descriptionでは、人間が読める形でモノの名前や説明を記述します。多言語で記述可能で、Thing Descriptionの利用アプリケーション側で適切な言語を選択して表示できるようになっています。
| keyword | type | 説明 |
|---|---|---|
| @context | anyURIまたは配列 | TDドキュメント全体で用いる、用語と呼ばれる省略名を定義するためのJSON-LDキーワード。 |
| title | string | デフォルトの言語に基づいて、人間が読めるタイトルを提供する (例えば、UI表現用のテキストを表示)。 |
これらの必須以外の語彙や詳細は、Thing Description 仕様書のThingのコア語彙の定義をご覧ください。
セキュリティの記述#
"securityDefinitions": { "nosec_sc": { "scheme": "nosec" } }, "security": [ "nosec_sc" ],このモノにアクセスする際の認証方法などを記載します。
例えば、上記のようにパスワード認証などを付けていない場合はnosecとします。
| keyword | type | 説明 |
|---|---|---|
| security | stringまたはstringの配列 | セキュリティ定義名の集合。securityDefinitionsで定義されているものから選定する。リソースにアクセスするためには、これらすべてが満たされていなければならない。 |
| securityDefinitions | SecuritySchemeのマップ | 名前付きセキュリティ構成情報 (定義のみ) の集合。securityの名前-値のペアで名前が用いられていなければ、実際には適用されない。 |
これらの必須以外の語彙やセキュリティに関する詳細は、Thing Description 仕様書の Thingのコア語彙の定義やセキュリティ語彙の定義をご覧ください。
相互作用のアフォーダンスの記述#
各アフォーダンスと相互作用を行うための方法をforms構造によって示します。
| keyword | type | 説明 |
|---|---|---|
| forms | Formの配列 | 操作の実行方法を記述する、フォームのハイパーメディア制御の集合。フォームは、プロトコルバインディングのシリアライゼーションである。 |
| href | anyURI | リンクのターゲットIRIまたはフォームの送信ターゲット。 |
これら以外の語彙や詳細は、Thing Description 仕様書のコア語彙の定義をご覧ください。 また、プロパティー・アクション・イベントの記述の際には、InteractionAffordance や PropertyAffordance、 ActionAffordance、EventAffordance などそれぞれのクラスの定義もご覧ください。
プロパティの記述#
"properties": { "led": { "title": "LED status", "titles": { "en": "LED status", "ja": "LEDの状態" }, "type": "object", "properties": { "value": { "type":"number" } }, "forms": [ { "href": "http://example.com:1880/led", "op": [ "readproperty", "writeproperty" ], "contentType": "application/json" } ] } },このモノがもつ「プロパティ」とそのプロパティへのアクセス方法を記述します。titleから、このモノはLEDの状態を持っており、formsから、読み書きするときにどのURLにどうアクセスすればよいかがわかります。
また、type,propertiesから、それらの情報は{"value":数値}というJSONで表現されることがわかります。
アクションの記述#
"actions": { "toggle": { "title": "toggle a switch", "titles": { "en": "toggle a switch", "ja": "スイッチをトグルする" }, "safe": false, "idempotent": false, "forms": [{ "op": "invokeaction", "href": "http://example.com:1880/toggle", "contentType": "application/json" }] } },このモノが受け付ける「アクション」とそのアクションの起動方法を記述します。
同じくtitleによってこれがスイッチをトグルするアクションであり、formsでアクセスの方法がわかります。
イベントの記述#
"events": { "toggled": { "title": "switch is toggled", "titles": { "en": "switch is toggled", "ja": "スイッチがトグルされた" }, "data": { "type": "object", "properties": { "value": { "type": "number" } } }, "forms": [ { "href": "ws://example.com:1880/toggled", "op": "subscribeevent", "contentType": "application/json" } ] } }}最後は「イベント」の情報です。
これまでと同様に、titleでスイッチのトグルの情報がイベントで取得できること、formsでそのイベントを購読する方法が分かります。
ここでは必須でない項目は省いて書いていますが、 これ以外にも他で定義された語彙をつかってより詳しくこの モノについての説明を書くことができます。 例えば、Smart Appliances REFerence (SAREF) ontologyの語彙を使って、
{ "@context": [ "https://www.w3.org/2019/wot/td/v1", { "saref": "https://w3id.org/saref#" } ], "@type": [ "saref:Lighting device", "saref:LightSwitch" ] ...と書くことで、このモノが照明とそのスイッチであることが明確になります。