Web of Things (WoT) Thing Description 2.0

メタデータとインターフェイスが WoT Thing Description によって記述される、物理的または仮想的なエンティティの抽象。 ここで仮想的なエンティティは、1 つ以上の Things の合成である。

@context については、 Thing Description インスタンスに対して次の規則が定義される:

• @context name-value pair は、文書を TD 1.1 として識別し、 Consumers が新たに導入された用語を 使用できるようにするため、anyURI https://www.w3.org/2022/wot/td/v1.1 を 含まなければならない（MUST）。
• TD 1.0 consumers が 存在する可能性がある場合、anyURI https://www.w3.org/2019/wot/td/v1 は最初の項目でなければならず（MUST）、 https://www.w3.org/2022/wot/td/v1.1 は 2 番目の項目でなければならない （MUST）。
• TD 1.1 consumers は、 W3C WoT Thing Description 1.0 [wot-thing-description10] 仕様を満たす TD を受け入れなければならない （MUST）。
• @context が Array である場合、anyURI https://www.w3.org/2022/wot/td/v1.1 の後に、型 anyURI または型 Map の要素を任意の順序で続けてもよい （MAY）が、 @context Array 内のすべての name-value pair を含む Map は 1 つだけ含めることが推奨される （RECOMMENDED）。
• @context Array に含まれる Maps は、値が型 anyURI の名前空間識別子であり、 名前がその名前空間を表す Term または接頭辞である name-value pair を含んでもよい （MAY）。
• @context Array に含まれる 1 つの Map は、 Thing Description の既定言語を定義する name-value pair を含むべきである （SHOULD）。ここで、名前は Term @language であり、 値は [BCP47] で定義される整形式の言語タグである （例: en、de-AT、 gsw-CH、zh-Hans、 zh-Hant-HK、 sl-nedis）。

Thing Description および Thing Model インスタンス内のすべての人間可読テキストの基底方向を決定するため、 この仕様は、基底方向メタデータを関連付ける組み込み機構が利用できない場合に、 [STRING-META] の 文字列固有の方向情報に関する指針に従うことを推奨する。

TD Processors は、双方向テキストを処理する際の特定の特殊ケースを 認識しておくべきである。TD Processors は、 ユーザーに文字列を提示するとき、特に周囲のテキストに埋め込む場合 （例: Web ユーザーインターフェイス）には、 bidi isolation を使用するよう注意すべきである （SHOULD）。 言語が適切に識別されている場合でも、混在方向テキストは任意の言語で発生し得る。

TD producers は、 素朴なユーザーエージェントでも正常に表示できる方法で 混在方向文字列を提供するよう試みるべきである （SHOULD）。 たとえば、RTL 文字列が LTR の並び（数字、ラテン文字のブランド名や商標名など）で始まる場合、 文字列の先頭に RLM 文字を含める、または反対方向の並びを bidi controls で 囲むことで、適切な表示を支援できる。

Strings on the Web: Language and Direction Metadata [string-meta] は、双方向テキストを使用する際の指針を提供し、多くの落とし穴を例示している。

properties、 actions、および events Maps 内に明示的に提供される Interaction Affordances に加えて、Thing は meta-interactions も提供できる。これは任意の forms Array 内の Form インスタンスによって示される。 Thing インスタンスの forms Array が Form インスタンスを含む場合、それは op メンバーを 含まなければならず（MUST）、 name op に割り当てられた文字列値は、直接または Array 内のいずれかで、 次の operation types のいずれかでなければならない （MUST）: readallproperties、 writeallproperties、 readmultipleproperties、 writemultipleproperties、 observeallproperties、 unobserveallproperties、 queryallactions、 subscribeallevents、または unsubscribeallevents。（Thing インスタンスにおける form の使用例については、例を参照。）

各 property meta-interaction のデータスキーマは、 各 PropertyAffordance インスタンスのデータスキーマを 単一の ObjectSchema インスタンスに結合することで構築される。 ここで、ObjectSchema インスタンスの properties Map は、 対応する PropertyAffordances インスタンスの名前によって識別される 各 PropertyAffordances のデータスキーマを含む。

別途指定されていない限り（例: TD Context Extension を通じて）、 readmultipleproperties 操作のリクエストデータは、 意図された PropertyAffordances インスタンス名を含む Array であり、 Form インスタンスによって指定される content type へ シリアル化される。

Consumers に可能な選択肢を示し、 それによって Consumers が Thing とどのように相互作用できるかを 示唆する Thing のメタデータ。潜在的な affordance には多くの種類があるが、 W3C WoT は Interaction Affordances として Properties、Actions、Events の 3 種類を定義する。

InteractionAffordance クラスは、次の サブクラスを持つ:

• PropertyAffordance
• ActionAffordance
• EventAffordance

Thing の状態を公開する Interaction Affordance。 この状態はその後、取得（read）および/または 更新（write）できる。Things は、変更後に新しい状態を プッシュすることで、Properties を observable にすることも 選択できる。

PropertyAffordance は、 InteractionAffordance Class および DataSchema Class の Subclass である。Form インスタンスが PropertyAffordance インスタンス内にある場合、op に割り当てられる値は MUST readproperty、writeproperty、 observeproperty、 unobserveproperty のいずれか、またはこれらの用語の組み合わせを含む Array でなければならない。

Thing の関数を呼び出せるようにする Interaction Affordance であり、状態を操作する（例: ランプのオン/オフを切り替える）か、Thing 上で プロセスをトリガーする（例: 時間をかけてランプを暗くする）。

ActionAffordance は、 InteractionAffordance Class の Subclass である。Form インスタンスが ActionAffordance インスタンス内にある場合、op に割り当てられる値は MUST invokeaction、 queryaction、cancelaction のいずれか、または これらの用語の組み合わせを含む Array でなければならない。

event データを Consumers に非同期にプッシュする event ソースを記述する Interaction Affordance （例: 過熱アラート）。

EventAffordance は、 InteractionAffordance Class の Subclass である。Form インスタンスが EventAffordance インスタンス内にある場合、op に割り当てられる値は MUST subscribeevent、 unsubscribeevent のいずれか、または Array 内の両方の用語でなければならない。

EventAffordances は、Thing 自身が関心を持つ Consumers に状態変化を通知するという意味で、observable PropertyAffordances に似ている。 しかし、EventAffordances の主な違いは、 関連リソースのすべての変化が event メッセージの送出を トリガーする必要はない点である。たとえば、数値の 重大なしきい値などである。さらに、 EventAffordances は、 subscription、dataResponse、および cancellation DataSchema 定義によって、より複雑な購読および 購読解除機構を可能にする。ただし、すべての プロトコルがこれらのより高度な機構をサポートするとは限らないため、 一部のシナリオでは、events は observable PropertyAffordances と 非常に似たものになる場合がある。このような場合、 Affordance をモデル化するために Property と Event のどちらを選択するかは、 基礎となるリソースの意味論に基づいて行うべきである。たとえば、 affordance の状態も Consumer によって読み取りまたは書き込みされることが 想定される場合、Property が最も適切な選択である可能性が高い。

TD 文書に関するバージョン情報を提供する Thing のメタデータ。必要に応じて、ファームウェアやハードウェアのバージョンなどの 追加のバージョン情報（TD 名前空間外の term 定義）は、TD Context Extension 機構を介して拡張できる。

VersionInfo Class の instances および model 内の値は、 ドットで区切られた 3 つの数値の列が、それぞれ メジャーバージョン、マイナーバージョン、パッチバージョンを示す セマンティックバージョニングのパターンに従うことが推奨される。詳細は [SEMVER] を参照。

[BCP47] に記述された 言語タグによって識別される、異なる言語の人間可読テキストの集合を提供する Map。 Thing Description インスタンス内でのこのコンテナーの使用例については、 6.3.2 人間可読 メタデータ を参照。

MultiLanguage Map の各名前は、 [BCP47] で定義される 言語タグでなければならない（MUST）。 MultiLanguage Map の各値は、 型 string でなければならない（MUST）。

使用されるデータ形式を記述するメタデータ。 検証に使用できる。

DataSchema クラスは、次の サブクラスを持つ:

• ArraySchema
• BooleanSchema
• NumberSchema
• IntegerSchema
• ObjectSchema
• StringSchema
• NullSchema

format 文字列値は、固定された値の集合と、 [JSON-SCHEMA] （特に Section 7.3 Defined Formats）で定義される対応する format rules から知られる。 Servients は、format 値を使用して、 それに応じた追加の検証を実行してもよい （MAY）。 既知の値の集合に見つからない値が format に割り当てられた場合、そのような検証は 成功すべきである（SHOULD）。

Array 型のデータを記述するメタデータ。 この Subclass は、 DataSchema インスタンス内の type に割り当てられる 値 array によって示される。

boolean 型のデータを記述するメタデータ。 この Subclass は、 DataSchema インスタンス内の type に 割り当てられる値 boolean によって示される。

number 型のデータを記述するメタデータ。 この Subclass は、 DataSchema インスタンス内の type に 割り当てられる値 number によって示される。

integer 型のデータを記述するメタデータ。 この Subclass は、 DataSchema インスタンス内の type に 割り当てられる値 integer によって示される。

Object 型のデータを記述するメタデータ。 この Subclass は、 DataSchema インスタンス内の type に割り当てられる 値 object によって示される。

string 型のデータを記述するメタデータ。 この Subclass は、 DataSchema インスタンス内の type に 割り当てられる値 string によって示される。

null 型のデータを記述するメタデータ。 この subclass は、DataSchema インスタンス内の type に割り当てられる 値 null によって示される。この Subclass は、 許容される唯一の値、すなわち null のみを記述する。 null は値が存在しないことを意味しない点に 注意することが重要である。これは JavaScript の null、 Python の None、Java の null、Ruby プログラミング言語の nil に類似している。これは oneOf 宣言の一部として使用でき、 データが null にもなり得ることを示すために使用される。

セキュリティ機構の構成を記述するメタデータ。 name scheme に割り当てられる値は、 Thing Description に含まれる Vocabulary 内で定義されなければならない （MUST）。 それは § 5. TD Information Model で定義される標準 Vocabulary 内、または TD Context Extension 内のいずれかである。

すべてのセキュリティスキームについて、 アクセスを直接提供する鍵、パスワード、またはその他の機密情報は TD に保存してはならず（MUST NOT）、 代わりに他の機構を介して out-of-band に共有および保存されるべきである。 TD の目的は、Consumer がすでに認可を持っている場合に限り、 Thing にアクセスする方法を記述することであり、その認可を付与するために 使用されることを意図していない。

TD で使用される各 security scheme オブジェクトは、 アクセスが許可される前に満たされるべき要件の集合を定義する。 その要件がすべて満たされたとき、セキュリティスキームは satisfied であるという。場合によっては、アクセスが許可される前に 複数の security schemes からの要件を満たす必要がある。

セキュリティスキームは通常、パスワードや鍵などの追加の 認証パラメーターを要求する場合がある。この情報の場所は、 name in に関連付けられた値によって示され、 多くの場合 name に関連付けられた値と組み合わせて使用される。 in に関連付けられた値は、次の値のいずれかを取ることができる:

header:

パラメーターは、プロトコルによって提供されるヘッダー内で与えられ、 ヘッダー名は name の値によって提供される。

query:

パラメーターは URI に query parameter として追加され、 query parameter の名前は name によって提供される。

body:

パラメーターはリクエストペイロードの body 内で提供され、 使用される data schema 要素は name によって提供される。 body セキュリティ情報 場所の文脈で使用される場合、name の値は、 それが使用される各 interaction の入力 DataSchema のルートに相対的な JSON pointer [RFC6901] の形式でなければならない（MUST）。 この値は fragment identifier ではなく、TD のルートに対する相対でもなく、 セキュリティスキームが結び付けられている任意の data schemas に対する相対であるため、 この値は # で始まるべきではない。これは「純粋な」 JSON pointer である。この値は fragment identifier ではないため、 特殊文字を URL エンコードする必要もない。対象要素は、参照された object または array schema 内の指定された場所にすでに存在していてもよいし、 存在していなくてもよい（したがってこの機構は simple types には適用できない）。 存在しない場合、それは挿入される。これにより、すべての interaction の data schemas 内で定義を重複させる必要がなくなる。 body locator で示される JSON pointer によって示される data schema の要素が、 示された schema 内にまだ存在しない場合、その pointer によって示される場所に 示された要素を挿入できなければならない （MUST）。 body locator で使用される JSON pointer は、既存の array の最後の要素の後に要素を挿入する必要がある場合、 存在しない array 要素を示すために "-" 文字を使用してもよい（MAY）。 body セキュリティ情報 場所によって参照（または作成）される要素は、 required であり、型 "string" でなければならない （MUST）。 name が与えられていない場合、body 全体が セキュリティパラメーターとして使用されると仮定される。

cookie:

パラメーターは name の値によって識別される cookie に保存される。

uri:

パラメーターは URI 自体に埋め込まれ、関連する interaction で name の値によって定義される URI template variable を使用して 符号化される。これは query 機構より一般的だが、 より複雑である。 値 uri は、query が適用できない場合にのみ、 security scheme 内の name in に対して指定されるべきである （SHOULD）。 in の値として uri を使用する security scheme の interactions で提供される URI は、定義された変数を含む URI template でなければならない（MUST）。

auto:

場所はプロトコルの一部として決定される、または交渉される。 SecurityScheme の in フィールドに auto の値が設定されている場合、 name フィールドは設定されるべきではない （SHOULD NOT）。 この場合、SecurityScheme の適用は、 所定のプロトコルに対する各仕様に従う（例: HTTP で BasicSecurityScheme を使用する場合の [RFC8288]）。

security scheme に複数のパラメーターが必要な場合、 各パラメーターについて security scheme 定義を繰り返し、 combo security scheme と allOf を使用して それらを組み合わせる。場合によっては、パラメーターは実際には秘密ではないが、 ユーザーがプライバシー保護のために TD から除外したいことがある。 例として、一部のセキュリティ機構では client identifier と secret key の 両方が必要である。理論上、client identifier は公開情報であるが、 更新が難しく、追跡リスクをもたらす場合がある。このような場合、 それが TD に現れないように、追加のセキュリティパラメーターとして 提供できる。

SecurityScheme で宣言される URI 変数の名前は、 TD 内で宣言される他のすべての URI 変数と異なっていなければならない （MUST）。

SecurityScheme クラスは、次の サブクラスを持つ:

• NoSecurityScheme
• AutoSecurityScheme
• ComboSecurityScheme
• BasicSecurityScheme
• DigestSecurityScheme
• APIKeySecurityScheme
• BearerSecurityScheme
• PSKSecurityScheme
• OAuth2SecurityScheme

Vocabulary Term nosec（すなわち "scheme": "nosec"）によって識別されるセキュリティ構成であり、 リソースへアクセスするために認証やその他の機構が不要であることを示す。

用語 auto（すなわち "scheme": "auto"）によって識別される 自動認証セキュリティ構成。この scheme は、 セキュリティパラメーターが実行時に基礎となるプロトコルによって 交渉され、各プロトコルの仕様に従うことを示す （例: HTTP 使用時の Basic Authentication については [RFC8288]）。

Vocabulary Term combo（すなわち "scheme": "combo"）によって識別される、他のセキュリティスキームの組み合わせ。 この scheme の要素は、securityDefinitions で定義される 他の名前付き schemes（他の ComboSecurityScheme 定義を含む）を組み合わせ、新しい scheme 定義を作成するさまざまな方法を定義する。 oneOf または allOf vocabulary terms のいずれか一方だけが 含まれなければならない（MUST）。 一緒に使用できる security scheme 定義のみを allOf と組み合わせることができる。たとえば、 一方が proxy に、もう一方が endpoint に適用される場合を除き、 異なる OAuth 2.0 flows を allOf を使用して 一般に組み合わせることはできない。security フィールドに 複数の名前付き security scheme 定義が列挙されている場合、 allOf 組み合わせと同じ意味論が適用される （許可される組み合わせに関する同じ制限も適用される）ことに注意。 oneOf 組み合わせは、それ以外は同一の forms 上で 異なる security schemes を使用することと等価である。この意味では oneOf scheme は本質的な機能ではないが、 そのような場合の冗長性を避けることができる。

暗号化されていないユーザー名とパスワードを使用する、 Vocabulary Term basic（すなわち "scheme": "basic"）によって識別される Basic Authentication [RFC7617] セキュリティ構成。

Vocabulary Term digest（すなわち "scheme": "digest"）によって識別される Digest Access Authentication [RFC7616] セキュリティ構成。この scheme は basic authentication に似ているが、man-in-the-middle attacks を回避するための 追加機能を備えている。

Vocabulary Term apikey（すなわち "scheme": "apikey"）によって識別される API key authentication セキュリティ構成。この scheme は access token が opaque である場合、 たとえばクラウドサービスプロバイダーによって未知または独自形式の鍵が 提供される場合に使用される。その場合、その鍵は標準的な token 形式を 使用していない可能性がある。この scheme は、サービスプロバイダーによって 提供される鍵を、"in" フィールドで示される機構を使用して サービスリクエストの一部として供給する必要があることを示す。

Bearer tokens が OAuth2 から独立して使用される状況向けに、 Vocabulary Term bearer（すなわち "scheme": "bearer"）によって識別される Bearer Token [RFC6750] セキュリティ構成。oauth2 scheme が指定されている場合、それは暗黙に含まれるため、通常この scheme も 指定する必要はない。format について、 値 jwt は [RFC7519] への適合を示し、 jws は [RFC7797] への適合を示し、 cwt は [RFC8392] への適合を示し、 jwe は [RFC7516] への適合を示す。 alg の値は、これらの標準と一貫して解釈される。 Bearer token の その他の形式およびアルゴリズムは、語彙拡張で指定してもよい （MAY）。

Vocabulary Term psk（すなわち "scheme": "psk"）によって 識別される pre-shared key authentication セキュリティ構成。 これは、TLS-PSK [RFC4279] などの pre-shared keys に標準が使用されること、および keys に使用される ciphersuite がプロトコル交渉中に確立されることを識別することを意図している。

[RFC6749] および [RFC8252] に適合するシステム向けの OAuth 2.0 authentication セキュリティ構成であり、 Vocabulary Term oauth2（すなわち "scheme": "oauth2"）によって識別される。

code flow では、authorization および token vocabulary terms の両方が 含まれなければならない（MUST）。 client flow では、token vocabulary term が含まれなければならない（MUST）。 client flow では、authorization vocabulary term を含めてはならない（MUST NOT）。 各 flow の必須要素は次の表に要約される:

link は、 「link context は relation type の resource を link target に持つ」 という形式の文として見ることができ、 任意の target attributes が その resource をさらに記述してもよい。

Link relations は、他の Things との関係 （例: Switch Thing が Lamp Thing を制御する）、特定の種類の Thing Models との関係 （例: Thing Description が特定の Thing Model のインスタンスである）、 またはさらなる documentation 情報との関係 （例: Thing の device manual）などを記述するために使用できる。 既存かつ確立された IANA の Link Relation 定義を再利用することが推奨される。

以下では、WoT Thing Description または Thing Model インスタンス内で使用することが推奨される best practice relation type table を導入する。

form は、「form context 上で operation type 操作を実行するには、 submission target に request method request を行う」という文として見ることができ、 任意の form fields が必要な request を さらに記述してもよい。Thing Descriptions では、 form context は周囲の Object であり、 Properties、Actions、Events、または meta-interactions のための Thing 自体などである。

contentCoding property の可能な値は、たとえば IANA HTTP content coding registry に見つけることができる。

form の可能な operation types のリストは固定されている。 このバージョンの仕様では、 [wot-architecture11] で記述される WoT interaction model を実装するために必要な well-known types のみを含む。 標準の将来バージョンではこのリストを拡張する可能性があるが、 operation types は 下表の値に制限されなければならない （MUST）。

WoT producer の Thing Description は、たとえば異なる protocol および/または content types 宣言を持つ複数の forms entries を持ってもよく、 それらを Consumer が サポートできる可能性がある。その場合、Consumer は自分にとって動作する 任意の form entry（例: protocol と content type がサポートされている）を 選択してよい。1 つの form が選択された場合、 Consumer は、可能な限り長く、 WoT producer との すべての新しい interaction に対してそれを使用し続けることが期待される。

primary response の expected response message を記述する communication metadata。

additional responses の expected response message を記述する communication metadata。

より複雑な例として、すべての Interaction Affordances が basic authentication を必要とするが、 1 つだけ authentication が不要な Thing があるとする。 status Property と toggle Action では、basic authentication が必要であり、 Thing level で定義される。 しかし overheating Event では authentication は不要であり、 したがって security configuration は form level で上書きされる。

{
    // ...
    "securityDefinitions": {
        "basic_sc": {"scheme": "basic"},
        "nosec_sc": {"scheme": "nosec"}
    },
    "security": "basic_sc",
    // ...
    "properties": {
        "status": {
            // ...
            "forms": [{
                "href": "https://mylamp.example.com/status"
            }]
        }
    },
    "actions": {
        "toggle": {
            // ...
            "forms": [{
                "href": "https://mylamp.example.com/toggle"
            }]
        }
    },
    "events": {
        "overheating": {
            // ...
            "forms": [{
                "href": "https://mylamp.example.com/oh",
                "security": "nosec_sc"
            }]
        }
    }
}

TDs は security schemes の組み合わせも指定できる。 以下は、proxy 上の digest authentication と、 Thing 上の bearer token authentication を組み合わせた TD snippet である。 digest scheme では、in の Default Value （すなわち header）は省略されているが、依然として適用される。 username/password や tokens などの対応する private security configuration は、正常に interaction するために Consumer 内で 構成する必要があることに注意。複数の security definitions を 有効化する場合、security member は array になる。

{
    // ...
    "securityDefinitions": {
        "proxy_sc": {
            "scheme": "digest",
            "proxy": "https://portal.example.com/"
        },
        "bearer_sc": {
            "scheme": "bearer",
            "in": "header",
            "format": "jwt",
            "alg": "ES256",
            "authorization": "https://servient.example.com:8443/"
        }
    },
    "security": ["proxy_sc", "bearer_sc"],
    // ...
}

ただし、 security element 内で security schemes を組み合わせるために 複数要素の array を使用することは現在 deprecated であり、 代わりに ComboSecurityScheme を使用すべきである（SHOULD）。 次の例は上記と完全に等価であり、これを示している:

{
    // ...
    "securityDefinitions": {
        "proxy_sc": {
            "scheme": "digest",
            "proxy": "https://portal.example.com/"
        },
        "bearer_sc": {
            "scheme": "bearer",
            "in": "header",
            "format": "jwt",
            "alg": "ES256",
            "authorization": "https://servient.example.com:8443/"
        },
        "combo_sc": {
            "scheme": "combo",
            "allOf": ["proxy_sc", "bearer_sc"]
        }
    },
    "security": "combo_sc",
    // ...
}

Security configurations は、同じ Interaction Affordance 内の異なる forms に対しても指定できる。 これは、HTTP と CoAP [RFC7252] など、異なる security mechanisms をサポートする複数の protocols を サポートする devices で必要となる場合がある。これは、代替の authentication mechanisms が許可されている場合にも有用である。 ここでは、HTTPS with basic authentication、digest authentication、bearer token authentication という 3 つの可能な方法で Property affordance を有効化する TD snippet を示す。 言い換えると、複数の forms 内で異なる security configurations を 使用することは、security mechanisms を "OR" 方式で組み合わせる方法を 提供する。対照的に、同じ security member に複数の security configurations を置くことは、それらを "AND" 方式で組み合わせる。 なぜならその場合、 Interaction Affordance の有効化を許可するために、それらすべてを満たす必要があるからである。 1 つの（default）configuration を Thing level で有効化することは 依然として必須であることに注意。

{
    // ...
    "securityDefinitions": {
        "basic_sc": { "scheme": "basic" },
        "digest_sc": { "scheme": "digest" },
        "bearer_sc": { "scheme": "bearer" }
    },
    "security": "basic_sc",
    // ...
    "properties": {
        "status": {
            // ...
            "forms": [{
                "href": "https://mylamp.example.com/status"
            }, {
                "href": "https://mylamp.example.com/status",
                "security": "digest_sc"
            }, {
                "href": "https://mylamp.example.com/status",
                "security": "bearer_sc"
            }]
        }
    },
    // ...
}

この場合の冗長性、たとえば form elements の詳細の繰り返しを 避けるために、代わりに oneOf を持つ ComboSecurityScheme を使用できる。

{
    // ...
    "securityDefinitions": {
        "basic_sc": { "scheme": "basic" },
        "digest_sc": { "scheme": "digest" },
        "bearer_sc": { "scheme": "bearer" },
        "combo_sc": {
            "scheme": "combo",
            "oneOf": [ "basic_sc", "digest_sc", "bearer_sc" ]
        }
    },
    "security": "combo_sc",
    // ...
    "properties": {
        "status": {
            // ...
            "forms": [{
                "href": "https://mylamp.example.com/status"
            }]
        }
    },
    // ...
}

別のより複雑な例として、OAuth 2.0 は scopes を使用する。 これらは tokens 内に現れることがある identifiers であり、その resource （または W3C WoT の場合は Interaction Affordance）へのアクセスを許可するために、 resource 内の対応する identifiers と一致しなければならない。 たとえば以下では、status Property は、 scope limited を含む bearer tokens を使用する Consumers によって read できるが、configure Action は special scope を含む token によってのみ invoke できる。 Scopes は roles と同一ではないが、多くの場合それらに関連付けられる。 たとえば、administrative role の者だけが "special" interactions を実行する認可を持つかもしれない。Tokens は複数の scope を 持つことができ、dedicated web services によって users に発行される。 この例では、administrator は limited と special の両方の scopes を持つ tokens を発行され得る一方で、 ordinary users には limited scope を持つ tokens が 提供され得る。

{
    // ...
    "securityDefinitions": {
        "oauth2_sc": {
            "scheme": "oauth2",
            "flow": "client",
            "token": "https://example.com/token",
            "scopes": ["limited", "special"]
        }
    },
    "security": "oauth2_sc",
    // ...
    "properties": {
        "status": {
            // ...
            "forms": [{
                "href": "https://scopes.example.com/status",
                "scopes": ["limited"]
            }]
        }
    },
    "actions": {
        "configure": {
            // ...
            "forms": [{
                "href": "https://scopes.example.com/configure",
                "scopes": ["special"]
            }]
        }
    },
    // ...
}

Thing は onboarding process を必要とすることがあり、その結果、 Consumer が Thing と interaction するために API key を必要とする。 この API key は、API key scheme が指定するように、異なる方法で Thing への request に含めることができる。以下は、 HTTPS request を送信するときに Consumer によって URI 内の API key が 置き換えられるべき URI template として、これを使用する方法の例である。

{
    // ...
    "securityDefinitions": {
        "apikey_key": {
            "scheme": "apikey",
            "in": "uri",
            "name": "adminKey"
        }
    },
    "security": "apikey_key",
    "properties": {
        "status": {
            // ...
            "forms": [{
                "href": "https://example.com/{adminKey}/status",
                // ...
            }]
        }
    },
    // ...
}

上に示した URI templates の例の使用に加えて、 ComboSecurityScheme の使用の別の例を挙げると、cloud service provider によって提供される client ID と "secret" key の両方を URL に埋め込まなければならない security scheme があるとする。 技術的には、実際に secret であり out-of-band で扱わなければならないのは key のみであり、secret ではない client ID は TD に埋め込むことができる。 しかし、client ID を容易に rotate できない場合、privacy を高めるために それを TD に埋め込むことを避けたい場合がある。この場合、 2 つの APIKeySecurityScheme インスタンスを組み合わせることができ、どちらも in location specifier に uri 値を使用して、 2 つの URI variables を宣言する。これらは、security scheme が有効な Form 内の href で使用できる （実際には、使用しなければならない）。例は次のとおり:

{
    // ...
    "securityDefinitions": {
        "apikey_key": {
            "scheme": "apikey",
            "in": "uri",
            "name": "secKey"
        },
        "apikey_id": {
            "scheme": "apikey",
            "in": "uri",
            "name": "secClientID"
        },
        "apikey_combo": {
            "scheme": "combo",
            "allOf": ["apikey_key","apikey_id"]
        }
    },
    "security": "apikey_combo",
    // ...
    "properties": {
        "status": {
            // ...
            "forms": [{
                "href": "https://example.com/{secClientID}/status/{secKey}",
                // ...
            }]
        }
    },
    // ...
}

この例には示されていないが、uriVariables を使用して 追加の URI template variables を宣言し、それらを同じ URI template に 含めることは合法である。ただし、その names は security schemes で宣言されたものと 衝突してはならない。上の例のように、security schemes で宣言される URI variables に特定の prefix を使用すると、name conflicts を避けやすくなる。

Body 内の API Key: 一部のシステムでは、security parameters が payload とともに含まれる場合もある。たとえば、あるシステムがすべての payload に対して、auth という名前の member を含む JSON object であることを要求し、その value が access key を含む key という member を持つ object であるとする。 ただし、interaction によっては、JSON object の他の elements が異なることがある。 この状況は、body security information location を使用して扱うことができる。 この location では、name parameter は実際には、それが結び付けられた 各 interaction の DataSchema のルートを基準に評価される JSON pointer であり、他の点で異なる payloads とともに使用できることに注意。 例として、brightness と color を設定する property と、オンおよびオフにする 2 つの別々の actions を持つ light がある。これらの actions の JSON payloads は異なるが、/auth/key element は同じ相対位置に 現れるため、単一の JSON pointer を使用できる。注記: security key が 一貫しない異なる locations に現れる場合は、複数の security scheme definitions を 使用する必要がある。

{
    // ...
    "securityDefinitions": {
        "apikey_body": {
            "scheme": "apikey",
            "in": "body",
            "name": "/auth/key"
        }
    },
    "security": "apikey_body",
    // ...
    "properties": {
        "color": {
            // ...
            "type": "object",
            "properties": {
                "brightness": {
                    "type": "number",
                    // ...
                },
                "rgb": {
                    "type": "array",
                    // ...
                },
                "auth": {
                    "type": "object",
                    "properties": {
                        "key": {
                           "type": "string"
                        }
                    },
                    "required": ["key"]
                }
            },
            "required": ["brightness", "rgb", "auth"],
            "forms": [{
                "href": "https://example.com/color",
                // ...
            }]
        }
    },
    "action": {
        "on": {
            // ...
            "input": {
                "auth": {
                    "type": "object",
                    "properties": {
                        "key": {
                           "type": "string"
                        }
                    },
                    "required": ["key"]
                }
            },
            "required": ["auth"],
            "forms": [{
                "href": "https://example.com/on",
                // ...
            }]
        },
        "off": {
            // ...
            "input": {
                "auth": {
                    "type": "object",
                    "properties": {
                        "key": {
                           "type": "string"
                        }
                    },
                    "required": ["key"]
                }
            },
            "required": ["auth"],
            "forms": [{
                "href": "https://example.com/off",
                // ...
            }]
        }
    },
    // ...
}

{
    // ...
    "securityDefinitions": {
        "apikey_body": {
            "scheme": "apikey",
            "in": "body",
            "name": "/auth/key"
        }
    },
    "security": "apikey_body",
    // ...
    "properties": {
        "color": {
            // ...
            "type": "object",
            "properties": {
                "brightness": {
                    "type": "number",
                    // ...
                },
                "rgb": {
                    "type": "array",
                    // ...
                }
            },
            "required": ["brightness", "rgb"],
            "forms": [{
                "href": "https://example.com/color",
                // ...
            }]
        }
    },
    "action": {
        "on": {
            // ...
            "required": ["auth"],
            "forms": [{
                "href": "https://example.com/on",
                // ...
            }]
        },
        "off": {
            // ...
            "forms": [{
                "href": "https://example.com/off",
                // ...
            }]
        }
    },
    // ...
}

href は、 http://example.org/weather/?lat=35&lon=139 の lat や lon のような動的変数を含む URI を 持つこともある。 その場合、URI は [RFC6570] で定義される template として 定義できる: http://example.org/weather/{?lat,long}。

そのような場合、URI Template variables は、JSON-object ベースの uriVariables member に、 Thing level または Interaction Affordance level のいずれかで、関連する（一意の） variable names を JSON names として集められなければならない （MUST）。

Form のインスタンス内で uriVariables に割り当てられる map 内の各 value の シリアル化は、Class DataSchema に依拠しなければならず （MUST）、そのシリアル化は 6.3.10 Data Schemas で定義される。

query parameters 用の URI Template と Interaction Affordance level の uriVariables を使用する TD snippet を以下に示す:

{
    "@context": ["https://www.w3.org/ns/wot-next/td", {
        "htv": "http://www.w3.org/2011/http#"
    }],
    // ...
    "properties": {
        "weather": {
            // ...
            "uriVariables": {
                "lat": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 90,
                    "description": "Latitude for the desired location in the world" },
                "long": {
                    "type": "number",
                    "minimum": -180,
                    "maximum": 180,
                    "description": "Longitude for the desired location in the world" }
            },
            "forms": [{
              "href": "http://example.org/weather/{?lat,long}",
              "htv:methodName": "GET"
            }]
        },
        // ...
    },
    // ...
}

あるいは、[RFC6570] で定義されるように、 uriVariables は href 構造を置き換えるために使用できる。 以下に、有効な Colombia の Bogota の forecast を取得する request が http://example.org/weather/bogota への HTTP GET request となる example TD を示す:

{
    "@context": ["https://www.w3.org/ns/wot-next/td", {
        "htv": "http://www.w3.org/2011/http#"
    }],
    // ...
    "properties": {
        "weather": {
            // ...
            "uriVariables": {
                "city": {
                    "type": "string",
                    "description": "City name to find the weather information for"
                }
            },
            "forms": [{
                "href": "http://example.org/weather/{city}",
                "htv:methodName": "GET"
            }]
        },
        // ...
    },
    // ...
}

以下の 2 つの例は、同じ uriVariables 機能を使用しながら組み合わせることもできる。 http://example.org/weather/bogota/?unit=Celsius への HTTP GET request は、次のように記述できる:

{
    "@context": ["https://www.w3.org/ns/wot-next/td", {
        "htv": "http://www.w3.org/2011/http#"
    }],
    // ...
    "properties": {
        "weather": {
            // ...
            "uriVariables": {
                "city": {
                    "type": "string",
                    "description": "City name to find the weather information for"
                },
                "unit": {
                    "type": "string",
                    "enum": ["fahrenheit_value","celsius_value"],
                    "description": "Desired unit for the temperature value"
                }
            },
            "forms": [{
                "href": "http://example.org/weather/{city}/{?unit}",
                "htv:methodName": "GET"
            }]
        },
        // ...
    },
    // ...
}

uriVariables は主に properties および events のためのものである。既存システムを後付けする場合、 actions に uriVariables を使用する必要がある場合がある。 一般に、新しい WoT-based system を設計する場合は、 uriVariables の使用を可能な限り避けることが推奨される。

contentType member は、media type [RFC2046] を割り当てるために使用され、; 文字で区切られた attribute-value pairs として media type parameters を含む。 例:

{
    // ...
    "contentType": "text/plain; charset=utf-8",
    // ...
}

一部のユースケースでは、Interaction Affordance の form metadata は request を記述するだけでなく、 expected response の metadata も提供する。たとえば、Action takePhoto は、camera の parameter settings （aperture priority、timer など）を request payload に JSON を使用して submit するための input schema を定義する （すなわち "contentType": "application/json"）。この action の output は 撮影された photo であり、たとえば JPEG format で利用可能である。 そのような場合、response member は response payload の representation format を示すために使用される （例: "contentType": "image/jpeg"）。ここでは output schema は 必要ない。content type が representation format を完全に指定するためである。

上記で説明した takePhoto Action に基づき、 response member を持つ form snippet を以下に示す:

{
    // ...
    "actions": {
        "takePhoto": {
            // ...
            "forms": [{
                "op": "invokeaction",
                "href": "http://camera.example.com/api/snapshot",
                "contentType": "application/json",
                "response": {
                    "contentType": "image/jpeg"
                }
            }]
        }
    },
    // ...
}

responses が payload を含むことを期待されず、したがって contentType も持たない場合、 空の response object を使用してこの情報を 伝えることができる。

{
    // ...
    "actions": {
        "brewCoffee": {
            "description": "Invoking this action does not return a payload.",
            "input": {
              "type": "object",
              "properties": {
                "coffeeType": {
                  "enum": [
                    "espresso",
                    "americano",
                    "cappuccino",
                    "latte"
                  ]
                },
                "useOatMilk": {
                  "type": "boolean",
                  "default": false
                }
              },
              "required": [
                "coffeeType"
              ]
            },
            "forms": [{
                "op": "invokeaction",
                "href": "http://coffee-maker.example.com/brew-coffee",
                "contentType": "application/json",
                "response": {}
            }]
        }
    },
    // ...
}

場合によっては、Interaction Affordance の一部として Thing から受信される message が、 異なる理由によって異なることがある。そのような理由には、 error cases または有効な response に対する alternative responses があり得る。 これらの場合、additionalResponses terms を使用して この振る舞いを記述できる。

たとえば、car engine を起動する Action Affordance は、 悪天候の場合や engine が maintenance を必要とする場合には 動作しないことがある。そのような場合、Thing は通常使用されない payloads で応答する必要がある。

Action Affordance 内に additionalResponses member を持つ TD snippet を以下に示す。その最初の element は、 output で記述されているものとは異なる payload で error response を送信できる、上記のケースを示している。 value false を持つ success は、 この payload が error case を指すという事実を示し、 schema は schemaDefinitions で使用される payload description へのリンクを可能にする。 additionalResponses 内の 2 番目の element も error response を記述するが、この場合 response は payload を持たない。

{
    // ...
    "schemaDefinitions": {
      "actionErrorPayload": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "enum": ["cold","hot","maintenance"]
          },
          "timeStamp": {
            "description": "UNIX time in numbers indicating when the error happened",
            "type": "number"
          }
        }
      }
    },
    // ...
    "actions": {
        "startEngine": {
            "output": {
              "type": "string"
            },
            "forms": [{
                "op": "invokeaction",
                "href": "http://mycar.example.com/api/engine",
                "contentType": "application/json",
                "additionalResponses": [
                  {
                    "success": false,
                    "contentType": "application/json",
                    "schema": "actionErrorPayload"
                  },
                  {
                    "success": false
                  },
                ]
            }]
        }
    },
    // ...
}

additionalResponses term は、 non-error cases でも使用できる。その場合、 success は true に設定され、 payload を記述するために別の schema を使用できる。

場合によっては、binary data が text-based values に埋め込まれることがある。たとえば、JSON string-based value が base64 encoded image を埋め込む場合である。 contentMediaType および contentEncoding terms は、そのような name-value pairs の context と encoding format を明確にするために使用できる。 contentMediaType および contentEncoding の sample usage を以下に示す:

{
    // ...
    "properties": {
        "image": {
                "description": "Provides latest image",
                "type": "string",
                "contentMediaType": "image/png",
                "contentEncoding": "base64",
                "forms": [{
                            "op": "readproperty",
                            "href": "coaps://mylamp.example.com/lastPicture",
                            "cov:methodName": "GET",
                            "contentType": "application/json"
                    }]
        }
    },
    // ...
}

forms が top level に存在する場合、 Thing によって提供される meta interactions を 記述するために使用できる。たとえば、operation types readallproperties および writeallproperties は、 Consumers が一度にすべての properties を read、write、または observe できるようにする、 Thing との meta interactions のためのものである。 下の例では、forms member が TD root object に含まれ、 Consumer は submission target https://mylamp.example.com/properties を使用して、 単一の protocol transaction で Thing のすべての Properties （すなわち on、 brightness、および timer）を read または write できる。

{
    // ...
    "properties": {
        "on": {
            "type": "boolean",
            "forms": [...]
        },
        "brightness": {
            "type": "number",
            "forms": [...]
        },
        "timer": {
            "type": "integer",
            "forms": [...]
        }
    },
    // ...
    "forms": [{
        "op": "readallproperties",
        "href": "https://mylamp.example.com/properties",
        "contentType": "application/json",
        "htv:methodName": "GET"
    },
    {
        "op": "writeallproperties",
        "href": "https://mylamp.example.com/properties",
        "contentType": "application/json",
        "htv:methodName": "PUT"
    }]
}

Thing-level uriVariables は、operation に さらなる variables を供給するため、または readmultipleproperties operation のための Property Affordance names のリストを指定するために使用できる。 下の例では、properties の unit はそのような variable を介して設定でき、 目的の properties のリストも設定できる:

{
    // ...
    "properties": {
        "temperature": {
            "type": "number",
            "forms": [...]
        },
        "brightness": {
            "type": "number",
            "forms": [...]
        },
        "humidity": {
            "type": "integer",
            "forms": [...]
        }
    },
    "uriVariables": {
        "propertyNames": {
            "type": "string",
            "description": "Comma separated list of property names to select."
        },
        "unitSystem": {
            "type": "string",
            "enum": ["metric","imperial","uscustomary"],
            "description": "System of Measurement that will be used for the values"
        }
    },
    "forms": [{
        "op": "readallproperties",
        "href": "https://mything.example.com/properties{?unitSystem}",
        "contentType": "application/json",
        "htv:methodName": "GET"
    },
    {
        "op": "readmultipleproperties",
        "href": "https://mylamp.example.com/properties{?propertyNames,unitSystem}",
        "contentType": "application/json",
        "htv:methodName": "GET"
    }]
}

readmultipleproperties operation では、 URI https://mylamp.example.com/properties?propertyNames=humidity,temperature&unitSystem=metric への example HTTP GET request は、 metric System of Measurement を用いて、 humidity および temperature Property Affordances の値を返す。

operation type writeallproperties の場合、 Consumer は、すべての writable（non readOnly）properties と （新しい）割り当て値（例: payload 内）を提供することが期待される。 同様に、writemultipleproperties operation type では、Consumer が writable （non readOnly）properties を提供することが期待される。 Thing 側では、 Thing は、 readmultipleproperties および readallproperties operation types の場合に readable（non writeOnly）properties を返すことが期待される。