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.
Future updates to this specification may incorporate new features.
The Web of Things Working Group intends to submit this document
for consideration as a W3C Proposed Recommendation
after at least the minimum CR review period has passed. However,
before PR transition is requested, any features or assertions
currently marked as at-risk that did not appear in the TD 1.0
specification and do not have at least two implementations at that
time will either be removed or converted into informative
statements, as appropriate.
Introduction
Thing Description
The WoT Thing Description (TD) is a central building block in the W3C Web of
Things (WoT) and can be considered as the entry point of a Thing
(much like the index.html of a Web site). A TD instance has five main
components: textual metadata about the Thing itself,
a set of Interaction Affordances
that indicate how the Thing can be used,
schemas for the data
exchanged with the Thing for machine-understandability, Security Definitions
to provide metadata about the security mechanisms that must be used for interactions, and, finally, Web links to
express any formal or informal relation to other Things or documents on the Web.
The Interaction Model of W3C WoT defines three types of Interaction Affordances:
Properties (PropertyAffordance class)
can be used for sensing and controlling parameters, such as getting the current value or
setting an operation state.
Actions (ActionAffordance class) model
invocation of physical (and hence time-consuming) processes, but can also be used to
abstract RPC-like calls of existing platforms.
Events (EventAffordance class) are used
for the push model of communication where notifications,
discrete events, or streams of values are sent asynchronously to the receiver.
See [[wot-architecture11]] for details.
In general, the TD provides metadata for different Protocol Bindings
identified by URI schemes [[RFC3986]] (e.g., http, coap, etc. [[?IANA-URI-SCHEMES]]),
content types based on media types [[RFC2046]]
(e.g., application/json, application/xml, application/cbor, application/exi, etc. [[?IANA-MEDIA-TYPES]]),
and security mechanisms (for authentication, authorization, confidentiality, etc.).
Serialization of TD instances is based on JSON [[RFC8259]], where JSON names refer to terms of
the TD vocabulary, as defined in this specification document. In addition the JSON serialization of TDs
follows the syntax of JSON-LD 1.1 [[?JSON-LD11]] to enable extensions and rich semantic processing.
Example 1 shows a TD instance and
illustrates the Interaction Model with Properties, Actions, and Events
by describing a lamp Thing with the title MyLampThing.
From this TD example,
we know there exists one Property affordance
with the title status.
In addition,
information is provided to indicate that this Property is accessible via
(the secure form of) the HTTP protocol with a GET method
at the URI https://mylamp.example.com/status
(announced within the forms structure by the
href member), and will return a string-based status value.
The use of the GET method is not stated explicitly,
but is one of the default assumptions defined by this document.
In a similar manner, an Action affordance is specified to toggle the
switch status using the POST method on the
https://mylamp.example.com/toggle resource,
where POST is again a default assumption for invoking Actions.
The Event affordance enables a mechanism for asynchronous messages
to be sent by a Thing.
Here, a subscription to be notified upon a possible overheating event
of the lamp can be obtained by using HTTP with its long polling
subprotocol on https://mylamp.example.com/oh.
This example also specifies the basic security scheme,
requiring a username and password for access.
Note that a security scheme is first given a name in
securityDefinitions and then activated by specifying
that name in a security section.
In combination with the use of the HTTP protocol this example
demonstrates the use of HTTP Basic Authentication.
Specification of at least one security scheme at the top level is mandatory,
and gives the default access requirements for every resource.
However, security schemes can also be specified per-form,
with configurations given at the form level overriding configurations given at the Thing level,
allowing for the specification of fine-grained access control.
It is also possible to use a special nosec security scheme to
indicate that no access control mechanisms are used.
Additional examples will be provided later.
The Thing Description offers the possibility to add contextual definitions
in some namespace. This mechanism can be used to integrate additional semantics
to the content of the Thing Description instance, provided that formal knowledge,
e.g., logic rules for a specific domain of application, can be found under the
given namespace. Contextual information can also help specify some configurations and
behavior of the underlying communication protocols declared in the forms field.
Example 2 extends the TD sample from
Example 1 by introducing a second definition in the @context to declare the
prefix saref as referring to SAREF, the
Smart Appliance Reference Ontology [[SMARTM2M]]. This IoT ontology includes terms interpreted
as semantic labels that can be set as values of the
@type field, giving the semantics of Things and their
Interaction Affordances. In the example below, the Thing is labelled with
saref:LightSwitch, the statusProperty is labelled with
saref:OnOffState and the toggleAction with
saref:ToggleCommand.
The declaration mechanism inside some
@context is specified by JSON-LD. A TD instance complies to version 1.1 of
that specification [[?json-ld11]]. Hence, a TD instance can be also processed as an RDF
document (for details about semantic processing, please refer to Appendix
and the documentation under the namespace IRIs, e.g.,
https://www.w3.org/2019/wot/td).
Thing Model
One of the main intentions of a Thing Description is to provide a Consumer
with all the details necessary to successfully interact with a Thing.
In some IoT application scenarios, a fully detailed Thing Description, e.g., with
communication metadata is not necessary (e.g., IoT ecosystems may implicitly handle communication separately),
or may not be available because a new entity has not yet been deployed (e.g., IP address is not yet known).
Sometimes, also a kind of class definition is required that forces capability definitions that should be
available for all created instances (e.g., large-scale production of new devices).
In order to address the above-mentioned scenarios or others, the Thing Model can be used that mainly provides the data model
definitions within Things' Properties, Actions, and/or Events and can be potentially used
as template for creating Thing Description instances. In the following a sample
Thing Model is presented that can be seen as a model for the Thing Description
instance in .
{
"@context": ["https://www.w3.org/2022/wot/td/v1.1"],
"@type": "tm:ThingModel",
"title": "Lamp Thing Model",
"properties": {
"status": {
"description": "current status of the lamp (on|off)",
"type": "string",
"readOnly": true
}
},
"actions": {
"toggle": {
"description": "Turn the lamp on or off"
}
},
"events": {
"overheating": {
"description": "Lamp reaches a critical temperature (overheating)",
"data": {"type": "string"}
}
}
}
Thing Model definitions are identified by the "@type": "tm:ThingModel".
As the example shows, it does not provide details about a single Thing instance due to the
lack of communication and security metadata.
This specification presents a mechanism for deriving valid Thing Description instances from
such Thing Model definitions. In addition, other design concepts are specified, including how
to override, extend, and reuse existing Thing Model definitions.
A Thing Description instance complies with this specification if it follows
the normative statements in
and
regarding Thing Description serialization.
A JSON Schema [[?JSON-SCHEMA]] to validate Thing Description instances
is provided in Appendix .
Terminology
The fundamental WoT terminology such as
Thing,
Consumer,
Producer,
Thing Description (TD),
Partial TD,
Thing Model (TM),
Interaction Model,
Interaction Affordance,
Property,
Action,
Event,
Protocol Binding,
Servient,
Vocabulary,
Term,
Vocabulary Term,
WoT Interface, and
WoT Runtime
are defined in Section 3
of the WoT Architecture specification [[wot-architecture11]].
In addition, this specification introduces the following definitions:
Semantic Tag, Semantic Annotation
A JSON-LD mechanism that links definitions in a Thing Descriptions document to concepts in an (RDF) ontology.
This allows Thing Description authors to provide further context and express domain knowledge in a standardized way.
In a Thing Descriptions document, this can be achieved using @type members, and through the use
of string prefixes using a colon (:).
A system that can serialize some internal representation of a Thing Description
in a given format and/or deserialize it from that format. A TD Processor can follow
validation steps to detect semantically inconsistent Thing Descriptions, that is,
Thing Descriptions that cannot satisfy constraints on the Instance Relation
of the Thing class.
For that purpose, a TD Processor can compute fill in the forms of Thing
Descriptions in which all possible Default Values are assigned.
A TD Processor is typically a sub-system of a WoT Runtime.
Implementations of a TD Processor can be a TD producer (able to serialize to TD Documents)
or a TD consumer (able to deserialize from TD Documents) or both.
TD Serialization
or
TD Document
Textual or binary representation of Thing Descriptions that can be stored and
exchanged between Servients. A TD Serialization follows a given representation
format, identified by a media type when exchanged over the network.
The default representation format for Thing Descriptions is JSON-based as defined by
this specification.
Levels of a TD (including
Thing Level, Affordance Level,
Data Schema Level, Forms Level)
The scope of a TD or TM instance at the given hierarchy level. For example, the root of a TD, where terms such
as @context are defined is the Thing level, forms are defined within the Affordance level,
type, maximum are defined within the Data Schema level and href is defined
within the Forms level.
Even if not defined, other levels can be used such as Links level.
These definitions are further developed in .
Namespaces
The version of the TD Information Model
defined in of this specification
is identified by the following IRI:
https://www.w3.org/2022/wot/td/v1.1
This IRI [[RFC3987]], which is also a URI [[!RFC3986]], can be dereferenced to obtain a
JSON-LD context file [[?json-ld11]],
allowing the compact strings in TD Documents to be expanded to full IRI-based
Vocabulary Terms. However, this processing is only required when transforming
JSON-based TD Documents to RDF, an optional feature of TD Processor
implementations.
In the present specification, Vocabulary Terms are always presented in their compact form.
Their expanded form can be accessed under the namespace IRI of the Vocabulary they
belong to. These namespaces follow the structure of .
Each Vocabulary used in the TD Information Model has its own namespace IRI,
as follows:
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#
All vocabularies that are additionally used for Thing Model definitions have the following namespace IRI:
Namespaces used in TMs
Vocabulary
Namespace IRI
Thing Model
https://www.w3.org/2022/wot/tm#
The Vocabularies are independent from each other.
They may be reused and extended in other W3C specifications.
Every breaking change in the design of a Vocabulary
will require the assignment of a new year-based namespace URI.
Note that to maintain the general coherence of the TD Information Model,
the associated JSON-LD context file is versioned such that every version has its own URI
(v1, v1.1, v2, ...)
to also identify non-breaking changes, in particular the addition of new Terms.
Because a Vocabulary under some namespace IRI can only undergo non-breaking
changes, its content can be safely cached or embedded in applications. One
advantage of exposing relatively static content under a namespace IRI is to
optimize payload sizes of messages exchanged between constrained devices. It
also avoids any privacy leakage resulting from devices accessing publicly
available vocabularies from private networks (see also
).
TD Information Model
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 .
the Data SchemaVocabulary, including (a subset of)
the terms defined by JSON Schema [[?JSON-SCHEMA]]
the WoT SecurityVocabulary, identifying security mechanisms
and requirements for their configuration
the Hypermedia ControlsVocabulary, 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
. The main elements of
the TD Information Model are then presented in
. Certain object properties may be
omitted in a TD when Default Values exist. A list of defaults
is given in .
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.
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 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 Terms (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.
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:
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.
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
. In each table of
, 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
and the documentation under the namespace IRIs, e.g.,
https://www.w3.org/2019/wot/td.
Class Definitions
A TD Processor MUST satisfy the
Class instantiation constraints on all Classes defined in
,
,
,
and .
In particular, note that all vocabulary terms and values are case sensitive.
This is also true for the serialization of the information model (Section ).
Core Vocabulary Definitions
Thing
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.
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.
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.
Define URI template variables according to [[RFC6570]] as collection
based on DataSchema declarations. The Thing leveluriVariables can be used in Thing levelforms 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 leveluriVariables and in Interaction Affordance level,
the Interaction Affordance level variable takes precedence.
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.1MAY 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
@contextArray.
Maps contained in an @contextArray 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 @contextArray 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 eventsMaps, a Thing can also
provide meta-interactions, which are indicated by
Form instances in its optional
formsArray.
When
the formsArray 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
propertiesMap 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.
InteractionAffordance
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.
Set of form hypermedia controls that describe
how an operation can be performed. Forms are
serializations of Protocol Bindings. The array cannot be empty.
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 leveluriVariablesand in Interaction Affordance level,
the Interaction Affordance level variable takes precedence.
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.
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.
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
InteractionAffordanceClass and
the DataSchemaClass.
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.
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).
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.
ActionAffordance
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).
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.
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.
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.
ActionAffordance is a Subclass of the
InteractionAffordanceClass.
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.
EventAffordance
An Interaction Affordance that describes an event
source, which asynchronously pushes event data to
Consumers (e.g., overheating
alerts).
EventAffordance is a Subclass of the
InteractionAffordanceClass.
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.
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).
VersionInfo
Metadata of a Thing that provides version information
about the TD document. If required, additional version
information such as firmware and hardware version (term
definitions outside of the TD namespace) can be extended
via the TD Context Extension
mechanism.
It is recommended that the values within instances and model of
the VersionInfoClass 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.
MultiLanguage
A Map providing a set of human-readable texts in different languages identified by language tags described in [[BCP47]]. See for example usages of this container in a Thing Description instance.
Each name of the MultiLanguageMap MUST be a language tag as defined in [[!BCP47]]. Each value of the MultiLanguageMap MUST be of type string.
Data Schema Vocabulary Definitions
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]].
A JSON Schema [[?JSON-SCHEMA]] processor for JSON Schema draft 7
can consume a data 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
, otherwise these terms are semantically ignored by TD Processors
(for details about semantic processing, please refer to
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 ) 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.
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).
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.
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 anytype (e.g., const, default) follow data types compatible with JSON Schema (boolean, integer, number, string, object, array, or null).
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.
ArraySchema
Metadata describing data of type Array. This
Subclass is indicated by the
value array assigned to type in
DataSchema instances.
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)
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.
NullSchema
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.
Security Vocabulary Definitions
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
in this document and in the Security Considerations
section of [[wot-architecture11]].
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.
A security configuration corresponding to identified
by the Vocabulary Termnosec (i.e., "scheme":
"nosec"), indicating there is no authentication or
other mechanism required to access the resource.
AutoSecurityScheme
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).
ComboSecurityScheme
A combination of other security schemes identified by the Vocabulary Termcombo (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 allOfvocabulary 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.
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.
Basic Authentication [RFC7617]
security configuration identified by the Vocabulary Termbasic (i.e.,
"scheme": "basic"), using an unencrypted
username and password.
string (one of header, query, body, cookie, or auto)
DigestSecurityScheme
Digest Access Authentication [RFC7616]
security configuration identified by the Vocabulary Termdigest (i.e.,
"scheme": "digest"). This scheme is similar
to basic authentication but with added features to avoid
man-in-the-middle attacks.
API key authentication security configuration
identified by the Vocabulary Termapikey (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.
string (one of header, query, body, cookie, uri, or auto)
BearerSecurityScheme
Bearer Token [RFC6750]
security configuration identified by the Vocabulary Termbearer (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.
string (one of header, query, body, cookie, or auto)
PSKSecurityScheme
Pre-shared key authentication security configuration
identified by the Vocabulary Termpsk (i.e., "scheme":
"psk").
This is meant to identify that a standard is used for pre-shared keys such as TLS-PSK [[RFC4279]],
and that the ciphersuite used for keys will be established during protocol negotiation.
OAuth 2.0 authentication security configuration
for systems conformant with [[!RFC6749]] and [[!RFC8252]], identified
by the Vocabulary Termoauth2 (i.e.,
"scheme": "oauth2").
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.
For
the code flow both authorization and tokenvocabulary terms
MUST be included.For
the client flow tokenvocabulary term MUST be included.For the
client flow authorizationvocabulary 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
Hypermedia Controls Vocabulary Definitions
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).
Link
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.
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").
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.
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).
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]]).
Refers to a Thing that controls the context Thing.
W3C Thing Description
Form
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.
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. .
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.
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.
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.
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.
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.
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
MUST be restricted to the values in the
table below.
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.
Mapping op Values to Data Schemas
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.
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
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.
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]].
Response-related Terms Usage
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
ExpectedResponseClass 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 summarize these cases in a concise manner.
ExpectedResponse
Communication metadata describing the expected
response message for the primary response.
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.
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
TD Representation Format
WoT Thing Descriptions represent Things and are modeled and structured based on
.
This section defines a JSON-based representation format for Things,
a serialization of instances of the ClassThing defined by the TD Information Model.
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
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.
Mapping to JSON Types
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
(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 .
Omitting Default Values
A Thing Description serialization may omit Vocabulary Term
for which Default Values are defined,
as listed in the table given in .
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.
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 .
Information Model Serialization
Thing Root Object
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 for details).
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:
All values assigned to
version,
securityDefinitions,
descriptions,
schemaDefinitions,
uriVariables,
properties,
actions, and
events
in an instance of the ClassThing
MUST be serialized as JSON objects.
All values assigned to
links, and
forms
in an instance of the ClassThing
MUST be serialized as JSON arrays containing JSON objects
as defined in
and , respectively.
The value assigned to
security
in an instance of ClassThing
MUST be serialized as JSON string or as JSON array whose elements are JSON strings.
Human-Readable Metadata
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 , 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.
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.
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 MultiLanguageMap
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 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:
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.
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 ,
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.
version
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:
The version member is intended as container for additional application- and/or device-specific version information based
on TD Context Extensions. See for details.
securityDefinitions and security
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 SecuritySchemeSubclass'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.
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:
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.
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.
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:
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.
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.
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.
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:
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.
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.
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 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 .
A snippet for two Property affordances is given below:
actions
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 ClassDataSchema,
whose serialization is defined in .
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 .
A TD snippet of an Action affordance is given below:
events
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 ClassDataSchema,
whose serialization is defined in .
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 .
A TD snippet of an Event object is given below:
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 illustrates how Events can use subscription and cancellation to describe Webhooks.
links
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 .
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:
To point to a developer documentation of a Thing the value service-doc can be used:
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 .
A TD snippet of a form object in the forms array is given below:
uriVariables
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 ClassDataSchema,
whose serialization is defined in .
A TD snippet using a URI Template for query parameters and uriVariables in the
Interaction Affordance level is given below:
{
"@context": "https://www.w3.org/2022/wot/td/v1.1",
// ...
"properties": {
"weather": {
// ...
"uriVariables": {
"lat": {
"type": "number",
"minimum": 0,
"maximum": 90,
"description": "Latitude for the desired location in the world" },
"long": {
"type": "number",
"minimum": -180,
"maximum": 180,
"description": "Longitude for the desired location in the world" }
},
"forms": [{
"href": "http://example.org/weather/{?lat,long}",
"htv:methodName": "GET"
}]
},
// ...
},
// ...
}
Alternatively, as defined in [[RFC6570]], uriVariables can be used for replacing the href structure.
An example TD is provided below where a valid request to get the forecast of Bogota, Colombia would be an HTTP GET
request to http://example.org/weather/bogota:
The two examples below can be also combined, while using the same uriVariables feature.
An HTTP GET request to http://example.org/weather/bogota/?unit=Celsius can be described as follows:
{
"@context": "https://www.w3.org/2022/wot/td/v1.1",
// ...
"properties": {
"weather": {
// ...
"uriVariables": {
"city": {
"type": "string",
"description": "City name to find the weather information for"
},
"unit": {
"type": "string",
"enum": ["fahrenheit_value","celsius_value"],
"description": "Desired unit for the temperature value"
}
},
"forms": [{
"href": "http://example.org/weather/{city}/{?unit}",
"htv:methodName": "GET"
}]
},
// ...
},
// ...
}
uriVariables are mainly for properties and events. When retrofitting an existing system, it may be necessary to use
uriVariables for actions. In general, it is recommended to avoid uriVariables as much as possible when a
new WoT-based system is designed.
contentType
The contentType member is used to assign a media type [[!RFC2046]]
including media type parameters as attribute-value pairs separated by a ; character.
Example:
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:
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:
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.
contentMediaType and contentEncoding
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:
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.
Thing-level uriVariables can be used here to supply further variables to the operation or to specify
a list of Property Affordance names for a readmultipleproperties operation.
In the example below, the unit for the properties can be set via such a variable and the desired list of properties
can be set:
{
// ...
"properties": {
"temperature": {
"type": "number",
"forms": [...]
},
"brightness": {
"type": "number",
"forms": [...]
},
"humidity": {
"type": "integer",
"forms": [...]
}
},
"uriVariables": {
"propertyNames": {
"type": "string",
"description": "Comma separated list of property names to select."
},
"unitSystem": {
"type": "string",
"enum": ["metric_value","imperial_value","uscustomary_value"],
"description": "System of Measurement that will be used for the values"
}
},
"forms": [{
"op": "readallproperties",
"href": "https://mything.example.com/properties{?unitSystem}",
"contentType": "application/json",
"htv:methodName": "GET"
},
{
"op": "readmultipleproperties",
"href": "https://mylamp.example.com/properties{?propertyNames,unitSystem}",
"contentType": "application/json",
"htv:methodName": "GET"
}]
}
For a readmultipleproperties operation, an example HTTP GET request to the URI
https://mylamp.example.com/properties?propertyNames=humidity,temperature&unitSystem=metric would return
the values humidity and temperature Property Affordances, with the metric
System of Measurement.
In the case of operation type writeallproperties, it is expected that the Consumer provides all writable (non readOnly) properties and the (new) assigned values (e.g., within payload).
Similarly, for the writemultipleproperties operation type, it is expected that the Consumer provides writable (non readOnly) properties.
On the Thing side, Thing is expected to return readable (non writeOnly) properties in the case of readmultipleproperties and readallproperties operation types.
Data Schemas
The data schemas of the WoT Thing Description defined through the
DataSchemaClass
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 DataSchemaSubclass'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.
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:
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 for an example.
Identification
The JSON-based serialization of Thing Descriptions is identified by
the media type application/td+json or the
CoAP Content-Format ID 432 (see ).
Validation
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 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.
Minimal Validation
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.
Basic Validation
This level of validation includes all those covered by
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
Full validation confirms that all the assertions in this document
are satisfied,
including the assertions given in 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.
TD Context Extensions
In addition to the standard Vocabulary definitions in
,
the WoT Thing Description offers the possibility to add context knowledge
from additional namespaces.
This mechanism can be used to enrich the Thing Description
instances with additional (e.g., domain-specific) semantics.
It can also be used to import additional Protocol Bindings
or new security schemes in the future.
For such TD Context Extensions, the Thing Descriptions use the @context
mechanism known from JSON-LD [[?json-ld11]].
When using TD Context Extensions,
the value of @context of the ClassThing
is an Array with additional elements of type anyURI identifying JSON-LD context files
or Map containing namespace IRIs as defined in .
The serialization rules for complex types in
define the serialization of an extended @context name-value pair.
A snippet with TD Context Extensions is given below:
TD Context Extensions allow for the use of additional Vocabulary Terms in a Thing Description instance.
If the included namespaces are based on Class definitions
such as those provided by the RDF Schema or OWL,
they can be used to annotate any Class instance of a Thing Description semantically
by associating the instance to a such an external Class definition.
This is done by assigning a Class name to the @type name-value pair or
including Class name in its Array value for multiple associations/annotations.
Following the serialization rules in ,
@type is either serialized as a JSON string or as a JSON array.
@type is the JSON-LD keyword [[?json-ld11]] used to set the type of a node.
TD Context Extensions also allow the inclusion of additional name-value pairs
and well-defined values within any Class instance of a Thing Description.
These pairs and values are defined through the included Vocabulary Terms
and are serialized as additional members in the corresponding JSON objects
or values of existing members, respectively.
Examples are additional version metadata for the Thing
or units of measure for data items.
The next subsections show some sample usage of different kind of ontologies in Thing Descriptions.
Example I: Additional Basic Metadata
The sample TD snippet below provides additional metadata terms from different
external context files as provided in @context. The version information
container is extended by adding additional version information about the used software (s:softwareVersion).
schema.org is used for providing serial number and organisation information such as the company name of the Thing.
The SAREF ontology is used to provide a semantic context of the
Thing (saref:TemperatureSensor), and for the unit assignment for the temperature property
the Ontology of Units of Measure (OM)
is used.
Please note that these Vocabularies and ontologies are used as examples. Others can be used based on application domain and use case.
In many cases, TD Context Extensions may be used to annotate pieces of a data schema,
to be able to semantically process the state information of the physical world object,
which is represented by the data exchanged during an interaction (e.g., in the payload of a response).
For example, a semantic description of this state information in RDF
can be embedded in the TD Document and pieces of a data schema can be individually annotated
as referring to specific parts of that RDF-modeled state of the physical world object.
The TD snippet below uses SAREF to describe the state of a lamp. The external Vocabulary
Termssn:forProperty, taken from SSN,
the Semantic Sensor Network Ontology [[VOCAB-SSN]], is being used to link the data schema of
the statusProperty with the actual on/off state of the physical
world object.
In , the state of the Thing
is given by the status affordance itself
and possible state changes are given by the toggle affordance.
In other words, the state of the physical world object directly provides the
Interaction Affordances of the Thing. This design is satisfactory for
simple cases. In more elaborate cases, however, several affordances may be available
for the same physical state. In the example above, the fullStatusProperty provides an alternative, more verbose representation for the state
of the lamp.
Example III: Geolocation Annotations
For many use cases like in building, agriculture, or smart city location based data is required. This
information can be provided in the Thing Description in different ways and can be relied on
different kind of location ontologies (e.g.,[[w3c-basic-geo]], schema.org) depending on purpose (e.g., indoor, outdoor).
Also see [[sdw-bp]].
The TD snippet below uses lat and long from the [[w3c-basic-geo]] ontology to
provide static latitude and longitude metadata at Thing's top level.
In some use cases location based metadata have to be provided at the interaction level, e.g.,
as provided as a Property that returns the latest longitude, latitude, and elevation values
based on schema.org:
In case a different name is desired for, e.g., longitude, latitude,
and elevation in the data model, the jsonld:context can be used to link
terms to specific vocabulary from an ontology (also see [[JSON-SCHEMA-ONTOLOGY]], Section 3.3 Defining a JSON-LD context for data instances):
With the TD Context Extensions in a Thing Description,
the communication metadata can be supplemented or new Protocol Bindings added
through additional Vocabulary Terms serialized into JSON objects representing a Form instance.
Please see for additional details.
Adding Security Schemes
Finally, new security schemes that are not included in
can be imported using the TD Context Extension mechanism.
This example uses a fictional ACE security scheme
based on [[?RFC9200]] that is, for this example,
defined by the namespace at http://www.example.org/ace-security#.
Additional security schemes MUST be Subclasses of the
ClassSecurityScheme.
Note that all security schemes defined in
are already part of the TD context and need not to be included through a TD Context Extension.
Behavioral Assertions
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.
Security Configurations
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.
Data Schemas
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.
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, ).
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.
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.
Protocol Binding based on HTTP
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.
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
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
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:
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.
Other Protocol Bindings
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 ).
Please refer to [[?WOT-BINDING-TEMPLATES]] for information on how to describe IoT platforms and ecosystems.
Thing Model
Basic Concept
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).
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 to validate TM instances that are serialized as JSON.
Thing Model Declaration
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 . 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 ).
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.
shows a valid sample lamp Thing Model without any protocol and security information.
Modeling Tools
In the context of Thing Model definitions specific features are introduced that can be used for Thing modelling.
Versioning
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.
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 ).
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.
Extension and Import
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 () or using the context extension concept
(). 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 eventsMap 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 for further explanation).
Lets assume we have a basic model description as provided in the following example:
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:
Please note that the title is overwritten and will be used when TD instances are created (also see in the next subsection ).
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.
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 into the new property definition
switch.
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.
{
"@context": "https://www.w3.org/2022/wot/td/v1.1",
"@type": "tm:ThingModel",
"title": "Multi Sensor",
"properties": {
"genericTemperature": {
"type": "number",
"unit": "C"
},
"innerTemperature": {
"tm:ref": "#/properties/genericTemperature",
"title": "The inner temperature",
"minimum": 10
},
"outerTemperature": {
"tm:ref": "#/properties/genericTemperature",
"title": "The outer temperature",
"description": "The outer temperature is measured in Kelvin",
"unit": "K"
}
},
"tm:optional": [
"/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
.
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 and imports
the status and dim definitions from and
respectively.
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.
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.
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 ).
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:
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.
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.
{
"@context": ["https://www.w3.org/2022/wot/td/v1.1"],
"@type": "tm:ThingModel",
"title": "Lamp Thing Model",
"description": "Lamp Thing Model Description",
"tm:optional": [
"/events/overheating"
],
"properties": {
"status": {
"description": "current status of the lamp (on|off)",
"type": "string",
"readOnly": true
}
},
"actions": {
"toggle": {
"description": "Turn the lamp on or off"
}
},
"events": {
"overheating": {
"description": "Lamp reaches a critical temperature (overheating)",
"data": {"type": "string"}
}
}
}
Since the Eventoverheating 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:
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.
Derivation of Thing Description Instances
Thing Models can be used as templates to generate a Thing Description based on the restrictions defined in
Sections and . 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 and .
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 .
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 ) 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 and/or .
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 ), as shown in the following example:
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 ).
Examples
The following Thing Model extends the model as shown in and
overwrites the maximum value of the dim property
In general the security measures taken to protect a WoT
system will depend on the threats and attackers that system
may face and the value of the assets that need to be protected.
A detailed discussion of security (and privacy) considerations for the Web of Things,
including a threat model that can be adapted to various circumstances, is
presented in the informative document [[WOT-SECURITY-GUIDELINES]].
Many WoT Things are similar to and use the same technologies as web services.
In addition to the specific security considerations below,
the security risks and mitigations discussed in
guides such as the OWASP Top 10 [[OWASP-Top-10]] for web services should be
evaluated, and if applicable, addressed.
This section discusses only security risks
and possible mitigations directly relevant to the WoT Thing Description.
A WoT Thing Description can describe both secure and
insecure network interfaces. When a Thing Description is
retro-fitted to an existing network interface, no change in the
security status of the network interface is to be expected.
The use of a WoT Thing Description introduces
the security risks given in the following sections.
After each risk, we suggest some possible mitigations.
TD Interception and Tampering
Intercepting and tampering with TDs can be used to launch man-in-the-middle attacks,
for example by rewriting URLs in TDs to redirect accesses to a malicious
intermediary that can capture or manipulate data.
Mitigation:
Thing Descriptions SHOULD be obtained only through
mutually authenticated secure channels.
Mutual authentication
ensures that the Consumer and the TD provider are both sure of the
identity of the other party to the communication.
However, mutual authentication also can be used to identify the
Consumer, which may be undesirable in some cases (privacy risk).
In cases where the Consumer is associated
with a person, e.g. browsers, TDs MAY be obtained
through a channel where only the TD provider is authenticated.
Context Interception and Tampering
Intercepting and tampering with context definition
files can be used to facilitate attacks
by modifying the interpretation of vocabulary.
Context extensions
(see )
that are loaded from the Web over non-secure connections,
such as HTTP, run the risk of being altered by an attacker, and
may modify the TD Information Model in ways that could
compromise security.
As recommended in
,
on constrained implementations
context definition files should be pre-installed and managed
using a secure software
update process and the context URLs only used to identify
known contexts, not to fetch them.
This consideration therefore applies only when fetching context definition
files dynamically is otherwise unavoidable, for example in a directory
service supporting general semantic processing.
Mitigation:
Ideally context definition files would only be obtained through secure
channels established by mutual authentication
but it is notable (and unfortunate) that many contexts are indicated using
"plain" HTTP URLs.
However, the HTTP protocol is vulnerable to interception and modification if
used without first establishing a secure transport channel using TLS.
If it is necessary to fetch a context definition file,
an implementation should first attempt to use HTTP over TLS
even when only an HTTP URL is given.
Limited Duration Accesses
In some scenarios,
it may be desirable to limit the scope and duration of
access to a set of Things by some users.
For example, if A is visiting B's house, B may
want to provide A with temporary and limited access to the garage door opener and
car charger so A can use them.
The scope however may be limited so that A cannot access
certain administrative functions of these Things (for example, to change how long
the garage door can remain open, or to change the charging rate).
In addition, the access should expire after A is expected to have left,
e.g. after one week.
Mitigations:
To limit the scope and duration of access to Things, tokens SHOULD
be used to manage access.
Note that this includes mechanisms such as OAuth2, which provide
for token generation flows where verifying the authentication and
authorization of a user is handled by a separate token provider
service.
Token provider services (which could be managed directly
by the Thing's administrator if
appropriate or desired for privacy) can
provide limited duration tokens and use scopes to limit access.
Scopes can limit access to specific interactions but
are not sufficient to limit duration.
See [[?RFC9200]].
Vulnerability Auditing
An attacker with access to a set of TDs, for example those returned by
WoT Discovery, may be able to use this information to identify vulnerable devices
and plan attacks on them.
Mitigation:
Deployers of IoT systems can use the same information to audit their IoT systems
and ensure that vulnerable systems are adequately protected (if necessary
by external means such as transport security and/or segmented networks) or hardened.
It is also possible to not make the TDs for known-vulnerable systems available
via discovery. This is, however, not a recommended
approach since security by obscurity is a poor defence: an attacker can still
discover the system by other means, even if the TD has limited distribution.
The definition of "vulnerable" however depends on the context
in which the information is made available, and to whom it is made available to.
Ideally, only those with the rights to access the Things
described by TDs should get access to those TDs.
The auto security scheme MAY be used if vulnerability
scanning is a concern.
Script Injection
Many strings given in TDs, in particular the values carried in
title/titles
and
description/descriptions,
are meant to be human-readable.
An application may take
such strings and use them to generate a user interface,
for example, a web dashboard listing a set of
available Things with their titles and descriptions.
If such an interface is naively generated using
string substitution, for example inserting the values of these strings into
marked places in a HTML template to create final HTML, any HTML
markup in the original string will be interpreted in the context
of the browser displaying the dashboard.
It is possible for an attacker to embed scripts in HTML in
various ways and have these scripts executed upon user interaction or even automatically (e.g. upon
page load, or upon an error, which can be done intentionally).
Since the string will be
generated by the TD producer and the dashboard will be generated by a different origin,
this is a form of cross-site-scripting (XSS) attack.
Mitigation:
Strings sourced from TDs should be treated like any other source of external string
when generating HTML: with care.
As a matter of policy, it is strongly suggested that
strings sourced from TDs either be sanitized using a carefully vetted HTML
sanitizer that disables any markup or be inserted into an HTML template using
DOM node manipulation APIs that will escape any markup.
It is also possible that strings sourced from TDs could be used to generate documents
in other markup languages, such as MD files or XML.
Such usages should take equivalent
precautions to ensure that string values are sanitized before insertion in a template.
Unfortunately such sanitization also will disable any HTML markup included for
internationalization purposes,
for example to set the initial direction of text rendering in
bidirectional text.
HTML markup SHOULD NOT be used for internationalization purposes in TD strings.
JSON Parsing
See RFC 8259, section 12: JSON should not be parsed as JavaScript using eval().
A WoT Thing Description is intended to be a pure data exchange format for
Thing metadata, not for holding executable content.
An (invalid) TD may, however, contain JavaScript code that,
when executed, could have side effects compromising the security of a system.
Mitigation:
A WoT Thing Description JSON-LD serialization MUST NOT be passed through a
code execution mechanism such as JavaScript's eval()
function to be parsed.
There are additional code injection risks discussed in
[[WOT-DISCOVERY]]. Other strings in TDs, such as the values given for
title and description, should be sanitized before being
used in templates for SQL, HTML, or other executable contexts.
This risk, however, is specifically about the Javascript injection risk
when parsing JSON.
JSON-LD Expansion
JSON-LD processing usually includes the replacement of short terms with
longer IRIs [[RFC3987]].
For this reason, WoT Thing Descriptions may expand considerably when processed using
a JSON-LD 1.1 processor and, in the worst case, the resulting data
might consume all of the recipient's resources or cause an exploitable
buffer overflow.
Mitigation:
Consumers SHOULD
set and enforce limits on
memory usage to prevent buffer overflow and resource exhaustion
during JSON-LD processing.
Privacy Considerations
Privacy risks will depend on the association of
Things with identifiable people and both the direct information and
the inferred information available from such an association.
A detailed discussion of privacy (and security) considerations for the Web of Things,
including a threat model that can be adapted to various circumstances, is
presented in the informative document [[WOT-SECURITY-GUIDELINES]].
This section discusses only privacy risks
and possible mitigations directly relevant to the WoT Thing Description.
The use of a WoT Thing Description introduces
the privacy risks given in the following sections.
After each risk, we suggest some possible mitigations.
Context Fetching
WoT Thing Descriptions can be evaluated with a
JSON-LD 1.1 processor [[json-ld11]],
which typically follows links to remote contexts (i.e., TD context
extensions, see )
automatically, resulting in the transfer of files
without the explicit request of the Consumer for each one.
If remote
contexts are served by third parties, it may allow them to gather
usage patterns or similar information leading to disclosure
of private information, or information that can be used to infer
private information.
In the case of the WoT, an attacker can also observe the network
traffic produced by such fetches and can use the metadata
of the fetch, such as the destination IP address,
to infer information about the device,
especially if domain-specific vocabularies are used.
This is a risk even if the connection
is encrypted, and is related to DNS privacy leaks.
See also ,
which is a related security risk which can also be avoided with the
following mitigations.
Mitigation:
Implementations on resource-constrained devices are expected
to perform raw JSON processing (as opposed to JSON-LD processing)
and support only a limited set of domain-specific extensions.
The set of supported extensions can be established by a
WoT Profile [[WOT-PROFILE]], for example.
Constrained implementations SHOULD use vetted
versions of their supported context extensions
managed statically or as part of a secure update process.
Constrained implementations SHOULD NOT follow links to remote contexts.
In this case the URLs are used only to identify extensions,
not to fetch their definitions.
Immutable Identifiers
A Thing Description containing an identifier (id) may
describe a Thing that is associated with an identifiable
person. Such identifiers pose various risks including tracking.
However, if the identifier is also immutable, then the
tracking risk is amplified, since a device
may be sold or given to another person and the known ID used to
track that person.
Mitigation:
All identifiers used in a TD SHOULD be mutable,
and in particular there SHOULD be a mechanism to update the id
of a Thing when necessary.
Specifically,
the id of a Thing should not be fixed in hardware.
This does, however, conflict with the Linked Data ideal that
identifiers are fixed URIs.
However, as a matter of policy, it is strongly suggested that deployments
update identifiers upon major changes in configuration or reinitialization.
Examples of major changes in configuration include moving a Thing to a new
local area network, assigning a new domain name,
or unregistering the Thing from one hub and registering it with a new
one. Generally, changes in configuration indicating a potential change
in ownership should result in a new identifier being created.
If more frequent changes are desired during
the operational phase of a device,
a mechanism can be put into place to notify only authorized users
of the change in identifier when a change is made.
Note however that some classes of devices, e.g., medical devices,
may require immutable IDs by law in some jurisdictions.
Ideally, any required immutable identifiers should only be
made available via affordances, such as a property, whose value can
only be obtained after appropriate authentication and
authorization, and managed separately from the TD identifier.
If it is necessary to use an immutable identifier as the TD identifier,
extra attention should be paid to secure
access to files, such as Thing Descriptions, containing such
immutable identifiers.
Fingerprinting
As noted above, the id member in a TD can pose a privacy risk.
However, even if the id is updated as described to mitigate its
tracking risk, it may still be possible to associate
a TD with a particular physical device, and from there to an identifiable person,
through fingerprinting.
Even if a specific device instance cannot be identified through fingerprinting,
it may be possible to infer the type of a device from the information in the TD, such
as the set of interactions, and use this type to infer private information about an
identifiable person, such as a medical condition.
Mitigation:
Only authorized users SHOULD be provided access
to the Thing Description for a Thing.
Only the amount of
information needed for the level of authorization and the use case
SHOULD be provided in a TD.
If the TD is only distributed to authorized users
through secure and confidential channels, for
example through a directory service that requires authentication,
then external unauthorized parties will not have access to the TD to fingerprint it.
To further mitigate this risk, information not necessary for a particular
use case of a TD should be omitted whenever possible. For example,
for an ad-hoc connection to a device where the Consumer does
not store state about the Thing, the id can be omitted.
If the Consumer does not need certain interactions for its use case,
they can be omitted.
If the Consumer is not authorized to use certain interactions,
they can likewise be omitted.
ID Metadata
The value of the id field of a TD might become available to
entities that do not have access to the full TD. If the value of the id
contains embedded metadata, such as the type of the device or the owner, this
could be used to infer personal information.
Mitigation:
The value of the id of a TD SHOULD NOT contain metadata
describing the Thing or from the TD itself.
Any temporary ID generated to manage TDs, for example an ID for a database
or directory service, SHOULD NOT contain metadata
describing the Thing or from the TD itself.
Using random UUIDs as recommended in
also mitigates this
risk.
Globally Unique Identifiers
Globally unique identifiers pose a privacy risk if a centralized authority is needed to
create and distribute them, since then a third party has knowledge of the identifiers.
Mitigation:
The id field in TDs is intentionally not required to be globally unique.
There are several cryptographic mechanisms (e.g. random UUIDs) available to generate suitable IDs in a
distributed fashion that do
not require a central registry. These mechanisms typically have a very low probability
of generating duplicate identifiers, and this needs to be taken into account in the system
design; for example, by detecting duplicates and regenerating IDs when necessary.
The scope of IDs also does not need to be global: it is acceptable to use identifiers
that only distinguish Things in a certain context, such as within a home or factory.
TD identifiers SHOULD be generated using a distributed mechanism such as UUIDs
that provides a high probability of uniqueness.
TD identifiers SHOULD NOT be generated using a centralized authority.
Inferencing of Personally Identifiable Information
In many locales, in order to protect the privacy of users,
there are legal requirements for the handling of
personally identifiable information,
that is,
information that can be associated with a particular person.
Such information can of course be generated by IoT devices directly.
However,
the existence and metadata of IoT devices
(the kind of data stored in a Thing Description)
can also contain or be used to infer personally identifiable information.
This information can be as simple as the fact that a certain person owns a certain
type of device,
which can lead to additional inferences about that person.
Mitigation:
As a matter of policy, it is strongly suggested that
Thing Descriptions associated with
personal devices be treated as if they contained
personally identifiable information, even if this information is not explicit.
As an example application of this principle,
consider how to obtain user consent.
Consent for usage of personally identifiable data
generated by a Thing is often obtained when a Thing is paired with system
consuming the data,
which is frequently also when the Thing Description
is registered with a local directory or the system consuming the
Thing Description in order to access the device.
In this case, consent for using data from a Thing can be combined with
consent for accessing the Thing Description of the Thing.
As a second example, if we consider a TD to contain personally
identifiable information, then it should not be retained indefinitely
or used for purposes other than those for which consent was given.
Comment: An MQTT client frequently publishes the illuminance data (number is serialized in text format) to
the topic /illuminance by the MQTT broker running behind the address 192.168.1.187:1883.
Context Extensions: use HTTP Protocol Binding supplements (htv prefix already included in TD context)
Offered affordances: 1 Event
Security: none
Protocol Binding: HTTP
Comment: WebhookThing provides an Event affordance temperature
which periodically pushes the latest temperature value to the Consumer using a Webhook mechanism,
where the Thing sends POST requests to a callback URI provided by the Consumer.
To describe this, the subscription member defines a write-only parameter callbackURL,
which must be submitted through the subscribeevent form.
The read-only parameter subscriptionID is returned by the subscription.
The WebhookThing will then periodically POST to this callback URI with a payload defined by data.
To unsubscribe, the Consumer has to submit the unsubscribeevent form with the subscriptionID as described in cancellation.
Alternatively, uriVariables approache can be used that informs the Consumer to include the subscriptionID string
into the URI that have to be called with the delete method (see tab 'With uriVariables'). In such setup, the cancellation container can be obmitted.
In general, this example can be further automated by using a TD Context Extension to include proper semantic annotations.
Instead of a periodic POST request to the Thing, the Consumer may provide response data with information when the next POST request should be
provided by the Thing.
This is described by using the dataResponse field.
JSON Schema for TD Instance Validation
A JSON Schema [[?JSON-SCHEMA]] document for syntactically validating Thing Description instances serialized in JSON based format is available at https://www.w3.org/2022/wot/td-schema/v1.1.
This JSON Schema does not require the terms with Default Values to be present. Thus, the terms with Default Values are optional. (see also )
The Thing Description defined by this document allows for
adding external vocabularies by using @context mechanism
known from JSON-LD [[?json-ld11]], and the terms in those external vocabularies can be
used in addition to the terms defined in .
For this reason, the below JSON schema is intentionally non-strict in that
regard. You can replace the value of additionalProperties schema
property true with false in different scopes/levels in
order to perform a stricter validation in case no external vocabularies are used.
contentType usage in Thing Descriptions
The different cases on the variation of request and response are explained at .
The tables below summarize these cases in a concise manner.
The tables start from simpler cases, such as single contentType, and go for more complex cases,
such as multiple contentTypes.
In all the tables, the messages are seen from the Thing point of view, where input means messages sent from
Consumer to the Thing (e.g., request) and output means messages sent from Thing to the Consumer (e.g., response).
The cases are numbered, which can be used to associate them with examples after the tables.
Single contentType case, where both input and output use the same contentType
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.
The following table takes into account further variations that are relevant for cases where an operation input can
accept different contentTypes or the output can return different contentTypes.
There can be cases where an Interaction Affordance has multiple forms.
Such cases with multiple forms should be treated as a combination of the cases in the table above and below.
Multiple contentType case, where input and output can use different contentTypes and there can be multiple
forms
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 contentTypes.
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 contentTypes
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 contentTypes 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.
JSON-LD Context Usage
The present specification introduces the TD Information Model
as a set of constraints over different Vocabularies, i.e. sets of
Vocabulary Terms. This section briefly explains how a machine-readable
definition of these constraints can be integrated into client applications,
by making use of the mandatory @context of a TD document.
Accessing the TD Information Model from a TD document is done in
two steps. First, clients must retrieve a mapping from JSON strings to IRIs.
This mapping is defined as a JSON-LD context, as explained later. Second, clients
can access the constraints defined on these IRIs by dereferencing them.
Constraints are defined as logical axioms in the RDF format, readily interpretable
by client programs.
All Vocabulary Terms referenced in
are serialized as (compact) JSON strings in a TD document. However, each of these
terms is unambiguously identified by a full IRI, as per the first Linked Data
principle [[LINKED-DATA]]. The mappings from JSON keys to IRIs is what the
@context value of a TD points to. For instance, the file at
This JSON file follows the JSON-LD 1.1 syntax [[JSON-LD11]].
Numerous JSON-LD libraries can automatically process the @context of a TD
and expand all the JSON strings it includes.
Once every Vocabulary Term of a TD is expanded to a IRI, the second step
consists in dereferencing this IRI to get fragments of the TD Information Model
that refer to that Vocabulary Term. For instance, dereferencing the IRI
results in an RDF document stating that the term ObjectSchema is a
Class and more precisely, a sub-class of DataSchema. Such
logical axioms are represented in RDF using formalisms of various complexity:
here, sub-class relations are expressed as RDF Schema axioms [[RDF-SCHEMA]].
Moreover, these axioms may be serialized in various formats. Here, they are
serialized in the Turtle format [[TURTLE]]:
<https://www.w3.org/2019/wot/json-schema#ObjectSchema>
a rdfs:Class .
<https://www.w3.org/2019/wot/json-schema#ObjectSchema>
rdfs:subClassOf <https://www.w3.org/2019/wot/json-schema#DataSchema> .
By default, if a user agent does not perform any content negotiation, a human-readable
HTML documentation is returned instead of the RDF document. To negotiate content,
clients must include the HTTP header Accept: text/turtle in their request.
Recent Specification Changes
Changes from the Proposed Recommendation 11 July 2023
Adjusted affiliations of former editors.
Added informative sentence to explain that Data Schema can be parsed by conventional JSON Schema validators.
Reworded an assertion by removing a double negation so that it is easier to understand.
Added stable links for JSON Schema resources.
Removed addressed editor's notes and converted notes for the readers to normal notes.
Changes from the Candidate Recommendation 19 January 2023
At-risk assertions that did not receive sufficient implementations were removed or converted to informative statements.
device flow in OAuth2SecurityScheme was removed, together with its
associated assertions.
Remove introductory paragraphs about at risk assertions.
Add captions to all tables
Add definitions of different levels of TD such as Thing Level
Convert editor's notes to normal notes.
Add default value alternatives to examples in the appendix.
Changes from Fourth Public Working Draft 3 August 2022
Status of the document Section: add list of at-risk features
All TD examples: fix highlighting problems and improve formatting
add security scheme auto, provide definition what "satisfying" a securityDefinition means and new wording of assertion (td-security-no-secrets) in Section
Section has been newly added.
Remove TD Context Extensions CoAP example in Section
Remove reference to Binding Document in assertion (bindings-requirements-scheme) in Section
Chapter moved before and
The term tm:required changed to
Section : add CoAP Content-Format ID for Thing Model
Changes from Third Public Working Draft 11 March 2022
In section it was made clear that all
vocabulary terms and values are case sensitive.
In section the rules for @context were
clarified by stating that TD 1.1 consumers must accept TD 1.0 TDs.
In section the term synchronous
was added.
In section it was clarified that null
does not mean the absence of a value.
The section with the corresponding
"scheme": "auto" was added to indicate that the security
parameters are going to be negotiated by the underlying protocols at runtime.
In section the vocabulary term hreflang
was added that to specify the language of a linked document.
The section was added which
summarizes the available data schema related terms with the op
keywords.
In section and the according
subsections the text has been revised and improved following the latest
security guidelines. Moreover, new sections about
,
,
,
, and
have been added.
In section and the according
subsections the text has been revised and improved following the latest
security guidelines. In addition, a new section about
was added.
In section it was made explicit
that tm:extends and the import mechanism based on
tm:ref supports transitive extension.
The section was added to provide
Thing Model registration information.
The section was split into
and .
In appendix the JSON Schema is
now linked instead of being included in the specification itself.
Changes from Second Public Working Draft 7 June 2021
In section , new namespace IRI is provided for Thing Description 1.1.
In section :
The type definition of titles and descriptions members that appear in sub-sections , , and were clarified.
In section :
In section :
The allowed values for the op member of a Form were expanded.
The description of the forms term was clarified.
The value used for @context has changed in Thing Description 1.1.
The rule in the use of @context for Thing Description 1.1 to be able to be consumed by TD 1.0 consumers are specified.
In section :
Clarifed that property can be retrieved and/or updated.
An additional note was appended for clarification.
In section :
The allowed values of the op member of a Form were expanded.
In section :
The description of the unit term was clarified.
The vocabulary terms contentEncoding and contentMediaType were moved to
section .
In section :
In section , the assignment of the in member was clarified.
In section , the assignment of the in and qop member was clarified.
In section , the assignment of the in member was clarified.
In section , the assignment of the alg, format and in member was clarified.
In section , a new value tm:submodel was added to the table describing the values used for relation types.
In section :
The assignment of the op term was clarified.
Values subscribeallevents, unsubscribeallevents, queryallactions, queryaction and cancelaction were added to the type definition of op term.
A table was added to describe the values of op term.
In section , default assignments were added to PropertyAffordance class's observable member and AdditionalExpectedResponse class's contentType member.
In section :
In section , the value used for @context has changed in Thing Description 1.1.
In section :
Examples were reordered, then the section was partitioned into sub-sections to make the section easier to read.
In section , the flow that appears in now uses client as a value.
In section , more examples were added.
A sub-section describing canonicalization was removed.
In section , additional terms are used in the example.
In section :
Added a reference to the Binding Templates specification to clarify href semantics.
A note was appended for clarification.
In section :
In section , a paragraph was added to describe a consideration in the use of versioning.
In section :
The syntax and processing rule of tm:ref was clarified.
was added.
Section was added.
Section is now after section . (order reversed)
In appendix , the example and its description were updated.
In appendix , the text of the second note was updated for clarification.
Changes from First Public Working Draft 24 November 2020
The editors would like to specially thank Cristiano Aguzzi, Thomas Jäckle, Jan Romann, Elodie Thiéblin, Michael Koster, Michael Lagally, Kazuyuki Ashimura, Daniel Peintner, Toru Kawaguchi, María Poveda, Dave Raggett, Kunihiko Toumura, Takeshi Yamada, Ben Francis, Manu Sporny, Klaus Hartke, Addison Phillips, Jose M. Cantera, Tomoaki Mizushima, Soumya Kanti Datta and Benjamin Klotz for providing contributions, guidance and expertise.
Also, many thanks to the W3C staff and all other current and former active Participants of the W3C Web of Things Interest Group (WoT IG) and Working Group (WoT WG) for their support, technical input and suggestions that led to improvements to this document.
Finally, special thanks to Joerg Heuer for leading the WoT IG for 2 years from its inception and guiding the group to come up with the concept of WoT building blocks including the Thing Description.
