Web of Things (WoT) Scripting API

3.1 The discover() method

Starts the discovery process that will provide ConsumedThing ThingDescription objects s that match the optional argument filter of type ThingFilter . When the argument is not provided, starts the widest discovery the Thing Description and Protocol Bindings allow and support. Returns an [ Observable ](https://github.com/tc39/proposal-observable) object that can be subscribed to and unsubscribed from. The handler function provided to the Observable during subscription will receive an argument of type USVString representing a ThingDescription .

"DiscoveryMethod">typedef <a href=

"DiscoveryMethod">typedef 
"https://heycam.github.io/webidl/#idl-DOMString">DOMString 

DiscoveryMethod



;

dictionary "dfn"> {
<span class="idlMember" id="idl-def-thingfilter-method" data-idl=""
data-title="method" data-dfn-for="thingfilter">    <span class=
"idlMemberType"><a href="#dom-discoverymethod" class="internalDFN"
data-link-type=
"dfn">      <span class=
"idlMemberName"><a data-no-default="" data-link-for="thingfilter"
data-lt="" href="#dom-thingfilter-method" class="internalDFN"
data-link-type="dfn"> = <span class=
"idlMemberValue">"any"
<span class="idlMember" id="idl-def-thingfilter-url" data-idl=""
data-title="url" data-dfn-for="thingfilter">    <span class=
"idlMemberType"><a href=
"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default=""

"dfn">ThingFilter {
  (DiscoveryMethod or DOMString) method = "any";
  
"https://heycam.github.io/webidl/#idl-USVString">USVString? 
data-link-for="thingfilter" data-lt="" href="#dom-thingfilter-url"
class="internalDFN" data-link-type=
"dfn">
<span class="idlMember" id="idl-def-thingfilter-query" data-idl=""
data-title="query" data-dfn-for="thingfilter">    <span class=
"idlMemberType"><a href=
"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default=""

"dfn">url;
  
"https://heycam.github.io/webidl/#idl-USVString">USVString? 
data-link-for="thingfilter" data-lt="" href=
"#dom-thingfilter-query" class="internalDFN" data-link-type=
"dfn">
<span class="idlMember" id="idl-def-thingfilter-constraints"
data-idl="" data-title="constraints" data-dfn-for=
"thingfilter">    <a href=
"https://heycam.github.io/webidl/#idl-sequence">sequence<a data-no-default=""
data-link-for="thingfilter" data-lt="" href=
"#dom-thingfilter-constraints" class="internalDFN" data-link-type=
"dfn">

"dfn">query;
  
data-link-type=
"dfn">ThingFragment? fragment;

};

The discover(filter) method in MUST run the form of a list of sets of property-value pairs (dictionaries). The list elements (dictionaries) are in OR relationship, following steps:

1. If invoking discover() is not allowed for the current scripting context for security reasons, throw SecurityError and within a constraint dictionary terminate these steps.
2. Return an Observable obs and execute the key-value pairs are next steps in AND relationship. Implementations SHOULD make parallel .
3. If obs.subscribe(handler, errorHandler, complete) is called, execute the following mapping from sub-steps:
   1. If the constraint dictionaries first argument handler is not defined or it is not a function, throw TypeError and terminate the algorithm. Otherwise configure handler to be invoked when a discovery hit happens.
   2. If the second argument errorHandler is defined, but it is not a function, throw SemanticAnnotations TypeError : for each property-value pair and terminate these steps. Otherwise if defined, save it to be invoked in error conditions.
   3. If the third argument onComplete is defined, but it is not a constraint dictionary, function, throw TypeError and terminate these steps. Otherwise if defined, save it to be invoked when the discovery process finished for other reasons than having been canceled.
   4. Each property name in If filter.query is defined, pass it as an opaque string to the constraint dictionary SHOULD underlying implementation to be matched against discovered items. The underlying implementation is responsible to parse it e.g. as a SPARQL or JSON query and match it against the either Thing Description s found during the discovery process. If queries are not supported, implementations SHOULD throw a name NotSupported property of a error and terminate these steps.
   5. If filter.fragment is defined, and if it contains other properties than the ones defined in SemanticType ThingFragment on , throw TypeError and terminate these steps. Otherwise save the target object for matching the discovered items against it.
   6. Request the underlying platform to start the discovery process, with the following parameters:
      • If filter.method is not defined or the value is "any" , use the widest discovery method supported by the underlying platform.
      • Otherwise if filter.method is "local" , use the local Thing Directory object, for discovery. Usually that defines Thing s deployed in the same device, or connected to the name of device in slave mode (e.g. sensors connected via Bluetooth or a Property on serial connection).
      • Otherwise if filter.method is "directory" , use the target remote Thing . Directory specified in filter.url .
      • When Otherwise if filter.method is "multicast" , use all the name matches, multicast discovery protocols supported by the values are compared. underlying platform.
4. Whenever a new item td is discovered by the underlying platform, run the following sub-steps:
   1. If filter.query is defined, check if td is a match for the values match, query. The matching algorithm is encapsulated by implementations. If that returns false , discard td and continue the constraint discovery process.
   2. If filter.fragment is matched. defined, for each property defined in it, check if that property exists in td and has the same value. If this is false in any checks, discard td and continue the discovery process.
   Editor's note Constraints are experimental feature, implementations are
   3. Otherwise if td has not required to support them. Editor's note Semantic annotations need revisiting been discarded in order to simplify their representation. In the [ WOT-TD ] specification they represent previous steps, invoke the handler function with td as parameter.
5. Whenever an error occurs during the discovery process, and if errorHandler is defined, invoke it with an argument of type @type Error construct. At the moment only whose @context , message property is set to @type UnknownError unless there was an error code provided by the Protocol Bindings , in which case set it to that value.
6. When the discovery process is finished, and if onComplete is defined, invoke it run the cancel discovery steps.
7. When the @id obs.unsubscribe() constructs are used in method is called, run the TD . following cancel discovery steps:
   1. Request the underlying platform to stop the discovery process. If this returns an error, or if it is not possible, for instance when discovery is based on open ended multicast requests, the implementation SHOULD discard subsequent discovered items.
   2. Set obs.closed to false .

3.2 The fetch() method

Accepts an url argument of type USVString that represents a URL (e.g. "file://..." or "https://..." ) and returns a Promise that resolves with a ThingDescription . (a serialized JSON-LD document of type USVString ).

The ThingDescription fetch(url) type Representation of method MUST run the Thing Description , standardized following steps:

1. Return a Promise promise and execute the next steps in parallel .
2. If invoking fetch() is not allowed for the Wot Things current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
3. If the argument url is not a URL, reject promise with TypeError and terminate these steps.
4. Make a request to fetch the content of url as described by the Protocol Bindings and wait for the reply. Implementations encapsulate the fetching process and the accepted media types (such as application/td+json ), as far as a valid Thing Description specification. can be obtained as defined in [ Note WOT-TD In this version of ]. Let td be the API, Thing Description s are represented string-serialized from the returned content, as opaque strings, denoting a serialized form, for instance JSON or JSON-LD. See Issue 38 specified in the Thing Description serialization .
5. If there was an error during the request, reject promise with an Error object error with error.message set to the error code seen by the Protocol Bindings and Issue 45 . terminate these steps.
6. Otherwise resolve promise with td and terminate these steps.

3.4 3.3 The consume() method

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

The consume(td) method must run the following steps:

1. If the argument td is not a string, throw a TypeError and terminate these steps.
2. Let stub be the result of running the TD parsing algorithm with td as argument. If that throws an error, re-throw the error and terminate these steps.
3. If stub does not have an own property that is defined in ThingFragment with a default value, add that property and value to stub .
4. Create a ConsumedThing object thing initialized from stub that implements Observable .
5. Add the read() and write() methods to the ThingProperty elements so that they make requests to access the remote Thing s and wait for the reply, as defined by the Protocol Bindings . Also, all ThingProperty elements SHOULD implement Observable , i.e. define a subscribe() method that should make request to observe the given Properties as defined by the Protocol Bindings .
6. Add the invoke() methods to the ThingAction elements so that they make requests to the remote Thing to invoke its actions, as defined by the Protocol Bindings .
7. Add the subscribe() method to all ThingEvent elements so that they make requests to subscribe to the events defined by the remote Thing , as defined by the Protocol Bindings .
8. Return thing .

3.5 3.4 The produce() method

Accepts a model argument of type ThingModel and returns an ExposedThing object, locally created based on the provided initialization parameters. An object.

The ExposedThing produce(model) can be created in method MUST run the following ways: steps:

1. from an initial If invoking produce() is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
2. If the argument model (including is a user given name and semantic annotations ), string, then adding properties, actions, events run the TD parsing algorithm with model passed as parameter. If it throws an error, re-throw that error and request handlers; terminate this algorithm. Otherwise let model be the returned value.
3. from a Thing Description (possibly of a If model is not an object, throw TypeError and terminate these steps.
4. If model does not have an own property that is defined in ConsumedThing ThingFragment object), then adding request handlers. with a default value, add that property and value to model .
3.6 The
5. Create an ThingModel ExposedThing type A Thing object thing initialized from model is used for producing a new .
6. For each property of ExposedThing and can be either a defined in ThingTemplate ThingFragment , initialize the property based on the provided initial or a default values provided to the local WoT Runtime implementation, for instance initialize:
   1. the ThingDescription id . 3.7 The property to be the final unique identifier of the Thing ,
   2. the security object of type SemanticAnnotations SecurityScheme dictionary A dictionary that provides to represent the semantic types actual security scheme and semantic metadata. <span class="idlDictionary" id= "idl-def-semanticannotations" data-idl="" data-title= "SemanticAnnotations">dictionary <span class= "idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" href="#dom-semanticannotations" class="internalDFN" data-link-type= "dfn"> { <span class="idlMember" id= "idl-def-semanticannotations-semantictype" data-idl="" data-title= "semanticType" data-dfn-for="semanticannotations"> <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-no-default="" data-link-for= "semanticannotations" data-lt="" href= "#dom-semanticannotations-semantictype" class="internalDFN" data-link-type="dfn"> <span class="idlMember" id="idl-def-semanticannotations-metadata" data-idl="" data-title="metadata" data-dfn-for= "semanticannotations"> <a href= "https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-semanticmetadata" class="internalDFN" data-link-type= "dfn"> <span class= "idlMemberName"><a data-no-default="" data-link-for= "semanticannotations" data-lt="" href= "#dom-semanticannotations-metadata" class="internalDFN" data-link-type="dfn"> }; The its properties as set up by the implementation,
   3. the semanticType properties property denotes a list of to be an object with all properties being SemanticType ThingProperty objects that in which the read() and write() methods are provided to define local methods to get and set the Property values,
   4. the semantic types that can be used in semantic metadata type-value pairs. The metadata actions property denotes a list of to be an object with all properties being SemanticMetadata ThingAction objects (type-value pairs). 3.8 The in which the SemanticType invoke() dictionary <span class="idlDictionary" id= "idl-def-semantictype" data-idl="" data-title= "SemanticType">dictionary <span class= "idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" href="#dom-semantictype" class="internalDFN" data-link-type= "dfn"> { <span class="idlMember" id="idl-def-semantictype-name" data-idl="" data-title="name" data-dfn-for= "semantictype"> required <a href= "https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" data-link-for="semantictype" data-lt="" href= "#dom-semantictype-name" class="internalDFN" data-link-type= "dfn"> <span class="idlMember" id="idl-def-semantictype-context" data-idl= "" data-title="context" data-dfn-for= "semantictype"> required <a href= "https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default="" data-link-for="semantictype" data-lt="" href= "#dom-semantictype-context" class="internalDFN" data-link-type= "dfn"> <span class="idlMember" id="idl-def-semantictype-prefix" data-idl= "" data-title="prefix" data-dfn-for= "semantictype"> <a href= "https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" data-link-for="semantictype" data-lt="" href= "#dom-semantictype-prefix" class="internalDFN" data-link-type= "dfn"> }; Represents a semantic type annotation, containing a name, a context and method is provided to define a prefix. local method to run the defined Action s,
   5. The the events property to be an object with all properties being name ExposedEvent attribute represents the name of the semantic type objects in which the given context. The context emit() attribute represents an URL link method is provided to define a local way to trigger sending notifications to all subscribed clients,
   6. and initialize the context of the semantic classification. other properties as initialized from model .
   7. Return thing .

   The prefix TD parsing algorithm attribute represents takes a short prefix associated with string td as argument and runs the following steps:

   1. Parse td according to the WoT Thing Description in order to produce a context. JSON object json . Update thing with the properties and values defined in json .
   Editor's note Semantic type examples to be added.
   2. If there was an error during the parsing, throw that error and terminate these steps.
   3. Otherwise return json .

3.9 3.5 The SemanticMetadata register() dictionary <span class="idlDictionary" id= "idl-def-semanticmetadata" data-idl="" data-title= "SemanticMetadata">dictionary <span class= "idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" href="#dom-semanticmetadata" class="internalDFN" data-link-type= "dfn"> { <span class="idlMember" id="idl-def-semanticmetadata-type" data-idl="" data-title="type" data-dfn-for= "semanticmetadata"> <a href= "#dom-semantictype" class="internalDFN" data-link-type= "dfn"> <span class= "idlMemberName"><a data-no-default="" data-link-for= "semanticmetadata" data-lt="" href="#dom-semanticmetadata-type" class="internalDFN" data-link-type= "dfn"> <span class="idlMember" id="idl-def-semanticmetadata-value" data-idl="" data-title="value" data-dfn-for= "semanticmetadata"> <a href= "https://heycam.github.io/webidl/#idl-any">any<a data-no-default="" data-link-for="semanticmetadata" data-lt="" href= "#dom-semanticmetadata-value" class="internalDFN" data-link-type= "dfn"> }; method

The Takes two mandatory arguments:

• SemanticMetadata directory dictionary describes denoting a pair of semantic type Thing Directory , and value:
• The type thing attribute represents the semantic type name defined by a denoting an SemanticType ExposedThing object.
The value attribute represents the metadata value.

A Generate the Thing Template is a dictionary that provides a user Description as td , given name, and the semantic types Properties , Action s and semantic metadata attached to the Event s defined for this ExposedThing object. Then make a request to register td to the given WoT Thing Description 's root level. Directory .

3.6 The ThingTemplate unregister() method dictionary extends

Takes two mandatory arguments:

• SemanticAnnotations directory and contains properties to initialize denoting a Thing : Directory , and
• The name thing denoting an attribute represents ExposedThing object.

Makes a request to unregister the user given name of thing from the given WoT Thing Directory . Editor's note Support for configuration and security data might be added later.

3.11 3.7 Examples

let discoveryFilter = {
  method: "directory",
  url: "http://directory.wotservice.org"
};
let subscription = wot.discover(discoveryFilter).subscribe(
  "hljs-params">thing { <span class=
"hljs-built_in">console.log(<span class=
"hljs-string">"Found Thing " + thing.name); },

"hljs-params">td => {
    console.log(
"hljs-string">"Found Thing " + td.name);
    
"hljs-comment">// fetch the TD and create a ConsumedThing
    let thing = wot.consume(td);
  },

  error => { console.log("Discovery finished because an error: " + error.message); },
  () => { console.log("Discovery finished successfully");}
);
setTimeout( () => {
    subscription.unsubscribe();
    console.log("Discovery timeout");
  },

5000

);

let subscription = wot.discover({ method: "local" }).subscribe(
  "hljs-params">thing { <span class=

"hljs-params">td => { 
"hljs-built_in">console.log("hljs-string">"Found local Thing " + thing.name); },

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

  error => { console.log("Discovery error: " + error.message); },
  () => { console.log("Discovery finished successfully");}
);

let subscription = wot.discover({ method: "local" }).subscribe({
  thing => { <span class=

  td => { 
"hljs-built_in">console.log("hljs-string">"Found local Thing " + thing.name); },

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

  error: err => { console.log("Discovery error: " + err.message); },
  complete: () => { console.log("Discovery finished successfully");}
});

4.9 4.1 Examples

Below a ConsumedThing interface example is given.

"hljs-keyword">try {
  
"hljs-keyword">let subscription = wot.discover({ method: "local" }).subscribe(
    
"hljs-params">td => {
      
"hljs-keyword">let thing = wot.consume(td);
      console.log(
"hljs-string">"Thing " + thing.name + " has been consumed.");
      
"hljs-keyword">let subscription = thing["temperature"].subscribe(function(value) {
          
"hljs-built_in">console.log("Temperature: " + value);
        });
      thing.actions["startMeasurement"].invoke({ units: "Celsius" })
        .then(() => { console.log("Temperature measurement started."); })
        .catch(e => {
           
"hljs-built_in">console.log("Error starting measurement.");
           subscription.unsubscribe();
         })
    },
    error => { console.log("Discovery error: " + error.message); },
    () => { console.log("Discovery finished successfully");}
  );
} catch(error) {
  console.log(
"hljs-string">"Error: " + error.message);

};

5.1 ; The DataSchema expose() method type represents a data type specified in

Start serving external requests for the Thing Description , so that WoT Interactions in a serialized form. using Properties , Action s and Event s will be possible.

The DataSchema expose() is under development, currently it can denote any type supported by method MUST run the Thing Description following steps:

1. Return a Promise promise and execute the WoT Runtime next steps in parallel . 5.7 The
2. If invoking addProperty() expose() method Adds is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
3. Make a Property defined by request to the argument underlying platform to attach protocol handlers and updates start serving external requests for WoT Interactions (read, write and observe Properties , invoke Action s and manage Event subscriptions), based on the Thing Description Protocol Bindings . Throws on error. Returns a reference to
4. If there was an error during the same request, reject promise with an Error object for supporting chaining. error with error.message set to the error code seen by the Protocol Bindings and terminate these steps.
5. Otherwise resolve promise with td and terminate these steps.

5.7.1 5.2 The ThingProperty destroy() dictionary <span class="idlDictionary" id= "idl-def-thingproperty" data-idl="" data-title= "ThingProperty">dictionary <span class= "idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" href="#dom-thingproperty" class="internalDFN" data-link-type= "dfn"> : <span class= "idlSuperclass"><a href="#dom-semanticannotations" class= "internalDFN" data-link-type= "dfn"> { <span class="idlMember" id="idl-def-thingproperty-name" data-idl="" data-title="name" data-dfn-for= "thingproperty"> required <a href= "https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" data-link-for="thingproperty" data-lt="" href= "#dom-thingproperty-name" class="internalDFN" data-link-type= "dfn"> <span class="idlMember" id="idl-def-thingproperty-schema" data-idl= "" data-title="schema" data-dfn-for= "thingproperty"> required <a href= "#dom-dataschema" class="internalDFN" data-link-type= "dfn"> <span class= "idlMemberName"><a data-no-default="" data-link-for="thingproperty" data-lt="" href="#dom-thingproperty-schema" class="internalDFN" data-link-type="dfn"> <span class="idlMember" id="idl-def-thingproperty-value" data-idl= "" data-title="value" data-dfn-for= "thingproperty"> <a href= "https://heycam.github.io/webidl/#idl-any">any<a data-no-default="" data-link-for="thingproperty" data-lt="" href= "#dom-thingproperty-value" class="internalDFN" data-link-type= "dfn"> <span class="idlMember" id="idl-def-thingproperty-writable" data-idl="" data-title="writable" data-dfn-for= "thingproperty"> <a href= "https://heycam.github.io/webidl/#idl-boolean">boolean<a data-no-default="" data-link-for="thingproperty" data-lt="" href= "#dom-thingproperty-writable" class="internalDFN" data-link-type= "dfn"> = <span class= "idlMemberValue">false <span class="idlMember" id="idl-def-thingproperty-observable" data-idl="" data-title="observable" data-dfn-for= "thingproperty"> <a href= "https://heycam.github.io/webidl/#idl-boolean">boolean<a data-no-default="" data-link-for="thingproperty" data-lt="" href= "#dom-thingproperty-observable" class="internalDFN" data-link-type= "dfn"> = <span class= "idlMemberValue">false }; method

Represents Stop serving external requests for the Thing Property description. and destroy the object. Note that eventual unregistering should be done before invoking this method.

The name destroy() attribute represents method MUST run the name of following steps:

1. Return a Promise promise and execute the Property next steps in parallel .
2. The If invoking schema destroy() attribute represents the data type is not allowed for the Property described by current scripting context for security reasons, reject promise with DataSchema SecurityError . and terminate these steps.
3. The value attribute represents Make a request to the value of underlying platform to stop serving external requests for WoT Interactions , based on the Property Protocol Bindings .
4. The If there was an error during the request, reject promise with an writable Error attribute defines whether object error with error.message set to the Property error code seen by the Protocol Bindings can be updated. The default value is false . and terminate these steps.
5. The Otherwise resolve promise with td and terminate these steps.

5.3 The observable addProperty() attribute defines whether the method

Adds a Property changes can be observed with name defined by the name argument, the data schema provided by the property argument of type PropertyFragment , and optionally an external client. The default initial value provided in the argument initValue whose type should match the one defined in the type property according to the value-matching algorithm . If initValue is not provided, it SHOULD be initialized as false undefined . Implementations SHOULD update the Thing Description . Throws on error. Returns a reference to the same object for supporting chaining.

5.8 5.4 The removeProperty() method

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

5.9 5.5 The addAction() method

Adds an Action to the actions property of a Thing object as an Action with name defined by the action name argument, defines input and output data format by the init argument of type ThingAction ActionFragment , and adds the function provided in the action argument as a handler, then updates the Thing Description . Throws on error. Returns a reference to the same object for supporting chaining.

The ThingAction provided action callback function will implement invoking an Action dictionary describes the arguments and SHOULD be called by implementations when a request for invoking the return value. The name attribute provides the Action name. The inputSchema attribute provides the description of the input arguments (argument list is represented by an object). If missing, it means received from the action does not accept arguments. underlying platform. The callback will receive a outputSchema parameters attribute provides dictionary argument according to the description definition in the init.input argument and will return a value of type defined by the returned data. If missing, it means init.output argument according to the action does not return data. value-matching algorithm .

There SHOULD be exactly one handler for any given Action . If no handler is initialized for any given Action , implementations SHOULD throw a TypeError .

5.10 5.6 The removeAction() method

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

5.11 5.7 The addEvent() method

Adds an event to the Thing object as with name defined by the name argument and qualifiers and initialization value provided by the event argument of type ThingEvent EventFragment to the Thing object and updates the Thing Description . Throws on error. Returns a reference to the same object for supporting chaining.

5.12 5.8 The removeEvent() method

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

5.13 5.9 The PropertyReadHandler callback

A function that returns is called when an external request for reading a Property is received. It should return a Promise and resolves it with the value of the Property matching the name argument to the setPropertyReadHandler function, or rejects with an error if the property is not found or the value cannot be retrieved.

5.14 5.10 The PropertyWriteHandler callback

A function that is called with when an external request for writing a Property is received. It is given the requested new value as argument that returns and should return a Promise which is resolved when the value of the Property matching that matches the name argument to the setPropertyReadHandler function is has been updated with value , or rejects with an error if the property is not found or the value cannot be updated.

5.15 5.11 The ActionHandler callback

A function called with a parameters dictionary argument assembled by the WoT runtime based on the Thing 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 Observable for actions that need progress notifications or that can be canceled).

5.16 5.12 The setPropertyReadHandler() method

Takes name as string argument and readHandler as argument of type PropertyReadHandler . Sets the handler function for reading the specified Property matched by name . Throws on error. Returns a reference to the same object for supporting chaining.

The readHandler callback function will implement reading a Property and SHOULD be called by implementations when a request for reading a Property is received from the 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.

When an external request for reading Property propertyName is received, the runtime SHOULD execute the following steps:

1. Return a Promise promise and execute the next steps in parallel .
2. If a Property with propertyName does not exist, reject promise with a ReferenceError and terminate these steps.
3. Otherwise, if no read handler has been defined for propertyName , resolve promise with the value of the Property named propertyName provided by the runtime implementation and terminate these steps.
4. Otherwise, invoke the read handler associated with propertyName . If it rejects, then reject promise with the same error, and resolve promise with the same value.

5.17 5.13 The setPropertyWriteHandler() method

Takes name as string argument and writeHandler as argument of type PropertyWriteHandler . Sets the handler function for writing the specified Property matched by name . Throws on error. Returns a reference to the same object for supporting chaining.

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

When an external request for writing a Property propertyName with a new value value is received, the runtime SHOULD execute the following steps:

1. Return a Promise promise and execute the next steps in parallel .
2. If a Property with propertyName does not exist, reject promise with a ReferenceError and terminate these steps.
3. Otherwise, if no write handler has been defined for propertyName , the runtime implementation SHOULD update the Property value with value , resolve promise and terminate these steps.
4. Otherwise, invoke the write handler associated with propertyName providing value as argument. If it rejects, then reject promise with the same error, and resolve promise with the same value.

5.18 5.14 The setActionHandler() method

Takes name as string argument and action as argument of type ActionHandler . 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 The action callback function will implement invoking an Action and SHOULD be called by implementations when a request for invoking a the Action is received from the underlying platform. The callback will receive a parameters dictionary argument.

There SHOULD be exactly at most one handler for any given Action and newly added handlers replace the old handlers.

When an external request for invoking the Action identified by name is received, the runtime SHOULD execute the following steps:

1. Return a Promise promise and execute the next steps in parallel .
2. If an Action identified by name does not exist, reject promise with a ReferenceError and terminate these steps.
3. Otherwise, if no action handler is initialized has been defined for any given name , reject promise with a ReferenceError and terminate these steps.
4. Otherwise, invoke the Action , implementations SHOULD return handler associated with name . If it rejects with error , then reject promise with the same error , otherwise if it resolves with value , then resolve promise with the action is invoked by any client. same value .

5.19 5.15 Examples

Below some ExposedThing interface examples are given.

        try {
  "hljs-keyword">var thing = WoT.produce({ <span class=
"hljs-attr">name: <span class=
"hljs-string">"tempSensor" });
  
  thing.addProperty({
    : <span class=
"hljs-string">"temperature",
    : <span class=
"hljs-number">0.0,
    : <span class=
"hljs-string">'{ "type": "number" }'
    <span class=
"hljs-comment">// use default values for the rest
  }).addProperty({
    : <span class=
"hljs-string">"max",
    : <span class=
"hljs-number">0.0,
    : <span class=
"hljs-string">'{ "type": "number" }'
    <span class=
"hljs-comment">// use default values for the rest
  }).addAction({
    : <span class=
"hljs-string">"reset",
    
  }).addEvent({

"hljs-keyword">var temperatureValueDefinition = {
    type: 
"hljs-string">"number",
    minimum: 
"hljs-number">-50,
    maximum: 
"hljs-number">10000
  };
  
"hljs-keyword">var temperaturePropertyDefinition = temperatureValueDefinition;
  // add the 'forms' property
  temperaturePropertyDefinition.forms = [ ... ];
  var thing = WoT.produce({
    name: "hljs-string">"onchange",
    : <span class=
"hljs-string">'{ "type": "number" }'
  });
  
  thing.setActionHandler(<span class=
"hljs-string">"reset", () => {
    .log(<span class=
"hljs-string">"Resetting maximum");
    thing.writeProperty(<span class=
"hljs-string">"max");
  });
  thing.start().then(<span class=
"hljs-params">() {
      thing.register();

"hljs-string">"tempSensor",
    properties: {      
"hljs-attr">temperature: temperaturePropertyDefinition
    },
    actions: {      reset: {        description: 
"hljs-string">"Reset the temperature sensor",
        input: {          
"hljs-attr">temperature: temperatureValueDefinition
        },
        output: 
"hljs-literal">null,
        forms: []
      },
    },
    events: {      
"hljs-attr">onchange: temperatureValueDefinition
    },
    links: []
  });
  await thing.expose();
  await wot.register("hljs-string">"https://mydirectory.org", thing);

  // define Thing business logic
  setInterval( async () => {
    let mock = Math.random()*100;
    thing.writeProperty(<span class=
"hljs-string">"temperature", mock);

    let old = "hljs-keyword">await thing.readProperty(<span class=
"hljs-string">"max");

"hljs-keyword">await thing["temperature"].read();

    if (old < mock) {
      thing.writeProperty(<span class=
"hljs-string">"max", mock);
      thing.emitEvent();

      await thing["hljs-string">"temperature"].write(mock);
      thing.emitEvent("onchange", mock);

    }
  }, 1000);
} catch (err) {
   console.log("Error creating ExposedThing: " + err);
}

        try {
  var statusValueDefinition = {
    type: "hljs-string">"object",
    properties: {      brightness: {        type: 
"hljs-string">"number",
        minimum: 
"hljs-number">0.0,
        maximum: 
"hljs-number">100.0,
        required: 
"hljs-literal">true
      },
      rgb: {        type: 
"hljs-string">"array",
        "minItems": 
"hljs-number">3,
        "maxItems": 
"hljs-number">3,
        items : {            "type" : 
"hljs-string">"number",
            
"hljs-string">"minimum": 0,
            
"hljs-string">"maximum": 255
        }
      }
  };
  
"hljs-keyword">var statusPropertyDefinition = statusValueDefinition;
  // add the 'forms' property
  statusPropertyDefinition["forms"] = [];
  var thing = WoT.produce({    name: 
"hljs-string">"mySensor",
    properties: {      brightness: {        type: 
"hljs-string">"number",
        minimum: 
"hljs-number">0.0,
        maximum: 
"hljs-number">100.0,
        required: 
"hljs-literal">true,
      },
      
"hljs-attr">status: statusPropertyDefinition
    },
    actions: {      status: {        description: 
"hljs-string">"Get status object",
        input: 
"hljs-literal">null,
        output: {          
"hljs-attr">status : statusValueDefinition;
        },
        forms: []
      },
    },
    events: {      
"hljs-attr">onstatuschange: statusValueDefinition;
    },
    links: []
  });
  thing.expose().then(() => {
      thing.register();
  });
} catch (err) {
   console.log(
"hljs-string">"Error creating ExposedThing: " + err);
}

        let thingDescription = "hljs-string">'{ "@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" } ] }';

"hljs-string">'{ \
  "name": "mySensor", \
  "@context": [ "http://www.w3.org/ns/td",\
     "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ],\
  "@type": [ "Thing", "Sensor" ], \
  "geo:location": "testspace", \
  "properties": { \
    "prop1": { \
      "type": "number",\
      "@type": [ "Property", "Temperature" ], \
      "saref:TemperatureUnit": "degree_Celsius" \
  } } }';

try {
  // note that produce() fails if thingDescription contains error
  let thing = WoT.produce(thingDescription);
  // Interactions were added from TD
  // WoT adds generic handler for reading any property
  // define a specific handler for one property
  let name = "examplePropertyName";
  thing.setPropertyReadHandler(name, () => {
    console.log("Handling read request for " + name);
    return new Promise((resolve, reject) => {
        let examplePropertyValue = 5;
        resolve(examplePropertyValue);
      },
      e => {
        console.log("Error");
      });
  });
  thing.start();

  thing.expose();

} catch(err) {
   console.log("Error creating ExposedThing: " + err);
}

        // fetch an external TD, e.g., to set up a proxy for that Thing
WoT.fetch("http://myservice.org/mySensor/description").then(td => {
  // WoT.produce() ignores instance-specific metadata (security, form)
  let thing = WoT.produce(td);
  // Interactions were added from TD
  // add server functionality
  // ...
});

6.1 The ThingDescription DataSchema dictionary and its subclasses related functionality, such as enumerating

Value types basically represent types that may be used in JSON object definitions and are used in ThingFragment to define Properties , Action s, Event s and links (introspection) Action parameters. Value types are represented as dictionary objects whose properties and possible sub-classes are defined in the DataSchema section of [ WOT-TD ].

One property of all DataSchema dictionary is an API extension that the type property whose value is out from a set of scope for enumerated strings defined in the DataSchema section of [ WOT-TD ] and is referred as DataType in this specification. However,

Based on type , the draft interfaces following sub-classes of DataSchema are defined here for informative purposes. <span class="idlInterface" id= "idl-def-consumedthing-partial-1" data-idl="" data-title= "ConsumedThing">partial interface <span class= "idlInterfaceID"><a data-no-default="" data-link-for="" data-lt="" href="#dom-consumedthing" class="internalDFN" data-link-type= "dfn"> { <span class="idlMethod" id="idl-def-consumedthing-getproperties" data-idl="" data-title="getProperties" data-dfn-for= "consumedthing"> <a href= "https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-thingproperty" class="internalDFN" data-link-type= "dfn"> <span class= "idlMethName"><a data-no-default="" data-link-for="consumedthing" data-lt="getproperties()|getProperties" href= "#dom-consumedthing-getproperties" class="internalDFN" data-link-type="dfn">getProperties <span class="idlMethod" id="idl-def-consumedthing-getactions" data-idl="" data-title="getActions" data-dfn-for= "consumedthing"> <a href= "https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-thingaction" class="internalDFN" data-link-type= "dfn"> <span class= "idlMethName"><a data-no-default="" data-link-for="consumedthing" data-lt="getactions()|getActions" href= "#dom-consumedthing-getactions" class="internalDFN" data-link-type= "dfn">getActions <span class="idlMethod" id="idl-def-consumedthing-getevents" data-idl="" data-title="getEvents" data-dfn-for= "consumedthing"> <a href= "https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-thingevent" class="internalDFN" data-link-type= "dfn"> <span class= "idlMethName"><a data-no-default="" data-link-for="consumedthing" data-lt="getevents()|getEvents" href="#dom-consumedthing-getevents" class="internalDFN" data-link-type= "dfn">getEvents <span class="idlMethod" id="idl-def-consumedthing-getlinks" data-idl="" data-title="getLinks" data-dfn-for= "consumedthing"> <a href= "https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-tdlink" class="internalDFN" data-link-type= "dfn"> <span class= "idlMethName"><a data-no-default="" data-link-for="consumedthing" data-lt="getlinks()|getLinks" href="#dom-consumedthing-getlinks" class="internalDFN" data-link-type= "dfn">getLinks }; in [ WOT-TD ]: BooleanSchema 6.1 , NumberSchema , IntegerSchema , StringSchema , ObjectSchema , ArraySchema .

6.2 The getProperties() SecurityScheme method dictionary and its subclasses

Returns the list of Properties Security metadata is represented as dictionary objects whose properties and sub-classes are defined in the Thing Description SecurityScheme section of [ WOT-TD ].

One property of the Thing SecurityScheme dictionary is the scheme property whose value is from a set of enumerated strings defined in the form SecurityScheme section of a list [ WOT-TD ]. Based on type , multiple subclasses of ThingProperty SecurityScheme objects. are defined.

6.2 6.3 The getActions() Link method dictionary

Returns Represents a Web Link with properties defined in the list Link section of Action [ WOT-TD s ].

6.4 The Form dictionary

Represents metadata describing service details, with properties defined in the Thing Description Form section of [ WOT-TD ].

6.5 The InteractionFragment dictionary

Represents the Thing common properties of WoT Interactions , one of Property , Action or Event , as defined in the form InteractionPattern section of [ WOT-TD ]. Its subclasses are referred as PropertyFragment , ActionFragment and EventFragment .

6.6 The PropertyFragment dictionary

Represents the Property interaction data that initializes a list ThingProperty object. Its properties are defined in the Property and InteractionPattern sections of [ WOT-TD ].

6.7 The ActionFragment dictionary

Represents the Action interaction data that initializes a ThingAction objects. object. Its properties are defined in the Action and InteractionPattern sections of [ WOT-TD ].

6.3 6.8 The getEvents() EventFragment method dictionary

Returns Represents the list of Event s interaction data that initializes a ThingEvent object. Its properties are defined in the Thing Description Event section of the [ WOT-TD ].

6.9 The ThingFragment dictionary

The ThingFragment dictionary is defined as Thing in the form of [ WOT-TD ]. It is a list dictionary that contains properties representing semantic metadata and interactions ( Properties , Action s and Event s). It is used for initializing an internal representation of a Thing Description and its properties may be used in ThingEvent ThingFilter objects. .

6.4 6.10 The getLinks() ThingDescription method type

Returns the list Serialized representation of linked resources in the Thing Description (a JSON-LD document).

6.4.1 7.1 The TDLink Interaction dictionary interface

Contains a hyperlink reference, a relation type The Interaction interface is an abstract class to represent Thing interactions: Properties , Actions and Events .

The InteractionFragment dictionary holds the common properties of PropertyFragment , ActionFragment and EventFragment dictionaries used for initializing ThingProperty , ThingAction and ThingEvent objects in a media type. ThingFragment dictionary used for creating an ExposedThing object.

"idl-def-interaction" data-idl="" data-title=
"Interaction">interface Interaction {
  readonly attribute (Form or FrozenArray<Form>) 
class="internalDFN" data-link-type=
"dfn">
<span class="idlMember" id="idl-def-tdlink-rel" data-idl=""
data-title="rel" data-dfn-for="tdlink">             <span class=
"idlMemberType"><a href=
"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default=""
data-link-for="tdlink" data-lt="" href="#dom-tdlink-rel" class=
"internalDFN" data-link-type=
"dfn">
};

"dfn">forms;
};

"dfn">Interaction includes 

InteractionFragment

;

The TDLink forms read-only property represents the protocol bindings initialization data and is initialized by the WoT Runtime .

7.2 The ThingProperty interface

The ThingProperty interface is used in ConsumedThing and ExposedThing objects to represent Thing Property interactions.

The PropertyFragment dictionary contains is used for initializing Property objects in a ThingFragment dictionary used for creating an ExposedThing object. It MUST implement one of the following properties: DataSchema dictionaries.

"idl-def-thingproperty" data-idl="" data-title=
"ThingProperty">interface ThingProperty : Interaction {
  // getter for PropertyFragment properties
  getter 
"https://heycam.github.io/webidl/#idl-any">any (DOMString name);
  // get and set interface for the Property
  
"https://heycam.github.io/webidl/#idl-promise">Promise<any> read();
  
"https://heycam.github.io/webidl/#idl-promise">Promise<void> write(any value);
};

"dfn">ThingProperty includes PropertyFragment;

"dfn">ThingProperty includes 

Observable

;

The href ThingProperty interface contains all the properties defined on PropertyFragment as read-only properties.

The type attribute read-only property represents the type definition for the Property as a hyperlink reference DataSchema dictionary object.

The writable read-only property tells whether the Property value can be updated. If it is false , then the set(value) method SHOULD always reject.

The observable read-only property tells whether the Property supports subscribing to value change notifications. If it is false , then the subscribe() method SHOULD always fail.

The constant read-only property - defined in DataSchema - tells whether the Property value is a constant. If true , the set() and subscribe() methods SHOULD always fail.

The required read-only property - defined in DataSchema - tells whether the Property should be always present on the ExposedThing object.

The read() method will fetch the value of the Property . Returns a Promise that resolves with the value, or rejects with an error.

The rel write() attribute represents method will attempt to set the value of the Property specified in the value argument whose type SHOULD match the one specified by the type property. Returns a relation Promise that resolves on success, or rejects on an error.

7.3 The ThingAction interface

"idl-def-thingaction" data-idl="" data-title=
"ThingAction">interface ThingAction : Interaction {
  
"https://heycam.github.io/webidl/#idl-promise">Promise<any> invoke(optional any inputValue);
};

"dfn">ThingAction includes 

ActionFragment

;

The invoke() method when invoked, starts the Action interaction with the input value provided by the inputValue argument. If inputValue is null , the action does not take any arguments and rejects if any arguments are provided. If the value is undefined , the action will ignore any arguments provided. Otherwise the type of inputValue SHOULD match the DataSchema definition in the input property. Returns a Promise that will reject with an error or will resolve with a value of type defined by the output property.

7.4 The ThingEvent interface

"idl-def-thingevent" data-idl="" data-title=
"ThingEvent">interface ThingEvent : Interaction {
};

"dfn">ThingEvent includes EventFragment;

"dfn">ThingEvent includes 

ThingProperty

;

Since ThingEvent implements Observable through the ThingProperty interface, event subscription is done by invoking the subscribe() method on the event object that returns a cancelable Subscription .

7.5 The mediaType ExposedEvent attribute represents interface

"idl-def-exposedevent" data-idl="" data-title=
"ExposedEvent">interface ExposedEvent : ThingEvent {
  void emit(any payload);
};

7.6 The value-matching algorithm

The value-matching algorithm is applied to a IANA media value input in relation to a valueType property of type . For TD DataSchema , for instance the value and type properties of a PropertyFragment s there will be registered media types, so applications will be able object, or the inputValue parameter to check whether an the href invoke() link points method of a ThingAction object in relation to the same object. It executes the following steps:

1. If valueType.type is not defined, or does not fully match a TD string enumerated in DataType , i.e. whether return false .
2. Otherwise, if valueType.type is "null" : if value is null , return true , otherwise return false .
3. Otherwise, if valueType.type is "boolean" : if value is either true or false , then return true , otherwise return false .
4. Otherwise, if valueType.type is "integer" : if value is not an integer type defined by the link underlying platform (such as long or long long ), then return false , otherwise execute the following sub-steps:
   1. If valueType.minimum is fetcheable with defined and value is not greater or equal than that value, return false .
   2. If valueType.maximum is defined and value is not less or equal than that value, return false .
   3. Return true .
5. Otherwise, if valueType.type is "number" , if value is not an integer or floating point type defined by the underlying platform (such as long or long long or double ), then return false , otherwise otherwise execute the following sub-steps:
   1. If valueType.minimum is defined and value is not greater or equal than that value, return false .
   2. If valueType.maximum is defined and value is not less or equal than that value, return false .
   3. Return true .
6. Otherwise, if valueType.type is "string" : if value is not a string type defined by the underlying platform, then return false , otherwise return true . In this API. case the algorithm expects a third parameter valueType.enum and runs the following sub-steps:
   • If valueType.enum is an array of strings, then if value fully matches one of the strings defined in the array, return true .
   • Otherwise, return false .
7. Otherwise, if valueType.type is "array" , execute the following sub-steps:
   1. If value is not an array, return false .
   2. If valueType.minItems is defined, and value does not contain at least valueType.minItems elements, return false .
   3. If valueType.maxItems is defined, and value contains more than valueType.maxItems elements, return false .
   4. Otherwise, if valueType.items is undefined , return false .
   5. Otherwise, if valueType.items is null , return true (i.e. any type is accepted as array element, including heterogenous arrays).
   6. Otherwise, for each element of the array value run the value-matching algorithm against the valueType.items object. If any of these runs returns false , then return false .
   7. Otherwise, return true .
8. Otherwise, if type is "object" , execute the following sub-steps:
   1. If value is not an Object , return false .
   2. If valueType.properties is not defined, return false .
   3. If valueType.properties is null , return true (i.e. accept any object value).
   4. For each string in the valueType.required array, if it does not match a property name in the value.properties object or in the value object, then return false .
   5. For each property with name propName and value propDataSchema found in valueType.properties , run the following sub-steps:
      1. If the result of applying the value-matching algorithm on the value value[propName] and propDataSchema is false , then return false .
   6. Return true .