"false">

Web of Things (WoT) Scripting API

W3C First Public Working Draft 14 September 2017

This version:
https://www.w3.org/TR/2017/WD-wot-scripting-api-20170914/ https://www.w3.org/TR/2018/WD-wot-scripting-api-20180405/
Latest published version:
https://www.w3.org/TR/wot-scripting-api/
Latest editor's draft:
https://w3c.github.io/wot-scripting-api/
Previous version:
https://www.w3.org/TR/2017/WD-wot-scripting-api-20170914/
Editors:
Zoltan Kis , ( Intel )
Kazuaki Nimura , ( Fujitsu Ltd. )
Daniel Peintner , ( Siemens AG )
Johannes Hund (Former Editor, when at Siemens AG)
Contributors:
In the GitHub repository
Repository:
We are on GitHub
File a bug

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, WoT Interactions , i.e. 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 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 ).

Changes from the previous publication can be found in Appendix A . A diff-marked version of this document is also available for comparison purposes.

Publication as 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 February 2018 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, Properties , Actions and Events exposed by the server Thing .

Exposing a Thing requires defining a Thing Description (TD) and instantiating a software stack needed to serve requests for accessing the exposed properties, 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.

Note

This specification does not make assumptions on how the WoT Runtime handles and runs scripts, including single or multiple tenancy, script deployment and lifecycle management. The API already supports the generic mechanisms that make it possible to implement script management, for instance by exposing a manager Thing whose Actions (action handlers) implement script lifecycle management operations.

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 supported in this specification:

2.1 Discovery

2.2 Consuming a Thing

Consume

2.3 Exposing a thing. Thing

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 does not expose properties, only 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 "idlInterfaceID"><a data-lt="WoT" href="#dom-wot" class=
"internalDFN" data-link-type="dfn" data-for=
""> {
<span class="idlMethod" id="idl-def-wot-discover(filter)" data-idl=

"idlInterfaceID">WoT {
    "idlMethType"><a href="#dfn-observable" class="internalDFN"
data-link-type="dfn">Observable<<a href="#dom-consumedthing"
class="internalDFN" data-link-type=

"idlMethType">Observable<
"dfn">ConsumedThing> "idlMethName"><a data-lt="discover()|discover()|discover"
data-lt-nodefault="" href="#dom-wot-discover()" class="internalDFN"
data-link-type="dfn" data-for=
"WoT">discover<a href="#dom-thingfilter"
class="internalDFN" data-link-type=

"idlMethName">discover(optional 
"dfn">ThingFilter filter);
<span class="idlMethod" id="idl-def-wot-consume(url)" data-idl=""
data-title="consume" data-dfn-for="wot">    <span class=

data-title="fetch" data-dfn-for="wot">    
"idlMethType">"https://heycam.github.io/webidl/#idl-promise">Promise<<a href="#dom-consumedthing"

"https://heycam.github.io/webidl/#idl-promise">Promise<
class="internalDFN" data-link-type=
"dfn">    <span class=
"idlMethName"><a data-lt="consume()|consume()|consume"
data-lt-nodefault="" href="#dom-wot-consume()" class="internalDFN"
data-link-type="dfn" data-for="WoT">consume(<span class=

"dfn">ThingDescription> fetch(
"idlParam">USVString url);
<span class="idlMethod" id="idl-def-wot-expose(init)" data-idl=""
data-title="expose" data-dfn-for="wot">    <span class=
"idlMethType"><a href=
"https://heycam.github.io/webidl/#idl-promise">Promise<<a href="#dom-exposedthing"
class="internalDFN" data-link-type=
"dfn">     <span class=
"idlMethName"><a data-lt="expose()|expose()|expose"
data-lt-nodefault="" href="#dom-wot-expose()" class="internalDFN"
data-link-type="dfn" data-for="WoT">expose(<span class=
"idlParam"><a href="#dom-thinginit"
class="internalDFN" data-link-type=
"dfn"> <span class=
"idlParamName">init
};

data-title="consume" data-dfn-for="wot">    ConsumedThing             consume(ThingDescription td);

data-title="produce" data-dfn-for="wot">    ExposedThing              produce(ThingModel model);
};

data-title="ThingDescription">typedef USVString ThingDescription;

data-title="ThingModel">typedef (ThingTemplate or ThingDescription) 

ThingModel

;


Editor's note

The algorithms for the WoT methods will be specified later. later, including error handling and security considerations.

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. allow and support. Returns an Observable object that can be subscribed to and unsubscribed to. from.

3.1.1 The DiscoveryMethod enumeration


"idl-def-discoverymethod" data-idl="" data-title=
"DiscoveryMethod">typedef DOMString 

DiscoveryMethod

;

DiscoveryMethod 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.1.2 The ThingFilter dictionary

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

"ThingFilter">dictionary <a data-lt=
"ThingFilter" href="#dom-thingfilter" class="internalDFN"
data-link-type="dfn" data-for=
""> {

"ThingFilter">dictionary ThingFilter {

    "idlMemberType">(DiscoveryType or <a href=
"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="method"
href="#dom-thingfilter-method" class="internalDFN" data-link-type=
"dfn" data-for=
"ThingFilter"> = <span class=

"idlMemberType">DiscoveryMethod      method = 
"idlMemberValue">"any";
    "https://heycam.github.io/webidl/#idl-USVString">USVString<a data-lt="url"
href="#dom-thingfilter-url" class="internalDFN" data-link-type=
"dfn" data-for="ThingFilter">
<span class="idlMember" id="idl-def-thingfilter-description"
data-idl="" data-title="description" data-dfn-for=
"thingfilter">    <span class=
"idlMemberType">Dictionary                   <span class=
"idlMemberName"><a data-lt="description" href=
"#dom-thingfilter-description" class="internalDFN" data-link-type=
"dfn" data-for=
"ThingFilter">

"https://heycam.github.io/webidl/#idl-USVString">USVString            url;

data-title="query" data-dfn-for="thingfilter">    USVString            query;

data-idl="" data-title="constraints" data-dfn-for=
"thingfilter">    sequence<Dictionary> constraints;

};

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 url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, such as a Thing Directory dictionary may be extended later with further attributes. or a Thing.

3.1.2

The DiscoveryMethod query enumeration <span class="idlEnum" id= "idl-def-discoverymethod" data-idl="" data-title= "DiscoveryMethod">enum <a data-lt= "DiscoveryMethod" href="#dom-discoverymethod" class="internalDFN" data-link-type="dfn" data-for= ""> { <a href="#dom-discoverymethod-any" class= "idlEnumItem">"any", <a href="#dom-discoverymethod-local" class= "idlEnumItem">"local", <a href="#dom-discoverymethod-nearby" class= "idlEnumItem">"nearby", <a href="#dom-discoverymethod-directory" class= "idlEnumItem">"directory", <a href="#dom-discoverymethod-broadcast" class= "idlEnumItem">"broadcast", <a href="#dom-discoverymethod-other" class= "idlEnumItem">"other" }; property represents a query string accepted by the implementation, for instance a SPARQL query.

The DiscoveryMethod constraints enumeration property represents additional information for the discovery type method in the form of a list of sets of property-value pairs (dictionaries). The list elements (dictionaries) are in OR relationship, and within a constraint dictionary the key-value pairs are in AND relationship. Implementations SHOULD make the following mapping from the constraint dictionaries to be used: " any SemanticAnnotations " does not provide any restriction : for each property-value pair in a constraint dictionary,

  • " Each property name in the constraint dictionary SHOULD match the either the local name " for discovering Thing s property of a defined in the same device " nearby SemanticType " for discovering Thing s nearby on the device, e.g. by Bluetooth target Thing object, or NFC the name of a Property on the target Thing .
  • " When the name matches, the values are compared. If the values match, the constraint is matched.
Editor's note

Constraints are experimental feature, implementations are not required to support them.

Editor's note

Semantic annotations need revisiting in order to simplify their representation. In the [ WOT-TD ] specification they represent the directory @type construct. At the moment only @context , @type and @id constructs are used in the TD .

" for discovery based on a service provided by a directory or repository of Thing s " 3.2 The broadcast fetch() " for method

Accepts an open ended discovery based on sending url argument and returns a request to Promise that resolves with a broadcast address " other ThingDescription .

3.3 The ThingDescription " for a proprietary method defined by type

Representation of the solution. Thing Description , 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 .

3.2 3.4 The consume() method

Accepts an url td argument and returns a of type Promise ThingDescription of and returns a ConsumedThing . object instantiated based on that description.

3.3 3.5 The expose() produce() method

Returns Accepts a model argument of type ThingModel Promise of a locally created and returns an ExposedThing object, locally created based on the provided initialization parameters. Editor's note The reason An ExposedThing s are can be created by in the following ways:

  1. from an initial model (including a factory method instead user given name and semantic annotations ), then adding properties, actions, events and request handlers;
  2. from a Thing Description (possibly of a constructor ConsumedThing object), then adding request handlers.

3.6 The ThingModel type

A Thing model is that an used for producing a new ExposedThing may and can be created in the local WoT Runtime either a ThingTemplate , or in a remote runtime. Even though currently only local creation is supported, the method is designed with this possible future compatibility in mind. ThingDescription .

3.3.1 3.7 The ThingInit SemanticAnnotations dictionary

A dictionary that provides the semantic types and semantic metadata.

"idl-def-thinginit" data-idl="" data-title=
"ThingInit">dictionary <a data-lt=
"ThingInit" href="#dom-thinginit" class="internalDFN"
data-link-type="dfn" data-for=
""> {
<span class="idlMember" id="idl-def-thinginit-name" data-idl=""
data-title="name" data-dfn-for="thinginit">    <span class=
"idlMemberType"><a href=
"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name"
href="#dom-thinginit-name" class="internalDFN" data-link-type="dfn"
data-for="ThingInit">
<span class="idlMember" id="idl-def-thinginit-url" data-idl=""
data-title="url" data-dfn-for="thinginit">    <span class=

"idl-def-semanticannotations" data-idl="" data-title=
"SemanticAnnotations">dictionary SemanticAnnotations {

"idl-def-semanticannotations-semantictype" data-idl="" data-title=
"semanticType" data-dfn-for="semanticannotations">    
"idlMemberType">"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-lt="url"
href="#dom-thinginit-url" class="internalDFN" data-link-type="dfn"
data-for="ThingInit">
<span class="idlMember" id="idl-def-thinginit-description"
data-idl="" data-title="description" data-dfn-for=
"thinginit">    <span class=
"idlMemberType">Dictionary <span class=
"idlMemberName"><a data-lt="description" href=
"#dom-thinginit-description" class="internalDFN" data-link-type=
"dfn" data-for=
"ThingInit">

"https://heycam.github.io/webidl/#idl-sequence">sequence<SemanticType>     semanticType;

data-idl="" data-title="metadata" data-dfn-for=
"semanticannotations">    sequence<SemanticMetadata> metadata;

};

The ThingInit semanticType property denotes a list of SemanticType objects that define the semantic types that can be used in semantic metadata type-value pairs.

The metadata property denotes a list of SemanticMetadata objects (type-value pairs).

3.8 The SemanticType dictionary contains properties to initialize

"idl-def-semantictype" data-idl="" data-title=
"SemanticType">dictionary SemanticType {

data-title="name" data-dfn-for=
"semantictype">    required DOMString name;

"" data-title="context" data-dfn-for=
"semantictype">    required USVString context;

"" data-title="prefix" data-dfn-for=
"semantictype">             DOMString prefix;
};

Represents a Thing : semantic type annotation, containing a name, a context and a prefix.

Editor's note

Semantic type examples to be added.

3.9 The SemanticMetadata dictionary


"idl-def-semanticmetadata" data-idl="" data-title=
"SemanticMetadata">dictionary SemanticMetadata {

data-idl="" data-title="type" data-dfn-for=
"semanticmetadata">    SemanticType type;

data-idl="" data-title="value" data-dfn-for=
"semanticmetadata">    any          value;
};

The SemanticMetadata dictionary describes a pair of semantic type and value:

3.10 The ThingTemplate dictionary

A Thing Template is a dictionary that provides a user given name, and the semantic types and semantic metadata attached to the ExposedThing Thing Description 's root level.


"idl-def-thingtemplate" data-idl="" data-title=
"ThingTemplate">dictionary ThingTemplate : SemanticAnnotations {

data-title="name" data-dfn-for=
"thingtemplate">    required DOMString name;
};

The ThingTemplate dictionary extends SemanticAnnotations and contains properties to initialize a Thing :

Editor's note

Support for configuration and security data might be added later.

3.4 3.11 Examples

Example 1 : Discover Things via directory
<span class= "hljs-keyword">let };
"hljs-keyword">let discoveryFilter = {
  method: 
"hljs-string">"directory",
  url: 
"hljs-string">"http://directory.wotservice.org"
};

"hljs-keyword">let subscription = wot.discover(discoveryType).subscribe(

"hljs-keyword">let subscription = wot.discover(discoveryFilter).subscribe(

  thing => { console.log("hljs-string">"Found Thing " + thing.url); },

"hljs-string">"Found Thing " + thing.name); },

  error => { console.log("Discovery finished because an error: " + error.message); },
  () => { console.log("Discovery finished successfully");}
);
setTimeout(
  <span class=
"hljs-params">()); },

setTimeout( () => {
    subscription.unsubscribe();
    console.log(
"hljs-string">"Discovery timeout");
  },


5000

);
Note

Note that canceling a discovery (through unsubscribe) 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
<span class=
let subscription = wot.discover({ method: "local" }).subscribe(
  thing => { console.log("hljs-string">"Found local Thing " + thing.url); },

"hljs-string">"Found local Thing " + thing.name); },

  error => { console.log("Discovery error: " + error.message); },
  () => { console.log("Discovery finished successfully");}
);
Example 3 : Same as above but with different Observable syntax

"hljs-keyword">let subscription = wot.discover({ method: "local" }).subscribe({
  thing => { console.log("Found local Thing " + thing.name); },
  error: 
"hljs-function">err => { console.log("Discovery error: " + err.message); },
  complete: 
"hljs-function">() => { console.log("Discovery finished successfully");}
});
Example 4 : Discover Things exposed nearby, e.g. via Bluetooth or NFC
<span class= "hljs-keyword">let} }).subscribe(
"hljs-keyword">let subscription = wot.discover({
  method: 
"hljs-string">"nearby",
  constraints: [{ 
"hljs-attr">protocol: "BLE-4.2" }, { protocol: "NFC"}]
}).subscribe(

  thing => { console.log("hljs-string">"Found nearby Thing " + thing.url); },

"hljs-string">"Found nearby Thing " + thing.name); },

  error => { console.log("Discovery error: " + error.message); },
  () => { console.log("Discovery finished successfully");}
);
Example 4 5 : Discover Things exposed in a proprietary way
<span class= "hljs-keyword">let} }).subscribe(
"hljs-keyword">let subscription = wot.discover({
  method: 
"hljs-string">"other",
  constraints: [{ 
"hljs-attr">solution: "XYZ123", key: "..."}]
}).subscribe(

  thing => { console.log("hljs-string">"Found Thing " + thing.url); },

"hljs-string">"Found Thing " + thing.name); },

  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, Properties , invoke Actions , and observe properties, Actions Properties and Events .

"ConsumedThing">interface <a data-lt=
"ConsumedThing" href="#dom-consumedthing" class="internalDFN"
data-link-type="dfn" data-for=
""> {

"ConsumedThing">interface ConsumedThing {

    readonly attribute "https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name"
href="#dom-consumedthing-name" class="internalDFN" data-link-type=
"dfn" data-for="ConsumedThing">
<span class="idlAttribute" id="idl-def-consumedthing-url" data-idl=
"" data-title="url" data-dfn-for=
"consumedthing">    readonly attribute <span class=
"idlAttrType"><a href=
"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-lt="url"
href="#dom-consumedthing-url" class="internalDFN" data-link-type=
"dfn" data-for="ConsumedThing">
<span class="idlAttribute" id="idl-def-consumedthing-description"
data-idl="" data-title="description" data-dfn-for=
"consumedthing">    readonly attribute <span class=
"idlAttrType"><a href="#dom-thingdescription" class="internalDFN"

"https://heycam.github.io/webidl/#idl-DOMString">DOMString name;

"idl-def-consumedthing-getthingdescription" data-idl="" data-title=
"getThingDescription" data-dfn-for="consumedthing">    
data-link-type=
"dfn">ThingDescription "idlAttrName"><a data-lt="description" href=
"#dom-consumedthing-description" class="internalDFN"
data-link-type="dfn" data-for=
"ConsumedThing">
<span class="idlMethod" id=
"idl-def-consumedthing-invokeaction(name,parameters)" data-idl=""
data-title="invokeAction" data-dfn-for=
"consumedthing">    <a href=
"https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="invokeAction()|invokeaction()|invokeAction"
data-lt-nodefault="" href="#dom-consumedthing-invokeaction()"
class="internalDFN" data-link-type="dfn" data-for=
"ConsumedThing">invokeAction(<span class=
"idlParam"><a href=
"https://heycam.github.io/webidl/#idl-DOMString">DOMString
<span class="idlMethod" id=
"idl-def-consumedthing-setproperty(name,value)" data-idl=""
data-title="setProperty" data-dfn-for=
"consumedthing">    <a href=
"https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="setProperty()|setproperty()|setProperty"
data-lt-nodefault="" href="#dom-consumedthing-setproperty()" class=
"internalDFN" data-link-type="dfn" data-for=
"ConsumedThing">setProperty(<span class=
"idlParam"><a href=
"https://heycam.github.io/webidl/#idl-DOMString">DOMString

"idlMethName">getThingDescription();

"idl-def-consumedthing-getproperty(name)" data-idl="" data-title=
"getProperty" data-dfn-for="consumedthing">    <span class=

"idl-def-consumedthing-readproperty-name" data-idl="" data-title=
"readProperty" data-dfn-for="consumedthing">    
"idlMethType">"https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="getProperty()|getproperty()|getProperty"
data-lt-nodefault="" href="#dom-consumedthing-getproperty()" class=
"internalDFN" data-link-type="dfn" data-for=
"ConsumedThing">getProperty(<span class=

"https://heycam.github.io/webidl/#idl-promise">Promise<any>     readProperty(
"idlParam">DOMString name);
"idl-def-consumedthing-addlistener(eventname,listener)" data-idl=""
data-title="addListener" data-dfn-for=

"idl-def-consumedthing-writeproperty-name-value" data-idl=""
data-title="writeProperty" data-dfn-for=

"consumedthing">    "#dom-consumedthing" class="internalDFN" data-link-type=
"dfn"> <span class=
"idlMethName"><a data-lt="addListener()|addlistener()|addListener"
data-lt-nodefault="" href="#dom-consumedthing-addlistener()" class=
"internalDFN" data-link-type="dfn" data-for=
"ConsumedThing">addListener(<span class=

"https://heycam.github.io/webidl/#idl-promise">Promise<void>    writeProperty(
"idlParam">"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a href="#dom-thingeventlistener"
class="internalDFN" data-link-type=
"dfn"> <span class=
"idlParamName">listener

"https://heycam.github.io/webidl/#idl-DOMString">DOMString name, any value);

"idl-def-consumedthing-removelistener(eventname,listener)"
data-idl="" data-title="removeListener" data-dfn-for=

"idl-def-consumedthing-invokeaction-name-parameters" data-idl=""
data-title="invokeAction" data-dfn-for=

"consumedthing">    "#dom-consumedthing" class="internalDFN" data-link-type=
"dfn"> <span class=
"idlMethName"><a data-lt=
"removeListener()|removelistener()|removeListener"
data-lt-nodefault="" href="#dom-consumedthing-removelistener()"
class="internalDFN" data-link-type="dfn" data-for=
"ConsumedThing">removeListener(<span class=
"idlParam"><a href=
"https://heycam.github.io/webidl/#idl-DOMString">DOMString,
                                 <span class=

"https://heycam.github.io/webidl/#idl-promise">Promise<any>     invokeAction(
"idlParam">"#dom-thingeventlistener" class="internalDFN" data-link-type=
"dfn"> <span class=
"idlParamName">listener

"https://heycam.github.io/webidl/#idl-DOMString">DOMString name, any parameters);

"idl-def-consumedthing-removealllisteners(eventname)" data-idl=""
data-title="removeAllListeners" data-dfn-for=

"idl-def-consumedthing-onpropertychange-name" data-idl=""
data-title="onPropertyChange" data-dfn-for=

"consumedthing">    "#dom-consumedthing" class="internalDFN" data-link-type=
"dfn"> <span class=
"idlMethName"><a data-lt=
"removeAllListeners()|removealllisteners()|removeAllListeners"
data-lt-nodefault="" href="#dom-consumedthing-removealllisteners()"
class="internalDFN" data-link-type="dfn" data-for=
"ConsumedThing">removeAllListeners(<span class=
"idlParam">optional <a href=
"https://heycam.github.io/webidl/#idl-DOMString">DOMString
<span class="idlMethod" id=
"idl-def-consumedthing-observe(name,requesttype)" data-idl=""
data-title="observe" data-dfn-for="consumedthing">    <span class=
"idlMethType"><a href="#dfn-observable" class="internalDFN"
data-link-type="dfn">Observable    <span class=
"idlMethName"><a data-lt="observe()|observe()|observe"
data-lt-nodefault="" href="#dom-consumedthing-observe()" class=
"internalDFN" data-link-type="dfn" data-for=
"ConsumedThing">observe(<span class=

"#dom-observable" class="internalDFN" data-link-type=
"dfn">Observable       onPropertyChange(
"idlParam">"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a href="#dom-requesttype"

"https://heycam.github.io/webidl/#idl-DOMString">DOMString name);

data-idl="" data-title="onEvent" data-dfn-for=
"consumedthing">    Observable       
class="internalDFN" data-link-type=
"dfn"> <span class=
"idlParamName">requestType
};
<span class="idlCallback" id="idl-def-thingeventlistener" data-idl=
"" data-title="ThingEventListener">callback <span class=
"idlCallbackID"><a data-lt="ThingEventListener" href=
"#dom-thingeventlistener" class="internalDFN" data-link-type="dfn"
data-for=
""> = <span class=
"idlCallbackType">void<span class=
"idlParamType"><a href="#dfn-event" class="internalDFN"
data-link-type="dfn">Event <span class=
"idlParamName">
event
);

"dfn">onEvent(DOMString name);

data-idl="" data-title="onTDChange" data-dfn-for=
"consumedthing">    Observable       onTDChange();
};


Represents ConsumedThing represents a local proxy object of the remote Thing .

4.1 The name read-only attribute represents the name of the Thing . property

The url name read-only attribute property represents the URL name of the Thing as specified in the TD . In this version it is read only.

4.2 The description getThingDescription() attribute read-only attribute represents method

Returns the description Thing Description of the Thing .

Editor's note

In this version, introspection based on TD is out of scope. Parsing and exposing Thing Description s is discussed in Issue 38 .

4.1 4.3 The invokeAction() readProperty() method

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

4.2 4.4 The setProperty() writeProperty() 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 4.5 The getProperty() invokeAction() method

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

4.4 4.6 The addListener() onPropertyChange() method

Adds the listener provided in the argument listener to the Event name provided in the argument eventName . 4.5 The Returns an removeListener() Observable method Removes a listener from for the Event Property identified by specified in the provided eventName name argument, allowing subscribing to and listener argument. unsubscribing from notifications.

4.6

The callback function passed to the removeAllListeners() subscribe() method Removes all listeners for when invoked on the Event provided by returned observer will receive the eventName optional argument, or if that was not provided, then removes all listeners from all Events . new property value each time it is changed.

4.7 The observe() onEvent() method

Returns an Observable for the Property , Event or Action specified in the name argument, allowing subscribing to and unsubscribing to from 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 passed to the Events defined in ExposedThing events . The event types are described in this section. 4.9.1 The PropertyChangeEvent interface <span class="idlInterface" id= "idl-def-propertychangeevent" data-idl="" data-title= "PropertyChangeEvent">[<span class= "extAttrName"><a href= "https://heycam.github.io/webidl/#Constructor">Constructor<a href="#dom-propertychangeeventinit" class="internalDFN" data-link-type= "dfn"> <span class= "idlParamName">init] interface <a data-lt= "PropertyChangeEvent" href="#dom-propertychangeevent" class= "internalDFN" data-link-type="dfn" data-for= ""> : <span class= "idlSuperclass"><a href="#dfn-event" class="internalDFN" data-link-type="dfn">Event { <span class="idlAttribute" id="idl-def-propertychangeevent-data" data-idl="" data-title="data" data-dfn-for= "propertychangeevent"> readonly attribute <span class= "idlAttrType"><a href="#dom-propertychangeeventinit" class= "internalDFN" data-link-type= "dfn"> <span class= "idlAttrName"><a data-lt="data" href= "#dom-propertychangeevent-data" class="internalDFN" data-link-type= "dfn" data-for= "PropertyChangeEvent"> }; The data attribute represents the changed Property . 4.9.1.1 The PropertyChangeEventInit dictionary <span class="idlDictionary" id= "idl-def-propertychangeeventinit" data-idl="" data-title= "PropertyChangeEventInit">dictionary <span class= "idlDictionaryID"><a data-lt="PropertyChangeEventInit" href= "#dom-propertychangeeventinit" class="internalDFN" data-link-type= "dfn" data-for=""> { <span class="idlMember" id="idl-def-propertychangeeventinit-name" data-idl="" data-title="name" data-dfn-for= "propertychangeeventinit"> <a href= "https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name" href="#dom-propertychangeeventinit-name" class="internalDFN" data-link-type="dfn" data-for= "PropertyChangeEventInit"> <span class="idlMember" id="idl-def-propertychangeeventinit-value" data-idl="" data-title="value" data-dfn-for= "propertychangeeventinit"> <a href= "https://heycam.github.io/webidl/#idl-any">any<a data-lt="value" href="#dom-propertychangeeventinit-value" class="internalDFN" data-link-type="dfn" data-for= "PropertyChangeEventInit"> }; The name > attribute represents the Property name. The value subscribe() attribute represents the new value of method when invoked on the Property . 4.9.2 The ActionInvocationEvent interface <span class="idlInterface" id= "idl-def-actioninvocationevent" data-idl="" data-title= "ActionInvocationEvent">[<span class= "extAttrName"><a href= "https://heycam.github.io/webidl/#Constructor">Constructor<a href="#dom-actioninvocationeventinit" class="internalDFN" data-link-type= "dfn">] interface <a data-lt= "ActionInvocationEvent" href="#dom-actioninvocationevent" class= "internalDFN" data-link-type="dfn" data-for= ""> : <span class= "idlSuperclass"><a href="#dfn-event" class="internalDFN" data-link-type="dfn">Event { <span class="idlAttribute" id="idl-def-actioninvocationevent-data" data-idl="" data-title="data" data-dfn-for= "actioninvocationevent"> readonly attribute <span class= "idlAttrType"><a href="#dom-actioninvocationeventinit" class= "internalDFN" data-link-type= "dfn"><a data-lt="data" href="#dom-actioninvocationevent-data" class="internalDFN" data-link-type="dfn" data-for= "ActionInvocationEvent"> }; The data attribute represents returned observer will receive the notification event data from the Action invocation. 4.9.2.1 The ActionInvocationEventInit dictionary <span class="idlDictionary" id= "idl-def-actioninvocationeventinit" data-idl="" data-title= "ActionInvocationEventInit">dictionary <span class= "idlDictionaryID"><a data-lt="ActionInvocationEventInit" href= "#dom-actioninvocationeventinit" class="internalDFN" data-link-type="dfn" data-for= ""> { <span class="idlMember" id= "idl-def-actioninvocationeventinit-actionname" data-idl="" data-title="actionName" data-dfn-for= "actioninvocationeventinit"> <span class= "idlMemberType"><a data-lt="actionName" href="#dom-actioninvocationeventinit-actionname" class= "internalDFN" data-link-type="dfn" data-for= "ActionInvocationEventInit"> <span class="idlMember" id= "idl-def-actioninvocationeventinit-returnvalue" data-idl="" data-title="returnValue" data-dfn-for= "actioninvocationeventinit"> <span class= "idlMemberType"><a data-lt="returnValue" href="#dom-actioninvocationeventinit-returnvalue" class= "internalDFN" data-link-type="dfn" data-for= "ActionInvocationEventInit"> }; 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 each time the Action . event is fired.

4.9.3 4.8 The ThingDescriptionChangeEvent onTDChange() interface <span class="idlInterface" id= "idl-def-thingdescriptionchangeevent" data-idl="" data-title= "ThingDescriptionChangeEvent">[<span class= "extAttrName"><a href= "https://heycam.github.io/webidl/#Constructor">Constructor<a href="#dom-thingdescriptionchangeeventinit" class="internalDFN" data-link-type= "dfn">] interface <a data-lt= "ThingDescriptionChangeEvent" href= "#dom-thingdescriptionchangeevent" class="internalDFN" data-link-type="dfn" data-for= ""><a href="#dfn-event" class="internalDFN" data-link-type="dfn">Event { <span class="idlAttribute" id= "idl-def-thingdescriptionchangeevent-data" data-idl="" data-title= "data" data-dfn-for= "thingdescriptionchangeevent"> readonly attribute <span class= "idlAttrType"><a href="#dom-thingdescriptionchangeeventinit" class= "internalDFN" data-link-type= "dfn"><a data-lt="data" href="#dom-thingdescriptionchangeevent-data" class="internalDFN" data-link-type="dfn" data-for= "ThingDescriptionChangeEvent"> }; method

The Returns an data Observable attribute represents the changes that occurred , allowing subscribing to and unsubscribing from notifications to the Thing Description .

4.9.3.1 The ThingDescriptionChangeEventInit dictionary <span class="idlDictionary" id= "idl-def-thingdescriptionchangeeventinit" data-idl="" data-title= "ThingDescriptionChangeEventInit">dictionary <span class= "idlDictionaryID"><a data-lt="ThingDescriptionChangeEventInit" href="#dom-thingdescriptionchangeeventinit" class="internalDFN" data-link-type="dfn" data-for= ""> { <span class="idlMember" id= "idl-def-thingdescriptionchangeeventinit-type" data-idl="" data-title="type" data-dfn-for= "thingdescriptionchangeeventinit"> <span class= "idlMemberType"><a href="#dom-tdchangetype" class="internalDFN" data-link-type= "dfn"> <span class= "idlMemberName"><a data-lt="type" href= "#dom-thingdescriptionchangeeventinit-type" class="internalDFN" data-link-type="dfn" data-for= "ThingDescriptionChangeEventInit"> <span class="idlMember" id= "idl-def-thingdescriptionchangeeventinit-method" data-idl="" data-title="method" data-dfn-for= "thingdescriptionchangeeventinit"> <span class= "idlMemberType"><a href="#dom-tdchangemethod" class="internalDFN" data-link-type= "dfn"> <span class= "idlMemberName"><a data-lt="method" href= "#dom-thingdescriptionchangeeventinit-method" class="internalDFN" data-link-type="dfn" data-for= "ThingDescriptionChangeEventInit"> <span class="idlMember" id= "idl-def-thingdescriptionchangeeventinit-name" data-idl="" data-title="name" data-dfn-for= "thingdescriptionchangeeventinit"> <span class= "idlMemberType"><a href= "https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name" href="#dom-thingdescriptionchangeeventinit-name" class= "internalDFN" data-link-type="dfn" data-for= "ThingDescriptionChangeEventInit"> <span class="idlMember" id= "idl-def-thingdescriptionchangeeventinit-data" data-idl="" data-title="data" data-dfn-for= "thingdescriptionchangeeventinit"> <span class= "idlMemberType"><a href="#dom-tdchangedata" class="internalDFN" data-link-type= "dfn"> <span class= "idlMemberName"><a data-lt="data" href= "#dom-thingdescriptionchangeeventinit-data" class="internalDFN" data-link-type="dfn" data-for= "ThingDescriptionChangeEventInit"> <span class="idlMember" id= "idl-def-thingdescriptionchangeeventinit-description" data-idl="" data-title="description" data-dfn-for= "thingdescriptionchangeeventinit"> <span class= "idlMemberType"><a href="#dom-thingdescription" class="internalDFN" data-link-type= "dfn"> <span class= "idlMemberName"><a data-lt="description" href= "#dom-thingdescriptionchangeeventinit-description" class= "internalDFN" data-link-type="dfn" data-for= "ThingDescriptionChangeEventInit"> }; 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 <span class="idlEnum" id= "idl-def-tdchangemethod" data-idl="" data-title= "TDChangeMethod">enum <a data-lt= "TDChangeMethod" href="#dom-tdchangemethod" class="internalDFN" data-link-type="dfn" data-for= ""> { <a href="#dom-tdchangemethod-add" class= "idlEnumItem">"add", <a href="#dom-tdchangemethod-remove" class= "idlEnumItem">"remove", <a href="#dom-tdchangemethod-change" class= "idlEnumItem">"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 <span class="idlEnum" id= "idl-def-tdchangetype" data-idl="" data-title= "TDChangeType">enum <a data-lt= "TDChangeType" href="#dom-tdchangetype" class="internalDFN" data-link-type="dfn" data-for= ""> { <a href="#dom-tdchangetype-property" class= "idlEnumItem">"property", <a href="#dom-tdchangetype-action" class= "idlEnumItem">"action", <a href="#dom-tdchangetype-event" class= "idlEnumItem">"event" }; <span class="idlTypedef" id="idl-def-tdchangedata" data-idl="" data-title="TDChangeData">typedef <span class= "idlTypedefType">(<a href="#dom-thingpropertyinit" class= "internalDFN" data-link-type= "dfn"> or <a href= "#dom-thingactioninit" class="internalDFN" data-link-type= "dfn"> or <a href= "#dom-thingeventinit" class="internalDFN" data-link-type= "dfn"> <span class= "idlTypedefID"><a data-lt="TDChangeData" href="#dom-tdchangedata" class="internalDFN" data-link-type="dfn" data-for= ""> TDChangeData ;

The property value tells callback function passed to the operation was applied on a Property definition. The action subscribe() value tells the operation was applied method when invoked 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 returned observer will receive the new description of the changed element. Depending on the change type, Thing Description each time it can be either a ThingPropertyInit , ThingActionInit , or ThingEventInit . is changed.

4.10 4.9 Examples

Below a ConsumedThing interface example is given.

Example 5 6 : Consume a Thing
wot.consume(<span class= "hljs-string">"http://mmyservice.org/mySensor" { .log(<span class= "hljs-string">"Thing " + thing.name + <span class= "hljs-string">" has been consumed."); .log(<span class= "hljs-string">"{ " + <span class= "hljs-built_in">JSON.serialize(thing) + <span class= "hljs-string">" }"); thing.addListener(<span class= "hljs-string">"onchange", <span class= "hljs-function"><span class= "hljs-keyword">function(<span class= "hljs-params">event{ (event <span class= "hljs-keyword">instanceof PropertyChangeEvent) { <span class= "hljs-built_in">console.log(<span class= "hljs-string">"Property " + event.name + <span class= "hljs-string">" value has changed to " + event.value); } }).invokeAction(<span class= "hljs-string">"startMeasurement", [<span class= "hljs-string">"Celsius"]); }, ).catch(<span class= "hljs-params">error { .log(<span class= "hljs-string">"Discovery finished because an error: " + error.message); });
try {
  let td = await wot.fetch("http://mmyservice.org/mySensor");
  let thing = wot.consume(td);
  console.log("Thing " + thing.name + " has been consumed.");
  let subscription = thing.onPropertyChange("temperature")
    .subscribe(function(value) {
      console.log("Temperature + " has changed to " + value);
    });
  thing.invokeAction("startMeasurement", { units: "Celsius" })
    .then(() => { console.log("Temperature measurement started."); })
    .catch(e => {
       console.log("Error starting measurement.");
       subscription.unsubscribe();
     })
} catch(error) {
  console.log("Error during fetch or consume: " + 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 . It also implements the ConsumedThing interface. An ExposedThing is created by the produce() method.

<span class="idlTypedef" id= "idl-def-thingdescription" data-idl="" data-title= "ThingDescription">typedef <a href= "https://heycam.github.io/webidl/#idl-USVString">USVString<a data-lt="ThingDescription" href="#dom-thingdescription" class="internalDFN" data-link-type= "dfn" data-for="">
<span class="idlCallback" id="idl-def-requesthandler" data-idl="" data-title="RequestHandler">callback <span class= "idlCallbackID"><a data-lt="RequestHandler" href= "#dom-requesthandler" class="internalDFN" data-link-type="dfn" data-for=""> = <span class= "idlCallbackType"><a href= "https://heycam.github.io/webidl/#idl-any">any<a href="#dom-request" class="internalDFN" data-link-type= "dfn"> <span class= "idlParamName">request Editor's note

It is under consideration to use a constructor for ExposedThing instead of a factory method.


"#dom-exposedthing" class="internalDFN" data-link-type=
"dfn">ExposedThing implements ConsumedThing;

interface "idlInterfaceID"><a data-lt="ExposedThing" href="#dom-exposedthing"
class="internalDFN" data-link-type="dfn" data-for=
""> {

"idlInterfaceID">ExposedThing {

"idlSectionComment">    // define how to expose and run the Thing

data-title="start" data-dfn-for="exposedthing">    Promise<void> start();

data-title="stop" data-dfn-for="exposedthing">    Promise<void> stop();

"idl-def-exposedthing-register-directory" data-idl="" data-title=
"register" data-dfn-for="exposedthing">    Promise<void> register(optional USVString directory);

"idl-def-exposedthing-unregister-directory" data-idl="" data-title=
"unregister" data-dfn-for="exposedthing">    Promise<void> unregister(optional USVString directory);

"idl-def-exposedthing-emitevent-eventname-payload" data-idl=""
data-title="emitEvent" data-dfn-for="exposedthing">    Promise<void> emitEvent(DOMString eventName, any payload);

    // define Thing Description modifiers
"idl-def-exposedthing-addproperty(property)" data-idl=""
data-title="addProperty" data-dfn-for=
"exposedthing">    <a href=
"#dom-exposedthing" class="internalDFN" data-link-type=

"idl-def-exposedthing-addproperty-property" data-idl="" data-title=
"addProperty" data-dfn-for="exposedthing">    
"dfn">ExposedThing  "idlMethName"><a data-lt="addProperty()|addproperty()|addProperty"
data-lt-nodefault="" href="#dom-exposedthing-addproperty()" class=
"internalDFN" data-link-type="dfn" data-for=
"ExposedThing">addProperty(<span class=
"idlParam"><a href=
"#dom-thingpropertyinit" class="internalDFN" data-link-type=
"dfn"> <span class=

"idlMethName">addProperty(ThingProperty 
"idlParamName">property);
"idl-def-exposedthing-removeproperty(name)" data-idl="" data-title=

"idl-def-exposedthing-removeproperty-name" data-idl="" data-title=

"removeProperty" data-dfn-for="exposedthing">    ExposedThing  "idlMethName"><a data-lt=
"removeProperty()|removeproperty()|removeProperty"
data-lt-nodefault="" href="#dom-exposedthing-removeproperty()"
class="internalDFN" data-link-type="dfn" data-for=
"ExposedThing">removeProperty(<span class=

"idlMethName">removeProperty(
"idlParam">DOMString name);
<span class="idlMethod" id="idl-def-exposedthing-addaction(action)"

    ExposedThing  "idlMethName"><a data-lt="addAction()|addaction()|addAction"
data-lt-nodefault="" href="#dom-exposedthing-addaction()" class=
"internalDFN" data-link-type="dfn" data-for=
"ExposedThing">addAction(<span class=
"idlParam"><a href=
"#dom-thingactioninit" class="internalDFN" data-link-type=
"dfn"> <span class=
"idlParamName">action
<span class="idlMethod" id=
"idl-def-exposedthing-removeaction(name)" data-idl="" data-title=
"removeAction" data-dfn-for="exposedthing">    <span class=
"idlMethType"><a href="#dom-exposedthing" class="internalDFN"

"idlMethName">addAction(
data-link-type=
"dfn">ThingAction action);

data-idl="" data-title="removeAction" data-dfn-for=
"exposedthing">    
"dfn">ExposedThing  "idlMethName"><a data-lt=
"removeAction()|removeaction()|removeAction" data-lt-nodefault=""
href="#dom-exposedthing-removeaction()" class="internalDFN"
data-link-type="dfn" data-for=
"ExposedThing">removeAction(<span class=

"idlMethName">removeAction(
"idlParam">DOMString name);
<span class="idlMethod" id="idl-def-exposedthing-addevent(event)"

    ExposedThing  "idlMethName"><a data-lt="addEvent()|addevent()|addEvent"
data-lt-nodefault="" href="#dom-exposedthing-addevent()" class=
"internalDFN" data-link-type="dfn" data-for=
"ExposedThing">addEvent(<span class=
"idlParam"><a href="#dom-thingeventinit"

"idlMethName">
class="internalDFN" data-link-type=
"dfn"> <span class=
"idlParamName">event
<span class="idlMethod" id="idl-def-exposedthing-removeevent(name)"

"dfn">addEvent(ThingEvent event);
    ExposedThing  "idlMethName"><a data-lt="removeEvent()|removeevent()|removeEvent"
data-lt-nodefault="" href="#dom-exposedthing-removeevent()" class=
"internalDFN" data-link-type="dfn" data-for=
"ExposedThing">removeEvent(<span class=
"idlParam"><a href=

"idlMethName">removeEvent(
"https://heycam.github.io/webidl/#idl-DOMString">DOMString name);
    // define request handlers
"idl-def-exposedthing-onretrieveproperty(handler)" data-idl=""
data-title="onRetrieveProperty" data-dfn-for=

"idl-def-exposedthing-setpropertyreadhandler-name-readhandler"
data-idl="" data-title="setPropertyReadHandler" data-dfn-for=

"exposedthing">    ExposedThing  "idlMethName"><a data-lt=
"onRetrieveProperty()|onretrieveproperty()|onRetrieveProperty"
data-lt-nodefault="" href="#dom-exposedthing-onretrieveproperty()"
class="internalDFN" data-link-type="dfn" data-for=
"ExposedThing">onRetrieveProperty(<span class=
"idlParam"><a href="#dom-requesthandler"
class="internalDFN" data-link-type=
"dfn"> <span class=
"idlParamName">handler

"idlMethName">setPropertyReadHandler(DOMString name,
                                         
"idlParam">PropertyReadHandler readHandler);

"idl-def-exposedthing-onupdateproperty(handler)" data-idl=""
data-title="onUpdateProperty" data-dfn-for=

"idl-def-exposedthing-setpropertywritehandler-name-writehandler"
data-idl="" data-title="setPropertyWriteHandler" data-dfn-for=

"exposedthing">    ExposedThing  "idlMethName"><a data-lt=
"onUpdateProperty()|onupdateproperty()|onUpdateProperty"
data-lt-nodefault="" href="#dom-exposedthing-onupdateproperty()"
class="internalDFN" data-link-type="dfn" data-for=
"ExposedThing">onUpdateProperty(<span class=
"idlParam"><a href="#dom-requesthandler"
class="internalDFN" data-link-type=
"dfn"> <span class=
"idlParamName">handler

"idlMethName">setPropertyWriteHandler(DOMString name,
                                          
"idlParam">PropertyWriteHandler writeHandler);

"idl-def-exposedthing-oninvokeaction(handler)" data-idl=""
data-title="onInvokeAction" data-dfn-for=

"idl-def-exposedthing-setactionhandler-name-action" data-idl=""
data-title="setActionHandler" data-dfn-for=

"exposedthing">    ExposedThing  "idlMethName"><a data-lt=
"onInvokeAction()|oninvokeaction()|onInvokeAction"
data-lt-nodefault="" href="#dom-exposedthing-oninvokeaction()"
class="internalDFN" data-link-type="dfn" data-for=
"ExposedThing">onInvokeAction(<span class=
"idlParam"><a href="#dom-requesthandler"
class="internalDFN" data-link-type=
"dfn"> <span class=
"idlParamName">handler
<span class="idlMethod" id=
"idl-def-exposedthing-onobserve(handler)" data-idl="" data-title=
"onObserve" data-dfn-for="exposedthing">    <span class=
"idlMethType"><a href="#dom-exposedthing" class="internalDFN"
data-link-type=
"dfn">  <span class=
"idlMethName"><a data-lt="onObserve()|onobserve()|onObserve"
data-lt-nodefault="" href="#dom-exposedthing-onobserve()" class=
"internalDFN" data-link-type="dfn" data-for=
"ExposedThing">onObserve(<span class=
"idlParam"><a href="#dom-requesthandler"
class="internalDFN" data-link-type=
"dfn"> <span class=
"idlParamName">handler
<span class=
"idlSectionComment">    // define how to expose and run the Thing
<span class="idlMethod" id=
"idl-def-exposedthing-register(directory)" data-idl="" data-title=
"register" data-dfn-for="exposedthing">    <span class=
"idlMethType"><a href=
"https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="register()|register()|register"
data-lt-nodefault="" href="#dom-exposedthing-register()" class=
"internalDFN" data-link-type="dfn" data-for=
"ExposedThing">register(<span class=
"idlParam">optional <a href=
"https://heycam.github.io/webidl/#idl-USVString">USVString
<span class="idlMethod" id=
"idl-def-exposedthing-unregister(directory)" data-idl=""
data-title="unregister" data-dfn-for=
"exposedthing">    <a href=
"https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="unregister()|unregister()|unregister"
data-lt-nodefault="" href="#dom-exposedthing-unregister()" class=
"internalDFN" data-link-type="dfn" data-for=
"ExposedThing">unregister(<span class=
"idlParam">optional <a href=
"https://heycam.github.io/webidl/#idl-USVString">USVString
<span class="idlMethod" id="idl-def-exposedthing-start()" data-idl=
"" data-title="start" data-dfn-for="exposedthing">    <span class=
"idlMethType"><a href=
"https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="start()|start()|start"
data-lt-nodefault="" href="#dom-exposedthing-start()" class=
"internalDFN" data-link-type="dfn" data-for=
"ExposedThing">start
<span class="idlMethod" id="idl-def-exposedthing-stop()" data-idl=
"" data-title="stop" data-dfn-for="exposedthing">    <span class=
"idlMethType"><a href=
"https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="stop()|stop()|stop"
data-lt-nodefault="" href="#dom-exposedthing-stop()" class=
"internalDFN" data-link-type="dfn" data-for=
"ExposedThing">stop
<span class="idlMethod" id=
"idl-def-exposedthing-emitevent(eventname,payload)" data-idl=""
data-title="emitEvent" data-dfn-for="exposedthing">    <span class=
"idlMethType"><a href=
"https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="emitEvent()|emitevent()|emitEvent"
data-lt-nodefault="" href="#dom-exposedthing-emitevent()" class=
"internalDFN" data-link-type="dfn" data-for=
"ExposedThing">emitEvent(<span class=

"idlMethName">setActionHandler(
"idlParam">"https://heycam.github.io/webidl/#idl-DOMString">DOMString

"https://heycam.github.io/webidl/#idl-DOMString">DOMString name, ActionHandler action);

};
<a href="#dom-exposedthing" class=
"internalDFN" data-link-type=
"dfn"> implements <a href=
"#dom-consumedthing" class="internalDFN" data-link-type=
"dfn">

data-idl="" data-title="PropertyReadHandler">callback PropertyReadHandler = Promise<any> ();

ConsumedThing

data-idl="" data-title="PropertyWriteHandler">callback PropertyWriteHandler = Promise<void> (any value);

data-title="ActionHandler">callback ActionHandler = 
Promise


;

<

href="https://heycam.github.io/webidl/#idl-any">
any

>

(

any

parameters

);


5.1 The ThingDescription start() type method

WoT provides a unified representation Start serving external requests 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 stop() interface method

<span class="idlInterface" id= "idl-def-request" data-idl="" data-title= "Request">interface <a data-lt= "Request" href="#dom-request" class="internalDFN" data-link-type= "dfn" data-for=""> { <span class="idlAttribute" id="idl-def-request-type" data-idl="" data-title="type" data-dfn-for= "request"> readonly attribute <a href= "#dom-requesttype" class="internalDFN" data-link-type= "dfn"> <span class= "idlAttrName"><a data-lt="type" href="#dom-request-type" class= "internalDFN" data-link-type="dfn" data-for= "Request"> <span class="idlAttribute" id="idl-def-request-from" data-idl="" data-title="from" data-dfn-for= "request"> readonly attribute <a href= "https://heycam.github.io/webidl/#idl-USVString">USVString<a data-lt="from" href="#dom-request-from" class="internalDFN" data-link-type="dfn" data-for="Request"> <span class="idlAttribute" id="idl-def-request-name" data-idl="" data-title="name" data-dfn-for= "request"> readonly attribute <a href= "https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name" href="#dom-request-name" class="internalDFN" data-link-type="dfn" data-for="Request"> <span class="idlAttribute" id="idl-def-request-options" data-idl="" data-title="options" data-dfn-for= "request"> readonly attribute <span class= "idlAttrType">Dictionary <span class= "idlAttrName"><a data-lt="options" href="#dom-request-options" class="internalDFN" data-link-type="dfn" data-for= "Request"> <span class="idlAttribute" id="idl-def-request-data" data-idl="" data-title="data" data-dfn-for= "request"> readonly attribute <a href= "https://heycam.github.io/webidl/#idl-any">any<a data-lt="data" href="#dom-request-data" class="internalDFN" data-link-type="dfn" data-for="Request"> <span class="idlMethod" id="idl-def-request-respond(response)" data-idl="" data-title="respond" data-dfn-for= "request"> <a href= "https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="respond()|respond()|respond" data-lt-nodefault="" href="#dom-request-respond()" class= "internalDFN" data-link-type="dfn" data-for= "Request">respond<span class= "idlParamType"><a href= "https://heycam.github.io/webidl/#idl-any">any <span class="idlMethod" id= "idl-def-request-respondwitherror(error)" data-idl="" data-title= "respondWithError" data-dfn-for="request"> <span class= "idlMethType">void<a data-lt= "respondWithError()|respondwitherror()|respondWithError" data-lt-nodefault="" href="#dom-request-respondwitherror()" class= "internalDFN" data-link-type="dfn" data-for= "Request">respondWithError(<span class= "idlParam"><a href= "https://heycam.github.io/webidl/#idl-Error">Error };

Represents an incoming request Stop serving external requests for the Thing .

5.3 The ExposedThing register() method

Generates the Thing Description is supposed to handle, for instance retrieving and updating given the properties, invoking Actions and observing Events Event (WoT interactions). The type attribute represents the type of the request as defined in RequestType . The for this object. If a from directory attribute represents the address of the client device issuing the request. The type of the address (URL, UUID or other) argument is defined by given, make a request to register 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 with the returned value) as key-value pairs. The exact format is specified given WoT repository by the Thing Description . The invoking its data register 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 <span class="idlEnum" id="idl-def-requesttype" data-idl="" data-title="RequestType">enum <span class= "idlEnumID"><a data-lt="RequestType" href="#dom-requesttype" class= "internalDFN" data-link-type="dfn" data-for= ""> { <a href="#dom-requesttype-property" class= "idlEnumItem">"property", <a href="#dom-requesttype-action" class= "idlEnumItem">"action", <a href="#dom-requesttype-event" class= "idlEnumItem">"event", }; 5.4 The value " property unregister() " represents requests to retrieve or update method

If a Property . The value " action " represents requests to invoke an Action . The value " event " represents requests to emit an event. The value " td directory " represents requests argument is given, make a request to change unregister the Thing Description , i.e. to add, remove or modify properties, Actions or Events . Editor's note This functionality is here for with the sake of completeness for future versions of given WoT repository by invoking its unregister Action . Then, and in the API. Currently there is case no corresponding functionality at arguments were provided to this function, stop the ConsumedThing Thing level and it is not guaranteed that a remove the Thing Description could be remotely changed by scripting. .

5.2.2 5.5 The respond() emitEvent() method

Sends a positive response to Emits an the event initialized with the event name specified by the Request eventName based on the Protocol Bindings argument and includes the data specified by the data payload argument.

5.2.3 5.6 The respondWithError() DataSchema method Sends a negative response to the type


"idl-def-dataschema" data-idl="" data-title=
"DataSchema">typedef USVString 


Request

DataSchema



based
on
the
Protocol
Bindings
and
includes
the
error
specified
by
the
error
argument.

5.3


;

The RequestHandler DataSchema callback Callback function for handling interaction requests. Receives an argument request of type represents a data type specified in the Thing Description in a serialized form.

Editor's note

Request DataSchema and should return an object or value that is used by Protocol Bindings to reply to the request. The returned under development, currently it can denote any type is defined supported by the Thing Description and the WoT Runtime .

5.4 5.7 The addProperty() method

Adds a Property defined by the argument and updates the Thing Description . Throws on error. Returns a reference to the same object for supporting chaining.

5.4.1 5.7.1 The ThingPropertyInit ThingProperty dictionary

"idl-def-thingpropertyinit" data-idl="" data-title=
"ThingPropertyInit">dictionary <span class=
"idlDictionaryID"><a data-lt="ThingPropertyInit" href=
"#dom-thingpropertyinit" class="internalDFN" data-link-type="dfn"
data-for=""> {
<span class="idlMember" id="idl-def-thingpropertyinit-name"
data-idl="" data-title="name" data-dfn-for=
"thingpropertyinit">    <a href=
"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name"
href="#dom-thingpropertyinit-name" class="internalDFN"
data-link-type="dfn" data-for=
"ThingPropertyInit">
<span class="idlMember" id="idl-def-thingpropertyinit-configurable"
data-idl="" data-title="configurable" data-dfn-for=
"thingpropertyinit">    <a href=
"https://heycam.github.io/webidl/#idl-boolean">boolean<a data-lt="configurable"
href="#dom-thingpropertyinit-configurable" class="internalDFN"
data-link-type="dfn" data-for=
"ThingPropertyInit">
<span class="idlMember" id="idl-def-thingpropertyinit-enumerable"
data-idl="" data-title="enumerable" data-dfn-for=
"thingpropertyinit">    <a href=
"https://heycam.github.io/webidl/#idl-boolean">boolean<a data-lt="enumerable"
href="#dom-thingpropertyinit-enumerable" class="internalDFN"
data-link-type="dfn" data-for=
"ThingPropertyInit">
<span class="idlMember" id="idl-def-thingpropertyinit-writable"

"idl-def-thingproperty" data-idl="" data-title=
"ThingProperty">dictionary ThingProperty : SemanticAnnotations {

data-title="name" data-dfn-for=
"thingproperty">    required DOMString  name;

"" data-title="schema" data-dfn-for=
"thingproperty">    required DataSchema schema;

"" data-title="value" data-dfn-for=
"thingproperty">             any        value;
"thingpropertyinit">    <a href=
"https://heycam.github.io/webidl/#idl-boolean">boolean<a data-lt="writable"
href="#dom-thingpropertyinit-writable" class="internalDFN"
data-link-type="dfn" data-for=
"ThingPropertyInit"> = <span class=
"idlMemberValue">true
<span class="idlMember" id=
"idl-def-thingpropertyinit-semantictypes" data-idl="" data-title=
"semanticTypes" data-dfn-for="thingpropertyinit">    <span class=
"idlMemberType"><a href=
"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-semantictype"
class="internalDFN" data-link-type=
"dfn"> <span class=
"idlMemberName"><a data-lt="semanticTypes" href=
"#dom-thingpropertyinit-semantictypes" class="internalDFN"
data-link-type="dfn" data-for=
"ThingPropertyInit">
<span class="idlMember" id="idl-def-thingpropertyinit-description"
data-idl="" data-title="description" data-dfn-for=
"thingpropertyinit">    <a href=
"#dom-thingdescription" class="internalDFN" data-link-type=
"dfn">       <span class=
"idlMemberName"><a data-lt="description" href=
"#dom-thingpropertyinit-description" class="internalDFN"
data-link-type="dfn" data-for=
"ThingPropertyInit">
<span class="idlMember" id="idl-def-thingpropertyinit-value"
data-idl="" data-title="value" data-dfn-for=
"thingpropertyinit">    <a href=
"https://heycam.github.io/webidl/#idl-any">any<a data-lt="value"
href="#dom-thingpropertyinit-value" class="internalDFN"
data-link-type="dfn" data-for=
"ThingPropertyInit">

"thingproperty">             boolean    writable = false;

data-idl="" data-title="observable" data-dfn-for=
"thingproperty">             boolean    observable = false;

};

Represents the Thing Property description.

  • The name attribute represents the name of the Property .
  • The value schema attribute represents the value of data type for the Property described by DataSchema .
  • The configurable value attribute defines whether the Property can be deleted from represents the object and whether its properties can be changed. The default value is false . of the Property .
  • The enumerable writable attribute defines whether the Property can be listed and iterated. updated. The default value is true false .
  • The writable observable attribute defines whether the Property changes can be updated. observed by an external client. The default value is true false .
  • 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 <span class="idlDictionary" id= "idl-def-semantictype" data-idl="" data-title= "SemanticType">dictionary <a data-lt= "SemanticType" href="#dom-semantictype" class="internalDFN" data-link-type="dfn" data-for= ""> { <span class="idlMember" id="idl-def-semantictype-name" data-idl="" data-title="name" data-dfn-for="semantictype"> <span class= "idlMemberType"><a href= "https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name" href="#dom-semantictype-name" class="internalDFN" data-link-type= "dfn" data-for="SemanticType"> <span class="idlMember" id="idl-def-semantictype-context" data-idl= "" data-title="context" data-dfn-for= "semantictype"> <a href= "https://heycam.github.io/webidl/#idl-USVString">USVString<a data-lt="context" href="#dom-semantictype-context" class="internalDFN" data-link-type="dfn" data-for= "SemanticType"> }; 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 5.8 The removeProperty() method

Removes the Property specified by the name argument, argument and updates the Thing Description and returns . Throws on error. Returns a reference to the object. same object for supporting chaining.

5.6 5.9 The addAction() method

Adds an Action to the Thing object as defined by the action argument of type ThingActionInit ThingAction and updates the Thing Description . Throws on error. Returns a reference to the same object for supporting chaining.

5.6.1 5.9.1 The ThingActionInit ThingAction dictionary

"idl-def-thingactioninit" data-idl="" data-title=
"ThingActionInit">dictionary <span class=
"idlDictionaryID"><a data-lt="ThingActionInit" href=
"#dom-thingactioninit" class="internalDFN" data-link-type="dfn"
data-for=""> {
<span class="idlMember" id="idl-def-thingactioninit-name" data-idl=
"" data-title="name" data-dfn-for=
"thingactioninit">    <a href=
"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name"
href="#dom-thingactioninit-name" class="internalDFN"
data-link-type="dfn" data-for=
"ThingActionInit">
<span class="idlMember" id=
"idl-def-thingactioninit-inputdatadescription" data-idl=""
data-title="inputDataDescription" data-dfn-for=
"thingactioninit">    <a href=
"#dom-thingdescription" class="internalDFN" data-link-type=
"dfn">       <span class=
"idlMemberName"><a data-lt="inputDataDescription" href=
"#dom-thingactioninit-inputdatadescription" class="internalDFN"
data-link-type="dfn" data-for=
"ThingActionInit">
<span class="idlMember" id=
"idl-def-thingactioninit-outputdatadescription" data-idl=""
data-title="outputDataDescription" data-dfn-for=
"thingactioninit">    <a href=
"#dom-thingdescription" class="internalDFN" data-link-type=
"dfn">       <span class=
"idlMemberName"><a data-lt="outputDataDescription" href=
"#dom-thingactioninit-outputdatadescription" class="internalDFN"
data-link-type="dfn" data-for=
"ThingActionInit">
<span class="idlMember" id="idl-def-thingactioninit-semantictypes"
data-idl="" data-title="semanticTypes" data-dfn-for=
"thingactioninit">    <a href=
"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-semantictype"

"idl-def-thingaction" data-idl="" data-title=
"ThingAction">dictionary ThingAction : SemanticAnnotations {

data-title="name" data-dfn-for=
"thingaction">    required DOMString  
class="internalDFN" data-link-type=
"dfn"> <span class=
"idlMemberName"><a data-lt="semanticTypes" href=
"#dom-thingactioninit-semantictypes" class="internalDFN"
data-link-type="dfn" data-for=
"ThingActionInit">
<span class="idlMember" id="idl-def-thingactioninit-action"
data-idl="" data-title="action" data-dfn-for=
"thingactioninit">    <span class=
"idlMemberType">Function               <span class=
"idlMemberName"><a data-lt="action" href=
"#dom-thingactioninit-action" class="internalDFN" data-link-type=
"dfn" data-for=
"ThingActionInit">

"dfn">name;

data-idl="" data-title="inputSchema" data-dfn-for=
"thingaction">             DataSchema inputSchema;

data-idl="" data-title="outputSchema" data-dfn-for=
"thingaction">             DataSchema outputSchema;

};

The ThingActionInit ThingAction 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 inputSchema attribute provides the description of the input arguments (argument list is represented by an object). If missing, it means the action does not accept arguments.
  • The outputDataDescription outputSchema 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 If missing, it means the Action , represented as SemanticType dictionaries. action does not return data.

5.7 5.10 The removeAction() method

Removes the Action specified by the name argument, argument and updates the Thing Description and returns . Throws on error. Returns a reference to the object. same object for supporting chaining.

5.8 5.11 The addEvent() method

Adds an event to the Thing object as defined by the event argument of type ThingEventInit ThingEvent and updates the Thing Description . Throws on error. Returns a reference to the same object for supporting chaining.

5.8.1 5.11.1 The ThingEventInit ThingEvent dictionary

"idl-def-thingeventinit" data-idl="" data-title=
"ThingEventInit">dictionary <span class=
"idlDictionaryID"><a data-lt="ThingEventInit" href=
"#dom-thingeventinit" class="internalDFN" data-link-type="dfn"
data-for=""> {
<span class="idlMember" id="idl-def-thingeventinit-name" data-idl=
"" data-title="name" data-dfn-for="thingeventinit">    <span class=
"idlMemberType"><a href=
"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name"
href="#dom-thingeventinit-name" class="internalDFN" data-link-type=
"dfn" data-for=
"ThingEventInit">
<span class="idlMember" id="idl-def-thingeventinit-semantictypes"
data-idl="" data-title="semanticTypes" data-dfn-for=
"thingeventinit">    <a href=
"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-semantictype"

"idl-def-thingevent" data-idl="" data-title=
"ThingEvent">dictionary ThingEvent : SemanticAnnotations {

data-title="name" data-dfn-for=
"thingevent">    required DOMString  
class="internalDFN" data-link-type=
"dfn"> <span class=
"idlMemberName"><a data-lt="semanticTypes" href=
"#dom-thingeventinit-semantictypes" class="internalDFN"
data-link-type="dfn" data-for=
"ThingEventInit">
<span class="idlMember" id="idl-def-thingeventinit-datadescription"
data-idl="" data-title="dataDescription" data-dfn-for=
"thingeventinit">    <a href=
"#dom-thingdescription" class="internalDFN" data-link-type=
"dfn">       <span class=
"idlMemberName"><a data-lt="dataDescription" href=
"#dom-thingeventinit-datadescription" class="internalDFN"
data-link-type="dfn" data-for=
"ThingEventInit">

"dfn">name;

data-title="schema" data-dfn-for=
"thingevent">             DataSchema schema;

};

  • The name attribute represents the event name.
  • The semanticTypes attribute represent a list of semantic type annotations attached to the event. The dataDescription schema attribute represents the description type of the data that is attached to the event. If missing, it means the event does not carry data.

5.9 5.12 The removeEvent() method

Removes the event specified by the name argument, argument and updates the Thing Description and returns . Returns a reference to the object. same object for supporting chaining.

5.10 5.13 The onRetrieveProperty() PropertyReadHandler method callback

Registers the handler A function for that returns a Promise and resolves it with the value of the Property retrieve requests received for matching the Thing , as defined by name argument to the handler setPropertyReadHandler function, or rejects with an error if the property of type is not found or the value cannot be retrieved.

5.14 The RequestHandler PropertyWriteHandler callback

A function called with value . The handler will receive an as argument request that returns a Promise which is resolved when the value of type the Property matching the name argument to the Request setPropertyReadHandler function is updated with value , or rejects with an error if the property is not found or the value cannot be updated.

Editor's note where at least request.name

Note that this function is defined and represents invoked by implementations before the name property is updated, so the code in this callback function can invoke the readProperty() method to find out the old value of the Property property, if needed. Therefore the old value is not provided to be retrieved. this method.

5.11 5.15 The onUpdateProperty() ActionHandler method callback

Defines the handler A function for Property called with a parameters dictionary argument assembled by the WoT runtime update requests received for based on the Thing , as defined by Description and the external client request. It returns a Promise that rejects with an error or resolves if the action is successful or ongoing (may also resolve with a control object such as an handler Observable property of type for actions that need progress notifications or that can be canceled).

5.16 The RequestHandler setPropertyReadHandler() method

Takes name . The handler will receive an as string argument and readHandler as argument request of type Request PropertyReadHandler where request.name defines . Sets the name of handler function for reading the specified Property matched by name . Throws on error. Returns a reference to be retrieved the same object for supporting chaining.

The readHandler callback function will implement reading a Property and request.data defines SHOULD be called by implementations when a request for reading a Property is received from the new value of underlying platform.

There SHOULD be at most one handler for any given Property and newly added handlers replace the old handlers. If no handler is initialized for any given Property . , implementations SHOULD implement a default property read handler.

5.12 5.17 The onInvokeAction() setPropertyWriteHandler() method

Defines the handler function for Action invocation requests received for the Thing , as defined by the Takes handler name property of type as string argument and RequestHandler writeHandler . The handler will receive an as argument request of type Request PropertyWriteHandler where request.name defines . Sets the name of handler function for writing the Action specified Property matched by name . Throws on error. Returns a reference to be invoked and request.data defines the input arguments same object for the Action supporting chaining.

There SHOULD be at most one write handler for any given Property as defined by and newly added handlers replace the Thing Description . old handlers. If no write handler is initialized for any given Property , implementations SHOULD implement default property update and notifying observers on change.

5.13 5.18 The onObserve() setActionHandler() method

Defines the handler function for observe requests received for the Thing , Takes name as defined by the string argument and handler action property as argument of type RequestHandler ActionHandler . The . Sets the handler function for the specified Action matched by name . Throws on error. Returns a reference to the same object for supporting chaining.

If provided, this callback function will receive implement invoking an argument Action and SHOULD be called by implementations when a request of type for invoking a Action is received from the underlying platform. The callback will receive a parameters dictionary argument.

There SHOULD be exactly one handler for any given Action . If no handler is initialized for any given Action , implementations SHOULD return error if the action is invoked by any client.

5.19 Examples

Below some Request ExposedThing where interface examples are given.

request.name defines the name of the Property or Action or event Example 7 : Create a new blank exposed Thing
        try {  
"hljs-keyword">var thing = WoT.produce({ name: "tempSensor" });
  // manually add Interactions
  thing.addProperty({
    name: 
"hljs-string">"temperature",
    value: 
"hljs-number">0.0,
    schema: 
"hljs-string">'{ "type": "number" }'
    
"hljs-comment">// use default values for the rest
  }).addProperty({
    name: 
"hljs-string">"max",
    value: 
"hljs-number">0.0,
    schema: 
"hljs-string">'{ "type": "number" }'
    
"hljs-comment">// use default values for the rest
  }).addAction({
    name: 
"hljs-string">"reset",
    // no input, no output
  }).addEvent({
    name: 
"hljs-string">"onchange",
    schema: 
"hljs-string">'{ "type": "number" }'
  });
  // add server functionality
  thing.setActionHandler("reset", () => {
    console.log(
"hljs-string">"Resetting maximum");
    thing.writeProperty("max", 0.0);
  });
  thing.start().then(() => {
      thing.register();
  });
  // define Thing business logic
  setInterval( async () => {
    let mock = 
"hljs-built_in">Math.random()*100;
    thing.writeProperty("temperature", mock);
    let old = 
"hljs-keyword">await thing.readProperty("max");
    if (old < mock) {
      thing.writeProperty("max", mock);
      thing.emitEvent("onchange");
    }
  }, 1000);
} catch (err) {
   console.log(
"hljs-string">"Error creating ExposedThing: " + err);
}
Example 8 : Create a new exposed Thing from a Thing Description
        
"hljs-keyword">let thingDescription = '{ "@context": [ "https://w3c.github.io/wot/w3c-wot-td-context.jsonld", "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ], "@type": [ "Thing", "Sensor" ], "name": "mySensor", "geo:location": "testspace", "interaction": [ { "@type": [ "Property", "Temperature" ], "name": "prop1", "schema": { "type": "number" }, "saref:TemperatureUnit": "degree_Celsius" } ] }';
try {  
"hljs-comment">// note that produce() fails if thingDescription contains error
  
"hljs-keyword">let thing = WoT.produce(thingDescription);
  
"hljs-comment">// Interactions were added from TD
  
"hljs-comment">// WoT adds generic handler for reading any property
  
"hljs-comment">// define a specific handler for one property
  let name = 
"hljs-string">"examplePropertyName";
  thing.setPropertyReadHandler(name, () => {
    console.log(
"hljs-string">"Handling read request for " + name);
    return 
"hljs-keyword">new Promise((resolve, reject) => {
        
"hljs-keyword">let examplePropertyValue = 5;
        resolve(examplePropertyValue);
      },
      e => {
        console.log(
"hljs-string">"Error");
      });
  });
  thing.start();
} catch(err) {
   console.log(
"hljs-string">"Error creating ExposedThing: " + err);
}
Example 9 : Create a new exposed Thing from a TD URI
        
"hljs-comment">// fetch an external TD, e.g., to set up a proxy for that Thing
WoT.fetch("http://myservice.org/mySensor/description").then(td => {
  
"hljs-comment">// WoT.produce() ignores instance-specific metadata (security, form)
  let thing = WoT.produce(td);  
"hljs-comment">// Interactions were added from TD
  // add server functionality  // ...
});

6. Experimental extensions to be observed. the ConsumedThing interface

request.options.observeType This section is of type non-normative.

The RequestType ThingDescription and defines whether a Property change or related functionality, such as enumerating Properties , Action invocation or event emitting is observed, or the changes to the Thing Description s, Event are observed. request.options.subscribe is true if subscription is turned or kept being turned on, s and it links (introspection) is false when subscription an API extension that is turned off. out of scope for this specification. However, the draft interfaces are defined here for informative purposes.


"idl-def-consumedthing-partial-1" data-idl="" data-title=
"ConsumedThing">partial interface ConsumedThing {

data-idl="" data-title="getProperties" data-dfn-for=
"consumedthing">    sequence<ThingProperty> getProperties();

data-idl="" data-title="getActions" data-dfn-for=
"consumedthing">    sequence<ThingAction>   getActions();

data-idl="" data-title="getEvents" data-dfn-for=
"consumedthing">    sequence<ThingEvent>    getEvents();

data-idl="" data-title="getLinks" data-dfn-for=
"consumedthing">    sequence<TDLink>        getLinks();
};

5.14 6.1 The register() getProperties() method

Generates the Thing Description given Returns the properties, Actions and Event list of Properties defined for this object. If a directory argument is given, make a request to register in the Thing Description with of the given WoT repository by invoking its Thing in the form of a list of register ThingProperty Action . objects.

5.15 6.2 The unregister() getActions() method

If a directory argument is given, make a request to unregister the Thing Description with Returns the given WoT repository by invoking its unregister list of Action . Then, and s defined in the case no arguments were provided to this function, stop the Thing Description and remove of the Thing Description . in the form of a list of ThingAction objects.

5.16 6.3 The start() getEvents() method

Start serving external requests for Returns the list of Event s defined in the Thing . Description of the Thing in the form of a list of ThingEvent objects.

5.20 7. Examples Observables

Below some This section is non-normative. ExposedThing

Observables are proposed interface examples to be included in ECMAScript and are given. used for handling pushed data associated with various possible sources, for instance events, timers, streams, etc. A minimal required implementation is described here.

Example 6 Editor's note : Create a new blank exposed Thing

This section is informal and contains rather laconic information for implementations on what to support for interoperability.


"idl-def-observable" data-idl="" data-title=
"Observable">interface Observable {

"idl-def-observable-subscribe-next-error-complete" data-idl=""
data-title="subscribe" data-dfn-for="observable">    Subscription subscribe((Observer or OnNext) next,
                           
"idlParam">optional OnError error,
                           
"idlParam">optional OnComplete complete);
};

data-title="Subscription">interface Subscription {

data-idl="" data-title="unsubscribe" data-dfn-for=
"subscription">    void unsubscribe();

data-idl="" data-title="closed" data-dfn-for=
"subscription">    readonly attribute boolean closed;
};

data-title="Observer">interface Observer {

"" data-title="next" data-dfn-for="observer">    void next(any value);

"" data-title="error" data-dfn-for="observer">    void error(Error error);

data-title="complete" data-dfn-for="observer">    void complete();
};

data-title="OnNext">callback OnNext = void (any value);

data-title="OnError">callback OnError = void (Error error);

data-title="OnComplete">callback OnComplete = 
void

();


<pre class="highlight hljs javascript" aria-busy="false" aria-live=
"polite">WoT.createExposedThing(thingDescription)
  .then(<span class=
"hljs-keyword">function(<span class=
"hljs-params">thing{
    <span class=
"hljs-comment">// manually add properties, actions, and events
    thing.addProperty({
      : <span class=
"hljs-string">"temperature",
      : <span class=
"hljs-string">"0",
      : <span class=
"hljs-literal">false
      <span class=
"hljs-comment">// use default values for the rest
    }).addEvent({
      : <span class=
"hljs-string">"onchange",
      : {
        : <span class=
"hljs-string">"float32"
      }
    }).addAction({
      : <span class=
"hljs-string">"reset",
      : <span class=
"hljs-function"><span class=
"hljs-params">() { <span class=
"hljs-keyword">this.temperature = <span class=
"hljs-number">0; }
    })
    
    .onRetrieveProperty( <span class=
"hljs-params">request {
      .log(<span class=
"hljs-string">"Handling read request");
       <span class=
"hljs-keyword">this.temperature;
    }).onObserve( <span class=
"hljs-params">request {
      .log(<span class=
"hljs-string">"Handling observe request");
      <span class=
"hljs-comment">// add listener identified by request.from
    }).onInvokeAction( <span class=
"hljs-params">request {
      .log(<span class=
"hljs-string">"Handling action request");
    }).start();
});

Example 7 7.1 The : Create a new exposed Thing from a TD URI Observer 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"); }); }) interface

The Observer Example 8 interface defines the callbacks needed to handle an Observable :

7.2 The : Create Subscription interface

Contains the closed property of type boolean that tells if the subscription is closed or active.

Also, contains the unsubscribe () method that cancels the subscription, i.e. makes a new exposed Thing request to the underlying platform to stop receiving data from a Thing Description the source, and sets the closed property to false .

7.3 The 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 // ... }); Observable interface

The Observable interface enabled subscribing to pushed data notifications by the subscribe () method:

6. 8. 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. 9. 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 , WoT Interactions , 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 HTML52 ] 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 .

The terms hyperlink reference and relation type are defined in [ HTML52 ] and RFC8288 .

8. 10. 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. Kesteren; Joshua Bell; Addison Phillips. W3C. 15 December 2016. W3C Candidate Recommendation. URL: https://encoding.spec.whatwg.org/ https://www.w3.org/TR/encoding/
[HTML5]
[HTML52]
HTML5 HTML 5.2 . Ian Hickson; Robin Berjon; Steve Faulkner; Arron Eicholz; Travis Leithead; Alex Danilo; Sangwhan Moon; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. Robin Berjon. W3C. 28 October 2014. 14 December 2017. W3C Recommendation. URL: https://www.w3.org/TR/html5/ https://www.w3.org/TR/html52/
[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 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. 14 September 2017. URL: https://www.w3.org/TR/2017/WD-wot-architecture-20170914/

D.2 Informative references

[WOT-TD]
WoT Thing Description . W3C. 20 August 2017. URL: https://w3c.github.io/wot-architecture/ https://www.w3.org/TR/2018/WD-wot-thing-description-20180405/