Web of Things (WoT) Discovery

W3C Editor's Draft

This version:
https://w3c.github.io/wot-discovery/
Latest published version:
https://www.w3.org/TR/wot-discovery/
Latest editor's draft:
https://w3c.github.io/wot-discovery/
Editors:
Andrea Cimmino ( Universidad Politécnica de Madrid )
Michael McCool ( Intel Corp. )
Farshid Tavakolizadeh ( Fraunhofer-Gesellschaft )
Kunihiko Toumura ( Hitachi, Ltd. )
Participate:
GitHub w3c/wot-discovery
File a bug
Commit history
Pull requests
Contributors
In the GitHub repository

Copyright © 2017-2021 W3C ® ( MIT , ERCIM , Keio , Beihang ). W3C liability , trademark and permissive document license rules apply.

Abstract

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.

Status of This Document

This is a preview

Do not attempt to implement this version of the specification. Do not reference this version as authoritative in any way. Instead, see https://w3c.github.io/wot-discovery/ for the Editor's draft.

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 .

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

2. Conformance

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.

3. Terminology

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:

Anonymous TD
A Thing Description without an a user-defined 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.
Enriched TD
A Thing Description embedded with additional attributes for bookkeeping and discovery.
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.
TDD
Short for Thing Description Directory.
Thing Description Directory
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.

4. Architecture

This section is non-normative.

Figure 1 shows an overview of discovery process.
Discovery process overview
Figure 1 Discovery process overview
Editor's note : Discovery Architecture 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.

5. Introduction Mechanisms

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

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

5.2 Well-Known URIs

A Thing or Thing Description Directory may use the Well-Known Uniform Resource Identifier [ RFC8615 ] to advertise its presence. The Thing or Thing Description Directory registers 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 .

Editor's note : Registration of Well-known URI

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

5.3 DNS-Based Service Discovery

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 .

Editor's note : Service Names in existing implementations

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:

td
Absolute pathname of the Thing Description of the Thing or Directory Description of the Thing Description Directory .
type
Type of the Thing Description, i.e. Thing or Directory . If omitted, the type is assumed to be Thing .

Editor's note : Usage of a TXT record in existing implementations

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.

An example sequence of discovery of Thing using DNS-SD and mDNS
Figure 2 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
Figure 3 An example sequence of discovery of 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 ]. And, 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 .

Editor's note

The resource types wot.thing and wot.directory are tentative. See also §  8. IANA Considerations .

5.5 DID Documents

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 .

Issue 65 : Create typed links in DID Documents for WoT Directories DID

These should be consistent with a general model that we should also use for similar things, i.e. CoRE-RD and DNS-SD. We should discuss with DID the process for how to document a link type for use in DID Documents.

6. Exploration Mechanisms

Editor's note : Exploration Mechanism Overview

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

Figure 4 depicts the high-level information model for self-describing and directory services. These exploration mechanisms are described in §  6.1 Self-description and §  6.2 Directory .
Exploration mechanisms high-level class diagram
Figure 4 The high-level class diagram of the exploration mechanisms
The Thing Description Directory ontology defines two new Thing Description classes that may be used to model special exploratory metadata:
Directory Description
A TD which describes a directory instance. The Directory Description MUST use type DirectoryDescription from the discovery context or URI https://www.w3.org/2021/wot/discovery#DirectoryDescription .

Example 3 which describes the API of the Thing Description Directory is an example of this TD type.

Link Description
A TD which describes a reference to another TD. The Link Description MUST use type LinkDescription from the discovery context or URI https://www.w3.org/2021/wot/discovery#LinkDescription . The Link Description MUST define the reference 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 Link Description.

Issue 54 : Need to define the discovery types and vocabulary

The context and type URIs are tentative and subject to change.

6.1 Self-description

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:
HTTP

The HTTP-based self-description SHOULD be over HTTPS (HTTP Over TLS). 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 server SHOULD serve the requests after performing necessary authentication and authorization.

Error responses:

  • 401 (Unauthorized): No authentication.
  • 403 (Forbidden): Insufficient rights to the resource.

6.2 Directory

Editor's note : Directory Overview

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

6.2.1 Information Model

Editor's note : Directory Information Model

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

The ontology of a TD stored in a TDD
Figure 5 The ontology of a TD that can be stored in a Thing Description Directory .

As shown in Figure 4 , the Thing Description Directory can contain zero or more TD s. For every TD, the directory additionally maintains the registration information for bookkeeping and search purposes. A Enriched TD which embeds s embed the registration information is called an Enriched TD . inside them. The ontology of a TD maintained by the directory is illustrated in Figure 5 .

6.2.1.1 Registration Information
The following table lists the registration information attributes:
Vocabulary term Description Assignment Type
created Provides information when the TD instance was created inside the directory. system-generated (read-only) dateTime
modified Provides information when the TD instance was last modified inside the directory. system-generated (read-only) dateTime
6.2.1.2 Anonymous TD Identifiers
Anonymous TD s have no id (or @id ) and are considered as JSON-LD blank nodes [ JSON-LD11 ]. The server assigns a local identifier to such TDs to allow enable management and retrieval from the directory. In situations where the server exposes an Anonymous TD, it MUST add the local identifier to the Anonymous TD as a blank node identifier to allow local referencing. Blank node identifiers begin with _: . which look like IRIs with an underscore scheme.

For example, a an Anonymous TD that has local identifier 48951ff3-4019-4e67-b217-dbbf011873dc will have the following blank node identifier: identifier set as its id attribute: _:48951ff3-4019-4e67-b217-dbbf011873dc . Anonymous TD s that embed blank node identifiers are in Enriched TD forms.

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

Editor's note : WoT-specific error types

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.

Issue 82 : Creation of OpenAPI spec from Directory TD

Need to confirm if equivalent OpenAPI spec can be easily created out of the TD in Example 3 . If yes, a sentence may be added indicating this possibility.

6.2.2.1 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, and listing (CRUDL) interfaces. The operations are described below:

6.2.2.1.1 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 §  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 specified as createTD action in Example 3 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 UUID Version 4 [ RFC4122 ]. That is a random or pseudo-random number which does not carry unintended information about the host or the resource.

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.

Issue 18 : Consider TTL Use cases
In certain scenarios (e.g. automatic removal of obsolete or accidental registrations), the registration may benefit from an expiration time. The expiration time may be set explicity or relative to the registration time as a time-to-live (TTL) value.
Issue 48 : How to avoid duplicates in a directory

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:

  • What are the use cases where a duplicate TD is desired?
  • How can we mitigate accidental duplicates (deduplication)?
6.2.2.1.2 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 Example 3 .

Error responses:

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

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 48951ff3-4019-4e67-b217-dbbf011873dc set as its blank node identifier (see §  6.2.1.2 Anonymous TD Identifiers ). Note that id is an alias for @id from the active context.

6.2.2.1.3 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 §  6.2.2.1.6 Validation . Upon success, the server MUST respond with 204 (No Content) status. This operation is specified as updateTD property in Example 3 .

    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 §  6.2.2.1.6 Validation . Upon success, the server MUST respond with a 204 (No Content) status. This operation is specified as updatePartialTD property in Example 3 .

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): No authentication.
  • 403 (Forbidden): Insufficient rights to the resource.

6.2.2.1.4 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 Example 3 .

Error responses:

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

6.2.2.1.5 Listing

The listing endpoint provides a way to query the collection of TD objects from the directory. The Search API may be used to retrieve TD fragments; see §  6.2.2.4 Search .

The list of TDs MUST be retrieved from the directory using an HTTP GET request. A successful response MUST have 200 (OK) status, contain application/ld+json Content-Type header, and an array of TDs in the body.

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

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:

  • When the 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.
  • When there are more TDs after a returned subset of the collection, the response MUST contain a 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.
  • All paged responses MUST contain a 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.
  • By default, the collection MUST be sorted alphanumerically by the unique identifier of TDs. The server MAY support sorting by other TD attributes using query arguments: 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:

The paginated list operation is specified as retrieveTDs property in Example 3 .

Error responses:

  • 401 (Unauthorized): No authentication.
  • 403 (Forbidden): Insufficient rights to the resource.

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

Example 7 is an example error response with two validation errors.
Issue 99 : Define requirements and add section for validation

How much validation does a directory need to do?

  1. If it only supports syntactic queries, is JSONSchema validation sufficient? Do we also use SHACL?
  2. If we support SPARQL, do we need to do more to make sure the ontologies used are correct?
  3. Is there a subset of TD assertions we should check?
6.2.2.2 Management
Editor's note : Management API

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

6.2.2.3 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 Example 3 .

Event Types
The server MUST produce events attributed to the lifecycle of the Thing Descriptions within the directory using create , update , and delete event types.
Event Filtering
The API enables server-side filtering of events to reduce resource consumption by delivering only the events required by clients. Client libraries may offer additional filtering capabilities on the client-side. The server-side 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=create&type=delete , the server will only deliver events of types create and delete . At the absence of any type query parameter, the server will deliver all types of events.
  • The server MAY support event filtering based on the search expressions passed as one of jsonpath , xpath , or sparql query parameters. This is to detect changes on particular TDs or attributes and does not not affect the event's data object.

    For example, the JSONPath expression $.properties will reduce the number of events to TDs that change their properties attributes. The resulting events may be for created or deleted TDs with the properties attribute or updates to properties attribute of existing TDs.

    If the server does not support a given search query parameter, it MUST reject the request with 501 (Not Implemented) status. This is to inform the clients about the missing feature at the connection time and prevent unexpected network traffic and events.
Event Data
The event data MUST contain the JSON serialization of the event object. The event data object is a Partial TD or the whole TD object depending on the request:
  • The event data object MUST at least include the identifier of the TD created, updated, or deleted at that event in Partial TD form.
  • When full query parameter is set to true and the event has create type, the server MAY return the whole TD object as event data.
  • When full 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 9 :

  • The full query parameter MUST be ignored for delete events. In other words, when the full query parameter is set to true and the event has delete type, the server must only provide the identifier in event data.
  • When a server which does not support the full 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.
Editor's note : SSE Authorization Header

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.

6.2.3 Security and Privacy

Editor's note : Security Considerations Overview

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

7. Security and Privacy Considerations

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:

Institutional
Both the Things producing metadata and the Consumers of that metadata are owned and controlled by an institution or representatives of an institution. Example: Automation in a factory where a control system is accessing the state of an assembly line in order to evaluate quality.
Service
The Things producing metadata are owned and controlled by an institution or representatives of an institution while the consumers are individuals. Example: driver of an electric vehicle accessing the TD for a charge station in order to check status of a charge.
Personal
Both the Things producing metadata and the Consumers of that metadata are owned and controlled by the same individual. Example: A smart home control system for charging an electric car from home-attached solar panels, both home and car owned by the same person.
Personal Peer-to-Peer
The Things producing metadata and the Consumers of that metadata are owned and controlled by different individuals. Example: A smart home control system for charging a guest's electric car from home-attached solar panels.
Institutional Peer-to-Peer
The Things producing metadata and the Consumers of that metadata are owned and controlled by different institutions. Example: A utility provides and manages power delivered to a factory, and the factory provides an interface for the utility to negotiate on-demand power usage reductions.
Client
The Things producing metadata are owned and controlled by an individual while the consumers are an institution or representatives of an institution. Example: A personal electric vehicle exposes an interface to a public charging station so that the charging station can evaluate the charge status of the vehicle.

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.

7.1 Denial of Service

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.

Mitigations:
A WoT Thing Description Directory implementation should
  • Limit the number of queries per unit time from the same reqeuestor
  • Limit the complexity of queries (for example, the total length of the query expression or its depth)
  • Use a watchdog timer to abort queries that take more than a certain maximum (implementation-configurable) amount of time.
In cases where queries are refused or aborted appropriate error responses should be returned.

7.2 Location Tracking

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.

Mitigations:
There are a few options to mitigate this risk:
  • Disable registration with public directories. Registration would still be possible with personal directories, for example, a home gateway, but a user could disable registration at other locations. This has the disadvantage that functionality is lost: personal devices cannot be discovered in public locations. This could be addressed by having internet-accessible private discovery services (e.g. the home gateway could provide an internet-accessible service, but with access control limiting use to authorized users.
  • Rotate IDs. Using fixed IDs makes it exceptionally easy to track devices. This problem also occurs in DHCP with MAC address and there is a similar partial mitigation: generate new random IDs periodically. There are however, a few issues. First of all, other identification information in the TD needs to be hidden. For example, client IDs issued by CSPs for API security should be omitted from TDs if they cannot be easily rotated. Second, if the device rotates the ID, the user may still need to know the current ID to find the device via discovery. This can be accomplished however by generating new IDs using a deterministic cryptographic generator that is a function of the current time. However, note that rotating IDs alone does not make tracking impossible since a TD might be fingerprinted. Also, updating an ID might be observable to the owner of the directory service, who could track and record the updated ID. Even if the TD is deleted and reinserted the association could be inferred. This is however exactly parallel to the situation with DHCP and rotation of MAC addresses. In general, however, generating new IDs at least for each service or person to which a TD is supplied makes it harder to connect registration events at different locations and times.
  • The problem of negative location inferencing can be mitigated by limiting access to private directories, for example in the home, by using access controls. If an attacker cannot access the service, they cannot retreive information to infer location. Access rights provided to guests (Peer-to-Peer Personal) should be appropriately time-limited. Use of long time-to-live values may be approprate in other cases. In addition, TDs should be updated in a directory only when they change. For example, the TD for a car may only be updated when new car firmware is available providing new services, and the time-to-live might be set at one month (covering most absences).
  • When explicit location information is available, whether stored in a TD or available in a property, additional care should be taken to only share the TD and/or access to the device with trusted partners, including directories. If the TD must be shared with a public directory, the location information can be stripped.

8. IANA Considerations

8.1 CoRE Resource Types Registration

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 [ wot-discovery ], §  5.4 CoRE Link Format and CoRE Resource Directory
wot.directory Directory Description of a Thing Description Directory [ wot-discovery ], §  5.4 CoRE Link Format and CoRE Resource Directory

A. Recent Specification Changes

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

C. References

C.1 Normative references

[CoRE-RD]
CoRE Resource Directory . Christian Amsüss; Zach Shelby; Michael Koster; Carsten Bormann; Peter van der Stok. IETF. 2 November 2020. URL: https://tools.ietf.org/html/draft-ietf-core-resource-directory-26
[DID-CORE]
Decentralized Identifiers (DIDs) v1.0 . Drummond Reed; Manu Sporny; Markus Sabadello. W3C. 18 March 2021. W3C Candidate Recommendation. URL: https://www.w3.org/TR/did-core/
[EVENTSOURCE]
Server-Sent Events . Ian Hickson. W3C. 28 January 2021. W3C Recommendation. URL: https://www.w3.org/TR/eventsource/
[JSON-LD11]
JSON-LD 1.1 . Gregg Kellogg; Pierre-Antoine Champin; Dave Longley. W3C. 16 July 2020. W3C Recommendation. URL: https://www.w3.org/TR/json-ld11/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels . S. Bradner. IETF. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[RFC2782]
A DNS RR for specifying the location of services (DNS SRV) . A. Gulbrandsen; P. Vixie; L. Esibov. IETF. February 2000. Proposed Standard. URL: https://datatracker.ietf.org/doc/html/rfc2782
[RFC4122]
A Universally Unique IDentifier (UUID) URN Namespace . P. Leach; M. Mealling; R. Salz. IETF. July 2005. Proposed Standard. URL: https://datatracker.ietf.org/doc/html/rfc4122
[RFC6690]
Constrained RESTful Environments (CoRE) Link Format . Z. Shelby. IETF. August 2012. Proposed Standard. URL: https://datatracker.ietf.org/doc/html/rfc6690
[RFC6762]
Multicast DNS . S. Cheshire; M. Krochmal. IETF. February 2013. Proposed Standard. URL: https://datatracker.ietf.org/doc/html/rfc6762
[RFC6763]
DNS-Based Service Discovery . S. Cheshire; M. Krochmal. IETF. February 2013. Proposed Standard. URL: https://datatracker.ietf.org/doc/html/rfc6763
[RFC7230]
Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing . R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
[RFC7231]
Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content . R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html
[RFC7396]
JSON Merge Patch . P. Hoffman; J. Snell. IETF. October 2014. Proposed Standard. URL: https://datatracker.ietf.org/doc/html/rfc7396
[RFC7540]
Hypertext Transfer Protocol Version 2 (HTTP/2) . M. Belshe; R. Peon; M. Thomson, Ed.. IETF. May 2015. Proposed Standard. URL: https://httpwg.org/specs/rfc7540.html
[RFC7807]
Problem Details for HTTP APIs . M. Nottingham; E. Wilde. IETF. March 2016. Proposed Standard. URL: https://datatracker.ietf.org/doc/html/rfc7807
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words . B. Leiba. IETF. May 2017. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc8174
[RFC8288]
Web Linking . M. Nottingham. IETF. October 2017. Proposed Standard. URL: https://httpwg.org/specs/rfc8288.html
[RFC8615]
Well-Known Uniform Resource Identifiers (URIs) . M. Nottingham. IETF. May 2019. Proposed Standard. URL: https://datatracker.ietf.org/doc/html/rfc8615
[SPARQL11-OVERVIEW]
SPARQL 1.1 Overview . The W3C SPARQL Working Group. W3C. 21 March 2013. W3C Recommendation. URL: https://www.w3.org/TR/sparql11-overview/
[wot-architecture]
Web of Things (WoT) Architecture . Matthias Kovatsch; Ryuichi Matsukura; Michael Lagally; Toru Kawaguchi; Kunihiko Toumura; Kazuo Kajimoto. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-architecture/
[wot-discovery]
Web of Things (WoT) Discovery . Andrea Cimmino; Michael McCool; Farshid Tavakolizadeh; Kunihiko Toumura. W3C. 24 November 2020. W3C Working Draft. URL: https://www.w3.org/TR/wot-discovery/
[wot-thing-description]
Web of Things (WoT) Thing Description . Sebastian Käbisch; Takuki Kamiya; Michael McCool; Victor Charpenay; Matthias Kovatsch. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-thing-description/
[wot-usecases]
Web of Things (WoT): Use Cases . Michael Lagally; Michael McCool; Ryuichi Matsukura; Tomoaki Mizushima. W3C. 15 October 2020. Editor's Draft. URL: https://w3c.github.io/wot-usecases/
[xpath-31]
XML Path Language (XPath) 3.1 . Jonathan Robie; Michael Dyck; Josh Spiegel. W3C. 21 March 2017. W3C Recommendation. URL: https://www.w3.org/TR/xpath-31/

C.2 Informative references

[JSONPATH]
JavaScript Object Notation (JSON) Path . Glyn Normington; Edward Surov; Marko Mikulicic; Stefan Gössner. IETF. 7 March 2021. DRAFT. URL: https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base-00
[LDP-Paging]
Linked Data Platform Paging 1.0 . Steve Speicher; John Arwe; Ashok Malhotra. W3C. 30 June 2015. W3C Note. URL: https://www.w3.org/TR/ldp-paging/
[REST-IOT]
RESTful Design for Internet of Things Systems . Ari Keranen; Matthias Kovatsch; Klaus Hartke. IETF. 11 May 2020. URL: https://tools.ietf.org/html/draft-irtf-t2trg-rest-iot-06
[RFC8552]
Scoped Interpretation of DNS Resource Records through "Underscored" Naming of Attribute Leaves . D. Crocker. IETF. March 2019. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc8552
[WOT-SECURITY]
Web of Things (WoT) Security and Privacy Guidelines . Elena Reshetova; Michael McCool. W3C. 6 November 2019. W3C Note. URL: https://www.w3.org/TR/wot-security/