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.
This WoT Discovery specification...
To do.
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 .
To Do.
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 word MUST in this document is 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.
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.
This section is non-normative.
Examples of why we need discovery.
This section is non-normative.
The WoT discovery process should have the following capabilities:
This section is non-normative.
This section is non-normative.
This section is non-normative.
This section is non-normative.
This section is non-normative.
This section is non-normative.
This section is non-normative.
Two-Phase approach.
Description of supported introductions, and requirements for new introduction mechanisms.
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
WoT-Directory
.
To Do.
To Do.
To Do.
Description of supported explorations, and requirements for new exploration mechanisms.
Mechanism for devices to self-describe, hosting their own TDs.
Mechanism for TDs to be hosted in a searchable directory service.
Description of conceptual data organization in a directory.
API of directory service.
Sub-API to register a TD (or a link). Manage existing records. Basically CRUD operations on TD records.
The Registration API uses the HTTP [ RFC7231 ] protocol and provides a RESTful design inline with [ REST-IOT ]. The serialization format for all request and response bodies is JSON, with JSON-LD 1.1 [ JSON-LD11 ] syntax to support extensions and semantic processing.
The
API
allows
registration
of
a
TD
object
passed
as
request
body.
A
TD
which
is
identified
with
an
id
attribute
(known
TD)
is
handled
differently
with
one
that
has
no
id
(anonymous
TD).
A
known
TD
is
submitted
to
the
directory
using
an
HTTP
PUT
request
at
a
unique
target
location
specified
in
the
path.
Upon
successful
processing,
the
server
shall
respond
with
a
201
(Created)
status.
Note:
If
the
target
location
corresponds
to
an
existing
TD,
the
request
shall
instead
proceed
as
an
Update
operation.
An
anonymous
TD
is
submitted
to
the
directory
using
an
HTTP
POST
request.
Upon
successful
processing,
the
server
shall
respond
with
a
201
(Created)
status
and
a
Location
header
containing
an
identifier
for
the
TD.
A
TD
is
retrieved
from
the
directory
using
an
HTTP
GET
request.
The
request
should
include
the
identifier
of
the
TD
as
part
of
the
path.
A
successful
response
shall
contain
the
TD
in
body
and
have
a
200
(OK)
status.
A
modified
TD
replaces
an
existing
when
submitted
using
an
HTTP
PUT
request
to
the
location
corresponding
to
the
existing
TD.
Upon
success,
the
server
responds
with
a
204
(No
Content)
status.
A
TD
is
partially
modified
when
the
modified
parts
are
submitted
using
an
HTTP
PATCH
request.
The
modified
parts
must
conform
to
the
original
TD
structure
and
may
include
other
existing
parts
of
the
TD.
Upon
success,
the
server
responds
with
a
204
(No
Content)
status.
A
TD
is
removed
from
the
directory
using
an
HTTP
DELETE
request.
The
request
should
include
the
identifier
of
the
TD
as
part
of
the
path.
A
successful
response
shall
have
a
204
(No
Content)
status.
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).
Sub-API to notify clients of events, such as updates to TDs.
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:
Minimum security and privacy requirements for confidentiality, authentication, access control, etc.
To do.
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 ].
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.