Web of Things（WoT）物 描述 2.0

物理实体或虚拟实体的一种抽象，其 元数据和接口由 WoT 物 描述来描述；其中虚拟实体是 一个或多个物的组合。

对于 @context，为 物描述 实例定义了以下规则：

• @context 名称-值对 MUST 包含 anyURI https://www.w3.org/2022/wot/td/v1.1， 以便将该文档标识为 TD 1.1，从而允许 消费者使用新 引入的术语。
• 当可能存在 TD 1.0 消费者时，anyURI https://www.w3.org/2019/wot/td/v1 MUST 是第一项，而 https://www.w3.org/2022/wot/td/v1.1 MUST 是第二 项。
• TD 1.1 消费者 MUST 接受满足 W3C WoT Thing Description 1.0 [wot-thing-description10] 规范的 TD。
• 当 @context 是一个数组时，anyURI https://www.w3.org/2022/wot/td/v1.1 MAY 后面可以 以任意顺序跟随类型为 anyURI 或类型为映射的元素，同时 RECOMMENDED 只包含 一个映射， 其中包含 @context 数组中的所有名称-值对。
• 映射包含在 @context 数组中时，MAY 包含名称-值 对，其中 值是类型为 anyURI 的命名空间标识符， 名称是术语或表示该 命名空间的前缀。
• 包含在 @context 数组中的一个映射 SHOULD 包含一个名称-值对， 该名称-值对定义物描述的默认语言， 其中名称是术语 @language， 值是 [BCP47] 所定义的格式良好的语言标签 （例如 en、de-AT、 gsw-CH、zh-Hans、 zh-Hant-HK、 sl-nedis）。

为了确定物描述 和物 模型实例中所有人类可读文本的基本方向， 本规范建议在没有内置机制可用于关联基本方向 元数据时，遵循 [STRING-META] 关于 字符串特定方向信息的指南。

TD 处理器在处理双向文本时应注意某些特殊情况。 TD 处理器 SHOULD 在向用户呈现字符串时注意使用 bidi 隔离， 尤其是在嵌入周围文本时（例如 Web 用户 界面）。混合方向文本可以出现在任何 语言中，即使该语言已被正确 标识。

TD 生产者 SHOULD 尝试以一种能被 朴素用户代理成功显示的方式提供混合方向 字符串。例如，如果一个 RTL 字符串 以 LTR 片段开头（例如数字或拉丁文字中的品牌或 商品名称），则在字符串开头包含一个 RLM 字符， 或者用 bidi 控制符包裹相反方向的片段， 可以帮助正确显示。

Strings on the Web: Language and Direction Metadata [string-meta] 提供了一些指导，并说明了使用双向文本时的 若干陷阱。

除了在 properties、 actions 和 events 映射中 显式提供的交互 可供性之外，一个物还可以 提供元交互，这些元交互由其可选 forms 数组中的 Form 实例表示。当一个物实例的 forms 数组包含 Form 实例时，它 MUST 包含 op 成员， 且赋给名称 op 的字符串值， 无论是直接给出还是在数组中给出，MUST 是以下 操作类型之一：readallproperties、 writeallproperties、 readmultipleproperties、 writemultipleproperties、 observeallproperties、 unobserveallproperties、 queryallactions、 subscribeallevents 或 unsubscribeallevents。（参见示例， 了解在物实例中使用 form 的情况。）

每个属性元交互的数据模式通过组合每个 PropertyAffordance 实例的数据模式来构造， 并放入单个 ObjectSchema 实例中；其中 ObjectSchema 实例的 properties 映射包含每个 PropertyAffordances 的数据模式，这些 数据模式由对应 PropertyAffordances 实例的名称标识。

如果未另行指定（例如通过 TD 上下文 扩展）， readmultipleproperties 操作的请求数据是一个 数组，其中包含 预期的 PropertyAffordances 实例 名称，并会被序列化为 Form 实例指定的内容类型。

物的元数据，向 消费者展示可能的选择，从而 提示消费者如何与 物交互。潜在可供性有许多类型， 但 W3C WoT 定义了三类交互可供性： 属性、动作和事件。

InteractionAffordance 类具有以下 子类：

• PropertyAffordance
• ActionAffordance
• EventAffordance

一种暴露物状态的交互可供性。 该状态随后可以被检索（读取）和/或 更新（写入）。物也可以选择通过在发生 变化后推送新状态，使属性可被观察。

PropertyAffordance 是 InteractionAffordance 类和 DataSchema 类的子类。 当 Form 实例位于 PropertyAffordance 实例内部时，赋给 op 的值 MUST 是 readproperty、writeproperty、 observeproperty、 unobserveproperty 之一，或是包含这些术语组合的 数组。

一种交互可供性，允许调用物的 某个函数，该函数会操纵状态（例如打开或关闭灯） 或触发物上的一个过程（例如随时间调暗灯）。

ActionAffordance 是 InteractionAffordance 类的子类。 当 Form 实例位于 ActionAffordance 实例内部时，赋给 op 的值 MUST 是 invokeaction、 queryaction、cancelaction 之一，或是 包含这些术语组合的 数组。

一种交互可供性，用于描述一个事件 源，它会向 消费者异步推送事件数据（例如过热 警报）。

EventAffordance 是 InteractionAffordance 类的子类。 当 Form 实例位于 EventAffordance 实例内部时，赋给 op 的值 MUST 是 subscribeevent、 unsubscribeevent，或在一个 数组中同时包含这两个术语。

EventAffordances 与可观察的 PropertyAffordances 类似，因为物自身会 将状态变化告知感兴趣的消费者。 但是，EventAffordances 的一个主要区别是， 相关资源的每一次变化并不一定需要 触发发出事件消息，例如数值的临界 阈值。此外， EventAffordances 允许通过定义 subscription、dataResponse 和 cancellation DataSchema 定义来实现更复杂的订阅和 取消订阅机制。不过，并非所有 协议都可能支持这些更高级的机制， 因此在某些场景中，事件可能与可观察的 PropertyAffordances 非常相似。在这些 情况下，应根据底层资源的语义来 在属性和事件之间选择用哪一个来建模 可供性；例如，如果该可供性的状态也预期 由消费者读取或写入，那么属性很可能是 合适的选择。

物的元数据，用于提供关于 TD 文档的版本信息。 如有需要，可通过 TD 上下文扩展机制扩展附加版本信息，例如固件和硬件版本 （TD 命名空间之外的术语定义）。

建议 VersionInfo 类中的 instances 和 model 的值遵循语义化 版本模式，其中由点分隔的三个数字序列 分别表示主版本、次版本和补丁版本。 详情见 [SEMVER]。

一个映射， 提供一组以 [BCP47] 中描述的 语言标签标识的不同语言的人类可读文本。请参阅 6.3.2 人类可读 元数据，了解该容器在 物描述实例中的示例用法。

MultiLanguage 映射的每个名称 MUST 是 [BCP47] 中定义的语言标签。 MultiLanguage 映射的每个值 MUST 为 string 类型。

描述所用数据格式的元数据。它可用于 验证。

DataSchema 类具有以下 子类：

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

format 字符串值来自一组 固定的值，以及 [JSON-SCHEMA] 中定义的相应格式规则 （尤其是第 7.3 节“已定义格式”）。服务体 MAY 使用 format 值 相应执行附加验证。 当赋给 format 的值不在已知值集合中时， 这样的验证 SHOULD 成功。

描述类型为数组的数据的元数据。 此子类由 DataSchema 实例中赋给 type 的值 array 表示。

描述类型为 boolean 的数据的元数据。 此子类由 DataSchema 实例中赋给 type 的值 boolean 表示。

描述类型为 number 的数据的元数据。 此子类由 DataSchema 实例中赋给 type 的值 number 表示。

描述类型为 integer 的数据的元数据。 此子类由 DataSchema 实例中赋给 type 的值 integer 表示。

描述类型为对象的数据的元数据。 此子类由 DataSchema 实例中赋给 type 的值 object 表示。

描述类型为 string 的数据的元数据。 此子类由 DataSchema 实例中赋给 type 的值 string 表示。

描述类型为 null 的数据的元数据。 该子类由 DataSchema 实例中赋给 type 的值 null 表示。该子类只描述一个可接受 值，即 null。需要注意的是， null 并不表示没有 值。它类似于 JavaScript 中的 null、 Python 中的 None、 Java 中的 null 和 Ruby 编程语言中的 nil。它可作为 oneOf 声明的一部分使用，在其中用于 表示该数据也可以是 null。

描述安全机制配置的元数据。 赋给名称 scheme 的值 MUST 定义在 物描述中包含的 词汇表内， 可以是在 § 5. TD 信息模型中定义的标准 词汇表， 也可以是在TD 上下文 扩展中。

对于所有安全方案，任何 密钥、密码或其他直接提供访问能力的敏感信息 MUST NOT 存储在 TD 中，而应通过其他机制 在带外共享和存储。TD 的目的 是在且仅在消费者已经获得授权时， 描述如何访问某个物，而并非用于 授予该授权。

TD 中使用的每个安全方案对象定义了一组 在授予访问前必须满足的要求。 当一个安全方案的所有要求都被满足时，我们称其 已满足。在某些情况下，必须先满足 多个安全方案的要求，才能授予访问。

安全方案通常可能需要附加的 认证参数，例如密码或密钥。 这些信息的位置由与名称 in 关联的值指示， 通常还会结合与 name 关联的值。与 in 关联的值可以取以下值之一：

header：

参数将放在协议提供的 header 中， header 的名称由 name 的值提供。

query：

参数将作为查询参数附加到 URI， 查询参数的名称由 name 提供。

body：

参数将放在请求负载的 body 中， 使用的数据模式元素由 name 提供。 当在 body 安全信息位置的上下文中使用时， name 的值 MUST 采用 JSON 指针 [RFC6901] 的形式，并相对于其所用于的每个交互的输入 DataSchema 的根。由于该值不是片段 标识符，也不是相对于 TD 的根，而是相对于 安全方案所绑定的任何数据模式，因此该值不应以 # 开头；它是一个“纯”JSON 指针。 由于该值不是片段标识符，也不需要对特殊字符 进行 URL 编码。目标元素可能已经存在于 所引用对象或数组模式中的指定位置，也可能不存在 （因此该机制不适用于简单类型）。如果不存在， 将插入该元素。这避免了在每个交互的数据 模式中重复定义。当 body 定位器中指示的 JSON 指针所指示的数据模式元素 在所指示的模式中尚不存在时，MUST 能够 在指针所指示的位置插入该 元素。 body 定位器中使用的 JSON 指针 MAY 使用 "-" 字符来指示不存在的数组元素，当需要 在现有数组最后一个元素之后插入元素时。 body 安全信息位置所引用（或创建）的元素 MUST 是必需的，并且类型为 "string"。如果未给出 name，则假定整个 body 都将用作安全 参数。

cookie：

参数存储在由 name 的值标识的 cookie 中。

uri：

参数嵌入在 URI 本身中， 该 URI 在相关交互中使用由 name 的值定义的 URI 模板变量进行编码。这比 query 机制更通用，但也更复杂。 仅当 query 不适用时， uri 值 SHOULD 被 指定为安全方案中名称 in 的值。 在使用 uri 作为 in 值的安全方案的交互中提供的 URI MUST 是包含已定义变量的 URI 模板。

auto：

位置作为协议的一部分确定， 或通过协商确定。如果 SecurityScheme 的 in 字段设置为 auto 值，则 name 字段 SHOULD NOT 被设置。在这种情况下， SecurityScheme 的应用受给定协议的相应规范约束 （例如在使用 HTTP 的 BasicSecurityScheme 时为 [RFC8288]）。

如果某个安全方案需要多个参数， 请为每个参数重复安全方案定义，并使用 combo 安全方案和 allOf 将其组合。 在某些情况下，参数实际上可能并非秘密，但用户可能 希望将其排除在 TD 之外以帮助保护隐私。 一个例子是，某些安全机制同时需要 客户端标识符和密钥。理论上，客户端 标识符是公开的；然而它可能难以更新并 带来跟踪风险。在这种情况下，可将其作为 附加安全参数提供，使其不出现在 TD 中。

SecurityScheme 中声明的 URI 变量名称 MUST 与 TD 中声明的所有其他 URI 变量不同。

SecurityScheme 类具有以下 子类：

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

一种安全配置，对应于由 词汇表术语 nosec 标识（即 "scheme": "nosec"），表示访问资源不需要认证或 其他机制。

一种由术语 auto 标识的自动认证安全配置 （即 "scheme": "auto"）。该方案表示 安全参数将在运行时由底层协议协商， 并受该协议相应规范的约束（例如在使用 HTTP 时 Basic Authentication 的 [RFC8288]）。

由词汇表术语 combo 标识的其他安全方案的组合 （即 "scheme": "combo"）。该方案的元素定义了 如何组合 securityDefinitions 中定义的其他具名方案（包括其他 ComboSecurityScheme 定义），以创建新的方案 定义。必须且只能包含 oneOf 或 allOf 词汇表术语之一。只有可以一起使用的安全方案定义 才能用 allOf 组合。例如，一般不可能 使用 allOf 将不同的 OAuth 2.0 流组合在一起， 除非一个适用于代理而另一个适用于端点。 注意，当多个具名安全方案定义列在 security 字段中时，其语义与 allOf 组合相同（并具有相同的 可允许组合限制）。oneOf 组合等价于 在其他方面相同的 forms 上使用不同的安全方案。 从这个意义上说，oneOf 方案并非必要特性， 但它可以避免此类情况下的冗余。

Basic Authentication [RFC7617] 安全配置，由词汇表术语 basic 标识（即 "scheme": "basic"），使用未加密的用户名和 密码。

Digest Access Authentication [RFC7616] 安全配置，由词汇表术语 digest 标识（即 "scheme": "digest"）。该方案类似于 basic authentication，但增加了避免 中间人攻击的特性。

API key 认证安全配置， 由词汇表术语 apikey 标识（即 "scheme": "apikey"）。当访问令牌是不透明的时应使用该方案， 例如云服务提供商提供了某种未知或专有格式的 密钥。在这种情况下，该密钥可能并未使用 标准令牌格式。该方案表示服务提供商提供的密钥 需要使用 "in" 字段所指示的机制， 作为服务请求的一部分提供。

Bearer Token [RFC6750] 安全配置，由词汇表术语 bearer 标识（即 "scheme": "bearer"），用于 bearer token 独立于 OAuth2 使用的情况。如果指定了 oauth2 方案，通常没有必要 同时指定该方案，因为它已被隐含。对于 format，值 jwt 表示 符合 [RFC7519]， jws 表示符合 [RFC7797]， cwt 表示符合 [RFC8392]，而 jwe 表示符合 [RFC7516]；alg 的值 按与这些标准一致的方式解释。 其他 bearer token 的格式和 算法 MAY 在词汇表扩展中指定。

预共享密钥认证安全配置， 由词汇表术语 psk 标识（即 "scheme": "psk"）。 这用于表明使用了预共享密钥标准， 例如 TLS-PSK [RFC4279]， 并且用于密钥的密码套件将在协议协商期间 建立。

用于符合 [RFC6749] 和 [RFC8252] 的系统的 OAuth 2.0 认证安全配置， 由词汇表术语 oauth2 标识（即 "scheme": "oauth2"）。

对于 code 流，authorization 和 token 词汇表术语 都 MUST 被包含。 对于 client 流，token 词汇表术语 MUST 被包含。 对于 client 流，authorization 词汇表术语 MUST NOT 被包含。 每个 流的强制元素汇总在下表中：

链接可被视为如下形式的陈述： “链接上下文 在 链接目标 处有一个 关系 类型资源”， 其中可选的 目标属性 可以 进一步描述该资源。

链接关系可用于描述各种关系， 例如与其他物的关系（如 Switch Thing 控制 Lamp Thing）、与特定类型物模型的关系（如物 描述是特定物模型的实例），或 与进一步文档信息的关系（如某个物的设备 手册）。建议复用已有且成熟的 IANA 链接 关系定义。

下面介绍一个最佳实践关系类型表， 建议在 WoT 物描述 或物 模型实例中使用。

form 可被视为如下陈述：“要在 form 上下文上执行一个 操作类型操作，请向 提交目标发出一个 请求方法 请求”，其中可选的 form 字段 可以进一步描述所需的请求。在物描述中， form 上下文是周围的对象， 例如属性、动作和事件，或物自身（用于元交互）。

contentCoding 属性的可能值可以在例如 IANA HTTP 内容编码注册表中找到。

form 的可能操作类型列表是固定的。 截至本规范版本，该列表仅包含实现 [wot-architecture11] 中描述的 WoT 交互模型所必需的已知类型。 标准的未来版本可以扩展该列表，但 操作类型 MUST 限制为下表中的值。

WoT 生产者的 物描述 可能具有多个 forms 条目，例如具有不同协议和/或 内容类型声明，而消费者可能支持其中一些。 在这种情况下，消费者可以选择任何对其可用的 form 条目（例如协议和内容类型受支持）。一旦选择一个 form，就预期消费者会尽可能持续 将其用于与 WoT 生产者的每次新交互。

描述主响应的预期 响应消息的通信元数据。

描述附加响应的预期 响应消息的通信元数据。

为了给出一个更复杂的示例，假设我们有一个 物，其中除一个之外的所有 交互 可供性都需要 basic 认证，而该例外项不需要认证。 对于 status 属性和 toggle 动作，要求 basic 认证，并在 物层级定义。对于 overheating 事件，则不需要 认证，因此安全配置在 form 层级被覆盖。

{
    // ...
    "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"
            }]
        }
    }
}

TD 也可以指定安全方案的组合。 下面是一个 TD 片段，展示了在代理上使用 digest 认证， 同时在物上结合 bearer token 认证。 在 digest 方案中，in 的默认值 （即 header）被省略，但仍然适用。 注意，相应的私有安全配置，例如用户名/密码 和 token，需要在消费者中配置， 以便成功交互。当激活多个安全 定义时，security 成员会变成一个 数组。

{
    // ...
    "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 元素中使用包含多个元素的 数组来组合安全方案； 应改为使用 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",
    // ...
}

也可以为同一个交互 可供性内的不同 forms 指定安全配置。 对于支持多个协议的设备，例如 HTTP 和 CoAP [RFC7252]， 这些协议支持不同安全机制时，这可能是必需的。 当允许替代认证机制时，这也很有用。下面的 TD 片段演示了激活一个属性可供性的三种 可能方式：通过带 basic 认证的 HTTPS、通过 digest 认证、以及通过 bearer token 认证。 换言之，在多个 forms 中使用不同安全配置， 提供了一种以“OR”方式组合安全 机制的方法。相反，将多个安全配置放入同一个 security 成员中会以“AND”方式组合它们， 因为在这种情况下必须全部满足这些配置，才能允许激活该 交互 可供性。注意，在物层级激活一个 （默认）配置仍然是强制的。

{
    // ...
    "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 元素的细节，可以改用带有 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 中，并且必须与资源中的相应标识符匹配， 才允许访问该资源（或在 W3C WoT 的情况下访问交互 可供性）。例如， 在下面示例中，status 属性可以由 消费者使用包含 scope limited 的 bearer tokens 读取，但 configure 动作只能使用包含 special scope 的 token 调用。Scopes 与角色并不相同，但通常与角色相关联； 例如，可能只有拥有管理员角色的人才被授权执行 “special”交互。Tokens 可以拥有多个 scope， 并由专门的 Web 服务签发给用户。在这个 示例中，可以向管理员签发同时带有 limited 和 special scopes 的 tokens，而普通用户可以获得带有 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"]
            }]
        }
    },
    // ...
}

一个物可以要求执行 onboarding 过程， 其结果是消费者需要 API key 才能与该 物交互。该 API key 可以按照 API key 方案的指定， 以不同方式包含在发往该 物的请求中。下面是一个示例，展示如何将其用作 URI 模板，其中 API key 应在消费者发送 HTTPS 请求时由消费者在 URI 中替换。

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

为了在上面所示 URI 模板示例的用法之外， 再举一个使用 ComboSecurityScheme 的示例，假设存在一个安全方案，其中云服务 提供商提供的客户端 ID 和“secret”key 都必须 嵌入到 URL 中。从技术上说，只有 key 真正是秘密的，并且必须带外处理，而不是秘密的客户端 ID 可以嵌入到 TD 中。然而，如果客户端 ID 不能轻易轮换，我们可能希望避免将其嵌入到 TD 中，以增强隐私。在这种情况下，我们可以 组合两个 APIKeySecurityScheme 实例， 二者都将 uri 值用于 in 位置说明符，以声明两个 URI 变量。然后这些变量可以（事实上，必须）在安全方案 处于激活状态的 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 模板变量， 并将它们包含在同一个 URI 模板中，是合法的；不过这些名称不能与 安全方案中声明的名称冲突。像上例那样， 为安全方案中声明的 URI 变量使用特定 前缀，可以更容易地避免名称 冲突。

Body 中的 API Key：在某些系统中，安全参数也可能 随负载一起包含。例如，假设一个系统要求每个 负载都是一个 JSON 对象，其中包含一个名为 auth 的成员，其值是一个对象，该对象包含一个名为 key 的成员，其中包含访问 key。可是，根据 交互不同，JSON 对象中的其他元素可能会变化。 这种情况可以通过使用 body 安全信息位置来处理。 注意，对于这个位置，name 参数实际上是一个 JSON 指针，它相对于其所绑定的每个交互的 DataSchema 根进行求值，这使其可以用于 其他方面会发生变化的负载。作为示例，下面是一盏灯， 它有一个用于设置亮度和颜色的属性，以及两个单独的 动作来打开和关闭它。虽然这些动作的 JSON 负载不同，但 /auth/key 元素出现在相同的 相对位置，因此可以使用单个 JSON 指针。 注意：如果安全 key 出现在不同且不一致的位置， 就有必要使用多个安全方案定义。

{
    // ...
    "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 也可以携带包含 动态变量的 URI，例如 http://example.org/weather/?lat=35&lon=139 中的 lat 和 lon。 在这种情况下，可以按照 [RFC6570] 中定义的方式，将 URI 定义为模板： http://example.org/weather/{?lat,long}。

在这种情况下，URI 模板 变量 MUST 收集到 基于 JSON 对象的 uriVariables 成员中， 可以位于物层级，也可以位于 交互可供性层级，并将相关（唯一的） 变量名作为 JSON 名称。

Form 实例中赋给 uriVariables 的 映射里的每个值，其序列化 MUST 依赖于类 DataSchema，其 序列化在 6.3.10 数据 模式中定义。

下面给出一个 TD 片段，它在交互 可供性层级中使用 URI 模板来表示查询参数 和 uriVariables：

{
    "@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 结构。下面提供一个示例 TD， 其中获取哥伦比亚波哥大的天气预报的有效请求， 将是发送到 http://example.org/weather/bogota 的 HTTP GET 请求：

{
    "@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"
            }]
        },
        // ...
    },
    // ...
}

下面两个示例也可以组合，同时 使用同一个 uriVariables 特性。一个发送到 http://example.org/weather/bogota/?unit=Celsius 的 HTTP GET 请求可以描述如下：

{
    "@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 主要用于属性 和事件。在改造现有系统时，可能 有必要将 uriVariables 用于 动作。一般而言，在设计新的 基于 WoT 的系统时，建议尽量避免使用 uriVariables。

contentType 成员用于指定 媒体类型 [RFC2046]， 包括由 ; 字符分隔的属性-值对形式的 媒体类型参数。示例：

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

在某些用例中，交互 可供性的 form 元数据不仅描述请求， 还为预期响应提供元数据。例如， 动作 takePhoto 定义了一个 input 模式，用于以 JSON 作为 请求负载（即 "contentType": "application/json"）来提交相机的参数设置 （光圈优先、定时器等）。该动作的输出 是拍摄的照片，例如以 JPEG 格式提供。 在这种情况下，response 成员 用于指示响应负载的表示格式（例如 "contentType": "image/jpeg"）。此处不需要 output 模式，因为内容类型已经完整指定了 表示格式。

下面基于上文描述的 takePhoto 动作，展示带有 response 成员的 form 片段：

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

在预期响应不包含负载、因此也没有 contentType 的情况下， 可以使用空的 response 对象 来传达此信息。

{
    // ...
    "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": {}
            }]
        }
    },
    // ...
}

在某些情况下，作为交互 可供性一部分从物接收的消息，可能会由于不同原因而有所不同。 这些原因可能是错误情况，或是对有效响应的 替代响应。在这些情况下，可以使用 additionalResponses 术语来 描述这种行为。

例如，用于启动汽车发动机的动作可供性， 在恶劣天气条件下或发动机需要维护时可能无法工作。 在这种情况下，物需要使用通常不会 使用的负载进行回复。

下面展示一个在动作 可供性中带有 additionalResponses 成员的 TD 片段。其第一个元素说明了 上述情况：错误响应可以使用不同于 output 中所描述内容的另一种负载发送。 值为 false 的 success 表明该负载对应错误情况，而 schema 允许链接到 schemaDefinitions 中使用的负载描述。 additionalResponses 中的第二个元素 也描述了错误响应，但这次响应没有 负载。

{
    // ...
    "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 术语也可以用于 非错误情况。在这种情况下， success 被设置为 true， 并且可以使用另一个 schema 来描述负载。

在某些情况下，二进制数据会嵌入到基于文本的 值中，例如，基于 JSON 字符串的值嵌入了一个 base64 编码图像。术语 contentMediaType 和 contentEncoding 可用于阐明 这类名称-值对的上下文和编码格式。 下面展示 contentMediaType 和 contentEncoding 的使用样例：

{
    // ...
    "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 出现在顶层时， 它可用于描述由物提供的元交互。 例如，操作类型 readallproperties 和 writeallproperties 用于与物进行元交互， 通过这些交互，消费者可以一次性读取、写入 或观察所有属性。在下面的示例中， forms 成员包含在 TD 根 对象中，消费者可以同时使用提交目标 https://mylamp.example.com/properties 来读取或写入该物的所有属性 （即 on、 brightness 和 timer）， 并在单个协议事务中完成。

{
    // ...
    "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"
    }]
}

物层级的 uriVariables 可在此处用于 为操作提供更多变量，或为 readmultipleproperties 操作指定 属性可供性名称列表。在下面的示例中， 属性的单位可以通过这样的变量来设置， 并且可以设置期望的属性列表：

{
    // ...
    "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 操作， 发送到 URI https://mylamp.example.com/properties?propertyNames=humidity,temperature&unitSystem=metric 的一个示例 HTTP GET 请求，将返回 humidity 和 temperature 属性可供性的值，并使用 metric 度量系统。

对于操作类型 writeallproperties，预期 消费者提供所有 可写（非 readOnly）属性以及 （新的）赋值（例如在负载中）。类似地， 对于 writemultipleproperties 操作 类型，预期消费者提供可写 （非 readOnly）属性。在物侧，对于 readmultipleproperties 和 readallproperties 操作类型，预期物返回 可读（非 writeOnly）属性。