Skip to content

Commit 9249005

Browse files
zolkiszolkis
authored
Merge pull request #94 from zolkis/master
Use schema, inputSchema, outputSchema from updated TD spec. Add support for TD links.
2 parents 4db1b18 + 7631629 commit 9249005

File tree

1 file changed

+108
-42
lines changed

1 file changed

+108
-42
lines changed

‎index.html

Lines changed: 108 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,8 @@
173173
<li>Invoke an <a>Action</a>.</li>
174174
<li>Observe <a>Events</a> emitted by the <a>Thing</a>.</li>
175175
<li>Observe changes to the <a>Thing Description</a> of the <a>Thing</a>.</li>
176+
<li>Get the <a>Thing Description</a>.</li>
177+
<li>Get the list of linked resources based on the <a>Thing Description</a>.</li>
176178
</ul>
177179
</li>
178180
</ul>
@@ -306,6 +308,9 @@ <h4>The <dfn>ThingFilter</dfn> dictionary</h4>
306308
</li>
307309
</ul>
308310
</p>
311+
<p class="ednote">
312+
Constraints are experimental feature, implementations are not required to support them.
313+
</p>
309314
<p class="ednote">
310315
Semantic annotations need revisiting in order to simplify their representation. In the [[WOT-TD]] specification they represent the `@type` construct. At the moment only `@context`, `@type` and `@id` constructs are used in the <a>TD</a>.
311316
</p>
@@ -471,7 +476,7 @@ <h3>The <dfn>ThingTemplate</dfn> dictionary</h3>
471476
</pre>
472477
<pre class="example" title="Same as above but with different Observable syntax">
473478
let subscription = wot.discover({ method: "local" }).subscribe({
474-
next: thing => { console.log("Found local Thing " + thing.name); },
479+
thing => { console.log("Found local Thing " + thing.name); },
475480
error: err => { console.log("Discovery error: " + err.message); },
476481
complete: () => { console.log("Discovery finished successfully");}
477482
});
@@ -507,7 +512,6 @@ <h2>The <dfn>ConsumedThing</dfn> interface</h2>
507512
<pre class="idl">
508513
interface ConsumedThing {
509514
readonly attribute DOMString name;
510-
void setName(DOMString name);
511515
ThingDescription getThingDescription();
512516
Promise&lt;any&gt; invokeAction(DOMString name, any parameters);
513517
Promise&lt;void&gt; writeProperty(DOMString name, any value);
@@ -519,19 +523,13 @@ <h2>The <dfn>ConsumedThing</dfn> interface</h2>
519523
</pre>
520524
<p>
521525
<code>ConsumedThing</code> represents a local proxy object of the remote <a>Thing</a>.
522-
<ul>
523-
<li>
524-
The <dfn>name</dfn> read-only attribute represents the user given name of the <a>Thing</a>.
525-
</li>
526-
</ul>
527526
</p>
528527

529-
<section> <h3>The <dfn>setName()</dfn> method</h3>
528+
<section> <h3>The <dfn>name</dfn> property</h3>
530529
<p>
531-
Takes a <code>name</code> parameter and sets the name of the <a>Thing</a>, as used in applications. Applications can provide a maximum 128 bytes long name, but implementations may reject (by throwing a `RangeError`) or truncate the provided name, depending on the capabilities of the underlying platform. Setting <code>name</code> throws `TypeError` on other invalid (not string) input.
530+
The `name` property represents the name of the <a>Thing</a> as specified in the <a>TD</a>. In this version it is read only.
532531
</p>
533532
</section>
534-
535533
<section> <h3>The <dfn>getThingDescription()</dfn> method</h3>
536534
<p>
537535
Returns the <a>Thing Description</a> of the <a>Thing</a>.
@@ -592,7 +590,8 @@ <h2>Examples</h2>
592590
Below a <code><a>ConsumedThing</a></code> interface example is given.
593591
</p>
594592
<pre class="example" title="Consume a Thing">
595-
wot.fetch("http://mmyservice.org/mySensor").then(td => {
593+
try {
594+
let td = await wot.fetch("http://mmyservice.org/mySensor");
596595
let thing = wot.consume(td);
597596
console.log("Thing " + thing.name + " has been consumed.");
598597
let subscription = thing.onPropertyChange("temperature")
@@ -605,9 +604,9 @@ <h2>Examples</h2>
605604
console.log("Error starting measurement.");
606605
subscription.unsubscribe();
607606
})
608-
}).catch(error => {
607+
} catch(error) {
609608
console.log("Error during fetch or consume: " + error.message);
610-
});
609+
};
611610
</pre>
612611
</section> <!-- Examples -->
613612
</section> <!-- ConsumedThing -->
@@ -630,11 +629,11 @@ <h2>The <dfn>ExposedThing</dfn> interface</h2>
630629
Promise&lt;void&gt; unregister(optional USVString directory);
631630
Promise&lt;void&gt; emitEvent(DOMString eventName, any payload);
632631
// define Thing Description modifiers
633-
ExposedThing addProperty(ThingPropertyInit property);
632+
ExposedThing addProperty(ThingProperty property);
634633
ExposedThing removeProperty(DOMString name);
635-
ExposedThing addAction(ThingActionInit action);
634+
ExposedThing addAction(ThingAction action);
636635
ExposedThing removeAction(DOMString name);
637-
ExposedThing addEvent(ThingEventInit event);
636+
ExposedThing addEvent(ThingEvent event);
638637
ExposedThing removeEvent(DOMString name);
639638
// define request handlers
640639
ExposedThing setActionHandler(ActionHandler action, optional DOMString actionName);
@@ -682,23 +681,23 @@ <h4>The <dfn>DataSchema</dfn> type</h4>
682681
typedef USVString DataSchema;
683682
</pre>
684683
<p>
685-
The <a>DataSchema</a> type represents a type name specified in the <a>Thing Description</a> in a serialized form, for instance JSON Schema.
684+
The <a>DataSchema</a> type represents a data type <a href="https://w3c.github.io/wot-thing-description/#dataschema">specified</a> in the <a>Thing Description</a> in a serialized form.
686685
</p>
687686
<p class="ednote">
688-
<a>DataSchema</a> is under development, currently it can denote any type supported by the <a>Thing Description</a> and the <a>WoT Runtime</a>, such as simple type like <code>"boolean"</code>, <code>"number"</code>, <code>"string"</code>, or <code>"array"</code>, or <code>"object"</code> that may specify value range etc.
687+
<a>DataSchema</a> is under development, currently it can denote any type supported by the <a>Thing Description</a> and the <a>WoT Runtime</a>.
689688
</p>
690689
</section>
691690

692691
<section> <h3>The <dfn>addProperty()</dfn> method</h3>
693692
<p>
694693
Adds a <a>Property</a> defined by the argument and updates the <a>Thing Description</a>. Throws on error. Returns a reference to the same object for supporting chaining.
695694
</p>
696-
<section data-dfn-for="ThingPropertyInit" data-link-for="ThingPropertyInit">
697-
<h4>The <dfn>ThingPropertyInit</dfn> dictionary</h4>
695+
<section data-dfn-for="ThingProperty" data-link-for="ThingProperty">
696+
<h4>The <dfn>ThingProperty</dfn> dictionary</h4>
698697
<pre class="idl">
699-
dictionary ThingPropertyInit: SemanticAnnotations {
698+
dictionary ThingProperty: SemanticAnnotations {
700699
required DOMString name;
701-
required DataSchema type;
700+
required DataSchema schema;
702701
any value;
703702
boolean writable = true;
704703
boolean observable = true;
@@ -709,7 +708,7 @@ <h4>The <dfn>ThingPropertyInit</dfn> dictionary</h4>
709708
<ul>
710709
<li>The <dfn>name</dfn> attribute represents the name of the <a>Property</a>.</li>
711710
<li>
712-
The <dfn>type</dfn> attribute represents the type for the <a>Property</a>.
711+
The <dfn>schema</dfn> attribute represents the data type for the <a>Property</a> described by <a>DataSchema</a>.
713712
</li>
714713
<li>The <dfn>value</dfn> attribute represents the value of the <a>Property</a>.</li>
715714
<li>
@@ -731,23 +730,23 @@ <h4>The <dfn>ThingPropertyInit</dfn> dictionary</h4>
731730

732731
<section> <h3>The <dfn>addAction()</dfn> method</h3>
733732
<p>
734-
Adds an <a>Action</a> to the <a>Thing</a> object as defined by the <code>action</code> argument of type <a>ThingActionInit</a> and updates the <a>Thing Description</a>. Throws on error. Returns a reference to the same object for supporting chaining.
733+
Adds an <a>Action</a> to the <a>Thing</a> object as defined by the <code>action</code> argument of type <a>ThingAction</a> and updates the <a>Thing Description</a>. Throws on error. Returns a reference to the same object for supporting chaining.
735734
</p>
736-
<section data-dfn-for="ThingActionInit">
737-
<h4>The <dfn>ThingActionInit</dfn> dictionary</h4>
735+
<section data-dfn-for="ThingAction">
736+
<h4>The <dfn>ThingAction</dfn> dictionary</h4>
738737
<pre class="idl">
739-
dictionary ThingActionInit: SemanticAnnotations {
738+
dictionary ThingAction: SemanticAnnotations {
740739
required DOMString name;
741-
DataSchema inputDataDescription;
742-
DataSchema outputDataDescription;
740+
DataSchema inputSchema;
741+
DataSchema outputSchema;
743742
};
744743
</pre>
745744
<p>
746-
The <a>ThingActionInit</a> dictionary describes the arguments and the return value.
745+
The <a>ThingAction</a> dictionary describes the arguments and the return value.
747746
<ul>
748747
<li>The <dfn>name</dfn> attribute provides the <a>Action</a> name.</li>
749-
<li>The <dfn>inputDataDescription</dfn> attribute provides the description of the input arguments (argument list is represented by an object). If missing, it means the action does not accept arguments.</li>
750-
<li>The <dfn>outputDataDescription</dfn> attribute provides the description of the returned data. If missing, it means the action does not return data.</li>
748+
<li>The <dfn>inputSchema</dfn> attribute provides the description of the input arguments (argument list is represented by an object). If missing, it means the action does not accept arguments.</li>
749+
<li>The <dfn>outputSchema</dfn> attribute provides the description of the returned data. If missing, it means the action does not return data.</li>
751750
</ul>
752751
</p>
753752
</section>
@@ -761,19 +760,19 @@ <h4>The <dfn>ThingActionInit</dfn> dictionary</h4>
761760

762761
<section> <h3>The <dfn>addEvent()</dfn> method</h3>
763762
<p>
764-
Adds an event to the <a>Thing</a> object as defined by the <code>event</code> argument of type <a>ThingEventInit</a> and updates the <a>Thing Description</a>. Throws on error. Returns a reference to the same object for supporting chaining.
763+
Adds an event to the <a>Thing</a> object as defined by the <code>event</code> argument of type <a>ThingEvent</a> and updates the <a>Thing Description</a>. Throws on error. Returns a reference to the same object for supporting chaining.
765764
</p>
766-
<section data-dfn-for="ThingEventInit">
767-
<h4>The <dfn>ThingEventInit</dfn> dictionary</h4>
765+
<section data-dfn-for="ThingEvent">
766+
<h4>The <dfn>ThingEvent</dfn> dictionary</h4>
768767
<pre class="idl">
769-
dictionary ThingEventInit: SemanticAnnotations {
768+
dictionary ThingEvent: SemanticAnnotations {
770769
required DOMString name;
771-
DataSchema dataDescription;
770+
DataSchema schema;
772771
};
773772
</pre>
774773
<ul>
775774
<li>The <dfn>name</dfn> attribute represents the event name.</li>
776-
<li>The <dfn>dataDescription</dfn> attribute represents the type of the data that is attached to the event. If missing, it means the event does not carry data.</li>
775+
<li>The <dfn>schema</dfn> attribute represents the type of the data that is attached to the event. If missing, it means the event does not carry data.</li>
777776
</ul>
778777
</section>
779778
</section>
@@ -854,13 +853,13 @@ <h2>Examples</h2>
854853
thing.addProperty({
855854
name: "temperature",
856855
value: "0",
857-
type: "number",
856+
schema: '{ \"type\": \"number\" }',
858857
writable: false
859858
// use default values for the rest
860859
});
861860
thing.addEvent({
862861
name: "onchange",
863-
dataDescription: "number"
862+
schema: '{ \"type\": \"number\" }'
864863
});
865864
thing.addAction({
866865
name: "reset",
@@ -896,8 +895,7 @@ <h2>Examples</h2>
896895
WoT.fetch("http://myservice.org/mySensor/description")
897896
.then(td => {
898897
let e_thing = WoT.produce(td);
899-
// properties, actions and events are added based on the TD
900-
console.log("created " + thing.name });
898+
// properties, actions and events have been added based on the TD
901899
// now add the requests handlers
902900
try {
903901
e_thing.setPropertyReadHandler(propertyName => {
@@ -937,6 +935,71 @@ <h2>Examples</h2>
937935
</section> <!-- ExposedThing Examples -->
938936
</section> <!-- ExposedThing -->
939937

938+
<section class="informative" data-dfn-for="ConsumedThing">
939+
<h2>Experimental extensions to the <strong>ConsumedThing</strong> interface</h2>
940+
<p>
941+
The <a>ThingDescription</a> related functionality, such as enumerating <a>Properties</a>, <a>Action</a>s, <a>Event</a>s and links (introspection) is an API extension that is out of scope for this specification. However, the draft interfaces are defined here for informative purposes.
942+
</p>
943+
<pre class="idl">
944+
partial interface ConsumedThing {
945+
sequence&lt;ThingProperty&gt; getProperties();
946+
sequence&lt;ThingAction&gt; getActions();
947+
sequence&lt;ThingEvent&gt; getEvents();
948+
sequence&lt;TDLink&gt; getLinks();
949+
};
950+
</pre>
951+
952+
<section> <h3>The <dfn>getProperties()</dfn> method</h3>
953+
<p>
954+
Returns the list of <a>Properties</a> defined in the <a>Thing Description</a> of the <a>Thing</a> in the form of a list of <a>ThingProperty</a> objects.
955+
</p>
956+
</section>
957+
958+
<section> <h3>The <dfn>getActions()</dfn> method</h3>
959+
<p>
960+
Returns the list of <a>Action</a>s defined in the <a>Thing Description</a> of the <a>Thing</a> in the form of a list of <a>ThingAction</a> objects.
961+
</p>
962+
</section>
963+
964+
<section> <h3>The <dfn>getEvents()</dfn> method</h3>
965+
<p>
966+
Returns the list of <a>Event</a>s defined in the <a>Thing Description</a> of the <a>Thing</a> in the form of a list of <a>ThingEvent</a> objects.
967+
</p>
968+
</section>
969+
970+
<section> <h3>The <dfn>getLinks()</dfn> method</h3>
971+
<p>
972+
Returns the list of linked resources in <a>Thing Description</a> of the <a>Thing</a> in the form of a list of <a>TDLink</a> objects.
973+
</p>
974+
<section data-dfn-for="TDLink" >
975+
<h4>The <dfn>TDLink</dfn> dictionary</h4>
976+
<p>
977+
Contains a hyperlink reference, a relation type and a media type.
978+
</p>
979+
<pre class="idl">
980+
dictionary TDLink {
981+
required USVString href;
982+
USVString mediaType;
983+
DOMString rel;
984+
};
985+
</pre>
986+
<p>The <a>TDLink</a> dictionary contains the following properties:
987+
<ul>
988+
<li>
989+
The <dfn>href</dfn> attribute represents a <a>hyperlink reference</a>.
990+
</li>
991+
<li>
992+
The <dfn>rel</dfn> attribute represents a <a>relation type</a>.
993+
</li>
994+
<li>
995+
The <dfn>mediaType</dfn> attribute represents a <a>IANA media type</a>. For <a>TD</a>s there will be registered media types, so applications will be able to check whether an `href` link points to a <a>TD</a>, i.e. whether the link is fetcheable with this API.
996+
</li>
997+
</ul>
998+
</p>
999+
</section> <!-- TDLink -->
1000+
</section>
1001+
</section>
1002+
9401003
<section data-dfn-for="Observable" class="informative">
9411004
<h2>Observables</h2>
9421005
<p>
@@ -1125,6 +1188,9 @@ <h3>The <dfn data-dfn-for="">Observable</dfn> interface</h3>
11251188
<dfn>IANA media type</dfn>s (formerly known as MIME types) are defined in
11261189
<a href="http://tools.ietf.org/html/rfc2046">RFC2046</a>.
11271190
</p>
1191+
<p>
1192+
The terms <dfn>hyperlink reference</dfn> and <dfn>relation type</dfn> are defined in [[!HTML5]] and <a href="https://tools.ietf.org/html/rfc8288">RFC8288</a>.
1193+
</p>
11281194
</section>
11291195

11301196
<section id="conformance">

0 commit comments

Comments
 (0)