forked from w3c/wot-discovery
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
3152 lines (3037 loc) · 188 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en-US">
<head>
<link rel="stylesheet" href="testing/atrisk.css">
<meta charset="utf-8" />
<title>Web of Things (WoT) Discovery</title>
<script
src="https://www.w3.org/Tools/respec/respec-w3c"
class="remove"
defer
></script>
<script class="remove">
var respecConfig = {
lint: {
"check-punctuation": true,
"local-refs-exist": true,
"no-http-props": true,
"no-headingless-sections": true,
"no-unused-dfns": false
},
doJsonLd : true,
specStatus : "ED",
// crEnd: "2022-08-30",
implementationReportURI: "https://w3c.github.io/wot-discovery/testing/report.html",
shortName : "wot-discovery",
copyrightStart : 2017,
group: "wg/wot",
wgPublicList : "public-wot-wg",
github: {
repoURL: "https://github.com/w3c/wot-discovery",
branch: "main"
},
previousPublishDate: "2022-08-10",
previousMaturity: "FPWD",
editors : [ {
name : "Andrea Cimmino",
w3cid : "115672",
company : "Universidad Politécnica de Madrid",
companyURL : "https://www.upm.es/"
}, {
name : "Michael McCool",
w3cid : "93137",
company : "Intel Corp.",
companyURL : "https://www.intel.com/"
}, {
name : "Farshid Tavakolizadeh",
w3cid : "122520",
company : "Invited Expert"
}, {
name : "Kunihiko Toumura",
w3cid : "83488",
company : "Hitachi, Ltd.",
companyURL : "https://www.hitachi.com/"
} ],
formerEditors: [ {
name : "Farshid Tavakolizadeh",
w3cid : "122520",
company : "Fraunhofer-Gesellschaft",
companyURL : "https://www.fraunhofer.de/",
retiredDate: "2021-09-30"
} ],
otherLinks : [
{
key : "Contributors",
data : [ {
value : "In the GitHub repository",
href : "https://github.com/w3c/wot-discovery/graphs/contributors"
} ]
}],
localBiblio : {
"GDPR-Defs" : {
title: "General Data Protection Regulation (GDPR) Article 4 - Definitions"
, href: "https://gdpr-info.eu/art-4-gdpr/"
, publisher: "European Union (EU) and the European Economic Area (EEA)"
},
"OWASP-Top-10" : {
title: "OWASP Top Ten"
, href: "https://owasp.org/www-project-top-ten/"
, publisher: "OWASP"
},
"REST-IOT" : {
title: "RESTful Design for Internet of Things Systems"
, href: "https://tools.ietf.org/html/draft-irtf-t2trg-rest-iot-06"
, authors: [
"Ari Keranen"
, "Matthias Kovatsch"
, "Klaus Hartke"
]
, publisher: "IETF"
, date: "11 May 2020"
},
"JSONPATH": {
title: "JSONPath: Query expressions for JSON"
, href: "https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base"
, authors: [
"Stefan Gössner"
, "Glyn Normington"
, "Carsten Bormann"
]
, publisher: "IETF"
, status: "DRAFT",
},
"wot-usecases" : {
title: "Web of Things (WoT): Use Cases"
, href: "https://w3c.github.io/wot-usecases/"
, authors: [
"Michael Lagally"
, "Michael McCool"
, "Ryuichi Matsukura"
, "Tomoaki Mizushima"
]
, publisher: "W3C"
, date: "15 October 2020"
, status: "Editor's Draft",
}
}
};
</script>
<style type="text/css">
a[href].internalDFN {
color: inherit;
border-bottom: 1px solid #99c;
text-decoration: none;
}
img.wot-diagram {
max-width: 90%;
height: auto;
}
.rfc2119-assertion {
background-color: rgb(230,230,230)
}
</style>
</head>
<body>
<section id="abstract">
<p>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.
</p>
<p>However, in order to use a Thing its Thing Description
first has to be obtained. The <em>WoT Discovery</em> 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.
</p>
<p>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: for distributing a single WoT Thing Description from a regular
web service, including as a special case self-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.
</p>
</section>
<!-- The following will be filled in by ReSpec -->
<section id="sotd"></section>
<section id="introduction">
<h1>Introduction</h1>
<p>The Web of Things (WoT) defines an architecture that supports the integration
and use of web technologies with IoT devices.
The WoT Architecture [[wot-architecture11]] document defines the basic
concepts and patterns of usage supported.
However, the WoT Thing Description [[wot-thing-description11]] 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.
</p>
<p>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.
</p>
<p>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-architecture11]] 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
distribution of single TDs from regular web services, with a special case of this
being self-description.
Finally, we discuss some security and privacy considerations, including a set of
potential risks and mitigations.
</p>
</section>
<!-- The following will be filled in by ReSpec -->
<section id="conformance"></section>
<section id="terminology" class="informative">
<h1>Terminology</h1>
<p>
The fundamental WoT terminology such as
<dfn>Thing</dfn>,
<dfn>Thing Description</dfn> (<dfn>TD</dfn>),
<dfn>Thing Model</dfn> (<dfn>TM</dfn>),
<dfn>Property</dfn>,
<dfn>Action</dfn>,
<dfn>Event</dfn>,
<dfn data-lt="WoT Anonymous Thing Description">Anonymous TD</dfn>,
<dfn data-lt="WoT Discoverer">Discoverer</dfn>,
<dfn data-lt="WoT Discovery">Discovery</dfn>,
<dfn data-lt="WoT Exploration">Exploration</dfn>,
<dfn data-lt="WoT Introduction">Introduction</dfn>,
<dfn data-lt="WoT Thing Description Server">Thing Description Server</dfn>
(<dfn data-lt="WoT TD Server">TD Server</dfn>),
<dfn data-lt="WoT Thing Description Directory">Thing Description Directory</dfn>
(<dfn data-lt="WoT TDD">TDD</dfn>),
<dfn data-lt="WoT Partial Thing Description">Partial TD</dfn>,
<dfn data-lt="WoT Enriched Thing Description">Enriched TD</dfn>
are defined in <a href="https://www.w3.org/TR/wot-architecture11/#terminology">Section 3</a>
of the WoT Architecture 1.1 specification [[?wot-architecture11]].
</p>
</section>
<section id="architecture" class="informative">
<h1>Architecture</h1>
<p>
<a href="#discovery-overview"></a> shows an overview of the WoT Discovery process.
Discovery uses a two-phase architecture to resolve the competing requirements to be
both open and to restrict access to metadata to authorized entities.
In the first phase, one or more of a set of relatively open
"Introduction" mechanisms may be used to generate a set of candidate URLs.
These URLs do not themselves contain metadata,
but are used in the second stage to reference "Exploration"
services that can actually provide metadata, after authentication,
in the form of <a>Thing Descriptions</a>.
</p>
<figure id="discovery-overview">
<img src="images/overview.png"
srcset="images/overview.svg"
class="wot-diagram"
alt="Discovery process overview" />
<figcaption>Discovery architecture overview.
A set of open Introduction mechanisms provides a set of URLs, which
point at Exploration services that only provide metadata (TDs) after suitable
authentication. Thing Links and Thing Description Directories provide
additional flexibility but retrieving further results from these is
at the discretion of the application.
</figcaption>
</figure>
<p>
The intention is that Introduction mechanisms are relatively open "first contact"
mechanisms to provide a starting point for the rest of the Discovery process.
In this document we specify details on several Introduction
mechanisms, suitable for different use cases, including both local and non-local
scenarios, but Introductions can in fact be provided by any mechanism that can return a URL.
Introductions, however, do not include any security or privacy controls and
so should not provide metadata directly.
Instead, the URLs provided by Introduction mechanisms reference
"Exploration" services. Exploration services actually do provide metadata,
but only after suitable authentication and access controls have been applied.
</p>
<p>
The Discovery process can produce a <em>set</em> of URLs as output from
its Introduction phase, even if only one Introduction mechanism is used
(some Introduction mechanisms can themselves return multiple URLs).
The final output after the Exploration phase
can also be a <em>set</em> of Thing Descriptions.
</p>
<p>
Each URL provided by the Introduction phase always points at an
Exploration service endpoint that will return a single Thing Description.
In the simplest case this URL references an ordinary resource
provided by a web server which provides the Thing Description of a Thing
describing an IoT endpoint device.
As a special case of this, for self-describing Things an Introduction URL might
point directly at an endpoint provided by a
Thing serving its own Thing Description.
</p>
<p>
In general Thing Descriptions might be provided in various ways and
in particular may not be self-describing.
For example,
</p>
<ul>
<li>brownfield devices not designed with the WoT
specification in mind will not be capable of serving their
own Thing Descriptions;
</li>
<li>battery-powered devices may not be online
most of the time; and
</li>
<li>some devices may not be powerful enough to manage and
serve TDs directly.
</li>
</ul>
<p>
The Thing Description for such Things should be provided
by separate services.
</p>
<p>
This document specifies two special cases that allow for more flexibility:
</p>
<ul>
<li>A Thing Description referenced by an Introduction URL
may describe a <a href="#exploration-td-type-thingdirectory">Thing Description Directory</a> service.
A Thing Description Directory service (which is still a Thing)
maintains a (possibly dynamic) database of Thing Descriptions.
Thing Description Directories that maintain large numbers of
Thing Descriptions may also support queries that can be used to
selectively retrieve Thing Descriptions.
</li>
<li>
The second special case is a
<a href="#exploration-td-type-thinglink">Thing Link</a>.
A Thing Link is also a Thing Description,
but rather than describing a Thing directly, it holds a link to
a Thing Description hosted elsewhere.
A Thing Description Directory can also store Thing Links
which can redirect to other Thing Description Directories,
allowing for a linked directory structure.
</li>
</ul>
<p>
It is <em>not</em> mandatory for the Discovery process to retrieve
the contents of Thing Description Directories and return them as
part of the results,
because in general this might result in a huge set of results.
Instead the application
should scan the results for Thing Description Directory TDs and
decide whether to retrieve TDs from them, possibly selectively.
Likewise, it is not required to follow Thing Links automatically;
instead the application may choose to follow them selectively.
</p>
</section>
<section id="discoverer-process" class="normative">
<h1>Discoverer Process</h1>
<p>In this section we will describe the WoT Discovery process from the point of view of a client,
and what it means to say that a client supports WoT Discovery.
We will use the term <a>Discoverer</a> for an entity that is a client of the WoT Discovery
process.
A Discoverer may or may not be a full Consumer.
A Discoverer does however need to read and extract information from special TDs for Directories
and Thing Links and use specific affordances and links provided in them.
Conversely, a Consumer may not support Discovery, although it is recommended
[[wot-architecture11]].
</p>
<p>
The WoT Discovery process is designed so that nearly any client that can fetch a single TD
given a single URI can be said to support WoT Discovery.
Of course, Discoverers may support more powerful Discovery mechanisms, but some of these
have additional requirements.
<!--
For example, using WoT Thing Description Directories (TDDs) requires the use of HTTP, and so
are only available to Discoverers that support this protocol.
However, use of HTTP (and Directories)
is not in fact a requirement of the WoT Discovery process.
-->
Some Introduction mechanisms can return multiple URLs,
each of which can in turn be used to fetch at least one TD.
So even without a TDD, it is possible to discover multiple TDs.
<!--
For example, a Discoverer supporting only CoAP may want to use
CoRE-RD as one of its Introduction mechanisms, and a single CoRE-RD instance can provide
multiple links to individual TDs.
Such a Discoverer could also support multiple Introduction mechanisms whose results are
merged, such as DNS-SD and CoRE-RD.
-->
</p>
<p>
The following assertions describe the specific responsibilities of a Discoverer:
</p>
<ul>
<li><span class="rfc2119-assertion" id="discoverer-must-support-intros">
A Discoverer MUST support at least one Introduction mechanism.</span>
The simplest Introduction mechanism, Direct, simply provides a single URL of a target TD.
This assertion results in different minimal requirements depending on
which Introduction mechanism is selected out of the several available.
For example, when Direct is used as the sole Introduction mechanism,
at a minimum a Discoverer must be able to accept a single URL pointing at a TD.
Note, however, that this TD could still be describing a Directory.
Another option would be for a Discoverer to implement, as its sole
Introduction mechanism, an "automatic" Introduction mechanism such as
DNS-SD, possibly in combination with mDNS.
In this case the application
code running in the Discoverer
would not have to supply any additional information to invoke Discovery.
</li>
<li><span class="rfc2119-assertion" id="discoverer-must-support-fetching">
A Discoverer MUST support fetching a TD from at least one URL provided as part of the Introduction process.</span>
In other words, not only must a Discoverer accept URLs pointing at TDs, it must be
able to fetch that TD, for example by using a GET for an HTTP URL.
It is permissible to split the implementation of a Discoverer into two components, one that
fetches/reads a TD and sets up a configuration during installation to be used by a
run-time component that cannot itself read TDs.
In this case, however, the latter component is not by itself a Discoverer.
</li>
<li><span class="rfc2119-assertion" id="discoverer-may-multiple-intro">
A Discoverer MAY support multiple invocations of the same Introduction mechanism.</span>
If multiple invocations of a single Introduction mechanism is supported,
or if multiple Introduction mechanisms are used, then the Discoverer needs to
manage a set of Introduction results.
Some Introduction mechanisms themselves return a set of results, e.g. CoRE-RD, DID, or DNS-SD.
Some mechanisms, such as scanning Bluetooth beacons, may intrinsically result in separate multiple "invocations".
However, this Discoverer requirement is optional to support an important special case:
it is permissible to have a simple
Discoverer that only supports a single invocation of a Direct Introduction,
directly specifying a single TD via a URL.
</li>
<li><span class="rfc2119-assertion" id="discoverer-merge-intros">
A Discoverer MUST be able to merge URLs resulting from
multiple Introduction mechanisms, multiple results from a single Introduction mechanism,
and multiple Introduction invocations into a single set.</span>
Note that even if only one Introduction mechanism is supported multiple results might be
produced.
This assertion states that the overall output of the Introduction phase is
a single set of URLs.
The word "set" is used here in the mathematical sense: the results are unordered and unique.
Uniqueness means that if multiple Introductions have the same result, they are merged into
a single result.
If the Discoverer only supports one Introduction mechanism and that mechanism
can only produce one URL, then the "merge" is trivial.
</li>
<li><span class="rfc2119-assertion" id="discoverer-td-identify">
A Discoverer MUST be able to identify whether a TD fetched from an
Introduction URL has <a href="#exploration-td-type-thingdirectory">Thing Directory</a>
or <a href="#exploration-td-type-thingdirectory">Thing Link</a> type.</span>
This implies that the Discoverer needs to be able
to check the <code>@type</code> field and make this distinction.
A Discoverer can decide whether or not to follow links or fetch TDD contents.
There are some use cases where a Consumer may not expand certain URLs, for example links pointing
at external resources, or when a TDD contains many TDs and fetching them all
would exceed the Consumer's memory processing capabilities.
</li>
<li><span class="rfc2119-assertion" id="discoverer-fetch-tdd">
A Discoverer MAY fetch additional TDs from any Exploration mechanism
described in its initial set of TDs (including, in particular, Thing Description Directories)
and add them into the set of TD results.</span>
This only adds the results of fetching TDs from an Exploration mechanism to the set of
results. These new results do not delete the original TD describing the Exploration mechanism.
A Discoverer implementation can decide whether or not to fetch TDD contents.
Implementers should consider the fact that TDDs may be large and fetching the contents of an entire TDD
might be prohibitively expensive.
</li>
<li><span class="rfc2119-assertion" id="discoverer-fetch-links">
A Discoverer MAY fetch source TDs from the targets of the links in a <a href="#exploration-td-type-thingdirectory">Thing Link</a>
described in its initial set of TDs and add them into the set of TD results.</span>
This only adds the results of fetching TDs from a Thing Link to the set of
results. These new results do not delete the original TD describing the Thing Link.
A Discoverer implementation can decide whether or not to fetch the targets of Thing Links.
</li>
<li><span class="rfc2119-assertion" id="discoverer-fetch-iteration">
A Discoverer MAY fetch additional TDs iteratively from any <a href="#exploration-td-type-thingdirectory">Thing Link</a> or
Exploration mechanism described in its set of TDs and add them into the set of TD results.</span>
This only adds the results of fetching TDs from an Exploration mechanism to the set of
results. These new results do not delete the original TD describing the Exploration mechanism.
</li>
<li><span class="rfc2119-assertion" id="discoverer-termination">
A Discoverer MAY terminate fetching additional TDs at any point or for
any reason.</span>
</li>
<li><span class="rfc2119-assertion" id="discoverer-any-order">
A Discoverer MAY fetch additional TDs by following links or fetching
additional TDs from Exploration mechanisms (e.g. TDDs) in any order.</span>
The Discoverer can fetch additional TDs in any order from any Exploration mechanism and is not
required to use all of them.
</li>
<li><span class="rfc2119-assertion" id="discoverer-track">
A Discoverer MUST track which TDs describing links or Exploration mechanisms
have already been fetched and avoid fetching duplicate results.</span>
This is to avoid infinite loops. Note that Thing Description Directories can easily refer to each other,
for example, so fetching the TDs from a TDD, then fetching all those TDs will give another copy of the
original TDD's TD. This second copy should NOT trigger further fetches.
Note that tracking cannot depend only on the value of "id" fields in TDs since this
field is optional.
</li>
</ul>
<p>
The above process supports a way to let Directories reference other Directories without duplicating their TDs:
a Directory wanting to reference other Directories should include a <a href="#exploration-td-type-thingdirectory">Thing Link</a> with a "describedby" relation to the
TD of the other Directory service. Then the above process would expand the Thing Link to obtain the actual TD of the Directory,
and then (optionally) use the appropriate Directory affordance to access the contents of the linked Directory.
Note that such a Thing Link points at the TD of the Directory, not at the Directory itself. These
may or may not be hosted in the same location.
</p><p>
Recursively fetching the contents of such linked directories, especially without a specific
query or filter, could easily result in downloading a large amount of data. Such recursive expansion should be limited to use
cases that require it, such as inventory, auditing, or indexing.
</p><p>
URLs for Directory services can also be
used with the federation capabilities of SPARQL queries, noted below, which in most cases will be a more efficient way
to collect specific information from a set of distributed directory services.
However, SPARQL requires the URL of a SPARQL endpoint for such federation, which can be found in the TDs
of Directories supporting SPARQL queries. This is not the same as the URL pointing at the TD of a Directory.
</p>
</p>
</section>
<section id="introduction-mech" class="normative">
<h1>Introduction Mechanisms</h1>
<p>This chapter describes mechanisms for initial contact with
Things or <a>Thing Description Directories</a>.
Any of the following mechanisms may
be provided by the Thing or the <a>Thing Description Directory</a> to Consumers.
The result of an introduction mechanism is always a URL (address) of an exploration service
which can be used to obtain detailed metadata (TDs) after suitable authentication.
It is also possible for multiple introduction mechanisms to be used and the results merged.
No particular introduction mechanism is mandatory, as long as the URL of at least one
exploration service is somehow obtained.
</p>
<section id="introduction-direct" class="normative">
<h2>Direct</h2>
<p><span class="rfc2119-assertion" id="introduction-direct-url">To obtain an URL of an exploration service, any mechanism that results in a single URL MAY be used.</span>
This includes Bluetooth beacons, QR codes, and written URLs to be
typed by a user.
<span class="rfc2119-assertion" id="introduction-direct-thing-description">
A request on all such URLs MUST result in a TD as prescribed in
[[[#exploration-mech]]].</span>
For self-describing Things, this can be the TD of the Thing itself.
<span class="rfc2119-assertion" id="introduction-direct-directory-description">
If the URL references a <a>Thing Description Directory</a>, this MUST be the Thing Description of the
<a>Thing Description Directory</a>.</span>
</p>
</section>
<section id="introduction-well-known" class="normative">
<h2>Well-Known URIs</h2>
<p>
<span class="rfc2119-assertion" id="introduction-well-known-uri">A Thing or <a>Thing Description Directory</a> MAY use the Well-Known Uniform Resource Identifier [[RFC8615]]
to advertise its presence.</span>
<span class="rfc2119-assertion" id="introduction-well-known-path">If a Thing or <a>Thing Description Directory</a> use the Well-Known Uniform Resource Identifier [[RFC8615]] to advertise its presence, it MUST register its own Thing Description
into the following path:
<code>/.well-known/wot</code>.</span>
<p>
<span class="rfc2119-assertion" id="introduction-well-known-thing-description">
When a request is made at the above Well-Known URI, the server MUST return
a Thing Description as prescribed in [[[#exploration-mech]]].</span>
</p>
</section>
<section id="introduction-dns-sd-sec" class="normative">
<h2>DNS-Based Service Discovery</h2>
<p><span class="rfc2119-assertion" id="introduction-dns-sd">A Thing or <a>Thing Description Directory</a> MAY use DNS-Based Service Discovery (DNS-SD)[[RFC6763]].</span>
This can be also be used on the same local network in combination with Multicast DNS (mDNS)[[RFC6762]].
</p>
<p>
The following table lists the service names and protocols for advertising their presense.
<table class="def">
<thead>
<tr>
<th>Service name</th>
<th>Thing or TDD</th>
<th>Protocol</th>
</tr>
</thead>
<tbody>
<tr class="rfc2119-table-assertion" id="introduction-dns-sd-service-name">
<td><code>_wot._tcp</code></td>
<td>Thing</td>
<td>HTTP over TCP, HTTP over TLS/TCP, CoAP over TCP, or CoAP over TLS/TCP</td>
</tr>
<tr class="rfc2119-table-assertion" id="introduction-dns-sd-service-name-directory">
<td><code>_directory._sub._wot._tcp</code></td>
<td>TDD</td>
<td>HTTP over TCP, HTTP over TLS/TCP, CoAP over TCP, or CoAP over TLS/TCP</td>
</tr>
<tr class="rfc2119-table-assertion" id="introduction-dns-sd-service-name-udp">
<td><code>_wot._udp</code></td>
<td>Thing</td>
<td>CoAP over UDP or CoAP over DTLS/UDP</td>
</tr>
<tr class="rfc2119-table-assertion" id="introduction-dns-sd-service-name-directory-udp">
<td><code>_directory._sub._wot._udp</code></td>
<td>TDD</td>
<td>CoAP over UDP or CoAP over DTLS/UDP</td>
</tr>
</tbody>
</table>
</p>
<div class="rfc2119-assertion" id="introduction-dns-sd-txt-record">
<p>
In addition, the following information MUST be included in the <code>TXT</code>
record that is pointed to by the Service Instance Name:
</p>
<dl>
<dt><code>td</code></dt>
<dd>Absolute pathname of the Thing Description of the Thing or Thing Description of the <a>Thing Description Directory</a>.</dd>
<dt><code>type</code></dt>
<dd>Type of the Thing Description, i.e. <code>Thing</code> or <code>Directory</code>.
If omitted, the type is assumed to be <code>Thing</code>.</dd>
<dt><code>scheme</code></dt>
<dd>Scheme part of URL. One of the following values can be specified, with the standard registered URI interpretations [[RFC7595]]: <code>http</code> (HTTP over TCP),<code>https</code> (HTTP over TLS/TCP), <code>coap</code> (CoAP over UDP), <code>coaps</code> CoAP over DTLS/UDP), <code>coap+tcp</code> (CoAP over TCP), or <code>coaps+tcp</code> (CoAP over TLS/TCP).
If omitted, the scheme is assumed to be <code>http</code> for TCP and <code>coap</code> for UDP. </dd>
</dl>
</div>
<p>
<a href="#sequence-dnssd-thing"></a> and <a href="#sequence-dnssd-directory"></a> shows example sequences
supporting discovery of a Thing or a <a>Thing Description Directory</a> using DNS-SD and mDNS.
</p>
<figure id="sequence-dnssd-thing">
<img src="images/sequence-dnssd-thing.png"
srcset="images/sequence-dnssd-thing.svg"
class="wot-diagram"
alt="An example sequence of discovery of Thing using DNS-SD and mDNS" />
<figcaption>Using mDNS for discovery of the Thing Description of a Thing</figcaption>
</figure>
<figure id="sequence-dnssd-directory">
<img src="images/sequence-dnssd-directory.png"
srcset="images/sequence-dnssd-directory.svg"
class="wot-diagram"
alt="An example sequence of discovery of directory service using DNS-SD and mDNS" />
<figcaption>Using mDNS for discovery of the Thing Description of a Thing Description Directory (TDD)</figcaption>
</figure>
</section>
<section id="introduction-core-rd-sec" class="normative">
<h2>CoRE Link Format and CoRE Resource Directory</h2>
<p>
<span class="rfc2119-assertion" id="introduction-core-rd">A Thing or <a>Thing Description Directory</a> MAY advertise its presence using the
Constrained RESTful Environment (CoRE) Link Format [[RFC6690]].</span>
<span class="rfc2119-assertion" id="introduction-core-rd-directory">
A <a>Thing</a> or <a>Thing Description Directory</a> MAY use the CoRE Resource Directory [[RFC9176]]
to register a link to its corresponding Thing Description.</span>
</p>
<p>
<span class="rfc2119-assertion" id="introduction-core-rd-resource-type-thing">
The resource type (<code>rt</code>) of the Link that targets the Thing Description of the Thing
MUST be <code>wot.thing</code>.</span>
<span class="rfc2119-assertion" id="introduction-core-rd-resource-type-directory">
The resource type of the Link that targets the Thing Description of the <a>Thing Description Directory</a>
MUST be <code>wot.directory</code>.</span>
</p>
</section>
<section id="introduction-did-sec" class="normative">
<h2>DID Documents</h2>
<p><span class="rfc2119-assertion" id="introduction-did">A <a>Thing</a> or <a>Thing Description Directory</a>
using a Decentralized Identifier (DID) [[DID-CORE]] MAY advertise the location of its <a>TD</a>
by including a DID Service Endpoint of type
<code>WotThing</code> or <code>WotDirectory</code>, respectively, in the DID Document that
the TD's identifier resolves to.</span>
</p>
<p><span class="rfc2119-assertion" id="introduction-did-service-endpoint">
If the DID Document obtained by resolving the DID of a <a>Thing</a> or <a>Thing Description Directory</a>
contains a Service Endpoint of type <code>WotThing</code> or <code>WotDirectory</code>, respectively,
then this Service Endpoint MUST refer to the <a>TD</a> describing that Thing
(when using the <code>WotThing</code> service name)
or the <a>TD</a> describing that <a>Thing Description Directory</a> (when using the <code>WotDirectory</code> service name),
respectively.</span>
</p>
<aside class="example" title="A Example Service Endpoint in a DID Document - WotThing">
<pre>
{
"service": [{
"id": "did:example:wotdiscoveryexample#td",
"type": "WotThing",
"serviceEndpoint":
"https://wot.example.com/.well-known/wot"
}]
}
</pre>
</aside>
<aside class="example" title="A Example Service Endpoint in a DID Document - WotDirectory">
<pre>
{
"service": [{
"id": "did:example:wotdiscoveryexample#tdd",
"type": "WotDirectory",
"serviceEndpoint":
"https://wot.example.com/tdd"
}]
}
</pre>
</aside>
</section>
</section>
<section id="exploration-mech" class="normative">
<h1>Exploration Mechanisms</h1>
<!--
<p class="ednote" title="Exploration Mechanism Overview">
To do: Description of supported explorations, and requirements for
new exploration mechanisms.
</p>
<div class="issue" data-number="202"></div>
-->
This section defines the supported exploration mechanisms
after providing some common background material.
<section id="exploration-overview" class="normative">
<h2>Overview</h2>
<figure id="exploration-class-diagram">
<img src="images/exploration-class-diagram.svg"
class="wot-diagram"
alt="Exploration mechanisms high-level class diagram" />
<figcaption>
The high-level class diagram of the exploration mechanisms,
depicting how Thing Description Servers and Thing Description Directories provide <a>TDs</a>.
A Self-describing Thing is a special case of a Thing Description Server that is also a Thing.
A Thing Description Directory acts as a Thing Description Server for each
Thing Description it contains.
</figcaption>
</figure>
<p>
[[[#exploration-class-diagram]]] depicts the high-level information
model for <a>TD Servers</a> (serving single TDs, including those for self-description)
and <a>Thing Description Directory</a> services.
A <a>Thing Description Directory</a> may contain <a>TDs</a>
and at the same time is also a Thing, which means it has its own TD.
A directory also hosts web service endpoints
for retrieving individual TDs for other Things
and each of these can be used as a TD Server.
A Thing may in general host its own TD in which case it
is a Self-Describing Thing.
Self-description is not mandatory for directories,
but Self-Describing Thing Description Directories are possible
that are both Thing Description Directories and Self-Describing Things.
</p>
<p>
The two basic exploration mechanisms are described in
[[[#exploration-server]]] and [[[#exploration-directory]]].
</p>
<section id="exploration-ontology" class="normative">
<h3>Ontology</h3>
<figure id="discovery-class-diagram-ontology">
<img src="images/discovery-class-diagram-ontology.svg"
class="wot-diagram"
alt="Ontology of TD in discovery context" />
<figcaption>The ontology of Thing Descriptions in the Discovery context.</figcaption>
</figure>
<p>
[[[#discovery-class-diagram-ontology]]] illustrates the Discovery ontology
as an extension of the Thing ontology.
</p>
<p>
The ontology includes a class for metadata that are associated with
TDs stored in a directory.
This class is called `RegistrationInformation` and described as part
of the directory specification in [[[#exploration-directory-registration-info]]].
</p>
<p>
The Discovery ontology also defines two new Thing Description classes,
described in the following sections,
that may be used to model special exploratory metadata:
<a href="#exploration-td-type-thingdirectory">ThingDirectory</a> and
<a href="#exploration-td-type-thinglink">ThingLink</a>.
</p>
<section id="exploration-td-type-thingdirectory" class="normative">
<h4>`ThingDirectory`</h4>
<div class="issue" data-number="148">
The type URIs used below are tentative and subject to change.
</div>
<span class="rfc2119-assertion" id="exploration-directory-description-type">
A TD which describes a Thing Description Directory instance MUST use type `ThingDirectory` from the
discovery context or URI `https://www.w3.org/2021/wot/discovery#ThingDirectory`.</span>
<p>
A TD of this class can be derived from Directory's Thing Model; see [[[#directory-api-spec]]].
</p>
</section>
<section id="exploration-td-type-thinglink" class="normative">
<h4>`ThingLink`</h4>
<div class="issue" data-number="148">
The type URIs used below are tentative and subject to change.
</div>
<span class="rfc2119-assertion" id="exploration-link-description-type">
A TD which describes a reference to another TD MUST use type `ThingLink` from the
discovery context or URI `https://www.w3.org/2021/wot/discovery#ThingLink`.</span>
<span class="rfc2119-assertion" id="exploration-link-description-link">
A Thing Link MUST define the referenced TD as a Link with
`describedby` link relation type, `application/td+json` media type
and `href` set to the target URL.</span>
<p>
[[[#example-td-link-type]]] is an example Thing Link.
</p>
<!-- Using https://tools.ietf.org/html/rfc6963 for ID of examples -->
<aside class="example" id="example-td-link-type" title="Example of a Thing Link, referencing a remote TD">
<pre>
{
"@context": [
"http://www.w3.org/ns/td",
"https://w3c.github.io/wot-discovery/context/discovery-context.jsonld"
],
"@type": "ThingLink",
"id": "urn:example:link",
"links": [{
"rel": "describedby",
"href": "https://example.com/td.jsonld",
"type": "application/td+json"
}],
"security": "nosec_sc",
"securityDefinitions": {
"nosec_sc": {
"scheme": "nosec"
}
},
"title": "Example TD referencing another"
}
</pre>
<div class="issue" data-number="148">
The context URIs are tentative and subject to change.
</div>
</aside>
<p>
A Thing Link can be used in various scenarios. For example:
</p>
<ul>
<li>
A self-describing Thing with limited computational resources intends
to describe itself: host a minimal <a>TD</a> (Thing Link) locally
and references a larger one with the full details hosted at a
different URL, perhaps in a directory.
</li>
<li>
A self-describing Thing or proxy has a very large or dynamic description:
registers a small or static <a>TD</a> (Thing Link) in a
directory which references the actual <a>TD</a> hosted at the edge.
</li>
<!-- We decided to remove this use case, since it is probably best
handled with access controls. However, this use case AND the ones
above imply a mix of link and other metadata and affordances, not
"pure" Thing Links. So we can't in general assume Thing Links
don't have other information.
<li>
A device intends to publish an entire <a>TD</a> which contains private and
public parts: publish one <a>TD</a> (Thing Link) with only the public
information referencing another <a>TD</a> which contains the full description.
</li>
-->
</ul>
</section>
</section>
<section id="exploration-secboot" class="normative">
<h3>Security Bootstrapping</h3>
<p>The purpose of an exploration service is to serve TDs, but only after suitable
authentication, and only to authorized parties.
However, in some cases a Discoverer may not know what security credentials are
needed to access a TD via an exploration service, particularly in ad-hoc scenarios.
Since upon first access to an exploration service a Discoverer will not yet
have access to the TD if suitable authentication credentials are not provided,
the Discoverer can't depend on the security metadata
held in TDs to know what kind of authentication and authorization information is needed.
If the Discoverer has no prior knowledge,
it will have to depend on existing security negotation support to
bootstrap access, at least to the TD itself.
</p>
<p>
We define the following for the HTTP protocol, for which security negotiation
processes already exist.
However, most of the HTTP negotiation processes assume there is a human user in the loop,
but this is also appropriate for WoT Discovery, since this problem will
typically occur when a user is trying to access a public WoT service or perform
integration of a new device. In this case the purpose of negotiation is to
provide guidance on what credentials are needed to access the system.
</p>
<p>
In cases when exploration services are being used to
automate system management it would be best to pre-establish what credentials (and
authentication mechanisms) are needed to access the relevant exploration services
and security bootstrapping would not be required.
For this reason security bootstrapping is not a mandatory feature, and can
be omitted or disabled on devices that are to be used with pre-established
security mechanisms.
</p>
<p>Security bootstrapping may also only be necessary on the <em>first</em> access to
a TD. Once a Discoverer has determined what credentials and authentication mechanism
are required to access a particular exploration service, they can retain this information
and attempt to use them for future accesses.
Note however that depending on the security scheme used, credentials themselves
may expire and may need to be re-established periodically.
</p>
<p>
<span class="rfc2119-assertion" id="security-bootstrapping-endpoints">Security
bootstrapping MAY be provided on any HTTP endpoint that serves a TD.</span>
<!--
This applies not only to endpoints serving TDs from self-describing Things,
but also to endpoints that retrieve single TDs,
including those in a <a>WoT Thing Description Directory</a>.
-->
As mentioned above, disabling or omitting security bootstrapping is permissible if
security mechanisms have been previously established. For example, if an installation
wants to use the OAuth2 <code>client</code> flow and provide potential clients with
an address of an authentication server to use in advance, then security bootstrapping
can be disabled, since the alternative would be to include other (and potentially
weaker) forms of authentication.
</p>
<p>In the HTTP protocol, the authentication and authorization mechanisms to be used can generally be negotiated by
the HTTP server returning a "401 (Unauthorized)" response code in conjunction with
a `WWW-Authenticate` header that specifies the information required.
To gain access, the client then needs to make another request
with the necessary information.
<a href="https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml">There
are several authentication schemes registered with IANA.</a>
However, not all of these are in wide use, some are experimental, and there is only
partial overlap with the schemes supported by TDs.
Also, note that the <code>oauth</code> scheme in the IANA registration refers
to OAuth1, which is deprecated, so it should not be used.
The relevant OAuth2 flow, the <code>code</code> flow, instead of a 401 response
begins with a redirection to an authentication
server, eventually resulting in credentials (bearer tokens in the case of WoT)
that can be used for access.
</p>
<p>
Given these considerations,
to enable security bootstrapping on a wide variety of devices as well
as on browsers, the following constraints should be observed:
</p>
<ul>
<li><span class="rfc2119-assertion" id="exploration-secboot-401">
If security bootstrapping is enabled on an exploration service,
after initial contact using the URL provided
by an introduction mechanism, the exploration service
MUST reply with either an HTTP "401 (Unauthorized)" response code
or (in the case of OAuth2) with either a HTTP "302 (Found)" or "303 (See Other)" response code if appropriate
authentication information has not been provided but access can be granted
when it is.</span>
Note that if the exploration service does not want to provide access for
some reason, or if security bootstrapping is disabled,
it can ignore the request or reply with another code such as 404 or 403.
Also, if no authentication is required, then the
system can reply immediately with the requested TD as if authentication information
were provided.
Bypassing authentication however is only
appropriate if the TD served as a response does not contain and cannot be used to infer
Personally Identifiable Information; see <a href="#privacy-considerations"></a>.
</li>
<li><span class="rfc2119-assertion" id="exploration-secboot-auth">
If security bootstrapping is enabled on an exploration service
using one of the following IANA-registered
HTTP Authentication Schemes: Basic, Bearer, or Digest,
then a 401 HTTP response
at an API endpoint intended to serve a TD
MUST include a <code>WWW-Authenticate</code> header
and any other headers
describing the required authorizations.</span>
For details of the requirements, the IANA registry should be consulted for
each of the above authentication schemes.
<span class="rfc2119-assertion" id="exploration-secboot-oauth2-flows">
If the OAuth2 <code>code</code> flow is used during security bootstrapping, the
"302 (Found)" or "303 (See Other)" response code MUST be used for redirection
to the authentication server,
with access credentials eventually being represented with bearer tokens.</span>
Note that the other OAuth2 flows supported in WoT Thing Description 1.1,
<code>client</code> and <code>device</code>, both expect the initial access
to be to the authentication server, not the final endpoint, and so cannot be
used via security bootstrapping.
These requirements also apply only to endpoints of exploration services that might need
to support security bootstrapping, that is those that serve TDs,
not to other endpoints that might be
provided by the same exploration service.
In particular, these requirements apply
only to URLs that can be referenced by introduction mechanisms, not to (for example)
event subscription endpoints.