Copyright © 2017 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
This document describes a formal model and common representation for a Web of Things (WoT) Thing Description. A Thing Description describes the metadata and interfaces of Things, where a Thing is an abstraction of a physical entity that provides interactions to and participates in the Web of Things. Thing Descriptions provide a narrow-waist 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 JSON-LD. JSON-LD provides both a powerful foundation to represent knowledge about Things and simplicity, since it allows processing as a JSON document. In addition to physical entities, Things can also represent virtual entities. A Thing Description instance can be hosted by the Thing itself or hosted externally due to Thing's resource restrictions (e.g. limited memory space) or when a Web of Things-compatible legacy device is retrofitted with a Thing Description.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
Implementers need to be aware that this specification is considered unstable. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation phase should subscribe to the repository and take part in the discussions.
Please contribute to this draft using the GitHub Issue feature of the WoT Thing Description repository. For feedback on security and privacy considerations, please use the WoT Security and Privacy Issues, as they are cross-cutting over all our documents.
This document was published by the Web of Things Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation.
Comments regarding this document are welcome. Please send them to public-wot-wg@w3.org (subscribe, archives).
Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 March 2017 W3C Process Document.
The W3C Thing Description (TD) is a central building block in a Web of Things (WoT) enabled system and can be considered as the entry point of a Thing (aka the index.html of the Thing). The TD consists of semantic metadata for the Thing itself, a narrow-waist interaction model with WoT's Properties, Actions, and Events, a semantic schema to make data models machine-understandable, and features for Web Linking to express relations among Things.
Properties can be used for controlling (or retrieving) parameters, such as a setting an operation state (or getting the current value). Actions model invocation of physical processes, but can also be used to abstract RPC-like calls of existing platforms. Events cover the push model where state change notifications, discrete events, and streams of values are sent asynchronously to the receiver. In general, the TD provides metadata for the different communication bindings (e.g., HTTP, CoAP, MQTT, etc.), mediaTypes (e.g., "application/json", "application/xml", "application/cbor", "application/exi" etc.), and security policies (authentication, authorization, etc.). The default serialization of the TD is JSON-LD.
Example 1 shows a simple TD instance that describes a lamp Thing with the name MyLampThing.
{
"@context": ["http://w3c.github.io/wot/w3c-wot-td-context.jsonld"],
"@type": ["Thing"],
"name": "MyLampThing",
"interaction": [
{
"@type": ["Property"],
"name": "status",
"outputData": {"type": "string"},
"writable": false,
"link": [{
"href": "coaps://mylamp.example.com:5683/status",
"mediaType": "application/json"
}]
},
{
"@type": ["Action"],
"name": "toggle",
"link": [{
"href": "coaps://mylamp.example.com:5683/toggle",
"mediaType": "application/json"
}]
},
{
"@type": ["Event"],
"name": "overheating",
"outputData": {"type": "string"},
"link": [{
"href": "coaps://mylamp.example.com:5683/oh",
"mediaType": "application/json"
}]
}
]
}
Based on this content, we know there exists one Property interaction resource with the name status. In addition, information is provided such as that this Property is accessible over the CoAP protocol with a GET method (see CoAP protocol
binding description in the W3C WoT protocol template deliverable [XXX]) at coaps://mylamp.example.com:5683/status (announced within the endoind (SP?) structure by the href
key), which
will return a string status value within a JSON structure (JSON as payload format is announced by the mediaType
field).
Further explanation of the example.
The generic WoT terminology is defined in [WOT-ARCHITECTURE]: Thing, Thing Description (in short TD), Web of Things (in short WoT), WoT Interface etc.
The namespace for TD is http://www.w3.org/ns/td#. TD itself defines a minimal set of classes and properties of its own. A full set of namespaces and prefixes used in this document is shown in the table below.
Prefix | Namespace |
---|---|
td | http://www.w3.org/ns/td# |
rdf | http://www.w3.org/1999/02/22-rdf-syntax-ns# |
rdfs | http://www.w3.org/2000/01/rdf-schema# |
xsd | http://www.w3.org/2001/XMLSchema# |
ToDo: complete table
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 words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].
A Thing Description instance complies with this specification if it follows the normative statements in Section 5. Vocabulary Definition.
In case of JSON-LD serialization, a Thing Description instance in JSON-LD format complies with this specification if it follows the normative statements in Section 6. JSON-LD Serialization
We need to be more precise here: How to validate a TD? E.g., structure validation and/or RDF validation? Comments are welcome.
The Thing Description relies on a small set of vocabulary. An overview of this vocabulary with its class context and class relation is given by the following figure.
A detailed description of the vocabulary is given in the next sub-section.
There is an information missing from the tables in subsequent sub-sections as to which vocabulary is optional or mandatory. Since the information is already available in the ontology files, tools need to be updated to extract and utilize this information to generate the content of these tables.
Thing
Describes a physical and/or virtual Thing (may represent one or more physical and / or virtual Things) in the Web of Thing context.
Field Name | Description | Expected value type |
---|---|---|
interaction |
Link from a Thing to the interaction patterns it provides | InteractionPattern |
security |
Links a given Thing to the security information that indicates the access metadata information for securely transmitting information via all the resources of the Thing. | Security |
base |
Define base URI that is valid for all defined local interaction resources. All other URIs in the TD must then be resolved using the algorithm defined in [RFC3986]. This field is optional. | anyURI |
name |
Name of the Thing or interaction pattern (must be a valid keyword to be used in the scripting API) | string |
InteractionPattern
Three interaction patterns are defined as subclasses: Property, Action and Event. When a concrete Property, Action or Event is defined in a Thing Description, it is called an "interaction resource". Interactions between Things can be as simple as one Thing accessing another Thing's data to get or (in the case the data is also writable) change representation of data such as metadata, status or mode. A Thing may also be interested in getting asynchronously notified of future changes in another Thing, or may want to initiate a process served in another Thing that may take some time to complete and monitor the progress. Interactions between Things may involve exchanges of data between them. This data can be either given as input by the client Thing, returned as output by the server Thing or both.
Field Name | Description | Expected value type |
---|---|---|
link |
Indicates the endpoints from which an interaction pattern is accessible | Link |
name |
Name of the Thing or interaction pattern (must be a valid keyword to be used in the scripting API) | string |
The class InteractionPattern
has the following subclasses:
Property
Property provides readable and/or writeable data that can be static (e.g., supported mode, rated output voltage, etc.) or dynamic (e.g., current fill level of water, minimum recorded temperature, etc.). Please note, this class also inherited all vocabulary from the InteractionPattern class.
Field Name | Description | Expected value type |
---|---|---|
outputData |
link to the n-ary class that allows the declaration of the data type and unit of measure provided by an interaction pattern. | DataSchema |
writable |
Boolean value that indicates whether a property is writable (=true) or not (=false) | boolean |
Action
The Action interaction pattern triggers changes or processes on a Thing that take a certain time to complete (i.e., actions cannot be applied instantaneously like property writes). Examples include an LED fade in, moving a robot, brewing a cup of coffee, etc. Usually, ongoing Actions are modelled as Task resources, which are created when an Action invocation is received by the Thing. Please note, this class also inherited all vocabulary from the InteractionPattern class.
Field Name | Description | Expected value type |
---|---|---|
outputData |
link to the n-ary class that allows the declaration of the data type and unit of measure provided by an interaction pattern. | DataSchema |
inputData |
link to the n-ary class that allows the declaration of the data type and unit of measure expected by an interaction pattern. | DataSchema |
Event
The Event interaction pattern enables a mechanism for events to be notified by a Thing on a certain condition (e.g., the fill level of the water tank reached a given threshold). Please note, this class also inherited all vocabulary from the InteractionPattern class.
Field Name | Description | Expected value type |
---|---|---|
outputData |
link to the n-ary class that allows the declaration of the data type and unit of measure provided by an interaction pattern. | DataSchema |
DataSchema
This class embeds JSON Schema declaration in a Linked Data form to allow, e.g., the representation of pairs (data type, semantic meaning such as unit of measure) that are expected as input data or output data of a given interaction pattern.
Link
Communication metadata where a service can be accessed by a client application. An interaction might have more than one link.
Field Name | Description | Expected value type |
---|---|---|
href |
URI of the endpoint where an interaction pattern is provided | anyURI |
mediaType |
Assign underlying media type of the interaction pattern based on IANA (https://www.iana.org/assignments/media-types/media-types.xhtml) | string |
Security
The (optional) security field can be used to provide access metadata (self-contained) information of the Thing for securely transmitting information via all its resources. Also see Section Security Consideration. Definition taken from http://w3c.github.io/wot/current-practices/wot-practices#security
Thing Description instances are modeled on the classes defined in 5. Vocabulary Definition, and they are serialized in JSON-LD by default, using the vocabulary defined there when they are served at run-time. JSON-LD is a serialization format that adds a semantic layer on top of the JSON specification: the terms that appear in a JSON document should be associated with uniquely identified concepts from shared vocabularies. This principle is part of a set of practices to publish data on the Web called Linked Data, where concepts are usually identified with URIs and originate from RDF vocabularies.
The JSON-LD representation for a Thing Description is a JSON object of which fields are defined below.
Field Name | JSON Construct | Mandatory | Description |
---|---|---|---|
@context | array of strings | yes | The array MUST contain a string "https://w3c.github.io/wot/w3c-wot-td-context.jsonld". Also see below. |
@type | array of strings | no | Gives annotations to the Thing |
name | string | yes | Name of the Thing |
base | string | no | Base URI for use in a Thing Description |
interaction | array of objects | no | See 6.2 Interaction Resources |
security | array of objects | no | See 6.4 Security |
Each field in Thing class (see 5.2.1 Thing) is represented by the namesake JSON field described in the above table.
The @context
key is used to define Thing Description's context. All JSON key terms that are defined in the present document (also see Vocabulary Definition Section ) have been put
in an external context document, available at
https://www.w3.org/ns/td/w3c-wot-td-context.jsonld
. Each Thing Description instance in JSON-LD MUST this context information
embedded within an JSON array structure. Thus, a basic Thing Description would contain the following declaration:
{
"@context": ["https://www.w3.org/ns/td/w3c-wot-td-context.jsonld"],
...
}
In case a single Thing Description instance involves several contexts, additional namespaces with prefixes can be extended to the @context
array structure. This option proves relevant if one wants to extend the existing Thing
Description context without modifying it. For instance:
{
"@context": ["https://www.w3.org/ns/td/w3c-wot-td-context.jsonld",
{"sensor": "http://example.org/sensors#"}],
...
}
Note: Besides these pre-defined terms in the Thing Description context, additional characteristics can be added to Thing level such as product ID, firmware version, location, etc. These terms should then appear in the context of the Thing .
This note should be moved to the td-context-extension definition once we have a section for that. In there it should be also explained that a context is not necessary if you are working outside of the RDF model and if you handle a TD just as a simple JSON document.
A sample TD snippet that relies on the defined fields above is given below:
{
"@context": ["https://www.w3.org/ns/td/w3c-wot-td-context.jsonld"],
"@type": ["Thing"],
"name": "MyThing",
"base": "coap://mything.example.com:5683/",
"interaction": [
...
}
Note:For examples of full Thing Description, see 6.7 Examples
An interaction in the context of the Web of Things is an exchange of data between a Web client and a Thing. This data can be either given as input by the client, returned as output by the Thing, or both. Three interaction patterns are defined: Property, Action, and Event.
The Property
interaction definitions (also see Property vocabulary definition section) provides metadata for readable and/or writeable data that can be static (e.g., supported mode, rated output
voltage, etc.) or dynamic (e.g., current fill level of water, minimum recorded temperature, etc.). Shown below is an example of a Property
interaction definition.
{
...
"interaction": [
{
"@type": ["Property"],
"name": "temperature",
"outputData":{ "type": "number" },
"writable": false,
"link": [{
"href" : "coap://mytemp.example.com:5683/temp",
"mediaType": "application/json"
}]
},
...
}
The JSON-LD representation for a Property
interaction definition is a JSON object of which the fields are defined below.
Field Name | JSON Construct | Mandatory | Description |
---|---|---|---|
@type | array of strings | yes | The array MUST start with a string "Property" |
name | string | yes | Name of the Property |
outputData | object | yes | See 6.5 Type System |
writable | boolean | no | a property is writable (=true) or not (=false) |
link | array of objects | no | See 6.3 Link |
Each field in Property class (see 5.2.3 Property) is represented by the namesake JSON field described in the above table.
The Action
interaction pattern (also see Action vocabulary definition section) targets changes or processes on a Thing that take a certain time to complete (i.e., actions cannot be applied instantaneously
like property writes). Examples include an LED fade in, moving a robot, brewing a cup of coffee, etc. Usually, ongoing Actions are modeled as Task resources, which are created when an Action invocation is received by the Thing.
{
...
"interaction": [
{
"@type": ["Action"],
"name": "fadeIn",
"inputData": { "type": "integer" },
"link": [{
"href" : "coap://mytemp.example.com:5683/in",
"mediaType": "application/json"
}]
}
]
...
}
JSON-LD representation for an Action
interaction definition is a JSON object of which the fields are defined below.
Field Name | JSON Construct | Mandatory | Description |
---|---|---|---|
@type | array of strings | yes | The array MUST start with a string "Action" |
name | string | yes | Name of the Action |
outputData | object | no | See 6.5 Type System |
inputData | object | no | See 6.5 Type System |
link | array of objects | no | See 6.3 Link |
Each field in Action class (see 5.2.4 Action) is represented by the namesake JSON field described in the above table.
The Event
interaction pattern (also see Event vocabulary definition section) enables a mechanism to be notified by a Thing on a certain condition. While some protocols such as CoAP can provide such
a mechanism natively, others do not. Furthermore, Events might need a specific configuration that requires data sent and stored on the Thing in a standard way. There are are four mandatory terms defined within the Event
pattern:
{
...
"interaction": [
{
"@type": ["Event"],
"name": "criticalCondition",
"outputData": { "type": "string" },
"link": [{
"href" : "coap://mytemp.example.com:5683/ev",
"mediaType": "application/json"
}]
}
]
...
}
The JSON-LD representation for an Event
interaction definition is a JSON object of which the fields are defined below.
Field Name | JSON Construct | Mandatory | Description |
---|---|---|---|
@type | array of strings | yes | The array MUST start with a string "Event" |
name | string | yes | Name of the Event |
outputData | object | yes | See 6.5 Type System |
link | array of objects | no | See 6.3 Link |
Each field in Event class (see 5.2.5 Event) is represented by the namesake JSON field described in the above table.
This section describes JSON-LD serialization for the instances of the 5.2.7 Link class. Shown below is an example of a link definition.
"link": [
{
"href" : "coap://mytemp.example.com:5683/temp",
"mediaType": "application/json"
}
]
JSON-LD representation for a link definition is a JSON array with name "link". Each item in the array is a JSON object that consists of two JSON fields as summarized below.
Field Name | JSON Construct | Mandatory | Description |
---|---|---|---|
href | string | yes | URI. If a relative URI is given then this URI is relative to base URI. |
mediaType | string | yes | Media type based on IANA |
Each field in Link class (see 5.2.7 Link) is represented by the namesake JSON field described in the above table.
Shown below is an example of a security resource definition.
{
...
"security": {
"cat": "token:jwt",
"alg":"HS256",
"as":"https://authority-issuing.org"
},
...
}
In the above example, a JSON Web Token (JWT) type is assigned (cat
), along with a corresponding hashing algorithm "HS256" (alg
) and the issuing authority of the security token (as
).
Consider the need for a context definition for the above example.
All of the three interaction types Property
, Action
, and Event
can specify the type of the value acceptable as an input or expected as an output of the interaction. In this section, we define an abstract
type system notation based on JSON-LD for describing the structure and datatypes for values of interaction types. While type system is designed to be compatible with JSON schema [draft-zyp-json-schema-04]
[draft-fge-json-schema-validation-00], it is intended to be encoding-neutral and integrates into the Linked Data vocabularies to allow semantic annotations.
It can not only be directly translated into JSON schema, but also can be handily translated into XML Schema. Use of JSON-LD equips the type system with a way to associate data elements with citations and semantic concepts defined elsewhere.
For Property
and Event
interaction types, each property or event can specify its value type using outputData
field within respective interaction type definition. In the following example, temperature
property and criticalCondition
event are defined as number
and string
, respectively.
{
...
"interaction": [
...
{
"@type": ["Property"],
"name": "temperature",
"outputData": { "type": "number" },
...
}
...
{
"@type": ["Event"],
"name": "criticalCondition",
"outputData": { "type": "string" },
...
}
...
]
...
}
Similarly, for Action
interaction type, each action can specify its input and/or output value type using inputData
and outputData
field, respectively. The following is an example value type definition
for an action. In the example, fadeIn
action is defined to have inputData
of type number
and outputData
of type boolean
.
{
...
"interaction": [
...
{
"@type": ["Action"],
"name": "fadeIn",
"inputData": {
"type": "number",
"actuator:unit": "actuator:ms"
},
"outputData": {
"type": "boolean"
},
...
}
...
]
...
}
Within inputData
and outputData
fields, type system allows the following definitions in the type
field:
These type constructs are in parallel to those that are available in JSON schema. Therefore, serialization of data exchanged between servients is straightforward when it is in JSON format.
Consider the following inputData
definition which defines the value to be an integer
within the value range of [ 0 ... 255 ].
"inputData": {
"type": "integer",
"minimum": 0,
"maximum": 255,
}
When the integer
being exchanged is 184, data serialization in JSON format will look like the following:
184
The snippet in the above example is a valid JSON document according to the syntax defined in [RFC7159], which allows sending simple types in the root of the document. There is no need for wrapping a single value into an object.
The same data (i.e. a number equal to 184) will look like the following when the data is exchanged in XML.
<integer>184</integer>
In the previous section, we used an example inputData
definition consisting of a single integer
.
With the type system, it is also possible to define value types that have more than one literal value. The type system provides two distinct constructs to define a structure that can have multiple literal values. One is the object
,
and the other is the array
.
The following is an example inputData
definition that defines the value to be an object
consisting of two named literals id
(of type integer
) and name
(of type string
)
where id
is required to be present.
"inputData": {
"type": "object",
"fields": [
{
"name": "id",
"value": {
"type": "integer"
}
},
{
"name": "name",
"value": {
"type": "string"
}
}
],
"required": ["id"]
}
When the id
number and the name
string values being exchanged are 1314520 and "Web of Things", data serialization in JSON format will look like the following.
{
"id": 1314520,
"name": "Web of Things"
}
The above data will look the following when the data is exchanged in XML.
<object>
<id>
<integer>1314520</integer>
</id>
<name>
<string>Web of Things</string>
</name>
</object>
In both JSON and XML serialization, values can appear in any order regardless of the order used in the fields
definition of the object
.
The following is an example valueType
definition that defines the value to be an array
that consists of exactly three number literals with each value within the range of [ 0 ... 2047 ].
"inputData": {
"type": "array",
"items": {
"type" : "number",
"minimum": 0,
"maximum": 2047
},
"minItems" : 3,
"maxItems" : 3
}
When the numbers being exchanged are 520, 184 and 1314, data serialization in JSON format will look like the following.
[
520,
184,
1314
]
The above data will look the following when the data is exchanged in XML.
<array>
<number>520</number>
<number>184</number>
<number>1314</number>
</array>
In the previous section, examples showed what data whose value type is described using the type system look like when serialized to XML in parallel to corresponding JSON serializations.
This section describes how type definitions described using the type system can be mapped to XML schema definitions by using the same examples. Given these type definitions, providing the mapping to XML schema allows XML tools to directly validate serialized XML data, for example. The XML structure for which this mapping is designed is based on EXI4JSON [exi-for-json].
Shown below is the type system object
definition given for the inputData
in Section Object. The object
consists of two named literals id
(of type
integer
) and name
(of type string
) where id
is required to be present.
{
"type": "object",
"fields": [
{
"name": "id",
"value": {
"type": "integer"
}
},
{
"name": "name",
"value": {
"type": "string"
}
}
],
"required": ["id"]
}
When the object
is anonymous (i.e. it is the root, or participates in an array
definition), the above object
definition transforms to the following XML Schema element definition.
<xs:element name="object" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:complexType>
<xs:all>
<xs:element name="id">
<xs:complexType>
<xs:sequence>
<xs:element name="integer" type="xs:integer" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="name" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element name="string" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:all>
</xs:complexType>
</xs:element>
Otherwise (i.e. the object
is a member of another object
definition, thus has a name), the object
definition transforms to the following XML schema element definition. Note $name
represents the name of the object
, and needs to be replaced by the actual name of the object
.
<xs:element name="$name" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:complexType>
<xs:sequence>
<xs:element name="object">
<xs:complexType>
<xs:all>
<xs:element name="id">
<xs:complexType>
<xs:sequence>
<xs:element name="integer" type="xs:integer" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="name" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element name="string" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:all>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
Shown below is the type system array
definition given for the inputData
in Section Array. The array
consists of exactly three number literals with each value within
the value range of [ 0 ... 2047 ].
{
"type": "array",
"items": {
"type" : "number",
"minimum": 0,
"maximum": 2047
},
"minItems" : 3,
"maxItems" : 3
}
When the array
is anonymous (i.e. it is the root, or participates in another array
definition), the above array
definition transforms to the following XML Schema element definition.
<xs:element name="array" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:complexType>
<xs:sequence>
<xs:element name="double" minOccurs="3" maxOccurs="3">
<xs:simpleType name="minInclusive">
<xs:restriction base="xs:double">
<xs:minInclusive value="0"/>
<xs:maxInclusive value="2047"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
Otherwise (i.e. the array
is a member of an object
definition, thus has a name), the array
definition transforms to the following XML schema element definition. Note $name
represents the name of the array
, and needs to be replaced by the actual name of the array
.
<xs:element name="$name" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:complexType>
<xs:sequence>
<xs:element name="array">
<xs:complexType>
<xs:sequence>
<xs:element name="double" minOccurs="3" maxOccurs="3" >
<xs:simpleType name="minInclusive">
<xs:restriction base="xs:double">
<xs:minInclusive value="0"/>
<xs:maxInclusive value="2047"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
To parse a valid Thing Description a simple JSON-based parser and tools can be used to retrieve the content. To validate and follow references to external context vocabulary, JSON-LD or RDF-based parsing tools and libraries are highly recommended.
In the following, we give examples of full TDs. The first one, a temperature sensor, shows how to define relations between Thing Properties. As a second example, we modeled an actuator (LED lamp) where Actions have all been characterized semantically, so that machines could unambiguously interpret them in an automated manner. At last, association between Things is shown by defining a master switch controlling other LED lamps.
{
"@context": ["https://w3c.github.io/wot/w3c-wot-td-context.jsonld",
"https://w3c.github.io/wot/w3c-wot-common-context.jsonld"],
"@type": ["Sensor"],
"name": "myTempSensor",
"base" : "coap:///www.example.com:5683/temp/",
"interaction": [
{
"@id": "val",
"@type": ["Property","Temperature"],
"unit": "celsius",
"reference": "threshold",
"name": "myTemp",
"outputData": { "type": "number" },
"writable": false,
"link": [{
"href" : "val",
"mediaType": "application/json"
}]
},
{
"@id": "threshold",
"@type": ["Property","Temperature"],
"unit": "celsius",
"name": "myThreshold",
"outputData": { "type": "number" },
"writable": true,
"link": [{
"href" : "thr",
"mediaType": "application/json"
}]
},
{
"@type": ["Event"],
"outputData": { "type": "number" },
"name": "myChange",
"property": "temp",
"link": [{
"href" : "val/changed",
"mediaType": "application/json"
}]
},
{
"@type": ["Event"],
"outputData": { "type": "number" },
"name": "myWarning",
"link": [{
"href" : "val/high",
"mediaType": "application/json"
}]
}
]
}
The Thing myTempSensor
defines two Properties: myTemp
and myThreshold
. Both are defined as temperatures, with the same unit (
celsius
). A client that is able to parse a TD only needs to know the predicate reference
to understand that the threshold acts as a reference value for myTemp
while the latter is the actual value
measured by the temperature sensor. Here, reference
points to http://schema.org/valueReference
.
Moreover, one of the Events of the Thing is linked to the measured value (with the predicate property
). It means in that context that an event should be triggered each time myTemp
changes. The other Event
does not define further semantics. It could be used either in a closed system (where clients are aware of its meaning) or by a human but an external agent would not have sufficient information to interpret it.
{
"@context": ["https://w3c.github.io/wot/w3c-wot-td-context.jsonld",
"https://w3c.github.io/wot/w3c-wot-common-context.jsonld"],
"@type": ["Lamp"],
"name": "myMasterLED",
"interaction": [
{
"@type": ["Action", "Toggle"],
"name": "myMasterOnOff",
"inputData": {
"@type": "OnOff",
"type": "boolean"
},
"link": [
{
"href" : "coap://www.example.com:5683/master",
"mediaType": "application/json"
},
{
"href" : "http://www.example.com:80/master",
"mediaType": "application/json"
}
]
}
]
}
In this last example, it would be good to illustrate the use of associations
. The Thing we modeled here acts as a master switch for eight lamps similar to that of LED actuators. This means switching
on and off
myMasterOnOff
will propagate to all associated Things by toggling their Action that is also of type Toggle
. No precise semantics for associations
have been defined yet and there might exist
many other kinds of dependency between Things than simply parent/child relations. This issue will be addressed soon. Until then, Thing associations could be useful for discovery.
Please see the WoT Security and Privacy repository for work in progress regarding threat models, assets, risks, recommended mitigations, and best practices for security and privacy for systems using the Web of Things. Once complete, security and privacy considerations relevant to Thing Descriptions will be summarized in this section.
This document contains a significant contribution from Web of Things members: ...