Copyright © 2017-2021 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
The W3C Web of Things (WoT) is intended to enable interoperability across IoT platforms and application domains. One key mechanism for accomplishing this goal is the definition and use of metadata describing the interactions an IoT device or service makes available over the network at a suitable level of abstraction. The WoT Thing Description specification satisfies this objective.
However, in order to use a Thing its Thing Description first has to be obtained. The WoT Discovery process described in this document addresses this problem. WoT Discovery needs to support the distribution of WoT Thing Descriptions in a variety of use cases. This includes ad-hoc and engineered systems; during development and at runtime; and on both local and global networks. The process also needs to work with existing discovery mechanisms, be secure, protect private information, and be able to efficiently handle updates to WoT Thing Descriptions and the dynamic and diverse nature of the IoT ecosystem.
The WoT Discovery process is divided into two phases, Introduction, and Exploration. The Introduction phase leverages existing discovery mechanisms but does not directly expose metadata; they are simply used to discover Exploration services, which provide metadata but only after secure authentication and authorization. This document normatively defines two Exploration services, one for WoT Thing self-description with a single WoT Thing Description and a searchable WoT Thing Description Directory service for collections of Thing Descriptions. A variety of Introduction services are also described and where necessary normative definitions are given to support them.
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/.
This document was published by the Web of Things Working Group as an Editor's Draft.
GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-wot-wg@w3.org (subscribe, archives).
Publication as an Editor's 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 1 August 2017 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 15 September 2020 W3C Process Document.
The Web of Things (WoT) defines an architecture that supports the integration and use of web technologies with IoT devices. The WoT Architecture [wot-architecture] document defines the basic concepts and patterns of usage supported. However, the WoT Thing Description [wot-thing-description] is a key specification for WoT Discovery since it is the purpose of WoT Discovery to make WoT Thing Descriptions available. Specifically, WoT Discovery has to allow authenticated and authorized entities (and only those entities) to find WoT Thing Descriptions satisfying a set of criteria, such as being near a certain location, or having certain semantics, or containing certain interactions. Conversely, in order to support security and privacy objectives, the WoT Discovery process must not leak information to unauthorized entities. This includes leaking information that a given entity is requesting certain information, not just the information distributed in the Thing Descriptions themselves.
There are already a number of discovery mechanisms defined, so we have to establish why we are proposing a new one. First, many existing discovery mechanisms have relatively weak security and privacy protections. One of our objectives is to establish a mechanism that not only uses best practices to protect metadata, but that can be upgraded to support future best practices as needed. Second, we are using discovery in a broad sense to include both local and non-local mechanisms. While a local mechanism might use a broadcast protocol, non-local mechanisms might go beyond the current network segment where broadcast is not scalable, and so a different approach, such as a search service, is needed. Our approach is to use existing mechanisms as needed to bootstrap into a more general and secure metadata distribution system. Third, the metadata we are distributing, the WoT Thing Description, is highly structured and includes rich data such as data schemas and semantic annotations. Existing discovery mechanisms based on a list of simple key-value pairs are not appropriate. At the same time, use of existing standards for semantic data query, such as SPARQL [SPARQL11-OVERVIEW], while potentially suitable for some advanced use cases, might require too much effort for many anticipated IoT applications. Therefore in order to address more basic applications, we also define some simpler query mechanisms.
After defining some basic terminology, we will summarize the basic use cases and requirements for WoT Discovery. These are a subset of the more detailed and exhaustive use cases and requirements presented in the WoT Use Cases [wot-usecases] and WoT Architecture [wot-architecture] documents. Then we will describe the basic architecture of the WoT Discovery process, which uses a two-phase Introduction/Exploration approach. The basic goal of this architecture is to be able to use existing discovery standards to bootstrap access to protected discovery services, but to distribute detailed metadata only to authorized users, and to also protect those making queries from eavesdroppers as much as possible. We then describe details of specific Introduction and Exploration mechanisms. In particular, we define in detail a normative API for a WoT Thing Description Directory (WoT TDD) service that provides a search mechanism for collections of WoT Thing Descriptions that can be dynamically registered by Things or entities acting on their behalf. The WoT Discovery mechanism however also supports self-description by individual Things and one issue we address is how to distinguish between these two approaches. Finally, we discuss some security and privacy considerations, including a set of potential risks and mitigations.
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 MAY, MUST, OPTIONAL, RECOMMENDED, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
This section is non-normative.
The fundamental WoT terminology such as Thing, Thing Description (TD), Property, Action, Event are defined in Section 3 of the WoT Architecture specification [WOT-ARCHITECTURE].
In addition, this specification introduces the following definitions:
id attribute).
This section is non-normative.
Figure 1 shows an overview of discovery process.
To do: an overview of the two-phase approach and its purpose, which is to support controlled and authenticated access to metadata by authorized users only.
This chapter describes mechanisms for initial contact with Things or Thing Description Directories. Any of the following mechanisms may be provided by the Thing or the Thing Description Directory to Consumers. The result of an introduction mechanism is always a URL (address) of an exploration service which can be used to obtain detailed metadata (TDs) after suitable authentication. It is also possible for multiple introduction mechanisms to be used and the results merged. No particular introduction mechanism is mandatory, as long as the URL of at least one exploration service is somehow obtained.
To obtain an URL of an exploration service, any mechanism that results in a single URL MAY be used. This includes Bluetooth beacons, QR codes, and written URLs to be typed by a user. A request on all such URLs MUST result in a TD as prescribed in § 6.1 Self-description. For self-describing Things, this can be the TD of the Thing itself. If the URL references a Thing Description Directory, this MUST be the Directory Description of the Thing Description Directory.
A Thing or Thing Description Directory MAY use the Well-Known Uniform Resource Identifier [RFC8615]
to advertise its presence.
If the Thing or Thing Description Directory use the Well-Known Uniform Resource Identifier to advertise its presense, it MUST register its own Thing or Directory Description
into the following path:
/.well-known/wot-thing-description.
When a request is made at the above Well-Known URI, the server MUST return a Thing Description as prescribed in § 6.1 Self-description.
The service name in Well-Known URI (wot-thing-description) is tentative.
"Well-Known URIs" registry and contents of registration request is described in Section 3.1 of [RFC8615].
A Thing or Thing Description Directory MAY use the DNS-Based Service Discovery (DNS-SD)[RFC6763]. This can be also be used to discover them on the same link by combining Multicast DNS (mDNS)[RFC6762].
In DNS-SD, format of the Service Instance Name is Instance.Service.Domain.
The Service part is a pair of labels following the conventions of [RFC2782].
The first label has an underscore followed by the Service Name,
and the second label describes the protocol.
The Service Name to indicate the Thing or Thing Description Directory MUST be _wot.
And the Service Name to indicate the Thing Description Directory MUST be _directory._sub._wot.
The Service Names _wot and _directory._sub._wot
are tentative. The following Service Names are used in the existing implementations:
_wot,
_device._sub._wot,
_directory._sub._wot,
_webthing,
_wot-servient.
To use a Service Name, registration to "Underscored and Globally Scoped DNS Node Names"
Registry [RFC8552] is required.
In addition, the following information MUST be included in the TXT
record that is pointed to by the Service Instance Name:
tdtypeThing or Directory.
If omitted, the type is assumed to be Thing.
The following key/value pairs are used in the existing implementations:
retrieve:
Absolute path name of the API to get an array of Thing Description IDs
from the directory service.
register:
Absolute path name of the API to register a Directory Description with the Thing Description Directory.
path:
The URI of the thing description on the Web Thing's web server
td:
Prefix of directory service API
tls:
Value of 1 if the Web Thing supports connections via HTTPS.
Figure 2 and Figure 3 shows example sequences of discovery of Thing and Thing Description Directory using DNS-SD and mDNS.
A Thing or Thing Description Directory MAY advertise its presence using the Constrained RESTful Environment (CoRE) Link Format [RFC6690]. A Thing or Thing Description Directory MAY use the CoRE Resource Directory [CoRE-RD] to register a link to the Thing or Directory Description.
The resource type (rt) of the Link that targets the Thing Description of the Thing
MUST be wot.thing.
The resource type of the Link that targets the Directory Description of the Thing Description Directory
MUST be wot.directory.
The resource types wot.thing and wot.directory are tentative.
See also § 9. IANA Considerations.
A Thing or Thing Description Directory MAY advertise its presence using the Decentralized Identifier (DID) [DID-CORE].
The DID Document obtained by resolving the DID of a Thing or Thing Description Directory MUST contains a Service Endpoint which point to Thing Description of the Thing or Directory Description of the Thing Description Directory.
To do: Description of supported explorations, and requirements for new exploration mechanisms.
Figure 5 illustrates the Discovery ontology as an extension of the Thing ontology.
The ontology includes a class for metadata that are associated with
TDs stored in a directory.
This class is called RegistrationInformation and described as part
of the directory specification in § 6.2.1.1 Registration Information.
Moreover, the Discovery ontology defines two new Thing Description classes that may be used to model special exploratory metadata:
ThingDirectory from the
discovery context or URI https://www.w3.org/2021/wot/discovery#ThingDirectory.
§ 8.1 Directory API Thing Description which describes the API of the Thing Description Directory is an example of this TD class.
ThingLink from the
discovery context or URI https://www.w3.org/2021/wot/discovery#ThingLink.
A Thing Link MUST define the referenced TD as a Link with
describedby link relation type, application/td+json media type
and href set to the target URL.
Example 2 is an example Thing Link.
A Thing Link can be used in various scenarios. For example:
The self-description is an exploration mechanism in which a Thing hosts its own TD and exposes it at a URL or through others means. If exposed at a URL (e.g. over HTTP or CoAP), the URL may be advertised via one of the § 5. Introduction Mechanisms. The hosted TD may also be registered inside a Thing Description Directory as prescribed in § 6.2 Directory.
The self-description using the following protocols must be according to the given specification:The HTTP-based self-description SHOULD be over HTTPS (HTTP Over TLS). The server SHOULD serve the requests after performing necessary authentication and authorization.
The HTTP server MUST serve the TD with a GET method.
A successful response MUST have 200 (OK) status, contain application/td+json
Content-Type header, and the TD in body.
The server MAY provide alternative representations through
server-driven content negotiation, that is by honouring the
request's Accept header and responding with the supported
TD serialization and equivalent Content-Type header.
The HTTP server MUST respond to HEAD requests by returning only the headers
equivalent to those returned by a GET request to the same endpoint.
This enables clients to retrieve HTTP headers such as the Content-Length in advance
to know the size of the TD (in bytes) and decide on an efficient query strategy.
Error responses:
To do: Describe mechanisms for TDs to be hosted in a searchable directory service.
To Do: Formal definition of information contained in a directory and its organization.
RegistrationInformation class is associated with TDs that are
stored in a directory.
The following table lists the registration information attributes for
use within TDs that embed or reference the Discovery context.
Note that only an Enriched TD embeds the registration information.
In this table,
client refers to the producer or consumer of a TD and server refers to
the Thing Description Directory.
| Vocabulary term | Description | Client Assignment | Server Assignment | Type |
|---|---|---|---|---|
created |
Provides information when the TD instance was
created inside the directory.
This MAY be set by the directory and returned to consumers. |
read-only | optional | dateTime |
modified |
Provides information when the TD instance was
last modified inside the directory.
This MAY be set by the directory and returned to consumers. |
read-only | optional | dateTime |
expires |
Provides the absolute time for when the TD instance registration expires.
The producer MAY set this to indicate the absolute expiry time during the registration.
For servers that support expirable TDs:
If |
optional | optional | dateTime |
ttl |
Time-to-live: relative amount of time in seconds from the registration time
until when the TD instance registration expires.
The producer MAY set this to indicate the relative expiry time during the registration.
For servers that support expirable TDs:
The server MUST use |
optional | read-only | number |
retrieved |
The time at which the TD was retrieved from the server.
This is useful for clients that intend to process other absolute timestamps but do not have an internal clock or other means of acquiring the current time. |
read-only | optional | dateTime |
Producers can set the expiry time to inform the directory and other consumers about the validity of the TD registrations. The expiry is also a useful indicator to inform the consumers about expiry of dynamic TDs, e.g. when changes to metadata such as geolocation or properties are expected to be valid for a limited period. Consumers may rely on the expiry time to know how long a retrieved TD will be valid and when they need to request a more recent one. Consumers who retrieve an expired TD may consider it as metadata of an inactive client.
For the servers, the expiry time is useful for implementing automatic removal of obsolete or accidental registrations. Servers SHOULD periodically purge TDs that are past their expiry times. Prescribing a global mandate or upper limit for the expiry time is application-specific and beyond the scope of this specification. The servers MAY mandate or set a configurable upper limit to expiry times and refuse incompliant requests. The purging by servers is particularly beneficial when interacting with clients (e.g. IoT devices) that are unable to explicitly deregister their TDs. This could be due to protocol-specific limitations, failure, destruction, or ungraceful decommissioning. Such clients should set a reasonably short expiry time and periodically extend it during the normal operation. If a client ceases to operate, a directory with purging capability will automatically remove its registration.
The HTTP API responses must use appropriate status codes described in this section for success and error responses. The HTTP API MUST use the Problem Details [RFC7807] format to carry error details in HTTP client error (4xx) and server error (5xx) responses. This enables both machines and humans to know the high-level error class and fine-grained details.
The Problem Details error type field is a URI reference which
could used to map the occurred error to WoT-specific error class.
There are few open issues raising the lack of WoT-specific error types:
wot-discovery#44,
wot-thing-description#303,
wot-scripting-api#200.
For now, type can be omitted which defaults to "about:blank", and title
should be set to HTTP status text.
For each HTTP endpoint that responds to the GET method, the server MUST accept HEAD
requests and return only the headers.
This allows clients to retrieve headers such as the Content-Length without receiving the body
and decide on a suitable strategy to query the information. For example, a constrained client can
request only the necessary parts of an object (using an apprpriate search query) or
retrieve a list of items in small subsets.
The Registration API is a RESTful HTTP API in accordance with the recommendations defined in [RFC7231] and [REST-IOT]. The default serialization format for all request and success response bodies MUST be JSON, with JSON-LD 1.1 [JSON-LD11] syntax to support extensions and semantic processing. Directories MAY accept additional representations based on request's indicated Content-Type or Content-Encoding, and provide additional representations through server-driven content negotiation.
The Registration API MUST provide create, retrieve, update, delete, and listing (CRUDL) interfaces. The operations are described below:
The API MUST allow registration of a TD object passed as request body.
The request SHOULD contain application/td+json Content-Type header for
JSON serialization of TD.
The TD object must be validated in accordance with § 6.2.2.1.6 Validation.
A TD which is identified with an id attribute MUST be handled
differently with one that has no identifier (Anonymous TD).
The create operations are elaborated below:
PUT request
at /things/{id} endpoint, where id is the unique TD identifier.
Upon successful processing, the server MUST respond with
201 (Created) status.
Note: If the target location corresponds to an existing TD, the request shall instead proceed as an Update operation and respond the appropriate status code (see Update section).
The create operation for TDs that have identifiers is specified
as createThing action in § 8.1 Directory API Thing Description.
POST request
at /things endpoint.
Upon successful processing, the server MUST respond with 201 (Created) status
and a Location header containing a system-generated identifier for the TD.
The scheme of the system-generated ID is described in § 6.2.1.3 Anonymous TD Identifiers.
The create operation for Anonymous TDs is specified as createAnonymousThing action in
§ 8.1 Directory API Thing Description.
A server that supports expirable TDs will realize such functionality
as described in § 6.2.1.2 Registration Expiry.
In particular, if ttl (relative expiry) is given during the creation,
such servers will calculate and store the expires value.
Error responses:
Registration of TDs using non-idempotent HTTP POST method enables creation of anonymous TDs (TDs without id attribute). The producer can distinguish between the created TDs using the unique-system generated IDs given in the response Location header.
A side-effect of this is that clients will be able to register duplicate TDs accidentally or on purpose.
Need to clarify:
A TD MUST be retrieved from the directory using an HTTP GET request
at /things/{id} endpoint, where id is the unique TD identifier.
A successful response MUST have 200 (OK) status, contain application/td+json
Content-Type header, and the requested TD in body.
The retrieve operation is specified as retrieveThing action in
§ 8.1 Directory API Thing Description.
Error responses:
id not found.The following is an example of a retrieved TD:
This is an Enriched TD which includes the registration information such as the creation and modification time of the TD within the directory.
The example below shows a retrieved Anonymous TD that is in
Enriched TD form and has local identifier urn:uuid:48951ff3-4019-4e67-b217-dbbf011873dc.
The following is an example of a retrieved TD that was registered with a relative expiry time of 3600 seconds (one hour). The server has calculated the absolute expiry time as one hour after the modification time.
For the sake of readability, the time values in this example are set to exact numbers. In realistic settings, time values may include fractions.The API MUST allow modifications to an existing TD as full replacement or partial updates. The update operations are described below:
PUT request
at /things/{id} endpoint, where id is the identifier of the existing TD.
The request SHOULD contain application/td+json Content-Type header for JSON
serialization of TD.
The TD object must be validated in accordance with § 6.2.2.1.6 Validation.
Upon success, the server MUST respond with 204 (No Content) status.
A server that supports expirable TDs will realize such functionality
as described in § 6.2.1.2 Registration Expiry.
If ttl (relative expiry) is set during the update operation,
the server will calculate and set the expires (absolute expiry) value.
This operation is specified as updateThing property in
§ 8.1 Directory API Thing Description.
Note: If the target location does not correspond to an existing TD,
the request shall instead proceed as a Create operation and respond
the appropriate status code (see Create section). In other words, an HTTP PUT
request acts as a create or update operation.
PATCH request
at /things/{id} endpoint, where id is the identifier of the existing TD.
The partial update MUST be processed using the JSON merge patch format
format described in [RFC7396].
The request MUST contain application/merge-patch+json Content-Type header for JSON
serialization of the merge patch document.
The input MUST be in Partial TD form and conform to the
original TD structure.
If the input contains members that appear in the original TD,
their values are replaced. If a member do not appear in the
original TD, that member is added. If the member is set to null
but appear in the original TD, that member is removed.
Members with object values are processed recursively.
After applying the modifications, the TD object must be validated in accordance with § 6.2.2.1.6 Validation.
Upon success, the server MUST respond with a 204 (No Content) status.
A server that supports expirable TDs will realize such functionality
as described in § 6.2.1.2 Registration Expiry.
During the partial update operation, if the resulting TD has
ttl (relative expiry), the server will calculate and set a new
expires (absolute expiry) value.
This operation is specified as partiallyUpdateThing property in
§ 8.1 Directory API Thing Description.
The following example is a merge patch document to update only the
base and registration expires fields of a TD:
Error responses:
id not found (for PATCH only).
A TD MUST be removed from the directory when an HTTP DELETE request is submitted
at /things/{id}, where id is the identifier of the existing TD.
A successful response MUST have 204 (No Content) status.
The retrieve operation is specified as deleteThing property in
§ 8.1 Directory API Thing Description.
Error responses:
id not found.The listing endpoint provides different ways to query the collection of full TD objects from the directory.
In many scenarios, retrieving parts instead of full TD objects is preferred because
only a subset of elements are needed (e.g. id and href of a property for all TDs)
and to save networking resources. The Search API allows querying parts of TD objects;
see § 6.2.2.4 Search.
The list of TDs MUST be retrieved from the directory using an HTTP GET request
at /things endpoint.
A successful response MUST have 200 (OK) status, contain application/ld+json
Content-Type header, and an array of TDs in the body.
There may be scenarios in which clients need to retrieve the collection in small subsets of TDs. While the Search API (§ 6.2.2.4 Search) does offer the ability to query a specific range, it may not be optimal, nor developer-friendly. The server MAY support pagination to return the collection in small subsets. The pagination must be based on the following rules:
limit query parameter is set to a positive integer,
the server MAY respond with a subset of TDs totalling
to less than or equal to the requested number.
next Link header [RFC8288]
with the URL of the next subset.
The next link MUST have the same limit argument given on the initial
request as well as a zero-based offset argument anchored at
the beginning of the next subset.
The link may be absolute or relative to directory API's base URL.
Moreover, it may include additional arguments that are necessary for
ordering or session management.
canonical Link header [RFC8288]
pointing to the collection and include an etag parameter to represent
the current state of the collection.
The link may be absolute or relative to directory API's base URL.
The etag value could be a revision number, timestamp, or UUID Version 4,
set whenever the TD collection changes in a way that affects the
ordering of the TDs.
The clients may rely on the etag value to know whether the collection
remains consistent across paginated retrieval of the collection.
For example, creation or deletion of TDs or update of TD fields used for
ordering may make shift the calculated paging window.
sort_by to select a field (e.g. created)
and sort_order to choose the order
(i.e. asc or desc for ascending and descending ordering).
If the server does not support custom sorting,
it MUST reject the request with 501 (Not Implemented) status.
If sorting attributes are accepted, they MUST be added consistently to all next links.
This above specification follows a subset of Linked Data Paging [LDP-Paging] to allow optional pagination of the JSON-LD array. Additional parts of Linked Data Paging may be implemented for examples to honour client's query preference or to add other link relations for semantic annotation and alternative navigation links.
The following example provides a walk-through of the paginated retrieval of TDs:Alternative to a pure array of TDs as the body of the response, the server MAY send a more verbose payload allowing server-side information, like pagination information, to be put in addition to the actual data.
For pagination information the alternative format leans against the formats as described in Hydra Advanced Concepts, more concretely the Partial Collection View. Adapted to our purposes and using the members field to accomodate the array of TDs, it looks like as follows for the listing endpoint:
To tell the server which format to send, the additional query parameter ?format=array|collection
can be added to the request. ?format=array is the default parameter, does not have to be provided
explicitly, and yields to a server response of the pure array of TDs. ?format=collection
should yield to a server response with the format as described in Example 8.
Serializing and returning the full list of TDs may be burdensome to servers. As such, servers should serialize incrementally and utilize protocol-specific mechanisms to respond in chunks. HTTP/1.1 servers SHOULD perform chunked Transfer-Encoding [RFC7230] to respond the data incrementally. Most HTTP/1.1 clients automatically process the data received with chunked transfer encoding. Memory-constrained applications which require the full list should consider processing the received data incrementally. Chunked transfer encoding is not supported in HTTP/2. HTTP/2 servers SHOULD respond the data incrementally using HTTP Frames [RFC7540].
The listing operation is specified as things property in
§ 8.1 Directory API Thing Description.
Error responses:
The syntactic validation of TD objects before storage is RECOMMENDED to prevent common erroneous submissions. The server MAY use Thing Description JSON Schema to validate standard TD vocabulary, or a more comprehensive JSON Schema to also validate extensions.
If the server fails to validate the TD object, it MUST inform the client
with necessary details to identify and resolve the errors.
The validation error MUST be described as Problem Details [RFC7807]
with an extension field called validationErrors, set to an array of objects
with field and description fields.
This is necessary to represent the error in a machine-readable way.
How much validation does a directory need to do?
To do: Other administrative functions not having to do with CRUD of individual records, for example, security configuration. Also, administrator roles may expand the capabilities of administrators for management of records (for instance, the ability to delete a record they did not create).
The Notification API is to notify clients about the changes
to Thing Descriptions maintained within the directory.
The Notification API MUST follow the Server-Sent Events [EVENTSOURCE]
specifications to serve events to clients
at /events endpoint.
In particular, the server responds to successful requests with 200 (OK) status
and text/event-stream Content Type.
Re-connecting clients may continue from
the last event by providing the last event ID as Last-Event-ID header value.
The server SHOULD provide an event ID as the id field in each event
and respond to re-connecting clients by delivering all missed events.
create, update, and delete event types.
The server MUST support event filtering based on the event type given by the client upon subscription.
For example, given the URI Template /events{/type}:
/events/create instructs the server to only deliver events of
type create
/events instructs the server to deliver all events
create and delete) from the server.
When using HTTP/2, multiple subscriptions on the same domain (HTTP streams)
get multiplexed on a single connection.
diff query parameter is set to true and the event has create type,
the server MAY return the whole TD object as event data.
diff query parameter is set to true and the event has update type,
the server MAY inform the client about the updated parts following the
JSON Merge Patch [RFC7396] format.
An update event data that is based on JSON Merge Patch [RFC7396]
MUST always include the identifier of the TD regardless of whether it
is changed.
The following example shows the event triggered on update of the TD from Example 11:
diff query parameter MUST be ignored for delete events.
In other words, the server does not need to include additional properties in
the payload of delete events when diff is set to true.
diff query parameter
is requested with such query parameter, it MUST
reject the request with 501 (Not Implemented) status.
This is to inform the clients about the lack of such functionality at the
connection time to avoid runtime exceptions caused by missing
event data attributes.
The Notification API is specified as three event affordances in
§ 8.1 Directory API Thing Description, namely:
thingCreation, thingUpdate, and thingDeletion.
Some early SSE implementations (including HTML5 EventSource) do not allow setting custom headers in the initial HTTP request. Authorization header is required in few OAuth2 flows and passing it as a query parameter is not advised. There are polyfills for browsers and modern libraries which allow setting Authorization header.
Sub-API to search a directory, e.g. issue a query.
There are different forms and levels of query possible, for example,
syntactic (JSONPath, XPath) vs. semantic (SPARQL),
and the more advanced query types may not be
supported by all directories.
So this API will have further subsections,
some of which will be optional.
Search also includes a sub-API for managing listing the contents (eg returned by
a query) including handling pagination, etc.
Note that one special form of query will be able to return everything.
Results may be subject to the requestor's authorization.
To discuss further:
Federated queries to other TDDs, Spatial and network-limited queries, Links
GET request
at /search/jsonpath?query={query} endpoint, where query is the JSONPath expression.
The request MUST contain a valid JSONPath [JSONPATH] as searching parameter.
A successful response MUST have 200 (OK) status, contain
application/json Content-Type header, and in
the body a set of complete TDs or a set of TD fragments.
The syntactic search with JSONPath is specified as searchJSONPath action in
§ 8.1 Directory API Thing Description.
List of errors:
GET request
at /search/xpath?query={query} endpoint, where query is the XPath expression.
The request MUST contain a valid XPath [xpath-31] as search parameter.
A successful response MUST have 200 (OK) status, contain
application/json Content-Type header, and in
the body a set of complete TDs or a set of TD fragments.
The syntactic search with XPath is specified as searchXPath action in
§ 8.1 Directory API Thing Description.
List of errors:
GET requests
at /search/sparql?query={query} endpoint, where query is the SPARQL expression.
The support for SPARQL search using HTTP POST method
at /search/sparql endpoint is OPTIONAL.
UPDATE queries are out of the scope for the API.
A successful response MUST have 200 (OK) status, and depending on the type
of query contain by default as Content-Type header application/ld+json
for CONSTRUCT and DESCRIBE queries or
application/json for SELECT or ASK.
The response body MAY contain TD fragments or a set of TDs depending on the query.
The semantic search with SPARQL is specified as searchSPARQL action in
§ 8.1 Directory API Thing Description.
List of errors:
Minimum security and privacy requirements for confidentiality, authentication, access control, etc.
This section is non-normative.
Security and privacy are cross-cutting issues that need to be considered in all WoT building blocks and WoT implementations. This chapter summarizes some general issues and guidelines to help preserve the security and privacy of concrete WoT discovery implementations. For a more detailed and complete analysis of security and privacy issues, see the WoT Security and Privacy Guidelines specification [WOT-SECURITY].
The WoT discovery architecture is designed to avoid a dependence on the security and privacy of existing discovery schemes by using a two-phase approach and requiring authorization before metadata release. However several security and privacy risks still exist. These are listed below along with possible mitigations. The level of risk to privacy in particular depends on the use case and whether there is a risk that information related to a person might be distributed in a fashion inconsistent with the privacy desires of that person. We distinguish the following broad classes of use case scenarios:
All of these in fact carry privacy risks. Even in the case of factory automation, there is the chance that data about employee performance would be captured and would have to be managed appropriately.
With these categories established, we will now discuss some specific risks and potential mitigations.
Certain functions of the directory service, in particular search queries, may require significant resources to execute and this fact can be used to launch DDoS attacks against WoT Thing Description Directory services.
This is mostly of concern in the Service scenario, where the metadata requester is a private individual and the provider is an institution. In some cases this risk may appear in Peer-to-Peer scenarios as well.
A discovery service may potentially allow the approximate location of a person to be determined without their consent. This risk occurs in some specific circumstances which can be avoided or mitigated. It is also similar to the risk posed by other network services such as DHCP and DNS.
For this risk to occur, there first has to be an IoT device that can be reliably associated with a person's location, such as a necessary medical device or a vehicle. Note that the risk only applies to personal use cases, not institutional ones. Secondly, the device has to be configured to register automatically with the nearest directory service. In this case, the location of the device can be inferred from the network range of the directory service and the location of the person inferred from the location of the device.
There are a few variants of this:
Some of these risks are shared by similar services. For example, DCHP automatically responds to requests for IP addresses on a local network, and devices typically provide an identifier (a MAC address) as part of this process, and the DHCP server maintains a registry. In theory, someone with access to the DHCP server in, say, a cafe, could use this information to track someone's phone and infer their location.
Below is a generic Thing Description for the Directory API with OAuth2 security. This specification only covers the HTTP and SSE protocol bindings. Other protocol bindings may be specified in future. The Thing Description alone should not be considered as the reference to implement or interact with a directory. The full specification is available as human-readable text in § 6.2.2 Directory Service API.
{
"@context": [
"http://www.w3.org/ns/td",
"https://w3c.github.io/wot-discovery/context/discovery-context.jsonld"
],
"@type": "ThingDirectory",
"title": "Thing Description Directory (TDD)",
"version": {
"instance": "1.0.0-alpha"
},
"securityDefinitions": {
"oauth2_code": {
"scheme": "oauth2",
"flow": "code",
"authorization": "https://auth.example.com/authorization",
"token": "https://auth.example.com/token",
"scopes": [
"write",
"read",
"readAll",
"search",
"notification"
]
},
"oauth2_client": {
"scheme": "oauth2",
"flow": "client",
"token": "https://auth.example.com/token",
"scopes": [
"write",
"read",
"readAll",
"search",
"notification"
]
},
"oauth2_device": {
"scheme": "oauth2",
"flow": "device",
"authorization": "https://auth.example.com/device_authorization",
"token": "https://auth.example.com/token",
"scopes": [
"write",
"read",
"readAll",
"search",
"notification"
]
},
"combo_sc": {
"scheme": "combo",
"oneOf": [
"oauth2_code",
"oauth2_client",
"oauth2_device"
]
}
},
"security": "combo_sc",
"base": "https://tdd.example.com",
"properties": {
"things": {
"description": "Retrieve all Thing Descriptions",
"uriVariables": {
"offset": {
"title": "Number of TDs to skip before the page",
"type": "number",
"default": 0
},
"limit": {
"title": "Number of TDs in a page",
"type": "number"
},
"format": {
"title": "Payload format",
"type": "string",
"enum": ["array", "collection"],
"default": "array"
},
"sort_by": {
"title": "Comparator TD attribute for collection sorting",
"type": "string",
"default": "id"
},
"sort_order": {
"title": "Sorting order",
"type": "string",
"enum": ["asc", "desc"],
"default": "asc"
}
},
"forms": [
{
"href": "/things",
"htv:methodName": "GET",
"response": {
"description": "Success response",
"htv:statusCodeValue": 200,
"contentType": "application/ld+json"
},
"scopes": "readAll"
},
{
"href": "/things{?offset,limit,sort_by,sort_order}",
"htv:methodName": "GET",
"response": {
"description": "Success response",
"htv:statusCodeValue": 200,
"contentType": "application/ld+json",
"htv:headers": [
{
"htv:fieldName": "Link"
}
]
},
"additionalResponses": [
{
"description": "Invalid query arguments",
"contentType": "application/problem+json",
"htv:statusCodeValue": 400
}
],
"scopes": "readAll"
}
]
}
},
"actions": {
"createThing": {
"description": "Create a Thing Description",
"uriVariables": {
"id": {
"@type": "ThingID",
"title": "Thing Description ID",
"type": "string",
"format": "iri-reference"
}
},
"forms": [
{
"href": "/things/{id}",
"htv:methodName": "PUT",
"contentType": "application/td+json",
"response": {
"description": "Success response",
"htv:statusCodeValue": 201
},
"additionalResponses": [
{
"description": "Invalid serialization or TD",
"contentType": "application/problem+json",
"htv:statusCodeValue": 400
}
],
"scopes": "write"
}
]
},
"createAnonymousThing": {
"description": "Create an anonymous Thing Description",
"forms": [
{
"href": "/things",
"htv:methodName": "POST",
"contentType": "application/td+json",
"response": {
"description": "Success response including the system-generated URI",
"htv:headers": [
{
"description": "System-generated URI",
"htv:fieldName": "Location"
}
],
"htv:statusCodeValue": 201
},
"additionalResponses": [
{
"description": "Invalid serialization or TD",
"contentType": "application/problem+json",
"htv:statusCodeValue": 400
}
],
"scopes": "write"
}
]
},
"retrieveThing": {
"description": "Retrieve a Thing Description",
"uriVariables": {
"id": {
"@type": "ThingID",
"title": "Thing Description ID",
"type": "string",
"format": "iri-reference"
}
},
"safe": true,
"idempotent": true,
"forms": [
{
"href": "/things/{id}",
"htv:methodName": "GET",
"response": {
"description": "Success response",
"htv:statusCodeValue": 200,
"contentType": "application/td+json"
},
"additionalResponses": [
{
"description": "TD with the given id not found",
"contentType": "application/problem+json",
"htv:statusCodeValue": 404
}
],
"scopes": "read"
}
]
},
"updateThing": {
"description": "Update a Thing Description",
"uriVariables": {
"id": {
"@type": "ThingID",
"title": "Thing Description ID",
"type": "string",
"format": "iri-reference"
}
},
"forms": [
{
"href": "/things/{id}",
"htv:methodName": "PUT",
"contentType": "application/td+json",
"response": {
"description": "Success response",
"htv:statusCodeValue": 204
},
"additionalResponses": [
{
"description": "Invalid serialization or TD",
"contentType": "application/problem+json",
"htv:statusCodeValue": 400
}
],
"scopes": "write"
}
]
},
"partiallyUpdateThing": {
"description": "Partially update a Thing Description",
"uriVariables": {
"id": {
"@type": "ThingID",
"title": "Thing Description ID",
"type": "string",
"format": "iri-reference"
}
},
"forms": [
{
"href": "/things/{id}",
"htv:methodName": "PATCH",
"contentType": "application/merge-patch+json",
"response": {
"description": "Success response",
"htv:statusCodeValue": 204
},
"additionalResponses": [
{
"description": "Invalid serialization or TD",
"contentType": "application/problem+json",
"htv:statusCodeValue": 400
},
{
"description": "TD with the given id not found",
"contentType": "application/problem+json",
"htv:statusCodeValue": 404
}
],
"scopes": "write"
}
]
},
"deleteThing": {
"description": "Delete a Thing Description",
"uriVariables": {
"id": {
"@type": "ThingID",
"title": "Thing Description ID",
"type": "string",
"format": "iri-reference"
}
},
"forms": [
{
"href": "/things/{id}",
"htv:methodName": "DELETE",
"response": {
"description": "Success response",
"htv:statusCodeValue": 204
},
"additionalResponses": [
{
"description": "TD with the given id not found",
"contentType": "application/problem+json",
"htv:statusCodeValue": 404
}
],
"scopes": "write"
}
]
},
"searchJSONPath": {
"description": "JSONPath syntactic search",
"uriVariables": {
"query": {
"title": "A valid JSONPath expression",
"type": "string"
}
},
"safe": true,
"idempotent": true,
"forms": [
{
"href": "/search/jsonpath?query={query}",
"htv:methodName": "GET",
"response": {
"description": "Success response",
"contentType": "application/json",
"htv:statusCodeValue": 200
},
"additionalResponses": [
{
"description": "JSONPath expression not provided or contains syntax errors",
"contentType": "application/problem+json",
"htv:statusCodeValue": 400
}
],
"scopes": "search"
}
]
},
"searchXPath": {
"description": "XPath syntactic search",
"uriVariables": {
"query": {
"title": "A valid XPath expression",
"type": "string"
}
},
"safe": true,
"idempotent": true,
"forms": [
{
"href": "/search/xpath?query={query}",
"htv:methodName": "GET",
"response": {
"description": "Success response",
"contentType": "application/json",
"htv:statusCodeValue": 200
},
"additionalResponses": [
{
"description": "XPath expression not provided or contains syntax errors",
"contentType": "application/problem+json",
"htv:statusCodeValue": 400
}
],
"scopes": "search"
}
]
},
"searchSPARQL": {
"description": "SPARQL semantic search",
"uriVariables": {
"query": {
"title": "A valid SPARQL 1.1. query",
"type": "string"
}
},
"safe": true,
"idempotent": true,
"forms": [
{
"href": "/search/sparql?query={query}",
"htv:methodName": "GET",
"response": {
"description": "Success response",
"htv:statusCodeValue": 200
},
"additionalResponses": [
{
"description": "SPARQL query not provided or contains syntax errors",
"contentType": "application/problem+json",
"htv:statusCodeValue": 400
}
],
"scopes": "search"
},
{
"href": "/search/sparql",
"htv:methodName": "POST",
"response": {
"description": "Success response",
"contentType": "application/json",
"htv:statusCodeValue": 200
},
"additionalResponses": [
{
"description": "SPARQL query not provided or contains syntax errors",
"contentType": "application/problem+json",
"htv:statusCodeValue": 400
}
],
"scopes": "search"
}
]
}
},
"events": {
"thingCreation": {
"description": "Registration of Thing Descriptions inside the directory",
"uriVariables": {
"diff": {
"description": "Receive the full created TD as event data",
"type": "boolean"
}
},
"data": {
"title": "Partial/Full TD",
"type": "object"
},
"forms": [
{
"op": "subscribeevent",
"href": "/events/create{?diff}",
"subprotocol": "sse",
"contentType": "text/event-stream",
"htv:headers": [
{
"description": "ID of the last event for reconnection",
"htv:fieldName": "Last-Event-ID"
}
],
"scopes": "notification"
}
]
},
"thingUpdate": {
"description": "Updates to Thing Descriptions within the directory",
"uriVariables": {
"diff": {
"description": "Include TD changes inside event data",
"type": "boolean"
}
},
"data": {
"title": "Partial TD",
"type": "object",
"contentMediaType": "application/merge-patch+json"
},
"forms": [
{
"op": "subscribeevent",
"href": "/events/update{?diff}",
"subprotocol": "sse",
"contentType": "text/event-stream",
"htv:headers": [
{
"description": "ID of the last event for reconnection",
"htv:fieldName": "Last-Event-ID"
}
],
"scopes": "notification"
}
]
},
"thingDeletion": {
"description": "Deletion of Thing Descriptions from the directory",
"data": {
"title": "Partial TD",
"type": "object"
},
"forms": [
{
"op": "subscribeevent",
"href": "/events/delete",
"subprotocol": "sse",
"contentType": "text/event-stream",
"htv:headers": [
{
"description": "ID of the last event for reconnection",
"htv:fieldName": "Last-Event-ID"
}
],
"scopes": "notification"
}
]
}
}
}
The scopes may need to be more concrete to able to allow updates but prevent creation.
Need to confirm if equivalent OpenAPI spec can be easily created out of the TD in § 8.1 Directory API Thing Description. If yes, a sentence may be added indicating this possibility.
The context URIs are tentative and subject to change.
The TD defined for a Directory service should really be a Thing Model. We should also "template" the "base" parameter (or omit it, and say it needs to be added when the Thing Model is instantiated).
Since we are talking about a class of things, we should have a Thing Model. However, the definition of Thing Model needs to be updated to allow specifying security scheme templates, form templates (including URL templates giving https), etc.
IANA will be asked to allocate the following value into the Well-Known URI defined in [RFC8615].
wot-thing-description
We are currently discussing whether we should adopt a shorter URI suffix (such as wot-td)
in view of limited packet lengths for some protocols.
IANA will be asked to allocate the following value into Service Name and Transport Protocol Port Number Registry defined in [RFC6335].
wot
IANA will be asked to allocate the following values into the Resource Type (rt=)
Link Target Attribute Values sub-registry of the Constrained Restful Environments (CoRE)
Parameters registry defined in [RFC6690].
| Value | Description | Reference |
|---|---|---|
wot.thing |
Thing Description of a Thing | § 5.4 CoRE Link Format and CoRE Resource Directory |
wot.directory |
Directory Description of a Thing Description Directory | § 5.4 CoRE Link Format and CoRE Resource Directory |
DirectoryDescription
identifying TDs of directories and
a type LinkDescription to identify a TD that is just a link to another
TD (useful for referring to remote directories in order to support federation).
Many thanks to the W3C staff and all other active Participants of the W3C Web of Things Interest Group (WoT IG) and Working Group (WoT WG) for their support, technical input and suggestions that led to improvements to this document.
Referenced in:
Referenced in:
Referenced in:
Referenced in: