forked from w3c/wot-binding-templates
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathindex.html
1471 lines (1373 loc) · 68.4 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" xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>Web of Things (WoT) Binding Templates</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove" defer></script>
<script class="remove">
var respecConfig = {
specStatus: "ED",
processVersion: 2017,
shortName: "wot-binding-templates",
copyrightStart: 2017,
group: "wg/wot",
noRecTrack: true,
wgPublicList: "public-wot-wg",
edDraftURI: "https://w3c.github.io/wot-binding-templates/",
githubAPI: "https://api.github.com/repos/w3c/wot-binding-templates",
issueBase: "https://www.github.com/w3c/wot-binding-templates/issues",
editors: [{
name: "Michael Koster",
w3cid: "110658",
company: "SmartThings",
companyURL: "https://www.smartthings.com/"
},
{
name: "Ege Korkan",
w3cid: "110131",
company: "Siemens AG",
companyURL: "https://www.siemens.com/"
}
],
otherLinks: [{
key: "Contributors",
data: [{
value: "In the GitHub repository",
href: "https://github.com/w3c/wot-binding-templates/graphs/contributors"
}]
}, {
key: "Repository",
data: [{
value: "We are on GitHub",
href: "https://github.com/w3c/wot-binding-templates/"
}, {
value: "File a bug",
href: "https://github.com/w3c/wot-binding-templates/issues"
}]
}],
localBiblio: {
"CoRE-RD": {
href: "https://tools.ietf.org/html/draft-ietf-core-resource-directory-11",
title: "CoRE Resource Directory",
status: "Internet-Draft",
publisher: "IETF",
date: "03 July 2017"
},
"wot-security-guidelines": {
href: "https://w3c.github.io/wot-security/",
title: "Web of Things (WoT) Security and Privacy Guidelines",
status: "W3C Editor's Draft",
publisher: "W3C",
date: "21 August 2019"
},
"iana-web-socket-registry": {
href: "https://www.iana.org/assignments/websocket/websocket.xml#subprotocol-name",
title: "IANA Registry for Websocket Subprotocols",
status: "",
publisher: "IANA",
date: "24 May 2019"
},
"iana-uri-schemes": {
href: "https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml",
title: "Uniform Resource Identifier (URI) Schemes",
status: "",
publisher: "IANA",
date: "21 July 2021"
},
"MQTT": {
href: "https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html",
title: "MQTT Version 5.0",
status: "",
publisher: "MQTT",
date: "07 March 2019",
authors: [
"Andrew Banks", "Ed Briggs", "Ken Borgendale", "Rahul Gupta"
]
},
"LWM2M": {
href: "https://www.omaspecworks.org/what-is-oma-specworks/iot/lightweight-m2m-lwm2m/",
title: "Lightweight M2M",
status: "",
publisher: "Open Mobility Alliance"
},
"OCF": {
href: "https://openconnectivity.org/developer/specifications/",
title: "OCF Specification",
publisher: "Open Connectivity Foundation",
date: "Last accessed: February 2020"
},
"Modbus": {
href: "https://modbus.org/specs.php",
title: "MODBUS APPLICATION PROTOCOL SPECIFICATION",
publisher: "Modbus Organization",
status: "",
date: "26 April 2012"
}
}
};
</script>
</head>
<body>
<section id="abstract">
<p>
W3C Web of Things enables applications to interact with and orchestrate connected Things at the Web scale.
The standardized abstract interaction model exposed by the WoT Thing Description enables applications to
scale and evolve independently of the individual Things.
</p>
<p>
Many network-level protocols, standards and platforms for connected Things have already been developed, and
have millions of devices deployed in the field today. These standards are converging on a common set of
transport
protocols and transfer layers, but each has peculiar content formats, payload schemas, and data types.
</p>
<p>
Despite using unique formats and data models, the high-level interactions exposed by most connected things
can be modeled using the Property, Action, and Event interaction affordances of the WoT Thing Description.
</p>
<p>
Binding Templates enable a Thing Description to be adapted to a specific protocol, data payload formats or
platforms that combine both in specific ways.
This is done through additional descriptive vocabularies, Thing Models and examples that aim to guide the
implementors of Things and Consumers alike.
</p>
<p>
This document acts as the base and explains how other binding templates should be designed.
Concrete binding templates are then provided in their respective documents that are linked to
from this document.
</p>
</section>
<section id="sotd">
<p class="ednote" title="The W3C WoT WG is asking for feedback">
Please contribute to this draft using the
<a href="https://github.com/w3c/wot-binding-templates/issues">GitHub Issue</a>
feature of the <a href="https://github.com/w3c/wot-binding-templates/">
WoT Binding Templates</a> repository.
For feedback on security and privacy considerations, please use the
<a href="https://github.com/w3c/wot-security/issues">WoT Security and Privacy</a>
Issues, as they are cross-cutting over all our documents.
</p>
</section>
<section id="introduction">
<h1>Introduction</h1>
<p>
Binding Templates consist of multiple specifications, referred to as a subspecification in this document,
that enable an application client (a Consumer) to interact,
using WoT Thing Description[[WOT-THING-DESCRIPTION] (TD), with Things that exhibit diverse protocols,
payload formats and their usage.
These subspecifications are categorized into three:
<ul>
<li> <a href="#protocol-intro"></a>: Application layer protocols (e.g., HTTP[[?RFC7231]], CoAP[[?RFC7252]],
MQTT[[?MQTT]], etc.) whose different message types are mapped to the WoT Thing
Description[[WOT-THING-DESCRIPTION]] via reusable vocabulary and extensions.</li>
<li> <a href="#payloads-intro"></a>: Different payload formats and media types [[IANA-MEDIA-TYPES]] which
can be represented in a TD.</li>
<li> <a href="#platforms-intro"></a>: Platforms and frameworks who combine the use of protocols and payloads
in a certain way.</li>
</ul>
</p>
<p>
Each subspecification is an independent document that has separate list of authors and publication dates.
This document explains what each subspecification should contain given their respective category and also
links to the respective specification.
</p>
</section>
<section id="conformance">
</section>
<section id="terminology" class="informative">
<h2>Terminology</h2>
<p>The fundamental WoT terminology such as
<dfn class="lint-ignore">Thing</dfn>,
<dfn class="lint-ignore">Consumer</dfn>,
<dfn class="lint-ignore">Thing Description</dfn> (<dfn class="lint-ignore">TD</dfn>),
<dfn class="lint-ignore">Interaction Model</dfn>,
<dfn class="lint-ignore">Interaction Affordance</dfn>,
<dfn class="lint-ignore">Property</dfn>,
<dfn class="lint-ignore">Action</dfn>,
<dfn class="lint-ignore">Event</dfn>,
<dfn class="lint-ignore">Protocol Binding</dfn>,
<dfn class="lint-ignore">Servient</dfn>,
<dfn class="lint-ignore">Vocabulary</dfn>,
<dfn class="lint-ignore">WoT Interface</dfn>,
<dfn class="lint-ignore">WoT Runtime</dfn>,
etc. is defined in <a href="https://w3c.github.io/wot-architecture/#terminology">Section 3</a>
of the WoT Architecture specification [[WOT-ARCHITECTURE]].
</p>
</section>
<section id="binding-overview">
<h1>Binding Templates Overview</h1>
<p>
This section describes the mechanisms of binding templates for protocols, payload formats and platforms.
Each subsection lists the idea behind the category of the binding, the currently existing bindings
and requirements for new bindings.
</p>
<section id="protocol-intro">
<h3>Protocols</h3>
<p>
Most protocols have a relatively small set of methods that define the message type, the semantic
intention of the message.
REST and PubSub architecture patterns result in different protocols with different methods.
Common methods found in these protocols are GET, PUT, POST, DELETE, PUBLISH, and SUBSCRIBE.
Binding Templates describe how these existing methods and vocabularies can be described in a Thing
Description.
</p>
<p>
This is done by defining the URI scheme of the protocol and mapping the protocol
methods to the abstract WoT operations such as <code>readproperty</code>, <code>invokeaction</code> and
<code>subscribeevent</code>.
</p>
<p>
The table below summarizes the currently specified protocols in their respective subspecification.
</p>
<table class="def">
<thead>
<tr>
<th>Abbreviation</th>
<th>Name</th>
<th>Link</th>
</tr>
</thead>
<tbody>
<tr>
<td>HTTP</td>
<td>Hypertext Transfer Protocol</td>
<td><a href="./bindings/protocols/http/index.html">Link</a></td>
</tr>
<tr>
<td>CoAP</td>
<td>Constrained Application Protocol</td>
<td><a href="./bindings/protocols/coap/index.html">Link</a></td>
</tr>
<tr>
<td>MQTT</td>
<td>Message Queuing Telemetry Transport</td>
<td><a href="./bindings/protocols/mqtt/index.html">Link</a></td>
</tr>
<tr>
<td>Modbus</td>
<td>Modbus</td>
<td><a href="./bindings/protocols/modbus/index.html">Link</a></td>
</tr>
</tbody>
</table>
<section>
<h4>Creating a new Protocol Binding</h4>
<p>
When creating a new protocol binding subspecification, e.g. based on a new communication protocol,
the proposed document should enable implementations of this binding in an interoperable way for
Consumer and Producer implementations.
More specifically, each binding MUST specify the following:
</p>
<ul>
<li>
<b>URI Scheme:</b> For identification of the used protocol, a standardized URI scheme
[[RFC3986]] value MUST be declared in the form of a string. This URI Scheme is used in TDs at
top level <code>base</code> or in the <code>href</code> term of the <code>forms</code>
container. These can be officially registered ones at IANA [[iana-uri-schemes]] (e.g.
<code>"https://"</code>, <code>"coap://"</code>) or they can be declared in the protocol
subspecification (e.g. <code>"mqtt://"</code>, <code>"modbus+tcp://"</code>). How the full URI
can be constructed for different affordances (or resources) MUST be specified as well.
<li>
<b>Mapping to WoT Operations:</b> Most protocols have a set of methods or verbs that adds a
meaning to the messages of the protocol.
A protocol binding MUST be able to map WoT operation types (<code>readproperty</code>,
<code>invokeaction</code>, etc.) to concrete protocol message types or methods. When specifying
the mapping, the mapping SHOULD be bidirectional, i.e. it should be clear how to
do a <code>readproperty</code> operation with the given protocol and how an existing
implementation's endpoints can be mapped to a WoT operation should be also clear.
A vocabulary detailing the operations methods SHOULD be provided to allow semantic annotations
of the operations with protocol specific information.
</li>
<li>
<b>Specification:</b> The official specification document of the protocol SHOULD be
provided. This SHOULD be a static version, i.e. the exact document used during the writing of
the binding that is guaranteed to not change. If this is not possible, the specification
should be marked with a date of access. When the specification is not publicly available and
cannot be linked with a static version, an editor's note should be provided in the
introduction, explaining how to get access to the specification.
</li>
</ul>
<p>
A template is also provided for new protocol binding specifications at <a
href="https://github.com/w3c/wot-binding-templates/blob/main/bindings/index.template.html">the
GitHub Repository.</a>
</p>
</section>
<p class="ednote">
The rest of this chapter (4.1.2) is not restructured yet
</p>
</section>
<section id="payloads-intro">
<h3>Payload Representation</h3>
Various payloads sent in the messages of protocols can be described in TDs using two mechanisms:
<ul>
<li>
<b>Media Types:</b> Media Types [[IANA-MEDIA-TYPES]] describe the encoding used for sending and
receiving the data with a protocol.
They are represented with the <code>contentType</code> in the Forms of a TD, which is mandatory for
each Interaction Affordance.
In some cases such as images, videos or any unstructured data, they are enough to describe the
payload.
Correct indication of Media Types enables proper processing of the serialized documents.
This way, the documents can be exchanged in any format and allow the upper layers of an application
to adapt to different formats.
</li>
<li>
<b>Data Schema:</b> The TD specification defines the Data Schema concept to describe the structure
of the data payloads.
Even though it is largely inspired by JSON Schema [[json-schema]], it can be used for describing
other payload types such as [[XML]], string-encoded images, bit representations of integers, etc.
Data Schema SHOULD be used in addition to the media types.
</li>
</ul>
The table below summarizes the currently specified payload formats.
<table class="def">
<thead>
<tr>
<th>Abbreviation</th>
<th>Name</th>
<th>Media Type</th>
<th>Link</th>
</tr>
</thead>
<tbody>
<tr>
<td>JSON</td>
<td>JavaScript Object Notation</td>
<td><code>application/json</code></td>
<td>TODO</td>
</tr>
<tr>
<td>XML</td>
<td>eXtensible Markup Language</td>
<td><code>application/xml</code></td>
<td><a href="./bindings/payloads/xml/index.html">Link</a></td>
</tr>
<tr>
<td>text</td>
<td>text</td>
<td><code>text/plain</code></td>
<td>TODO</td>
</tr>
<tr>
<td>Unstructured Data</td>
<td>Unstructured Data</td>
<td>various</td>
<td>TODO</td>
</tr>
</tbody>
</table>
<section>
<h4>Creating a new Payload Format Binding</h4>
<p>
Each payload format binding document, SHOULD contain the respective media type.
Ideally this media type has been registered at the IANA registry [[IANA-MEDIA-TYPES]] with a
corresponding mime type (e.g. <code>application/json</code>).
If it is not registered, the binding document can propose a mime type. Additionally, how that media
type is represented
in a Data Schema SHOULD be demonstrated with examples.
In all cases, the following information SHOULD be provided:
<ul>
<li>
<b>Specification:</b> The official specification document of the payload format SHOULD be
provided. This SHOULD be a static version, i.e. the exact document used during the writing of
the binding that is guaranteed to not change. If this is not possible, the specification
should be marked with a date of access. When the specification is not publicly available and
cannot be linked with a static version, an editor's note should be provided in the
introduction, explaining how to get access to the specification.
</li>
</ul>
</p>
</section>
</section>
<section id="platforms-intro">
<h3>Platforms</h3>
<p>
There are already various IoT platforms on the market that allows exposing physical and virtual Things
to the Internet.
These platforms generally propose a certain API specification over a protocol and media type.
Thus, they can be seen as a combination of the <a href="#protocol-intro"></a> and <a href="#payloads-intro"></a>.
Platform subspecifications provide Thing Models and examples of TDs on how to integrate these
platforms in to the W3C Web of Things.
</p>
<p>
The table below summarizes the currently specified platforms.
</p>
<table class="def">
<thead>
<tr>
<th>Name</th>
<th>Link</th>
</tr>
</thead>
<tbody>
<tr>
<td>Philips Hue</td>
<td>TODO</td>
</tr>
<tr>
<td>ECHONET</td>
<td>TODO</td>
</tr>
<tr>
<td>OPC-UA</td>
<td>TODO</td>
</tr>
</tbody>
</table>
<section>
<h4>Creating a new Platform Binding</h4>
<p>
Depending on the platform and the variety of devices it proposes, each binding specification will be
structured differently.
When the platforms offer a <i>reasonable</i> set of device types, a Thing Model for each device type
SHOULD be provided.
In other cases, possible devices SHOULD be generalized by providing a set of example Thing Models or
TDs.
In all cases, the following information SHOULD be provided:
</p>
<ul>
<li>
<b>Protocol:</b> The protocol used by the platform SHOULD be specified and linked to a protocol
binding document when a corresponding one exists.
</li>
<li>
<b>Media Type:</b> The media type used by the platform SHOULD be specified and linked to a
payload binding document when a corresponding one exists.
</li>
<li>
<b>API Documentation:</b> A static link pointing to the used API Documentation or Specification
of the platform SHOULD be provided. When the documentation is not
publicly available and cannot be included in a static version in the respective folder, an
editor's note should be provided in the introduction, explaining how to
get access to the documentation.
</li>
</ul>
</section>
</section>
</section>
<section id="binding-examples" class="informative">
<h1>Examples of Thing Descriptions with Binding Templates</h1>
<p>
The following TD examples uses CoAP and MQTT Protocol Bindings.
These TD Context Extensions assume that there is a CoAP and MQTT in RDF vocabulary similar to
[[?HTTP-in-RDF10]] that is accessible via the namespace <code>http://www.example.org/coap-binding#</code>
and <code>http://www.example.org/mqtt-binding#</code>, respectively.
The supplemented <code>cov:methodName</code> member instructs the Consumer which CoAP method has to be
applied (e.g., <code>GET</code> for the CoAP Method Code 0.01, <code>POST</code> for the CoAP Method Code
0.02, or <code>iPATCH</code> for CoAP Method Code 0.07).
The supplemented <code>"mqv:controlPacketValue"</code> member instructs the Consumer which MQTT command has
to be applied (e.g., <code>8</code> for the subscribing and <code>10</code> for unsubscribing).
</p>
<p>
A TD with simple payload format and protocols can be seen below.
Here each interaction affordance has one form with one protocol.
</p>
<pre class="example" title="TD with a Simple Payload">
{
"@context": [
"https://www.w3.org/2019/wot/td/v1",
{
"iot": "http://iotschema.org/",
"cov": "http://www.example.org/coap-binding#",
"mqv": "http://www.example.org/mqtt-binding#"
}
],
"@type": [ "Thing", "iot:Light", "iot:LevelCapability", "iot:BinarySwitchCapability" ],
"base": "http://example.com",
"title": "Lamp",
"id": "urn:dev:ops:32473-WoTLamp-1234",
"securityDefinitions": {"basic_sc": {
"scheme": "basic",
"in": "header"
}},
"security": ["basic_sc"],
"properties": {
"switchState": {
"@type": ["iot:SwitchStatus", "iot:SwitchData"],
"type": "boolean",
"writeOnly": false,
"readOnly": false,
"observable": false,
"forms": [
{
"href": "/example/light/currentswitch",
"op": ["readproperty", "writeproperty"],
"contentType": "application/json"
}
]
},
"brightness": {
"@type": ["iot:CurrentLevel", "iot:LevelData"],
"type": "number",
"writeOnly": false,
"readOnly": false,
"observable": false,
"forms": [
{
"href": "coap://example.com/example/light/currentdimmer",
"op": ["readproperty", "writeproperty"],
"contentType": "application/json"
}
]
}
},
"actions": {
"switchOn": {
"@type": ["iot:SwitchOnAction"],
"input": {
"type": "boolean",
"const": true
},
"forms": [
{
"href": "/example/light/currentswitch",
"op": ["invokeaction"],
"contentType": "application/json"
}
]
},
"switchOff": {
"@type": ["iot:SwitchOff"],
"input": {
"type": "boolean",
"const": false
},
"forms": [
{
"href": "/example/light/currentswitch",
"op": ["invokeaction"],
"contentType": "application/json"
}
]
},
"setBrightness": {
"@type": ["iot:SetLevelAction"],
"input": {
"@type": ["iot:LevelData"],
"type": "number"
},
"forms": [
{
"href": "/example/light/currentdimmer",
"op": ["invokeaction"],
"contentType": "application/json"
}
]
}
}
}
</pre>
<p>
Another version of the previous TD with complex payload and multiple protocol options is shown below.
Notably, the <code>brightness</code> property can be read via HTTP, written to via CoAP and observed via
MQTT.
</p>
<pre class="example" title="TD with protocol options and complex payload">
{
"@context": [
"https://www.w3.org/2019/wot/td/v1",
{
"iot": "http://iotschema.org/",
"cov": "http://www.example.org/coap-binding#",
"mqv": "http://www.example.org/mqtt-binding#"
}
],
"base": "http://example.com/",
"@type": [ "Thing", "iot:Light", "iot:LevelCapability", "iot:BinarySwitch" ],
"title": "Lamp",
"id": "urn:dev:ops:32473-WoTLamp-1234",
"securityDefinitions": {"basic_sc": {
"scheme": "basic",
"in": "header"
}},
"security": ["basic_sc"],
"properties": {
"switchState": {
"@type": ["iot:SwitchStatus"],
"type": "object",
"properties": {
"switch": {
"@type": ["iot:SwitchData"],
"type": "boolean"
}
},
"writeOnly": false,
"readOnly": false,
"observable": true,
"forms": [
{
"href": "/example/light/currentswitch",
"contentType": "application/json",
"op": ["readproperty"],
"htv:methodName": "GET"
},
{
"href": "/example/light/currentswitch",
"contentType": "application/json",
"op": ["writeproperty"],
"htv:methodName": "POST"
},
{
"href": "mqtt://example.com/example/light/currentswitch",
"op": ["observeproperty"],
"mqv:controlPacketValue": "SUBSCRIBE"
}
]
},
"brightness": {
"@type": ["iot:CurrentLevel"],
"type": "object",
"properties": {
"brightness": {
"@type": ["iot:LevelData" ],
"type": "integer",
"minimum": 0,
"maximum": 255
}
},
"writeOnly": false,
"readOnly": false,
"observable": true,
"forms": [
{
"href": "coap://example.com/example/light/currentdimmer",
"contentType": "application/json",
"op": ["readproperty"],
"cov:methodName": "GET"
},
{
"href": "/example/light/currentdimmer",
"contentType": "application/json",
"op": ["writeproperty"],
"htv:methodName": "POST"
},
{
"href": "mqtt://example.com/example/light/currentdimmer",
"op": ["observeproperty"],
"mqv:controlPacketValue": "SUBSCRIBE"
}
]
},
"transitionTime": {
"@type": ["iot:TransitionTime"],
"type": "object",
"properties": {
"transitionTime": {
"@type": ["iot:TransitionTimeData" ],
"type": "integer",
"minimum": 0,
"maximum": 255
}
},
"writeOnly": false,
"readOnly": false,
"observable": false,
"forms": [
{
"href": "/example/light/transitiontime",
"contentType": "application/json",
"op": ["readproperty"],
"htv:methodName": "GET"
},
{
"href": "/example/light/transitiontime",
"contentType": "application/json",
"op": ["writeproperty"],
"htv:methodName": "POST"
}
]
}
},
"actions": {
"switchOn": {
"@type": ["iot:SwitchOnAction"],
"input": {
"type": "boolean",
"const": true
},
"forms": [
{
"href": "/example/light/currentswitch",
"contentType": "application/json",
"op": ["invokeaction"],
"htv:methodName": "POST"
}
]
},
"switchOff": {
"@type": ["iot:SwitchOffAction"],
"input": {
"type": "boolean",
"const": false
},
"forms": [
{
"href": "/example/light/currentswitch",
"contentType": "application/json",
"op": ["invokeaction"],
"htv:methodName": "POST"
}
]
},
"setBrightness": {
"title": "Set Brightness Level",
"@type": ["iot:SetLevelAction"],
"input": {
"type": "object",
"properties": {
"brightness": {
"@type": ["iot:LevelData"],
"type": "integer",
"minimum": 0,
"maximum": 255
}
},
"transitionTime": {
"@type": ["iot:TransitionTimeData"],
"type": "integer",
"minimum": 0,
"maximum": 65535
}
},
"forms": [
{
"href": "/example/light/",
"contentType": "application/json",
"op": ["invokeaction"],
"htv:methodName": "POST"
}
]
}
}
}
</pre>
</section>
<section id="sec-security-considerations">
<h1>Security and Privacy Considerations</h1>
<p class="ednote">
Security and privacy considerations are still under discussion and development; the content below should be
considered preliminary.
Due to the complexity of the subject we are considering producing a separate document containing a detailed security and privacy considerations
discussion including a risk analysis, threat model, recommended mitigations, and appropriate references to
best practices.
A summary will be included here. Work in progress is located in the
<a href="https://github.com/w3c/wot-security/">WoT Security and Privacy</a> repository.
Please file any security or privacy considerations and/or concerns using the <a
href="https://github.com/w3c/wot-security/issues">GitHub Issue</a> feature.
</p>
<p>
Security is a cross-cutting issue that needs to be taken into account in all WoT building blocks.
The W3C WoT does not define any new security mechanisms, but provides guidelines to apply the best
practices from Web security, IoT security, and information security for general software and hardware
considerations.
</p>
<p>
The <a
href="https://w3c.github.io/wot-architecture/#dfn-wot-thing-description">WoT
Thing Description</a> must be used together with integrity protection mechanisms and access control
policies.
Users must ensure that no sensitive information is included in the <a
href="https://w3c.github.io/wot-architecture/#dfn-td">TDs</a>
themselves.
</p>
<p>
The <a
href="https://w3c.github.io/wot-architecture/#dfn-wot-binding-templates">WoT
Binding Templates</a> must correctly cover the security mechanisms employed by the underlying <a
href="https://w3c.github.io/wot-architecture/#dfn-iot-platform">IoT
platform</a>.
Due to the automation of network interactions necessary in the IoT, operators need to ensure that <a
href="https://w3c.github.io/wot-architecture/#dfn-thing">Things</a>
are exposed and consumed in a way that is compliant with their security policies.
</p>
<p>
The <a href="https://w3c.github.io/wot-architecture/#dfn-wot-runtime">
WoT Runtime</a> implementation for the
<a href="https://w3c.github.io/wot-architecture/#dfn-wot-scripting-api">WoT
Scripting API</a> must have mechanisms to prevent malicious access to the system and isolate scripts in
multi-tenant <a
href="https://w3c.github.io/wot-architecture/#dfn-servient">Servients</a>.
</p>
</section>
<section id="sec-acknowledgements" class="appendix">
<h2>Acknowledgements</h2>
<p>
Special thanks to all active participants of the W3C Web of Things Interest Group and Working Group
for their technical input and suggestions that led to improvements to this document.
</p>
</section>
<section id="sec-orphaned">
<h2>Orphaned Sections</h2>
<p class="ednote">
The below chapters are copied from other places in this document. They require discussion on where to place
them, i.e. either here or another document of the working group, or to be completely removed.
</p>
<section id="form-element">
<h2>Forms Element</h2>
<p>
The form elements contain the URI [[RFC3986]] pointing to an instance of the interaction
and descriptions of the protocol settings and options expected to be used when
between the Consumer and the Thing for the interaction.
</p>
<section id="operation-types">
<h2>Operation Types</h2>
<p>
Form Operation Types describe the intended semantics of performing the operation
described by the form.
</p>
<p>
For example, the Property interaction allows read and write operations. The
protocol binding may contain a form for the read operation and a different
form for the write operation. The value of the <code>op</code> attribute of the form
indicates which form is which and allows the Consumer to select the correct
form for the operation required.
</p>
<pre class="example" title="Form Operation Types">
"op": "readproperty"
"op": "writeproperty"
</pre>
<p>
The vocabulary in section 4 lists the recommended set of form operations,
and the full TD examples in section 5 contain example uses of form operations types.
</p>
</section>
<section id="content-types">
<h2>Content Types</h2>
<p>
Content Types define the serialization details and other rules for processing the payloads.
The content type is used to select a serializer/deserializer and to select an additional set of
rules and constraints for the protocol driver.
Content type includes the media type and potential parameters for the media type.
</p>
<p>
For example, the media type <code>application/ocf+cbor</code> indicates that CBOR
serialization is used, but also that OCF rules and namespaces
apply to the processing of the representations.
</p>
<p>
Some special protocol drivers may be invoked by using a non-registered
media type (e.g., <code>x-<echonet></code>) along with a custom URI Scheme [[RFC3986]] and its
own set of protocol methods and options defined for that URI Scheme.
</p>
<p> When the media type is <code>application/xml</code> (or its binary representation
<code>application/exi</code>) and there is a Data Schema provided for the payload, the payloads are
constrained by a XML Schema derived from the Data Schema.
See <a href="bindings/payloads/xml/index.html" class="sec-ref"> XML Binding
</a> for how to derive a XML Schema from a Data Schema definition.
</p>
</section>
<section id="protocol-methods-options">
<h2>Protocol Methods and Options</h2>
<p>
Each target protocol may specify different method names for similar
operations, and there may be semantic differences between similar method names of
different protocols. Additionally, platforms may use different methods
for realizing a particular WoT Interaction Affordance. For example, POST may
be used for writing a Property value in one platform, while PUT may be
used in another. For these reasons, we require the ability to specify
which method to use for a particular Interaction. We also will provide
vocabulary to differentiate between methods of different protocols.
</p>
<p>
The W3C RDF vocabulary for HTTP [[HTTP-in-RDF10]] is used to identify the methods
and options specified in the HTTP protocol bindings.
</p>
<p>
For the sake of consistency, we will use the same ontology design pattern
to derive a vocabulary for each target protocol, e.g. CoAP, MQTT.
</p>
<p>
The example below shows some method definitions for various protocols.
</p>
<pre class="example" title="Vocabulary Example for Methods">
"htv:methodName": "GET"
"mqv:controlPacketValue": "SUBSCRIBE"
"cov:methodName": "GET"
</pre>
<p>
Header options in HTTP, CoAP, MQTT sometimes must be included in a protocol binding in order to
successfully interact with the underlying protocol. The example below shows the structure of
the definition for HTTP header options, according to the W3C HTTP Vocabulary in RDF.
</p>
<pre class="example" title="HTTP Vocabulary Example for Header Options">
"htv:headers":
[
{
"htv:fieldName": "Accept",
"htv:fieldValue": "application/json"
},
{
"htv:fieldName": "Transfer-Encoding",
"htv:fieldValue": "chunked"
}
]
</pre>
<p>
Note: different forms in a binding may need different header constructions,
therefore the <code>htv:headers</code> construct is an extension of the TD "form" element.
</p>
<p>
Protocols may have defined sub-protocols that can be used for some interaction
types. For example, to receive asynchronous notifications using HTTP, some
servers may support long polling (<code>longpoll</code>), WebSub [[WebSub]]
(<code>websub</code>) and Server-Sent Events [[eventsource]] (<code>sse</code>).
The <code>subprotocol</code> item may be defined in a form instance to indicate the
use of one of these protocols, for example long polling with its special use of HTTP:
<pre class="example" title="subprotocol">
{
"op": "subscribeevent",
"href": "https://mylamp.example.com/overheating",
"subprotocol": "longpoll"
}
</pre>
</p>
</section>
</section>
<section>
<h3><code>subprotocol</code> Vocabulary</h3>
<p>
The <code>subprotocol</code> field is defined in [[!WOT-THING-DESCRIPTION]].
</p>
<p>
Currently, the supported values are <code>longpoll</code>, <code>websub</code> and <code>sse</code>
defined for HTTP. Subprotocols can be used for asynchronous event delivery or observing Properties.
</p>