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/.
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.
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
words
MUST
and
SHOULD
in
this
document
is
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).
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.
Support
peer-to-peer
(self-identifying),
local
(network
segment),
and
global
(internet-wide)
discovery.
Support
discovery
via
third-party
services
(e.g.
a
directory
service)
in
order
to
support
sleeping
devices.
Be
compatible
with
the
WoT
Scripting
Discovery
API.
5.2
Search
This
section
is
non-normative.
Support
various
forms
of
query,
including
keyword,
template,
and
semantic
queries.
Support
spatial
and
sub-net
limited
queries.
Be
scalable
to
large
databases
of
TDs.
5.3
Data
Management
This
section
is
non-normative.
Support
both
Dynamic
and
Static
TDs.
Support
explicit
deletion
and
access
control
management
of
TDs.
Automatically
clean
up
TDs
for
devices
that
are
no
longer
accessible.
5.4
Security
This
section
is
non-normative.
Support
best
known
methods
for
confidentiality
and
authentication.
Support
authorization
and
role
management.
5.5
Privacy
This
section
is
non-normative.
Support
authentication
and
authorization
mechanisms
that
do
not
reveal
user
identities.
Support
device
and
information
lifecycle,
trust
management,
access
controls.
Distribute
TDs
and
other
metadata
only
to
authenticated
and
authorized
users.
Don’t
leak
metadata
or
queries
to
unauthorized
entities.
5.6
Alignment
with
Existing
Standards
This
section
is
non-normative.
Align
with
IETF
CoRE
Resource
Directories,
CoRE
Link
Format,
and
DID.
Be
accessible
via
a
variety
of
existing
discovery
mechanisms,
including
DNS-SD,
DNS-SRV,
DHCP,
QR
codes,
and
Bluetooth
beacons.
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
WoT-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
API
of
directory
service.
8.2.2.1
Registration
Sub-API
to
register
a
TD
(or
a
link).
Manage
existing
records.
Basically
CRUD
operations
on
TD
records.
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
Sub-API
to
notify
clients
of
events,
such
as
updates
to
TDs.
8.2.2.4
Search
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
counts
with
three
different
APIs
to
perform
the
search:
the
JSONPath
search,
the
XPath
search,
and
the
semantic
search.
The
Directory
MUST
implement
the
JSONPath
search
or
the
XPath
search,
and
SHOULD
implement
the
semantic
search.
8.2.2.4.1
JSONPath
search
The
API
MUST
receive
as
valid
HTTP
request
using
the
GET
method.
As
parameter,
the
request
MUST
provide
as
valid
JSONPath
expression.
JSONPath
search
MUST
output
an
array,
contaning
json
elements
that
can
be
either
json
values
or
json
documents.
List
of
errors:
400(Bad
Request):
if
the
JSONPath
contains
syntax
or
grammar
errors
500(Internal
Server
Error):
if
the
service
fails
executing
the
JSONPath
8.2.2.4.2
XPath
search
The
API
MUST
receive
as
valid
HTTP
request
using
the
GET
method.
As
parameter,
the
request
MUST
provide
as
valid
expression
written
acording
to
the
standard
XPath
3.1
[].
The
XPath
search
MUST
output
an
array,
contaning
json
elements
that
can
be
either
json
values
or
json
documents.
List
of
errors:
400(Bad
Request):
if
the
XPath
contains
syntax
or
grammar
errors
500(Internal
Server
Error):
if
the
service
fails
executing
the
XPath
8.2.2.4.3
Semantic
search
The
API
MUST
implement
the
SPARQL
1.1.
protocol
for
SELECT,
ASK,
DESCRIBE,
and
CONSTRUCT
queries.
Requests
MUST
use
the
methods
HTTP
GET
or
HTTP
POST
containing
a
valid
query
written
according
to
the
SPARQL
1.1
Query
Language.
The
HTTP
GET
MUST
encode
the
query
under
the
parameter
'query'
as
a
URL.
The
HTTP
POST
MUST
have
the
application/sparql-query
Content-Type
header
and
MUST
have
contain
the
query
as
body.
Alternativelly,
HTTP
POST
MUST
have
the
application/x-www-form-urlencoded
Content-Type
header
and
MUST
encode
the
query
in
the
BODY
as
a
URL
under
the
argument
'query'.
Content-negotiation
for
SELECT
and
ASK
queries
(by
default
is
JSON):
Accept
:
application/sparql-results+xml
or
application/xml
outputs
tue
query
answer
in
XML
Accept
:
application/sparql-results+json
or
application/json
outputs
the
query
answer
in
JSON
Accept
:
text/csv
outputs
the
query
answer
in
CSV
Accept
:
text/tab-separated-values
outputs
the
query
answer
in
TSV
Content-negotiation
for
CONSTRUCT
and
DESCRIBE
queries
(by
default
is
JSON-LD
1.1):
Accept
:
application/rdf+xml
outputs
the
query
answer
in
RDF/XML
Accept
:
application/n-triples
outputs
the
query
answer
in
N-TRIPLES
Accept
:
application/n-quads
or
text/x-nquads
outputs
the
query
answer
in
NQuads
Accept
:
application/x-turtle
or
text/turtle
or
application/turtle
outputs
the
query
answer
in
TURTLE
Accept
:
application/trig
outputs
the
query
answer
in
TriG
Accept
:
application/ld+json
outputs
the
query
answer
in
JSON-LD
Accept
:
application/trix
outputs
the
query
answer
in
Trix
Accept
:
text/n3
outputs
the
query
answer
in
N3
List
of
errors:
400(Bad
Request):
if
the
SPARQL
query
contains
syntax
or
grammar
errors
500(Internal
Server
Error):
if
the
service
fails
executing
the
query
8.2.3
Security
and
Privacy
Minimum
security
and
privacy
requirements
for
confidentiality,
authentication,
access
control,
etc.
9.
Exploration
Mechanisms
To
do.
10.
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
Initial
framework.
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.