-
Notifications
You must be signed in to change notification settings - Fork 17
/
index.html
1283 lines (1220 loc) · 70.9 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 : {
"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-25"
, authors: [
"Zach Shelby"
, "Michael Koster"
, "Carsten Bormann"
, "Peter van der Stok"
, "Christian Amsüss"
]
, publisher: "IETF"
, date: "13 July 2020"
},
"JSONPATH" : {
title: "JSONPath -- XPath for JSON"
, href: "https://tools.ietf.org/id/draft-goessner-dispatch-jsonpath-00.html"
, authors: [
"S. Gössner"
, "C. Bormann, Ed."
]
, publisher: "IETF"
, date: "12 July 2020"
, 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 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 to 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>Property</dfn>,
<dfn>Action</dfn>,
<dfn>Event</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>
<p>
In addition, this specification introduces the following definitions:
</p>
<dl>
<dt><dfn data-lt="WoT Anonymous Thing Description">Anonymous TD</dfn>
</dt>
<dd>A Thing Description without an identifier (`id` attribute).
</dd>
<dt><dfn data-lt="WoT Discovery">Discovery</dfn>
</dt>
<dd>In the WoT context, the process of finding and retrieving Thing metadata
in the form of Thing Descriptions for Things satisfying some criteria of interest.
</dd>
<dt><dfn data-lt="WoT Enriched Thing Description">Enriched TD</dfn>
</dt>
<dd>A Thing Description embedded with additional attributes for bookkeeping and discovery.
</dd>
<dt><dfn data-lt="WoT Exploration">Exploration</dfn>
</dt>
<dd>A discovery mechanism that provides access to detailed metadata in the
form of one or more Thing Descriptions. Exploration mechanisms are in
general protected by security mechansism and are accessible only to authorized users.
</dd>
<dt><dfn data-lt="WoT Introduction">Introduction</dfn>
</dt>
<dd>A "first contact" discovery mechanism, whose result is a URL that
references an exploration mechanism. Introduction mechanisms themselves
should not directly provide metadata, and in general are designed to be
open.
</dd>
<dt><dfn data-lt="WoT TDD">TDD</dfn>
</dt>
<dd>Short for Thing Description Directory.
</dd>
<dt><dfn data-lt="WoT Thing Description Directory">Thing Description Directory</dfn>
</dt>
<dd>A directory service with a prescribed API that allows the
registration, management, and search of a database of Thing Descriptions.
Note that the acronym should be TDD, not TD, to avoid confusion with Thing Descriptions (TDs).
</dd>
<dt><dfn data-lt="WoT Partial Thing Description">Partial TD</dfn>
</dt>
<dd>A data model partially conformant to the Thing Description schema by including
only a subset of the attributes.
</dd>
</dl>
</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 class="ednote" title="Discovery Architecture Overview">
To do: an overview of the two-phase approach and its purpose, which is to support
controlled and authenticated access to metadata by authorized users only.
</p>
</section>
<section id="introduction-mech" class="normative">
<h1>Introduction Mechanisms</h1>
<p>This chapter describes a mechanism for discovering a Thing or a Directory Service.
The following mechanism is provided by the Thing or the Directory Service so that
Consumer can discover the Thing Description or a URL that point to the Thing Description.
</p>
<p class="ednote" title="Missing assertion blocks">
The following sub-sections define assertions without
using the `rfc2119-assertion` class.
</p>
<section id="introduction-direct" class="normative">
<h2>Direct</h2>
<p>Any mechanism that results in a single URL.
This includes Bluetooth beacons, QR codes, and written URLs to be
typed by a user.
A request on all such URLs MUST result in a TD as prescribed in
[[[#exploration-self]]].
For self-describing Things, this can be the TD of the Thing itself.
If the URL references a Directory, this MUST be the TD of the
Directory service.
</p>
</section>
<section id="introduction-well-known" class="normative">
<h2>Well-Known URIs</h2>
<p>
A Thing or Directory Service MAY use the Well-Known Uniform Resource Identifier [[RFC8615]]
to advertise its presence. The Thing or Directory Service registers its own Thing Description
into the following path:
<code>/.well-known/wot-thing-description</code>.
<p>
When a request is made at the above path, the server MUST return
a Thing Description as prescribed in [[[#exploration-self]]].
</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>A Thing or Directory Service MAY use the DNS-Based Service Discovery (DNS-SD)[[RFC6763]].
This can be also be used to discover them on the same link by combining Multicast DNS (mDNS)[[RFC6762]].
</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>
The Service Name to indicate the Thing or Directory Service MUST be <code>_wot</code>.
And the Service Name to indicate the Directory Service MUST be <code>_directory._sub._wot</code>.
</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>.
To use a Service Name, registration to "Underscored and Globally Scoped DNS Node Names"
Registry [[RFC8552]] is required.
</p>
<p>
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 Service.</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>
</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 Thing Description with the Directory Service.<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 Directory Service 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 Directory Service 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>
A Thing or Directory Service MAY advertise its presence using the
Constrained RESTful Environment (CoRE) Link Format [[RFC6690]].
And, a Thing or Directory Service MAY use the CoRE Resource Directory [[CoRE-RD]]
to register a link to the Thing Description.
</p>
<p>
The endpoint type(<code>et</code>) of the Link that targets the Thing Description of the Thing
MUST be <code>wot.thing</code>.
The endpoint type of the Link that targets the Thing Description of the Directory Service
MUST be <code>wot.directory</code>.
</p>
<p class="ednote">
The endpoint types <code>wot.thing</code> and <code>wot.directory</code> are tentative.
</p>
</section>
<section id="introduction-did" class="normative">
<h2>DID Documents</h2>
<p>A Thing or Directory Service MAY advertise its presence using
the Decentralized Identifier (DID) [[DID-CORE]].
</p>
<p>
The DID Document obtained by resolving the DID of a Thing or Directory Service MUST
contains a Service Endpoint which point to Thing Description of the Thing or Directory Service.
</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>
[[[#exploration-class-diagram]]] depicts the high-level information
model for self-describing and directory services.
These exploration mechanisms are described in
[[[#exploration-self]]] and [[[#exploration-directory]]].
<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</figcaption>
</figure>
This specification defines two new Thing Description classes which may be
used to model special exploratory metadata:
<dt>Directory Description</dt><dd>
A TD which describes a directory instance.
<span class="rfc2119-assertion" id="exploration-directory-description-type">
The Directory Description MUST use type `DirectoryDescription` from the
discovery context or URI `https://www.w3.org/2021/wot/discovery#DirectoryDescription`.
</span>
<p>
[[[#directory-thing-description]]] which describes the API of the
Thing Description Directory is an example of this TD type.
</p>
</dd>
<dt>Link Description</dt><dd>
A TD which describes a reference to another TD.
<span class="rfc2119-assertion" id="exploration-link-description-type">
The Link Description MUST use type `LinkDescription` from the
discovery context or URI `https://www.w3.org/2021/wot/discovery#LinkDescription`.
</span>
<span class="rfc2119-assertion" id="exploration-link-description-link">
The Link Description MUST define the reference 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 Link Description.
</p>
<!-- Using https://tools.ietf.org/html/rfc6963 for ID of examples -->
<aside class="example" id="example-td-link-type" title="Example Link Description">
<pre>
{
"@context": [
"https://www.w3.org/2019/wot/td/v1",
"https://w3c.github.io/wot-discovery/context/discovery-context.jsonld"
],
"@type": "LinkDescription",
"id": "urn:example:link",
"links": [{
"rel": "describedby",
"href": "https://example.com/td.jsonld",
"type": "application/td+json"
}],
"security": "basic_sc",
"securityDefinitions": {
"basic_sc": {
"scheme": "basic"
}
},
"title": "Example TD referencing another"
}
</pre>
</aside>
</dd>
<p class="issue" data-number="54">
The context and type URIs are tentative and subject to change.
</p>
<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 TD 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-method">
The HTTP server MUST serve the TD 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 TD 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>
<span class="rfc2119-assertion" id="self-http-access-control">
The server SHOULD serve the requests after performing necessary
authentication and authorization.
</span>
</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>
</section>
<figure id="directory-class-diagram">
<img src="images/directory-class-diagram.svg"
class="wot-diagram"
alt="Directory service class diagram" />
<figcaption>The class diagram of the directory service</figcaption>
</figure>
<p>
[[[#directory-class-diagram]]] shows the information model of the
<a>Thing Description Directory</a>.
A directory can contain zero or more <a>TD</a>s.
For every TD, the directory may maintain the registration information for
bookkeeping and search purposes. The information may also include the
unique identifier of the TD within the directory.
This is useful for when a TD has been registered under an identifier
which differs from TD's internal `id` field.
When available, consumers may request the registration information
via the respective API.
A TD which embeds the registration information is called an <a>Enriched TD</a>.
</p>
<section id="exploration-directory-api" class="normative">
<h3>Directory Service API</h3>
The Directory APIs must use secure protocols guaranteeing
<a href="https://www.w3.org/TR/wot-security/#dfn-system-user-data">System User Data</a>
authenticity and confidentiality (see [[?WOT-SECURITY]]).
<span class="rfc2119-assertion" id="tdd-https">
The HTTP API MUST be exposed over HTTPS (HTTP Over TLS).
</span>
<p>
The HTTP API responses must use appropriate status codes described in
this section for success and error responses.
<span class="rfc2119-assertion" id="tdd-http-errors">
The HTTP API MUST use the Problem Details [[RFC7807]] format to carry
error details in HTTP client error (4xx) and server error (5xx) responses.
</span>
This enables both machines and humans to know the high-level error class
and fine-grained details.
<p class="ednote" title="WoT-specific error types">
The Problem Details error `type` field is a URI reference which
could used to map the occurred error to WoT-specific error class.
There are few open issues raising the lack of WoT-specific error types:
<a href="https://github.com/w3c/wot-discovery/issues/44">wot-discovery#44</a>,
<a href="https://github.com/w3c/wot-thing-description/issues/303">wot-thing-description#303</a>,
<a href="https://github.com/w3c/wot-scripting-api/issues/200">wot-scripting-api#200</a>.
<br>
For now, `type` can be omitted which defaults to "about:blank", and `title`
should be set to HTTP status text.
</p>
</p>
<p>Below is a generic Thing Description for the Directory HTTP API
with OAuth2 security. The Thing Description alone should not be
considered as the full specification to implement or interact with
a directory. Additional details for every interaction are described
in human-readable form in the subsequent sections.
</p>
<aside class="example" id="directory-thing-description" title="Thing Description of the Directory">
<pre><div data-include='directory.td.json'></div></pre>
<p class="ednote" title="Normative JSON Block">
Need to add a css class for normative code blocks, instead of using the `example` class.
</p>
<p class="ednote" title="ID Type">
The `id` variable need to have a defined type for semantic association with TD's `id` attribute.
</p>
<p class="ednote" title="Scopes">
The scopes may need to be more concrete to able to allow updates but prevent creation.
</p>
</aside>
<p class="issue" data-number="82">
Need to confirm if equivalent OpenAPI spec can be easily created out of the TD in
[[[#directory-thing-description]]]. If yes, a sentence may be added indicating
this possibility.
</p>
<section id="exploration-directory-api-registration" class="normative">
<h4>Registration</h4>
<p>
The Registration API is a RESTful HTTP API in accordance with the recommendations
defined in [[RFC7231]] and [[?REST-IOT]].
<span class="rfc2119-assertion" id="tdd-reg-default-representation">
The default serialization format for all request and response bodies MUST be
JSON, with JSON-LD 1.1 [[JSON-LD11]] syntax to support extensions and semantic
processing.
</span>
<span class="rfc2119-assertion" id="tdd-reg-additional-representation">
Directories MAY accept additional representations based on request's indicated
Content-Type or Content-Encoding, and provide additional representations through
server-driven content negotiation.
</span>
</p>
<p>
<span class="rfc2119-assertion" id="tdd-reg-operations">
The Registration API MUST provide create, retrieve, update, delete (CRUD) interfaces.
</span>
<div class="issue" data-number="16">
The API needs to offer a mechanism to efficiently query all TDs.
The search API may offer the expected functionality by searching for everything
and adding protocol-specific pagination arguments. However, that is hardly RESTful.
We could instead extend the registration API to CRUDL, adding Listing operation.
</div>
The operations are described below:
</p>
<section id="exploration-directory-api-registration-creation" class="normative">
<h4>Creation</h4>
<p>
<span class="rfc2119-assertion" id="tdd-reg-create-body">
The API MUST allow registration of a TD object passed as request body.
</span>
<span class="rfc2119-assertion" id="tdd-reg-create-contenttype">
The request SHOULD contain `application/td+json` Content-Type header for
JSON serialization of TD.
</span>
The TD object must be validated in accordance with [[[#validation]]].
</p>
<p>
<span class="rfc2119-assertion" id="tdd-reg-types">
A TD which is identified with an `id` attribute MUST be handled
differently with one that has no identifier (<a>Anonymous TD</a>).
</span>
The create operations are specified as `createTD` action in
[[[#directory-thing-description]]]
and elaborated below:
</p>
<ul>
<li>
<span class="rfc2119-assertion" id="tdd-reg-create-known-td">
A TD MUST be submitted to the directory using an HTTP `PUT` request at a
target location (HTTP path) containing the unique TD `id`.
</span>
<span class="rfc2119-assertion" id="tdd-reg-create-known-td-resp">
Upon successful processing, the server MUST respond with
201 (Created) status.
</span>
<p>
Note: If the target location corresponds to an existing TD,
the request shall instead proceed as an Update operation and respond
the appropriate status code (see Update section).
</p>
</li>
<li>
<span class="rfc2119-assertion" id="tdd-reg-create-anonymous-td">
An <a>Anonymous TD</a> MUST be submitted to the directory using an HTTP `POST` request.
</span>
<span class="rfc2119-assertion" id="tdd-reg-create-anonymous-td-resp">
Upon successful processing, the server MUST respond with 201 (Created) status
and a Location header containing a system-generated identifier for the TD.
</span>
<span class="rfc2119-assertion" id="tdd-reg-create-anonymous-td-generated-id"></span>
The identifier SHOULD be a Version 4 UUID URN [[RFC4122]].
</span>
</li>
</ul>
<p>
Error responses:
<ul>
<li>
400 (Bad Request): Invalid serialization or TD.
This is accompanied by an appropriate response message.
</li>
<li>
401 (Unauthorized): No authentication.
</li>
<li>
403 (Forbidden): Insufficient rights to the resource.
</li>
</ul>
</p>
In certain scenarios (e.g. automatic removal of obsolete or accidental registrations),
the registration may benefit from an expiration time.
The expiration time may be set explicity or relative to the registration time
as a time-to-live (TTL) value.
<span class="rfc2119-assertion" id="tdd-reg-">
When TTL is set, the server MUST calculate the expiration time relative
to creation time.
</span>
<span class="rfc2119-assertion" id="tdd-reg-">
The server MAY
</span>
<p class="ednote" title="Deduplication">
The server should employ a mechanism to eliminate duplication of TDs submitted with
a `POST` request. The spec need to have recommendations on how to perform this.
</p>
</section>
<section id="exploration-directory-api-registration-retrieval" class="normative">
<h4>Retrieval</h4>
<p>
<span class="rfc2119-assertion" id="tdd-reg-retrieve">
A TD MUST be retrieved from the directory using an HTTP `GET` request,
including the identifier of the TD as part of the path.
</span>
<span class="rfc2119-assertion" id="tdd-reg-retrieve-resp">
A successful response MUST have 200 (OK) status, contain `application/td+json`
Content-Type header, and the requested TD in body.
</span>
The retrieve operation is specified as `retrieveTD` property in
[[[#directory-thing-description]]].
</p>
<p>
Error responses:
<ul>
<li>
404 (Not Found): TD with the given `id` not found.
</li>
<li>
401 (Unauthorized): No authentication.
</li>
<li>
403 (Forbidden): Insufficient rights to the resource.
</li>
</ul>
</p>
<p class="ednote" title="Registration Info query argument">
Need to specify and describe the query argument to toggle
enrichment of TD with registration info.
</p>
The following is an example queried TD, enriched with the registration info per request:
<aside class="example" id="example-td-registration-info" title="Example TD with Registration Info">
<pre>
{
"@context": [
"https://www.w3.org/2019/wot/td/v1",
"https://w3c.github.io/wot-discovery/context/discovery-context.jsonld"
],
"id": "urn:example:simple-td",
"security": "basic_sc",
"securityDefinitions": {
"basic_sc": {
"scheme": "basic"
}
},
"tdd:registration": {
"tdd:created": "2021-01-19T17:02:00Z",
"tdd:id": "urn:example:simple-td",
"tdd:modified": "2021-01-19T17:02:00Z"
},
"title": "Simple TD"
}
</pre>
</aside>
</section>
<section id="exploration-directory-api-registration-update" class="normative">
<h4>Update</h4>
<p>
<span class="rfc2119-assertion" id="tdd-reg-update-types">
The API MUST allow modifications to an existing TD as full replacement or partial updates.
</span>
The update operations are described below:
</p>
<ul>
<li>
<span class="rfc2119-assertion" id="tdd-reg-update">
A modified TD MUST replace an existing one when submitted using an HTTP `PUT` request
to the location corresponding to the existing TD.
</span>
<span class="rfc2119-assertion" id="tdd-reg-update-contenttype">
The request SHOULD contain `application/td+json` Content-Type header for JSON
serialization of TD.
</span>
The TD object must be validated in accordance with [[[#validation]]].
<span class="rfc2119-assertion" id="tdd-reg-update-resp">
Upon success, the server MUST respond with 204 (No Content) status.
</span>
This operation is specified as `updateTD` property in
[[[#directory-thing-description]]].
<p>
Note: If the target location does not correspond to an existing TD,
the request shall instead proceed as a Create operation and respond
the appropriate status code (see Create section). In other words, an HTTP `PUT`
request acts as a create or update operation.
</p>
</li>
<li>
<span class="rfc2119-assertion" id="tdd-reg-update-partial">
An existing TD MUST be partially modified when the modified parts are submitted using an
HTTP `PATCH` request to the location corresponding to the existing TD.
</span>
<span class="rfc2119-assertion" id="tdd-reg-update-partial-mergepatch">
The partial update MUST be processed using the JSON merge patch format
format described in [[RFC7396]].
</span>
<span class="rfc2119-assertion" id="tdd-reg-update-partial-contenttype">
The request MUST contain `application/merge-patch+json` Content-Type header for JSON
serialization of the merge patch document.
</span>
<span class="rfc2119-assertion" id="tdd-reg-update-partial-partialtd">
The input MUST be in <a>Partial TD</a> form and conform to the
original TD structure.
</span>
If the input contains members that appear in the original TD,
their values are replaced. If a member do not appear in the
original TD, that member is added. If the member is set to `null`
but appear in the original TD, that member is removed.
Members with object values are processed recursively.
After applying the modifications, the TD object must be validated in accordance with [[[#validation]]].
<span class="rfc2119-assertion" id="tdd-reg-update-partial-resp">
Upon success, the server MUST respond with a 204 (No Content) status.
</span>
This operation is specified as `updatePartialTD` property in
[[[#directory-thing-description]]].
</li>
</ul>
<p>
Error responses:
<ul>
<li>
400 (Bad Request): Invalid serialization or TD.
This is accompanied by an appropriate response message.
</li>
<li>
404 (Not Found): TD with the given `id` not found (for `PATCH` only).
</li>
<li>
401 (Unauthorized): Rejecting a request without appropriate authentication.
</li>
<li>
403 (Forbidden): Rejecting a request due to insufficient rights to the resource.
</li>
</ul>
</p>
</section>
<section id="exploration-directory-api-registration-deletion" class="normative">
<h4>Deletion</h4>
<p>
<span class="rfc2119-assertion" id="tdd-reg-delete">
A TD MUST be removed from the directory when an HTTP `DELETE` request
is submitted to the location corresponding to the existing TD.
</span>
<span class="rfc2119-assertion" id="tdd-reg-delete-resp">
A successful response MUST have 204 (No Content) status.
</span>
The retrieve operation is specified as `deleteTD` property in
[[[#directory-thing-description]]].
</p>
<p>
Error responses:
<ul>
<li>
404 (Not Found): TD with the given `id` not found.
</li>
<li>
401 (Unauthorized): No authentication.
</li>
<li>
403 (Forbidden): Insufficient rights to the resource.
</li>
</ul>
</p>
</section>
<section id="validation" class="normative">
<h4>Validation</h4>
<span class="rfc2119-assertion" id="td-validation-syntactic">
The syntactic validation of TD objects before storage is RECOMMENDED to
prevent common erroneous submissions.
</span>
<span class="rfc2119-assertion" id="td-validation-jsonschema">
The server MAY use
<a href="https://www.w3.org/TR/wot-thing-description/#json-schema-for-validation">Thing Description JSON Schema</a>
to validate standard TD vocabulary, or a more comprehensive JSON Schema to also validate extensions.
</span>
<span class="rfc2119-assertion" id="td-validation-result">
If the server fails to validate the TD object, it MUST inform the client
with necessary details to identify and resolve the errors.
</span>
<p class="ednote" title="Validation Example">
It would be nice to include an example validation result in
the uniform error format (i.e. RFC7807 Problem Details).