forked from w3c/wot-discovery
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
2825 lines (2699 loc) · 164 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>
<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
},
doJsonLd : true,
specStatus : "ED",
shortName : "wot-discovery",
copyrightStart : 2017,
group: "wg/wot",
wgPublicList : "public-wot-wg",
github: {
repoURL: "https://github.com/w3c/wot-discovery",
branch: "master"
},
previousPublishDate: "2020-11-24",
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 : "Fraunhofer-Gesellschaft",
companyURL : "https://www.fraunhofer.de/"
}, {
name : "Kunihiko Toumura",
w3cid : "83488",
company : "Hitachi, Ltd.",
companyURL : "https://www.hitachi.com/"
} ],
otherLinks : [
{
key : "Contributors",
data : [ {
value : "In the GitHub repository",
href : "https://github.com/w3c/wot-discovery/graphs/contributors"
} ]
}],
localBiblio : {
"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"
},
"CoRE-RD" : {
title: "CoRE Resource Directory"
, href: "https://tools.ietf.org/html/draft-ietf-core-resource-directory-26"
, authors: [
"Christian Amsüss"
, "Zach Shelby"
, "Michael Koster"
, "Carsten Bormann"
, "Peter van der Stok"
]
, publisher: "IETF"
, date: "2 November 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, 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.
</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-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.
</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-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.
</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 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-architecture/#terminology">Section 3</a>
of the WoT Architecture specification [[?WOT-ARCHITECTURE]].
</p>
</section>
<section id="architecture" class="informative">
<h1>Architecture</h1>
<a href="#discovery-overview"></a> shows an overview of discovery process.
<figure id="discovery-overview">
<img src="images/overview.png"
srcset="images/overview.svg"
class="wot-diagram"
alt="Discovery process overview" />
<figcaption>Discovery process overview</figcaption>
</figure>
<p>
The WoT discovery process is designed using a two-phase approach.
In the first phase, one or more of a set of "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, "Exploration", to actually fetch metadata.
The intention is that Introductions are relatively open and can support any
mechanism that can return a URL, including simply entering URLs directly.
Introductions, however, do not include any security or privacy controls and
so should not provide metadata directly. Instead, the provided URLs are followed
to "Exploration" mechanisms that will actually provide metadata but allow for
suitable security and privacy controls.
</p>
<p>
Note that the discovery process can produce a <em>set</em> of URLs following
its Introduction phase, even if only one Introduction mechanism is used,
and the final output after the Exploration phase
can be a <em>set</em> of Thing Descriptions.
Generally each URL provided by the Introduction phase points at a Thing Description,
and in the simplest case this is in fact the Thing Description of a Thing that
represents an IoT device. In the case of self-describing Things the URL might
even point directly at the Thing which can serve its own Thing Description,
but in general Thing Descriptions might also be provided by other entities.
However, there are also two special cases that allow for more flexibility:
</p>
<ul>
<li>A given Thing Description may in fact describe a Thing Description Directory service.
A Thing Description Directory service (which is still a Thing) maintains a (usually dynamic) list of Thing Descriptions
which can be fetched and added to the discovery set (the set can be narrowed by
using query filters when fetching TDs from a directory).
</li>
<li>
The second special case is a Thing Link. This is also a Thing Description,
but rather than describing a Thing directly holds a link to
a Thing Descriptions 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>
</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-ARCHITECTURE]].
</p>
<p class="ednote" title="Consumers SHOULD support Discovery">
Note: the WoT Architecture specification only says that Consumers SHOULD support Discovery.
</p>
<p>
The WoT Discovery process is designed so that nearly any client that can fetch a single TD
given a single URI using any protocol (including "file") 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 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 or by reading it from a file
specified by way of a file 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 is a Thing Description Directory or a Thing Link.</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 Thing Link
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 Thing Link 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 Thing Link 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-self]]].
</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 Directory 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 the Thing or <a>Thing Description Directory</a> use the Well-Known Uniform Resource Identifier to advertise its presense, it MUST register its own Thing or Directory Description
into the following path:
<code>/.well-known/wot-thing-description</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-self]]].
</span>
</p>
<p class="ednote" title="Registration of Well-known URI">
The service name in Well-Known URI (<code>wot-thing-description</code>) is tentative.
"Well-Known URIs" registry and contents of registration request is described in Section 3.1 of [[RFC8615]].
</p>
</section>
<section id="introduction-dns-sd" 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 the DNS-Based Service Discovery (DNS-SD)[[RFC6763]].</span>
This can be also be used to discover them on the same link by combining Multicast DNS (mDNS)[[RFC6762]].
</p>
<p>
In DNS-SD, format of the Service Instance Name is <code>Instance.Service.Domain</code>.
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.
</p>
<p>
<span class="rfc2119-assertion" id="introduction-dns-sd-service-name">
The Service Name to indicate the Thing or <a>Thing Description Directory</a> MUST be <code>_wot</code>.
</span>
<span class="rfc2119-assertion" id="introduction-dns-sd-service-name-directory">
And the Service Name to indicate the <a>Thing Description Directory</a> MUST be <code>_directory._sub._wot</code>.
</span>
</p>
<p class="ednote" title="Service Names in existing implementations">
The Service Names <code>_wot</code> and <code>_directory._sub._wot</code>
are tentative. The following Service Names are used in the existing implementations:
<code>_wot</code>,
<code>_device._sub._wot</code>,
<code>_directory._sub._wot</code>,
<code>_webthing</code>,
<code>_wot-servient</code>.
To use a Service Name, registration to "Underscored and Globally Scoped DNS Node Names"
Registry [[RFC8552]] is required.
</p>
<p>
<span class="rfc2119-assertion" id="introduction-dns-sd-txt-record">
In addition, the following information MUST be included in the <code>TXT</code>
record that is pointed to by the Service Instance Name:
<dl>
<dt><code>td</code></dt>
<dd>Absolute pathname of the Thing Description of the Thing or Directory 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>
</dl>
</span>
</p>
<p class="ednote" title="Usage of a TXT record in existing implementations">
The following key/value pairs are used in the existing implementations:<br/>
<code>retrieve</code>:
Absolute path name of the API to get an array of Thing Description IDs
from the directory service.<br/>
<code>register</code>:
Absolute path name of the API to register a Directory Description with the <a>Thing Description Directory</a>.<br/>
<code>path</code>:
The URI of the thing description on the Web Thing's web server<br/>
<code>td</code>:
Prefix of directory service API<br/>
<code>tls</code>:
Value of 1 if the Web Thing supports connections via HTTPS.<br/>
</p>
<p>
<a href="#sequence-dnssd-thing"></a> and <a href="#sequence-dnssd-directory"></a> shows example sequences
of discovery of Thing and <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>An example sequence of discovery of Thing using DNS-SD and mDNS</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>An example sequence of discovery of <a>Thing Description Directory</a> using DNS-SD and mDNS</figcaption>
</figure>
</section>
<section id="introduction-core-rd" 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 Thing or <a>Thing Description Directory</a> MAY use the CoRE Resource Directory [[CoRE-RD]]
to register a link to the Thing or Directory 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 Directory Description of the <a>Thing Description Directory</a>
MUST be <code>wot.directory</code>.
</span>
</p>
<p class="ednote">
The resource types <code>wot.thing</code> and <code>wot.directory</code> are tentative.
See also <a href="#iana-considerations"></a>.
</p>
</section>
<section id="introduction-did" class="normative">
<h2>DID Documents</h2>
<p><span class="rfc2119-assertion" id="introduction-did">A Thing or <a>Thing Description Directory</a> MAY advertise its presence using
the Decentralized Identifier (DID) [[DID-CORE]].</span>
</p>
<p>
<span class="rfc2119-assertion" id="introduction-did-service-endpoint">
The DID Document obtained by resolving the DID of a Thing or <a>Thing Description Directory</a> MUST
contains a Service Endpoint which point to Thing Description of the Thing or Directory Description of the <a>Thing Description Directory</a>.
</span>
</p>
<aside class="example" title="A Example Service Endpoint in a DID Document">
<pre>
{
"service": [{
"id": "did:example:wotdiscoveryexample#td",
"type": "WotThingDescription",
"serviceEndpoint":
"https://wot.example.com/.well-known/wot-thing-description"
}]
}
</pre>
</aside>
<div class="issue" data-number="65"></div>
</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>
<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 Things expose <a>TDs</a>.
</figcaption>
</figure>
[[[#exploration-class-diagram]]] depicts the high-level information
model for self-describing and directory services.
A directory may contain <a>TDs</a> and at the same time provide a <a>TD</a>
and act as a self-describing Thing.
The exploration mechanisms are described in
[[[#exploration-self]]] and [[[#exploration-directory]]].
<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>
Moreover, the Discovery ontology defines two new Thing Description classes
that may be used to model special exploratory metadata:
</p>
<div class="issue" data-number="148">
The type URIs used below are tentative and subject to change.
</div>
<dt>Thing Directory</dt>
<dd>
<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>
[[[#directory-api-spec]]] which describes the API of the
Thing Description Directory is an example of this TD class.
</p>
</dd>
<dt>Thing Link</dt>
<dd>
<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:
<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>
</p>
</dd>
<section id="exploration-self" class="normative">
<h2>Self-description</h2>
<!-- <p class="ednote" title="Self-Description Overview">
To do: Describe mechanisms for devices to self-describe, hosting their own TDs.
</p> -->
<p>
The self-description is an exploration mechanism in which a <a>Thing</a>
hosts its own <a>TD</a> 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 [[[#introduction-mech]]].
The hosted <a>TD</a> may also be registered inside a <a>Thing Description Directory</a>
as prescribed in [[[#exploration-directory]]].
</p>
The self-description using the following protocols must be according
to the given specification:
<dl>
<dt>HTTP</dt>
<dd>
<p>
<span class="rfc2119-assertion" id="self-http-secure">
The HTTP-based self-description SHOULD be over HTTPS (HTTP Over TLS).
</span>
<span class="rfc2119-assertion" id="self-http-access-control">
The server SHOULD serve the requests after performing necessary
authentication and authorization.
</span>
</p>
<p>
<span class="rfc2119-assertion" id="self-http-method">
The HTTP server MUST serve the <a>TD</a> with a `GET` method.
</span>
<span class="rfc2119-assertion" id="self-http-resp">
A successful response MUST have 200 (OK) status, contain `application/td+json`
Content-Type header, and the <a>TD</a> in body.
</span>
<span class="rfc2119-assertion" id="self-http-alternate-content">
The server MAY provide alternative representations through
server-driven content negotiation, that is by honouring the
request's Accept header and responding with the supported
TD serialization and equivalent Content-Type header.
</span>
</p>
<p>
<span class="rfc2119-assertion" id="self-http-head">
The HTTP server MUST respond to `HEAD` requests by returning only the headers
equivalent to those returned by a `GET` request to the same endpoint.
</span>
This enables clients to retrieve HTTP headers such as the Content-Length in advance
to know the size of the <a>TD</a> (in bytes) and decide on an efficient query strategy.
</p>
<p>
In constrained environments, a single <a>TD</a> may be too large to process
for the server or clients.
See [[[#perf-incremental-transfer]]] for protocol-specific recommendations on
incremental transfer of the requested payload.
</p>
<p>
Error responses:
<ul>
<li>
401 (Unauthorized): No authentication.
</li>
<li>
403 (Forbidden): Insufficient rights to the resource.
</li>
</ul>
</p>
</dd>
</dl>
<!-- add additional protocols for self-description here -->
</section>
<section id="exploration-directory" class="normative">
<h2>Directory</h2>
<p class="ednote" title="Directory Overview">
To do: Describe mechanisms for TDs to be hosted in a searchable directory service.
</p>
<section id="exploration-directory-info" class="normative">
<h3>Information Model</h3>
<p class="ednote" title="Directory Information Model">
To Do: Formal definition of information contained in a directory and its organization.
</p>
As shown in [[[#exploration-class-diagram]]],
the <a>Thing Description Directory</a> can contain zero or more <a>TDs</a>.
For every TD, the directory maintains additional metadata
for bookkeeping and search purposes.
These are described in
[[[#exploration-directory-registration-info]]] and
[[[#exploration-directory-anonymous-td]]].
A <a>TD</a> that embeds such additional metadata as part of the
interaction with the directory is called an <a>Enriched TD</a>.
<section id="exploration-directory-registration-info" class="normative">
<h4>Registration Information</h4>
The ontology of a <a>TD</a> in the Discovery context was
introduced in [[[#discovery-class-diagram-ontology]]].
The `RegistrationInformation` class is associated with <a>TDs</a> that are
stored in a directory.
The following table lists the registration information attributes for
use within <a>TDs</a> that embed or reference the Discovery context.
Note that only an <a>Enriched TD</a> embeds the registration information.
<span class="rfc2119-assertion" id="tdd-context-injection">
An <a>Enriched TD</a> MUST contain in its @context the URI <code>https://w3c.github.io/wot-discovery/context/discovery-context.jsonld</code>
</span>
In this table,
client refers to the producer or consumer of a <a>TD</a> and server refers to
the <a>Thing Description Directory</a>.
<table class="def">
<thead>
<tr>
<th>Vocabulary term</th>
<th>Description</th>
<th>Client Assignment</th>
<th>Server Assignment</th>
<th>Type</th>
</tr>
</thead>
<tbody>
<tr class="rfc2119-table-assertion" id="tdd-registrationinfo-vocab-created">
<td><code>created</code></td>
<td>
Provides information when the TD instance was
created inside the directory.
<p>
This MAY be set by the directory and returned to consumers.
</p>
</td>
<td>read-only</td>
<td>optional</td>
<td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#dateTime"><code>dateTime</code></a></td>
</tr>
<tr class="rfc2119-table-assertion" id="tdd-registrationinfo-vocab-modified">
<td><code>modified</code></td>
<td>
Provides information when the TD instance was
last modified inside the directory.
<p>
This MAY be set by the directory and returned to consumers.
</p>
</td>
<td>read-only</td>
<td>optional</td>
<td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#dateTime"><code>dateTime</code></a></td>
</tr>
<tr class="rfc2119-table-assertion" id="tdd-registrationinfo-vocab-expires">
<td><code>expires</code></td>
<td>
Provides the absolute time for when the TD instance registration expires.
<p>
The producer MAY set this to indicate the absolute expiry time
during the registration.
</p>
<p>
For servers that support expirable TDs:
If `ttl` (relative expiry) is present, the server MUST ignore
client assignments to `expires` and instead compute and set it internally.
</p>
</td>
<td>optional</td>
<td>optional</td>
<td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#dateTime"><code>dateTime</code></a></td>
</tr>
<tr class="rfc2119-table-assertion" id="tdd-registrationinfo-vocab-ttl">
<td><code>ttl</code></td>
<td>
Time-to-live: relative amount of time in seconds from the registration time
until when the TD instance registration expires.
<p>
The producer MAY set this to indicate the relative expiry time
during the registration.
</p>
<p>
For servers that support expirable TDs:
The server MUST use `ttl` to calculate the `expires` (relative expiry) value.
</p>
</td>
<td>optional</td>
<td>read-only</td>
<td><code>number</code></a></td>
</tr>
<tr class="rfc2119-table-assertion" id="tdd-registrationinfo-vocab-retrieved">
<td><code>retrieved</code></td>
<td>
The time at which the TD was retrieved from the server.
<p>
This is useful for clients that intend to process other absolute timestamps but
do not have an internal clock or other means of acquiring the current time.
</p>
</td>
<td>read-only</td>
<td>optional</td>
<td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#dateTime"><code>dateTime</code></a></td>
</tr>
</tbody>
</table>
</section>
<section id="exploration-directory-registration-expiry" class="normative">
<h4>Registration Expiry</h4>
Section [[[#exploration-directory-registration-info]]] introduces few attributes to
specify and discover the expiry time of registered <a>TDs</a>.
<p>
Producers can set the expiry time to inform the directory and other consumers
about the validity of the TD registrations.
The expiry is also a useful indicator to inform the consumers about
expiry of dynamic <a>TDs</a>, e.g. when changes to metadata such as
geolocation or properties are expected to be valid for a limited period.
Consumers may rely on the expiry time to know how long a retrieved <a>TD</a>
will be valid and when they need to request a more recent one.
Consumers who retrieve an expired TD may consider it as metadata of an
inactive client.
</p>
<p>
For the servers, the expiry time is useful for implementing automatic
removal of obsolete or accidental registrations.