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.

Introduction

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 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.

Terminology

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.

Anonymous TD
A Thing Description without an identifier (`id` attribute).
Discovery
In the WoT context, the process of finding and retrieving Thing metadata in the form of Thing Descriptions for Things satisfying some criteria of interest.
Exploration
A discovery mechanism that provides access to detailed metadata in the form of one or more Thing Descriptions. Exploration mechanisms are in general protected by security mechansism and are accessible only to authorized users.
Introduction
A "first contact" discovery mechanism, whose result is a URL that references an exploration mechanism. Introduction mechanisms themselves should not directly provide metadata, and in general are designed to be open.
Thing Description Directory (TDD)
A directory service with a prescribed API that allows the registration, management, and search of a database of Thing Descriptions. Note that the acronym should be TDD, not TD, to avoid confusion with Thing Descriptions (TDs).
Partial TD
A data model partially conformant to the Thing Description schema by including only a subset of the attributes.

Architecture

shows an overview of discovery process.
Discovery process overview
Discovery process overview

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.

Introduction Mechanisms

This chapter describes a mechanism for discovering a Thing or a Directory Service. The following mechanism is provided by the Thing or the Directory Service so that Consumer can discover the Thing Description or a URL that point to the Thing Description.

Direct

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.

Well-Known URIs

A Thing or Directory Service MAY use the Well-Known Uniform Resource Identifier [[RFC8615]] to advertise its presence. The Thing or Directory Service registers its own Thing Description into the following path: /.well-known/wot-thing-description.

When the HTTP GET access is made to the above path, the HTTP server MUST return a Thing Description with the content-type set to application/td+json.

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]].

DNS-Based Service Discovery

A Thing or Directory Service 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 Directory Service MUST be _wot. And the Service Name to indicate the Directory Service 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. 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:

td
Absolute pathname of the Thing Description of the Thing or Directory Service.
type
Type of the Thing Description, i.e. Thing 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 Thing Description with the Directory Service.
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.

and shows example sequences of discovery of Thing and Directory Service using DNS-SD and mDNS.

An example sequence of discovery of Thing using DNS-SD and mDNS
An example sequence of discovery of Thing using DNS-SD and mDNS
An example sequence of discovery of Directory Service using DNS-SD and mDNS
An example sequence of discovery of Directory Service using DNS-SD and mDNS

CoRE Link Format and CoRE Resource Directory

A Thing or Directory Service MAY advertise its presence using the Constrained RESTful Environment (CoRE) Link Format [[RFC6690]]. And, a Thing or Directory Service MAY use the CoRE Resource Directory [[CoRE-RD]] to register a link to the Thing Description.

The endpoint type(et) of the Link that targets the Thing Description of the Thing MUST be wot.thing. The endpoint type of the Link that targets the Thing Description of the Directory Service MUST be wot.directory.

The endpoint types wot.thing and wot.directory are tentative.

DID Documents

A Thing or Directory Service MAY advertise its presence using the Decentralized Identifier (DID) [[DID-CORE]].

The DID Document obtained by resolving the DID of a Thing or Directory Service MUST contains a Service Endpoint which point to Thing Description of the Thing or Directory Service.

Exploration Mechanisms

To do: Description of supported explorations, and requirements for new exploration mechanisms.

Self-description

To do: Describe mechanisms for devices to self-describe, hosting their own TDs.

Directory

To do: Describe mechanisms for TDs to be hosted in a searchable directory service.

A Directory can be distinguished from a Thing by the use of an @type including the semantic term Directory.

Information Model

To Do: Formal definition of information contained in a directory and its organization.

Directory Service API

The Directory APIs must use secure protocols guaranteeing System User Data authenticity and confidentiality (see [[?WOT-SECURITY]]). The HTTP API MUST be exposed over HTTPS (HTTP Over TLS).

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.

Need to confirm if equivalent OpenAPI spec can be easily created out of the TD in [[[#directory-thing-description]]]. If yes, a sentence may be added indicating this possibility.

Registration

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.

The API needs to offer a mechanism to efficiently query all TDs. The search API may offer the expected functionality by searching for everything and adding protocol-specific pagination arguments. However, that is hardly RESTful. We could instead extend the registration API to CRUDL, adding Listing operation.
The operations are described below:

TD Creation

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 [[[#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 specified as `createTD` action in [[[#directory-thing-description]]] and elaborated below:

  • A TD MUST be submitted to the directory using an HTTP `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).

  • An Anonymous TD MUST be submitted to the directory using an HTTP `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:

  • 400 (Bad Request): Invalid serialization or TD. This is accompanied by an appropriate response message.
  • 401 (Unauthorized): No authentication.
  • 403 (Forbidden): Insufficient rights to the resource.

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.

TD Retrieval

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-thing-description]]].

Error responses:

  • 404 (Not Found): TD with the given `id` not found.
  • 401 (Unauthorized): No authentication.
  • 403 (Forbidden): Insufficient rights to the resource.

TD Update

The API MUST allow modifications to an existing TD as full replacement or partial updates. The update operations are described below:

  • A modified TD MUST replace an existing one when submitted using an HTTP `PUT` request to the location corresponding to 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 [[[#validation]]]. Upon success, the server MUST respond with 204 (No Content) status. This operation is specified as `updateTD` property in [[[#directory-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 existing TD MUST be partially modified when the modified parts are submitted using an HTTP `PATCH` request to the location corresponding to 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 [[[#validation]]]. Upon success, the server MUST respond with a 204 (No Content) status. This operation is specified as `updatePartialTD` property in [[[#directory-thing-description]]].

Error responses:

  • 400 (Bad Request): Invalid serialization or TD. This is accompanied by an appropriate response message.
  • 404 (Not Found): TD with the given `id` not found (for `PATCH` only).
  • 401 (Unauthorized): Rejecting a request without appropriate authentication.
  • 403 (Forbidden): Rejecting a request due to insufficient rights to the resource.

TD Deletion

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-thing-description]]].

Error responses:

  • 404 (Not Found): TD with the given `id` not found.
  • 401 (Unauthorized): No authentication.
  • 403 (Forbidden): Insufficient rights to the resource.

Validation

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.

It would be nice to include an example validation result in the uniform error format (i.e. RFC7807 Problem Details).

Management

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).

Notification

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. 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. This API is specified as `registration` event in [[[#directory-thing-description]]].

Event Types
The server MUST produce events for creation, update, and deletion of Thing Descriptions represented by `created_td`, `updated_td`, `deleted_td` keywords respectively.
Event Filtering
The API supports server-side filtering of events to reduce resource consumption by delivering only the events required by clients. The filtering is based on query parameters passed to the server at connection time. The filtering behavior is described below:
  • The server MUST support event filtering based on the event types passed as one or more `type` query parameters. For example, in response to query `?type=created_td&type=deleted_td`, the server must only deliver events of types `created_td` and `deleted_td`. At the absence of any `type` query parameter, the server must deliver all types of events.
  • The server MUST support event filtering based on the Thing Description identifier passed as one or more `td_id` query parameters. For example, the query `?type=updated_td&td_id=urn:example:1234` must result in `updated_td` events for the TD identified with `urn:example:1234`.
  • The server MAY support event filtering based on the search expressions passed as one of `jsonpath`, `xpath`, or `sparql` query parameters. If the server does not support a given search query parameter, it MUST reject the request with 501 (Not Implemented) status.
Event Data
The event data MUST contain the JSON serialization of the event object. The event data object is defined by the following rules:
  • The event data object MUST at least include the identifier of the TD created, updated, or deleted at that event as value of `td_id` field.
  • When `include_changes` query parameter is set to `true`, the create event data object MAY include the created TD as the value of `created_td` field.
  • When `include_changes` query parameter is set to `true`, the update event data object MAY include the updated parts of the TD in Partial TD form as the value of `td_updates` field.
  • When a server which does not support the inclusion of changes inside event data object is requested with a `include_changes` query parameter, it MUST reject the request with 501 (Not Implemented) status.

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.

Security and Privacy

Minimum security and privacy requirements for confidentiality, authentication, access control, etc.

Security and Privacy Considerations

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]].

To do, some discussion of general security and privacy concerns and mitigations. Note that the architecture above is designed to address many such points, for example the two-phase approach and "authorization before metadata release" principles, so this would be a summary and a recap.

Recent Specification Changes

Acknowledgments

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.