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

Abstract

The W3C Web of Things (WoT) is intended to enable interoperability across IoT platforms and application domains.

This WoT Discovery specification...

To do.

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

To do.

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.

1. Introduction

To Do.

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

This specification uses the following terms as defined here. The WoT prefix is used to avoid ambiguity for terms that are (re)defined specifically for Web of Things concepts.

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).
Anonymous TD
A Thing Description without an identifier (id attribute).

4. Use Cases

This section is non-normative.

Examples of why we need discovery.

5. Requirements

This section is non-normative.

The WoT discovery process should have the following capabilities:

5.1 System

This section is non-normative.

5.3 Data Management

This section is non-normative.

5.4 Security

This section is non-normative.

5.5 Privacy

This section is non-normative.

5.6 Alignment with Existing Standards

This section is non-normative.

6. Architecture

This section is non-normative.

Two-Phase approach.

7. Introduction Mechanisms

Description of supported introductions, and requirements for new introduction mechanisms.

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

7.2 DNS-SD

To Do.

7.3 CoRE Resource Directory

To Do.

7.4 DID Documents

To Do.

8. Exploration Mechanisms

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

8.1 Self-description

Mechanism for devices to self-describe, hosting their own TDs.

8.2 Directory

Mechanism for TDs to be hosted in a searchable directory service.

8.2.1 Information Model

Description of conceptual data organization in a directory.

8.2.2 Directory Service API

The Directory APIs must use secure protocols guaranteeing System User Data authenticity and confidentiality (see [WOT-SECURITY-GUIDELINES]). All HTTP APIs MUST be exposed over HTTPS (HTTP Over TLS).
8.2.2.1 Registration
Editor's note: Schema for error objects

[RFC7807] may be a good option.
Should error objects be JSON-LD?

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:

Create a TD:

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:

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

Editor's note: Deduplication

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.

Retrieve a TD:

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:

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

Update a TD:

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:

  • A modified TD MUST replace an existing one when submitted using an HTTP 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.

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

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

Delete a TD:

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:

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

8.2.2.2 Management

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

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

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

8.2.3 Security and Privacy

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

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

A. Recent Specification Changes

Changes from First Draft

B. Acknowledgments

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.

C. References

C.1 Normative references

[EVENTSOURCE]
Server-Sent Events. Ian Hickson. W3C. 3 February 2015. W3C Recommendation. URL: https://www.w3.org/TR/eventsource/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC4122]
A Universally Unique IDentifier (UUID) URN Namespace. P. Leach; M. Mealling; R. Salz. IETF. July 2005. Proposed Standard. URL: https://tools.ietf.org/html/rfc4122
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174
[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/

C.2 Informative references

[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/
[REST-IOT]
RESTful Design for Internet of Things System. A. Keranen; M. Kovatsch; K. Hartke. IETF. 14 September 2017. URL: https://tools.ietf.org/id/draft-keranen-t2trg-rest-iot-05.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
[RFC7807]
Problem Details for HTTP APIs. M. Nottingham; E. Wilde. IETF. March 2016. Proposed Standard. URL: https://tools.ietf.org/html/rfc7807
[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/
[WOT-SECURITY-GUIDELINES]
Web of Things (WoT) Security and Privacy Guidelines. ; Michael McCool; Elena Reshetova. W3C. March 2019. URL: https://w3c.github.io/wot-security/