Skip to content

Commit 5d70e76

Browse files
danielpeintnerdanielpeintner
authored
Merge pull request #289 from relu91/partialTD
Add definitions for partialTD
2 parents 76fc62a + 5b7b6c8 commit 5d70e76

File tree

1 file changed

+212
-8
lines changed

1 file changed

+212
-8
lines changed

‎index.html‎

Lines changed: 212 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,65 @@
9292
},
9393
};
9494
</script>
95+
<script>
96+
document.addEventListener("DOMContentLoaded", () => {
97+
// Add example button selection logic
98+
for (const button of document.querySelectorAll(".ds-selector-tabs .selectors button")) {
99+
button.onclick = () => {
100+
const ex = button.closest(".ds-selector-tabs");
101+
ex.querySelector("button.selected").classList.remove("selected");
102+
ex.querySelector(".selected").classList.remove("selected");
103+
button.classList.add('selected');
104+
ex.querySelector("." + button.dataset.selects).classList.add("selected");
105+
}
106+
}
107+
});
108+
</script>
109+
<style>
110+
/* example tab selection */
111+
.ds-selector-tabs {
112+
padding-bottom: 2em;
113+
}
114+
.ds-selector-tabs .selectors {
115+
padding: 0;
116+
border-bottom: 1px solid #ccc;
117+
height: 28px;
118+
}
119+
.ds-selector-tabs .selectors button {
120+
display: inline-block;
121+
min-width: 54px;
122+
text-align: center;
123+
font-size: 11px;
124+
font-weight: bold;
125+
height: 27px;
126+
padding: 0 8px;
127+
line-height: 27px;
128+
transition: all,0.218s;
129+
border-top-right-radius: 2px;
130+
border-top-left-radius: 2px;
131+
color: #666;
132+
border: 1px solid transparent;
133+
}
134+
.ds-selector-tabs .selectors button:first-child {
135+
margin-left: 2px;
136+
}
137+
.ds-selector-tabs .selectors button.selected {
138+
color: #202020 !important;
139+
border: 1px solid #ccc;
140+
border-bottom: 1px solid #fff !important;
141+
}
142+
.ds-selector-tabs .selectors button:hover {
143+
background-color: transparent;
144+
color: #202020;
145+
cursor: pointer;
146+
}
147+
.ds-selector-tabs pre:not(.preserve), .ds-selector-tabs table:not(.preserve) {
148+
display: none;
149+
}
150+
.ds-selector-tabs pre.selected, .ds-selector-tabs table.selected {
151+
display: block;
152+
}
153+
</style>
95154
</head>
96155
<body>
97156

@@ -369,7 +428,6 @@ <h2>The <dfn>ThingDescription</dfn> type</h2>
369428
</div>
370429
</section>
371430
</section>
372-
373431
<section data-dfn-for="WOT">
374432
<h2>The <dfn>WOT</dfn> namespace</dfn></h2>
375433
<p>
@@ -423,12 +481,20 @@ <h2>The <dfn>WOT</dfn> namespace</dfn></h2>
423481

424482
<section> <h3>The <dfn>produce()</dfn> method</h3>
425483
<pre class="idl">
484+
typedef object ExposedThingInit;
485+
426486
partial namespace WOT {
427-
Promise&lt;ExposedThing&gt; produce(ThingDescription td);
487+
Promise&lt;ExposedThing&gt; produce(ExposedThingInit init);
428488
};
429489
</pre>
430490
<div>
431-
Belongs to the <a>WoT Producer</a> conformance class. Expects a |td:ThingDescription| argument and returns a {{Promise}} that resolves with an {{ExposedThing}} object that extends {{ConsumedThing}} with a server interface, i.e. the ability to define request handlers. The method MUST run the following steps:
491+
Belongs to the <a>WoT Producer</a> conformance class. Expects a |init:ExposedThingInit| argument and returns a {{Promise}}
492+
that resolves with an {{ExposedThing}} object that extends {{ConsumedThing}} with a server interface,
493+
i.e. the ability to define request handlers. The |init:ExposedThingInit| object is an instance of the <a>ExposedThingInit</a> type.
494+
Specifically, an <a>ExposedThingInit</a> value is a dictionary used for the initialization of an <a>ExposedThing</a> and
495+
it represents a <a>Partial TD</a> as described in the [[!WOT-ARCHITECTURE]]. As such, it has the same
496+
structure of a <a>Thing Description</a> but it may omit some information.
497+
The method MUST run the following steps:
432498
<ol>
433499
<li>
434500
Return a {{Promise}} |promise:Promise| and execute the next steps <a>in parallel</a>.
@@ -437,13 +503,97 @@ <h2>The <dfn>WOT</dfn> namespace</dfn></h2>
437503
If invoking this method is not allowed for the current scripting context for security reasons, reject |promise| with a {{SecurityError}} and abort these steps.
438504
</li>
439505
<li>
440-
Let |thing:ExposedThing| be a new {{ExposedThing}} object constructed with |td|.
506+
Let |thing:ExposedThing| be a new {{ExposedThing}} object constructed with |init|.
441507
</li>
442508
<li>
443509
Resolve |promise| with |thing|.
444510
</li>
445511
</ol>
446512
</div>
513+
<section>
514+
<h3>Expand an ExposedThingInit</h3>
515+
To <dfn>expand an ExposedThingInit</dfn> given |init:ExposedThingInit| and obtain a valid |td:ThingDescription| as
516+
a result,
517+
run the following steps:
518+
<ol class="algorithm">
519+
<li>Run <a>validate an ExposedThingInit</a> on |init|. If that fails,
520+
[= exception/throw =] {{SyntaxError}} and abort these steps.</li>
521+
<li>Initialize and empty object called |td|</li>
522+
<li>
523+
For each property |key| in |init| copy |key| and value of |key| to |td| recursively.
524+
</li>
525+
<li>For each |scheme:SecurityScheme| defined in <code>securityDefinitions</code> check if it is supported by at least one <a>Protocol Binding</a>.
526+
If not remove scheme </li>
527+
<li>if the value of <code>security</code> is defined but it is not contained in <code>securityDefinitions</code> remove
528+
<code>security</code></li>
529+
<li>For each |affordance| run the following sub-steps:
530+
<ol>
531+
<li>For each |form:Form| defined in |affordance| execute:
532+
<ol>
533+
<li>if |form|'s |contentType:string| is not recognized by the runtime as valid remove |contentType:string| from |form|
534+
</li>
535+
<li>if |form|'s |href:URL| has an unknown schema remove |href| from |form|.</li>
536+
<li>if |form|'s |href:URL| is absolute and its <code>authority</code> it is not recognized by the runtime as a valid
537+
remove |href| from |form|. </li>
538+
<li>if |form|'s |href:URL| is already in use by other <a>ExposedThings</a> remove |href| from |form|.</li>
539+
</ol>
540+
</li>
541+
</ol>
542+
</li>
543+
<li>Search for missing required properties in |td| accordingly to
544+
<a href="https://www.w3.org/TR/2020/WD-wot-thing-description11-20201124/#json-schema-for-validation">TD JSON
545+
Schema</a>.
546+
<p class="ednote">The editors find this step vague. It will be improved or removed in the next iteration. </p>
547+
</li>
548+
<li>For each |missing| property run these sub-steps:
549+
<ol>
550+
<li>If |missing| is <code>title</code> generate a runtime unique name and assign to <code>title</code>.</li>
551+
<li>If |missing| is <code>@context</code> assign the latest supported Thing Description context URI.</li>
552+
<li>If |missing| is <code>instance</code> assign the string <code>1.0.0</code>.</li>
553+
<li>If |missing| is <code>forms</code> generate a list of <a>Forms</a> using the available <a>Protocol Bindings</a> and content types
554+
encoders. Then assign the obtained list to <code>forms</code>.</li>
555+
<li>If |missing| is <code>security</code> assign the label of the first supported <a>SecurityScheme</a> in <code>securityDefinitions</code> field.
556+
If no <a>SecurityScheme</a> is found generate a <a>NoSecurityScheme</a> called <code>nosec</code> and assing the string <code>nosec</code>
557+
to <code>security</code>.
558+
<p class="issue">The discussion about how to properly generate a value for <code>security</code> is still open.
559+
See issue <a href="https://github.com/w3c/wot-scripting-api/issues/299">#299</a> </p>
560+
</li>
561+
<li>If |missing| is <code>href</code> define |formStub| as the partial <a>Form</a> that does not have <code>href</code>. Generate a valid |url:URL| using the first <a>Protocol Binding</a>
562+
that satisfy the requirements of |formStub|. Assign |url| to <code>href</code>. If not <a>Protocol Binding</a> can be found remove |formStub| from |td|. </li>
563+
<li>Add |missing| to |td| with |value| as value</li>
564+
</ol>
565+
</li>
566+
<li>Run <a>validate a TD</a> on |td|. If that fails re-[= exception/throw =] the error and abort these steps</li>
567+
<li>Return |td|</li>
568+
</ol>
569+
</section>
570+
<section>
571+
<h3>Validating an ExposedThingInit</h3>
572+
To <dfn>validate an ExposedThingInit</dfn> given |init:ExposedThingInit|, run the following steps:
573+
<ol class="algorithm">
574+
<li>
575+
Parse <a href="https://www.w3.org/TR/2020/WD-wot-thing-description11-20201124/#json-schema-for-validation">TD JSON
576+
Schema</a>
577+
and load it in object called |exposedThingInitSchema:object|
578+
</li>
579+
<li>let |optional:Array| be a list containing the following strings: <code>title</code>, <code>@context</code>,
580+
<code>instance</code>, <code>forms</code>, <code>security</code>, and <code>href</code>. </li>
581+
<li>
582+
For each property and sub-property |key| in |exposedThingInitSchema| equals to <code>required</code> execute the following steps:
583+
<ol>
584+
<li>if |key| |value| is an <code>Array</code> then remove all its elements equal to the elements in |optional|</li>
585+
<li>if |key| |value| is a <code>string</code> then if |value| is equal to one of the elements in |optional| remove |key| from |exposedThingInitSchema|</li>
586+
</ol>
587+
</li>
588+
<li>Return the result of <a>validating an object with JSON Schema</a> given |init| and |exposedThingInitSchema|.
589+
<p class="ednote">The<dfn>validating an object with JSON Schema</dfn> steps are still under discussion.
590+
Currently this specification reference to the validation process of JSONSchema. Please
591+
follow this <a href="https://json-schema.org/draft/2019-09/json-schema-validation.html">document</a>
592+
when validating |init| with |exposedThingInitSchema|. Notice that the working group is evaluating an alternative formal approach.
593+
</p>
594+
</li>
595+
</ol>
596+
</section>
447597
</section>
448598

449599
<section> <h3>The <dfn>discover()</dfn> method</h3>
@@ -2112,12 +2262,13 @@ <h3>Constructing {{ExposedThing}}</h3>
21122262
Before invoking <a href="#dom-exposedthing-expose">expose()</a>, the {{ExposedThing}} object does not serve any requests. This allows first constructing {{ExposedThing}} and then initialize its <a>Properties</a> and service handlers before starting serving requests.
21132263
</p>
21142264
<div>
2115-
To construct an {{ExposedThing}} with the {{ThingDescription}}
2116-
|td:ThingDescription|, run the following steps:
2265+
To construct an {{ExposedThing}} with the {{ExposedThingInit}}
2266+
|init:ExposedThingInit|, run the following steps:
21172267
<ol>
21182268
<li>
21192269
If invoking this method is not allowed for the current scripting context for security reasons, [= exception/throw =] a {{SecurityError}} and abort these steps.
21202270
</li>
2271+
<li>Run the <a>expand an ExposedThingInit</a> steps on |init|. if that fails re-[= exception/throw =] the error and abort these steps. Otherwise store the obtained |td:ThingDescription| </li>
21212272
<li>
21222273
Run the <a>expand a TD</a> steps on |td|. If that fails, re-[= exception/throw =] the error and abort these steps.
21232274
</li>
@@ -3266,6 +3417,58 @@ <h2>ExposedThing Examples</h2>
32663417
console.log("Error creating ExposedThing: " + err);
32673418
}
32683419
</pre>
3420+
<p>
3421+
The following will cover a set of examples for the generation of a <a>Thing Description</a> from
3422+
an <a>ExposedThingInit</a> using <a>expand an ExposedThingInit</a> steps. As hypothesis the runtime
3423+
supports HTTP and COAP protocol bindings and it is hosted at 192.168.0.1.
3424+
</p>
3425+
<p>
3426+
The next example shows how to exploit a <a>ExposedThingInit</a> to create a simple <a>Thing Description</a>
3427+
with one <a>Property</a> with the default values.
3428+
</p>
3429+
<aside class="example ds-selector-tabs" title="Create a Thing Description with one Property afforndace">
3430+
<div class="selectors">
3431+
<button class="selected" data-selects="init">ExposedThingInit</button>
3432+
<button data-selects="td">ThingDescription</button>
3433+
</div>
3434+
3435+
<pre class="selected init" data-transform="updateExample" title="An instance of the ExposedThingInit type">
3436+
{
3437+
"properties" : {
3438+
"temperature":{}
3439+
}
3440+
}
3441+
</pre>
3442+
<pre class="td" data-transform="updateExample" >
3443+
{
3444+
"@context": [
3445+
"https://www.w3.org/2019/wot/td/v1"
3446+
],
3447+
"title": "Thing-123",
3448+
"securityDefinitions": {
3449+
"no_sec": {
3450+
"scheme": "nosec"
3451+
}
3452+
},
3453+
"security": "no_sec",
3454+
"properties": {
3455+
"temperature": {
3456+
"forms": [{
3457+
"href": "http://192.168.0.1:8080/properties/temperature",
3458+
"contentType": "application/json"
3459+
},
3460+
{
3461+
"href": "coap://192.168.0.1:9090/properties/temperature",
3462+
"contentType": "application/json"
3463+
}]
3464+
}
3465+
}
3466+
}
3467+
</pre>
3468+
</aside>
3469+
<p class="ednote">
3470+
TODO: add more examples where the <a>ExposedThingInit</a> contains suggested values that are replaced by the algorithm.
3471+
</p>
32693472
</section> <!-- ExposedThing Examples -->
32703473
</section> <!-- ExposedThing -->
32713474

@@ -3702,9 +3905,10 @@ <h3>Denial Of Service Security Risk</h3>
37023905

37033906
<section> <h2>Terminology and conventions</h2>
37043907
<p>
3705-
The generic WoT terminology is defined in [[!WOT-ARCHITECTURE]]: <dfn data-lt="Things">Thing</dfn>, <dfn data-lt="Thing Descriptions">Thing Description</dfn> (in short <dfn>TD</dfn>), <dfn>Web of Things</dfn> (in short <b><i>WoT</i></b>), <dfn>WoT Interface</dfn>, <dfn>Protocol Bindings</dfn>, <dfn>WoT Runtime</dfn>, <dfn data-lt="consume|consume a TD|consuming a TD">Consuming a Thing Description</dfn>, <dfn>Thing Directory</dfn>, <dfn data-lt="Properties">Property</dfn>, <dfn data-lt="Actions">Action</dfn>, <dfn data-lt="Events|WoT-Event">Event</dfn>,
3908+
The generic WoT terminology is defined in [[!WOT-ARCHITECTURE]]: <dfn data-lt="Things">Thing</dfn>, <dfn data-lt="Thing Descriptions">Thing Description</dfn> (in short <dfn>TD</dfn>), <dfn>Partial TD</dfn>, <dfn>Web of Things</dfn> (in short <b><i>WoT</i></b>), <dfn>WoT Interface</dfn>, <dfn>Protocol Bindings</dfn>, <dfn>WoT Runtime</dfn>, <dfn data-lt="consume|consume a TD|consuming a TD">Consuming a Thing Description</dfn>, <dfn>Thing Directory</dfn>, <dfn data-lt="Properties">Property</dfn>, <dfn data-lt="Actions">Action</dfn>, <dfn data-lt="Events|WoT-Event">Event</dfn>,
37063909
<a href="https://www.w3.org/TR/2020/WD-wot-thing-description11-20201124/#dataschema">
3707-
<dfn>DataSchema</dfn></a>, <a href="https://www.w3.org/TR/2020/WD-wot-thing-description11-20201124/#form"><dfn>Form</dfn></a> etc.
3910+
<dfn>DataSchema</dfn></a>, <a href="https://www.w3.org/TR/2020/WD-wot-thing-description11-20201124/#form"><dfn data-lt="Forms">Form</dfn></a>,
3911+
<a href="https://w3c.github.io/wot-thing-description/#securityscheme"><dfn>SecurityScheme</dfn></a>, <a href="https://w3c.github.io/wot-thing-description/#nosecurityscheme"><dfn>NoSecurityScheme</dfn></a> etc.
37083912
</p>
37093913
<p>
37103914
<dfn data-plurals="WoT Interactions">WoT Interaction</dfn> is a synonym for <a href="https://www.w3.org/TR/2020/WD-wot-architcture11-20201124/#dfn-interaction-affordance"><dfn>Interaction Affordance</dfn></a>.

0 commit comments

Comments
 (0)