Web of Things (WoT) Thing Description 1.1

An abstraction of a physical or a virtual entity whose metadata and interfaces are described by a WoT Thing Description, whereas a virtual entity is the composition of one or more Things.

For @context the following rules are defined for Thing Description instances:

• The @context name-value pair MUST contain the anyURI https://www.w3.org/2022/wot/td/v1.1 in order to identify the document as a TD 1.1 which would allow Consumers to use the newly introduced terms.
• When there are possibly TD 1.0 consumers the anyURI https://www.w3.org/2019/wot/td/v1 MUST be the first entry and the https://www.w3.org/2022/wot/td/v1.1 MUST be the second entry.
• TD 1.1 consumers MUST accept TDs satisfying the W3C WoT Thing Description 1.0 [wot-thing-description] specification.
• When @context is an Array, the anyURI https://www.w3.org/2022/wot/td/v1.1 MAY be followed by elements of type anyURI or type Map in any order, while it is RECOMMENDED to include only one Map with all the name-value pairs in the @context Array.
• Maps contained in an @context Array MAY contain name-value pairs, where the value is a namespace identifier of type anyURI and the name a Term or prefix denoting that namespace.
• One Map contained in an @context Array SHOULD contain a name-value pair that defines the default language for the Thing Description, where the name is the Term @language and the value is a well-formed language tag as defined by [BCP47] (e.g., en, de-AT, gsw-CH, zh-Hans, zh-Hant-HK, sl-nedis).

To determine the base direction of all human-readable text in Thing Description and Thing Model instances this specification recommends to follow the [STRING-META] guideline about string-specific directional information when no built-in mechanism for associating base direction metadata is available.

TD Processors should be aware of certain special cases when processing bidirectional text. TD Processors SHOULD take care to use bidi isolation when presenting strings to users, particularly when embedding in surrounding text (e.g., for Web user interface). Mixed direction text can occur in any language, even when the language is properly identified.

TD producers SHOULD attempt to provide mixed direction strings in a way that can be displayed successfully by a naive user agent. For example, if an RTL string begins with an LTR run (such as a number or a brand or trade name in Latin script), including an RLM character at the start of the string or wrapping opposite direction runs in bidi controls can assist in proper display.

Strings on the Web: Language and Direction Metadata [string-meta] provides some guidance and illustrates a number of pitfalls when using bidirectional text.

In addition to the explicitly provided Interaction Affordances in the properties, actions, and events Maps, a Thing can also provide meta-interactions, which are indicated by Form instances in its optional forms Array. When the forms Array of a Thing instance contains Form instances, it MUST contain op member with the string values assigned to the name op, either directly or within an Array, MUST be one of the following operation types: readallproperties, writeallproperties, readmultipleproperties, writemultipleproperties, observeallproperties, unobserveallproperties, queryallactions, subscribeallevents, or unsubscribeallevents. (See an example for an usage of form in a Thing instance.)

The data schema for each of the property meta-interactions is constructed by combining the data schemas of each PropertyAffordance instance in a single ObjectSchema instance, where the properties Map of the ObjectSchema instance contains each data schema of the PropertyAffordances identified by the name of the corresponding PropertyAffordances instance.

If not specified otherwise (e.g., through a TD Context Extension), the request data of the readmultipleproperties operation is an Array that contains the intended PropertyAffordances instance names, which is serialized to the content type specified by the Form instance.

Metadata of a Thing that shows the possible choices to Consumers, thereby suggesting how Consumers may interact with the Thing. There are many types of potential affordances, but W3C WoT defines three types of Interaction Affordances: Properties, Actions, and Events.

The class InteractionAffordance has the following subclasses:

• PropertyAffordance
• ActionAffordance
• EventAffordance

An Interaction Affordance that exposes state of the Thing. This state can then be retrieved (read) and/or updated (write). Things can also choose to make Properties observable by pushing the new state after a change.

PropertyAffordance is a Subclass of the InteractionAffordance Class and the DataSchema Class. When a Form instance is within a PropertyAffordance instance, the value assigned to op MUST be one of readproperty, writeproperty, observeproperty, unobserveproperty or an Array containing a combination of these terms.

An Interaction Affordance that allows to invoke a function of the Thing, which manipulates state (e.g., toggling a lamp on or off) or triggers a process on the Thing (e.g., dim a lamp over time).

ActionAffordance is a Subclass of the InteractionAffordance Class. When a Form instance is within an ActionAffordance instance, the value assigned to op MUST either be invokeaction, queryaction, cancelaction or an Array containing a combination of these terms.

An Interaction Affordance that describes an event source, which asynchronously pushes event data to Consumers (e.g., overheating alerts).

EventAffordance is a Subclass of the InteractionAffordance Class. When a Form instance is within an EventAffordance instance, the value assigned to op MUST be either subscribeevent, unsubscribeevent, or both terms within an Array.

Metadata of a Thing that provides version information about the TD document. If required, additional version information such as firmware and hardware version (term definitions outside of the TD namespace) can be extended via the TD Context Extension mechanism.

It is recommended that the values within instances and model of the VersionInfo Class follow the semantic versioning pattern, where a sequence of three numbers separated by a dot indicates the major version, minor version, and patch version, respectively. See [SEMVER] for details.

A Map providing a set of human-readable texts in different languages identified by language tags described in [BCP47]. See 6.3.2 Human-Readable Metadata for example usages of this container in a Thing Description instance.

Each name of the MultiLanguage Map MUST be a language tag as defined in [BCP47]. Each value of the MultiLanguage Map MUST be of type string.

Metadata that describes the data format used. It can be used for validation.

The class DataSchema has the following subclasses:

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

The format string values are known from a fixed set of values and their corresponding format rules defined in [JSON-SCHEMA] (Section 7.3 Defined Formats in particular). Servients MAY use the format value to perform additional validation accordingly. When a value that is not found in the known set of values is assigned to format, such a validation SHOULD succeed.

Metadata describing data of type Array. This Subclass is indicated by the value array assigned to type in DataSchema instances.

Metadata describing data of type boolean. This Subclass is indicated by the value boolean assigned to type in DataSchema instances.

Metadata describing data of type number. This Subclass is indicated by the value number assigned to type in DataSchema instances.

Metadata describing data of type integer. This Subclass is indicated by the value integer assigned to type in DataSchema instances.

Metadata describing data of type Object. This Subclass is indicated by the value object assigned to type in DataSchema instances.

Metadata describing data of type string. This Subclass is indicated by the value string assigned to type in DataSchema instances.

Metadata describing data of type null. This subclass is indicated by the value null assigned to type in DataSchema instances. This Subclass describes only one acceptable value, namely null. It is important to note that null does not mean the absence of a value. It is analogous to null in JavaScript, None in Python, null in Java and nil in Ruby programming languages. It can be used as part of a oneOf declaration, where it is used to indicate, that the data can also be null.

Metadata describing the configuration of a security mechanism. The value assigned to the name scheme MUST be defined within a Vocabulary included in the Thing Description, either in the standard Vocabulary defined in § 5. TD Information Model or in a TD Context Extension.

For all security schemes, any keys, passwords, or other sensitive information directly providing access MUST NOT be stored in the TD and should instead be shared and stored out-of-band via other mechanisms. The purpose of a TD is to describe how to access a Thing if and only if a Consumer already has authorization, and is not meant be used to grant that authorization.

Each security scheme object used in a TD defines a set of requirements to be met before access can be granted. We say a security scheme is satisfied when all its requirements are met. In some cases requirements from multiple security schemes will have to be met before access can be granted.

Security schemes generally may require additional authentication parameters, such as a password or key. The location of this information is indicated by the value associated with the name in, often in combination with the value associated with name. The value associated with in can take one of the following values:

header:

The parameter will be given in a header provided by the protocol, with the name of the header provided by the value of name.

query:

The parameter will be appended to the URI as a query parameter, with the name of the query parameter provided by name.

body:

The parameter will be provided in the body of the request payload, with the data schema element used provided by name. When used in the context of a body security information location, the value of name MUST be in the form of a JSON pointer [RFC6901] relative to the root of the input DataSchema for each interaction it is used with. Since this value is not a fragment identifier, and is not relative to the root of the TD but to whichever data schemas the security scheme is bound to, this value should not start with #; it is a "pure" JSON pointer. Since this value is not a fragment identifier, it also does not need to URL-encode special characters. The targeted element may or may not already exist at the specified location in the referenced data schema. If it does not, it will be inserted. This avoids having to duplicate definitions in the data schemas of every interaction. When an element of a data schema indicated by a JSON pointer indicated in a body locator does not already exist in the indicated schema, it MUST be possible to insert the indicated element at the location indicated by the pointer. The JSON pointer used in the body locator MAY use the "-" character to indicate a non-existent array element when it is necessary to insert an element after the last element of an existing array. The element referenced (or created) by a body security information location MUST be required and of type "string". If name is not given, it is assumed the entire body is to be used as the security parameter.

cookie:

The parameter is stored in a cookie identified by the value of name.

uri:

The parameter is embedded in the URI itself, which is encoded in the relevant interaction using a URI template variable defined by the value of name. This is more general than the query mechanism but more complex. The value uri SHOULD be specified for the name in in a security scheme only if query is not applicable. The URIs provided in interactions where a security scheme using uri as the value for in MUST be a URI template including the defined variable.

auto:

The location is determined as part of the protocol, or negotiated. If a value of auto is set for the in field of a SecurityScheme, then the name field SHOULD NOT be set. In this case, the application of the SecurityScheme is subject to the respective specification for the given protocol (e.g. [RFC8288] when using the BasicSecurityScheme with HTTP).

The names of URI variables declared in a SecurityScheme MUST be distinct from all other URI variables declared in the TD.

The class SecurityScheme has the following subclasses:

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

A security configuration corresponding to identified by the Vocabulary Term nosec (i.e., "scheme": "nosec"), indicating there is no authentication or other mechanism required to access the resource.

An automatic authentication security configuration identified by the term auto (i.e., "scheme": "auto"). This scheme indicates that the security parameters are going to be negotiated by the underlying protocols at runtime, subject to the respective specifications for the protocol (e.g. [RFC8288] for Basic Authentication when using HTTP).

This section is at risk.

A combination of other security schemes identified by the Vocabulary Term combo (i.e., "scheme": "combo"). Elements of this scheme define various ways in which other named schemes defined in securityDefinitions, including other ComboSecurityScheme definitions, are to be combined to create a new scheme definition. Exactly one of either oneOf or allOf MUST be included. Only security scheme definitions which can be used together can be combined with allOf. For example, it is not possible in general to combine different OAuth 2.0 flows together using allOf unless one applies to a proxy and one to the endpoint. Note that when multiple named security scheme definitions are listed in a security field the same semantics apply as in an allOf combination (and the same limitations on allowable combinations). The oneOf combination is equivalent to using different security schemes on forms that are otherwise identical. In this sense a oneOf scheme is not an essential feature but it does avoid redundancy in such cases.

Basic Authentication [RFC7617] security configuration identified by the Vocabulary Term basic (i.e., "scheme": "basic"), using an unencrypted username and password.

Digest Access Authentication [RFC7616] security configuration identified by the Vocabulary Term digest (i.e., "scheme": "digest"). This scheme is similar to basic authentication but with added features to avoid man-in-the-middle attacks.

API key authentication security configuration identified by the Vocabulary Term apikey (i.e., "scheme": "apikey"). This scheme is to be used when the access token is opaque, for example when a key in an unknown or proprietary format is provided by a cloud service provider. In this case the key may not be using a standard token format. This scheme indicates that the key provided by the service provider needs to be supplied as part of service requests using the mechanism indicated by the "in" field.

Bearer Token [RFC6750] security configuration identified by the Vocabulary Term bearer (i.e., "scheme": "bearer") for situations where bearer tokens are used independently of OAuth2. If the oauth2 scheme is specified it is not generally necessary to specify this scheme as well as it is implied. For format, the value jwt indicates conformance with [RFC7519], jws indicates conformance with [RFC7797], cwt indicates conformance with [RFC8392], and jwe indicates conformance with [RFC7516], with values for alg interpreted consistently with those standards. Other formats and algorithms for bearer tokens MAY be specified in vocabulary extensions.

Pre-shared key authentication security configuration identified by the Vocabulary Term psk (i.e., "scheme": "psk"). This is meant to identify that a standard is used for pre-shared keys such as TLS-PSK [RFC4279], and that the ciphersuite used for keys will be established during protocol negotiation.

OAuth 2.0 authentication security configuration for systems conformant with [RFC6749], [RFC8252] and (for the device flow) [RFC8628], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2").

For the code flow both authorization and token MUST be included. For the client flow token MUST be included. For the client flow authorization MUST NOT be included. For the device flow both authorization and token MUST be included. In the case of the device flow the value provided for authorization refers to the device authorization endpoint defined in [RFC8628]. The mandatory elements for each flow are summarized in the following table:

A link can be viewed as a statement of the form "link context has a relation type resource at link target", where the optional target attributes may further describe the resource.

Link relations can be used to describe relations such as to other Things (e.g., a Switch Thing controls a Lamp Thing), to a specific kind of Thing Models (e.g., a Thing Description is an instance of a specific Thing Model), or to further documentations information (e.g., device manual of a Thing). It is recommended to reuse existing and established Link Relation definitions from IANA.

In the following a best practice relation type table is introduced that is recommended to use within WoT Thing Description or Thing Model instances.

A form can be viewed as a statement of "To perform an operation type operation on form context, make a request method request to submission target" where the optional form fields may further describe the required request. In Thing Descriptions, the form context is the surrounding Object, such as Properties, Actions, and Events or the Thing itself for meta-interactions.

Possible values for the contentCoding property can be found, e.g., in the IANA HTTP content coding registry.

The list of possible operation types of a form is fixed. As of this version of the specification, it only includes the well-known types necessary to implement the WoT interaction model described in [wot-architecture11]. Future versions of the standard may extend this list but operations types SHOULD NOT be arbitrarily set by servients and be restricted to the values in the table below.

A Thing Description of a WoT producer may have multiple forms entries with, e.g., different protocol and/or content types declarations that a Consumer could possibly support. In that case the Consumer may choose any form entry that works (e.g., the protocol and content type is supported) for them. When one form is chosen, it is expected that the Consumer will continue to use it as long as possible for every new interaction with the WoT producer.

Communication metadata describing the expected response message for the primary response.

Communication metadata describing the expected response message for additional responses.

To give a more complex example, suppose we have a Thing where all Interaction Affordances require basic authentication except for one, for which no authentication is required. For the status Property and the toggle Action, basic authentication is required and defined at the Thing level. For the overheating Event, however, no authentication is required, and hence the security configuration is overridden at the 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 can specify a combination of security schemes as well. Below is a TD snippet showing digest authentication on a proxy combined with bearer token authentication on the Thing. In the digest scheme, the Default Value of in (i.e., header) is omitted, but still applies. Note that the corresponding private security configuration such as username/password and tokens need to be configured in the Consumer to interact successfully. When activating multiple security definitions, the security member becomes an 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"],
    // ...
}

However, the use of an array with multiple elements to combine security schemes in a security element is now deprecated, instead a ComboSecurityScheme SHOULD be used. In the following example, which is exactly equivalent to the one above, this is demonstrated:

{
    // ...
    "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 can also be specified for different forms within the same Interaction Affordance. This may be required for devices that support multiple protocols, for example HTTP and CoAP [RFC7252], which support different security mechanisms. This is also useful when alternative authentication mechanisms are allowed. Here is a TD snippet demonstrating three possible ways to activate a Property affordance: via HTTPS with basic authentication, with digest authentication, with bearer token authentication. In other words, the use of different security configurations within multiple forms provides a way to combine security mechanisms in an "OR" fashion. In contrast, putting multiple security configurations in the same security member combines them in an "AND" fashion, since in that case they would all need to be satisfied to allow activation of the Interaction Affordance. Note that activating one (default) configuration at the Thing level is still mandatory.

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

To avoid redundancy in this case, e.g. repeating the details of the form elements, a ComboSecurityScheme with oneOf can be used instead.

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

As another more complex example, OAuth 2.0 makes use of scopes. These are identifiers that may appear in tokens and must match with corresponding identifiers in a resource to allow access to that resource (or Interaction Affordance in the case of W3C WoT). For example, in the following, the status Property can be read by Consumers using bearer tokens containing the scope limited, but the configure Action can only be invoked with a token containing the special scope. Scopes are not identical to roles, but are often associated with them; for example, perhaps only those in an administrative role are authorized to perform "special" interactions. Tokens can have more than one scope and are issued by dedicated web services to users. In this example, an administrator could be issued tokens with both the limited and special scopes, while ordinary users could be provided with tokens with the limited scope.

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

A Thing can require an onboarding process that results in the Consumer requiring an API key to interact with the Thing. This API key can be included in the request to the Thing in different ways as the API key scheme specifies. Below is an example of how it can be used as a URI template where the API key should be replaced in the URI by the Consumer when sending an HTTPS request.

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

To give another example of the use of the ComboSecurityScheme in addition to the use of URI templates example shown above, suppose there is a security scheme where a client ID and a "secret" key provided by a cloud service provider must both be embedded in the URL. Technically, only the key is actually secret and must be handled out-of-band, and the client ID, which is not secret, could be embedded in the TD. However, if the client ID cannot be easily rotated we may want to avoid embedding it in the TD to enhance privacy. In this case we can combine two instances of APIKeySecurityScheme, both using the uri value for the in location specifier, to declare two URI variables. These can then (in fact, they must) be used in the href in a Form where the security scheme is active. An example follows:

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

While not shown in this example, it is legal to declare additional URI template variables using uriVariables and include them in the same URI template, although the names cannot conflict with those declared in security schemes. Using a specific prefix as in the above example for URI variables declared in security schemes can make it easier to avoid name conflicts.

API Key in Body: Security parameters might also be included along with the payload in some systems. For example, suppose a system requires every payload to be a JSON object including a member named auth whose value is an object containing a member called key containing an access key. Depending on the interaction, however, other elements of the JSON object might vary. This situation can be dealt with using the body security information location. Note that for this location, the name parameter is actually a JSON pointer evaluated relative to the root of the DataSchema for each interaction it is bound with, which allows it to be used with payloads that vary in other respects. As an example, here is a light that has a property to set its brightness and color and two separate actions to turn it on and off. Although the JSON payloads are different for these actions the /auth/key element occurs in the same relative location so single JSON pointer can be used. Note: if the security key occurs in different inconsistent locations, it will be necessary to use multiple 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 may also carry a URI that contains dynamic variables such as lat and lon in http://example.org/weather/?lat=35&lon=139. In that case the URI can be defined as template as defined in [RFC6570]: http://example.org/weather/{?lat,long}.

In such a case, the URI Template variables MUST be collected in the JSON-object based uriVariables member either in the Thing level or in Interaction Affordance level with the associated (unique) variable names as JSON names.

The serialization of each value in the map assigned to uriVariables in an instance of Form MUST rely on the Class DataSchema, whose serialization is defined in 6.3.10 Data Schemas.

A TD snippet using a URI Template for query parameters and uriVariables in the Interaction Affordance level is given below:

{
    "@context": "https://www.w3.org/2022/wot/td/v1.1",
    // ...
    "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"
            }]
        },
        // ...
    },
    // ...
}

Alternatively, as defined in [RFC6570], uriVariables can be used for replacing the href structure. An example TD is provided below where a valid request to get the forecast of Bogota, Colombia would be an HTTP GET request to http://example.org/weather/bogota:

{
    "@context": "http://www.w3.org/ns/td",
    // ...
    "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"
            }]
        },
        // ...
    },
    // ...
}

The two examples below can be also combined, while using the same uriVariables feature. An HTTP GET request to http://example.org/weather/bogota/?unit=Celsius can be described as follows:

{
    "@context": "http://www.w3.org/ns/td",
    // ...
    "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 are mainly for properties and events. When retrofitting an existing system, it may be necessary to use uriVariables for actions. In general, it is recommended to avoid uriVariables as much as possible when a new WoT-based system is designed.

The contentType member is used to assign a media type [RFC2046] including media type parameters as attribute-value pairs separated by a ; character. Example:

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

In some use cases, the form metadata of the Interaction Affordance not only describes the request, but also provides metadata for the expected response. For instance, an Action takePhoto defines an input schema to submit parameter settings of a camera (aperture priority, timer, etc.) using JSON for the request payload (i.e., "contentType": "application/json"). The output of this action is the photo taken, which is available in JPEG format, for example. In such cases, the response member is used to indicate the representation format of the response payload (e.g., "contentType": "image/jpeg"). Here no output schema is required, as the content type fully specifies the representation format.

If present, the value assigned to response in an instance of Form MUST be a JSON object. If present, the response object MUST contain a contentType member as defined in the Class definition of ExpectedResponse.

A form snippet with the response member is shown below based on the takePhoto Action described above:

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

In some cases, the message received from the Thing as part of an Interaction Affordance can differ due to different reasons. Such reasons could be error cases or alternative responses for a valid response. In these cases, additionalResponses terms can be used to describe this behavior.

For example, an Action Affordance to turn on a car engine may not work in bad weather conditions or in case the engine needs maintenance. In such a case, the Thing needs to reply with payloads that are not usually used.

A TD snippet with the additionalResponses member in an Action Affordance is shown below. It describes the case mentioned above when an error response can be sent with another payload than what is described in the output. The success with the value false refers to the fact that this payload refers to an error case and schema allows linking to the payload description used at schemaDefinitions:

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

The additionalResponses term can be used in non-error cases as well. In that case, success is set to true and another schema can be used to describe the payload.

In some cases binary data is embedded in text-based values, e.g., a JSON string-based value embeds a base64 encoded image. The terms contentMediaType and contentEncoding can be used to clarify the context and encoding format of such name-value pairs. A sample usage of contentMediaType and contentEncoding is shown below:

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

When forms is present at the top level, it can be used to describe meta interactions offered by a Thing. For example, the operation types readallproperties and writeallproperties are for meta interactions with a Thing by which Consumers can read, write or observe all properties at once. In the example below, a forms member is included in the TD root object and the Consumer can use the submission target https://mylamp.example.com/properties both to read or write all Properties (i.e., on, brightness, and timer) of the Thing in a single protocol transaction.

{
    // ...
    "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 can be used here to supply further variables to the operation or to specify a list of Property Affordance names for a readmultipleproperties operation. In the example below, the unit for the properties can be set via such a variable and the desired list of properties can be set:

{
    // ...
    "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_value","imperial_value","uscustomary_value"],
            "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"
    }]
}

For a readmultipleproperties operation, an example HTTP GET request to the URI https://mylamp.example.com/properties?propertyNames=humidity,temperature&unitSystem=metric would return the values humidity and temperature Property Affordances, with the metric System of Measurement.

In the case of operation type writeallproperties, it is expected that the Consumer provides all writable (non readOnly) properties and the (new) assigned values (e.g., within payload). Similarly, for the writemultipleproperties operation type, it is expected that the Consumer provides writable (non readOnly) properties. On the Thing side, Thing is expected to return readable (non writeOnly) properties in the case of readmultipleproperties and readallproperties operation types.