Copyright © 2017-2020 W3C ® ( MIT , ERCIM , Keio , Beihang ). W3C liability , trademark and permissive document license rules apply.
The W3C Web of Things (WoT) is intended to enable interoperability across IoT platforms and application domains. One key mechanism for accomplishing this goal is the definition and use of metadata describing the interactions an IoT device or service makes available over the network at a suitable level of abstraction. The WoT Thing Description specification satisfies this objective.
However, in order to use a Thing its Thing Description first has to be obtained. The WoT Discovery process described in this document addresses this problem. WoT Discovery needs to support the distribution of WoT Thing Descriptions in a variety of use cases. This includes ad-hoc and engineered systems; during development and at runtime; and on both local and global networks. The process also needs to work with existing discovery mechanisms, be secure, protect private information, and be able to efficiently handle updates to WoT Thing Descriptions and the dynamic and diverse nature of the IoT ecosystem.
The WoT Discovery process is divided into two phases, Introduction, and Exploration. The Introduction phase leverages existing discovery mechanisms but does not directly expose metadata; they are simply used to discover Exploration services, which provide metadata but only after secure authentication and authorization. This document normatively defines two Exploration services, one for WoT Thing self-description with a single WoT Thing Description and a searchable WoT Thing Directory service for collections of Thing Descriptions. A variety of Introduction services are also described and where necessary normative definitions are given to support them.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document was published by the Web of Things Working Group as an Editor's Draft.
GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-wot-wg@w3.org ( archives ).
Publication as an Editor's Draft does not imply endorsement by the W3C Membership.
This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 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 .
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.
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.
This section is non-normative.
The present document uses the terminology defined in the WoT Architecture [ wot-architecture ] document, and also the additional terms defined here. The WoT prefix is used to avoid ambiguity for terms that are (re)defined specifically for Web of Things concepts.
id
attribute).
This section is non-normative.
Figure 1 shows an overview of discovery process.
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.
This chapter describes a mechanism for discovering a Thing or a Directory Service. The following mechanism is provided by the Thing or the Directory Service so that Consumer can discover the Thing Description or a URL that point to the Thing Description.
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
Thing
or
Directory
Service
MAY
use
the
Well-Known
Uniform
Resource
Identifier
[
RFC8615
]
to
advertise
its
presence.
The
Thing
or
Directory
Service
registers
its
own
Thing
Description
into
the
following
path:
/.well-known/wot-thing-description
.
When
the
HTTP
GET
access
is
made
to
the
above
path,
the
HTTP
server
MUST
return
a
Thing
Description
with
the
content-type
set
to
application/td+json
.
The
service
name
in
Well-Known
URI
(
wot-thing-description
)
is
tentative.
"Well-Known
URIs"
registry
and
contents
of
registration
request
is
described
in
Section
3.1
of
[
RFC8615
].
A Thing or Directory Service MAY use the DNS-Based Service Discovery (DNS-SD)[ RFC6763 ]. This can be also be used to discover them on the same link by combining Multicast DNS (mDNS)[ RFC6762 ].
In
DNS-SD,
format
of
the
Service
Instance
Name
is
Instance.Service.Domain
.
The
Service
part
is
a
pair
of
labels
following
the
conventions
of
[
RFC2782
].
The
first
label
has
an
underscore
followed
by
the
Service
Name,
and
the
second
label
describes
the
protocol.
The
Service
Name
to
indicate
the
Thing
or
Directory
Service
MUST
be
_wot
.
And
the
Service
Name
to
indicate
the
Directory
Service
MUST
be
_directory._sub._wot
.
The
Service
Names
_wot
and
_directory._sub._wot
are
tentative.
The
following
Service
Names
are
used
in
the
existing
implementations:
_wot
,
_device._sub._wot
,
_directory._sub._wot
,
_webthing
.
To
use
a
Service
Name,
registration
to
"Underscored
and
Globally
Scoped
DNS
Node
Names"
Registry
[
RFC8552
]
is
required.
In
addition,
the
following
information
MUST
be
included
in
the
TXT
record
that
is
pointed
to
by
the
Service
Instance
Name:
td
type
Thing
or
Directory
.
If
omitted,
the
type
is
assumed
to
be
Thing
.
The
following
key/value
pairs
are
used
in
the
existing
implementations:
retrieve
:
Absolute
path
name
of
the
API
to
get
an
array
of
Thing
Description
IDs
from
the
Directory
Service.
register
:
Absolute
path
name
of
the
API
to
register
a
Thing
Description
with
the
Directory
Service.
path
:
The
URI
of
the
thing
description
on
the
Web
Thing's
web
server
td
:
Prefix
of
Directory
Service
API
tls
:
Value
of
1
if
the
Web
Thing
supports
connections
via
HTTPS.
Figure 2 and Figure 3 shows example sequences of discovery of Thing and Directory Service using DNS-SD and mDNS.
A Thing or Directory Service MAY advertise its presence using the Constrained RESTful Environment (CoRE) Link Format [ RFC6690 ]. And, a Thing or Directory Service MAY use the CoRE Resource Directory [ CoRE-RD ] to register a link to the Thing Description.
The
endpoint
type(
et
)
of
the
Link
that
targets
the
Thing
Description
of
the
Thing
MUST
be
wot.thing
.
The
endpoint
type
of
the
Link
that
targets
the
Thing
Description
of
the
Directory
Service
MUST
be
wot.directory
.
The
endpoint
types
wot.thing
and
wot.directory
are
tentative.
A Thing or Directory Service MAY advertise its presence using the Decentralized Identifier (DID) [ DID-CORE ].
The DID Document obtained by resolving the DID of a Thing or Directory Service MUST contains a Service Endpoint which point to Thing Description of the Thing or Directory Service.
To do: Description of supported explorations, and requirements for new exploration mechanisms.
To do: Describe mechanisms for devices to self-describe, hosting their own TDs.
To do: Describe mechanisms for TDs to be hosted in a searchable directory service.
A
Directory
can
be
distinguished
from
a
Thing
by
the
use
of
an
@type
including
the
semantic
term
Directory
.
To Do: Formal definition of information contained in a directory and its organization.
The HTTP API responses must use appropriate status codes described in this section for success and error responses. The HTTP API MUST use the Problem Details [ RFC7807 ] format to carry error details in HTTP client error (4xx) and server error (5xx) responses. This enables both machines and humans to know the high-level error class and fine-grained details.
The
Problem
Details
error
type
field
is
a
URI
reference
which
could
used
to
map
the
occurred
error
to
WoT-specific
error
class.
There
are
few
open
issues
raising
the
lack
of
WoT-specific
error
types:
wot-discovery#44
,
wot-thing-description#303
,
wot-scripting-api#200
.
For
now,
type
can
be
omitted
which
defaults
to
"about:blank",
and
title
should
be
set
to
HTTP
status
text.
Below is a generic Thing Description for the Directory HTTP API with OAuth2 security. The Thing Description alone should not be considered as the full specification to implement or interact with a directory. Additional details for every interaction are described in human-readable form in the subsequent sections.
Need to confirm if equivalent OpenAPI spec can be easily created out of the TD in Example 2 . If yes, a sentence may be added indicating this possibility.
The Registration API is a RESTful HTTP API in accordance with the recommendations defined in [ RFC7231 ] and [ REST-IOT ]. The default serialization format for all request and response bodies MUST be JSON, with JSON-LD 1.1 [ JSON-LD11 ] syntax to support extensions and semantic processing. Directories MAY accept additional representations based on request's indicated Content-Type or Content-Encoding, and provide additional representations through server-driven content negotiation.
The Registration API MUST provide create, retrieve, update, delete (CRUD) interfaces.
The
API
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
must
be
validated
syntactically
using
the
Thing
Description
JSON
Schema
[
WoT-Thing-Description
].
in
accordance
with
§
6.2.2.1.1
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
2
and
elaborated
below:
PUT
request
at
a
target
location
(HTTP
path)
containing
the
unique
TD
id
.
Upon
successful
processing,
the
server
MUST
respond
with
201
(Created)
status.
Note: If the target location corresponds to an existing TD, the request shall instead proceed as an Update operation and respond the appropriate status code (see Update section).
POST
request.
Upon
successful
processing,
the
server
MUST
respond
with
201
(Created)
status
and
a
Location
header
containing
a
system-generated
identifier
for
the
TD.
The
identifier
SHOULD
be
a
Version
4
UUID
URN
[
RFC4122
].
Error responses:
The
server
should
employ
a
mechanism
to
eliminate
duplication
of
TDs
submitted
with
a
POST
request.
The
spec
need
to
have
recommendations
on
how
to
perform
this.
A
TD
MUST
be
retrieved
from
the
directory
using
an
HTTP
GET
request,
including
the
identifier
of
the
TD
as
part
of
the
path.
A
successful
response
MUST
have
200
(OK)
status,
contain
application/td+json
Content-Type
header,
and
the
requested
TD
in
body.
The
retrieve
operation
is
specified
as
retrieveTD
property
in
Example
2
.
Error responses:
id
not
found.
The API MUST allow modifications to an existing TD as full replacement or partial updates. The update operations are described below:
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
updateTD
property
in
Example
2
.
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.
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
updatePartialTD
property
in
Example
2
.
Error responses:
id
not
found
(for
PATCH
only).
A
TD
MUST
be
removed
from
the
directory
when
an
HTTP
DELETE
request
is
submitted
to
the
location
corresponding
to
the
existing
TD.
A
successful
response
MUST
have
204
(No
Content)
status.
The
retrieve
operation
is
specified
as
deleteTD
property
in
Example
2
.
Error responses:
id
not
found.
It would be nice to include an example validation result in the uniform error format (i.e. RFC7807 Problem Details).
How much validation does a directory need to do?
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).
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
2
.
created_td
,
updated_td
,
deleted_td
keywords
respectively.
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.
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
.
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.
td_id
field.
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.
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.
include_changes
query
parameter,
it
MUST
reject
the
request
with
501
(Not
Implemented)
status.
Some early SSE implementations (including HTML5 EventSource) do not allow setting custom headers in the initial HTTP request. Authorization header is required in few OAuth2 flows and passing it as a query parameter is not advised . There are polyfills for browsers and modern libraries which allow setting Authorization header.
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
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
2
.
List of errors:
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
2
.
List of errors:
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
2
.
List of errors:
Minimum security and privacy requirements for confidentiality, authentication, access control, etc.
This section is non-normative.
Security and privacy are cross-cutting issues that need to be considered in all WoT building blocks and WoT implementations. This chapter summarizes some general issues and guidelines to help preserve the security and privacy of concrete WoT discovery implementations. For a more detailed and complete analysis of security and privacy issues, see the WoT Security and Privacy Guidelines specification [ WOT-SECURITY ].
To do, some discussion of general security and privacy concerns and mitigations. Note that the architecture above is designed to address many such points, for example the two-phase approach and "authorization before metadata release" principles, so this would be a summary and a recap.
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.