This is the first draft of the new simplified TD
approach based on JSON-LD 1.1. Some definitions are not
finished yet and are still in progress. A stable Thing
Description deliverable version based on JSON-LD 1.0 can be
found
here.
Abstract
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 of
Things, where a Thing is an abstraction of a physical or
virtual entity that provides interactions to and participates
in the Web of Things. Thing Descriptions provide a set of
interactions based on a small vocabulary that makes it possible
both to integrate diverse devices and to allow diverse
applications to interoperate. Thing Descriptions, by default,
are encoded in a JSON format that also allows JSON-LD
processing. The latter provides a powerful foundation to
represent knowledge about Things in a machine-understandable
way. A Thing Description instance can be hosted by the Thing
itself or hosted externally when a Thing has resource
restrictions (e.g., limited memory space) or when a Web of
Things-compatible legacy device is retrofitted with a Thing
Description.
Status of This Document
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.
Editor's note: The W3C WoT WG is asking for
feedback
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 security and privacy is 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.
Changes from the previous publication can be found in
Appendix B. 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.
The Thing Description (TD) is a central building block in
the W3C Web of
Things (WoT) and can be considered as the entry point of a
Thing (much like the index.html of a Web site). The TD
consists of semantic metadata for the Thing itself, an
interaction model based on WoT's Properties,
Actions, and Events paradigm, a
semantic schema to make data models machine-understandable, and
features for Web Linking to express relations among Things.
Properties can be used for sensing and controlling
parameters, such as getting the current value or setting an
operation state. Actions model invocation of physical (and
hence time-consuming) processes, but can also be used to
abstract RPC-like calls of existing platforms. Events are used
for the push model of communication where notifications,
discrete events, or streams of values are sent asynchronously
to the receiver. In general, the TD provides metadata for
different communication bindings identified by URI schemes
(e.g., "http", "coap", "mqtt", etc.), media types (e.g.,
"application/json", "application/xml", "application/cbor",
"application/exi" etc.), and security mechanisms (for
authentication, authorization, confidentiality, etc.).
Serialization of TD instances is based on JSON and includes at
least the TD core vocabulary as JSON keys as defined in this
specification document.
Example 1 shows a simple TD instance in such a JSON
serialization and depicts WoT's Properties,
Actions, and Events paradigm by
describing a lamp Thing with the name MyLampThing.
Example
1: Simple Thing Description
Sample with JSON serialization
Based on this content, we know there exists one
Property interaction resource with the name
status. In addition, information is provided to indicate
that this Property is accessible via (the secure form of) the
HTTP protocol with a GET method at the URI
https://mylamp.example.com/status (announced
within the forms structure by the
href key), and will return a string status value.
The use of the GET method is not stated explicitly, but is one
of the default assumptions defined by this document.
In a similar manner, an Action is specified to
toggle the switch status using the POST method applied to the
https://mylamp.example.com/toggle resource, where
POST is again a default assumption for invoking Actions.
The Event pattern enables a mechanism for
asynchronous messages to be sent by a Thing. Here, a
subscription to be notified upon a possible overheating event
of the lamp can be obtained by using the HTTP with its long
polling sub-protocol at
https://mylamp.example.com/oh.
This example also specifies the basic security
scheme, requiring a username and password for access. In
combination with the use of the HTTP protocol this indicates
the use of HTTP Basic Authentication. Specification of a
security scheme at the top level as in this example indicates
that it is required for every resource. However, security
schemes can also be specified per-interaction or per-form, with
lower-level configurations overriding higher-level ones,
allowing for the specification of fine-grained access control.
Examples are provided later.
The TD in Example 1 reflects some additional defined default
assumptions that are not explicitly described. For example, the
media type of the exchange format of the interactions is
assumed to be JSON (=mediaType) and the
Propertystatus resource is not writable as
well as not observable. Specifically, the TD specification
defines vocabulary terms (writable,
observable, mediaType) that have
default values. If these vocabulary terms are not explicitly
used in a Thing Description instance, the Thing Description
processor follows default assumptions for interpretation as
defined in this specification.
The TD can be also processed as an RDF-based model. In that
case, the Thing Description instance needs to be transformed
into valid JSON-LD first. In terms of JSON-LD 1.1
serialization, the open-world assumption of RDF semantic
processing requires vocabulary terms with default values to be
always present explicitly in the instances. Example 2 shows the
same TD in a JSON-LD 1.1 serialization representing exactly
the same information as in Example 1; however, default values
have been filled in.
Example
2: Thing Description as
JSON-LD 1.1 Serialization
The TD will reuse existing vocabulary definitions
such as for http from the http://www.w3.org/2011/http#
namespace. In that case the prefix http is used.
However, there are prefixes such as coap and
mqtt which have no namespace yet. Currently
there are efforts to have such namespace representations
which will be referenced in the TD specification in the
future. In the meantime, the [WOT-PROTOCOL-BINDING]
provides the list of terms that can be used to specify the
protocol metadata in the Thing Description.
4.
Conformance
As well as all 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.Information Model and Section 6.Thing Description
Serialization regarding Thing Description
serialization.
In the future some information about RDF
validation will be provided.
5.
Information Model
5.1
Overview
The W3C
Thing Description provides a set of vocabulary for describing
physical and virtual Things. To increase interoperability the
vocabulary terms are defined using the Resource Description
Framework (RDF). All vocabulary restrictions noted in these
tables MUST be
followed,including mandatory items and default
values.
In general, the Thing Description vocabulary set is
grouped in three modules: the core Thing Description
vocabulary reflecting WoT's paradigm of
Properties, Actions, and
Events (also see [WOT-ARCHITECTURE]);the
data schema vocabulary reflecting a subset of the terms
defined in JSON Schema [JSON-SCHEMA-VALIDATION]
in a linked data representation; and the security vocabulary
used to define security mechanismconfiguration
requirements.
An overview of this vocabulary with its class context and
class relation is given by the following three figures: the
TD core model, the TD data schema model, and the TD security
model. Please note that the figures reflect the vocabulary
terms and structure as they would be used in a Thing
Description instance (see Section 6.Thing Description
Serialization).The full ontology definitions of
the different modules can be viewed by following the
namespaces as provided in Section 3.Namespaces.
Figure 1TD core model
Figure 2TD data schema model
Figure 3TD security model
Editor's note: Default Values and Mandatory
Attributes
In the figures above, and in the tables to
follow, items which have default values are indicated as
being optional. However, technically, these are optional
only in the JSON serialization. They are actually
mandatory parts of the information model and are also
mandatory in the JSON-LD serialization. In addition, the
security scheme configuration is not actually optional even
in the JSON serialization. Security configuration is
mandatory at least one of the three levels at which it may
be specified... so it can be omitted only if it is
specified at a different level for each form. A future
version of this document should better express the status
of these attributes.
A detailed description of the vocabulary of the TD core
model and TD data schema model is given in the next
sub-section.
5.2 Core Vocabulary Definition
5.2.1Thing
Describes a physical and/or virtual Thing (may represent
one or more physical and/or virtual Things) in the Web of
Things context.
Field Name
Description
Mandatory
Default value
Type
id
unique identifier of the Thing (URI, e.g. custom
URN)
Define the 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].
Set of security configurations, provided as an
array, that must all be satisfied for access to
resources at or below the current level, if not
overridden at a lower level.
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 the 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.
Each instance of a
Property, Action, and
Event class MUST have an identifier that is unique within
the context of a Thing Description document. See
Section Representation Format for more details about
JSON-LD 1.1 identifiers.
Field Name
Description
Mandatory
Default value
Type
forms
Indicates one or more endpoints from which an
interaction pattern is accessible.
Set of security configurations, provided as an
array, that must all be satisfied for access to
resources at or below the current level, if not
overridden at a lower level.
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.
Properties expose internal state of a Thing that can be
directly retrieved (get) and optionally modified (set). In
addition, Things can also choose to make Properties
observable by pushing the new state (not an event) after a
change; this must follow eventual consistency (also see CAP
Theorem).
Field Name
Description
Mandatory
Default value
Type
observable
Indicates whether a remote servient can subscribe
to ("observe") the Property, to receive change
notifications or periodic updates (true/false).
Property instances may also be instances of
the class DataSchema and therefore can contain, among
others, the type term.
5.2.4Action
Actions offer functions of the Thing. These functions
may manipulate the internal state of a Thing in a way that
is not possible through setting Properties. Examples are
changing internal state that is not exposed as a Property,
changing multiple Properties, changing Properties over time
or with a process that should not be disclosed. Actions may
also be pure functions, that is, they may not use any
internal state at all, and may simply process input data
and return a result that directly depends only on the input
given.
Field Name
Description
Mandatory
Default value
Type
input
Link to the n-ary class that allows the
declaration of the accepted data type of an
action.
The Event Interaction Pattern describes event sources
that asynchronously push messages. Here not state, but
state transitions (events) are communicated (e.g.,
"clicked"). Events may be triggered by internal state
changes that are not exposed as Properties. Events usually
follow strong consistency, where messages need to be queued
to ensure eventual delivery of all events that have
occurred.
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 rel attribute indicates which form
is which and allows the client to select the
correct form for the operation required.
The value of the rel attribute of
the form must be one of readproperty,
writeproperty, observeproperty, invokeaction,
subscribeevent, or unsubscribeevent.
(one of "readproperty",
"writeproperty",
"observeproperty",
"invokeaction",
"subscribeevent", or
"unsubscribeevent")
subProtocol
Indicates the exact mechanism by which an
interaction will be accomplished for a given protocol
when there are multiple options. For example, for
HTTP and Events, it indicates which of several
available mechanisms should be used for asynchronous
notifications.
Set of security configurations, provided as an
array, that must all be satisfied for access to
resources at or below the current level, if not
overridden at a lower level.
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.
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 rel attribute indicates which form is which and
allows the client to select the correct form for the
operation required.
By default, the context of a link is the URL of
the representation it is associated with, and is
serialized 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).
For the core TD vocabulary only well-established security
mechanisms are supported, such as those built into protocols
supported by WoT or already in wide use with those protocols.
The current set of HTTP security schemes is partly based on
OpenAPI 3.0.1 (see also [OPENAPI]). Note however that while
the HTTP security schemes, vocabulary and syntax given in
this specification share many similarities with OpenAPI they
are not fully compatible. Also, since OpenAPI primarily
targets web services built around HTTP, it does not cover the
full set of use cases required for the IoT. Security schemes
appropriate for IoT-centered protocols such as CoAP and MQTT
are therefore also included.
Editor's note: Security Scheme
Extensions
The vocabulary extension mechanism of the WoT
Thing Description allows for additional security schemes if
needed.However, for more information about what additional
security schemes or modifications are under discussion for
the core WoT vocabulary(and to file issues if you have a
request) please visit the WoT Security TF
repository.
5.4.1SecurityScheme
Field Name
Description
Mandatory
Default value
Type
scheme
Identification of security mechanism being
configured.
A security configuration corresponding to ("scheme":
"nosec"), indicating there is no authentication or other
mechanism required to access the resource.
5.4.3BasicSecurityScheme
Basic authentication security configuration ("scheme":
"basic"), using an unencrypted username and password. This
scheme should be used with some other security mechanism
providing confidentiality, for example, TLS.
Field Name
Description
Mandatory
Default value
Type
in
Specifies the location of security authentication
information (one of header, query, body, or
cookie).
Digest authentication security configuration ("scheme":
"digest"). This scheme is similar to basic authentication
but with added features to avoid man-in-the-middle
attacks.
Bearer token authentication security configuration
("scheme": "bearer"). This scheme is intended for
situations where bearer tokens are used independently of
OAuth2. If the oauth2 scheme is specified it is not
generally necessary to specify this scheme as well as it is
implied.
OAuth2 authentication security configuration ("scheme":
"oauth2"). For the implicit flow the authorizationUrl and
scopes are required. For the password and client flows both
tokenUrl and scopes are required. For the code flow
authorizationUrl, tokenUrl, and scopes are required.
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.
API key authentication security configuration ("scheme":
"apikey"). This is for the case where the access token is
opaque and is not using a standard token format.
Field Name
Description
Mandatory
Default value
Type
in
Specifies the location of security authentication
information (one of header, query, body, or
cookie).
This is the first draft that uses JSON-LD 1.1 as
a serialization format of the Thing Description. As that is
work in progress, working assumptions are based on the latest
Community
Draft of JSON-LD 1.1. A new JSON-LD Working Group has
already been chartered.
It is planned that this section will conform to the latest
working draft of their JSON-LD 1.1 deliverable and only use
stable elements.
Thing Description instances are modeled and structured based
on Section 5.Information Model. This section defines
a TD serialization based on JSON [RFC8259].
6.1 Representation Format
The JSON serialization of TDs follows the syntax of
JSON-LD 1.1 in order to streamline semantic evaluation.
Hence, serializations can be parsed either as raw JSON or
with a JSON-LD 1.1 processor.
In order to enable this convergence, all vocabulary terms
defined in Section 5.Information Model will have a JSON key
representation.
In addition, Thing Description instances MAY contain JSON-LD 1.1 keywords
such as @context and
@type.
The data types of the vocabulary as defined in Section
5.3Data Schema Vocabulary Definition will
be transformed to JSON-based types. The following rules are
used for vocabulary terms based on some simple type
definitions:
Vocabulary terms that use simple types
string and anyURI MUST be serialized as JSON string.
Vocabulary terms that use simple type
unsignedInt MUST be
serialized as JSON integer.
Vocabulary terms that use simple type
double MUST be
serialized as JSON number.
All vocabulary terms in Section 5.Information
Model associated with more complex class-based
types are defined separately for structured JSON type
transformation in the following subsections.
6.1.1 Thing as a whole
The root
object of a Thing Description instance MAY include the @context key
from JSON-LD 1.1 with the value URI of the Thing
description context file
http://www.w3.org/ns/td.
http://www.w3.org/ns/td uses
content negotiation to return the context file. Thus, it
must be fetched with an Accept header set to
application/ld+json.
When a Thing Description instance is
processed and interpreted by a JSON-LD 1.1 processor the
@context field MUST be present (see also Section
JSON-LD
1.1 Processing).
When a single Thing Description
instance involves several contexts, additional namespaces
with prefixes MUST be
appended to the @context array
structure. This option proves relevant if one wants
to extend the existing Thing Description context without
modifying it. For instance:
Each mandatory and optional field
name as defined in the class ThingMUST be serialized as a JSON key in the root
object of the Thing Description instance.
The type
of the fields properties,
actions, and eventsMUST be a JSON
object.
The type
of the fields links, scopes, and
securityMUST be a JSON array.
A TD snippet based on the defined fields of the class
Thing
without the optional field @context is given
below:
Properties (and sub-properties) offered by
a Thing MUST be
collected in the JSON-object based properties
field with (unique) Property names as JSON
keys.
Each mandatory and optional vocabulary
term as defined in the class Property, as well as its two
superclasses InteractionPattern and DataSchema,
MUST be serialized as
a JSON key within a Property object.
The type of the fields
properties and itemsMUST be serialized as a JSON
object.
The type of the fields
forms, required, and
enum, scopes, and
security, MUST be serialized as a JSON array.
A TD snippet based on the defined fields is given
below:
Similar to the case at the
Thing level, properties MAY have additional semantic annotations
based on JSON-LD 1.1 keywords.
When a Thing Description instance is
processed and interpreted by a JSON-LD 1.1 processor, each
propertyMUST contain the vocabulary terms
observable and writable due to
the open-world
assumption of Linked Data. This assumption means
that if a Linked Data model of a Thing Description instance
were to omit these vocabulary terms, then the interpreter
would not be able to make any assumptions about their
actual value.
A snippet of a JSON-LD 1.1 processable TD serialization
including semantic annotations and the default values of
observable and writable based on
the class Property is given as
follows:
Actions
offered by a Thing MUST be collected in the JSON-object based
actions field with (unique) Action names as
JSON keys.
Each optional vocabulary term as defined
in the class Action and its superclass
InteractionPatternMUST be serialized as a JSON
key within an Action object.
The type of the fields
input and outputMUST be serialized as a JSON
object.
The keys of input and output
rely on the the class DataSchema.
The type of the fields
forms, scopes, and
securityMUST be serialized as a JSON array.
A TD snippet based on the defined fields is given
below:
Definitions within the
actions field MAY have additional semantic annotations based
on JSON-LD 1.1 keywords.
6.1.4events
Events
offered by a Thing MUST be collected in the JSON-object based
events field with (unique) Event names as JSON
keys.
Each optional vocabulary term as defined in
the class Event, as well as its two
superclasses InteractionPattern and DataSchema,
MUST be serialized as
a JSON key within an Event object.
The type of the fields
properties and itemsMUST be serialized as a JSON
object.
The
type of the fields forms,
required, and enum,
scopes, and securityMUST be serialized as a JSON
array.
A TD snippet based on the defined fields is given
below:
Definitions within the
events field MAY have additional semantic annotations based on
JSON-LD 1.1 keywords.
6.1.5forms
Each
mandatory and optional vocabulary term as defined in the
class Form, MUST be serialized as a JSON key.
If required, formsMAY be supplemented
with protocol-specific vocabulary terms identified with a
prefix. See also [WOT-PROTOCOL-BINDING].
When a Thing Description instance is
processed and interpreted by a JSON-LD 1.1 processor, each
forms (array) entry MUST contain a mediaType due to
the open-world
assumption of Linked Data. This assumption means
that if a Linked Data model of a Thing Description instance
were to omit these vocabulary terms, then the interpreter
would not be able to make any assumptions about their
actual value.
A TD snippet based on the defined fields is given
below:
Each
mandatory and optional vocabulary term as defined in the
class SecurityScheme, MUST be serialized as a JSON
key.
The following TD snippet shows a simple security
configuration specifying basic username/password
authentication in the header. The value of in
given is actually the default value of
header.
Here is a more complex example: a TD snippet showing
digest authentication on a proxy combined with bearer token
authentication on an endpoint. Here the default value of
in in the digest scheme,
header, is implied.
Security definitions can be given at more than one
level. In this case, definitions at the lower levels
override (completely replace) the definitions at the higher
level.
Security configuration is mandatory. Every form
in a Thing MUST have
a security configuration either provided in the form
itself, at the interaction level directly above it (if
security is not configured in the form), or at the Thing
level (if security is not configured in either the form or
at the interaction level). In the vocabulary defined
above, note that security is marked as
non-mandatory. However, this is only true locally (at a
specific level), and only if the security is configured at
a higher or lower level. In other words, a security
configuration must be provided at some level for
each form.
Security configuration is considered binding.
The security configuration metadata
provided in a Thing Description MUST accurately reflect the security
requirements of the Thing. Some protocols can ask
for authentication dynamically. If a protocol asks for a
form of security credentials not declared in the Thing
Description then the Thing Description is to be considered
invalid.
The nosec security scheme is provided for
the case that no security is needed. The minimal security
configuration for a Thing is configuration of the
nosec security scheme at the top level, as in
the following example:
{
"id": "urn:dev:wot:com:example:servient:myThing",
"name": "MyThing",
"description": "Additional (human) readable information of the Thing.",
"support": "https://servient.example.com/contact",
"security": [{"scheme": "nosec"}],
"properties": {...},
"actions": {...},
"events": {...},
"links": [...]
}
To give a more complex example, suppose we have a Thing
where all interactions require basic authentication except
for one interaction for which no authentication is
required. In the following, the nosec scheme
for the security configuration in the
overheating event to indicate no
authentication is required. For the status
property and the toggle action, however,
basic authentication is required as defined at
the top level of the Thing.
Security definitions can also can be given for different
elements at the same level. This may be required for
devices that support multiple protocols, for example CoAP
and HTTP, with support for different security mechanisms.
This is also useful when alternative authentication
mechanisms are allowed. Here is a TD snippet demonstrating
three possible ways to access a resource: via HTTPS with
basic authentication, via HTTPS via digest authentication,
or via CoAPS with an API key. In other words, the use of
multiple security configurations at the same level provides
a way to combine security mechanisms an in "OR" fashion. In
contrast, putting multiple security configurations in the
same security field combines them in an "AND"
fashion, since in that case they would all need to be
satisfied to allow access to the resource.
The JSON-based serialization of the TD is identified by
the media type [MEDIATYPES]
application/td+json.
Editor's note: CoAP Content Format
CoAP-based WoT implementations can use the
experimental Content-Format 65100 until a
proper identifier has been registered.
The
media type application/td+jsonMUST be also associated with the
JSON-LD context http://www.w3.org/ns/td.
That means that this media type can also be used for
contextual identification of the vocabulary within a
(simplified) TD instance that may omit the
@context key term.
Editor's note: IANA Considerations
Neither the application/td+json
media type nor a CoAP Content-Format identifier have been
registered with IANA yet.
6.3 Implementation Notes
6.3.1 JSON Processing
The minimum requirement to read the content of a Thing
Description instance is a (simple) JSON parser.
If the key terms
writable and/or observable are
not present within a properties definition,
the default value defined in 5.Information
ModelMUST
be assumed.
If the mediaType key
term is not present within a forms definition,
the default value as defined in 5.Information
ModelMUST
be assumed.
To validate the semantic meaning and follow references
to external context vocabulary terms (e.g.,
iot.schema.org), use of JSON-LD or RDF-based tools and
libraries is highly recommended as explained in the next
sub-section.
6.3.2 JSON-LD 1.1 Processing
To interpret the semantic meaning of a Thing Description
in terms of RDF triples, a Thing Description instance first
requires a valid JSON-LD 1.1 representation based on this
Thing Description specification. Then this representation
can be passed to a JSON-LD 1.1 processor.
The following pre-processing steps of a Thing Description
instance must be executed before starting JSON-LD 1.1
processing:
Before starting JSON-LD
1.1 processing of a Thing Description instance, there
MUST be a
@context key from JSON-LD 1.1 as defined in
Section 6.1.1Thing as a whole.
Before starting JSON-LD
1.1 processing of a Thing Description instance, all
external vocabulary terms used in the Thing Description
MUST provide their
context URIs as prefix or within the
@context field.
Before starting
JSON-LD 1.1 processing of a Thing Description instance,
all mandatory vocabulary terms as defined in Section
5.Information Model that are missing
from the instance MUST be inserted explicitly with their
default value.
Section 1.Introduction shows an example of how
the input and output of such preprocessing would
appear.
7. Example Thing Description Instances
7.1 MyLampThing Example
Example 18: MyLampThing
represented as a compact JSON serialization
{
"id": "urn:dev:wot:com:example:servient:lamp",
"name": "MyLampThing",
"description" : "MyLampThing uses JSON-LD 1.1 serialization",
"security": [{"scheme": "psk"}],
"properties": {
"status": {
"description" : "Shows the current status of the lamp",
"type": "string",
"forms": [{
"href": "coaps://mylamp.example.com/status"
}]
}
},
"actions": {
"toggle": {
"description" : "Turn on or off the lamp",
"forms": [{
"href": "coaps://mylamp.example.com/toggle"
}]
}
},
"events": {
"overheating": {
"description" : "Lamp reaches a critical temperature (overheating)",
"type": "string",
"forms": [{
"href": "coaps://mylamp.example.com/oh"
}]
}
}
}
Example 19: MyLampThing
with semantic annotations based on a valid JSON-LD 1.1
representation
{
"@context": ["http://www.w3.org/ns/td",
{"iot": "http://iotschema.org/"}],
"@type" : "Thing",
"id": "urn:dev:wot:com:example:servient:lamp",
"name": "MyLampThing",
"description" : "MyLampThing uses JSON-LD 1.1 serialization",
"security": [{"scheme": "psk"}],
"properties": {
"status": {
"@type" : "iot:SwitchStatus",
"description" : "Shows the current status of the lamp",
"writable": false,
"observable": false,
"type": "string",
"forms": [{
"href": "coaps://mylamp.example.com/status",
"mediaType": "application/json"
}]
}
},
"actions": {
"toggle": {
"@type" : "iot:SwitchStatus",
"description" : "Turn on or off the lamp",
"forms": [{
"href": "coaps://mylamp.example.com/toggle",
"mediaType": "application/json"
}]
}
},
"events": {
"overheating": {
"@type" : "iot:TemperatureAlarm",
"description" : "Lamp reaches a critical temperature (overheating)",
"type": "string",
"forms": [{
"href": "coaps://mylamp.example.com/oh",
"mediaType": "application/json"
}]
}
}
}
8. Security and Privacy Considerations
Editor's note
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.
A. JSON Schema for TD Instance
Validation
Below is a JSON Schema
[JSON-SCHEMA-VALIDATION]
for syntactically validating Thing Description instances
serialized in JSON-LD 1.1.
Editor's note
This schema is known to be too permissive. This
issue will be resolved in the next release of this
document.
The default serialization format for Thing Description is
now plain JSON. Thing Description instances still
MAY contain JSON-LD
keys such as @context and @type
for facilitating semantic evaluation of TDs. (see Section
6.1Representation Format)
With regards to JSON-LD, this Thing Description draft
uses JSON-LD 1.1 instead of JSON-LD 1.0. With this
transition, all vocabulary terms defined in vocabulary
definition sections now have a JSON key representation.
Previously, there were vocabulary terms represented as key
values in TDs.
In addition to Thing Description core vocabulary, Thing
Description now has the data schema vocabulary reflecting a
subset of JSON Schema terms as linked data representation
(see Section 5.3Data Schema Vocabulary Definition)
and the security vocabulary (see Section 5.4Security Vocabulary Definition) for
defining security based conditions.
A security field is available at three levels (Thing,
Interaction Patterns and Forms) for providing security
requirements for accessing resources. Security configuration
is mandatory for each form.
Some vocabulary terms (e.g., writable,
observable, mediaType) now have
default values that are used by Thing Description processors
when they are absent in TD instances (see Section 5.2Core Vocabulary Definition). Note
that some security vocabulary terms can also have such
values (see Section 5.4Security Vocabulary Definition).
Things now have a mandatory field id for
uniquely identifying a Thing, and an optional field
support to provide information about Thing
Description maintainer.
Interaction patterns have an optional label
field providing text for such uses as user interfaces.
The rel attribute for form now
has enumerated allowable values specified.
JSON-LD @context key value to represent the Thing
description context file now is
http://www.w3.org/ns/td.
Added a section about media types used for exchanging
TDs. (see Section 6.2Media Type)
Added a section about implementation notes that provide
useful clarifications to implementers. (see Section
6.3Implementation Notes)
A JSON Schema is provided in an appendix section to
facilitate the validation of Thing Description instances.
(see Section A.JSON Schema for TD Instance
Validation)
The editors would like to thank Dave Raggett, Matthias
Kovatsch, Michael McCool, Michael Koster, Victor Charpenay,
Kawaguchi Toru, Michael Lagally, Kazuyuki Ashimura, María
Poveda, Daniel Peintner, Ben Francis for their contributions,
comments, and guidance.
