+
+
+
+
+
++Web +of +Things +(WoT) +Scripting +API +
+
+
+W3C
+
+Editor's
+
+First
+Public
+Working
+
+Draft
+13
+
+
+
+-
+
- +This +version: + +
-
+
https://w3c.github.io/wot-scripting-api/ ++ +https://www.w3.org/TR/2017/WD-wot-scripting-api-20170914/ + + +
+ - +Latest +published +version: + +
- + +https://www.w3.org/TR/wot-scripting-api/ + + +
- +Latest +editor's +draft: + +
- + +https://w3c.github.io/wot-scripting-api/ + + +
- +Editors: + + + + +
- +Contributors: + +
- + +In +the +GitHub +repository + + +
- +Repository: + +
- + +We +are +on +GitHub + + +
- + +File +a +bug + + +
+ +Copyright + +© +2017 + + +W3C + + + +® + +( + + +MIT + +, + + +ERCIM + +, + +Keio +, + +Beihang + +). + +W3C + + +liability +, + +trademark + +and + +permissive +document +license + +rules +apply. +
++
+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. +
++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. +
++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: +
+-
+
- +Discover +all + +Thing + +s +in +the +WoT +network +by +sending +a +broadcast +request. + +
- +Discover + +Thing + +s +running +in +the +local + +WoT +Runtime +. + +
- +Discover +nearby + +Thing + +s, +for +instance +by +NFC +or +Bluetooth. + +
- +Discover + +Thing + +s +by +sending +a +discovery +request +to +a +given +registry. + +
- +Discover + +Thing + +s +by +filters +defined +on + +Thing +Description + +s + +
- +Discover + +Thing + +s +by +semantic +filters. + +
- +Stop +or +suppress +an +ongoing +discovery +process. + +
- +Fetch +and + +consume +a +TD + +of +a +remote + +Thing +. + +
-
+On
+a
+consumed
+
+Thing
+,
+
-
+
- +Get +the +value +of +a + +Property + +or +set +of +properties. + +
- +Set +the +value +of +a + +Property + +or +a +set +of +properties. + +
- +Invoke +an + +Action +. + +
-
+Observe
+
+Events
+.
+
-
+
- +Add +a +listener +to +an + +Event +. + +
- +Remove +a +listener +from +an + +Event +. + +
- +Remove +all +listeners. + +
-
+
- +A + +Property + +has +changed. + +
- +An + +Action + +has +been +invoked. + +
- + +Thing +Description + +has +changed, +i.e. + +Properties +, + +Events + +or + +Actions + +have +been +defined, +removed, +or +the +definition +has +changed. + +
+
+ - +Consume +a +thing. + +
- +Create +and +expose +a +local + +Thing + +based +on +a + +Thing +Description +. + +
-
+Programmatically
+create
+and
+expose
+a
+local
+
+Thing
+.
+This
+may
+include
+the
+following
+use
+cases:
+
-
+
- +Create +a +local + +Thing +. + +
- +Add +a + +Property + +definition +to +the + +Thing +. + +
- +Add +an + +Event + +definition +to +the + +Thing +. + +
- +Add +an + +Action + +definition +to +the + +Thing +. + +
- +Attach +semantic +information +to +an + +Action + + +
- +Attach +semantic +information +to +a + +Property + + +
- +Attach +semantic +information +to +an + +Event + + +
- +Emit +an + +Event +, +i.e. +notify +all +listeners +subscribed +to +that + +Event +. + +
-
+Register
+handlers
+for
+external
+requests:
+
-
+
- +to +retrieve +a + +Property + +value; + +
- +to +update +a + +Property + +value; + +
- +to +run +an + +Action +: +take +the +parameters +from +the +request, +execute +the +defined +action, +and +return +the +result; + +
- +to +add +a +listener +to +an + +Event + +; + +
- +to +remove +an + +Event + +listener. + +
- +to +fetch +the + +Thing +Description + +; + +
+
+ - +Register +the +Thing. + +
- +Unregister +the +Thing. + +
- +Start +the +exposed + +Thing + +in +order +to +process +external +requests. + +
- +Stop +the +exposed + +Thing +. + +
+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 +. +
+
+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);
+};
+
+
++The +algorithms +for +the +WoT +methods +will +be +specified +later. +
+
+
+3.1
+
+The
+
+
+discover()
+
+
+method
+
+
+Starts
+the
+discovery
+process
+that
+will
+provide
+
+
+
+objects
+that
+match
+the
+optional
+argument
+
+ConsumedThing
+
+
+
+
+.
+When
+the
+argument
+is
+not
+provided,
+starts
+the
+widest
+discovery
+the
+
+Thing
+Description
+
+and
+
+Protocol
+Bindings
+
+allow.
+Returns
+an
+
+
+ThingFilter
+
+
+
+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
+
+
+
+enumeration
+that
+can
+be
+extended
+by
+string
+values
+defined
+by
+solutions
+(with
+no
+guarantee
+of
+interoperability).
+
+DiscoveryMethod
+
+
+
+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
+.
+
+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.
+
+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.
+
+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
+
+
+
+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 +
+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
+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.
+
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");}
+);
+
+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");}
+);
+
+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 DOMStringname; + readonly attribute USVStringurl; + readonly attributeThingDescriptiondescription; + Promise<any> invokeAction(DOMString name, any parameters); + Promise<void> setProperty(DOMString name, any value); + Promise<any> getProperty(DOMString name); +ConsumedThingaddListener(DOMString eventName,ThingEventListenerlistener); +ConsumedThingremoveListener(DOMString eventName, +ThingEventListenerlistener); +ConsumedThingremoveAllListeners(optional DOMString eventName); + Observable observe(DOMString name,RequestTyperequestType); +}; + +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. +
+
+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
+
+dictionary ActionInvocationEventInit {
+ DOMString actionName;
+ any returnValue;
+};
+
+
++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
+
+[Constructor(ThingDescriptionChangeEventInit init)]
+interface ThingDescriptionChangeEvent : Event {
+ readonly attribute ThingDescriptionChangeEventInit data;
+};
+
+
+
+The
+
+
+data
+
+
+attribute
+represents
+the
+changes
+that
+occurred
+to
+the
+
+Thing
+Description
+.
+
+
+4.9.3.1
+
+The
+
+
+ThingDescriptionChangeEventInit
+
+
+dictionary
+
+dictionary ThingDescriptionChangeEventInit {
+ TDChangeType type;
+ TDChangeMethod method;
+ DOMString name;
+ TDChangeData data;
+ ThingDescription description;
+};
+
+
+-
+
-
+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"
+};
+
+
+-
+
-
+The
+
+
+add ++ +value +denotes +addition +of +a + +Property +, + +Action + +or +event. +
+ -
+The
+
+
+remove ++ +value +denotes +removal +of +a + +Property +, + +Action + +or +event. +
+ -
+The
+
+
+change ++ +value +denotes +a +change +applied +on +a + +Property +, + +Action + +or +event. +
+
+
+4.9.3.1.2
+
+The
+
+
+TDChangeType
+
+
+enumeration
+
+enum+TDChangeType{ + "property", + "action", + "event" +}; + +typedef + +( + ++ThingPropertyInit ++ +or + ++ThingActionInit ++ +or + ++ThingEventInit ++ +) + + + ++TDChangeData ++ + +; + +
-
+
-
+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
+
+
+
+interface
+example
+is
+given.
+
+ConsumedThing
+
+
+
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; +callbackRequestHandler= any (Requestrequest); +interfaceExposedThing{ + // define Thing Description modifiers +ExposedThingaddProperty(ThingPropertyInitproperty); +ExposedThingremoveProperty(DOMString name); +ExposedThingaddAction(ThingActionInitaction); +ExposedThingremoveAction(DOMString name); +ExposedThingaddEvent(ThingEventInitevent); +ExposedThingremoveEvent(DOMString name); + // define request handlers +ExposedThingonRetrieveProperty(RequestHandlerhandler); +ExposedThingonUpdateProperty(RequestHandlerhandler); +ExposedThingonInvokeAction(RequestHandlerhandler); +ExposedThingonObserve(RequestHandlerhandler); + // 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. +
++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
+
+
+
+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
+.
+
+Request
+
+
+
+
+5.4
+
+The
+
+
+addProperty()
+
+
+method
+
++Adds +a + +Property + +defined +by +the +argument +and +updates +the + +Thing +Description +. +
+
+
+5.4.1
+
+The
+
+
+ThingPropertyInit
+
+
+dictionary
+
+dictionary ThingPropertyInit {
+ DOMString name;
+ boolean configurable = true;
+ boolean enumerable = true;
+ boolean writable = true;
+ sequence<SemanticType> semanticTypes;
+ ThingDescription description;
+ any value;
+};
+
+
++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. +
+
+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
+
+dictionary ThingActionInit {
+ DOMString name;
+ ThingDescription inputDataDescription;
+ ThingDescription outputDataDescription;
+ sequence<SemanticType> semanticTypes;
+ Function action;
+};
+
+
+
+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
+
+dictionary ThingEventInit {
+ DOMString name;
+ sequence<SemanticType> semanticTypes;
+ ThingDescription dataDescription;
+};
+
+
+-
+
-
+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
+
+
+.
+The
+handler
+will
+receive
+an
+argument
+
+request
+
+of
+type
+
+RequestHandler
+
+
+
+
+
+where
+at
+least
+
+request.name
+
+is
+defined
+and
+represents
+the
+name
+of
+the
+
+Property
+
+to
+be
+retrieved.
+
+Request
+
+
+
+
+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
+
+
+.
+The
+handler
+will
+receive
+an
+argument
+
+request
+
+of
+type
+
+RequestHandler
+
+
+
+
+
+where
+
+request.name
+
+defines
+the
+name
+of
+the
+
+Property
+
+to
+be
+retrieved
+and
+
+request.data
+
+defines
+the
+new
+value
+of
+the
+
+Property
+.
+
+Request
+
+
+
+
+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
+
+
+.
+The
+handler
+will
+receive
+an
+argument
+
+request
+
+of
+type
+
+RequestHandler
+
+
+
+
+
+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
+.
+
+Request
+
+
+
+
+5.13
+
+The
+
+
+onObserve()
+
+
+method
+
+
+Defines
+the
+handler
+function
+for
+observe
+requests
+received
+for
+the
+
+Thing
+,
+as
+defined
+by
+the
+
+handler
+
+property
+of
+type
+
+
+.
+The
+handler
+will
+receive
+an
+argument
+
+request
+
+of
+type
+
+RequestHandler
+
+
+
+
+
+where
+
+Request
+
+
+
-
+
- + +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:
+
-
+
-
+"
+
+propertychange
+
+"
+of
+type
+
+
+PropertyChangeEvent ++ +
+ -
+"
+
+actioninvocation
+
+"
+of
+type
+
+
+ActionInvocationEvent ++ +
+ -
+"
+
+descriptionchange
+
+"
+of
+type
+
+
+ThingDescriptionChangeEvent ++. +
+
+In +addition, +user +defined +events +are +specified +by +the + +Thing +Description +. +
++ +5.20 + +Examples +
+
+Below
+some
+
+
+
+interface
+examples
+are
+given.
+
+ExposedThing
+
+
+
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();
+});
+
+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");
+ });
+})
+
+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 +
++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. +
++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 +. +
++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: +
+-
+
- +Retrieving +information +from +Thing +Description +( + +https://github.com/w3c/wot-scripting-api/issues/38 + +) + +
- +Script +management +and +runtime +related +issues +( + +https://github.com/w3c/wot-scripting-api/issues/ + +) + +
+ +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/ + + +