Copyright © 2017-2020 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 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 (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 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 March 2019 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 [sparql], while potentially suitable for some advanced use cases, might require to 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, 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 present document uses the terminology defined in the WoT Architecture [wot-architecture] document, and also the additional terms defined here. The WoT prefix is used to avoid ambiguity for terms that are (re)defined specifically for Web of Things concepts.
id attribute).
This section is non-normative.
Examples of why we need discovery.
This section is non-normative.
The WoT discovery process should have the following capabilities:
This section is non-normative.
This section is non-normative.
This section is non-normative.
This section is non-normative.
This section is non-normative.
This section is non-normative.
This section is non-normative.
Two-Phase approach.
Description of supported introductions, and requirements for new introduction mechanisms.
Any mechanism that results in a single URL.
This includes Bluetooth beacons, QR codes, and written URLs to be
typed by a user.
A GET on all such URLs MUST result in a TD.
For self-describing Things, this can be the TD of the Thing itself.
If the URL references a Directory, this MUST be the TD of the
Directory service.
A Directory can be distinguished from a Thing by the use of an
@type including the semantic term Directory.
To Do.
To Do.
To Do.
Description of supported explorations, and requirements for new exploration mechanisms.
Mechanism for devices to self-describe, hosting their own TDs.
Mechanism for TDs to be hosted in a searchable directory service.
Description of conceptual data organization in a directory.
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.
Below is a generic Thing Description for the Directory HTTP API with OAuth2 security. The Thing Description alone should not be considered as the full specification to implement or interact with a directory. Additional details for every interaction are described in human-readable form in the subsequent sections.
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 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 (CRUD) interfaces based on the following specification:
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 SHOULD be validated syntactically using the
Thing Description JSON Schema
[WoT-Thing-Description].
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 specified as createTD action in
Directory's Thing Description
and elaborated below:
PUT request at a
target location (HTTP path) containing the unique TD id.
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).
POST request.
Upon successful processing, the server MUST respond with 201 (Created) status
and a Location header containing a system-generated identifier for the TD.
The identifier SHOULD be a Version 4 UUID URN [RFC4122].
Error responses:
The server should employ a mechanism to eliminate duplication of TDs submitted with
a POST request. The spec need to have recommendations on how to perform this.
A TD MUST be retrieved from the directory using an HTTP GET request,
including the identifier of the TD as part of the path.
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 retrieveTD property in
Directory's Thing Description.
Error responses:
id not found.
The API MUST allow modifications to existing TDs as full replacement or partial updates.
The request SHOULD contain application/td+json Content-Type header for JSON
serialization of TD.
The update operations are described below:
PUT request
to the location corresponding to the existing TD.
The TD object SHOULD be
validated syntactically using the
Thing Description JSON Schema
[WoT-Thing-Description].
Upon success, the server MUST respond with 204 (No Content) status.
This operation is specified as updateTD property in
Directory's 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. An HTTP PATCH may be used for
an update-only operation.
PATCH request to the location corresponding to the existing TD.
The modified parts MUST conform to the original TD structure.
The input MAY include other existing parts of the TD or the whole TD object.
When the whole TD object is provided as input, the operation acts as an update-only action.
After applying the modifications,
the TD object SHOULD be validated syntactically using the
Thing Description JSON Schema
[WoT-Thing-Description].
Upon success, the server MUST respond with a 204 (No Content) status.
This operation is specified as updatePartialTD property in
Directory's Thing Description.
Error responses:
id not found (for PATCH only).
A TD MUST be removed from the directory when an HTTP DELETE request
is submitted to the location corresponding to the existing TD.
A successful response MUST have 204 (No Content) status.
The retrieve operation is specified as deleteTD property in
Directory's Thing Description.
Error responses:
id not found.
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).
Sub-API to notify clients of events, such as updates to TDs.
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:
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].
Special thanks to X, Y, and Z for their contributions to this document.
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.