Web of Things (WoT) Thing Description 1.1

Abstract

This document describes a formal information model and a common representation for a Web of Things (WoT) Thing Description 1.1. A Thing Description describes the metadata and interfaces of Things , where a Thing is an abstraction of a physical or virtual entity that provides interactions to and participates in the Web of Things. Thing Descriptions provide a set of interactions based on a small vocabulary that makes it possible both to integrate diverse devices and to allow diverse applications to interoperate. Thing Descriptions, by default, are encoded in a JSON format that also allows JSON-LD processing. The latter provides a powerful foundation to represent knowledge about Things in a machine-understandable way. A Thing Description instance can be hosted by the Thing itself or hosted externally when a Thing has resource restrictions (e.g., limited memory space) or when a Web of Things-compatible legacy device is retrofitted with a Thing Description. Furthermore, this document introduces the Thing Model, which allows authors to describe only the model or class of an Internet of Things (IoT) entity. Thing Models can be seen as a template for Thing Description instances, but with reduced constraints such as no or few requirements for specific communication metadata.

This specification describes a superset of the features defined in Thing Description 1.0 [ WOT-THING-DESCRIPTION10 ]. Unless otherwise specified, documents created with version 1.0 of this specification remain compatible with Thing Description 1.1.

Table 1 Namespaces used in TDs
Vocabulary	Namespace IRI
Core	`https://www.w3.org/2019/wot/td#`
Data Schema	`https://www.w3.org/2019/wot/json-schema#`
Security	`https://www.w3.org/2019/wot/security#`
Hypermedia Controls	`https://www.w3.org/2019/wot/hypermedia#`

Table 2 Namespaces used in TMs
Vocabulary	Namespace IRI
Thing Model	`https://www.w3.org/2022/wot/tm#`

This section introduces the TD Information Model . The TD Information Model serves as the conceptual basis for the processing of Thing Descriptions and their serialization, which is described separately in 6. TD Representation Format .

The TD Information Model is built upon the following, independent Vocabularies :

the core TD Vocabulary , which reflects the Interaction Model with the Properties , Actions , and Events Interaction Affordances [ wot-architecture11 ]
the Data Schema Vocabulary , including (a subset of) the terms defined by JSON Schema [ JSON-SCHEMA ]
the WoT Security Vocabulary , identifying security mechanisms and requirements for their configuration
the Hypermedia Controls Vocabulary , encoding the main principles of RESTful communication using Web links and forms

Each of these Vocabularies is essentially a set of Terms that can be used to build data structures, interpreted as objects in the traditional object-oriented sense. Objects are instances of classes and have properties. In the context of W3C WoT, they denote Things and their Interaction Affordances . A formal definition of objects is given in 5.2 Preliminaries . The main elements of the TD Information Model are then presented in 5.3 Class Definitions . Certain object properties may be omitted in a TD when Default Values exist. A list of defaults is given in 5.4 Default Value Definitions .

The UML diagram shown next gives an overview of the TD Information Model . It represents all classes as tables and the associations that exist between classes, starting from the class Thing, as directed arrows. For the sake of readability, the diagram was split in four parts, one for each of the four base Vocabularies .

UML diagram of the TD information model for the TD core vocabulary — Figure 1 TD core vocabulary

UML diagram of the TD information model for the Data schema vocabulary — Figure 2 Data schema vocabulary

UML diagram of the TD information model for the WoT security vocabulary — Figure 3 WoT security vocabulary

UML diagram of the TD information model for the hypermedia controls vocabulary — Figure 4 Hypermedia controls vocabulary

To provide a model that can be easily processed by both, simple rules on a tree-based document (i.e., raw JSON processing) and rich Semantic Web tooling (i.e., JSON-LD processing), this document defines the following formal preliminaries to construct the TD Information Model accordingly.

All definitions in this section refer to sets , which intuitively are collections of elements that can themselves be sets. All arbitrarily complex data structures can be defined in terms of sets. In particular, an Object is a data structure recursively defined as follows:

a Term , which may or may not belong to a Vocabulary , is an Object .
a set of name-value pairs where the name is a Term and the value is another Object , is also an Object .

Though this definition does not prevent Objects to include multiple name-value pairs with the same name, they are generally not considered in this specification. An Object whose elements only have numbers as names is called an Array . Similarly, an Object whose elements only have Term s (that do not belong to any Vocabulary ) as names is called a Map . All names appearing in some name-value pair in a Map are assumed to be unique within the scope of the Map .

Moreover, Object s can be instances of some Class . A Class , which is denoted by a Vocabulary Term , is first defined by a set of Vocabulary Terms called a Signature . A Class whose Signature is empty is called a Simple Type .

The Signature of a Class allows to construct two functions that further define Classes : an Assignment Function and a Type Function . The Assignment Function of a Class takes a Vocabulary Term of the Class 's Signature as input and returns either true or false as output. Intuitively, the Assignment Function indicates whether an element of the Signature is mandatory or optional when instantiating the Class . The Type Function of a Class also takes a Vocabulary Term of the Class 's Signature as input and returns another Class as output. These functions are partial : their domain is limited to the Signature of the Class being defined.

On the basis of these two functions, an Instance Relation can be defined for a pair composed of an Object and a Class . This relation is defined as constraints to be satisfied. That is, an Object is an instance of a Class if the two following constraints are both satisfied:

if for every Term for which the Assignment Function of the Class returns true, the Object includes a name-value pair with the Vocabulary Term as name.
if for every Vocabulary Term in the Signature of the Class used as name in some name-value pair of the Object , the value of that pair is an instance of the Class returned by the Type Function of the Class for the given Vocabulary Term .

According to the definition above, an Object would be an instance of every Simple Type , regardless of its structure. Instead, another definition for the Instance Relation is introduced for Simple Types : an Object is an instance of a Simple Type if it is a Term with a given lexical form (e.g., true,false for the boolean type, 1,2,3, ... for the unsignedInt type, etc.).

Moreover, additional Classes , called Parameterized Classes , can be derived from the generic Map and Array structures. An Object is a Map of some Class , that is, an instance of the Map type parameterized with some Class , if it is a Map such that the value in all the name-value pairs it contains is an instance of this Class . The same applies to Arrays .

Finally, a Class is a Subclass of some other Class if every instance of the former is also an instance of the latter.

Given all definitions above, the TD Information Model is to be understood as a set of Class definitions, which include a Class name (a Vocabulary Term ), a Signature (a set of Vocabulary Terms ), an Assignment Function , and a Type Function . These Class definitions are provided as tables in 5.3 Class Definitions . For each table, the values "mandatory" (respectively, "optional") in the assignment column indicates that the Assignment Function returns true (respectively, false ) for the corresponding Vocabulary Term .

By convention, Simple Types are denoted by names starting with lowercase. The TD Information Model references the following Simple Types defined in XML Schema [ XMLSCHEMA11-2-20120405 ]: string,anyURI,dateTime,integer,unsignedInt,double, and boolean. Their definition (i.e., the specification of their lexical form) is outside of the scope of the TD Information Model .

In addition, the TD Information Model defines a global function on pairs of Vocabulary Terms . The function takes a Class name and another Vocabulary Term as input and returns an Object . If the returned Object is different from null, it represents the Default Value for some assignment on the input Vocabulary Term in an instance of the input Class . This function allows to relax the constraint defined above on the Assignment Function : an Object is an instance of a Class if it includes all mandatory assignments or if Default Value exist for the missing assignments. All Default Values are given in the table of 5.4 Default Value Definitions . In each table of 5.3 Class Definitions , the assignment column contains the value "with default" if a Default Value is available for the corresponding combination of Class and Vocabulary Term in the TD Information Model .

The formalization introduced here does not consider the possible relation between Objects as abstract data structures and physical world objects such as Things . However, care was given to the possibility of re-interpreting all Vocabulary Terms involved in the TD Information Model as RDF resources, so as to integrate them in a larger model of the physical world (an ontology). For details about semantic processing, please refer to D. JSON-LD Context Usage and the documentation under the namespace IRIs, e.g., https://www.w3.org/2019/wot/td .

A TD Processor MUST satisfy the Class instantiation constraints on all Classes defined in 5.3.1 Core Vocabulary Definitions , 5.3.2 Data Schema Vocabulary Definitions , 5.3.3 Security Vocabulary Definitions , and 5.3.4 Hypermedia Controls Vocabulary Definitions .

In particular, note that all vocabulary terms and values are case sensitive. This is also true for the serialization of the information model (Section 6. TD Representation Format ).

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.

Table 3 Vocabulary Terms in Thing Level
Vocabulary term	Description	Assignment	Type
`@context`	JSON-LD keyword to define short-hand names called terms that are used throughout a TD document.	mandatory	`anyURI` or Array
`@type`	JSON-LD keyword to label the object with semantic tags (or types).	optional	`string` or Array of `string`
`id`	Identifier of the Thing in form of a URI [ RFC3986 ] (e.g., stable URI, temporary and mutable URI, URI with local IP address, URN, etc.).	optional	`anyURI`
`title`	Provides a human-readable title (e.g., display a text for UI representation) based on a default language.	mandatory	`string`
`titles`	Provides multi-language human-readable titles (e.g., display a text for UI representation in different languages). Also see MultiLanguage .	optional	Map of `MultiLanguage`
`description`	Provides additional (human-readable) information based on a default language.	optional	`string`
`descriptions`	Can be used to support (human-readable) information in different languages. Also see MultiLanguage .	optional	Map of `MultiLanguage`
`version`	Provides version information.	optional	`VersionInfo`
`created`	Provides information when the TD instance was created.	optional	`dateTime`
`modified`	Provides information when the TD instance was last modified.	optional	`dateTime`
`support`	Provides information about the TD maintainer as URI scheme (e.g., `mailto` [ RFC6068 ], `tel` [ RFC3966 ], `https` [ RFC9112 ]).	optional	`anyURI`
`base`	Define the base URI that is used for all relative URI references throughout a TD document. In TD instances, all relative URIs are resolved relative to the base URI using the algorithm defined in [ RFC3986 ]. `base` does not affect the URIs used in `@context` and the IRIs used within Linked Data [ LINKED-DATA ] graphs that are relevant when semantic processing is applied to TD instances.	optional	`anyURI`
`properties`	All Property-based Interaction Affordances of the Thing.	optional	Map of `PropertyAffordance`
`actions`	All Action-based Interaction Affordances of the Thing.	optional	Map of `ActionAffordance`
`events`	All Event-based Interaction Affordances of the Thing.	optional	Map of `EventAffordance`
`links`	Provides Web links to arbitrary resources that relate to the specified Thing Description.	optional	Array of `Link`
`forms`	Set of form hypermedia controls that describe how an operation can be performed. Forms are serializations of Protocol Bindings. Thing level forms are used to describe endpoints for a group of interaction affordances.	optional	Array of `Form`
`security`	Set of security definition names, chosen from those defined in `securityDefinitions`. These must all be satisfied for access to resources.	mandatory	`string` or Array of `string`
`securityDefinitions`	Set of named security configurations (definitions only). Not actually applied unless names are used in a `security` name-value pair.	mandatory	Map of `SecurityScheme`
`profile`	Indicates the WoT Profile mechanisms followed by this Thing Description and the corresponding Thing implementation.	optional	`anyURI` or Array of `anyURI`
`schemaDefinitions`	Set of named data schemas. To be used in a `schema` name-value pair inside an `AdditionalExpectedResponse` object.	optional	Map of `DataSchema`
`uriVariables`	Define URI template variables according to [ RFC6570 ] as collection based on DataSchema declarations. The Thing level `uriVariables` can be used in Thing level `forms` or in Interaction Affordances. The individual variables DataSchema cannot be an ObjectSchema or an ArraySchema since each variable needs to be serialized to a string inside the `href` upon the execution of the operation. If the same variable is both declared in Thing level `uriVariables` and in Interaction Affordance level, the Interaction Affordance level variable takes precedence.	optional	Map of `DataSchema`

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-description10 ] 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.

Table 4 Vocabulary Terms in InteractionAffordance Level
Vocabulary term	Description	Assignment	Type
`@type`	JSON-LD keyword to label the object with semantic tags (or types).	optional	`string` or Array of `string`
`title`	Provides a human-readable title (e.g., display a text for UI representation) based on a default language.	optional	`string`
`titles`	Provides multi-language human-readable titles (e.g., display a text for UI representation in different languages). Also see MultiLanguage .	optional	Map of `MultiLanguage`
`description`	Provides additional (human-readable) information based on a default language.	optional	`string`
`descriptions`	Can be used to support (human-readable) information in different languages. Also see MultiLanguage .	optional	Map of `MultiLanguage`
`forms`	Set of form hypermedia controls that describe how an operation can be performed. Forms are serializations of Protocol Bindings. The array cannot be empty.	mandatory	Array of `Form`
`uriVariables`	Define URI template variables according to [ RFC6570 ] as collection based on DataSchema declarations. The individual variables DataSchema cannot be an ObjectSchema or an ArraySchema since each variable needs to be serialized to a string inside the `href` upon the execution of the operation. If the same variable is both declared in Thing level `uriVariables` and in Interaction Affordance level, the Interaction Affordance level variable takes precedence.	optional	Map of `DataSchema`

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.

Table 5 Vocabulary Terms in PropertyAffordance Level
Vocabulary term	Description	Assignment	Type
`observable`	A hint that indicates whether Servients hosting the Thing and Intermediaries should provide a Protocol Binding that supports the `observeproperty` and `unobserveproperty` operations for this Property.	with default	`boolean`

Note

Property instances are also instances of the class DataSchema . Therefore, it can contain the type,unit,readOnly and writeOnly members, among others.

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.

Note

It is considered to be good practice that each observeproperty has a corresponding unobserveproperty unless the protocol supports implicit unsubscription mechanisms (e.g., heartbeat to detect connection loss).

Note

The observation mechanism depends on the underlying protocol or sub-protocol. Having said that, it is not guaranteed that the current Property value will be provided once the subscription is initiated. Hence, it may be necessary to read the current Property value before/after the subscription to get a first value.

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).

Table 6 Vocabulary Terms in ActionAffordance Level
Vocabulary term	Description	Assignment	Type
`input`	Used to define the input data schema of the Action.	optional	`DataSchema`
`output`	Used to define the output data schema of the Action.	optional	`DataSchema`
`safe`	Signals if the Action is safe (=true) or not. Used to signal if there is no internal state (cf. resource state) is changed when invoking an Action. In that case responses can be cached as example.	with default	`boolean`
`idempotent`	Indicates whether the Action is idempotent (=true) or not. Informs whether the Action can be called repeatedly with the same result, if present, based on the same input.	with default	`boolean`
`synchronous`	Indicates whether the action is synchronous (=true) or not. A synchronous action means that the response of action contains all the information about the result of the action and no further querying about the status of the action is needed. Lack of this keyword means that no claim on the synchronicity of the action can be made.	optional	`boolean`

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).

Table 7 Vocabulary Terms in EventAffordance Level
Vocabulary term	Description	Assignment	Type
`subscription`	Defines data that needs to be passed upon subscription, e.g., filters or message format for setting up Webhooks.	optional	`DataSchema`
`data`	Defines the data schema of the Event instance messages pushed by the Thing.	optional	`DataSchema`
`dataResponse`	Defines the data schema of the Event response messages sent by the consumer in a response to a data message.	optional	`DataSchema`
`cancellation`	Defines any data that needs to be passed to cancel a subscription, e.g., a specific message to remove a Webhook.	optional	`DataSchema`

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 .

Note

It is considered to be good practice that each subscribeevent has a corresponding unsubscribeevent unless the protocol supports implicit unsubscription mechanisms (e.g., heartbeat to detect connection loss).

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.

Table 8 Vocabulary Terms in VersionInfo Level
Vocabulary term	Description	Assignment	Type
`instance`	Provides a version indicator of this TD.	mandatory	`string`
`model`	Provides a version indicator of the underlying TM.	optional	`string`

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.

A data schema is an abstract notation for data contained in data formats.

The data schema vocabulary definition reflects a very common subset of the terms defined by JSON Schema [ JSON-SCHEMA ]. It is noted that data schema definitions within Thing Description instances are not limited to this defined subset and may use additional terms found in JSON Schema using a TD Context Extension for the additional terms as described in 7. TD Context Extensions , otherwise these terms are semantically ignored by TD Processors (for details about semantic processing, please refer to D. JSON-LD Context Usage and the documentation under the namespace IRIs, e.g., https://www.w3.org/2019/wot/td ).

In a TD, concrete data formats are specified in Forms (see 5.3.4.2 Form ) using content types. When the value of a content type in an instance of the Form is application/json, the data schema can be processed directly by JSON Schema processors. Otherwise, Web of Things (WoT) Binding Templates [ WOT-BINDING-TEMPLATES ] defines data schema's available mappings to other content types such as XML [ xml ]. If the content type in an instance of the Form is not application/json and if no mapping is defined for the content type, specifying a data schema does not make sense for the content type.

The following table contains content types which MAY use data schema to describe the structure of their payloads.

Table 9 Content types that can use a Data Schema
Format	Content Type
JSON/CBOR	`application/json` `application/ld+json` `application/senml+json` `application/cbor` `application/senml+cbor`
XML/EXI	`application/xml` `application/senml+xml` `application/exi` `application/senml-exi`

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

Table 10 Vocabulary Terms in DataSchema Level
Vocabulary term	Description	Assignment	Type
`@type`	JSON-LD keyword to label the object with semantic tags (or types)	optional	`string` or Array of `string`
`title`	Provides a human-readable title (e.g., display a text for UI representation) based on a default language.	optional	`string`
`titles`	Provides multi-language human-readable titles (e.g., display a text for UI representation in different languages). Also see MultiLanguage .	optional	Map of `MultiLanguage`
`description`	Provides additional (human-readable) information based on a default language.	optional	`string`
`descriptions`	Can be used to support (human-readable) information in different languages. Also see MultiLanguage .	optional	Map of `MultiLanguage`
`const`	Provides a constant value.	optional	any type
`default`	Supply a default value. The value SHOULD validate against the data schema in which it resides.	optional	any type
`unit`	Provides unit information that is used, e.g., in international science, engineering, and business. To preserve uniqueness, it is recommended that the value of the unit points to a semantic definition (also see Section Semantic Annotations ).	optional	`string`
`oneOf`	Used to ensure that the data is valid against one of the specified schemas in the array. This can be used to describe multiple input or output schemas.	optional	Array of `DataSchema`
`enum`	Restricted set of values provided as an array.	optional	Array of any type
`readOnly`	Boolean value that is a hint to indicate whether a property interaction / value is read only (=true) or not (=false).	with default	`boolean`
`writeOnly`	Boolean value that is a hint to indicate whether a property interaction / value is write only (=true) or not (=false).	with default	`boolean`
`format`	Allows validation based on a format pattern such as "date-time", "email", "uri", etc. (Also see below.)	optional	`string`
`type`	Assignment of JSON-based data types compatible with JSON Schema (one of boolean, integer, number, string, object, array, or null).	optional	`string` (one of `object`,`array`,`string`,`number`,`integer`,`boolean`, or `null` )

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.

Vocabulary terms typed as

any


type

(e.g.,


const


default

) follow data types compatible with JSON Schema (boolean, integer, number, string, object, array, or null).

Note

The format term is not widely implemented by JSON Schema tools. In addition, the term format is being discussed by the JSON Schema standardisation community and may be replaced by another mechanism or removed in a future JSON Schema version.

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

Table 11 Vocabulary Terms in ArraySchema Level
Vocabulary term	Description	Assignment	Type
`items`	Used to define the characteristics of an array.	optional	`DataSchema` or Array of `DataSchema`
`minItems`	Defines the minimum number of items that have to be in the array.	optional	`unsignedInt`
`maxItems`	Defines the maximum number of items that have to be in the array.	optional	`unsignedInt`

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.

Table 12 Vocabulary Terms in NumberSchema Level
Vocabulary term	Description	Assignment	Type
`minimum`	Specifies a minimum numeric value, representing an inclusive lower limit. Only applicable for associated number or integer types.	optional	`double`
`exclusiveMinimum`	Specifies a minimum numeric value, representing an exclusive lower limit. Only applicable for associated number or integer types.	optional	`double`
`maximum`	Specifies a maximum numeric value, representing an inclusive upper limit. Only applicable for associated number or integer types.	optional	`double`
`exclusiveMaximum`	Specifies a maximum numeric value, representing an exclusive upper limit. Only applicable for associated number or integer types.	optional	`double`
`multipleOf`	Specifies the multipleOf value number. The value must strictly greater than 0. Only applicable for associated number or integer types.	optional	`double`

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

Table 13 Vocabulary Terms in IntegerSchema Level
Vocabulary term	Description	Assignment	Type
`minimum`	Specifies a minimum numeric value, representing an inclusive lower limit. Only applicable for associated number or integer types.	optional	`integer`
`exclusiveMinimum`	Specifies a minimum numeric value, representing an exclusive lower limit. Only applicable for associated number or integer types.	optional	`integer`
`maximum`	Specifies a maximum numeric value, representing an inclusive upper limit. Only applicable for associated number or integer types.	optional	`integer`
`exclusiveMaximum`	Specifies a maximum numeric value, representing an exclusive upper limit. Only applicable for associated number or integer types.	optional	`integer`
`multipleOf`	Specifies the multipleOf value number. The value must strictly greater than 0. Only applicable for associated number or integer types.	optional	`integer`

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

Table 14 Vocabulary Terms in ObjectSchema Level
Vocabulary term	Description	Assignment	Type
`properties`	Data schema nested definitions.	optional	Map of `DataSchema`
`required`	Defines which members of the object type are mandatory, i.e. which members are mandatory in the payload that is to be sent (e.g. input of `invokeaction`,`writeproperty` ) and what members will be definitely delivered in the payload that is being received (e.g. output of `invokeaction`,`readproperty` )	optional	Array of `string`

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

Table 15 Vocabulary Terms in StringSchema Level
Vocabulary term	Description	Assignment	Type
`minLength`	Specifies the minimum length of a string. Only applicable for associated string types.	optional	`unsignedInt`
`maxLength`	Specifies the maximum length of a string. Only applicable for associated string types.	optional	`unsignedInt`
`pattern`	Provides a regular expression to express constraints of the string value. The regular expression must follow the [ ECMA-262 ] dialect.	optional	`string`
`contentEncoding`	Specifies the encoding used to store the contents, as specified in [ RFC2045 ] (Section 6.1) and [ RFC4648 ].	optional	`string` (e.g., `7bit`,`8bit`,`binary`,`quoted-printable`,`base16`,`base32`, or `base64` )
`contentMediaType`	Specifies the MIME type of the contents of a string value, as described in [ RFC2046 ].	optional	`string` (e.g., `image/png`, or `audio/mpeg` )

Note

The length of a string (i.e., minLength and maxLength ) is defined as the number of Unicode code points, as defined by [ RFC8259 ]. Note that some user-perceived characters are composed of more than one Unicode code point. Arbitrary index values might not fall on these grapheme boundaries, so truncation according to maxLength might alter the appearance or meaning of the string.

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.

This specification provides a selection of well-established security mechanisms that are directly built into protocols eligible as Protocol Bindings for W3C WoT or are widely in use with those protocols. The current set of HTTP security schemes is partly based on OpenAPI 3.0.1 (see also [ OPENAPI ]). However while the HTTP security schemes, Vocabulary , and syntax given in this specification share many similarities with OpenAPI, they are not compatible.

Generally, security schemes require some form of secure transport to be effective, such as TLS or DTLS. Requirements for the use of secure transport are given in Section 10. Security Considerations in this document and in the Security Considerations section of [ wot-architecture11 ].

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 object or array schema (consequently the mechanism is not applicable to simple types). 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).

If multiple parameters are needed for a security scheme, repeat the security scheme definition for each parameter and combine them using a combo security scheme and allOf. In some cases parameters may not actually be secret but a user may wish to leave them out of the TD to help protect privacy. As an example of this, some security mechanisms require both a client identifier and a secret key. In theory, the client identifier is public however it may be hard to update and pose a tracking risk. In such a case it can be provided as an additional security parameter so it does not appear in the TD.

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

Table 16 Vocabulary Terms in SecurityScheme Level
Vocabulary term	Description	Assignment	Type
`@type`	JSON-LD keyword to label the object with semantic tags (or types).	optional	`string` or Array of `string`
`description`	Provides additional (human-readable) information based on a default language.	optional	`string`
`descriptions`	Can be used to support (human-readable) information in different languages. Also see MultiLanguage .	optional	Map of `MultiLanguage`
`proxy`	URI of the proxy server this security configuration provides access to. If not given, the corresponding security configuration is for the endpoint.	optional	`anyURI`
`scheme`	Identification of the security mechanism being configured.	mandatory	`string` (e.g., `nosec`,`combo`,`basic`,`digest`,`bearer`,`psk`,`oauth2`,`apikey`, or `auto` )

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 vocabulary terms 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.

Table 17 Vocabulary Terms in ComboSecurityScheme Level
Vocabulary term	Description	Assignment	Type
`oneOf`	Array of two or more strings identifying other named security scheme definitions, any one of which, when satisfied, will allow access. Only one may be chosen for use.	mandatory	Array of `string`
`allOf`	Array of two or more strings identifying other named security scheme definitions, all of which must be satisfied for access.	mandatory	Array of `string`

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

Table 18 Vocabulary Terms in BasicSecurityScheme Level
Vocabulary term	Description	Assignment	Type
`name`	Name for query, header, cookie, or uri parameters.	optional	`string`
`in`	Specifies the location of security authentication information.	with default	`string` (one of `header`,`query`,`body`,`cookie`, or `auto` )

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.

Table 19 Vocabulary Terms in DigestSecurityScheme Level
Vocabulary term	Description	Assignment	Type
`name`	Name for query, header, cookie, or uri parameters.	optional	`string`
`in`	Specifies the location of security authentication information.	with default	`string` (one of `header`,`query`,`body`,`cookie`, or `auto` )
`qop`	Quality of protection.	with default	`string` (one of `auth`, or `auth-int` )

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.

Table 20 Vocabulary Terms in APIKeySecurityScheme Level
Vocabulary term	Description	Assignment	Type
`name`	Name for query, header, cookie, or uri parameters.	optional	`string`
`in`	Specifies the location of security authentication information.	with default	`string` (one of `header`,`query`,`body`,`cookie`,`uri`, or `auto` )

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 .

Table 21 Vocabulary Terms in BearerSecurityScheme Level
Vocabulary term	Description	Assignment	Type
`authorization`	URI of the authorization server.	optional	`anyURI`
`name`	Name for query, header, cookie, or uri parameters.	optional	`string`
`alg`	Encoding, encryption, or digest algorithm.	with default	`string` (e.g., `ES256`, or `ES512-256` )
`format`	Specifies format of security authentication information.	with default	`string` (e.g., `jwt`,`cwt`,`jwe`, or `jws` )
`in`	Specifies the location of security authentication information.	with default	`string` (one of `header`,`query`,`body`,`cookie`, or `auto` )

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.

Table 22 Vocabulary Terms in PSKSecurityScheme Level
Vocabulary term	Description	Assignment	Type
`identity`	Identifier providing information which can be used for selection or confirmation.	optional	`string`

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

Table 23 Vocabulary Terms in OAuth2SecurityScheme Level
Vocabulary term	Description	Assignment	Type
`authorization`	URI of the authorization server.	optional	`anyURI`
`token`	URI of the token server.	optional	`anyURI`
`refresh`	URI of the refresh server.	optional	`anyURI`
`scopes`	Set of authorization scope identifiers provided as an array. These are provided in tokens returned by an authorization server and associated with forms in order to identify what resources a client may access and how. The values associated with a form SHOULD be chosen from those defined in an `OAuth2SecurityScheme` active on that form.	optional	`string` or Array of `string`
`flow`	Authorization flow.	mandatory	`string` (e.g., `code`, or `client` )

For the code flow both authorization and token vocabulary terms MUST be included. For the client flow token vocabulary term MUST be included. For the client flow authorization vocabulary term MUST NOT be included. The mandatory elements for each flow are summarized in the following table:

Element	`code`	`client`
`authorization`	mandatory	omit
`token`	mandatory	mandatory
`refresh`	optional	optional

The present model provides a representation for (typed) Web links and Web forms exposed by a Thing . The Link class definition reflects a very common subset of the terms defined in Web Linking [ RFC8288 ]. The defined terms can be used, e.g., to describe the relation to another Thing such as a Lamp Thing is controlled by a Switch Thing . The Form class corresponds to a newly introduced form of hypermedia control to manipulate the state of Things (and other Web resources).

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.

Table 24 Vocabulary Terms in Link Level
Vocabulary term	Description	Assignment	Type
`href`	Target IRI of a link or submission target of a form.	mandatory	`anyURI`
`type`	Target attribute providing a hint indicating what the media type [ RFC2046 ] of the result of dereferencing the link should be.	optional	`string`
`rel`	A link relation type identifies the semantics of a link.	optional	`string`
`anchor`	Overrides the link context (by default the Thing itself identified by its `id` ) with the given URI or IRI.	optional	`anyURI`
`sizes`	Target attribute that specifies one or more sizes for the referenced icon. Only applicable for relation type "icon". The value pattern follows {Height}x{Width} (e.g., "16x16", "16x16 32x32").	optional	`string`
`hreflang`	The hreflang attribute specifies the language of a linked document. The value of this must be a valid language tag [ BCP47 ].	optional	`string` or Array of `string`

Note : hreflang type

The hreflang attribute is allowed to be a string or array in this version of the spec. Depending on the result of [ LINKSET-MEDIA-TYPES ] the values of hrefLang can be restricted to array only.

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.

Table 25 Best practice relation type table
Value	Occurrence	Explanation	Source of value origin
`icon`	0..*	Imports an icon associated to the Thing (e.g., for UI purposes).	IANA Link Relation
`service-doc`	0..*	Relation to a resource that provide (human-readable) documentation or descriptions.	IANA Link Relation
`alternate`	0..*	Point to alternative representation of the Thing (i.e. RDF-Turtle, human-readable HTML document, ...).	IANA Link Relation
`type`	0..1	Indicate that the Thing is an instance of the target resource such as to a Thing Model .	IANA Link Relation
`tm:extends`	0..1	Extends an existing definition of the target resource such as a Thing Model . Only applicable for Thing Model definitions.	W3C WoT Thing Model
`tm:submodel`	0..*	Used to compose one or multiple Thing Models . Only applicable for Thing Model definitions.	W3C WoT Thing Model
`manifest`	0..*	Point to the web app manifest of a web application which provides, e.g., a user interface with which a user can interact with the Thing (also see [ APPMANIFEST ]).	IANA Link Relation
`proxy-to`	0..*	Target resource provide the address of a proxy. Additional security metadata can be provided using the `proxy` field in a SecurityScheme .	W3C WoT Security and WoT Binding Template
`collection`	0..1	Points to a collections of Things .	IANA Link Relation
`item`	0..*	Points to a Thing that is member of the current Thing collections.	IANA Link Relation
`predecessor-version`	0..1	Points to a previous Thing Description or Thing Model version.	IANA Link Relation
`controlledBy`	0..*	Refers to a Thing that controls the context Thing .	W3C Thing Description

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.

Table 26 Vocabulary Terms in Form Level
Vocabulary term	Description	Assignment	Type
`href`	Target IRI of a link or submission target of a form.	mandatory	`anyURI`
`contentType`	Assign a content type based on a media type (e.g., `text/plain` ) and potential parameters (e.g., `charset=utf-8` ) for the media type [ RFC2046 ].	with default	`string`
`contentCoding`	Content coding values indicate an encoding transformation that has been or can be applied to a representation. Content codings are primarily used to allow a representation to be compressed or otherwise usefully transformed without losing the identity of its underlying media type and without loss of information. Examples of content coding include "gzip", "deflate", etc. .	optional	`string`
`security`	Set of security definition names, chosen from those defined in `securityDefinitions`. These must all be satisfied for access to resources.	optional	`string` or Array of `string`
`scopes`	Set of authorization scope identifiers provided as an array. These are provided in tokens returned by an authorization server and associated with forms in order to identify what resources a client may access and how. The values associated with a form SHOULD be chosen from those defined in an `OAuth2SecurityScheme` active on that form.	optional	`string` or Array of `string`
`response`	This optional term can be used if, e.g., the output communication metadata differ from input metadata (e.g., output contentType differ from the input contentType). The response name contains metadata that is only valid for the primary response messages.	optional	`ExpectedResponse`
`additionalResponses`	This optional term can be used if additional expected responses are possible, e.g. for error reporting. Each additional response needs to be distinguished from others in some way (for example, by specifying a protocol-specific error code), and may also have its own data schema.	optional	Array of `AdditionalExpectedResponse`
`subprotocol`	Indicates the exact mechanism by which an interaction will be accomplished for a given protocol when there are multiple options. For example, for HTTP and Events, it indicates which of several available mechanisms should be used for asynchronous notifications such as long polling ( `longpoll` ), WebSub [ websub ] ( `websub` ), Server-Sent Events ( `sse` ) [ html ] (also known as EventSource). Please note that there is no restriction on the subprotocol selection and other mechanisms can also be announced by this subprotocol term.	optional	`string` (e.g., `longpoll`,`websub`, or `sse` )
`op`	Indicates the semantic intention of performing the operation(s) described by the form. For example, the Property interaction allows get and set operations. The protocol binding may contain a form for the get operation and a different form for the set operation. The op attribute indicates which form is for which and allows the client to select the correct form for the operation required. op can be assigned one or more interaction verb(s) each representing a semantic intention of an operation.	with default	`string` or Array of `string` (one of `readproperty`,`writeproperty`,`observeproperty`,`unobserveproperty`,`invokeaction`,`queryaction`,`cancelaction`,`subscribeevent`,`unsubscribeevent`,`readallproperties`,`writeallproperties`,`readmultipleproperties`,`writemultipleproperties`,`observeallproperties`,`unobserveallproperties`,`subscribeallevents`,`unsubscribeallevents`, or `queryallactions` )

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.

Table 27 Well-known operation types
Operation Type	Description
readproperty	Identifies the read operation on Property Affordances to retrieve the corresponding data.
writeproperty	Identifies the write operation on Property Affordances to update the corresponding data.
observeproperty	Identifies the observe operation on Property Affordances to be notified with the new data when the Property is updated.
unobserveproperty	Identifies the unobserve operation on Property Affordances to stop the corresponding notifications.
invokeaction	Identifies the invoke operation on Action Affordances to perform the corresponding action.
queryaction	Identifies the querying operation on Action Affordances to get the status of the corresponding action.
cancelaction	Identifies the cancel operation on Action Affordances to cancel the ongoing corresponding action.
subscribeevent	Identifies the subscribe operation on Event Affordances to be notified by the Thing when the event occurs.
unsubscribeevent	Identifies the unsubscribe operation on Event Affordances to stop the corresponding notifications.
readallproperties	Identifies the readallproperties operation on a Thing to retrieve the data of all Properties in a single interaction.
writeallproperties	Identifies the writeallproperties operation on a Thing to update the data of all writable Properties in a single interaction.
readmultipleproperties	Identifies the readmultipleproperties operation on a Thing to retrieve the data of selected Properties in a single interaction.
writemultipleproperties	Identifies the writemultipleproperties operation on a Thing to update the data of selected writable Properties in a single interaction.
observeallproperties	Identifies the observeallproperties operation on Properties to be notified with new data when any Property is updated.
unobserveallproperties	Identifies the unobserveallproperties operation on Properties to stop notifications from all Properties in a single interaction.
queryallactions	Identifies the queryallactions operation on a Thing to get the status of all Actions in a single interaction.
subscribeallevents	Identifies the subscribeallevents operation on Events to subscribe to notifications from all Events in a single interaction.
unsubscribeallevents	Identifies the unsubscribeallevents operation on Events to unsubscribe from notifications from all Events in a single interaction.

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 .

This section is non-normative.

Protocols that can be used with TDs follow request-response or eventing mechanisms. The Data Schema of an affordance generally correlates with the op keywords used in forms. The table below informatively summarizes the available data schema related terms with the op keywords.

Consumer to Thing applies for messages sent by the Consumer to the Thing, such as the value for writing a property.
Thing to Consumer applies for messages sent by the Thing to the Consumer, such as the value of a property value as the result of reading a property.
In case that there is no correlation with the data schema and the operation, it implies that no payload is required for executing the operation or no payload is expected as a result of the operation.

Table 28 Mapping op Values to Data Schemas
Operation Type	Consumer to Thing DataSchema Correlation	Thing to Consumer DataSchema Correlation
readproperty	No correlation.	All fields in the Property Affordance without `"writeOnly":true`.
writeproperty	All fields in the Property Affordance without `"readOnly":true`.	No correlation. `additionalResponses` can be used in the form level.
observeproperty	No correlation.	All fields in the Property Affordance without `"writeOnly":true`.
unobserveproperty	No correlation.	No correlation.
invokeaction	Value of the `input` key.	Value of the `output` key.
queryaction	No correlation.	No correlation. `additionalResponses` can be used in the form level.
cancelaction	No correlation.	No correlation. `additionalResponses` can be used in the form level.
subscribeevent	Value of the `subscription` key with all fields without `"readOnly":true`	Value of the `subscription` key with all fields without `"writeOnly":true`
unsubscribeevent	Value of the `subscription` key with all fields without `"readOnly":true`	Value of the `subscription` key with all fields without `"writeOnly":true`

Note : writeproperty and observeproperty relationship

Writing to a property does not necessarily mean that a new value will be sent to the Consumer observing the property. It depends on the protocol and implementation.

Note : Further Data Schemas mappings

Further specification of how to map operations to data schemas, as well as mapping meta operations such as readallproperties can be found in the respective protocol specification of the [ WOT-BINDING-TEMPLATES ].

The optional response name-value pair can be used to provide metadata for the expected response message. With the core vocabulary, it only includes content type information, but TD Context Extensions could be applied. If no response name-value pair is provided, it MUST be assumed that the content type of the response is equal to the content type assigned to the Form instance. Note that contentType within an ExpectedResponse Class does not have a Default Value . For instance, if the value of the content type of the form is application/xml the assumed value of the content type of the response will be also application/xml.

In some cases additional responses might be possible. One example of this is error responses but in some cases there might also be additional successful responses. In this case, the response name-value pair is still used for the primary response but additionalResponses may also be provided, whose value is an array of AdditionalExpectedResponse objects. Each additional response must be distinguished in some way from the primary response, either by contentType or by protocol-specific settings such as error code header values. Each additional response may also have a data schema which can differ from the normal output data schema for the interaction.

In some use cases, input and output data might be represented in a different form, for instance an Action that accepts JSON, but returns an image. In such a case, the optional response name-value pair can describe the content type of the expected response. If the content type of the expected response differs from the content type of the form, the Form instance MUST include a name-value pair with the name response. For instance, an ActionAffordance could only accept application/json for its input data, while it will respond with an image/jpeg content type for its output data. In that case the content types differ and the response name-value pair has to be used to provide response content type ( image/jpeg ) information to the Consumer .

Similar considerations apply to additional responses, although in this case the contentType is optional if it is the same as the input content Type (e.g. JSON). If the content type of an additional expected response differs from the content type of the form, the Form instance MUST include an entry in the array associated with the name additionalResponses that includes a value for the name contentType. If the data schema of an additional expected response differs from the output data schema of the interaction, the Form instance MUST include an entry in the array associated with the name additionalResponses that includes a value for the name schema.

The different cases on the variation of request and response are explained above. The tables at C. contentType usage in Thing Descriptions summarize these cases in a concise manner.

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

Table 29 Vocabulary Terms in ExpectedResponse Level
Vocabulary term	Description	Assignment	Type
`contentType`	Assign a content type based on a media type (e.g., `text/plain` ) and potential parameters (e.g., `charset=utf-8` ) for the media type [ RFC2046 ].	mandatory	`string`

Communication metadata describing the expected response message for additional responses.

Table 30 Vocabulary Terms in AdditionalExpectedResponse Level
Vocabulary term	Description	Assignment	Type
`success`	Signals if an additional response should not be considered an error.	with default	`boolean`
`contentType`	Assign a content type based on a media type (e.g., `text/plain` ) and potential parameters (e.g., `charset=utf-8` ) for the media type [ RFC2046 ].	with default	`string`
`schema`	Used to define the output data schema for an additional response if it differs from the default output data schema. Rather than a `DataSchema` object, the name of a previous definition given in a `schemaDefinitions` map must be used.	optional	`string`

When assignments in a TD are missing, a TD Processor MUST follow the Default Value assignments expressed in the table of Default Value Definitions .

The following table gives all Default Values defined in the TD Information Model .

Table 31 Default values of vocabulary terms that are used when the terms are not present in a TD
Class	Vocabulary Term	Default Value	Comment
`PropertyAffordance`	`readOnly`	`false`	The default value for this vocabulary term applies only to the `PropertyAffordance` level definition. In other contexts, such as `DataSchema` definitions, the vocabulary term is optional.
`PropertyAffordance`	`writeOnly`	`false`	The default value for this vocabulary term applies only to the `PropertyAffordance` level definition. In other contexts, such as `DataSchema` definitions, the vocabulary term is optional.
`PropertyAffordance`	`observable`	`false`
`ActionAffordance`	`safe`	`false`
`ActionAffordance`	`idempotent`	`false`
`AdditionalExpectedResponse`	`success`	`false`
`AdditionalExpectedResponse`	`contentType`	value of the `contentType` of the `Form` element it belongs to.
`Form`	`contentType`	`application/json`
`Form`	`op`	Array of `string` with the elements `readproperty` and `writeproperty` when `readOnly` and `writeOnly` are set to `false` or Array of `string` with the element `readproperty` when `readOnly` is set to `true` or Array of `string` with the element `writeproperty` when `writeOnly` is set to `true`.	If defined within an instance of `PropertyAffordance`
`Form`	`op`	`invokeaction`	If defined within an instance of `ActionAffordance`
`Form`	`op`	Array of `string` with the elements `subscribeevent` and `unsubscribeevent`	If defined within an instance of `EventAffordance`
`BasicSecurityScheme`	`in`	`header`
`DigestSecurityScheme`	`in`	`header`
`DigestSecurityScheme`	`qop`	`auth`
`APIKeySecurityScheme`	`in`	`query`
`BearerSecurityScheme`	`in`	`header`
`BearerSecurityScheme`	`alg`	`ES256`
`BearerSecurityScheme`	`format`	`jwt`

WoT Thing Descriptions represent Things and are modeled and structured based on 5. TD Information Model . This section defines a JSON-based representation format for Things , a serialization of instances of the Class Thing defined by the TD Information Model .

A TD Processor MUST be able to serialize Thing Descriptions into the JSON format [ RFC8259 ] and/or deserialize Thing Descriptions from that format, according to the rules noted in 6.1 Mapping to JSON Types and 6.3 Information Model Serialization .

The JSON serialization of the TD Information Model is aligned with the syntax of JSON-LD 1.1 [ json-ld11 ] in order to streamline semantic evaluation. Hence, the TD representation format can be processed either as raw JSON or with a JSON-LD 1.1 processor (for details about semantic processing, please refer to D. JSON-LD Context Usage and the documentation under the namespace IRIs, e.g., https://www.w3.org/2019/wot/td ).

In order to support interoperable internationalization, TDs MUST be serialized according to the requirements defined in Section 8.1 of RFC8259 [ RFC8259 ] for open ecosystems. In summary, this requires the following:

TDs MUST be encoded using UTF-8 [ RFC3629 ].
Implementations MUST NOT add a byte order mark (U+FEFF) to the beginning of a TD document.
TD Processors MAY ignore the presence of a byte order mark rather than treating it as an error.

The TD Information Model is constructed, so that there is an easy mapping between model Objects and JSON types. Every Class instances maps to a JSON object, where each name-value pair of the Class instance is a member of the JSON object.

Every Simple Type mentioned in 5.3 Class Definitions (i.e., string,anyURI,dateTime,integer,unsignedInt,double, and boolean ) maps to a primitive JSON type (string, number, boolean), as per the rules listed below. These rules apply to values in name-value pairs:

Values that are of type string or anyURI MUST be serialized as JSON strings.
Values that are of type dateTime MUST be serialized as JSON strings following the "date-time" format specified by [ RFC3339 ]. Examples would include 2019-05-24T13:12:45Z and 2015-07-11T09:32:26+08:00. Values that are of type dateTime SHOULD use the literal Z representing the UTC time zone instead of an offset.
Values that are of type integer or unsignedInt MUST be serialized as JSON numbers without a fraction or exponent part.
Values that are of type double MUST be serialized as JSON number.
Values that are of type boolean MUST be serialized as JSON boolean.

Every complex type of the TD Information Model (i.e., Arrays , Maps , and Class instances) maps to a structured JSON type (array and object), as per the rules listed below:

A value of type Array MUST be serialized as JSON array, with each value of the name-value pairs as element of the JSON array ordered by the numeric name of the pair.
A value of type Map MUST be serialized as a JSON object, with each name-value pair as member of the JSON object.
A Class instance MUST be serialized as a JSON object, following the detailed rules given individually in 6.3 Information Model Serialization .

A Thing Description serialization may omit Vocabulary Term for which Default Values are defined, as listed in the table given in 5.4 Default Value Definitions .

The following example shows the TD instance from Example 1 with a checkbox to also include the members with Default Values (=checkbox checked). These members can be omitted (=checkbox unchecked) to simplify the TD serialization. Note that a TD Processor interprets these omitted members identically as if they were explicitly present with a given Default Value .

Example 4

TD with Default Values that can be omitted

with Default Values

{    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    "id": 
"hljs-string">"urn:uuid:014139c9-b267-4db5-9c61-cc2d2bfc217d",
    "title": 
"hljs-string">"MyLampThing",
    "securityDefinitions": {        "basic_sc": {            "scheme": 
"hljs-string">"basic"
        }
    },
    "security": 
"hljs-string">"basic_sc",
    "properties": {        "status": {            "type": 
"hljs-string">"string",
            "forms": [{                "href": 
"hljs-string">"https://mylamp.example.com/status"
            }]
        }
    },
    "actions": {        "toggle": {            "forms": [{                "href": 
"hljs-string">"https://mylamp.example.com/toggle"
            }]
        }
    },
    "events": {        "overheating": {            "data": {                "type": 
"hljs-string">"string"
            },
            "forms": [{                "href": 
"hljs-string">"https://mylamp.example.com/oh",
                
"hljs-attr">"subprotocol": "longpoll"
            }]
        }
    }
}

{    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    "id": 
"hljs-string">"urn:uuid:014139c9-b267-4db5-9c61-cc2d2bfc217d",
    "title": 
"hljs-string">"MyLampThing",
    "securityDefinitions": {        "basic_sc": {            "scheme": 
"hljs-string">"basic",
            "in": 
"hljs-string">"header"
        }
    },
    "security": 
"hljs-string">"basic_sc",
    "properties": {        "status": {            "type": 
"hljs-string">"string",
            "readOnly": 
"hljs-literal">false,
            
"hljs-attr">"writeOnly": false,
            
"hljs-attr">"observable": false,
            "forms": [{                "op": [                    
"hljs-string">"readproperty",
                    
"hljs-string">"writeproperty"
                ],
                "href": 
"hljs-string">"https://mylamp.example.com/status",
                
"hljs-attr">"contentType": "application/json"
            }]
        }
    },
    "actions": {        "toggle": {            "safe": 
"hljs-literal">false,
            
"hljs-attr">"idempotent": false,
            "forms": [{                "op": 
"hljs-string">"invokeaction",
                "href": 
"hljs-string">"https://mylamp.example.com/toggle",
                
"hljs-attr">"contentType": "application/json"
            }]
        }
    },
    "events": {        "overheating": {            "data": {                "type": 
"hljs-string">"string",
                
"hljs-attr">"readOnly": false,
                
"hljs-attr">"writeOnly": false
            },
            "forms": [{                "op": 
"hljs-string">"subscribeevent",
                "href": 
"hljs-string">"https://mylamp.example.com/oh",
                
"hljs-attr">"contentType": "application/json",
                
"hljs-attr">"subprotocol": "longpoll"
            }]
        }
    }
}

Please note that, depending on the Protocol Binding used, additional protocol-specific Vocabulary Terms may apply. They may also have associated Default Values , and hence can also be omitted as explained in this subsection. Further information can be found in 8.3 Protocol Bindings .

A Thing Description is a data structure rooted at an Object of type Thing. In turn, a JSON serialization of the Thing Description is a JSON object, which is the root of a syntax tree constructed from the TD Information Model .

The root element of a TD Serialization MUST be a JSON object that includes a member with the name @context and a value of type string or array that equals or respectively contains https://www.w3.org/2022/wot/td/v1.1.

In general, this URI is used to identify the TD representation format version defined by this specification. For JSON-LD processing [ json-ld11 ], this URI specifies the Thing Description context file. An @context of type array indicates TD Context Extensions (see 7. TD Context Extensions for details).

Example 5

{      "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    // ...
}

All name-value pairs of an instance of Thing, where the name is a Vocabulary Term in the Signature of Thing, MUST be serialized as JSON members of the root object.

A TD snippet for a serialized root object including all mandatory and optional members is given below:

Example 6 : Sample of Thing serializations

{    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    "@type": 
"hljs-string">"Thing",
    "id": 
"hljs-string">"urn:uuid:1b37933b-3212-4dad-9c2c-74c6042c3e2b",
    "title": 
"hljs-string">"MyThing",
    "titles": {
"hljs-comment">/*...*/},
    "description": 
"hljs-string">"Human readable information.",
    "descriptions": {
"hljs-comment">/*...*/},
    "support": 
"hljs-string">"mailto:support@example.com",
    "version": {
"hljs-comment">/*...*/},
    "created": 
"hljs-string">"2018-11-14T19:10:23.824Z",
    "modified": 
"hljs-string">"2019-06-01T09:12:43.124Z",
    
"hljs-attr">"securityDefinitions": {/*...*/},
    "security": 
"hljs-comment">/*...*/,
    "base": 
"hljs-string">"https://servient.example.com/",
    "properties": {
"hljs-comment">/*...*/},
    "actions": {
"hljs-comment">/*...*/},
    "events": {
"hljs-comment">/*...*/},
    "links": [...],    "forms": [...]
}

All values assigned to version,securityDefinitions,descriptions,schemaDefinitions,uriVariables,properties,actions, and events in an instance of the Class Thing MUST be serialized as JSON objects.

All values assigned to links, and forms in an instance of the Class Thing MUST be serialized as JSON arrays containing JSON objects as defined in 6.3.8 links and 6.3.9 forms, respectively.

The value assigned to security in an instance of Class Thing MUST be serialized as JSON string or as JSON array whose elements are JSON strings.

JSON members named title and description are used within a TD document to provide human-readable metadata. They can be used as comments for developers inspecting a TD document or as display texts for user interface.

As defined in 5.3.1.1 Thing, the base text direction used to display human-readable metadata can either be estimated using heuristics such as the first-strong rule or inferred from language information. In TD documents the default language is defined by a value assigned to @language in the @context, and this, along with a script subtag if necessary, can be used to determine a base text direction. However, when interpreting human-readable text, each human-readable string value MUST be processed independently. In other words, a TD Processor cannot carry forward changes in direction from one string to another, or infer direction for one string from another one elsewhere in the TD.

A TD snippet using title and description is shown below. The default language is set to en through the definition of the @language member within a JSON object in the @context array.

Example 7

{    "@context": [        
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
        { "@language": "en" }
    ],
    "title": 
"hljs-string">"MyThing",
    "description": 
"hljs-string">"Human readable information.",
    // ...    "properties": {        "on": {            "title": 
"hljs-string">"On/Off",
            "type": 
"hljs-string">"boolean",
            "forms": [...]
        },
        "status": {            "title": 
"hljs-string">"Status",
            "type": 
"hljs-string">"object",
            // ...            "forms": [...]
        }
    },
    // ...
}

Strings on the Web [ STRING-META ] recommends the use of metadata to determine the base direction of string values. Given that the Thing Description format is based on JSON-LD 1.1 [ json-ld11 ], @direction with the string values "ltr","rtl" and null value null MAY be used inside the @context to indicate the default text direction for the human readable strings in the entire TD document. When metadata such as @direction is not present, TD Consumers SHOULD use first-strong detection as a fallback. For the MultiLanguage Map , TD Consumers MAY infer the base direction from the language tag of the individual strings. The example below illustrates the use of the @direction term. See [ json-ld11 ] and [ string-meta ] for more detailed information.

Example 8

{     "@context": [         
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
         { 
           "@language": 
"hljs-string">"ar-EG",
           
"hljs-attr">"@direction": "rtl" 
         }
     ],
     "title": 
"hljs-string">"شيء يخصني يقيس درجة الحرارة",
     "description": 
"hljs-string">"شيء يقيس درجة الحرارة و يظهر حالته",
     // ...     "properties": {         "temp": {             "title": 
"hljs-string">"درجة الحرارة",
             "type": 
"hljs-string">"boolean",
             "forms": [...]
         },
         "status": {             "title": 
"hljs-string">"حالة",
             "type": 
"hljs-string">"object",
             // ...             "forms": [...]
         }
     },
     // ...
}

The JSON members named titles and descriptions are used within the TD document to provide human-readable metadata in multiple languages within a single TD document. All name-value pairs of a MultiLanguage Map MUST be serialized as members of a JSON object, where the name is a valid language tag as defined by [ BCP47 ] (also see W3C I18N Glossary ) and the value is a human-readable string in the language indicated by the tag. See 5.3.1.7 MultiLanguage for details. All MultiLanguage object within a TD document SHOULD contain the same set of language members.

A TD snippet using titles and descriptions at different levels is given below:

Example 9

{    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    "title": 
"hljs-string">"MyThing",
    "titles": {        "en": 
"hljs-string">"MyThing",
        "de": 
"hljs-string">"MeinDing",
        "ja": 
"hljs-string">"私の物",
        "zh-Hans": 
"hljs-string">"我的东西", 
        "zh-Hant": 
"hljs-string">"我的東西"
    },
    "descriptions": {        "en": 
"hljs-string">"Human readable information.",
        "de": 
"hljs-string">"Menschenlesbare Informationen.",
        "ja": 
"hljs-string">"人間が読むことができる情報",
        "zh-Hans": 
"hljs-string">"人们可阅读的信息", 
        "zh-Hant": 
"hljs-string">"人們可閱讀的資訊"
    },
    // ...    "properties": {        "on": {            "titles": {                "en": 
"hljs-string">"On/Off",
                "de": 
"hljs-string">"An/Aus",
                "ja": 
"hljs-string">"オンオフ",
                
"hljs-attr">"zh-Hans": "开关",
                
"hljs-attr">"zh-Hant": "開關" },
            "type": 
"hljs-string">"boolean",
            "forms": [...]
        },
        "status": {            "titles": {                "en": 
"hljs-string">"Status",
                "de": 
"hljs-string">"Zustand",
                "ja": 
"hljs-string">"状態",
                
"hljs-attr">"zh-Hans": "状态",
                
"hljs-attr">"zh-Hant": "狀態" },
            "type": 
"hljs-string">"object",
            // ...            "forms": [...]
        }
    },
    // ...
}

TD instances may also combine the use of title and description with titles and descriptions. When title and titles or description and descriptions are present within the same JSON object, the values of title and description MAY be seen as the default text. When title and titles or description and descriptions are present in a TD document, each title and description member SHOULD have a corresponding titles and descriptions member, respectively. The language of the default text is indicated by the default language, which is usually set by the creator of the Thing Description instance.

Example 10

{    "@context": [        
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
        { "@language": "de" }
    ],
    "title": 
"hljs-string">"MeinDing",
    "titles": {        "en": 
"hljs-string">"MyThing",
        "de": 
"hljs-string">"MeinDing",
        "ja": 
"hljs-string">"私の物",
        "zh-Hans": 
"hljs-string">"我的东西", 
        "zh-Hant": 
"hljs-string">"我的東西"
    },
    "description": 
"hljs-string">"Menschenlesbare Informationen.",
    "descriptions": {        "en": 
"hljs-string">"Human readable information.",
        "de": 
"hljs-string">"Menschenlesbare Informationen.",
        "ja": 
"hljs-string">"人間が読むことができる情報",
        "zh-Hans": 
"hljs-string">"人们可阅读的信息", 
        "zh-Hant": 
"hljs-string">"人們可閱讀的資訊"
    },
    // ...    "properties": {        "on": {            "title": 
"hljs-string">"An/Aus",
            "titles": {                "en": 
"hljs-string">"On/Off",
                "de": 
"hljs-string">"An/Aus",
                "ja": 
"hljs-string">"オンオフ",
                
"hljs-attr">"zh-Hans": "开关",
                
"hljs-attr">"zh-Hant": "開關" },
            "type": 
"hljs-string">"boolean",
            "forms": [...]
        },
        "status": {            "title": 
"hljs-string">"Zustand",
            "titles": {                "en": 
"hljs-string">"Status",
                "de": 
"hljs-string">"Zustand",
                "ja": 
"hljs-string">"状態",
                
"hljs-attr">"zh-Hans": "状态",
                
"hljs-attr">"zh-Hant": "狀態" },
            "type": 
"hljs-string">"object",
            // ...            "forms": [...]
        }
    },
    // ...
}

Another possibility to set the default language is through a language negotiation mechanism, such as the Accept-Language header field of HTTP. In cases where the default language has been negotiated, an @language member MUST be present to indicate the result of the negotiation and the corresponding default language of the returned content. When the default language has been negotiated successfully, TD documents SHOULD include the appropriate matching values for the members title and description in preference to MultiLanguage objects in titles and descriptions members. Note however that Things MAY choose to not support such dynamically-generated TDs nor to support language negotiation (e.g., because of resource constraints).

There is no guarantee that strings in TDs will be displayed in an HTML rendering context. In fact, to mitigate the XSS security risk described in 10.5 Script Injection , HTML tags embedded in strings sourced from TDs should be sanitized (and so not interpreted as HTML) in applications embedding these strings in web pages or web applications. Therefore HTML embedded in strings is not an appropriate mechanism for specifying text rendering direction.

All name-value pairs of an instance of VersionInfo, where the name is a Vocabulary Term included in the Signature of VersionInfo, MUST be serialized as JSON members with the Vocabulary Term as name.

A TD snippet of a version information object is given below:

Example 11

{    // ...    "version": { 
"hljs-attr">"instance": "1.2.1" },
    // ...
}

The version member is intended as container for additional application- and/or device-specific version information based on TD Context Extensions . See 7.1 Semantic Annotations for details.

In a Thing instance, the value assigned to securityDefinitions is a Map of instances of SecurityScheme. All name-value pairs of a Map of SecurityScheme instances MUST be serialized as members of the JSON object that results from serializing the Map ; the name of a pair MUST be serialized as a JSON string and the value of the pair, an instance of SecurityScheme, MUST be serialized as a JSON object.

All name-value pairs of an instance of one of the Subclasses of SecurityScheme, where the name is a Vocabulary Term included in the Signature of that Subclass or in the Signature of SecurityScheme, MUST be serialized as members of the JSON object that results from serializing the SecurityScheme Subclass 's instance, with the Vocabulary Term as name.

The following TD snippet shows a simple security configuration specifying basic username/password authentication in the header. The value given for in is actually the Default Value ( header ) and could be omitted. A named security configuration ( basic_sc ) is given in the securityDefinitions map. In this example, that definition is activated by including its JSON name in the security member.

Example 12

{    // ...    "securityDefinitions": {        "basic_sc": {            "scheme": 
"hljs-string">"basic",
            "in": 
"hljs-string">"header"
        }
    },
    "security": 
"hljs-string">"basic_sc",
    // ...
}

Security configuration in the TD is mandatory. At least one security definition MUST be activated through the security member at the Thing level (i.e., in the TD root object). This configuration can be seen as the default security mechanism required to interact with the Thing . Security definitions MAY also be activated at the level of the form elements by including a security member in form objects, which overrides (i.e., completely replace) all definitions activated at the Thing level .

The nosec security scheme is provided for the case that no security is needed. The minimal security configuration for a Thing is activation of the nosec security scheme at the Thing level , as shown in the following example:

Example 13

{    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    "id": 
"hljs-string">"urn:uuid:e9ecb6ad-cd4c-481b-96ce-5b4c57ddb844",
    "title": 
"hljs-string">"MyThing",
    "description": 
"hljs-string">"Human readable information.",
    "support": 
"hljs-string">"https://servient.example.com/contact",
    
"hljs-attr">"securityDefinitions": { "nosec_sc": { "scheme": "nosec" }},
    "security": 
"hljs-string">"nosec_sc",
    "properties": {
"hljs-comment">/*...*/},
    "actions": {
"hljs-comment">/*...*/},
    "events": {
"hljs-comment">/*...*/},
    "links": [
"hljs-comment">/*...*/]
}

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.

Example 14

{    // ...    "securityDefinitions": {        "basic_sc": {
"hljs-attr">"scheme": "basic"},
        "nosec_sc": {
"hljs-attr">"scheme": "nosec"}
    },
    "security": 
"hljs-string">"basic_sc",
    // ...    "properties": {        "status": {            // ...            "forms": [{                "href": 
"hljs-string">"https://mylamp.example.com/status"
            }]
        }
    },
    "actions": {        "toggle": {            // ...            "forms": [{                "href": 
"hljs-string">"https://mylamp.example.com/toggle"
            }]
        }
    },
    "events": {        "overheating": {            // ...            "forms": [{                "href": 
"hljs-string">"https://mylamp.example.com/oh",
                
"hljs-attr">"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.

Example 15

{    // ...    "securityDefinitions": {        "proxy_sc": {            "scheme": 
"hljs-string">"digest",
            "proxy": 
"hljs-string">"https://portal.example.com/"
        },
        "bearer_sc": {            "scheme": 
"hljs-string">"bearer",
            "in": 
"hljs-string">"header",
            "format": 
"hljs-string">"jwt",
            "alg": 
"hljs-string">"ES256",
            
"hljs-attr">"authorization": "https://servient.example.com:8443/"
        }
    },
    "security": [
"hljs-string">"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:

Example 16

{    // ...    "securityDefinitions": {        "proxy_sc": {            "scheme": 
"hljs-string">"digest",
            "proxy": 
"hljs-string">"https://portal.example.com/"
        },
        "bearer_sc": {            "scheme": 
"hljs-string">"bearer",
            "in": 
"hljs-string">"header",
            "format": 
"hljs-string">"jwt",
            "alg": 
"hljs-string">"ES256",
            
"hljs-attr">"authorization": "https://servient.example.com:8443/"
        },
        "combo_sc": {            "scheme": 
"hljs-string">"combo",
            "allOf": [
"hljs-string">"proxy_sc", "bearer_sc"]
        }
    },
    "security": 
"hljs-string">"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.

Example 17

{    // ...    "securityDefinitions": {        "basic_sc": { 
"hljs-attr">"scheme": "basic" },
        "digest_sc": { 
"hljs-attr">"scheme": "digest" },
        "bearer_sc": { 
"hljs-attr">"scheme": "bearer" }
    },
    "security": 
"hljs-string">"basic_sc",
    // ...    "properties": {        "status": {            // ...            "forms": [{                "href": 
"hljs-string">"https://mylamp.example.com/status"
            }, {
                "href": 
"hljs-string">"https://mylamp.example.com/status",
                
"hljs-attr">"security": "digest_sc"
            }, {
                "href": 
"hljs-string">"https://mylamp.example.com/status",
                
"hljs-attr">"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.

Example 18

{    // ...    "securityDefinitions": {        "basic_sc": { 
"hljs-attr">"scheme": "basic" },
        "digest_sc": { 
"hljs-attr">"scheme": "digest" },
        "bearer_sc": { 
"hljs-attr">"scheme": "bearer" },
        "combo_sc": {             "scheme": 
"hljs-string">"combo", 
            "oneOf": [ 
"hljs-string">"basic_sc", "digest_sc", "bearer_sc" ] 
        }
    },
    "security": 
"hljs-string">"combo_sc",
    // ...    "properties": {        "status": {            // ...            "forms": [{                "href": 
"hljs-string">"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.

Example 19

{    // ...    "securityDefinitions": {        "oauth2_sc": {            "scheme": 
"hljs-string">"oauth2",
            "flow": 
"hljs-string">"client",
            "token": 
"hljs-string">"https://example.com/token",
            "scopes": [
"hljs-string">"limited", "special"]
        }
    },
    "security": 
"hljs-string">"oauth2_sc",
    // ...    "properties": {        "status": {            // ...            "forms": [{                "href": 
"hljs-string">"https://scopes.example.com/status",
                
"hljs-attr">"scopes": ["limited"]
            }]
        }
    },
    "actions": {        "configure": {            // ...            "forms": [{                "href": 
"hljs-string">"https://scopes.example.com/configure",
                
"hljs-attr">"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.

Example 20

{    // ...    "securityDefinitions": {        "apikey_key": {            "scheme": 
"hljs-string">"apikey",
            "in": 
"hljs-string">"uri",
            "name": 
"hljs-string">"adminKey"
        }
    },
    "security": 
"hljs-string">"apikey_key",
    "properties": {        "status": {            // ...            "forms": [{                "href": 
"hljs-string">"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:

Example 21

{    // ...    "securityDefinitions": {        "apikey_key": {            "scheme": 
"hljs-string">"apikey",
            "in": 
"hljs-string">"uri",
            "name": 
"hljs-string">"secKey"
        },
        "apikey_id": {            "scheme": 
"hljs-string">"apikey",
            "in": 
"hljs-string">"uri",
            "name": 
"hljs-string">"secClientID"
        },
        "apikey_combo": {            "scheme": 
"hljs-string">"combo",
            "allOf": [
"hljs-string">"apikey_key","apikey_id"]
        }
    },
    "security": 
"hljs-string">"apikey_combo",
    // ...    "properties": {        "status": {            // ...            "forms": [{                "href": 
"hljs-string">"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.

Example 22

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

However, it is rather annoying and redundant to add the security information to every data schema. It is possible to simplify this example by using the feature that the location referenced by a JSON pointer in a


body

location will be automatically inserted if it does not exist. In this case the above example can be simplified to the following. Note that in fact a data schema will effectively be created for the actions

on

and

off

to hold just the security information.

Example 23

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

The value assigned to properties in a Thing instance is a Map of instances of PropertyAffordance. All name-value pairs of a Map of PropertyAffordance instances MUST be serialized as members of the JSON object that results from serializing the Map ; the name of a pair MUST be serialized as a JSON string and the value of the pair, an instance of PropertyAffordance, MUST be serialized as a JSON object.

All name-value pairs of an instance of PropertyAffordance, where the name is a Vocabulary Term included in (one of) the Signatures of PropertyAffordance,InteractionAffordance, or DataSchema, MUST be serialized as members of the JSON object that results from serializing the PropertyAffordance instance, with the Vocabulary Term as name. See 6.3.10 Data Schemas for details on serializing DataSchema instances.

The value assigned to forms in an instance of PropertyAffordance MUST be serialized as a JSON array containing one or more JSON object serializations as defined in 6.3.9 forms.

A snippet for two Property affordances is given below:

Example 24 : Sample of Property serializations

{    // ...    "properties": {        "on": {            "type": 
"hljs-string">"boolean",
            "forms": [...]
        },
        "status": {            "type": 
"hljs-string">"object",
            "properties": {                "brightness": {                    
"hljs-attr">"type": "number",
                    
"hljs-attr">"minimum": 0.0,
                    
"hljs-attr">"maximum": 100.0
                },
                "rgb": {                    
"hljs-attr">"type": "array",
                    "items": {                        
"hljs-attr">"type": "number",
                        
"hljs-attr">"minimum": 0,
                        
"hljs-attr">"maximum": 255
                    },
                    
"hljs-attr">"minItems": 3,
                    
"hljs-attr">"maxItems": 3
                }
            },
            
"hljs-attr">"required": ["brightness", "rgb"],
            "forms": [...]
        }
    },
    // ...
}

In a Thing instance, the value assigned to actions is a Map of instances of ActionAffordance. All name-value pairs of a Map of ActionAffordance instances MUST be serialized as members of the JSON object that results from serializing the Map ; the name of a pair MUST be serialized as a JSON string and the value of the pair, an instance of ActionAffordance, MUST be serialized as a JSON object.

All name-value pairs of an instance of ActionAffordance, where the name is a Vocabulary Term included in (one of) the Signatures of ActionAffordance or InteractionAffordance, MUST be serialized as members of the JSON object that results from serializing the ActionAffordance instance, with the Vocabulary Term as name.

The values assigned to input and output in an instance of ActionAffordance MUST be serialized as JSON objects. They rely on the Class DataSchema, whose serialization is defined in 6.3.10 Data Schemas .

The value assigned to forms in an instance of ActionAffordance MUST be serialized as a JSON array containing one or more JSON object serializations as defined in 6.3.9 forms.

A TD snippet of an Action affordance is given below:

Example 25 : Sample of an Action serialization

{    // ...    "actions": {        "fade": {            "title": 
"hljs-string">"Fade in/out",
            
"hljs-attr">"description": "Smooth fade in and out animation.",
            "input": {                "type": 
"hljs-string">"object",
                "properties": {                    "from": {                        
"hljs-attr">"type": "integer",
                        
"hljs-attr">"minimum": 0,
                        
"hljs-attr">"maximum": 100
                    },
                    "to": {                        
"hljs-attr">"type": "integer",
                        
"hljs-attr">"minimum": 0,
                        
"hljs-attr">"maximum": 100
                    },
                    
"hljs-attr">"duration": {"type": "number"}
                },
                
"hljs-attr">"required": ["to","duration"]
            },
            "output": {
"hljs-attr">"type": "string"},
            "forms": [...]
        }
    },
    // ...
}

In a Thing instance, the value assigned to events is a map of instances of EventAffordance. All name-value pairs of a Map of EventAffordance instances MUST be serialized as members of the JSON object that results from serializing the Map ; the name of a pair MUST be serialized as a JSON string and the value of the pair, an instance of EventAffordance, MUST be serialized as a JSON object.

All name-value pairs of an instance of EventAffordance, where the name is a Vocabulary Term included in (one of) the Signatures of EventAffordance or InteractionAffordance, MUST be serialized as members of the JSON object that results from serializing the EventAffordance instance, with the Vocabulary Term as name.

The values assigned to subscription,data, and cancellation in an instance of EventAffordance MUST be serialized as JSON objects. They rely on the Class DataSchema, whose serialization is defined in 6.3.10 Data Schemas .

The value assigned to forms in an instance of EventAffordance MUST be serialized as a JSON array containing one or more JSON object serializations as defined in 6.3.9 forms.

A TD snippet of an Event object is given below:

Example 26 : Sample of an Event serialization

{    // ...    "events": {        "overheated": {            "data": {                "type": 
"hljs-string">"string"
            },
            "forms": [...]
        }
    },
    // ...
}

Event affordances have been defined in a flexible manner, in order to adopt existing (e.g., WebSub [ websub ]) or customer-oriented event mechanisms (e.g., Webhooks). For this reason, subscription and cancellation can be defined according to the desired mechanism. Please find further details in [ WOT-BINDING-TEMPLATES ]. Example A.3 Webhook Event Example illustrates how Events can use subscription and cancellation to describe Webhooks.

All name-value pairs of an instance of Link, where the name is a Vocabulary Term included in the Signature of Link, MUST be serialized as members of the JSON object that results from serializing the Link instance, with the Vocabulary Term as name.

It is recommended to follow the link relation values as provided in Section 5.3.4.1 Link. The examples provided below demonstrate the use of different link relation types.

A reference can be provided that points to a Thing (e.g., a controller) that controls the underlying unit (e.g., a lamp). For this controlledBy can be used:

Example 27 : Sample of a Link serialization

{    // ...    "links": [{        "rel": 
"hljs-string">"controlledBy",
        "href": 
"hljs-string">"https://servient.example.com/things/lampController",
        "type": 
"hljs-string">"application/td+json"
    }]
    // ...
}

To point to a developer documentation of a Thing the value service-doc can be used:

Example 28 : Link to developer documentation

{       // ...       "links": [{           "rel": 
"hljs-string">"service-doc",
           "href": 
"hljs-string">"https://example.com/howTo",
           "type": 
"hljs-string">"application/pdf",
           "hreflang": 
"hljs-string">"en"
       }]
       // ...
}

A superordinate Thing can collect a group of Things and refer to them by using the item value:

Example 29 : An electric drive includes two motors.

{       "title": 
"hljs-string">"Electric Drive",
       // ...       "links": [{           "rel": 
"hljs-string">"item",
           "href": 
"hljs-string">"coaps://motor1.example.com",
           "type": 
"hljs-string">" application/td+json"
       },
       {
           "rel": 
"hljs-string">"item",
           "href": 
"hljs-string">"coaps://motor2.example.com",
           "type": 
"hljs-string">" application/td+json"
       }]
       // ...
}

A Thing refers to a group in which it is collected with the collection value:

Example 30 : An electric motor is member of the electric drive collection.

{       "title": 
"hljs-string">"Electric Motor 1",
       "base": 
"hljs-string">"coaps://motor1.example.com",
       // ...       "links": [{           "rel": 
"hljs-string">"collection",
           "href": 
"hljs-string">"coaps://drive.example.com",
           "type": 
"hljs-string">" application/td+json"
       }]
       // ...
}

All name-value pairs of an instance of Form, where the name is a Vocabulary Term included in the Signature of Form, MUST be serialized as members of the JSON object that results from serializing the Form instance, with the Vocabulary Term as name.

If required, form objects MAY be supplemented with protocol-specific Vocabulary Terms identified with a prefix. See also 8.3 Protocol Bindings .

A TD snippet of a form object in the forms array is given below:

Example 31 : Sample of a Form serialization

{    // ...    "forms": [{        "op": 
"hljs-string">"writeproperty",
        "href": 
"hljs-string">"http://mytemp.example.com:5683/temp",
        "contentType": 
"hljs-string">"application/json",
        
"hljs-attr">"htv:methodName": "POST"
    }]
    // ...
}

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:

Example 32

{    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    // ...    "properties": {        "weather": {            // ...            "uriVariables": {                "lat": {                     
"hljs-attr">"type": "number", 
                    
"hljs-attr">"minimum": 0, 
                    
"hljs-attr">"maximum": 90, 
                    
"hljs-attr">"description": "Latitude for the desired location in the world" },
                "long": {                     
"hljs-attr">"type": "number", 
                    
"hljs-attr">"minimum": -180, 
                    
"hljs-attr">"maximum": 180, 
                    
"hljs-attr">"description": "Longitude for the desired location in the world" }
            },
            "forms": [{              "href": 
"hljs-string">"http://example.org/weather/{?lat,long}",
              
"hljs-attr">"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:

Example 33

{    "@context": 
"hljs-string">"http://www.w3.org/2022/wot/td/v1.1",
    // ...    "properties": {        "weather": {            // ...            "uriVariables": {                "city": {                    
"hljs-attr">"type": "string",
                    
"hljs-attr">"description": "City name to find the weather information for" 
                }
            },
            "forms": [{                "href": 
"hljs-string">"http://example.org/weather/{city}",
                
"hljs-attr">"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:

Example 34

{    "@context": 
"hljs-string">"http://www.w3.org/2022/wot/td/v1.1",
    // ...    "properties": {        "weather": {            // ...            "uriVariables": {                "city": {                    
"hljs-attr">"type": "string",
                    
"hljs-attr">"description": "City name to find the weather information for" 
                },
                "unit": {                    
"hljs-attr">"type": "string",
                    
"hljs-attr">"enum": ["fahrenheit_value","celsius_value"],
                    
"hljs-attr">"description": "Desired unit for the temperature value"
                }
            },
            "forms": [{                "href": 
"hljs-string">"http://example.org/weather/{city}/{?unit}",
                
"hljs-attr">"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:

Example 35

{    // ...    "contentType": 
"hljs-string">"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:

Example 36

{    // ...    "actions": {        "takePhoto": {            // ...            "forms": [{                "op": 
"hljs-string">"invokeaction",
                "href": 
"hljs-string">"http://camera.example.com/api/snapshot",
                
"hljs-attr">"contentType": "application/json",
                "response": {                    
"hljs-attr">"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:

Example 37

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

Example 38

{    // ...    "properties": {        "image": {                 
"hljs-attr">"description": "Provides latest image", 
                "type": 
"hljs-string">"string",
                
"hljs-attr">"contentMediaType": "image/png",
                
"hljs-attr">"contentEncoding": "base64",
                "forms": [{                             
"hljs-attr">"op": "readproperty", 
                            
"hljs-attr">"href": "coaps://mylamp.example.com/lastPicture", 
                            
"hljs-attr">"cov:methodName": "GET",
                            
"hljs-attr">"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.

Example 39

{    // ...    "properties": {        "on": {            "type": 
"hljs-string">"boolean",
            "forms": [...]
        },
        "brightness": {            "type": 
"hljs-string">"number",
            "forms": [...]
        },
        "timer": {            "type": 
"hljs-string">"integer",
            "forms": [...]
        }
    },
    // ...    "forms": [{        "op": 
"hljs-string">"readallproperties",
        "href": 
"hljs-string">"https://mylamp.example.com/properties",
        "contentType": 
"hljs-string">"application/json",
        
"hljs-attr">"htv:methodName": "GET"
    }, 
    {
        "op": 
"hljs-string">"writeallproperties",
        "href": 
"hljs-string">"https://mylamp.example.com/properties",
        "contentType": 
"hljs-string">"application/json",
        
"hljs-attr">"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:

Example 40

{    // ...    "properties": {        "temperature": {            "type": 
"hljs-string">"number",
            "forms": [...]
        },
        "brightness": {            "type": 
"hljs-string">"number",
            "forms": [...]
        },
        "humidity": {            "type": 
"hljs-string">"integer",
            "forms": [...]
        }
    },
    "uriVariables": {        "propertyNames": {            "type": 
"hljs-string">"string",
            
"hljs-attr">"description": "Comma separated list of property names to select."
        },
        "unitSystem": {            "type": 
"hljs-string">"string",
            "enum": [
"hljs-string">"metric_value","imperial_value","uscustomary_value"],
            
"hljs-attr">"description": "System of Measurement that will be used for the values"
        }
    },
    "forms": [{        "op": 
"hljs-string">"readallproperties",
        "href": 
"hljs-string">"https://mything.example.com/properties{?unitSystem}",
        "contentType": 
"hljs-string">"application/json",
        
"hljs-attr">"htv:methodName": "GET"
    }, 
    {
        "op": 
"hljs-string">"readmultipleproperties",
        "href": 
"hljs-string">"https://mylamp.example.com/properties{?propertyNames,unitSystem}",
        "contentType": 
"hljs-string">"application/json",
        
"hljs-attr">"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.

The data schemas of the WoT Thing Description defined through the DataSchema Class are based on a subset of the JSON Schema terms [ JSON-SCHEMA ]. Thus, serializations of the TD data schemas can be fed directly into JSON Schema validator implementations to validate the data exchanged with Things .

Data schema serialization applies to PropertyAffordance instances, the values assigned to input and output in ActionAffordance instances, the values assigned to subscription,data, and cancellation in EventAffordance instances, and the value assigned to uriVariables in instances of Subclasses of InteractionAffordance (when a form object uses a URI Template).

All name-value pairs of an instance of one of the Subclasses of DataSchema, where the name is a Vocabulary Term included in the Signature of that Subclass or in the Signature of DataSchema, MUST be serialized as members of the JSON object that results from serializing the DataSchema Subclass 's instance, with the Vocabulary Term as name.

The value assigned to properties in an instance of ObjectSchema MUST be serialized as a JSON object.

The values assigned to enum,required, and oneOf in an instance of DataSchema MUST be serialized as a JSON array.

The value assigned to items in an instance of ArraySchema MUST be serialized as a JSON object or a JSON array containing JSON objects.

A TD snippet data schema members is given below. Note that the surrounding object may be a data schema object (e.g., for input and output ) or a Property object, which would contain additional members.

Example 41 : Sample of a DataSchema serialization

{    // ...    "type": 
"hljs-string">"object",
    "properties": {        "status": {            "title": 
"hljs-string">"Status",
            "type": 
"hljs-string">"string",
            "enum": [
"hljs-string">"on_value", "off_value", "error_value"]
        },
        "brightness": {            "title": 
"hljs-string">"Brightness value",
            "type": 
"hljs-string">"number",
            "minimum": 
"hljs-number">0.0,
            "maximum": 
"hljs-number">100.0
        },
        "rgb": {            "title": 
"hljs-string">"RGB color value",
            "type": 
"hljs-string">"array",
            "items": {                "type": 
"hljs-string">"number",
                
"hljs-attr">"minimum": 0,
                
"hljs-attr">"maximum": 255
            },
            "minItems": 
"hljs-number">3,
            "maxItems": 
"hljs-number">3
        }
    },
    // ...
}

The terms readOnly and writeOnly can be used to signal which data items are exchanged in read interactions (i.e., when reading a Property) and which in write interactions (i.e., when writing a Property). This can be used as a workaround when Properties of an unconventional Thing exhibit different data for reading and writing, which can be the case when augmenting an existing device or service with a Thing Description.

A TD snippet with the usage of readOnly and writeOnly is given below:

Example 42

{    // ...    "properties": {        "status": {            
"hljs-attr">"description": "Read or write On/Off status.",
            "type": 
"hljs-string">"object",
            "properties": {                "latestStatus": {                    
"hljs-attr">"type": "string",
                    
"hljs-attr">"enum": ["on_value", "off_value"],
                    
"hljs-attr">"readOnly": true
                },
                "newStatusValue": {                    
"hljs-attr">"type": "string",
                    
"hljs-attr">"enum": ["on_value", "off_value"],
                    
"hljs-attr">"writeOnly": true
                }
            },
            "forms": [...]
        }
    }
    // ...
}

When the status Property is read, the status data is returned using a latestStatus member in the payload. To update the status Property, the new value must be provided through a newStatusValue member in the payload.

As an additional feature, a Thing Description instance allows the usage of a unit member within data schemas. This can be used to associate a unit of measure to a data item. Its string value can be selected freely. However, it is recommended to select units defined in well-known Vocabularies . See 7. TD Context Extensions for an example.

The JSON-based serialization of Thing Descriptions is identified by the media type application/td+json or the CoAP Content-Format ID 432 (see 12. IANA Considerations ).

In several contexts automatic validation of a JSON-based serialization of a Thing Description is useful. Formally, a valid TD satisfies all the assertions in this specification, but not all assertions can be validated given only the JSON serialization, for instance, the assertions listed under 8. Behavioral Assertions that relate a TD to the behavior of a Thing that it describes. Extensions are also problematic, in that even if formal metadata is given for validating an extension, dynamically fetching this metadata in a deployment might pose a privacy risk. In this section, therefore, we name and define various levels of validation appropriate for different contexts.

This level of validation includes all assertions implied by normative tables in this document, and those that can be checked by looking only at the TD itself.

Minimal Validation is appropriate where validation needs to be self-contained (e.g. devices on isolated networks). It does not attempt to validate context extensions and vocabularies.

In practice, these assertions can be validated using a JSON Schema in combination with a few spot checks, for example to check that security schema names have matching definitions.

This level of validation includes all those covered by 6.5.1 Minimal Validation as well as basic validation of semantic definitions.

Basic validation is appropriate in situations where network access is possible and does not pose a privacy risk, and for relatively unconstrained computing requirements. It is suitable for gateways, for example, but not for endpoints, since semantic processing is required. It can do basic validation of extensions, specfically that the vocabulary used is defined.

In this case, context definition files and SHACL definitions can be used to validate additional assertions and check TDs for semantic consistency. In addition, if context definitions and SHACL constraints for extension vocabularies can be fetched, then these can be used to validate extensions.

Full validation confirms that all the assertions in this document are satisfied, including the assertions given in 8. Behavioral Assertions that confirm the TD is consistent with the Thing it describes.

This level of validation is appropriate during development, before release, and possibly after installation. Validation during development would have to be on test Things. Actual installation of instances of such Things requires updating the TD with appropriate per-instance identifiers and URLs and so for maximum assurance, in-field validation would have to take place after installation.

The following assertions relate to the behavior of components of a WoT system, as opposed to the representation or information model of the TD. However, note that TDs are descriptive, and may in particular be used to describe pre-existing network interfaces. In these cases, assertions cannot be made that constrain the behavior of such pre-existing interfaces. Instead, the assertions are to be interpreted as constraints on the TD to accurately represent such interfaces.

To enable secure interoperation, security configurations need to accurately reflect the requirements of the Thing :

If a Thing requires a specific access mechanism for an interaction, that mechanism MUST be specified in the security configuration of the Thing Description.
If a Thing does not require a specific access mechanism for an interaction, that mechanism MUST NOT be specified in the security configuration of the Thing Description.

Some security protocols may ask for authentication information dynamically, including required encoding or encryption schemes. One consequence of the above is that if a protocol asks for a form of security credentials or an encoding or encryption scheme not declared in the Thing Description then the Thing Description is to be considered invalid.

The data schemas provided in the TD should accurately represent the data payloads returned and accepted by the described Thing in the interactions specified in the TD. In general, Consumers should follow the data schemas strictly, not generating anything not given in the WoT Thing Description, but should accept additional data from the Thing not given explicitly in the WoT Thing Description. In general, Things are described by WoT Thing Descriptions, but Consumers are constrained to follow WoT Thing Descriptions when interacting with Things .

A Consumer when interacting with another target Thing described in a WoT Thing Description MUST generate data organized according to the data schemas given in the corresponding interactions.
A WoT Thing Description MUST accurately describe the data returned and accepted by each interaction.
A Thing MAY return additional data from an interaction even when such data is not described in the data schemas given in its WoT Thing Description. This applies to ObjectSchema and ArraySchema (when items is an Array of DataSchema ) where there can be additional properties or items in the data returned. This behaves as if "additionalProperties":true or "additionalItems":true as defined in [ JSON-SCHEMA ].
A Consumer when interacting with another Thing MUST accept without error any additional data not described in the data schemas given in the Thing Description of the target Thing . This applies to ObjectSchema and ArraySchema (when items is an Array of DataSchema ) where there can be additional properties or items in the data returned. This behaves as if "additionalProperties":true or "additionalItems":true as defined in [ JSON-SCHEMA ].
A Consumer when interacting with another Thing MUST NOT generate data not described in the data schemas given in the Thing Description of that Thing .
A Consumer when interacting with another Thing MUST generate URIs according to the URI Templates, base URIs, and form href parameters given in the Thing Description of the target Thing .
URI Templates, base URIs, and href members in a WoT Thing Description MUST accurately describe the WoT Interface of the Thing .

A Protocol Binding is the mapping from an Interaction Affordance to concrete messages of a specific protocol such as HTTP [ RFC7231 ], CoAP [ RFC7252 ], or MQTT [ MQTT ]. Protocol Bindings of Interaction Affordances are serialized as forms as defined in 6.3.9 forms.

Every form in a WoT Thing Description needs to have a submission target, given by the href member, as indicated in Form . The URI scheme [ RFC3986 ] of this submission target indicates what Protocol Binding the Thing implements [ wot-architecture11 ]. For instance, if the target starts with http or https, a Consumer can then infer the Thing implements the Protocol Binding based on HTTP and it should expect HTTP-specific terms in the form instance (see next section, 8.3.1 Protocol Binding based on HTTP ).

Every form in a WoT Thing Description MUST follow the requirements of the Protocol Binding indicated by the URI scheme [ RFC3986 ] of its href member.
Every form in a WoT Thing Description MUST accurately describe requests (including request headers, if present) accepted by the Thing in an interaction.

Note

Optimally, the protocols used are listed as a scheme in the IANA registry [ IANA-URI-SCHEMES ]). This guarantees a unique Protocol Binding assignment. In case the desired protocol is not yet registered with IANA, it is recommended to follow the scheme value of the protocol specifications, if available. In principle, to avoid ambiguity in the identification of the protocol via the scheme, the Protocol Binding document will provide a recommended scheme value to enable unique protocol identification in the context of WoT.

Per default the Thing Description supports the Protocol Binding based on HTTP by including the HTTP RDF vocabulary definitions from HTTP Vocabulary in RDF 1.0 [ HTTP-in-RDF10 ]. This vocabulary can be directly used within TD instances by the usage of the prefix htv, which points to http://www.w3.org/2011/http#. Further details of Protocol Binding based on HTTP can be found in [ WOT-BINDING-TEMPLATES ].

To interact with a Thing that implements the Protocol Binding based on HTTP, a Consumer needs to know what HTTP method to use when submitting a form. In the general case, a Thing Description can explicitly include a term indicating the method, i.e., htv:methodName. For the sake of conciseness, the Protocol Binding based on HTTP defines Default Values for the operation types listed below, which also aims at convergence of the methods expected by Things (e.g., GET to read, PUT to write). When no method is indicated in a form representing an Protocol Binding based on HTTP, a Default Value MUST be assumed as shown in the following table.

Table 32 Default values of vocabulary terms for HTTP that are used when the terms are not present in a form of a TD, containing an HTTP URI Scheme
Vocabulary term	Default value	Context
`htv:methodName`	`GET`	`Form` with operation type `readproperty`,`readallproperties`,`readmultipleproperties`
`htv:methodName`	`PUT`	`Form` with operation type `writeproperty`,`writeallproperties`,`writemultipleproperties`
`htv:methodName`	`POST`	`Form` with operation type `invokeaction`

For example, the Example 1 in 1. Introduction does not contain operation types and HTTP methods in the forms. The following Default Values should be assumed for the forms in the Example 1 :

Example 50

with default values for Protocol Binding based on HTTP

{    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    "id": 
"hljs-string">"urn:uuid:3a559b69-cbec-4e7b-b543-bd8e6e41fd8b",
    "title": 
"hljs-string">"MyLampThing",
    "securityDefinitions": {        "basic_sc": {            "scheme": 
"hljs-string">"basic",
            "in": 
"hljs-string">"header"
        }
    },
    "security": [        "basic_sc"
    ],
    "properties": {        "status": {            "type": 
"hljs-string">"string",
            "readOnly": 
"hljs-literal">true,
            "forms": [
                {
                    
"hljs-attr">"op": "readproperty",
                    
"hljs-attr">"href": "https://mylamp.example.com/status"
                }
            ]
        }
    },
    "actions": {        "toggle": {            "forms": [
                {
                    
"hljs-attr">"href": "https://mylamp.example.com/toggle"
                }
            ]
        }
    },
    "events": {        "overheating": {            "data": {                "type": 
"hljs-string">"string"
            },
            "forms": [
                {
                    
"hljs-attr">"href": "https://mylamp.example.com/oh",
                    
"hljs-attr">"subprotocol": "longpoll"
                }
            ]
        }
    }
}

{    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    "id": 
"hljs-string">"urn:uuid:3deca264-4f90-4321-a5ea-f197e6a1c7cf",
    "title": 
"hljs-string">"MyLampThing",
    "securityDefinitions": {        "basic_sc": {            "scheme": 
"hljs-string">"basic",
            "in": 
"hljs-string">"header"
        }
    },
    "security": [        "basic_sc"
    ],
    "properties": {        "status": {            "type": 
"hljs-string">"string",
            "readOnly": 
"hljs-literal">true,
            "forms": [
                {
                    
"hljs-attr">"op": "readproperty",
                    
"hljs-attr">"href": "https://mylamp.example.com/status",
                    
"hljs-attr">"htv:methodName": "GET"
                }
            ]
        }
    },
    "actions": {        "toggle": {            "forms": [
                {
                    
"hljs-attr">"op": "invokeaction",
                    
"hljs-attr">"href": "https://mylamp.example.com/toggle",
                    
"hljs-attr">"htv:methodName": "POST"
                }
            ]
        }
    },
    "events": {        "overheating": {            "data": {                "type": 
"hljs-string">"string"
            },
            "forms": [
                {
                    
"hljs-attr">"op": "subscribeevent",
                    
"hljs-attr">"href": "https://mylamp.example.com/oh",
                    
"hljs-attr">"subprotocol": "longpoll"
                }
            ]
        }
    }
}

In the case of a forms entry that has multiple op values the usage of the htv:methodName is not permitted. A TD Processor will extend the multiple op values to separate forms entries and associates a single operation with the default assumption. The address information (e.g. href ) and other metadata are taken over in the extended version.

Example 51

extended forms in case of multiple values in op

{    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    "id": 
"hljs-string">"urn:uuid:43e2081d-3fd9-41bf-803d-baaefb79c70f",
    "title": 
"hljs-string">"MyLampThing",
    "securityDefinitions": {        "basic_sc": {            "scheme": 
"hljs-string">"basic",
            "in": 
"hljs-string">"header"
        }
    },
    "security": [        "basic_sc"
    ],
    "properties": {        "status": {            "type": 
"hljs-string">"string",
            "forms": [
                {
                    
"hljs-attr">"op" : ["readproperty", "writeproperty"],
                    
"hljs-attr">"href": "https://mylamp.example.com/status"
                }
            ]
        }
    }
}

{    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    "id": 
"hljs-string">"urn:uuid:9cd44eef-0b3f-4566-94b0-1358af3d86bd",
    "title": 
"hljs-string">"MyLampThing",
    "securityDefinitions": {        "basic_sc": {            "scheme": 
"hljs-string">"basic",
            "in": 
"hljs-string">"header"
        }
    },
    "security": [        "basic_sc"
    ],
    "properties": {        "status": {            "type": 
"hljs-string">"string",
            "forms": [
                {
                    
"hljs-attr">"op": "readproperty",
                    
"hljs-attr">"href": "https://mylamp.example.com/status",
                    
"hljs-attr">"htv:methodName": "GET"
                },
                {
                    
"hljs-attr">"op": "writeproperty",
                    
"hljs-attr">"href": "https://mylamp.example.com/status",
                    
"hljs-attr">"htv:methodName": "PUT"
                }
            ]
        }
    }
}

The number of Protocol Bindings a Thing can implement is not restricted. Other Protocol Bindings (e.g., for CoAP, MQTT, or OPC UA) are intended to be standardized in separate documents such as a protocol Vocabulary similar to HTTP Vocabulary in RDF 1.0 [ HTTP-in-RDF10 ] or specifications including Default Value definitions. Such protocols can be simply integrated into the TD by the usage of the TD Context Extension mechanism (see 7. TD Context Extensions ).

Please refer to [ WOT-BINDING-TEMPLATES ] for information on how to describe IoT platforms and ecosystems.

The figure below illustrates the relation of the Thing Model and Thing Description . A Thing Model mainly describes interaction affordances such as the Properties , Actions , and Events and common metadata. When a Thing Descriptions is instantiated by relying on a Thing Model, it SHOULD be valid according to that Thing Model. This paradigm can be compared with abstract class or interface definition (~Thing Model) in object-oriented programming to create objects (~Thing Descriptions).

Figure 5 Thing Model and its relation to the Thing Description.

The Thing Model is a logical description of the interface and possible interaction with Thing 's Properties , Actions , and Events , however it does not contain Thing instance-specific information, such as concrete protocol usage (e.g., IP address), or even a serial number and GPS location. However, Thing Models allows to include, e.g., security schemes if they apply to the entire class of instances the model describes. They might have URLs (e.g., like token servers) that might need to be omitted or parameterized (with templates) although in a lot of cases these might also be given.

Thing Model can be serialized in the same JSON-based format as a Thing Description which also allows JSON-LD processing. Note that a Thing Model cannot be validated in the same way as Thing Description instances due to some missing mandatory terms. This means that any term that is not using the placeholder type, still uses the types declared in TD Information Model . For example, the value of minimum needs to be an integer, unless a placeholder is used.

You can use the JSON Schema in the GitHub repository to validate TM instances that are serialized as JSON.

Note

The link for the TM needs to be updated to a permanent one before publication.

A Thing Model is recognized by the top level @type. Thing Model definitions MUST use the keyword @type at top level and a value of type string or array that equals or respectively contains tm:ThingModel. Additionally, in order to identify it as a JSON-LD document, Thing Model definitions MUST use the keyword @context at top level with same rules as a Thing Description. The prefix tm is defined within Thing Descriptions ' context and points to the Thing Model namespace as defined in 4. Namespaces . It is intended that vocabulary from the tm context only be used in Thing Model definitions and are removed or replaced when Thing Descriptions are generated (also see 9.4 Derivation of Thing Description Instances ).

A Thing Model MAY NOT contain instance specific Protocol Binding and security information such as endpoint addresses. Consequently, Thing Model definitions will also be valid if there are no JSON members like forms , base , securityDefinitions , and security . Thing Models are also valid even if these JSON members are used (e.g., as template), however, the nested mandatory members like href are omitted.

Example 3 shows a valid sample lamp Thing Model without any protocol and security information.

In the context of Thing Model definitions specific features are introduced that can be used for Thing modelling.

When the Thing Model definitions change over time, this SHOULD be reflected in the version container. The string-based term model is used within the version container to provide such versioning information, like [ SEMVER ]. The following snippet shows the usage of model in a Thing Model instance.

Example 52 : Thing Model versioning

{    // ...    "@type": 
"hljs-string">"tm:ThingModel",
    "title": 
"hljs-string">"Lamp Thing Model",
    "description": 
"hljs-string">"Lamp Thing Description Model",
    "version" : {
"hljs-attr">"model": "1.0.0"},
    // ...
}

Due to the definition of Thing Model the term instance MUST be omitted within the version container.

When Thing Models are updated and have a new version, this may affect other Thing Models that use the extension and import features (see Section 9.3.2 Extension and Import ). In some cases it is also useful to reflect a new version in the file name and/or in a corresponding URL to identify the version.

A Thing Model can extend an existing Thing Model by using the tm:extends mechanism announced in the links definition: When a Thing Model extends another Thing Model, at least one links entry with "rel": "tm:extends" that targets a Thing Model that is be extended MUST be used. The Thing Model will inherit all definitions from the extended Thing Model . There is the opportunity to extend the existing definition with further metadata by providing further JSON name-value pairs from the existing TD information model ( 5. TD Information Model ) or using the context extension concept ( 7. TD Context Extensions ). A Thing Model can also overwrite existing definitions such as title(s) and maximum etc.. For this there exist two limitations: A Thing Model SHOULD NOT overwrite the JSON names defined within the properties,actions, and/or events Map of the extended Thing Model . Definitions SHOULD NOT be overwritten in such a way that possible instance values are no longer valid compared to the origin extended definitions. Those assertions preserve the semantics throughout of the extended Thing Model . E.g., it is not allowed that a "minimum":2 from a extended Thing Model can be overwritten with "minimum":0. Meanwhile, overwriting with "minimum":5 would work since all instances values will always fulfill the restrictions of the extended Thing Model (also see Figure Figure 6 for further explanation).

Lets assume we have a basic model description as provided in the following example:

Example 53 : Basic On/Off Thing Model Definition

{    "@context": [
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1"], 
    "@type": 
"hljs-string">"tm:ThingModel",
    "title": 
"hljs-string">"Basic On/Off Thing Model",
    "properties": {        "onOff": {            "type": 
"hljs-string">"boolean"
        }
    }
}

Now a new device class model called 'Smart Lamp Control' that will be used as template for creating TD instances is designed. This model will reuse the existing definition of the 'Basic On/Off Thing Model' and extend it with a dim property:

Example 54 : Smart Lamp Control Thing Model Definition

{    "@context": [
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1"], 
    "@type": 
"hljs-string">"tm:ThingModel",
    "title": 
"hljs-string">"Smart Lamp Control with Dimming",
    "links" : [{        "rel": 
"hljs-string">"tm:extends",
        "href": 
"hljs-string">"http://example.com/BasicOnOffTM",
        "type": 
"hljs-string">"application/tm+json"
     }],
    "properties" : {        "dim" : {            "title": 
"hljs-string">"Dimming level",
            "type": 
"hljs-string">"integer",
            "minimum": 
"hljs-number">0,
            "maximum": 
"hljs-number">100
        }
   }
}

Please note that the title is overwritten and will be used when TD instances are created (also see in the next subsection 9.4 Derivation of Thing Description Instances ).

The tm:extends feature only permits inheriting all definitions of one Thing Model . In many use cases, however, it is desired only to import pieces of definitions of one or more existing Thing Models . For importing pieces of definitions of one or more existing Thing Models , the tm:ref term is introduced that provides the location of an existing (sub-)definition that SHOULD be reused. The tm:ref value MUST follow the pattern that starts with the file location as URI [ RFC3986 ](Section 4.1)), followed by # character, and followed by JSON Pointer [ RFC6901 ] definition. Note that the URI can also be empty, indicating a same-document reference [ RFC3986 ](Section 4.4)). In this case, the tm:ref is supposed to be interpreted as a relative reference. Every time tm:ref is used, the referenced pre-definition and its dependencies (e.g., by context extension) MUST be assumed at the new defined definition.

Note

Portions of the tm:ref value might contain non-ASCII characters that require URL ("percent") encoding before use. Before applying escapes to a tm:ref value, implementations should check that the value is not already encoded.

The following example shows a new TM definition that imports the existing definition of the property onOff from Example 53 into the new property definition switch.

Example 55 : Smart Lamp Control imports existing definition

{    "@context": [
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1"], 
    "@type": 
"hljs-string">"tm:ThingModel",
    "title": 
"hljs-string">"Smart Lamp Control",
    "properties" : {        "switch" : {            "tm:ref": 
"hljs-string">"http://example.com/BasicOnOffTM.tm.jsonld#/properties/onOff"
        }
   }
}

As an example for relative imports using tm:ref, the following Thing Model re-uses and augments (see below) a genericTemperature property in two more specific properties, which describe an inner and an outer temperature value, respectively.

Example 56 : Multi Sensor Thing Model re-using definitions with relative imports

{    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1", 
    "@type": 
"hljs-string">"tm:ThingModel",
    "title": 
"hljs-string">"Multi Sensor",
    "properties": {        "genericTemperature": {            "type": 
"hljs-string">"number",
            "unit": 
"hljs-string">"C"
        },
        "innerTemperature": {            "tm:ref": 
"hljs-string">"#/properties/genericTemperature",
            "title": 
"hljs-string">"The inner temperature",
            "minimum": 
"hljs-number">10
        },
        "outerTemperature": {            "tm:ref": 
"hljs-string">"#/properties/genericTemperature",
            "title": 
"hljs-string">"The outer temperature",
            
"hljs-attr">"description": "The outer temperature is measured in Kelvin",
            "unit": 
"hljs-string">"K"
        }
    },
    "tm:optional": [        
"hljs-string">"/properties/genericTemperature"
    ]
}

At the place the "tm:ref" is defined, additional name-value pairs can be added. It is also permitted to override name-value pairs from the referenced definition. If the intention is to override an existing JSON name-value pair definition from tm:ref, the same JSON name MUST be used at the same level of the tm:ref declaration that provides a new value. The process to overwrite MUST follow the JSON Merge Patch algorithm as defined in [RFC7396] where the content of the referenced definition is patched with the new provided JSON name-value pairs.

It is noted that the values can also be based on a JSON object or array, or simply be a null value. null would result to a removal of existing JSON name-value pair in the target.

Similar to tm:extends and to keep the semantic meaning, definitions SHOULD NOT be overwritten in such a way that possible instance values are no longer valid compared to the origin referenced definition.

The following example shows a new TM definition that overwrites ( maximum ), enhances ( unit ), and removes ( title ) existing definitions from Example 54 .

Example 57 : Smart Lamp Control extend and overwrite existing definitions

{    "@context": [
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1"], 
    "@type": 
"hljs-string">"tm:ThingModel",
    "title": 
"hljs-string">"Smart Lamp Control",
    "properties" : {        "dimming" : {            "tm:ref": 
"hljs-string">"http://example.com/SmartLampControlwithDimming.tm.jsonld#/properties/dim",
            "title": 
"hljs-literal">null,
            "maximum": 
"hljs-number">80,
            "unit": 
"hljs-string">"%"
        }
   }
}

Based on the JSON Merge Patch algorithm the {"title": null,"maximum": 80,"unit": "%"} would act as a patch for the referenced origin content {"title": "Dimming level", "type": "integer", "minimum": 0, "maximum": 100}.

The tm:extends and the import mechanism based on tm:ref can also be used at the same time in a TM definition. The following example extends the TM from Example 53 and imports the status and dim definitions from Example 3 and Example 54 respectively.

Example 58 : Smart Lamp Control Thing Model with extend and import mechanism

{    "@context": [
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1"], 
    "@type": 
"hljs-string">"tm:ThingModel",
    "title": 
"hljs-string">"Smart Lamp Control",
    "links" : [{        "rel": 
"hljs-string">"extends",
        "href": 
"hljs-string">"http://example.com/BasicOnOffTM",
        "type": 
"hljs-string">"application/tm+json"
     }],
    "properties" : {        "status" : {            "tm:ref": 
"hljs-string">"http://example.com/LampTM.tm.jsonld#/properties/status"
        },
        "dimming" : {            "tm:ref": 
"hljs-string">"http://example.com/LampWithDimmingTM.tm.jsonld#/properties/dim"
        }
   }
}

The tm:extends and the import mechanism based on tm:ref explicitly supports transitive extension (a hierarchy of extensions). For example, assuming there are 3 TMs: "A" which defines a tm:extends of the TM "B" which itself defines a tm:extends of the TM "C". Consequently, the "A" TM extends all definitions of both "B" and "C". Recursive extensions leading to an infinite loop MUST NOT be defined.

The following figure summarizes the allowable override behaviour of the extension and imports TM functions presented in this section. Three Thing Models use the tm:ref or tm:extends feature to reuse TM definitions of the Smart Lamp Control Thing Model . The first Thing Model imports and overwrites the maximum value to 120 within the dimmer property. However, this results in possible instance values (at runtime) that may not be in the range of the original dim definition between 0 and 100 of the dim definition of the Smart Lamp Control Thing Model. Thus, such a Thing Model definition is not allowed. The second model overwrites the property type value by number. Again, this will potentially result in numeric dim values that are not accepted by the definition of the origin dim type definition (integer) of the Smart Lamp Control Thing Model . The last model is defined in a correct way. The new ranges of dim produce potential instance values that are also fulfilled by the original dim definition.

Figure 6 Overwriting behavior of Thing Models .

In some applications, it is beneficial to reuse existing Thing Model definitions and compose them into a new IoT system. An example would be that a new Smart Ventilator is designed to consist of two sub/child Thing Model definitions such as a Ventilation Thing Model that provides on/off and adjustRpm capabilities, and an LED Thing Model that provides dimmable and RGB capabilities.

Example 59

Top level/parent Smart Ventilator Thing Model

"false">{
    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    "@type": 
"hljs-string">"tm:ThingModel",
    "title": 
"hljs-string">"Smart Ventilator Thing Model",
    "version" : { 
"hljs-attr">"model": "1.0.0" },
    "links": [
      {
        "rel": 
"hljs-string">"tm:submodel",
        "href": 
"hljs-string">"./Ventilation.tm.jsonld",
        "type": 
"hljs-string">"application/tm+json",
        "instanceName": 
"hljs-string">"ventilation"
      },
      {
        "rel": 
"hljs-string">"tm:submodel",
        "href": 
"hljs-string">"./LED.tm.jsonld",
        "type": 
"hljs-string">"application/tm+json",
        "instanceName": 
"hljs-string">"led"
      }
    ],
    "properties" : {        "status" : {
"hljs-attr">"type": "string", "enum": ["on_value", "off_value", "error_value"]}
    }
}


"hljs json">{
    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    "@type": 
"hljs-string">"tm:ThingModel",
    "title": 
"hljs-string">"Ventilator Thing Model",
    "version": {        "model": 
"hljs-string">"1.0.0"
    },
    "properties": {        "switch": {            "type": 
"hljs-string">"boolean",
            
"hljs-attr">"description": "True=On; False=Off"
        },
        "adjustRpm": {            "type": 
"hljs-string">"number",
            "minimum": 
"hljs-number">200,
            "maximum": 
"hljs-number">1200
        }
    }
}


"hljs json">{
    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    "@type": 
"hljs-string">"tm:ThingModel",
    "title": 
"hljs-string">"LED Thing Model",
    "version": {        "model": 
"hljs-string">"1.0.0"
    },
    "properties": {        "R": {            "type": 
"hljs-string">"number",
            
"hljs-attr">"description": "Red color"
        },
        "G": {            "type": 
"hljs-string">"number",
            
"hljs-attr">"description": "Green color"
        },
        "B": {            "type": 
"hljs-string">"number",
            
"hljs-attr">"description": "Blue color"
        }
    },
    "actions": {        "fadeIn": {            "title": 
"hljs-string">"fadeIn",
            "input": {                "type": 
"hljs-string">"number",
                
"hljs-attr">"description": "fadeIn in ms"
            }
        },
        "fadeOut": {            "title": 
"hljs-string">"fadeOut",
            "input": {                "type": 
"hljs-string">"number",
                
"hljs-attr">"description": "fadeOut in ms"
            }
        }
    }
}

Such composition can be introduced by the usage of the links container. If it is desired to provide information that a Thing Model consists of one or more (sub-) Thing Models , the links entries MUST use the "rel": "tm:submodel" that targets to the (sub-) Thing Models . Optionally an instanceName MAY be provided to associate an individual name to the composed (sub-) Thing Model . This is useful when multiple similar Thing Model definitions are composed and needs to be distinguished.

Different strategies can be followed to generate Thing Descriptions from composed Thing Model definitions. The default recommendation is to generate from each parent and sub/child Thing Model a corresponding Thing Descriptions (also see 9.4 Derivation of Thing Description Instances ). The composition relation can be reflected by the collection and item relation types in the links container of the Thing Descriptions . An example based on Smart Ventilation is given here:

Example 60

Thing Descriptions of the Smart Ventilator

"false">{
    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    "title": 
"hljs-string">"Smart Ventilator",
    "securityDefinitions": {        "basic_sc": {            "scheme": 
"hljs-string">"basic",
            "in": 
"hljs-string">"header"
        }
    },
    "security": 
"hljs-string">"basic_sc",
    "links": [
        {
            "rel": 
"hljs-string">"item",
            "href": 
"hljs-string">"./Ventilation.td.jsonld",
            "type": 
"hljs-string">"application/td+json"
        },
        {
            "rel": 
"hljs-string">"item",
            "href": 
"hljs-string">"./LED.td.jsonld",
            "type": 
"hljs-string">"application/td+json"
        },
        {
            "rel": 
"hljs-string">"type",
            "href": 
"hljs-string">"./SmartVentilator.tm.jsonld",
            "type": 
"hljs-string">"application/tm+json"
        }
    ],
    "properties": {        "status": {            "type": 
"hljs-string">"string",
            "enum": [                "on_value",                "off_value",                "error_value"
            ],
            "forms": [
                {
                    
"hljs-attr">"href": "http://127.0.13.232:4563/status"
                }
            ]
        }
    }
}


"hljs json">{
    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    "title": 
"hljs-string">"Ventilator",
    "securityDefinitions": {        "basic_sc": {            "scheme": 
"hljs-string">"basic",
            "in": 
"hljs-string">"header"
        }
    },
    "security": 
"hljs-string">"basic_sc",
    "links": [
        {
            "rel": 
"hljs-string">"collection",
            "href": 
"hljs-string">"./SmartVentilation.td.jsonld",
            "type": 
"hljs-string">"application/td+json"
        },
        {
            "rel": 
"hljs-string">"type",
            "href": 
"hljs-string">"./Ventilation.tm.jsonld",
            "type": 
"hljs-string">"application/tm+json"
        }
    ],
    "security": 
"hljs-string">"basic_sc",
    "properties": {        "switch": {            "type": 
"hljs-string">"boolean",
            
"hljs-attr">"description": "True=On; False=Off",
            "forms": [
                {
                    
"hljs-attr">"href": "http://127.0.13.212:4563/switch"
                }
            ]
        },
        "adjustRpm": {            "type": 
"hljs-string">"number",
            "minimum": 
"hljs-number">200,
            "maximum": 
"hljs-number">1200,
            "forms": [
                {
                    
"hljs-attr">"href": "http://127.0.13.212:4563/adjustRpm"
                }
            ]
        }
    }
}


"hljs json">{
    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    "title": 
"hljs-string">"LED Thing Model",
    "securityDefinitions": {        "basic_sc": {            "scheme": 
"hljs-string">"basic",
            "in": 
"hljs-string">"header"
        }
    },
    "security": 
"hljs-string">"basic_sc",
    "links": [
        {
            "rel": 
"hljs-string">"collection",
            "href": 
"hljs-string">"./SmartVentilation.td.jsonld",
            "type": 
"hljs-string">"application/td+json"
        },
        {
            "rel": 
"hljs-string">"type",
            "href": 
"hljs-string">"./LED.tm.jsonld",
            "type": 
"hljs-string">"application/tm+json"
        }
    ],
    "properties": {        "R": {            "type": 
"hljs-string">"number",
            
"hljs-attr">"description": "Red color",
            "forms": [
                {
                    
"hljs-attr">"href": "http://127.0.13.211:4563/R"
                }
            ]
        },
        "G": {            "type": 
"hljs-string">"number",
            
"hljs-attr">"description": "Green color",
            "forms": [
                {
                    
"hljs-attr">"href": "http://127.0.13.211:4563/G"
                }
            ]
        },
        "B": {            "type": 
"hljs-string">"number",
            
"hljs-attr">"description": "Blue color",
            "forms": [
                {
                    
"hljs-attr">"href": "http://127.0.13.211:4563/B"
                }
            ]
        }
    },
    "actions": {        "fadeIn": {            "title": 
"hljs-string">"fadeIn",
            "input": {                "type": 
"hljs-string">"number",
                
"hljs-attr">"description": "fadeIn in ms"
            },
            "forms": [
                {
                    
"hljs-attr">"href": "http://127.0.13.211:4563/fadeIn"
                }
            ]
        },
        "fadeOut": {            "title": 
"hljs-string">"fadeOut",
            "input": {                "type": 
"hljs-string">"number",
                
"hljs-attr">"description": "fadeOut in ms"
            },
            "forms": [
                {
                    
"hljs-attr">"href": "http://127.0.13.211:4563/fadeOut"
                }
            ]
        }
    }
}

A single TD can also be generated which contains the interaction definitions of the top level/parent Thing Model and all interaction definitions of all sub/child Thing Models . Thereby the generation process MUST avoid possible name collisions. The following example shows a potential generated (self-contained) Thing Description of the Smart Ventilator Thing Model.

Example 61 : Self-contained TD of the Smart Ventilator TM

{    "@context": 
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
    "title": 
"hljs-string">"Smart Ventilator",
    "securityDefinitions": {        "basic_sc": {            "scheme": 
"hljs-string">"basic",
            "in": 
"hljs-string">"header"
        }
    },
    "security": 
"hljs-string">"basic_sc",
    "links": [
        {
            "rel": 
"hljs-string">"type",
            "href": 
"hljs-string">"./SmartVentilator.tm.jsonld",
            "type": 
"hljs-string">"application/tm+json"
        }
    ],
    "properties": {        "status": {            "type": 
"hljs-string">"string",
            "enum": [                "on_value",                "off_value",                "error_value"
            ],
            "forms": [
                {
                    
"hljs-attr">"href": "http://127.0.13.232:4563/status"
                }
            ]
        },
        "switch": {            "type": 
"hljs-string">"boolean",
            
"hljs-attr">"description": "True=On; False=Off",
            "forms": [
                {
                    
"hljs-attr">"href": "http://127.0.13.212:4563/switch"
                }
            ]
        },
        "adjustRpm": {            "type": 
"hljs-string">"number",
            "minimum": 
"hljs-number">200,
            "maximum": 
"hljs-number">1200,
            "forms": [
                {
                    
"hljs-attr">"href": "http://127.0.13.212:4563/adjustRpm"
                }
            ]
        },
        "R": {            "type": 
"hljs-string">"number",
            
"hljs-attr">"description": "Red color",
            "forms": [
                {
                    
"hljs-attr">"href": "http://127.0.13.211:4563/R"
                }
            ]
        },
        "G": {            "type": 
"hljs-string">"number",
            
"hljs-attr">"description": "Green color",
            "forms": [
                {
                    
"hljs-attr">"href": "http://127.0.13.211:4563/G"
                }
            ]
        },
        "B": {            "type": 
"hljs-string">"number",
            
"hljs-attr">"description": "Blue color",
            "forms": [
                {
                    
"hljs-attr">"href": "http://127.0.13.211:4563/B"
                }
            ]
        }
    },
    "actions": {        "fadeIn": {            "title": 
"hljs-string">"fadeIn",
            "input": {                "type": 
"hljs-string">"number",
                
"hljs-attr">"description": "fadeIn in ms"
            },
            "forms": [
                {
                    
"hljs-attr">"href": "http://127.0.13.211:4563/fadeIn"
                }
            ]
        },
        "fadeOut": {            "title": 
"hljs-string">"fadeOut",
            "input": {                "type": 
"hljs-string">"number",
                
"hljs-attr">"description": "fadeOut in ms"
            },
            "forms": [
                {
                    
"hljs-attr">"href": "http://127.0.13.211:4563/fadeOut"
                }
            ]
        }
    }
}

In some cases it is desirable to not enforce which interaction affordances are mandatory and do not necessarily need to be implemented in a Thing Description instance. If interaction models are not mandatory to be implemented in a Thing Description instance, Thing Model definitions MUST use the JSON member name tm:optional.tm:optional MUST be a JSON array at the top level. The value of tm:optional MUST provide JSON Pointer [ RFC6901 ] references to the required interaction model definitions. The JSON Pointers of tm:optional MUST resolve to an entire interaction affordance Map definition.

The following sample shows the usage of tm:optional for the Event interaction overheating.

Example 62 : Thing Model with the tm:optional term for interaction affordances.

{    "@context": [
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1"], 
    "@type": 
"hljs-string">"tm:ThingModel",
    "title": 
"hljs-string">"Lamp Thing Model",
    "description": 
"hljs-string">"Lamp Thing Model Description",
    "tm:optional": [        "/events/overheating"
    ],
    "properties": {        "status": {            
"hljs-attr">"description": "current status of the lamp (on|off)",
            "type": 
"hljs-string">"string",
            "readOnly": 
"hljs-literal">true
        }
    },
    "actions": {        "toggle": {            
"hljs-attr">"description": "Turn the lamp on or off"
        }
    },
    "events": {        "overheating": {            
"hljs-attr">"description": "Lamp reaches a critical temperature (overheating)",
            "data": {
"hljs-attr">"type": "string"}
        }
    }
}

Since the Event overheating is not mandatory it may not be available in a Thing Description instance.

Please note that an optional definition in a Thing Model definition can be overwritten in the case it is extended by another Thing Model through the use of tm:ref:

Example 63 : Thing Model overwrites tm:optional of the previous Thing Model example.

{    "@context": [
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1"], 
    "@type": 
"hljs-string">"tm:ThingModel",
    "title": 
"hljs-string">"Lamp Thing Model (All Mandatory)",
    "description": 
"hljs-string">"Lamp Thing Model description expects all interaction affordances (status, toggle, and overheating)",
    "links": [
       {
          "rel": 
"hljs-string">"tm:extends",
          "href": 
"hljs-string">"./lampThingModel.tm.jsonld",
          "type": 
"hljs-string">"application/tm+json"
       }
    ],
    "events": {        "overheating": {            "tm:ref": 
"hljs-string">"./lampThingModel.tm.jsonld#/events/overheating" 
        }
    }
}

A Thing Model can specify which terms should be used in a TD instance, but their values are unspecific and are first known during TD instantiation. In a case where TD instance terms, but not their values, are known in advance, the placeholder labeling MAY be used in a Thing Model. The placeholder labeling MUST be substituted with a concrete value (e.g., as JSON number, JSON string, JSON object, etc) when TD instance is created from the Thing Model. The string-based pattern of the placeholder MUST follow a valid pattern based on the regular expression {{2}[ -~]+}{2} (e.g., {{PLACEHOLDER_IDENTIFIER}} ). The characters between {{ and }} are used as identifier name of the placeholder. The identifier name can be used to identify the placeholder for the substitution process. A placeholder MUST be applied within the value of the JSON name-value pair. If a non string-based value of a JSON name-value pair has a placeholder, the value MUST be (temporarily) typed as string. After replacing the placeholder, e.g. when creating a Thing Description instance, the original type is applied with the corresponding replaced value.

The following Thing Model example defines different placeholders. The placeholder map is used to apply the replacement and to transform the intended value type.

Example 64

Thing Description generation from Thing Model

"false">{
        "@context": [
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1"], 
        "@type": 
"hljs-string">"tm:ThingModel",
        "title": 
"hljs-string">"Thermostate No. {{THERMOSTATE_NUMBER}}",
        "version": 
"hljs-string">"{{VERSION_INFO}}",
        "base": 
"hljs-string">"mqtt://{{MQTT_BROKER_ADDRESS}}",
        "properties": {                "temperature": {                        
"hljs-attr">"description": "Shows the current temperature value",
                        
"hljs-attr">"type": "number",
                        
"hljs-attr">"minimum": -20,
                        
"hljs-attr">"maximum": "{{THERMOSTATE_TEMPERATURE_MAXIMUM}}",
                        
"hljs-attr">"observable": "{{THERMOSTATE_TEMPERATURE_OBSERVABLE}}"
                }
        }
        ...
}


"hljs json">{
        
"hljs-attr">"THERMOSTATE_NUMBER": 4, 
        
"hljs-attr">"MQTT_BROKER_ADDRESS": "192.168.178.72:1883",
        
"hljs-attr">"THERMOSTATE_TEMPERATURE_MAXIMUM": 47.7, 
        
"hljs-attr">"THERMOSTATE_TEMPERATURE_OBSERVABLE": true,
        
"hljs-attr">"VERSION_INFO": {"instance": "1.0.1", "model": "2.0.0"}
}

"false">{
        "@context": [
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1"], 
        "@type": 
"hljs-string">"Thing",
        "title": 
"hljs-string">"Thermostate No. 4",
        "version": {
"hljs-attr">"instance": "1.0.1", "model": "2.0.0"},
        "base": 
"hljs-string">"mqtt://192.168.178.72:1883",
        "properties": {                "temperature": {                        
"hljs-attr">"description": "Shows the current temperature value",
                        
"hljs-attr">"type": "number",
                        
"hljs-attr">"minimum": -20.0,
                        
"hljs-attr">"maximum": 47.7,
                        
"hljs-attr">"observable": true
                }
        }
        ...
}

Thing Models can be used as templates to generate a Thing Description based on the restrictions defined in Sections 5. TD Information Model and 6. TD Representation Format . During this process missing data such as communication and security metadata have to be complemented to create valid Thing Description instances. A Thing Model MUST be defined in such a way that there are no inconsistencies that would result in a Thing Description not being able to meet the requirements as described in Section 5. TD Information Model and 6. TD Representation Format . A TM-to-TD generator to derive a Thing Description instance from a Thing Model transforms it to a Partial TD using the following steps:

Copy all definitions from the input Thing Model to the resulting Partial TD instance. If used, the extension and imports feature MUST be resolved and represented in the Partial TD instance according to 9.3.2 Extension and Import .
If used, links element entry with "rel":"tm:extends" MUST be removed from the current Partial TD
The tm:ThingModel value of the top-level @type MUST be removed in the Partial TD instance.
All required interactions (not listed in tm:optional ) MUST be taken over to the Partial TD instance.
All optional interactions (listed in tm:optional ) MAY be taken over to the Partial TD instance.
If used, all placeholders (see Section 9.3.5 Placeholder ) in the Thing Model MUST be replaced with a valid corresponding value in the Partial TD .

Finally, a TM-to-TD generator will take the resulting Partial TD and transform it into a Thing Description with this last step

Missing communication and/or security metadata details MUST be completed in the Thing Description instance based on Section 6.3.4 securityDefinitions and security and/or 6.3.9 forms.

It is recommended that the id value of a Thing Model provides a placeholder such as "id": "urn:example:{{RANDOM_ID_PATTERN}}" for the TD generation process. Please avoid including metadata in the id pattern.

Thing Description instances that follow a Thing Model can carry the information regarding which type of Thing Model is derived. In this context, the linking concept can be used with "rel": "type" (also see Section 5.3.4.1 Link ), as shown in the following example:

Example 65

Linking Thing Description to a Thing Model Definition

"false">{
        // ...        "@type": 
"hljs-string">"tm:ThingModel",
        "title": 
"hljs-string">"Smart Pump",
        "id": 
"hljs-string">"urn:example:{{RANDOM_ID_PATTERN}}",
        "description": 
"hljs-string">"Smart Pump live plant and simulator",
        "version" : {
"hljs-attr">"model" : "1.0.0" },
        // ...
}

"false">{
        // ...        "@type": 
"hljs-string">"Thing",
        "title": 
"hljs-string">"Smart Pump",
        "id": 
"hljs-string">"urn:example:123-321-123-321",
        "description": 
"hljs-string">"Smart Pump live plant and simulator",
        "version" : {
"hljs-attr">"instance": "1.0.0", "model": "1.0.0" },
        "links" : [{                "rel": 
"hljs-string">"type",
                "href": 
"hljs-string">"http://example.com/ThingModelPool/Pump",
                "type": 
"hljs-string">"application/tm+json"
        }],
        // ...
}

Please note that a TD can only be an instance of one TM at a time. That means for Thing Descriptions: The links array MUST use the entry with "rel": "type" a maximum of once. If it is desired to reflect all relationships to other Things in a Thing Description, the composition mechanism in TMs can be considered (see Section 9.3.3 Composition ).

The following Thing Model extends the model as shown in Example 54 and overwrites the maximum value of the dim property

Example 66 : Extending Smart Control Lamp with a modified dim constrained

{    "@context": [
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1"], 
    "@type": 
"hljs-string">"tm:ThingModel",
    "links" : [{        "rel": 
"hljs-string">"tm:extends",
        "href": 
"hljs-string">"http://example.com/SmartControlLampTM",
        "type": 
"hljs-string">"application/tm+json"
     }],
    "properties" : {        "dim" : {            "maximum": 
"hljs-number">200
        }
   }
}

The expected Thing Description that is derived from this Thing Model would be (with HTTP Binding and basic security applied):

Example 67 : Thing Description

{    "@context": [
"hljs-string">"https://www.w3.org/2022/wot/td/v1.1"], 
    "@type": 
"hljs-string">"Thing",
    "title": 
"hljs-string">"Smart Lamp Control",
    "securityDefinitions": {        "basic_sc": {
"hljs-attr">"scheme": "basic", "in": "header"}
    },
    "security": 
"hljs-string">"basic_sc",
    "links" : [{        "rel": 
"hljs-string">"type",
        "href": 
"hljs-string">"url/to/SmartLampControlModifiedDimTM",
        "type": 
"hljs-string">"application/tm+json"
     }
   ],
   "properties" : {        "onOff": {            "type": 
"hljs-string">"boolean",
            "forms": [{
"hljs-attr">"href": "https://smartlamp.example.com/onoff"}]
        },
        "dim" : {            "type": 
"hljs-string">"integer",
            "minimum": 
"hljs-number">0,
            "maximum": 
"hljs-number">200,
            "forms": [{
"hljs-attr">"href": "https://smartlamp.example.com/dim"}]
        }
   }
}

Case	Needed Terms	Explanation	Consumer Behavior	Thing Behavior
Case 1A: Input present, output not present	`contentType` inside the form	`contentType` refers only to the input	Encode input payload according to the `contentType` available in the form. If possible in the used protocol, add the value of `contentType` to the input header.	If possible in the used protocol, decode the input payload in the using the input header `contentType`. If not possible in the used protocol or not available, decode the output payload in the corresponding `contentType` available in the form.
Case 1B: Input not present, output present.	`contentType` inside the form.	`contentType` refers only to the output.	If possible in the used protocol, add preference for the `contentType` available in the form to the input header. If possible in the used protocol, decode the output payload using the output header `contentType`. If not possible in the used protocol or not available, decode the output payload in the corresponding `contentType` available in the form.	Encode output payload in the corresponding `contentType` available in the form. If possible in the used protocol, add the value of `contentType` to the output header.
Case 1C: Input and output present, same `contentType` for messages.	`contentType` inside the form.	`contentType` refers both to input and output.	Encode input payload according to the `contentType` available in the form. If possible in the used protocol, add the value of `contentType` to the input header. If possible in the used protocol, add preference for the `contentType` of the output payload to the input header using value in the `contentType`. If possible in the used protocol, decode the output payload using the output header `contentType`. If not possible in the used protocol or not available, decode the output payload in the corresponding `contentType` available in the form.	If possible in the used protocol, decode the input payload in the using the input header `contentType`. If not possible in the used protocol or not available, decode the input payload in the corresponding `contentType` available in the form. Encode output payload in the corresponding `contentType` available in the form. If possible in the used protocol, add the value of `contentType` to the output header.

Case	Needed Terms	Explanation	Consumer Behavior	Thing Behavior
Case 2A: Single input and single output present, different `contentType` for messages.	`contentType` and `response` inside the form. `response` has `contentType` with a different value.	`contentType` in the form level refers to the input and `contentType` in the `response` (response-level) refers to the output	Encode input payload according to the `contentType` available in the form level. If possible in the used protocol, add the value of form-level `contentType` to the input header. If possible in the used protocol, add preference for the `contentType` of the output payload to the input header using the response-level `contentType`. If possible in the used protocol, decode the output payload using the output header `contentType`. If not possible in the used protocol or not available, decode the output payload in the corresponding `contentType` available in the response level.	If possible in the used protocol, decode the input payload in the using the input header. If not possible in the used protocol or not available, decode the input payload in the corresponding `contentType` available in the form level. Encode output payload in the corresponding `contentType` available in the response level. If possible in the used protocol, add the value of response-level `contentType` to the output header.
Case 2B: Input and multiple possible outputs present, same `contentType` for messages	`contentType` and `additionalResponses` inside the form. `schema` in the `additionalResponses` array items can be needed.	`contentType` in the form level refers to the input and the normal output. `additionalResponses` does not need `contentType` since the default value rule applies. This is the same case (Case 1C) as there is actually a single `contentType`. However, there can be different Data Schemas delivered in the output, requiring the `additionalResponses` and `schema` terms in the form.	See Case 1C	See Case 1C
Case 2C: Input and multiple possible outputs present, different `contentType` for output messages	`contentType`,`additionalResponses` and possibly `response` inside the form. `additionalResponses` needs `contentType` for output the messages with different `contentType` s.	This the most complicated case that can have different ways to be described in a TD. `contentType` in the form level refers to the input and to the expected output if the output is of the same `contentType` (like in case 1C). `contentType` inside `response` refers to the expected output if the output is of a different `contentType` (like in case 2A). `contentType` inside `additionalResponses` refers to other possible outputs.	Encode input payload according to the `contentType` available in the form level. If possible in the used protocol, add the value of form-level `contentType` to the input header. If possible in the used protocol, decode the output payload using the output header `contentType`. If not possible in the used protocol or not available, decode the output payload in the corresponding `contentType` available in the response level or one of the `contentType` s in `additionalResponses`.	If possible in the used protocol, decode the input payload in the using the input header. If not possible in the used protocol or not available, decode the input payload in the corresponding `contentType` available in the form level. Encode output payload in the corresponding `contentType` available in the response level or one of the `contentType` s in `additionalResponses`. If the output is associated with an error case, use the `contentType` in a form with `"success":false` If possible in the used protocol, add the value of the used `contentType` to the output header.

`properties`	→	`https://www.w3.org/2019/wot/td#hasPropertyAffordance`
`object`	→	`https://www.w3.org/2019/wot/json-schema#ObjectSchema`
`basic`	→	`https://www.w3.org/2019/wot/security#BasicSecurityScheme`
`href`	→	`https://www.w3.org/2019/wot/hypermedia#hasTarget`
...

Web of Things (WoT) Thing Description 1.1

Abstract

Status of This Document

1. Introduction

1.1 Thing Description

1.2 Thing Model

2. Conformance

3. Terminology

4. Namespaces

5. TD Information Model

5.1 Overview

5.2 Preliminaries

5.3 Class Definitions

5.3.1 Core Vocabulary Definitions

5.3.1.1 Thing

5.3.1.2 InteractionAffordance

5.3.1.3 PropertyAffordance

5.3.1.4 ActionAffordance

5.3.1.5 EventAffordance

5.3.1.6 VersionInfo

5.3.1.7 MultiLanguage

5.3.2 Data Schema Vocabulary Definitions

5.3.2.1 DataSchema

5.3.2.2 ArraySchema

5.3.2.3 BooleanSchema

5.3.2.4 NumberSchema

5.3.2.5 IntegerSchema

5.3.2.6 ObjectSchema

5.3.2.7 StringSchema

5.3.2.8 NullSchema

5.3.3 Security Vocabulary Definitions

5.3.3.1 SecurityScheme

5.3.3.2 NoSecurityScheme

5.3.3.3 AutoSecurityScheme

5.3.3.4 ComboSecurityScheme

5.3.3.5 BasicSecurityScheme

5.3.3.6 DigestSecurityScheme

5.3.3.7 APIKeySecurityScheme

5.3.3.8 BearerSecurityScheme

5.3.3.9 PSKSecurityScheme

5.3.3.10 OAuth2SecurityScheme

5.3.4 Hypermedia Controls Vocabulary Definitions

5.3.4.1 Link

5.3.4.2 Form

5.3.4.2.1 Mapping op Values to Data Schemas

5.3.4.2.2 Response-related Terms Usage

5.3.4.3 ExpectedResponse

5.3.4.4 AdditionalExpectedResponse

5.4 Default Value Definitions

6. TD Representation Format

6.1 Mapping to JSON Types

6.2 Omitting Default Values

6.3 Information Model Serialization

6.3.1 Thing Root Object

6.3.2 Human-Readable Metadata

6.3.3 version

6.3.4 securityDefinitions and security

6.3.4.1 Multiple Security Definitions

6.3.4.2 security in Forms

6.3.4.3 ComboSecurityScheme

6.3.4.4 OAuth 2.0 usage

6.3.4.5 API key usage

6.3.5 properties

6.3.6 actions

6.3.7 events

6.3.8 links

6.3.9 forms

6.3.9.1 uriVariables

6.3.9.2 contentType

6.3.9.3 response

6.3.9.4 additionalResponses

6.3.9.5 contentMediaType and contentEncoding

6.3.9.6 Top level forms

6.3.10 Data Schemas

6.4 Identification

6.5 Validation

6.5.1 Minimal Validation

6.5.2 Basic Validation

6.5.3 Full Validation

7. TD Context Extensions

5.3.1.1 `Thing`

5.3.1.2 `InteractionAffordance`

5.3.1.3 `PropertyAffordance`

5.3.1.4 `ActionAffordance`

5.3.1.5 `EventAffordance`

5.3.1.6 `VersionInfo`

5.3.1.7 `MultiLanguage`

5.3.2.1 `DataSchema`

5.3.2.2 `ArraySchema`

5.3.2.3 `BooleanSchema`

5.3.2.4 `NumberSchema`

5.3.2.5 `IntegerSchema`

5.3.2.6 `ObjectSchema`

5.3.2.7 `StringSchema`

5.3.2.8 `NullSchema`

5.3.3.1 `SecurityScheme`

5.3.3.2 `NoSecurityScheme`

5.3.3.3 `AutoSecurityScheme`

5.3.3.4 `ComboSecurityScheme`

5.3.3.5 `BasicSecurityScheme`

5.3.3.6 `DigestSecurityScheme`

5.3.3.7 `APIKeySecurityScheme`

5.3.3.8 `BearerSecurityScheme`

5.3.3.9 `PSKSecurityScheme`

5.3.3.10 `OAuth2SecurityScheme`

5.3.4.1 `Link`

5.3.4.2 `Form`

5.3.4.3 `ExpectedResponse`

5.3.4.4 `AdditionalExpectedResponse`

6.3.3 `version`

6.3.4 `securityDefinitions` and `security`

6.3.4.2 `security` in Forms

6.3.4.3 `ComboSecurityScheme`

6.3.5 `properties`

6.3.6 `actions`

6.3.7 `events`

6.3.8 `links`

6.3.9 `forms`

6.3.9.1 `uriVariables`

6.3.9.2 `contentType`

6.3.9.3 `response`

6.3.9.4 `additionalResponses`

6.3.9.5 `contentMediaType` and `contentEncoding`

6.3.9.6 Top level `forms`

12.1 `application/td+json` Media Type Registration

12.2 `application/tm+json` Media Type Registration