From 7f22e43a1c8178a375984503908234d6ed5d1bdc Mon Sep 17 00:00:00 2001 From: Kazuyuki Ashimura Date: Thu, 14 Sep 2017 04:00:04 +0900 Subject: [PATCH 1/2] fix typos and broken link --- Overview.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Overview.html b/Overview.html index 8e9f54c0..590ee849 100644 --- a/Overview.html +++ b/Overview.html @@ -1434,7 +1434,7 @@

3.2 The 3.3 The expose() method

Returns a Promise of a locally created ExposedThing based on the provided - initialization paramaters. + initialization parameters.

Editor's note
@@ -1661,7 +1661,7 @@
4
Editor's note

- Action parameters could be also included, but it's debateble because privacy reasons. + Action parameters could be also included, but it's debatable because privacy reasons.

@@ -1683,7 +1683,7 @@

4. };

- The data attribute represents the changes that occured to the data attribute represents the changes that occurred to the Thing Description.

From c8c1b6528deef7717992e5381819313a551864da Mon Sep 17 00:00:00 2001 From: Kazuyuki Ashimura Date: Thu, 14 Sep 2017 07:41:29 +0900 Subject: [PATCH 2/2] add diff.html --- diff.html | 9758 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 9758 insertions(+) create mode 100644 diff.html diff --git a/diff.html b/diff.html new file mode 100644 index 00000000..c22818df --- /dev/null +++ b/diff.html @@ -0,0 +1,9758 @@ + + + + + + + + + + + Web of Things (WoT) Scripting API + + + + + + + + + + + + + + +
+

+Abstract +

+

+The + +Web +of +Things + +(WoT) +provides +layered +interoperability +between + +Things + +by +using +the + +WoT +Interface + +s. +

+

+This +specification +describes +a +programming +interface +representing +the + +WoT +Interface + +that +allows +scripts +run +on +a + +Thing + +to +discover +and +consume +(retrieve) +other + +Thing + +s +and +to +expose + +Things + +characterized +by +properties, + +Actions + +and + +Events +. +

+

+Scripting +is +an +optional +"convenience" +building +block +in +WoT +and +it +is +typically +used +in +gateways +that +are +able +to +run +a + +WoT +Runtime + +and + +script +management +, +providing +a +convenient +way +to +extend +WoT +support +to +new +types +of +endpoints +and +implement +WoT +applications +like + +Thing +Directory +. +

+
+
+

+Status +of +This +Document +

+

+ +This +section +describes +the +status +of +this +document +at +the +time +of +its +publication. +Other +documents +may +supersede +this +document. +A +list +of +current + +W3C + +publications +and +the +latest +revision +of +this +technical +report +can +be +found +in +the + + +W3C + +technical +reports +index + +at +https://www.w3.org/TR/. + +

+

+Implementers +need +to +be +aware +that +this +specification +is +considered +unstable. +Vendors +interested +in +implementing +this +specification +before +it +eventually +reaches +the +Candidate +Recommendation +phase +should +subscribe +to +the + +repository + +and +take +part +in +the +discussions. +

+
+
+ +Editor's +note + +: +The +W3C +WoT +WG +is +asking +for +feedback + +
+

+Please +contribute +to +this +draft +using +the + +GitHub +Issue + +feature +of +the + +WoT +Scripting +API + +repository. +For +feedback +on +security +and +privacy +considerations, +please +use +the + +WoT +Security +and +Privacy + +Issues. +

+
+

+This +document +was +published +by +the + +Web +of +Things +Working +Group + +as +an +Editor's + +a +First +Public +Working + +Draft. +This +document +is +intended +to +become +a + +W3C + +Recommendation. +

+Comments +regarding +this +document +are +welcome. +Please +send +them +to + +public-wot-wg@w3.org + +( + +subscribe +, + +archives + +). +

+

+Publication +as +an +Editor's + +a +First +Public +Working + +Draft +does +not +imply +endorsement +by +the + +W3C + +Membership. +This +is +a +draft +document +and +may +be +updated, +replaced +or +obsoleted +by +other +documents +at +any +time. +It +is +inappropriate +to +cite +this +document +as +other +than +work +in +progress. +

+

+This +document +was +produced +by +a +group +operating +under +the + +5 +February +2004 + +W3C + +Patent +Policy +. + +W3C + +maintains +a + +public +list +of +any +patent +disclosures + +made +in +connection +with +the +deliverables +of +the +group; +that +page +also +includes +instructions +for +disclosing +a +patent. +An +individual +who +has +actual +knowledge +of +a +patent +which +the +individual +believes +contains + +Essential +Claim(s) + +must +disclose +the +information +in +accordance +with + +section +6 +of +the + +W3C + +Patent +Policy +. +

+

+This +document +is +governed +by +the + +1 +March +2017 + +W3C + +Process +Document +. +

+
+ +
+

+ +1. + +Introduction +

+

+The +overall +WoT +concepts +are +described +in +the + +WoT +Architecture + +document. +The +Web +of +Things +is +made +of +entities +( + +Thing + +s) +that +can +describe +their +capabilities +in +a +machine-interpretable +format, +the + +Thing +Description + +(TD) +and +expose +these +capabilities +through +the + +WoT +Interface +. +Support +for +scripting +is +optional +for +WoT +devices. +

+

+By + +consuming +a +TD +, +a +client + +Thing + +creates +a +runtime +resource +model +that +allows +accessing +the +properties, + +Actions + +and + +Events + +exposed +by +the +server + +Thing +. +

+

+Exposing +a + +Thing + +requires +defining +a + +Thing +Description + +and +instantiating +a +software +stack +needed +to +serve +requests +for +accessing +the +exposed +properties, + +Actions + +and + +Events +. +This +specification +describes +how +to +expose +and +consume + +Thing + +s +by +a +script. +

+
+
+ +Note + +
+

+Typically +scripts +are +meant +to +be +used +on +devices +able +to +provide +resources +(with +a + +WoT +interface + +) +for +managing +(installing, +updating, +running) +scripts, +such +as +bridges +or +gateways +that +expose +and +control +simpler +devices +as +WoT + +Thing + +s. +

+
+

+For +an +introduction +on +how +scripts +could +be +used +in + +Web +of +Things +, +check +the + +Primer + +document. +For +some +background +on +API +design +decisions +check +the + +Rationale + +document. +

+
+
+

+ +2. + +Use +Cases +

+

+ +This +section +is +non-normative. + +

+

+The +following +scripting +use +cases +are +covered +in +this +specification: +

+ +

+The +following +use +cases +are +being +considered +for +next +versions: +

+
    +
  • +Add, +remove +and +update +the +definition +of +a + +Property + +on +a +Thing +that +runs +in +the +same +the +WoT +Runtime. +
    • +
  • +Add, +remove +and +update +the +definition +of +an + +Action + +on +a +Thing +that +runs +in +the +same +the +WoT +Runtime. +
    • +
  • +Add, +remove +and +update +the +definition +of +an + +Event + +on +a +Thing +that +runs +in +the +same +the +WoT +Runtime. +
    • +
+
+
+

+ +3. + +The + + +WoT + + +object +

+

+The +WoT +object +is +the +main +API +entry +point +and +it +is +exposed +by +an +implementation +of +the + +WoT +Runtime +. +The + +WoT +object + +has +no +internal +state +and +provides +methods +for +discovering, +consuming +and +exposing +a + +Thing +. +

+
+
+ +Note + +
+

+Browser +implementations + +SHOULD + +use +a +namespace +object +such +as + +wot +, +and + +Node.js + +-like +runtimes + +MAY + +provide +the +API +object +through +the + + +require() + + +or + + +import + + +mechanism. +

+
+
+ 
interface WoT {
+    Observable<ConsumedThing> discover(optional ThingFilter filter);
+    Promise<ConsumedThing>    consume(USVString url);
+    Promise<ExposedThing>     expose(ThingInit init);
+};
+
+
+
+
+
+ +Editor's +note + +
+

+The +algorithms +for +the +WoT +methods +will +be +specified +later. +

+
+
+

+ +3.1 + +The + + +discover() + + +method +

+

+Starts +the +discovery +process +that +will +provide + + + +ConsumedThing + + + +objects +that +match +the +optional +argument + + + +ThingFilter + + +. +When +the +argument +is +not +provided, +starts +the +widest +discovery +the + +Thing +Description + +and + +Protocol +Bindings + +allow. +Returns +an + + +Observable + + +object +that +can +be +subscribed +and +unsubscribed +to. +

+
+

+ +3.1.1 + +The + + +ThingFilter + + +dictionary +

+

+The + + +ThingFilter + + +dictionary +that +represents +the +constraints +for +discovering + +Thing + +s +as +key-value +pairs. +

+
+ 
dictionary ThingFilter {
+    (DiscoveryType or DOMString) method = "any";
+    USVString                    url;
+    Dictionary                   description;
+};
+
+
+
+

+The + + +method + + +property +represents +the +discovery +type +that +should +be +used +in +the +discovery +process. +The +possible +values +are +defined +by +the + + + +DiscoveryMethod + + + +enumeration +that +can +be +extended +by +string +values +defined +by +solutions +(with +no +guarantee +of +interoperability). +

+

+The + + +url + + +property +represents +additional +information +for +the +discovery +method, +such +as +the +URL +of +the + +Thing +Directory + +server +to +be +used. +

+

+The + + +description + + +property +represents +additional +information +for +the +discovery +method +in +the +form +of +a +set +of +key-value +pairs, +as +defined +in +the + +Thing +Description +. +

+
+
+ +Editor's +note + +
+

+The + + +DiscoveryMethod + + +enumeration +can +be +extended +by +the + +Thing +Description + +with +values +that +are +not +specified +here. +This +extensibility +of + + +DiscoveryMethod + + +by +proprietary +or +private +methods +is +a +working +assumption +until +consensus +is +formed +and +may +be +removed +later. +

+
+
+
+ +Editor's +note + +
+

+The + + +ThingFilter + + +dictionary +may +be +extended +later +with +further +attributes. +

+
+
+
+

+ +3.1.2 + +The + + +DiscoveryMethod + + +enumeration +

+
+ 
enum DiscoveryMethod {
+    "any",
+    "local",
+    "nearby",
+    "directory",
+    "broadcast",
+    "other"
+};
+
+
+
+

+The + + +DiscoveryMethod + + +enumeration +represents +the +discovery +type +to +be +used: +

+
    +
  • +" + + +any + + +" +does +not +provide +any +restriction +
    • +
  • +" + + +local + + +" +for +discovering + +Thing + +s +defined +in +the +same +device +
    • +
  • +" + + +nearby + + +" +for +discovering + +Thing + +s +nearby +the +device, +e.g. +by +Bluetooth +or +NFC +
    • +
  • +" + + +directory + + +" +for +discovery +based +on +a +service +provided +by +a +directory +or +repository +of + +Thing + +s +
    • +
  • +" + + +broadcast + + +" +for +an +open +ended +discovery +based +on +sending +a +request +to +a +broadcast +address +
    • +
  • +" + + +other + + +" +for +a +proprietary +method +defined +by +the +solution. +
    • +
+
+
+
+

+ +3.2 + +The + + +consume() + + +method +

+

+Accepts +an + +url + +argument +and +returns +a + + +Promise + + +of +a + + +ConsumedThing + +. +

+
+
+

+ +3.3 + +The + + +expose() + + +method +

+

+Returns +a + + +Promise + + +of +a +locally +created + + +ExposedThing + + +based +on +the +provided +initialization +parameters. +

+
+
+ +Editor's +note + +
+

+The +reason + + +ExposedThing + + +s +are +created +by +a +factory +method +instead +of +a +constructor +is +that +an + + +ExposedThing + + +may +be +created +in +the +local + +WoT +Runtime + +or +in +a +remote +runtime. +Even +though +currently +only +local +creation +is +supported, +the +method +is +designed +with +this +possible +future +compatibility +in +mind. +

+
+
+

+ +3.3.1 + +The + + +ThingInit + + +dictionary +

+
+ 
dictionary ThingInit {
+    DOMString  name;
+    USVString  url;
+    Dictionary description;
+};
+
+
+
+

+The + + +ThingInit + + +dictionary +contains +properties +to +initialize +a + +Thing +: +

+
    +
  • +The + + +name + + +attribute +represents +the +user +given +name +of +the + +Thing +. +
    • +
  • +The + + +url + + +attribute +represents +the +address +of +the + +Thing +. +
    • +
  • +The + + +description + + +attribute +represents +the + +Thing +Description + +of +the + +Thing +. +
    • +
+
+
+
+

+ +3.4 + +Examples +

+
+
+ +Example +1 + +: +Discover +Things +via +directory + +
+ 
let discoveryType = { method: "directory", url: "http://directory.wotservice.org" };
+let subscription = wot.discover(discoveryType).subscribe(
+  thing => { console.log("Found Thing " + thing.url); },
+  error => { console.log("Discovery finished because an error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);
+setTimeout(
+  () => { subscription.unsubscribe(); console.log("Discovery timeout"); },
+
+5000
+
+);
+
+
+
+
+ +Note + +
+

+Note +that +canceling +a +discovery +(through +unsubscribe) +may +not +be +successful +in +all +cases, +for +instance +when +discovery +is +based +on +open +ended +broadcast +requests. +However, +once + +unsubscribe() + +has +been +called, +implementations + +MUST + +suppress +further +event +handling +( +i.e. +further +discoveries +and +errors) +on +the +Observable. +Also, +a +discovery +error +may +not +mean +the +end +of +the +discovery +process. +However, +in +order +to +respect +Observable +semantics +(error +always +terminates +processing), +implementations + +MUST + +close +or +suppress +further +event +handling +on +the +Observable. +

+
+
+
+ +Example +2 + +: +Discover +Things +exposed +by +local +hardware + +
+ 
let subscription = wot.discover({ method: "local" }).subscribe(
+  thing => { console.log("Found local Thing " + thing.url); },
+  error => { console.log("Discovery error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);
+
+
+
+
+ +Example +3 + +: +Discover +Things +exposed +nearby, +e.g. +via +Bluetooth + +
+ 
let subscription = wot.discover({ method: "nearby", description: {protocol: "BLE4.2"} }).subscribe(
+  thing => { console.log("Found nearby Thing " + thing.url); },
+  error => { console.log("Discovery error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);
+
+
+
+
+ +Example +4 + +: +Discover +Things +exposed +in +a +proprietary +way + +
+ 
let subscription = wot.discover({ method: "other", description: { solution: "XYZ123", key: "..."} }).subscribe(
+  thing => { console.log("Found Thing " + thing.url); },
+  error => { console.log("Discovery error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);
+
+
+
+
+
+

+ +4. + +The + + +ConsumedThing + + +interface +

+

+The + + +ConsumedThing + + +interface +is +a +client +API +for +sending +requests +to +servers +in +order +to +retrieve +or +update +properties, +invoke + +Actions +, +and +observe +properties, + +Actions + +and + +Events +. +

+
+ 
interface ConsumedThing {
+    readonly attribute DOMString        name;
+    readonly attribute USVString        url;
+    readonly attribute ThingDescription description;
+    Promise<any>  invokeAction(DOMString name, any parameters);
+    Promise<void> setProperty(DOMString name, any value);
+    Promise<any>  getProperty(DOMString name);
+    ConsumedThing addListener(DOMString eventName, ThingEventListener listener);
+    ConsumedThing removeListener(DOMString eventName,
+                                 ThingEventListener listener);
+    ConsumedThing removeAllListeners(optional DOMString eventName);
+    Observable    observe(DOMString name, RequestType requestType);
+};
+
+callback
+
+
+
+ThingEventListener
+
+
+
+=
+
+void
+
+(
+
+
+
+Event
+
+
+
+event
+
+
+);
+
+
+
+

+Represents +a +local +proxy +object +of +the +remote + +Thing +. +

+
    +
  • +The + + +name + + +read-only +attribute +represents +the +name +of +the + +Thing +. +
    • +
  • +The + + +url + + +read-only +attribute +represents +the +URL +of +the + +Thing +. +
    • +
  • +The + + +description + + +attribute +read-only +attribute +represents +the +description +of +the + +Thing +. +
    +
    + +Editor's +note + +
    +

    +Parsing +and +exposing + +Thing +Description + +s +is +discussed +in + +Issue +38 +. +

    +
    +
    • +
+
+

+ +4.1 + +The + + +invokeAction() + + +method +

+

+Takes +the + +Action + +name +from +the + +name + +argument +and +the +list +of +parameters, +then +requests +from +the +underlying +platform +and +the + +Protocol +Bindings + +to +invoke +the + +Action + +on +the +remote + +Thing + +and +return +the +result. +Returns +a + + +Promise + + +that +resolves +with +the +return +value +or +rejects +with +an + +Error +. +

+
+
+

+ +4.2 + +The + + +setProperty() + + +method +

+

+Takes +the + +Property + +name +as +the + +name + +argument +and +the +new +value +as +the + +value + +argument, +then +requests +from +the +underlying +platform +and +the + +Protocol +Bindings + +to +update +the + +Property + +on +the +remote + +Thing + +and +return +the +result. +Returns +a + + +Promise + + +that +resolves +on +success +or +rejects +with +an + +Error +. +

+
+
+

+ +4.3 + +The + + +getProperty() + + +method +

+

+Takes +the + +Property + +name +as +the + +name + +argument, +then +requests +from +the +underlying +platform +and +the + +Protocol +Bindings + +to +retrieve +the + +Property + +on +the +remote + +Thing + +and +return +the +result. +Returns +a + + +Promise + + +that +resolves +with +the + +Property + +value +or +rejects +with +an + +Error +. +

+
+
+

+ +4.4 + +The + + +addListener() + + +method +

+

+Adds +the +listener +provided +in +the +argument + +listener + +to +the + +Event + +name +provided +in +the +argument + +eventName +. +

+
+
+

+ +4.5 + +The + + +removeListener() + + +method +

+

+Removes +a +listener +from +the + +Event + +identified +by +the +provided + +eventName + +and + +listener + +argument. +

+
+
+

+ +4.6 + +The + + +removeAllListeners() + + +method +

+

+Removes +all +listeners +for +the + +Event + +provided +by +the + +eventName + +optional +argument, +or +if +that +was +not +provided, +then +removes +all +listeners +from +all + +Events +. +

+
+
+

+ +4.7 + +The + + +observe() + + +method +

+

+Returns +an + +Observable + +for +the + +Property +, + +Event + +or + +Action + +specified +in +the + +name + +argument, +allowing +subscribing +and +unsubscribing +to +notifications. +The + +requestType + +specifies +whether +a + +Property +, +an + +Event + +or +an + +Action + +is +observed. +

+
+
+ +Editor's +note + +
+

+The + +observe() + +method +could +replace + +addListener() + +and + +removeListener() +, +though +they +could +be +kept +for +convenience. +

+
+
+
+

+ +4.8 + +The + + +ThingEventListener + + +callback +

+

+A +function +called +with +an + +Event + +object +when +an +event +is +emitted. +

+
+
+

+ +4.9 + +Events +

+

+Clients +can +subscribe +to +the + +Events + +defined +in + +ExposedThing +events +. +The +event +types +are +described +in +this +section. +

+
+

+ +4.9.1 + +The + + +PropertyChangeEvent + + +interface +

+
+ 
[Constructor(PropertyChangeEventInit init)]
+interface PropertyChangeEvent : Event {
+    readonly attribute PropertyChangeEventInit data;
+};
+
+
+
+

+The + + +data + + +attribute +represents +the +changed + +Property +. +

+
+
+ +4.9.1.1 + +The + + +PropertyChangeEventInit + + +dictionary +
+
+ 
dictionary PropertyChangeEventInit {
+    DOMString name;
+    any       value;
+};
+
+
+
+

+The + + +name + + +> +attribute +represents +the + +Property + +name. +

+

+The + + +value + + +attribute +represents +the +new +value +of +the + +Property +. +

+
+
+
+

+ +4.9.2 + +The + + +ActionInvocationEvent + + +interface +

+
+ 
[Constructor(ActionInvocationEventInit init)]
+interface ActionInvocationEvent : Event {
+    readonly attribute ActionInvocationEventInit data;
+};
+
+
+
+

+The + + +data + + +attribute +represents +the +notification +data +from +the + +Action + +invocation. +

+
+
+ +4.9.2.1 + +The + + +ActionInvocationEventInit + + +dictionary +
+ +
+
+ +Editor's +note + +
+

+Action +parameters +could +be +also +included, +but +it's +debatable +because +privacy +reasons. +

+
+

+The + + +actionName + + +attribute +represents +the +name +of +the + +Action + +that +has +been +invoked. +

+

+The + + +returnValue + + +attribute +represents +the +return +value +of +the + +Action +. +

+
+
+
+

+ +4.9.3 + +The + + +ThingDescriptionChangeEvent + + +interface +

+ +

+The + + +data + + +attribute +represents +the +changes +that +occurred +to +the + +Thing +Description +. +

+
+
+ +4.9.3.1 + +The + + +ThingDescriptionChangeEventInit + + +dictionary +
+ +
    +
  • +The + + +type + + +attribute +represents +the +change +type, +whether +has +it +been +applied +on +properties, + +Actions + +or + +Events +. +
    • +
  • +The + + +method + + +attribute +tells +what +operation +has +been +applied, +addition, +removal +or +change. +
    • +
  • +The + + +name + + +attribute +represents +the +name +of +the + +Property +, + +Action + +or +event +that +has +changed. +
    • +
  • +The + + +description + + +attribute +is +defined +for +the +addition +and +change +methods, +and +represents +the +new +description. +
    • +
  • +The + + +data + + +attribute +provides +the +initialization +data +for +the +added +or +changed +elements. +
    • +
+
+
+ +4.9.3.1.1 + +The + + +TDChangeMethod + + +enumeration +
+
+ 
enum TDChangeMethod {
+    "add",
+    "remove",
+    "change"
+};
+
+
+
+ +
+
+
+ +4.9.3.1.2 + +The + + +TDChangeType + + +enumeration +
+ +
    +
  • +The + + +property + + +value +tells +the +operation +was +applied +on +a + +Property + +definition. +
    • +
  • +The + + +action + + +value +tells +the +operation +was +applied +on +a +action +definition. +
    • +
  • +The + + +event + + +value +tells +the +operation +was +applied +on +an +event +definition. +
    • +
+
+
+
+ +4.9.3.1.3 + +The + + +TDChangeData + + +type +
+

+Represents +the +new +description +of +the +changed +element. +Depending +on +the +change +type, +it +can +be +either +a + + +ThingPropertyInit + +, + + +ThingActionInit + +, +or + + +ThingEventInit + +. +

+
+
+
+
+
+

+ +4.10 + +Examples +

+

+Below +a + + + +ConsumedThing + + + +interface +example +is +given. +

+
+
+ +Example +5 + +: +Consume +a +Thing + +
+ 
wot.consume("http://mmyservice.org/mySensor").then( thing => {
+    console.log("Thing " + thing.name + " has been consumed.");
+    console.log("{ " + JSON.serialize(thing) + " }");
+    thing.addListener("onchange", function(event) {
+        if (event instanceof PropertyChangeEvent) {
+            console.log("Property " + event.name + " value has changed to " + event.value);
+        }
+    }).invokeAction("startMeasurement", ["Celsius"]);
+  },
+).catch(error => {
+  console.log("Discovery finished because an error: " + error.message);
+});
+
+
+
+
+
+

+ +5. + +The + + +ExposedThing + + +interface +

+

+The + + +ExposedThing + + +interface +is +the +server +API +that +allows +defining +request +handlers, +properties, + +Actions +, +and + +Events + +to +a + +Thing +. +

+
+ 
typedef USVString ThingDescription;
+callback RequestHandler = any (Request request);
+interface ExposedThing {
+    // define Thing Description modifiers
+    ExposedThing  addProperty(ThingPropertyInit property);
+    ExposedThing  removeProperty(DOMString name);
+    ExposedThing  addAction(ThingActionInit action);
+    ExposedThing  removeAction(DOMString name);
+    ExposedThing  addEvent(ThingEventInit event);
+    ExposedThing  removeEvent(DOMString name);
+    // define request handlers
+    ExposedThing  onRetrieveProperty(RequestHandler handler);
+    ExposedThing  onUpdateProperty(RequestHandler handler);
+    ExposedThing  onInvokeAction(RequestHandler handler);
+    ExposedThing  onObserve(RequestHandler handler);
+    // define how to expose and run the Thing
+    Promise<void> register(optional USVString directory);
+    Promise<void> unregister(optional USVString directory);
+    Promise<void> start();
+    Promise<void> stop();
+    Promise<void> emitEvent(DOMString eventName, any payload);
+};
+
+
+
+ExposedThing
+
+
+implements
+
+
+ConsumedThing
+
+
+;
+
+
+
+
+

+ +5.1 + +The + + +ThingDescription + + +type +

+

+WoT +provides +a +unified +representation +for +data +exchange +between + +Thing + +s, +standardized +in +the + +Wot +Things +Description + +specification. +

+
+
+ +Note + +
+

+In +this +version +of +the +API, + +Thing +Description + +s +are +represented +as +opaque +strings, +denoting +a +serialized +form, +for +instance +JSON +or +JSON-LD. +See + +Issue +38 + +and + +Issue +45 +. +Parsing +and +composing + +Thing +Description + +s +is +left +for +external +libraries +until +standardized +here. +

+
+
+
+

+ +5.2 + +The + + +Request + + +interface +

+
+ 
interface Request {
+    readonly attribute RequestType type;
+    readonly attribute USVString   from;
+    readonly attribute DOMString   name;
+    readonly attribute Dictionary  options;
+    readonly attribute any         data;
+    Promise respond(any response);
+    void    respondWithError(Error error);
+};
+
+
+
+

+Represents +an +incoming +request +the + + +ExposedThing + + +is +supposed +to +handle, +for +instance +retrieving +and +updating +properties, +invoking + +Actions + +and +observing + +Events + +(WoT +interactions). +

+
    +
  • +The + + +type + + +attribute +represents +the +type +of +the +request +as +defined +in + + +RequestType + +. +
    • +
  • +The + + +from + + +attribute +represents +the +address +of +the +client +device +issuing +the +request. +The +type +of +the +address +(URL, +UUID +or +other) +is +defined +by +the + +Thing +Description +. +
    • +
  • +The + + +name + + +attribute +represents +the +name +of +the + +Property + +to +be +retrieved +or +updated, +or +the +name +of +the +invoked + +Action +, +or +the +event +name +to +be +observed. +
    • +
  • +The + + +options + + +attribute +represents +the +options +relevant +to +the +request +(e.g. +the +format +or +measurement +units +for +the +returned +value) +as +key-value +pairs. +The +exact +format +is +specified +by +the + +Thing +Description +. +
    • +
  • +The + + +data + + +attribute +represents +the +value +of +the + +Property +, +or +the +input +data +(arguments) +of +an + +Action +. +It +is +not +used +for +retrieve +requests +and +event +requests, +only +for + +Property + +update +and + +Action + +invocation +requests. +
    • +
+
+

+ +5.2.1 + +The + + +RequestType + + +enumeration +

+
+ 
enum RequestType {
+    "property",
+    "action",
+    "event",
+    "td"
+};
+
+
+
+
    +
  • +The +value +" + + +property + + +" +represents +requests +to +retrieve +or +update +a + +Property +. +
    • +
  • +The +value +" + + +action + + +" +represents +requests +to +invoke +an + +Action +. +
    • +
  • +The +value +" + + +event + + +" +represents +requests +to +emit +an +event. +
    • +
  • +The +value +" + + +td + + +" +represents +requests +to +change +the + +Thing +Description +, +i.e. +to +add, +remove +or +modify +properties, + +Actions + +or + +Events +. +
    +
    + +Editor's +note + +
    +

    +This +functionality +is +here +for +the +sake +of +completeness +for +future +versions +of +the +API. +Currently +there +is +no +corresponding +functionality +at +the + + +ConsumedThing + + +level +and +it +is +not +guaranteed +that +a +Thing +Description +could +be +remotely +changed +by +scripting. +

    +
    +
    • +
+
+
+

+ +5.2.2 + +The + + +respond() + + +method +

+

+Sends +a +positive +response +to +the + + +Request + + +based +on +the + +Protocol +Bindings + +and +includes +the +data +specified +by +the + +data + +argument. +

+
+
+

+ +5.2.3 + +The + + +respondWithError() + + +method +

+

+Sends +a +negative +response +to +the + + +Request + + +based +on +the + +Protocol +Bindings + +and +includes +the +error +specified +by +the + +error + +argument. +

+
+
+
+

+ +5.3 + +The + + +RequestHandler + + +callback +

+

+Callback +function +for +handling +interaction +requests. +Receives +an +argument + +request + +of +type + + + +Request + + + +and +should +return +an +object +or +value +that +is +used +by + +Protocol +Bindings + +to +reply +to +the +request. +The +returned +type +is +defined +by +the + +Thing +Description +. +

+
+
+

+ +5.4 + +The + + +addProperty() + + +method +

+

+Adds +a + +Property + +defined +by +the +argument +and +updates +the + +Thing +Description +. +

+
+

+ +5.4.1 + +The + + +ThingPropertyInit + + +dictionary +

+ +

+Represents +the + +Thing + + +Property + +description. +

+
    +
  • +The + + +name + + +attribute +represents +the +name +of +the + +Property +. +
    • +
  • +The + + +value + + +attribute +represents +the +value +of +the + +Property +. +
    • +
  • +The + + +configurable + + +attribute +defines +whether +the + +Property + +can +be +deleted +from +the +object +and +whether +its +properties +can +be +changed. +The +default +value +is + +false +. +
    • +
  • +The + + +enumerable + + +attribute +defines +whether +the + +Property + +can +be +listed +and +iterated. +The +default +value +is + +true +. +
    • +
  • +The + + +writable + + +attribute +defines +whether +the + +Property + +can +be +updated. +The +default +value +is + +true +. +
    • +
  • +The + + +semanticTypes + + +attribute +represents +a +list +of +semantic +type +annotations +(e.g. +labels, +classifications +etc) +relevant +to +the + +Property +, +represented +as + + +SemanticType + + +dictionaries. +
    • +
  • +The + + +description + + +attribute +represents +the + +Property + +description +to +be +added +to +the + +Thing +Description +. +
    • +
+
+
+

+ +5.4.2 + +The + + +SemanticType + + +dictionary +

+
+ 
dictionary SemanticType {
+    DOMString name;
+    USVString context;
+};
+
+
+
+

+Represents +a +semantic +type +annotation, +containing +a +name +and +a +context. +

+
    +
  • +The + + +name + + +attribute +represents +the +name +of +the +semantic +type +in +the +given +context. +
    • +
  • +The + + +context + + +attribute +represents +an +URL +link +to +the +context +of +the +semantic +classification. +
    • +
+
+
+ +Editor's +note + +
+

+Semantic +type +examples +to +be +added. +

+
+
+
+
+

+ +5.5 + +The + + +removeProperty() + + +method +

+

+Removes +the + +Property + +specified +by +the + +name + +argument, +updates +the + +Thing +Description + +and +returns +the +object. +

+
+
+

+ +5.6 + +The + + +addAction() + + +method +

+

+Adds +an + +Action + +to +the + +Thing + +object +as +defined +by +the + +action + +argument +of +type + + +ThingActionInit + + +and +updates +the + +Thing +Description +. +

+
+

+ +5.6.1 + +The + + +ThingActionInit + + +dictionary +

+ +

+The + + +ThingActionInit + + +dictionary +describes +the +arguments +and +the +return +value. +

+
    +
  • +The + + +name + + +attribute +provides +the + +Action + +name. +
    • +
  • +The + + +action + + +attribute +provides +a +function +that +defines +the + +Action +. +
    • +
  • +The + + +inputDataDescription + + +attribute +provides +the +description +of +the +input +arguments. +
    • +
  • +The + + +outputDataDescription + + +attribute +provides +the +description +of +the +returned +data. +
    • +
  • +The + + +semanticTypes + + +attribute +provides +a +list +of +semantic +type +annotations +(e.g. +labels, +classifications +etc) +relevant +to +the + +Action +, +represented +as + + +SemanticType + + +dictionaries. +
    • +
+
+
+
+

+ +5.7 + +The + + +removeAction() + + +method +

+

+Removes +the + +Action + +specified +by +the + +name + +argument, +updates +the + +Thing +Description + +and +returns +the +object. +

+
+
+

+ +5.8 + +The + + +addEvent() + + +method +

+

+Adds +an +event +to +the + +Thing + +object +as +defined +by +the + +event + +argument +of +type + + +ThingEventInit + + +and +updates +the + +Thing +Description +. +

+
+

+ +5.8.1 + +The + + +ThingEventInit + + +dictionary +

+ +
    +
  • +The + + +name + + +attribute +represents +the +event +name. +
    • +
  • +The + + +semanticTypes + + +attribute +represent +a +list +of +semantic +type +annotations +attached +to +the +event. +
    • +
  • +The + + +dataDescription + + +attribute +represents +the +description +of +the +data +that +is +attached +to +the +event. +
    • +
+
+
+
+

+ +5.9 + +The + + +removeEvent() + + +method +

+

+Removes +the +event +specified +by +the + +name + +argument, +updates +the + +Thing +Description + +and +returns +the +object. +

+
+
+

+ +5.10 + +The + + +onRetrieveProperty() + + +method +

+

+Registers +the +handler +function +for + +Property + +retrieve +requests +received +for +the + +Thing +, +as +defined +by +the + +handler + +property +of +type + + + +RequestHandler + + +. +The +handler +will +receive +an +argument + +request + +of +type + + + +Request + + + +where +at +least + +request.name + +is +defined +and +represents +the +name +of +the + +Property + +to +be +retrieved. +

+
+
+

+ +5.11 + +The + + +onUpdateProperty() + + +method +

+

+Defines +the +handler +function +for + +Property + +update +requests +received +for +the + +Thing +, +as +defined +by +the + +handler + +property +of +type + + + +RequestHandler + + +. +The +handler +will +receive +an +argument + +request + +of +type + + + +Request + + + +where + +request.name + +defines +the +name +of +the + +Property + +to +be +retrieved +and + +request.data + +defines +the +new +value +of +the + +Property +. +

+
+
+

+ +5.12 + +The + + +onInvokeAction() + + +method +

+

+Defines +the +handler +function +for + +Action + +invocation +requests +received +for +the + +Thing +, +as +defined +by +the + +handler + +property +of +type + + + +RequestHandler + + +. +The +handler +will +receive +an +argument + +request + +of +type + + + +Request + + + +where + +request.name + +defines +the +name +of +the + +Action + +to +be +invoked +and + +request.data + +defines +the +input +arguments +for +the + +Action + +as +defined +by +the + +Thing +Description +. +

+
+
+

+ +5.13 + +The + + +onObserve() + + +method +

+

+Defines +the +handler +function +for +observe +requests +received +for +the + +Thing +, +as +defined +by +the + +handler + +property +of +type + + + +RequestHandler + + +. +The +handler +will +receive +an +argument + +request + +of +type + + + +Request + + + +where +

+
    +
  • + +request.name + +defines +the +name +of +the + +Property + +or + +Action + +or +event +to +be +observed. +
    • +
  • + +request.options.observeType + +is +of +type + + +RequestType + + +and +defines +whether +a + +Property + +change +or + +Action + +invocation +or +event +emitting +is +observed, +or +the +changes +to +the + +Thing +Description + +are +observed. +
    • +
  • + +request.options.subscribe + +is + +true + +if +subscription +is +turned +or +kept +being +turned +on, +and +it +is + +false + +when +subscription +is +turned +off. +
    • +
+
+
+

+ +5.14 + +The + + +register() + + +method +

+

+Generates +the + +Thing +Description + +given +the +properties, + +Actions + +and + +Event + +defined +for +this +object. +If +a + +directory + +argument +is +given, +make +a +request +to +register +the + +Thing +Description + +with +the +given +WoT +repository +by +invoking +its + +register + + +Action +. +

+
+
+

+ +5.15 + +The + + +unregister() + + +method +

+

+If +a + +directory + +argument +is +given, +make +a +request +to +unregister +the + +Thing +Description + +with +the +given +WoT +repository +by +invoking +its + +unregister + + +Action +. +Then, +and +in +the +case +no +arguments +were +provided +to +this +function, +stop +the + +Thing + +and +remove +the + +Thing +Description +. +

+
+
+

+ +5.16 + +The + + +start() + + +method +

+

+Start +serving +external +requests +for +the + +Thing +. +

+
+
+

+ +5.17 + +The + + +stop() + + +method +

+

+Stop +serving +external +requests +for +the + +Thing +. +

+
+
+

+ +5.18 + +The + + +emitEvent() + + +method +

+

+Emits +an +the +event +initialized +with +the +event +name +specified +by +the + +eventName + +argument +and +data +specified +by +the + +payload + +argument. +

+
+
+

+ +5.19 + +Events +supported +by +ExposedThing +

+

+The +following +default +events + +SHOULD + +be +supported +by + + +ExposedThing + + +implementations: +

+ +

+In +addition, +user +defined +events +are +specified +by +the + +Thing +Description +. +

+
+
+

+ +5.20 + +Examples +

+

+Below +some + + + +ExposedThing + + + +interface +examples +are +given. +

+
+
+ +Example +6 + +: +Create +a +new +blank +exposed +Thing + +
+ 
WoT.createExposedThing(thingDescription)
+  .then(function(thing) {
+    // manually add properties, actions, and events
+    thing.addProperty({
+      name: "temperature",
+      value: "0",
+      writable: false
+      // use default values for the rest
+    }).addEvent({
+      name: "onchange",
+      outputDataDescription: {
+        type: "float32"
+      }
+    }).addAction({
+      name: "reset",
+      action: () => { this.temperature = 0; }
+    })
+    // add server functionality
+    .onRetrieveProperty( request => {
+      console.log("Handling read request");
+      return this.temperature;
+    }).onObserve( request => {
+      console.log("Handling observe request");
+      // add listener identified by request.from
+    }).onInvokeAction( request => {
+      console.log("Handling action request");
+    }).start();
+});
+
+
+
+
+ +Example +7 + +: +Create +a +new +exposed +Thing +from +a +TD +URI + +
+ 
let thingDescription = '{
+  "name": "mySensor",
+  "url": "http://myservice.org/mySensor/description"
+}';
+WoT.createExposedThing(thingDescription)
+  .then(function(thing) {
+    // properties, actions and events are added based on the TD
+    console.log("created " + thing.name });
+    // now add the requests handlers
+    thing.onRetrieveProperty(function(request) {
+        console.log("Sending property '" + request.property + "' to " + request.from);
+    }).onUpdateProperty(function(request) {
+        console.log("Updating property '" + request.property + "' by " + request.from);
+    }).onObserve(function(request) {
+        console.log("Adding listener " + request.from);
+        console.log("Observing " + request.type + " " + request.name +
+            (request.subscribe? " recursively" : ""));
+    }).start().then(function() {
+       console.log("Thing started serving requests");
+    });
+})
+
+
+
+
+ +Example +8 + +: +Create +a +new +exposed +Thing +from +a +Thing +Description + +
+ 
let thingDescription = '{
+  "name": "mySensor",
+  "description": {
+    "@context": [
+      "http://w3c.github.io/wot/w3c-wot-td-context.jsonld",
+      "http://w3c.github.io/wot/w3c-wot-common-context.jsonld",
+    ],
+    "@type": [ "Thing" ],
+    "interaction": [
+      // ...
+    ]
+    // ...
+  }'
+};
+WoT.createExposedThing(thingDescription)
+  .then(function(thing) {
+    // properties, actions and events are added based on the TD
+    // ...
+});
+
+
+
+
+
+

+ +6. + +Security +and +Privacy +

+
+
+ +Editor's +note + +
+

+Please +see +the + +WoT +Security +and +Privacy + +repository +for +work +in +progress +regarding +threat +models, +assets, +risks, +recommended +mitigations, +and +best +practices +for +security +and +privacy +for +systems +using +the +Web +of +Things. +Once +complete, +security +and +privacy +considerations +relevant +to +the +Scripting +API +will +be +summarized +in +this +section. +

+
+
+
+

+ +7. + +Terminology +and +conventions +

+

+The +generic +WoT +terminology +is +defined +in +[ + + +WOT-ARCHITECTURE + + +]: + +Thing +, + +Thing +Description + +(in +short + +TD + +), + +Web +of +Things + +(in +short + + +WoT + + +), + +WoT +Interface +, + +Protocol +Bindings +, + +WoT +Runtime +, + +Consuming +a +Thing +Description +, + +Thing +Directory +, + +Property +, + +Action +, + +Event + +etc. +

+
+
+ +Note + +
+

+In +this +version +of +the +specification, +a + +WoT +Runtime + +is +assumed +to +run +scripts +that +uses +this +API +to +define +one +or +more + +Thing + +s +that +share +a +common +event +loop. +Script +deployment +methods +are +out +of +scope +of +this +version. +In +future +versions, +running +multiple +scripts +(as +modules) +may +be +possible, +and +script +deployment + +MAY + +be +implemented +using +a +manager + +Thing + +whose + +Actions + +permit +script +lifecycle +management +operations. +

+
+

+ +JSON-LD + +is +defined +in +[ + + +JSON-LD + + +] +as +a +JSON +document +that +is +augmented +with +support +for +Linked +Data +by +providing +a + +@context + +property +with +a +defining +URI +. +

+

+The +terms + + +URL + + +and + + +URL +path + + +are +defined +in +[ + + +URL + + +]. +

+

+The +following +terms +are +defined +in +[ + + +HTML5 + + +] +and +are +used +in +the +context +of +browser +implementations: + + +browsing +context + +, + + +top-level +browsing +context + +, + + +global +object + +, + + +incumbent +settings +object + +, + + +Document + +, + + +document +base +URL + +, + + +Window + +, + + +WindowProxy + +, + + +origin + +, + + +ASCII +serialized +origin + +, +executing +algorithms + + +in +parallel + +, + + +queue +a +task + +, + + +task +source + +, + + +iframe + +, + + +valid +MIME +type + +. +

+

+A + +browsing +context + +refers +to +the +environment +in +which + +Document + +objects +are +presented +to +the +user. +A +given + +browsing +context + +has +a +single + + +WindowProxy + + +object, +but +it +can +have +many + + +Document + + +objects, +with +their +associated + + +Window + + +objects. +The + +script +execution +context + +associated +with +the + +browsing +context + +identifies +the +entity +which +invokes +this +API, +which +can +be +a + +web +app +, +a + +web +page +, +or +an + +iframe +. +

+

+The +term + + +secure +context + + +is +defined +in +[ + + +WEBAPPSEC + + +]. +

+

+ + +Error +, + +EvalError +, + +RangeError +, + +ReferenceError +, + +SyntaxError +, + +TypeError +, + +URIError + +, + + +script +execution +context + +, + + +Promise + +, + + +JSON + +, + + +JSON.stringify + + +and + + +JSON.parse + + +are +defined +in +[ + + +ECMASCRIPT + + +]. +

+

+ + +DOMString + +, + + +USVString + +, + + +ArrayBuffer + +, + + +BufferSource + + +and + + +any + + +are +defined +in +[ + + +WEBIDL + + +]. +

+

+The +term + + +event + + +and +the + + +Event + + +object +are +defined +in + +DOM + +and + +Node.js +. +

+
+
+ +Note + +
+

+This +specification +uses +the +convention +that +an +event +listener +will +receive +an + +Event + +object. +This +should +work +both +in +a +browser +environment +and +in +a +Node.js +like +environment. +

+
+

+ + +Observable + +s + +are +proposed +to +be +included +in +ECMAScript. +

+

+The +algorithms + + +utf-8 +encode + +, +and + + +utf-8 +decode + + +are +defined +in +[ + + +ENCODING + + +]. +

+

+ +IANA +media +type + +s +(formerly +known +as +MIME +types) +are +defined +in + +RFC2046 +. +

+
+
+

+ +8. + +Conformance +

+

+As +well +as +sections +marked +as +non-normative, +all +authoring +guidelines, +diagrams, +examples, +and +notes +in +this +specification +are +non-normative. +Everything +else +in +this +specification +is +normative. +

+

+The +key +words + +MAY +, + +MUST +, +and + +SHOULD + +are +to +be +interpreted +as +described +in +[ + + +RFC2119 + + +]. +

+

+This +document +defines +conformance +criteria +that +apply +to +a +single +product: +the + +UA + +(user +agent) +that +implements +the +interfaces +it +contains. +

+

+This +specification +can +be +used +for +implementing +the +WoT +Scripting +API +in +multiple +programming +languages. +The +interface +definitions +are +specified +in +[ + + +WEBIDL + + +]. +

+

+The +user +agent +(UA) +may +be +implemented +in +the +browser, +or +in +a +separate +runtime +environment, +such +as + +Node.js + +or +small +embedded +runtimes. +

+

+Implementations +that +use +ECMAScript +executed +in +a +browser +to +implement +the +APIs +defined +in +this +document + +MUST + +implement +them +in +a +manner +consistent +with +the +ECMAScript +Bindings +defined +in +the +Web +IDL +specification +[ + + +WEBIDL + + +]. +

+

+Implementations +that +use +TypeScript +or +ECMAScript +in +a +runtime +to +implement +the +APIs +defined +in +this +document + +MUST + +implement +them +in +a +manner +consistent +with +the +TypeScript +Bindings +defined +in +the +TypeScript +specification +[ + + +TYPESCRIPT + + +]. +

+

+This +document +serves +a +general +description +of +the +WoT +Scripting +API. +Language +and +runtime +specific +issues +are +discussed +in +separate +extensions +of +this +document. +

+
+
+

+ +A. + +Changes +

+

+The +following +is +a +list +of +major +changes +to +the +document. +For +a +complete +list +of +changes, +see +the + +github +change +log +. +You +can +also +view +the + +recently +closed +bugs +. +

+
+
+

+ +B. + +Open +issues +

+

+The +following +problems +are +being +discussed +and +need +most +attention: +

+ +
+
+

+ +C. + +Acknowledgements +

+

+Special +thanks +to +former +editor +Johannes +Hund +(until +August +2017, +when +at +Siemens +AG) + +for +developing +this +specification. +Also, +the +editors +would +like +to +thank +Dave +Raggett, +Matthias +Kovatsch, +Michael +Koster +and +Michael +McCool +for +their +comments +and +guidance. +

+
+
+

+ +D. + +References +

+
+

+ +D.1 + +Normative +references +

+
+
+[ECMASCRIPT] +
+
+ + +ECMAScript +Language +Specification + +. +Ecma +International. +URL: + +https://tc39.github.io/ecma262/ + +
+
+[ENCODING] +
+
+ + +Encoding +Standard + +. +Anne +van +Kesteren. +WHATWG. +Living +Standard. +URL: + +https://encoding.spec.whatwg.org/ + +
+
+[HTML5] +
+
+ + +HTML5 + +. +Ian +Hickson; +Robin +Berjon; +Steve +Faulkner; +Travis +Leithead; +Erika +Doyle +Navara; +Theresa +O'Connor; +Silvia +Pfeiffer. +W3C. +28 +October +2014. +W3C +Recommendation. +URL: + +https://www.w3.org/TR/html5/ + +
+
+[JSON-LD] +
+
+ + +JSON-LD +1.0 + +. +Manu +Sporny; +Gregg +Kellogg; +Markus +Lanthaler. +W3C. +16 +January +2014. +W3C +Recommendation. +URL: + +https://www.w3.org/TR/json-ld/ + +
+
+[RFC2119] +
+
+ + +Key +words +for +use +in +RFCs +to +Indicate +Requirement +Levels + +. +S. +Bradner. +IETF. +March +1997. +Best +Current +Practice. +URL: + +https://tools.ietf.org/html/rfc2119 + +
+
+[TYPESCRIPT] +
+
+ + +TypeScript +Language +Specification + +. +Microsoft. +1 +October +2012. +URL: + +https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md + +
+
+[URL] +
+
+ + +URL +Standard + +. +Anne +van +Kesteren. +WHATWG. +Living +Standard. +URL: + +https://url.spec.whatwg.org/ + +
+
+[WEBAPPSEC] +
+
+ + +Secure +Contexts + +. +W3C. +17 +July +2015. +URL: + +https://w3c.github.io/webappsec/specs/powerfulfeatures + +
+
+[WEBIDL] +
+
+ + +Web +IDL + +. +Cameron +McCormack; +Boris +Zbarsky; +Tobie +Langel. +W3C. +15 +December +2016. +W3C +Editor's +Draft. +URL: + +https://heycam.github.io/webidl/ + +
+
+[WOT-ARCHITECTURE] +
+
+ + +Web +of +Things +Architecture + +. +W3C. +20 +August +2017. +URL: + +https://w3c.github.io/wot-architecture/ + +
+
+
+
+ + + +