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 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/.
Publication as a Working 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.
The Web of Things (WoT) defines an architecture that
supports the integration and use of web technologies with IoT
devices. The WoT Architecture [wot-architecture]
document defines the basic concepts and patterns of usage
supported. However, the WoT Thing Description [wot-thing-description]
is a key specification for WoT Discovery since it is the
purpose of WoT Discovery to make WoT Thing Descriptions
available. Specifically, WoT Discovery has to allow
authenticated and authorized entities (and only those entities)
to find WoT Thing Descriptions satisfying a set of criteria,
such as being near a certain location, or having certain
semantics, or containing certain interactions. Conversely, in
order to support security and privacy objectives, the WoT
Discovery process must not leak information to unauthorized
entities. This includes leaking information that a given entity
is requesting certain information, not just the information
distributed in the Thing Descriptions themselves.
There are already a number of discovery mechanisms defined,
so we have to establish why we are proposing a new one. First,
many existing discovery mechanisms have relatively weak
security and privacy protections. One of our objectives is to
establish a mechanism that not only uses best practices to
protect metadata, but that can be upgraded to support future
best practices as needed. Second, we are using discovery in a
broad sense to include both local and non-local mechanisms.
While a local mechanism might use a broadcast protocol,
non-local mechanisms might go beyond the current network
segment where broadcast is not scalable, and so a different
approach, such as a search service, is needed. Our approach is
to use existing mechanisms as needed to bootstrap into a more
general and secure metadata distribution system. Third, the
metadata we are distributing, the WoT Thing Description, is
highly structured and includes rich data such as data schemas
and semantic annotations. Existing discovery mechanisms based
on a list of simple key-value pairs are not appropriate. At the
same time, use of existing standards for semantic data query,
such as SPARQL [SPARQL11-OVERVIEW], while
potentially suitable for some advanced use cases, might require
too much effort for many anticipated IoT applications.
Therefore in order to address more basic applications, we also
define some simpler query mechanisms.
After defining some basic terminology, we will summarize the
basic use cases and requirements for WoT Discovery. These are a
subset of the more detailed and exhaustive use cases and
requirements presented in the WoT Use Cases [wot-usecases]
and WoT Architecture [wot-architecture]
documents. Then we will describe the basic architecture of the
WoT Discovery process, which uses a two-phase
Introduction/Exploration approach. The basic goal of this
architecture is to be able to use existing discovery standards
to bootstrap access to protected discovery services, but to
distribute detailed metadata only to authorized users, and to
also protect those making queries from eavesdroppers as much as
possible. We then describe details of specific Introduction and
Exploration mechanisms. In particular, we define in detail a
normative API for a WoT Thing Description Directory (WoT TDD)
service that provides a search mechanism for collections of WoT
Thing Descriptions that can be dynamically registered by Things
or entities acting on their behalf. The WoT Discovery mechanism
however also supports self-description by individual Things and
one issue we address is how to distinguish between these two
approaches. Finally, we discuss some security and privacy
considerations, including a set of potential risks and
mitigations.
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 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
mechanism 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.
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.
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 An example sequence of discovery of Thing
using DNS-SD and mDNS
Figure 3 An example sequence of discovery of Thing
Description Directory using DNS-SD and mDNS
5.4 CoRE Link Format and CoRE
Resource Directory
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 DirectoryMUST be
wot.directory.
Editor's note
The resource types wot.thing and
wot.directory are tentative. See also § 8. IANA Considerations.
The DID Document obtained
by resolving the DID of a Thing or Thing
Description DirectoryMUST
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.
Figure 4 The high-level class diagram of the exploration
mechanismsThe 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.
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 honoring 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.
As shown in
Figure 4, the Thing
Description Directory can contain zero or more
TDs. For every TD, the
directory may additionally maintain the registration
information for bookkeeping and search purposes. When
available, consumers may request the registration
information via the respective API. A TD which embeds the
registration information is called an Enriched
TD. The ontology of a TD maintained by the directory is
illustrated in
Figure 5.
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
TDMUST 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.
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 explicitly
or relative to the registration time as a
time-to-live (TTL) value.
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.
Editor's note: Registration Info query
argument
Need to specify and describe the
query argument to toggle enrichment of TD with
registration info.
The following is an example queried TD,
enriched with the registration info per request:
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 Partial
TDs or 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].
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
5 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?
If it only supports syntactic queries, is
JSONSchema validation sufficient? Do we also
use SHACL?
If we support SPARQL, do we need to do more
to make sure the ontologies used are
correct?
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
Editor's note: Notification API Changes
The query and payload specification are
subject to change for simplification and
consistency with other API features (e.g. Anonymous
TD, partial TD format [RFC7396]).
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 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.
6.2.2.4 Search
Editor's note: Search API Overview
Sub-API to search a directory, e.g.
issue a query. There are different forms and levels
of query possible, for example, syntactic
(JSONPath, XPath) vs. semantic (SPARQL), and the
more advanced query types may not be supported by
all directories. So this API will have further
subsections, some of which will be optional. Search
also includes a sub-API for managing listing the
contents (eg returned by a query) including
handling pagination, etc. Note that one special
form of query will be able to return everything.
Results may be subject to the requestor's
authorization.
To discuss further: Federated queries to other
TDDs, Spatial and network-limited queries,
Links
The Directory has three search APIs: syntactic
search with JSONPath [JSONPATH]
or XPath [xpath-31],
and semantic search with SPARQL [sparql11-overview].
The Directory MUST implement the syntactic search
with JSONPath.The Directory SHOULD implement the syntactic search
with XPath.The Directory MAY implement semantic search with
SPARQL.
6.2.2.4.1 Syntactic
search: JSONPath
The API MUST allow searching TDs using an
HTTP GET request.The request
MUST contain a valid
JSONPath [JSONPATH]
as searching parameter.A successful
response MUST have 200
(OK) status, contain application/json
Content-Type header, and in the body a set of
complete TDs or a set of TD fragments. The
syntactic search with JSONPath is specified as
searchJSONPath property in Example 3.
List of errors:
400 (Bad Request): JSONPath expression not
provided or contains syntax errors.
401 (Unauthorized): No authentication.
403 (Forbidden): Insufficient rights to the
resource.
The standardization of JSONPath expressions is
in progress by an independent working group.
6.2.2.4.2 Syntactic
search: XPath
The support for
XPath Search API is recommended. If
implemented, the XPath query API MUST allow searching TDs using an
HTTP GET request.The request MUST contain a valid XPath
[xpath-31]
as search parameter.A successful response
MUST have 200 (OK) status,
contain application/json Content-Type
header, and in the body a set of complete TDs or a
set of TD fragments. The syntactic search
with XPath is specified as searchXPath
property in Example 3.
List of errors:
400 (Bad Request): XPath expression not
provided or contains syntax errors.
401 (Unauthorized): No authentication.
403 (Forbidden): Insufficient rights to the
resource.
501 (Not Implemented): XPath API not
supported.
6.2.2.4.3 Semantic search:
SPARQL
The support for SPARQL
Search API is optional. If implemented, the
SPARQL search API MUST
allow searching TDs using the SPARQL protocol
[sparql11-overview].The SPARQL API
MUST accept queries using
HTTP GET requests.The support for
SPARQL search using HTTP POST method
is OPTIONAL.UPDATE queries are out of the scope
for the API. A successful
response MUST have 200
(OK) status, and depending on the type of query
contain by default as Content-Type header
application/ld+json for
CONSTRUCT and DESCRIBE
queries or application/json for
SELECT or ASK. The
response body MAY contain
TD fragments or a set of TDs depending on the
query. The semantic search with SPARQL is
specified as searchSPARQL property in
Example 3.
List of errors:
400 (Bad Request): SPARQL query not provided
or contains syntax errors.
401 (Unauthorized): No authentication.
403 (Forbidden): Insufficient rights to the
resource.
501 (Not Implemented): SPARQL API not
supported.
A WoT Thing
Description Directory MAY
implement federation in its SPARQL query
API.If
implemented, the SPARQL API MUST implement the SPARQL 1.1
Federated Query standard [sparql11-overview].
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 requestor
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:
The TD or Thing could report actual location
information so no inferencing by network range is
needed;
A directory could support actual search by
location;
Absence of a TD in a directory could reveal negative
location information (e.g. if a TD times out and is removed
from a directory, that means the device has not been
present for a while, which could be used to infer that a
person is NOT in a particular location, e.g. not at
home.
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
retrieve 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 appropriate 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].
Update name of directory service to "Thing Description
Directory" with acronym TDD, to avoid confusion with the acronym
TD used for Thing Descriptions.
Elaboration of complete API for registration of a Thing
Description with a Thing Description Directory, including support
for creation, update, retrieval, deletion, and listing.
Add recommendation that TDs be validated before storage in a directory.
Note: this corresponds to work under way in the TD spec to precisely define
appropriate levels of automatic validation for different contexts, including
directory registration.
Addition of Security and Privacy Considerations regarding Denial of Service and Location Tracking.
Addition of IANA Considerations regarding CoRE Resource Types.
Definition of Enriched TD to support embedded metadata in TDs returned by a TDD.
Updates to description of exploration to avoid unnecessary dependence
on HTTP (in the future, other protocols may be supported).
Use of "resource type" instead of "endpoint type" when describing entry in CoRE RD.
Addition of ontology for TDDs that include the type DirectoryDescription
identifying TDs of directories and
a type LinkDescription to identify a TD that is just a link to another
TD (useful for referring to remote directories in order to support federation).
Add section for self-description exploration mechanism.
This supports the use case where a Thing hosts its own TD and peer-to-peer Thing
communication.
Addition of diagram showing the directory information model.
Removal of reference to Issue 16, citing CRUD interface requirements.
Replaced with CRUDL (CRUD + Listing) interface requirement.
MAY assertion added to explicitly permit implementation of SPARQL federation,
and a requirement that if implemented, it needs to follow the SPARQL 1.1 specification.
Updates to references: more recent versions of CoRE RD, DID Core, Eventsource, JSON-LD,
and JSON Path specifications.
Use of datatracker service (and URLs) to reference IETF RFCs.
Addition of normative references to RFC7396 and RFC7540.
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.
