Copyright © 2017-2018 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 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).
Changes from the previous publication can be found in Appendix A. A diff-marked version of this document is also available for comparison purposes.
Publication as a 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 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 February 2018 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 serialisation of the TD is JSON-LD.
Example 1 shows a simple TD instance that reflects WoT's Property, Action, Event paradigm by describing a lamp Thing with the name MyLampThing.
{
"@context": ["https://w3c.github.io/wot/w3c-wot-td-context.jsonld"],
"@type": ["Thing"],
"name": "MyLampThing",
"interaction": [
{
"@type": ["Property"],
"name": "status",
"schema": {"type": "string"},
"writable": false,
"observable": true,
"form": [{
"href": "coaps://mylamp.example.com:5683/status",
"mediaType": "application/json"
}]
},
{
"@type": ["Action"],
"name": "toggle",
"form": [{
"href": "coaps://mylamp.example.com:5683/toggle",
"mediaType": "application/json"
}]
},
{
"@type": ["Event"],
"name": "overheating",
"schema": {"type": "string"},
"form": [{
"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
accessable over the CoAP protocol with a GET method (see CoAP
protocol binding description in the W3C WoT protocol template
deliverable [WOT-PROTOCOL-BINDING])
at coaps://mylamp.example.com:5683/status (announced within the
form
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).
In a similar manner an Action is specified to toogle the switch status using the POST method that is applied to the coaps://mylamp.example.com:5683/toggle resource (see CoAP protocol binding description in the W3C WoT protocol template deliverable [WOT-PROTOCOL-BINDING]).
Events which are, e.g., unexpected or irregular can be specified with the WoT's Event model. Here, a subscription of a possible overheating event of the lamp can be applied by using CoAP OBSERVE at coaps://mylamp.example.com:5683/oh. (see CoAP protocol binding description in the W3C WoT protocol template deliverable [WOT-PROTOCOL-BINDING]).
The Thing Description defines a relative small set of terms to describe mainly Thing's interaction models. However, the TD opens the re-usage of existing models from un-specific (e.g., schema.org, SSN) and specific domains (e.g., smart home, consumer electronics, industry, automotive) to enrich the capabilities of a Thing with further vocabulary and semantics.
The following example extends the previous shown example with further semantics from the iotschema.org context.
{
"@context": ["https://w3c.github.io/wot/w3c-wot-td-context.jsonld",
{"iot": "http://iotschema.org/"}],
"@type": ["Thing", "iot:Light", "iot:BinarySwitch"],
"name": "MyLampThing",
"interaction": [
{
"@type": ["Property", "iot:SwitchStatus"],
"name": "status",
"schema": {"type": "string"},
"writable": false,
"observable": true,
"form": [{
"href": "coaps://mylamp.example.com:5683/status",
"mediaType": "application/json"
}]
},
{
"@type": ["Action", "iot:ChangeSwitchStatus"],
"name": "toggle",
"form": [{
"href": "coaps://mylamp.example.com:5683/toggle",
"mediaType": "application/json"
}]
},
{
"@type": ["Event", "iot:TemperatureAlarm"],
"name": "overheating",
"schema": {"type": "string"},
"form": [{
"href": "coaps://mylamp.example.com:5683/oh",
"mediaType": "application/json"
}]
}
]
}
Provide detail description about the semantic usage in the example. Please also check the samples provided in Section 6.7.
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# |
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 serializiation, a Thing Description instance in JSON-LD format complies with this specification if it follows the normative statements in Section 6. 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 relys 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 |
---|---|---|
link |
provides Web links to arbitrary resources that relate to the specified Thing Description. |
Link
|
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 |
---|---|---|
form |
Indicates one or more endpoints from which an interaction pattern is accessible |
Form
|
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 |
---|---|---|
schema |
link to the n-ary class that allows the declaration of the data type and unit of measure provided by a property or an event. |
DataSchema
|
observable |
Indicates whether a remote servient can subscribe to ("observe") the Property, to receive change notifications or periodic updates (true/false). |
boolean
|
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 |
---|---|---|
inputSchema |
link to the n-ary class that allows the declaration of the accepted data type of an action. |
DataSchema
|
outputSchema |
link to the n-ary class that allows the declaration of the data type returned by an action. |
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 |
---|---|---|
schema |
link to the n-ary class that allows the declaration of the data type and unit of measure provided by a property or an event. |
DataSchema
|
DataSchema
This class embeds the terms that are defined by JSON Schema (https://tools.ietf.org/html/draft-handrews-json-schema-validation-00#section-6) and map them 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.
In next update of the TD deliverable the full list of schema terms will be defined here. For now, please check the data schema defintions that are provided in Section 6.5 and examples provided in WoT Binding Template.
Form
Communication metadata where a service can be accessed by a client application. An interaction might have more than one form.
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
|
rel |
Indicates the expected result of performing the
operation 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 value of the "rel" attribute of the form indicates which form is which and allows the client to select the correct form for the oeration required |
string
|
Link
A Web link, as specified by IETF RFC 8288 (https://tools.ietf.org/html/rfc8288).
Field Name | Description | Expected value type |
---|---|---|
anchor |
By default, the context of a link is the URL of the representation it is associated with, and is serialised as a URI. When present, the anchor parameter overrides this with another URI, such as a fragment of this resource, or a third resource (i.e., when the anchor value is an absolute URI). |
anyURI
|
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
|
rel |
Indicates the expected result of performing the
operation 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 value of the "rel" attribute of the form indicates which form is which and allows the client to select the correct form for the oeration required |
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-metadata
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. If relative
URIs are used within the form field (see
6.3 Form), base
MUST be
present.
|
interaction | array of objects | no | See 6.2 Interaction Resources |
security | array of objects | no | See 6.4 Security |
link | array of objects | no | tbd: see Link |
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 have this context
information enmbedded 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",
"schema":{ "type": "number" },
"writable": false,
"observable": true,
"form": [{
"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 | Gives one or more semantic annotations to the
Property interaction. The array
MUST start with
a string "Property" |
name | string | yes | Name of the Property |
schema | object | yes | See 6.5 Type System |
writable | boolean | yes | a property is writable (=true) or not (=false) |
observable | boolean | yes | a property is observable (=true) or not (=false) |
form | array of objects | no | See 6.3 Form |
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",
"inputSchema": { "type": "integer" },
"form": [{
"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 | Gives one or more semantic annotations to the
Action interaction. The array MUST start with a string
"Action" |
name | string | yes | Name of the Action |
outputSchema | object | no | See 6.5 Type System |
inputSchema | object | no | See 6.5 Type System |
form | array of objects | no | See 6.3 Form |
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 three mandatory terms and one optional term defined
within the Event
pattern:
{
...
"interaction": [
{
"@type": ["Event"],
"name": "criticalCondition",
"schema": { "type": "string" },
"form": [{
"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 | Gives one or more semantic annotations to the
Event interaction. The array MUST start with a string
"Event" |
name | string | yes | Name of the Event |
schema | object | yes | See 6.5 Type System |
form | array of objects | no | See 6.3 Form |
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 Form class. Shown below is an example of a form definition.
"form": [
{
"href" : "coap://mytemp.example.com:5683/temp",
"mediaType": "application/json",
"rel": "writeProperty"
}
]
JSON-LD representation for a web form definition is a JSON array with name "form". 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 the MUST present base URI (see 6.1 Thing as a Whole). |
mediaType | string | yes | Media type based on IANA |
rel | string | no | Provides the expected result of performing the
operation described by the form. Check [WOT-PROTOCOL-BINDING]
for detail usage of rel . |
The form field is used to pointing a URI to an instance of the interaction and descriptions of the protocol settings and options expected to be used between the client and server for the interaction. The different opportunities of the protocol settings (such as for HTTP, CoAP, MQTT, etc) is described in [WOT-PROTOCOL-BINDING].
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 three interaction types, Property
,
Action
, and Event
, include data
schema definitions. Instances of the Property
and Event
interaction types each must define
only one schema (i.e. schema
field), which
describes the data they expose, while instances of the
Action
interaction type can define different
schemas for inputs (i.e. inputSchema
) and
outputs (i.e. outputSchema
). In the case of a
Property
that allows for an update operation,
the input data and the output data are defined by a single
schema (schema
field).
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 [JSON-SCHEMA-CORE] [JSON-SCHEMA-VALIDATION], 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.
Within schema
, inputSchema
and outputSchema
fields, simple type
assignments can be done by using the type
field that specifies one of the datatypes borrowed from
[JSON-SCHEMA-VALIDATION].
Shown below is an example of an interaction snippet that
carries a simple type definition number
within schema
.
"schema": { "type": "number" }
JSON-LD representation for primitive data type definition is a JSON object of which the field is defined below.
Field Name | JSON Construct | Mandatory | Description |
---|---|---|---|
type | string | yes |
The following type defintions are possible for simple type assignments:
|
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.
In order to make more precise data type defintions the
TD also allows the usage of restrication terms borrowed
from [JSON-SCHEMA-VALIDATION].
Consider the following schema
definition
which defines the value to be an integer
within the value range of [ 0 ... 255 ].
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 255
}
The following table only display a small subset of the restriction terms defined in JSON Schema. Please check [JSON-SCHEMA-VALIDATION] for the full set of restrictions.
Field Name | JSON Construct | Mandatory | Description |
---|---|---|---|
minimum | number | no | Specifies a minimum numeric value. Only
applicable for associated number or
integer types. |
maximum | number | no | Specifies a maximum numeric value. Only
applicable for associated number or
integer types. |
minLength | number | no | Minimum length of the string. Only applicable
for associated string type. |
maxLength | number | no | Maximum length of the string. Only applicable
for associated string type. |
const | any type | no | Provides a constand/default value. |
... | ... | ... | Check [JSON-SCHEMA-VALIDATION] for further type restriction terms. |
Unlike in JSON Schema, the TD with JSON-LD
serializiation allows a semantic annotation of data
members of the types by using the @type
key.
The example below comes with a semantic annotation within
inputSchema
to privide its semantic context
DimmerData that is defined in the http://iotschema.org/
namespace.
{
"@context": [
"https://w3c.github.io/wot/w3c-wot-td-context.jsonld",
{"iot": "http://iotschema.org/"}
],
...
"inputSchema": {
"type": "integer",
"@type": ["iot:DimmerData" ],
"minimum": 0,
"maximum": 255,
},
...
}
JSON-LD representation for semantic annotation of
simple type within schema
,
inputSchema
and outputSchema
fields is defined below.
Field Name | JSON Construct | Mandatory | Description |
---|---|---|---|
@type | array of strings | no | Gives one or more semantic annotations to the data member. |
ToDo: Provide information about JSON Schema
validation with @type
.
Unless otherwise specified in the form
field (also see [WOT-PROTOCOL-BINDING])
the provided schema reflects the payload structure of the
runtime data of the Property
,
Action
, and Event
.
Let's consider the simple data type defintion as shown
in Example 11. 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>
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 one is the
array
. Both object
and
array
are assigned as the value of
type
field in order to indicate the use of
those constructs.
In order to avoid duplicate key definitions with
different meanings in the context documents,
object
definitions take a form that is
slightly different from that of [JSON-SCHEMA-VALIDATION].
The following highlights the differences.
field
instead of JSON Schema's properties of a JSON
objectfield
array must
contain the key name
(corresponding to the
field name of the specified JSON object), and
schema
, whose value must be a data schema
as specified in the present section (recursive
definition)The following example shows a Thing Description
object
definiton using JSON-LD
serializiation, in comparison with an equivalent JSON
Schema object definition.
TD with JSON-LD object
definition |
JSON Schema object definition |
---|---|
Example 16
{
"type": "object",
"field": [{
"name": "id",
"schema": {
"type": "integer"
}
}],
"required": ["id"]
}
|
Example 17
{
"type": "object",
"properties": {
"id": {"type": "integer"}
},
"required": ["id"]
}
|
The following is an example inputSchema
definition that declares the value to be an
object
consisting of two named literals
brightness
(of type integer
)
and name
(of type string
) where
brightness
is required to be present.
"inputSchema": {
"type": "object",
"field": [
{
"name": "brightness",
"schema": {
"type": "integer",
"@type": ["iot:DimmerData"],
"minimum": 0,
"maximum": 255
}
},
{
"name": "name",
"schema": {
"type": "string"
}
}
],
"required": ["brightness"]
}
JSON-LD representation for object data type definition is a JSON object with terms as defined below.
Field Name | JSON Construct | Mandatory | Description |
---|---|---|---|
type | string | yes | "object" has to be assigned to
type for object declaration. |
field | array of objects | yes |
Each array entry defines within the object one member of the structure by its
|
required | array of strings | no | Defines which members (associated by member's
name ) that are defined within the
field are mandatory or not in an
instance. |
Arrays follow again the same convention as defined in
[JSON-SCHEMA-VALIDATION].
The following is an example value type 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 ].
"inputSchema": {
"type": "array",
"items": {
"type" : "number",
"minimum": 0,
"maximum": 2047
},
"minItems" : 3,
"maxItems" : 3
}
JSON-LD representation for array type definition is a JSON object with terms as defined below.
Field Name | JSON Construct | Mandatory | Description |
---|---|---|---|
type | string | yes | "array" has to be assigned to type
for array declaration. |
items | object | yes |
Defines characteristics of the array items by its underlying
|
minItems | integer | no | Defines the minimum number of itmes that have to be in the array. |
maxItems | integer | no | Defines the maximum number of itmes that the array can provide. |
... | ... | ... | Check [JSON-SCHEMA-VALIDATION] for further array restriction terms. |
In the case of an object-based schema decleration the
expected instance is straightforward and similar handling
to JSON Schema and JSON instances. Let's consider Example
18: When the brightness
number and the
name
string values being exchanged are 200
and "Web of Things", data serialization in JSON format
will look like the following.
{
"brightness": 200,
"name": "Web of Things"
}
The above data will look the following when the data is exchanged in XML.
<object>
<id>
<integer>200</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
field
definition of the
object
.
In the case of an array decleration there is the same bahavior from JSON Schema and JSON instances. Let's consider Example 19: 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 inputSchema
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",
"field": [
{
"name": "id",
"schema": {
"type": "integer"
}
},
{
"name": "name",
"schema": {
"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 inputSchema
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": [
{
"@type": ["Property","Temperature"],
"reference": "threshold",
"name": "myTemp",
"schema": {
"type": "number"
},
"writable": false,
"observable": true,
"form": [{
"href" : "val",
"mediaType": "application/json"
}]
},
{
"@type": ["Property","Temperature"],
"name": "myThreshold",
"schema": {
"type": "number"
},
"writable": true,
"form": [{
"href" : "thr",
"mediaType": "application/json"
}]
},
{
"@type": ["Event"],
"schema": { "type": "number" },
"name": "myChange",
"property": "temp",
"form": [{
"href" : "val/changed",
"mediaType": "application/json"
}]
},
{
"@type": ["Event"],
"schema": { "type": "number" },
"name": "myWarning",
"form": [{
"href" : "val/high",
"mediaType": "application/json"
}]
}
]
}
The Thing myTempSensor
defines two
Properties: myTemp
and
myThreshold
. Both are defined as temperatures.
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",
"inputSchema": {
"@type": ["OnOff"],
"type": "boolean"
},
"form": [
{
"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. 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: ...