This document describes a formal model and a common representation for a Web of Things (WoT) Thing Description. A Thing Description describes the metadata and interfaces ofThings, where aThing 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 aboutThings in a machine-understandable way. A Thing Description instance can be hosted by theThing itself or hosted externally when aThing has resource restrictions (e.g., limited memory space) or when a Web of Things-compatible legacy device is retrofitted with a Thing Description.
GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them topublic-wot-wg@w3.org (archives).
TheInteraction Model ofW3C WoT defines three types ofInteraction 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-ARCHITECTURE] for details.
In general, the TD provides metadata for differentProtocol 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 theInteraction Model with Properties, Actions, and Events by describing a lampThing with the titleMyLampThing.
From this TD example, we know there exists oneProperty affordance with the titlestatus. 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 URIhttps://mylamp.example.com/status (announced within theforms structure by thehref 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, anAction affordance is specified to toggle the switch status using the POST method on thehttps://mylamp.example.com/toggle resource, where POST is again a default assumption for invoking Actions.
TheEvent affordance enables a mechanism for asynchronous messages to be sent by aThing. 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 onhttps://mylamp.example.com/oh.
This example also specifies thebasic security scheme, requiring a username and password for access. Note that a security scheme is first given a name insecurityDefinitions and then activated by specifying that name in asecurity 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 theThing level, allowing for the specification of fine-grained access control. It is also possible to use a specialnosec 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 theforms field.Example 2 extends the TD sample from Example 1 by introducing a second defintion in the@context to declare the prefixsaref as referring toSAREF, 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 ofThings and theirInteraction Affordances. In the example below, theThing is labelled withsaref:LightSwitch, thestatusProperty is labelled withsaref:OnOffState and thetoggleAction withsaref:ToggleCommand.
Example2: Thing Description with TD Context Extension for semantic annotations
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§ D. JSON-LD Context Usage and the documentation under the namespace IRIs, e.g.,https://www.w3.org/2019/wot/td).
2. Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key wordsMAY,MUST,MUST NOT,RECOMMENDED,SHOULD, andSHOULD NOT in this document are to be interpreted as described inBCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
The fundamental WoT terminology such asThing,Consumer,Thing Description (TD),Interaction Model,Interaction Affordance,Property,Action,Event,Protocol Binding,Servient,WoT Interface,WoT Runtime, etc. is defined inSection 3 of the WoT Architecture specification [WOT-ARCHITECTURE].
In addition, this specification introduces the following definitions:
TD Context Extension
A mechanism to extendThing Descriptions with additionalVocabulary Terms. It is the basis for semantic annotations and extensions to core mechanisms such as Protocol Bindings, Security Schemes, and Data Schemas.
A system that can serialize some internal representation of aThing Description in a given format and/or deserialize it from that format. ATD Processor must detect semantically inconsistentThing Descriptions, that is,Thing Descriptions that cannot satisfy constraints on theInstance Relation of theThing class. For that purpose, aTD Processor may compute canonical forms ofThing Descriptions in which all possibleDefault Values are assigned. ATD Processor is typically a sub-system of aWoT Runtime. Implementations of a TD Processor may be a TD producer only (able to serialize to TD Documents) or a TD consumer only (able to deserialize from TD Documents).
TD Serialization orTD Document
Textual or binary representation ofThing Descriptions that can be stored and exchanged betweenServients. ATD Serialization follows a given representation format, identified by a media type when exchanged over the network. The default representation format forThing Descriptions is JSON-based as defined by this specification.
A character string. When aTerm is part of aVocabulary, i.e., prefixed by a namespace IRI, it is called aVocabulary Term. For the sake of readability,Vocabulary Terms present in this document are always written in a compact form and not as full IRIs.
In the present specification,Vocabulary Terms are always presented in their compact form. Their expanded form can be accessed under the namespace IRI of theVocabulary they belong to. These namespaces follow the structure of§ 5.3 Class Definitions. EachVocabulary used in theTD Information Model has its own namespace IRI, as follows:
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#
TheVocabularies are independent from each other. They may be reused and extended in otherW3C specifications. Every breaking change in the design of aVocabulary will require the assignment of a new year-based namespace URI. Note that to maintain the general coherence of theTD 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 newTerms.
Because aVocabulary 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§ 9.1 Context Fetching Privacy Risk).
The UML diagram shown next gives an overview of theTD Information Model. It represents all classes as tables and the associations that exist between classes, starting from the classThing, as directed arrows. For the sake of readability, the diagram was split in four parts, one for each of the four baseVocabularies.
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 theTD Information Model accordingly.
All definitions in this section refer tosets, 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, anObject is a data structure recursively defined as follows:
a set of name-value pairs where the name is aTerm and the value is anotherObject, is also anObject.
Though this definition does not preventObjects to include multiple name-value pairs with the same name, they are generally not considered in this specification. AnObject whose elements only have numbers as names is called anArray. Similarly, anObject whose elements only haveTerms (that do not belong to anyVocabulary) as names is called aMap. All names appearing in some name-value pair in aMap are assumed to beunique within the scope of theMap.
On the basis of these two functions, anInstance Relation can be defined for a pair composed of anObject and aClass. This relation is defined as constraints to be satisfied. That is, anObject is an instance of aClass if the two following constraints areboth satisfied:
According to the definition above, anObject would be an instance of everySimple Type, regardless of its structure. Instead, another definition for theInstance Relation is introduced forSimple Types: anObject is an instance of aSimple Type if it is aTerm with a given lexical form (e.g.,true,false for theboolean type,1,2,3, ... for theunsignedInt type, etc.).
Moreover, additionalClasses, calledParameterized Classes, can be derived from the genericMap andArray structures. AnObject is aMap of someClass, that is, an instance of theMap typeparameterized with someClass, if it is aMap such that the value in all the name-value pairs it contains is an instance of thisClass. The same applies toArrays.
Finally, aClass is aSubclass of some otherClass if every instance of the former is also an instance of the latter.
By convention,Simple Types are denoted by names starting with lowercase. TheTD Information Model references the followingSimple Types defined in XML Schema [XMLSCHEMA11-2-20120405]:string,anyURI,dateTime,integer,unsignedInt,double, andboolean. Their definition (i.e., the specification of their lexical form) is outside of the scope of theTD Information Model.
The formalization introduced here does not consider the possible relation betweenObjects as abstract data structures and physical world objects such asThings. However, care was given to the possibility of re-interpreting allVocabulary Terms involved in theTD Information Model as RDF resources, so as to integrate them in a larger model of the physical world (an ontology). For details about semantic processing, please refer to§ D. JSON-LD Context Usage and the documentation under the namespace IRIs, e.g.,https://www.w3.org/2019/wot/td.
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. In this version of TD, all operations that can be described at the Thing level are concerning how to interact with the Thing'sProperties collectively at once.
The@context name-value pairMUST contain the anyURIhttps://www.w3.org/2019/wot/td/v1 either directly when of typeanyURI or as first element when of typeArray.When@context is anArray, the anyURIhttps://www.w3.org/2019/wot/td/v1MAY be followed by elements of typeanyURI or typeMap in any order, while it isRECOMMENDED to include only oneMap with all the name-value pairs in the@contextArray.Maps contained in an@contextArrayMAY contain name-value pairs, where the value is a namespace identifier of typeanyURI and the name aTerm or prefix denoting that namespace.OneMap contained in an@contextArraySHOULD contain a name-value pair that defines the default language for the Thing Description, where the name is theTerm@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).
The computation of the base direction of all human-readable text strings is defined by the following set of rules:
If no language tag is given, the base directionSHOULD be inferred through first-strong heuristics or detection algorithms such as the CLDR Likely Subtags [LDML].
Outside ofMultiLanguageMaps, the base directionMAY be inferred from the language tag of the default language.
Inside ofMultiLanguageMaps, the base direction of each value of the name-value pairsMAY be inferred from the language tag given in the corresponding name.
In cases where a language can be written in more than one script with different base directions, the corresponding language tag given in@language orMultiLanguageMapsMUST include a script subtag, so that an appropriate base direction can be inferred. An example is Azeri, which is written LTR when Latin script is used (specified usingaz-Latn) and RTL when Arabic script is used (specified usingaz-Arab).
TD Processors should be aware of certain special cases when processing bidirectional text. They 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 providedInteraction Affordances in theproperties,actions, andeventsArrays, aThing can also provide meta-interactions, which are indicated byForm instances in its optionalformsArray.When theformsArray of aThing instance containsForm instances, the string values assigned to the nameop, either directly or within anArray,MUST be one of the followingoperation types:readallproperties,writeallproperties,readmultipleproperties, orwritemultipleproperties. (Seean example for an usage ofform in a Thing instance.)
The data schema for each of these meta-interactions is constructed by combining the data schemas of eachPropertyAffordance instance in a singleObjectSchema instance, where thepropertiesMap of theObjectSchema instance contains each data schema of thePropertyAffordances identified by the name of the correspondingPropertyAffordances instance.
If not specified otherwise (e.g., through aTD Context Extension), the request data of thereadmultipleproperties operation is anArray that contains the intendedPropertyAffordances instance names, which is serialized to the content type specified by theForm instance.
An Interaction Affordance that exposes state of the Thing. This state can then be retrieved (read) and optionally 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 theobserveproperty operation for this Property.
Property instances are also instances of the classDataSchema. Therefore, it can contain thetype,unit,readOnly andwriteOnly members, among others.
PropertyAffordance is aSubclass of theInteractionAffordanceClass and theDataSchemaClass.When a Form instance is within aPropertyAffordance instance, the value assigned toopMUST be one ofreadproperty,writeproperty,observeproperty,unobserveproperty or anArray containing a combination of these terms.
5.3.1.4ActionAffordance
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.
ActionAffordance is aSubclass of theInteractionAffordanceClass.When a Form instance is within anActionAffordance instance, the value assigned to opMUST beinvokeaction.
5.3.1.5EventAffordance
An Interaction Affordance that describes an event source, which asynchronously pushes event data toConsumers (e.g., overheating alerts).
EventAffordance is aSubclass of theInteractionAffordanceClass.When a Form instance is within anEventAffordance instance, the value assigned toopMUST be eithersubscribeevent,unsubscribeevent, or both terms within anArray.
5.3.1.6VersionInfo
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 theTD Context Extension mechanism.
It is recommended that the values within instances of theVersionInfoClass 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.
5.3.1.7MultiLanguage
AMap providing a set of human-readable texts in different languages identified by language tags described in [BCP47]. See§ 6.3.2 Human-Readable Metadata for example usages of this container in a Thing Description instance.
Each name of theMultiLanguageMapMUST be a language tag as defined in [BCP47].Each value of theMultiLanguageMapMUST be of typestring.
5.3.2 Data Schema Vocabulary Definitions
The data schema vocabulary definition is reflecting a very common subset of the terms defined by JSON Schema [JSON-SCHEMA]. It is noted that data schema definitions within Thing Description instances are not limited to this defined subset and may use additional terms found in JSON Schema using aTD Context Extension for the additional terms as described in§ 7. TD Context Extensions, otherwise these terms are semantically ignored byTD Processors (for details about semantic processing, please refer to§ D. JSON-LD Context Usage and the documentation under the namespace IRIs, e.g.,https://www.w3.org/2019/wot/td).
A data schema is an abstract notation for data contained in data formats. In a TD, concrete data formats are specified in Forms (see§ 5.3.4.2Form) using content types. When the value of a content type in an instance of the Form isapplication/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 notapplication/json and if no mapping is defined for the content type, specifying a data schema does not make sense for the content type.
5.3.2.1DataSchema
Metadata that describes the data format used. It can be used for validation.
Theformat 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).ServientsMAY use theformat value to perform additional validation accordingly.When a value that is not found in the known set of values is assigned toformat, such a validationSHOULD succeed.
5.3.2.2ArraySchema
Metadata describing data of typeArray. ThisSubclass is indicated by the valuearray assigned totype inDataSchema instances.
Metadata describing data of typestring. ThisSubclass is indicated by the valuestring assigned totype inDataSchema instances.
5.3.2.8NullSchema
Metadata describing data of typenull. ThisSubclass is indicated by the valuenull assigned totype inDataSchema instances. This Subclass describes only one acceptable value, namelynull. It can be used as part of aoneOf declaration, where it is used to indicate, that the data can also benull.
A security configuration corresponding to identified by theVocabulary Termnosec (i.e.,"scheme": "nosec"), indicating there is no authentication or other mechanism required to access the resource.
5.3.3.3BasicSecurityScheme
Basic Authentication [RFC7617] security configuration identified by theVocabulary Termbasic (i.e.,"scheme": "basic"), using an unencrypted username and password. This scheme should be used with some other security mechanism providing confidentiality, for example, TLS.
Digest Access Authentication [RFC7616] security configuration identified by theVocabulary 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 theVocabulary Termapikey (i.e.,"scheme": "apikey"). This is for the case where the access token is opaque and is not using a standard token format.
Bearer Token [RFC6750] security configuration identified by theVocabulary Termbearer (i.e.,"scheme": "bearer") for situations where bearer tokens are used independently of OAuth2. If theoauth2 scheme is specified it is not generally necessary to specify this scheme as well as it is implied. Forformat, the valuejwt indicates conformance with [RFC7519],jws indicates conformance with [RFC7797],cwt indicates conformance with [RFC8392], andjwe indicates conformance with [RFC7516], with values foralg interpreted consistently with those standards.Other formats and algorithms for bearer tokensMAY be specified in vocabulary extensions.
OAuth2 authentication security configuration for systems conformant with [RFC6749] and [RFC8252], identified by theVocabulary Termoauth2 (i.e.,"scheme": "oauth2").For thecode flow bothauthorization andtokenMUST be included. If noscopes are defined in theSecurityScheme then they are considered to be empty.
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 anOAuth2SecurityScheme active on that form.
The present model provides a representation for (typed) Web links and Web forms exposed by aThing. TheLink class definition is reflecting 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 anotherThing such as aLamp Thing is controlled by aSwitch Thing. TheForm class corresponds to a newly introduced form of hypermedia control to manipulate the state ofThings (and other Web resources).
5.3.4.1Link
A link can be viewed as a statement of the form "link context has arelation type resource atlink target", where the optionaltarget attributes may further describe the resource.
A form can be viewed as a statement of "To perform anoperation type operation onform context, make arequest method request tosubmission target" where the optionalform fields may further describe the required request. In Thing Descriptions, theform context is the surrounding Object, such as Properties, Actions, and Events or the Thing itself for meta-interactions.
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.
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. .
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.
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 anOAuth2SecurityScheme 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 response messages.
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-ARCHITECTURE]. Future versions of the standard may extend this list butoperations typesSHOULD NOT be arbitrarily set by servients.
The optionalresponse 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 noresponse name-value pair is provided, itMUST be assumed that the content type of the response is equal to the content type assigned to the Form instance. Note thatcontentType within anExpectedResponseClass does not have aDefault Value. For instance, if the value of the content type of the form isapplication/xml the assumed value of the content type of the response will be alsoapplication/xml.
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 optionalresponse 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, theForm instanceMUST include a name-value pair with the nameresponse. For instance, anActionAffordance could only acceptapplication/json for its input data, while it will respond with animage/jpeg content type for its output data. In that case the content types differ and theresponse name-value pair has to be used to provide response content type (image/jpeg) information to theConsumer.
5.3.4.3ExpectedResponse
Communication metadata describing the expected response message.
Array ofstring with the elementsreadproperty andwriteproperty
If defined within an instance ofPropertyAffordance
Form
op
invokeaction
If defined within an instance ofActionAffordance
Form
op
subscribeevent
If defined within an instance ofEventAffordance
BasicSecurityScheme
in
header
DigestSecurityScheme
in
header
BearerSecurityScheme
in
header
APIKeySecurityScheme
in
query
DigestSecurityScheme
qop
auth
BearerSecurityScheme
alg
ES256
BearerSecurityScheme
format
jwt
6. TD Representation Format
WoT Thing Descriptions represent Things and are modeled and structured based on§ 5. TD Information Model. This section defines a JSON-based representation format forThings, a serialization of instances of theClassThing defined by theTD Information Model.
The JSON serialization of theTD Information Model is aligned with the syntax of JSON-LD 1.1 [json-ld11] in order to streamline semantic evaluation. Hence, the TD representation format can be processed either as raw JSON or with a JSON-LD 1.1 processor (for details about semantic processing, please refer to§ D. JSON-LD Context Usage and the documentation under the namespace IRIs, e.g.,https://www.w3.org/2019/wot/td).
In order to support interoperable internationalization,TDsMUST be serialized according to the requirements defined in Section 8.1 of RFC8259 [RFC8259] for open ecosystems. In summary, this requires the following:
ImplementationsMUST NOT add a byte order mark (U+FEFF) to the beginning of a TD document.
TD ProcessorsMAY ignore the presence of a byte order mark rather than treating it as an error.
6.1 Mapping to JSON Types
TheTD Information Model is constructed, so that there is an easy mapping between modelObjects and JSON types. EveryClass instances maps to a JSON object, where each name-value pair of theClass instance is a member of the JSON object.
EverySimple Type mentioned in§ 5.3 Class Definitions (i.e.,string,anyURI,dateTime,integer,unsignedInt,double, andboolean) 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 typestring oranyURIMUST be serialized as JSON strings.
Values that are of typedateTimeMUST be serialized as JSON strings following the "date-time" format specified by [RFC3339]. Examples would include2019-05-24T13:12:45Z and2015-07-11T09:32:26+08:00.Values that are of typedateTimeSHOULD use the literalZ representing the UTC time zone instead of an offset.
Values that are of typeinteger orunsignedIntMUST be serialized as JSON numbers without a fraction or exponent part.
Values that are of typedoubleMUST be serialized as JSON number.
Values that are of typebooleanMUST be serialized as JSON boolean.
Every complex type of theTD Information Model (i.e.,Arrays,Maps, andClass instances) maps to a structured JSON type (array and object), as per the rules listed below:
A value of typeArrayMUST 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 typeMapMUST be serialized as JSON object, with each name-value pair as member of the JSON object.
The following example shows the TD instance fromExample 1 with a checkbox to also include the members withDefault Values (=checkbox checked). These members can be omitted (=checkbox unchecked) to simplify the TD serialization. Note that aTD Processor interprets these omitted members identically as if they were explicitly present with a givenDefault Value.
Please note that, depending on theProtocol Binding used, additional protocol-specificVocabulary Terms may apply. They may also have associatedDefault Values, and hence can also be omitted as explained in this subsection. Further information can be found in§ 8.3 Protocol Bindings.
6.3 Information Model Serialization
6.3.1 Thing Root Object
A Thing Description is a data structure rooted at anObject of typeThing. In turn, a JSON serialization of the Thing Description is a JSON object, which is the root of a syntax tree constructed from theTD Information Model.
The root element of aTD SerializationMUST be a JSON object that includes a member with the name@context and a value of type string or array that equals or respectively containshttps://www.w3.org/2019/wot/td/v1.
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 indicatesTD Context Extensions (see§ 7. TD Context Extensions for details).
All name-value pairs of an instance ofThing, where the name is aVocabulary Term in theSignature ofThing,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 toversion,securityDefinitions,properties,actions, andevents in an instance of theClassThingMUST be serialized as JSON objects.
All values assigned tolinks, andforms in an instance of theClassThingMUST be serialized as JSON arrays containing JSON objects as defined in§ 6.3.8links and§ 6.3.9forms, respectively.
The value assigned tosecurity in an instance ofClassThingMUST be serialized as JSON string or as JSON array whose elements are JSON strings.
6.3.2 Human-Readable Metadata
JSON members namedtitle anddescription are used within a TD document to provide human-readable metadata. They can be used as comments for developers inspecting a TD document or as display texts for user interface.
As defined in§ 5.3.1.1Thing, 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 valueMUST be processed independently. In other words, aTD 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.
Note
Strings on the Web [STRING-META] suggests both strong-first and language-based inferencing as means to determine the base text direction. Given that the Thing Description format is based on JSON-LD 1.1 [json-ld11], which currently lacks explicit direction metadata, these approaches are currently considered appropriate at the time of this publication. However, if JSON-LD 1.1 adopts support for explicit base direction metadata as recommended by [STRING-META], the Thing Description format should be updated to take advantage of that feature.
A TD snippet usingtitle anddescription is shown below. The default language is set toen through the definition of the@language member within a JSON object in the@context array.
The JSON members namedtitles anddescriptions are used within the TD document to provide human-readable metadata in multiple languages within a single TD document.All name-value pairs of aMultiLanguageMapMUST be serialized as members of a JSON object, where the name is a well-formed language tag as defined by [BCP47] and the value is a human-readable string in the language indicated by the tag. See§ 5.3.1.7MultiLanguage for details.AllMultiLanguage object within a TD documentSHOULD contain the same set of language members.
A TD snippet usingtitles anddescriptions at different levels is given below:
TD instances may also combine the use oftitle anddescription withtitles anddescriptions.Whentitle andtitles ordescription anddescriptions are present within the same JSON object, the values oftitle anddescriptionMAY be seen as the default text.Whentitle andtitles ordescription anddescriptions are present in a TD document, eachtitle anddescription memberSHOULD have a correspondingtitles anddescriptions 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 theAccept-Language header field of HTTP.In cases where the default language has been negotiated, an@language memberMUST 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 documentsSHOULD include the appropriate matching values for the memberstitle anddescription in preference toMultiLanguage objects intitles anddescriptions members.Note however that ThingsMAY choose to not support such dynamically-generated TDs nor to support language negotiation (e.g., because of resource constraints).
6.3.3version
All name-value pairs of an instance ofVersionInfo, where the name is aVocabulary Term included in theSignature ofVersionInfo,MUST be serialized as JSON members with theVocabulary Term as name.
A TD snippet of a version information object is given below:
In aThing instance, the value assigned tosecurityDefinitions is aMap of instances ofSecurityScheme.All name-value pairs of aMap ofSecurityScheme instancesMUST be serialized as members of the JSON object that results from serializing theMap; the name of a pairMUST be serialized as a JSON string and the value of the pair, an instance ofSecurityScheme,MUST be serialized as a JSON object.
All name-value pairs of an instance of one of theSubclasses ofSecurityScheme, where the name is aVocabulary Term included in theSignature of thatSubclass or in theSignature ofSecurityScheme,MUST be serialized as members of the JSON object that results from serializing theSecuritySchemeSubclass's instance, with theVocabulary Term as name.
The following TD snippet shows a simple security configuration specifying basic username/password authentication in the header. The value given forin is actually theDefault Value (header) and could be omitted. A named security configuration must be given in thesecurityDefinitions map. That definition must be activated by including its JSON name in thesecurity member, which can be of type string when only one definition is activated.
Here is a more complex example: a TD snippet showing digest authentication on a proxy combined with bearer token authentication on theThing. In thedigest scheme, theDefault Value ofin (i.e.,header) is omitted, but still applies. Note that the corresponding private security configuration such as username/password and tokens must be configured in theConsumer to interact successfully. When activating multiple security definitions, thesecurity member becomes an array.
Security configuration in the TD is mandatory.At least one security definitionMUST be activated through thesecurity array 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 theThing.Security definitionsMAY also be activated at the form level by including asecurity member in form objects, which overrides (i.e., completely replace) all definitions activated at the Thing level.
Thenosec security scheme is provided for the case that no security is needed. The minimal security configuration for aThing is activation of thenosec security scheme at the Thing level, as shown in the following example:
To give a more complex example, suppose we have aThing where allInteraction Affordances require basic authentication except for one, for which no authentication is required. For thestatus Property and thetoggle Action,basic authentication is required and defined at the Thing level. For theoverheating Event, however, no authentication is required, and hence the security configuration is overridden at the form level.
Security configurations can also can be specified for different forms within the sameInteraction 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 samesecurity member combines them in an "AND" fashion, since in that case they would all need to be satisfied to allow activation of theInteraction Affordance. Note that activating one (default) configuration at the Thing level is still mandatory.
As another more complex example, OAuth2 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 (orInteraction Affordance in the case ofW3C WoT). For example, in the following, thestatus Property can be read byConsumers using bearer tokens containing the scopelimited, but theconfigure Action can only be invoked with a token containing thespecial 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. In this example, an administrator would probably be issued tokens with both thelimited andspecial scopes, while ordinary users would only be issued tokens with thelimited scope.
The value assigned toproperties in aThing instance is aMap of instances ofPropertyAffordance.All name-value pairs of aMap ofPropertyAffordance instancesMUST be serialized as members of the JSON object that results from serializing theMap; the name of a pairMUST be serialized as a JSON string and the value of the pair, an instance ofPropertyAffordance,MUST be serialized as a JSON object.
All name-value pairs of an instance ofPropertyAffordance, where the name is aVocabulary Term included in (one of) theSignatures ofPropertyAffordance,InteractionAffordance, orDataSchema,MUST be serialized as members of the JSON object that results from serializing thePropertyAffordance instance, with theVocabulary Term as name. See§ 6.3.10 Data Schemas for details on serializingDataSchema instances.
The value assigned toforms in an instance ofPropertyAffordanceMUST be serialized as a JSON array containing one or more JSON object serializations as defined in§ 6.3.9forms.
A snippet for twoProperty affordances is given below:
In aThing instance, the value assigned toactions is aMap of instances ofActionAffordance.All name-value pairs of aMap ofActionAffordance instancesMUST be serialized as members of the JSON object that results from serializing theMap; the name of a pairMUST be serialized as a JSON string and the value of the pair, an instance ofActionAffordance,MUST be serialized as a JSON object.
All name-value pairs of an instance ofActionAffordance, where the name is aVocabulary Term included in (one of) theSignatures ofActionAffordance orInteractionAffordance,MUST be serialized as members of the JSON object that results from serializing theActionAffordance instance, with theVocabulary Term as name.
The values assigned toinput andoutput in an instance ofActionAffordanceMUST be serialized as JSON objects. They rely on theClassDataSchema, whose serialization is defined in§ 6.3.10 Data Schemas.
The value assigned toforms in an instance ofActionAffordanceMUST be serialized as a JSON array containing one or more JSON object serializations as defined in§ 6.3.9forms.
A TD snippet of an Action affordance is given below:
..."actions": {"fade" : {"title":"Fade in/out","description":"Smooth fade in and out animation.","input": {"type":"object","properties": {"from": {"type":"integer","minimum":0,"maximum":100 },"to": {"type":"integer","minimum":0,"maximum":100 },"duration": {"type":"number"} },"required": ["to","duration"], },"output": {"type":"string"},"forms": [...] }},...
6.3.7events
In aThing instance, the value assigned toevents is a map of instances ofEventAffordance.All name-value pairs of aMap ofEventAffordance instancesMUST be serialized as members of the JSON object that results from serializing theMap; the name of a pairMUST be serialized as a JSON string and the value of the pair, an instance ofEventAffordance,MUST be serialized as a JSON object.
All name-value pairs of an instance ofEventAffordance, where the name is aVocabulary Term included in (one of) theSignatures ofEventAffordance orInteractionAffordance,MUST be serialized as members of the JSON object that results from serializing theEventAffordance instance, with theVocabulary Term as name.
The values assigned tosubscription,data, andcancellation in an instance ofEventAffordanceMUST be serialized as JSON objects. They rely on theClassDataSchema, whose serialization is defined in§ 6.3.10 Data Schemas.
The value assigned toforms in an instance ofEventAffordanceMUST be serialized as a JSON array containing one or more JSON object serializations as defined in§ 6.3.9forms.
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 andcancellation can be defined according to the desired mechanism. Please find further details in [WOT-BINDING-TEMPLATES]. Example§ A.3 Webhook Event Example illustrates how Events can usesubscription andcancellation to describe Webhooks.
6.3.8links
All name-value pairs of an instance ofLink, where the name is aVocabulary Term included in theSignature ofLink,MUST be serialized as members of the JSON object that results from serializing theLink instance, with theVocabulary Term as name.
A TD snippet of a link object in thelinks array is given below:
All name-value pairs of an instance ofForm, where the name is aVocabulary Term included in theSignature ofForm,MUST be serialized as members of the JSON object that results from serializing theForm instance, with theVocabulary Term as name.
href may also carry a URI that contains dynamic variables such as p and d in http://192.168.1.25/left?p=2&d=1. In that case the URI can be defined as template as defined in [RFC6570]:http://192.168.1.25/left{?p,d}.
In such a case, the URI Template variablesMUST be collected in the JSON-object baseduriVariables member with the associated (unique) variable names as JSON names.
The serialization of each value in the map assigned touriVariables in an instance ofFormMUST rely on theClassDataSchema, whose serialization is defined in§ 6.3.10 Data Schemas.
A TD snippet using a URI Template anduriVariables is given below:
ThecontentType 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 theInteraction Affordance not only describes the request, but also provides metadata for the expected response. For instance, an ActiontakePhoto defines aninput 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, theresponse member is used to indicate the representation format of the response payload (e.g.,"contentType": "image/jpeg"). Here nooutput schema is required, as the content type fully specifies the representation format.
If present, the value assigned toresponse in an instance ofFormMUST be a JSON object.If present, the response objectMUST contain acontentType member as defined in theClass definition ofExpectedResponse.
Aform snippet with theresponse member is shown below based on thetakePhoto Action described above:
Whenforms is present at the top level, it can be used to describe meta interactions offered by aThing. For example, the operation types "readallproperties" and "writeallproperties" are for meta interactions with aThing by whichConsumers can read and write all properties at once. In the example below, aforms member is included in the TD root object and theConsumer can use the submission targethttps://mylamp.example.com/allproperties both to read or write all Properties (i.e.,on,brightness, andtimer) of theThing in a single protocol transaction.
In the case of operation typewriteallproperties, it is expected that theConsumer provides all writable (nonreadOnly) properties and the (new) assigned values (e.g., within payload). Similarly, for thewritemultipleproperties operation type, it is expected that theConsumer provides writable (nonreadOnly) properties. On theThing side,Thing is expected to return readable (nonwriteOnly) properties in the case ofreadmultipleproperties andreadallproperties operation types.
6.3.10 Data Schemas
The data schemas of the WoT Thing Description defined through theDataSchemaClass 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 withThings.
Data schema serialization applies toPropertyAffordance instances, the values assigned toinput andoutput inActionAffordance instances, the values assigned tosubscription,data, andcancellation inEventAffordance instances, and the value assigned touriVariables in instances ofSubclasses ofInteractionAffordance (when aform object uses a URI Template).
All name-value pairs of an instance of one of theSubclasses ofDataSchema, where the name is aVocabulary Term included in theSignature of thatSubclass or in theSignature ofDataSchema,MUST be serialized as members of the JSON object that results from serializing theDataSchemaSubclass's instance, with theVocabulary Term as name.
The value assigned toproperties in an instance ofObjectSchemaMUST be serialized as a JSON object.
The values assigned toenum,required, andoneOf in an instance ofDataSchemaMUST be serialized as a JSON array.
The value assigned toitems in an instance ofArraySchemaMUST 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., forinput andoutput) or a Property object, which would contain additional members.
The termsreadOnly andwriteOnly can be used 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 workaround when Properties of an unconventionalThing 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 ofreadOnly andwriteOnly is given below:
When thestatus Property is read, the status data is returned using alatestStatus member in the payload. To update thestatus Property, the new value must be provided through anewStatusValue member in the payload.
As an additional feature, a Thing Description instance allows the usage of aunit 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-knownVocabularies. See§ 7. TD Context Extensions for an example.
6.4 Identification
The JSON-based serialization of Thing Descriptions is identified by the media typeapplication/td+json or the CoAP Content-Format ID432 (see§ 10. IANA Considerations).
7. TD Context Extensions
This section is non-normative.
In addition to the standardVocabulary definitions in§ 5. TD Information Model, 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 additionalProtocol Bindings or new security schemes in the future.
For suchTD Context Extensions, the Thing Descriptions use the@context mechanism known from JSON-LD [json-ld11]. When usingTD Context Extensions, the value of@context of theClassThing is an Array with additional elements of typeanyURI identifying JSON-LD context files orMap containing namespace IRIs as defined in§ 5.3.1.1Thing.
TD Context Extensions allow for additionalVocabulary Terms to a Thing Description instance. If the included namespaces are based onClass definitions such as those provided by the RDF Schema or OWL, they can be used to annotate anyClass instance of a Thing Description semantically by associating the instance to a such an externalClass definition. This is done by assigning aClass name to the@type name-value pair or includingClass name in itsArray value for multiple associations/annotations. Following the serialization rules in§ 6.1 Mapping to JSON Types,@type is either serialized as JSON string or as 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 anyClass instance of a Thing Description. These pairs and values are defined through the includedVocabulary Terms and are serialized as additional members in the corresponding JSON objects or values of existing members, respectively. Examples are additional version metadata for theThing or units of measure for data items.
As an example, the TD snippet given below extends the version information container by adding version numbers for the hardware and firmware of theThing, and uses values from externalVocabularies for theThing and for the data schema unit:SAREF, also used inExample2, andOM, the Ontology of Units of Measure [RIJGERSBERG]. TheseVocabularies are used as examples—others may exist, in particular in the home automation domain.
{"@context": ["https://www.w3.org/2019/wot/td/v1", {"v":"http://www.example.org/versioningTerms#","saref":"https://w3id.org/saref#","om":"http://www.ontology-of-units-of-measure.org/resource/om-2/" } ],"version": {"instance":"1.2.1","v:firmware":"0.9.1","v:hardware":"1.0" }, ..."@type":"saref:TemperatureSensor","properties": {"temperature": {"description":"Temperature value of the weather station","type":"number","minimum":-32.5,"maximum":55.2,"unit":"om:degree_Celsius","forms": [...] }, ... }, ...}
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 theTD 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 externalVocabulary Termssn:forProperty, taken fromSSN, the Semantic Sensor Network Ontology [VOCAB-SSN], is being used to link the data schema of thestatusProperty with the actual on/off state of the physical world object.
InExample2, the state of theThing is given by thestatus affordance itself and possible state changes are given by thetoggle affordance. In other words, the state of the physical world object directly provides theInteraction Affordances of theThing. 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, thefullStatusProperty provides an alternative, more verbose representation for the state of the lamp.
The following TD example uses a fictional CoAPProtocol Binding, as no suchProtocol Binding is available at the time of writing this specification. ThisTD Context Extension assumes that there is aCoAP in RDF vocabulary similar toHTTP Vocabulary in RDF 1.0 [HTTP-in-RDF10] that is accessible via an example namespacehttp://www.example.org/coap-binding#. The supplementedcov:methodName member instructs theConsumer which CoAP method has to be applied (e.g.,GET for the CoAP Method Code 0.01,POST for the CoAP Method Code 0.02, oriPATCH for CoAP Method Code 0.07).
Example30: Specialization of forms through TD Context Extension
Finally, new security schemes that are not included in§ 5.3.3 Security Vocabulary Definitions can be imported using theTD Context Extension mechanism. This example uses a fictional ACE security scheme based on [ACE] that is, for this example, defined by the namespace athttp://www.example.org/ace-security#. Note that such additional security schemes must beSubclasses of theClassSecurityScheme.
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 must be interpreted as constraints on the TD to accurately represent such interfaces.
8.1 Security Configurations
To enable secure interoperation, security configurations must accurately reflect the requirements of theThing:
If aThing requires a specific access mechanism for an interaction, that mechanismMUST be specified in the security configuration of the Thing Description.
If aThing does not require a specific access mechanism for an interaction, that mechanismMUST 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.
8.2 Data Schemas
The data schemas provided in the TD should accurately represent the data payloads returned and accepted by the describedThing 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 theThing not given explicitly in the WoT Thing Description. In general,Things aredescribed by WoT Thing Descriptions, butConsumers areconstrained to follow WoT Thing Descriptions when interacting withThings.
AThing acting as aConsumer when interacting with another targetThing described in a WoT Thing DescriptionMUST generate data organized according to the data schemas given in the corresponding interactions.
A WoT Thing DescriptionMUST accurately describe the data returned and accepted by each interaction.
AThingMAY 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 toObjectSchema andArraySchema (whenitems is an Array ofDataSchema) 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].
AThing acting as aConsumer when interacting with anotherThingMUST accept without error any additional data not described in the data schemas given in the Thing Description of the targetThing. This applies toObjectSchema andArraySchema (whenitems is an Array ofDataSchema) 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].
AThing acting as aConsumer when interacting with anotherThingMUST NOT generate data not described in the data schemas given in the Thing Description of thatThing.
AThing acting as aConsumer when interacting with anotherThingMUST generate URIs according to the URI Templates, base URIs, and form href parameters given in the Thing Description of the targetThing.
URI Templates, base URIs, and href members in a WoT Thing DescriptionMUST accurately describe theWoT Interface of theThing.
Every form in a WoT Thing Description must have a submission target, given by thehref member. The URI scheme of this submission target indicates whatProtocol Binding theThing implements [WOT-ARCHITECTURE]. For instance, if the target starts withhttp orhttps, aConsumer can then infer theThing implements theProtocol Binding based on HTTP and it should expect HTTP-specific terms in the form instance (see next section,§ 8.3.1 Protocol Binding based on HTTP).
Every form in a WoT Thing DescriptionMUST follow the requirements of theProtocol Binding indicated by the URI scheme of itshref member.
Every form in a WoT Thing DescriptionMUST accurately describe requests (including request headers, if present) accepted by theThing in an interaction.
8.3.1 Protocol Binding based on HTTP
Per default the Thing Description supports theProtocol Binding based on HTTP by including the HTTP RDF vocabulary definitions fromHTTP Vocabulary in RDF 1.0 [HTTP-in-RDF10]. This vocabulary can be directly used within TD instances by the usage of the prefixhtv, which points tohttp://www.w3.org/2011/http#. Further details ofProtocol Binding based on HTTP can be found in [WOT-BINDING-TEMPLATES].
To interact with aThing that implements theProtocol Binding based on HTTP, aConsumer 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, theProtocol Binding based on HTTP definesDefault Values for the operation types listed below, which also aims at convergence of the methods expected byThings (e.g., GET to read, PUT to write).When no method is indicated in a form representing anProtocol Binding based on HTTP, aDefault ValueMUST be assumed as shown in the following table.
Please refer to [WOT-BINDING-TEMPLATES] for information on how to describe IoT platforms and ecosystems.
9. Security and Privacy Considerations
This section is non-normative.
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 needs to protect. In addition 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 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]. This section discusses only security and privacy 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 and privacy risks given in the following sections. After each risk, we suggest some possible mitigations.
9.1 Context Fetching Privacy Risk
Fetching the vocabulary files given in the@context member of any JSON-LD [json-ld11] document can be a privacy risk. In the case of the WoT, an attacker can 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.
Mitigation:
Avoid actual fetching of vocabulary files. Vocabulary files should be cached whenever possible. Ideally they would be made immutable, built into the interpreting device, and not fetched at all, with the URI in the@context member serving only as an identifier of the (known) vocabulary. This requires the use of strict version control, as updates should use a new URI to ensure that existing URIs can refer to immutable data. Use well-known standard vocabulary files whenever possible to improve the chances that the context file will be available locally to systems interpreting the metadata in a Thing Description.
9.2 Immutable Identifiers Privacy Risk
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 should be mutable, and there should be a mechanism to update theid of aThing. Specifically, theid of aThing should not be fixed in hardware. This does, however, conflict with the Linked Data ideal that identifiers are fixed URIs. In many circumstances it will be acceptable to only allow updates to identifiers if aThing is reinitialized. In this case as a software entity the oldThing ceases to exist and a newThing is created. This can be sufficient to break a tracking chain when, for example, a device is sold to a new owner. Alternatively, 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. In this case extra attention should be paid to secure access to files, such as Thing Descriptions, containing such immutable identifiers. It may also be desirable to not share the "true" immutable identifier in such a case in the TD whenever possible.
9.3 Fingerprinting Privacy Risk
As noted above, theid member in a TD can pose a privacy risk. However, even if theid 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 aThing, and only the amount of information needed for the level of authorization and the use case should be provided. 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, theid 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. If the Consumer does not have any capability to display human-readable information such as titles or descriptions, they can be omitted or replaced with zero-length strings.
9.4 Globally Unique Identifier Privacy Risk
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:
Theid field in TDs are intentionally not required to be globally unique. There are several cryptographic mechanisms 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.
9.5 TD Interception and Tampering Security Risk
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:
Obtain Thing Descriptions only through mutually authenticated channels. This ensures that theConsumer and the server are both sure of the identity of the other party to the communication. This is also necessary in order to deliver TDs only to authorized users.
9.6 Context Interception and Tampering Security Risk
Intercepting and tampering with context files can be used to facilitate attacks by modifying the interpretation of vocabulary.
Mitigation:
Ideally context files would only be obtained through authenticated channels but it is notable (and unfortunate) that many contexts are indicated using HTTP URLs, which are vulnerable to interception and modification if dereferenced. However, if context files are immutable and cached, and dereferencing is avoided whenever possible, then this risk can be reduced.
9.7 Inferencing of Personally Identifiable Information Privacy Risk
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:
Treat a Thing Description associated with a personal device as if it contained personally identifiable information. As an example application of this principle, consider how to obtain user consent. Consent for usage of personally identifiable data generated by aThing is often obtained when aThing 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 aThing can be combined with consent for accessing the Thing Description of theThing. 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.
Since WoT Thing Description is intended to be a pure data exchange format forThing metadata, the serializationSHOULD NOT be passed through a code execution mechanism such as JavaScript'seval() function to be parsed. An (invalid) document may contain code that, when executed, could lead to unexpected side effects compromising the security of a system.
WoT Thing Descriptions can be evaluated with a JSON-LD 1.1 processor, which typically follows links to remote contexts (i.e., TD context extensions, seeW3C WoT Thing Description, section 7) automatically, resulting in the transfer of files without the explicit request of theConsumer for each one. If remote contexts are served by third parties, it may allow them to gather usage patterns or similar information leading to privacy concerns.While implementations on resource-constrained devices are expected to perform raw JSON processing (as opposed to JSON-LD processing), implementations in generalSHOULD statically cache vetted versions of their supported context extensions and not to follow links to remote contexts. Supported context extensions can be managed through a secure software update mechanism instead.
Context Extensions (seeW3C WoT Thing Description, section 7) that are loaded from the Web over non-secure connections, such as HTTP, run the risk of being altered by an attacker such that they may modify theTD Information Model in a way that could compromise security.For this reason,Consumer againSHOULD vet and cache remote contexts before allowing the system to use it.
Given that JSON-LD processing usually includes the substitution of long IRIs [RFC3987] with short terms, 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.ConsumersSHOULD treat any TD metadata with due skepticism.
{"@context": ["https://www.w3.org/2019/wot/td/v1", {"cov":"http://www.example.org/coap-binding#" } ],"id":"urn:dev:ops:32473-WoTLamp-1234","title":"MyLampThing","description" :"MyLampThing uses JSON serialization","securityDefinitions": {"psk_sc":{"scheme":"psk"}},"security": ["psk_sc"],"properties": {"status": {"description" :"Shows the current status of the lamp","type":"string","forms": [{"op":"readproperty","href":"coaps://mylamp.example.com/status","cov:methodName" :"GET" }] } },"actions": {"toggle": {"description" :"Turn on or off the lamp","forms": [{"href":"coaps://mylamp.example.com/toggle","cov:methodName" :"POST" }] } },"events": {"overheating": {"description" :"Lamp reaches a critical temperature (overheating)","data": {"type":"string"},"forms": [{"href":"coaps://mylamp.example.com/oh","cov:methodName" :"GET","subprotocol" :"cov:observe" }] } }}
A.2 MyIlluminanceSensor Example with MQTT Protocol Binding
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.
Example34: MyIlluminanceSensor with MQTT Protocol Binding
Context Extensions: use HTTPProtocol Binding supplements (htv prefix already included in TD context)
Offered affordances: 1 Event
Security: none
Protocol Binding: HTTP
Comment:WebhookThing provides an Event affordancetemperature which periodically pushes the latest temperature value to theConsumer using a Webhook mechanism, where theThing sends POST requests to a callback URI provided by theConsumer. To describe this, thesubscription member defines a write-only parametercallbackURL, which must be submitted through thesubscribeevent form. The read-only parametersubscriptionID is returned by the subscription. TheWebhookThing will then periodically POST to this callback URI with a payload defined bydata. To unsubscribe, theConsumer has to submit theunsubscribeevent form, which makes use of a URI Template. TheuriVariables member informs theConsumer to include thesubscriptionID string. This can be further automated by using aTD Context Extension to include proper semantic annotations. Alternatively, one can imagine unsubscribing using thecancellation member similarly tosubscription and combine this with aunsubscribeevent form that describes a POST request with payload to unsubscribe.
Example35: Temperature Event with subscription and cancellation
{"@context":"https://www.w3.org/2019/wot/td/v1","id":"urn:dev:ops:32473-Thing-1234","title":"WebhookThing","description":"Webhook-based Event with subscription and unsubscribe form.","securityDefinitions": {"nosec_sc": {"scheme":"nosec"}},"security": ["nosec_sc"],"events": {"temperature": {"description":"Provides periodic temperature value updates.","subscription": {"type":"object","properties": {"callbackURL": {"type":"string","format":"uri","description":"Callback URL provided by subscriber for Webhook notifications.","writeOnly":true },"subscriptionID": {"type":"string","description":"Unique subscription ID for cancellation provided by WebhookThing.","readOnly":true } } },"data": {"type":"number","description":"Latest temperature value that is sent to the callback URL." },"cancellation": {"type":"object","properties": {"subscriptionID": {"type":"integer","description":"Required subscription ID to cancel subscription.","writeOnly":true } } },"uriVariables": {"subscriptionID": {"type":"string" } },"forms": [ {"op":"subscribeevent","href":"http://192.168.0.124:8080/events/temp/subscribe","contentType":"application/json","htv:methodName":"POST" }, {"op":"unsubscribeevent","href":"http://192.168.0.124:8080/events/temp/{subscriptionID}","htv:methodName":"DELETE" } ] } }}
B. JSON Schema for TD Instance Validation
This section is non-normative.
Below is a JSON Schema [JSON-SCHEMA] document for syntactically validating Thing Description instances serialized in JSON based format.
Note
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§ 5. TD Information Model. For this reason, the below JSON schema is intentionally non-strict in that regard. You can replace the value ofadditionalProperties schema propertytrue withfalse in different scopes/levels in order to perform a stricter validation in case no external vocabularies are used.
Note
Please note that some JSON Schema validation tools do not support theiri string format.
AThing Description Template is a description for aclass ofThings. It describes the properties, actions, events and common metadata that are shared for an entire group ofThings, to enable the common handling of thousands of devices by a cloud server, which is not practical on a per-Thing basis. The Thing Description Template uses the same core vocabulary and information model from§ 5. TD Information Model.
The Thing Description Template is a logical description of the interface and possible interaction with devices (properties, actions and events), however it does not contain device-specific information, such as a serial number, GPS location, security information or concrete protocol endpoints.
Since a Thing Description Template does not contain aProtocol Binding to specific endpoints and does not define a specific security mechanism, theforms andsecurityDefinitions andsecurity keys must not be present.
The same Thing Description Template can be implemented byThings from multiple vendors, aThing can implement multiple Thing Description Templates, define additional metadata (vendor, location, security) and define bindings to concrete protocols. To avoid conflicts between properties, actions and events from different Thing Description Templates that are combined into a commonThing, all these identifiers must be unique within aThing.
A common Thing Description Template for a class of devices enables writing applications across vendors and creates a more attractive market for application developers. A concrete Thing Description can implement multiple Thing Description Templates and thus can aggregate function blocks into a combined device.
The business models of cloud vendors are typically built on managing thousands of identical devices. All devices with the same Thing Description Template can be managed in the same way by cloud applications. It is easy to create multiple simulated devices, if the interface and the instance are treated separately.
Since a Thing Description Template is a subset of the Thing Description in which some optional and mandatoryVocabulary Terms do not exist, however, it can be serialized in the same way and in the same formats as a Thing Description. Note that Thing Template instances cannot be validated in the same way as Thing Description instances due to some missing mandatory terms.
C.1 Thing Description Template Examples
This section shows a Thing Description Template for a lamp and a Thing Description Template for a buzzer.
{"@context": ["https://www.w3.org/2019/wot/td/v1"],"@type" :"ThingTemplate","title":"Lamp Thing Description Template","description" :"Lamp Thing Description Template","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"} } }}
C.1.2 Thing Description Template: Buzzer
Example37: MyBuzzerThingTemplate serialized in JSON
{"@context": ["https://www.w3.org/2019/wot/td/v1"],"@type" :"ThingTemplate","title":"Buzzer Thing Description Template","description" :"Thing Description Template of a buzzer that makes noise for 10 seconds","actions": {"buzz": {"description" :"buzz for 10 seconds" } }}
D. JSON-LD Context Usage
This section is non-normative.
The present specification introduces theTD Information Model as a set of constraints over differentVocabularies, i.e. sets ofVocabulary 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 theTD 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.
AllVocabulary Terms referenced in§ 5. TD Information Model 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 everyVocabulary Term of a TD is expanded to a IRI, the second step consists in dereferencing this IRI to get fragments of theTD Information Model that refer to thatVocabulary Term. For instance, dereferencing the IRI
results in an RDF document stating that the termObjectSchema is aClass and more precisely, a sub-class ofDataSchema. 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 headerAccept: text/turtle in their request.
In section§ 8.1 Security Configurations, clarified the interaction between the dynamic authentication information asked by some security protocols and the security configurations information declared in the Thing Description.
At-risk featuresCertSecurityScheme,PublicSecurityScheme,PoPSecurityScheme as well asimplicit,password andclient flows inOAuth2SecurityScheme were removed.
In section§ 6.3.9forms, clarified the expectations ofConsumers andThings for operation typeswritemultipleproperties,readmultipleproperties andreadallproperties.
In section§ 8.3.1 Protocol Binding based on HTTP, the contexts in which default valuesGET orPUT are used for vocabulary termhtv:methodName were clarified.
The editors would like to thank Michael Koster, Michael Lagally, Kazuyuki Ashimura, Ege Korkan, 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.
