Web of Things (WoT) Scripting API

Fetching a Thing Description

Fetching a TD given a URL should be done with an external method, such as the Fetch API or a HTTP client library, which offer already standardized options on specifying fetch details.

try {
  let res = await fetch('https://tds.mythings.biz/sensor11');
  // ... additional checks possible on res.headers
  let td = await res.json();
  let thing = new ConsumedThing(td);
  console.log("Thing name: " + thing.getThingDescription().title);
} catch (err) {
  console.log("Fetching TD failed", err.message);
}

Expanding a Thing Description

Note that [[WOT-TD]] allows using a shortened Thing Description by the means of defaults and requiring clients to expand them with default values specified in [[WOT-TD]] for the properties that are not explicitly defined in a given TD.

Validating a Thing Description

The [[!WOT-TD]] specification defines how a TD should be validated. Therefore, this API expects the {{ThingDescription}} objects be validated before used as parameters. This specification defines a basic TD validation as follows.

The WOT interface

[SecureContext, Exposed=(Window,Worker)]
interface WOT {
  // methods defined in UA conformance classes
};

Browser implementations should use a namespace object such as navigator.wot. Standalone runtimes may expose the API object through mechanisms like require() or import.

The consume() method

partial interface WOT {
  Promise<ConsumedThing> consume(ThingDescription td);
};

The produce() method

partial interface WOT {
  Promise<ExposedThing> produce(ThingDescription td);
};

The discover() method

partial interface WOT {
  ThingDiscovery discover(optional ThingFilter filter = null);
};

The InteractionInput type

typedef any DataSchemaValue;
typedef (ReadableStream or DataSchemaValue) InteractionInput;

Belongs to the WoT Consumer conformance class and represents the WoT Interaction data provided by application scripts to the UA.

DataSchemaValue is an ECMAScript value that is accepted for DataSchema defined in [[WoT-TD]] (i.e. null, boolean, number, string, array, or object).

{{ReadableStream}} is meant to be used for WoT Interactions that don't have a DataSchema in the Thing Description, only a {{Form}}'s `contentType` that can be represented by a stream.

In practice, any ECMAScript value may be used for WoT Interactions that have a DataSchema defined in the Thing Description, or which can be mapped by implementations to the {{Form}}'s `contentType` defined in the Thing Description.

The algorithms in this document specify how exactly input data is used in WoT Interactions.

The InteractionOutput interface

Belongs to the WoT Consumer conformance class. An {{InteractionOutput}} object is always created by the implementations and exposes the data returned from WoT Interactions to application scripts.

This interface exposes a convenience function which should work in the vast majority of IoT use cases: the value() function. Its implementation will inspect the data, parse it if adheres to a DataSchema, or otherwise fail early, leaving the underlying stream undisturbed so that application scripts could attempt reading the stream themselves, or handling the data as {{ArrayBuffer}}.

[SecureContext, Exposed=(Window,Worker)]
interface InteractionOutput {
  readonly attribute ReadableStream? data;
  readonly attribute boolean dataUsed;
  readonly attribute Form? form;
  readonly attribute DataSchema? schema;
  Promise<ArrayBuffer> arrayBuffer();
  Promise<any> value();
};

The data property represents the raw payload in WoT Interactions as a {{ReadableStream}}, initially `null`.

The dataUsed property tells whether the data stream has been disturbed. Initially `false`.

The form attribute represents the Form selected from the Thing Description for this WoT Interaction, initially `null`.

The schema attribute represents the DataSchema (defined in [[WoT-TD]]) of the payload as a {{JSON}} object, initially `null`.

The [[\value]] internal slot represents the parsed value of the WoT Interaction, initially `undefined` (note that `null` is a valid value).

Using {{InteractionInput}} and {{InteractionOutput}}

As illustrated in the next pictures, the {{InteractionOutput}} interface is used every time implementations provide data to scripts, while {{InteractionInput}} is used when the scripts pass data to the implementation.

When a {{ConsumedThing}} reads data, it receives it from the implementation as an {{InteractionOutput}} object.

An {{ExposedThing}} read handler provides the read data to the implementation as {{InteractionInput}}.

When a {{ConsumedThing}} writes data, it provides it to the implementation as {{InteractionInput}}.

An {{ExposedThing}} write handler receives data from to implementation as an {{InteractionOutput}} object.

When a {{ConsumedThing}} invokes an Action data, it provides the parameters as {{InteractionInput}} and receives the output of the Action as an {{InteractionOutput}} object.

An {{ExposedThing}} action handler receives arguments from the implementation as an {{InteractionOutput}} object and provides Action output as {{InteractionInput}} to the implementation.

Constructing ConsumedThing

After fetching a Thing Description as a JSON object, one can create a {{ConsumedThing}} object.

The getThingDescription() method

Returns the internal slot ||td|| of the {{ConsumedThing}} object that represents the Thing Description of the {{ConsumedThing}}. Applications may consult the Thing metadata stored in ||td|| in order to introspect its capabilities before interacting with it.

The InteractionOptions dictionary

Holds the interaction options that need to be exposed for application scripts according to the Thing Description.

The formIndex property, if defined, represents an application hint for which Form definition, identified by this index, of the TD to use for the given WoT interaction. Implementations SHOULD use the Form with this index for making the interaction, but MAY override this value if the index is not found or not valid. If not defined, implementations SHOULD attempt to use the Form definitions in order of appearance as listed in the TD for the given Wot Interaction.

The uriVariables property if defined, represents the URI template variables to be used with the WoT Interaction that are represented as parsed JSON objects defined in [[!WOT-TD]].

The support for URI variables comes from the need exposed by [[WOT-TD]] to be able to describe existing TDs that use them, but it should be possible to write a Thing Description that would use Actions for representing the interactions that need URI variables and represent the URI variables as parameters to the Action and in that case that could be encapsulated by the implementations and the |options| parameter could be dismissed from the methods exposed by this API.

The data property if defined, represents additional opaque data that needs to be passed to the interaction.

The PropertyMap type

Represents a map of Property names as strings to a value that the Property can take. It is used as a property bag for interactions that involve multiple Properties at once.

It could be defined in Web IDL (as well as {{ThingDescription}}) as a maplike interface from string to any.

The readProperty() method

The readMultipleProperties() method

The readAllProperties() method

The writeProperty() method

As discussed in Issue #193, the design decision is that write interactions only return success or error, not the written value (optionally). TDs should capture the schema of the Property values, including precision and alternative formats. When a return value is expected from the interaction, an Action should be used instead of a Property.

The writeMultipleProperties() method

The WotListener callback

User provided callback that is given an argument of type {{InteractionOutput}} and is used for observing Property changes and handling Event notifications. Since subscribing to Events are WoT interactions and might take options or even data, they are not modelled with software events.

The observeProperty() method

The unobserveProperty() method

The invokeAction() method

The subscribeEvent() method

The unsubscribeEvent() method

ConsumedThing Examples

The next example illustrates how to fetch a TD by URL, create a {{ConsumedThing}}, read metadata (title), read property value, subscribe to property change, subscribe to a WoT event, unsubscribe.

try {
  let res = await fetch("https://tds.mythings.org/sensor11");
  let td = res.json();
  let thing = new ConsumedThing(td);
  console.log("Thing " + thing.getThingDescription().title + " consumed.");
} catch(e) {
  console.log("TD fetch error: " + e.message); },
};

try {
  // subscribe to property change for “temperature”
  await thing.observeProperty("temperature", value => {
    console.log("Temperature changed to: " + parseData(value));
  });
  // subscribe to the “ready” event defined in the TD
  await thing.subscribeEvent("ready", eventData => {
    console.log("Ready; index: " + parseData(eventData));
    // run the “startMeasurement” action defined by TD
    await thing.invokeAction("startMeasurement", { units: "Celsius" });
    console.log("Measurement started.");
  });
} catch(e) {
  console.log("Error starting measurement.");
}

setTimeout( () => {
  console.log(“Temperature: “ +
    parseData(await thing.readProperty(“temperature”)));
  await thing.unsubscribe(“ready”);
  console.log("Unsubscribed from the ‘ready’ event.");
},
10000);

async function parseData(response) {
  let value = undefined;
  try {
    value = await response.value();
  catch(err) {
    // if response.value() fails, try low-level stream read
    if (response.dataUsed)
      return undefined;  // or make a second request

    const reader = value.data.getReader();
    value = null;

    reader.read().then(function process({ done, chunk }) {
        if (done) {
          value += chunk;
          return value;
        }
        value += chunk;
        return reader.read().then(process);
      });
  }
  return value;
};

Constructing {{ExposedThing}}

The {{ExposedThing}} interface extends {{ConsumedThing}}. It is constructed from a full or partial {{ThingDescription}} object.

Note that an existing {{ThingDescription}} object can be optionally modified (for instance by adding or removing elements on its |properties|, |actions| and |events| internal properties) and the resulting object can used for constructing an {{ExposedThing}} object. This is the current way of adding and removing Property, Action and Event definitions, as illustrated in the examples.

Before invoking expose(), the {{ExposedThing}} object does not serve any requests. This allows first constructing {{ExposedThing}} and then initialize its Properties and service handlers before starting serving requests.

Methods inherited from {{ConsumedThing}}

The readProperty(), readMultipleProperties(), readAllProperties(), writeProperty(), writeMultipleProperties(), writeAllProperties() methods have the same algorithmic steps as described in ConsumedThing, with the difference that making a request to the underlying platform MAY be implemented with local methods or libraries and don't necessarily need to involve network operations.

The implementation of {{ConsumedThing}} interface in an {{ExposedThing}} provide the default methods to interact with the {{ExposedThing}}.

After constructing an {{ExposedThing}}, a script can initialize its Properties and can set up the optional read, write and action request handlers (the default ones are provided by the implementation). The script provided handlers MAY use the default handlers, thereby extending the default behavior, but they can also bypass them, overriding the default behavior. Finally, the script would call expose() on the {{ExposedThing}} in order to start serving external requests.

The request handlers actually implement the behavior and it is the responsibility of the developers to keep the Thing Description defined in {{ExposedThing}} synchronized with the implementation of the request handlers.

The PropertyReadHandler callback

A function that is called when an external request for reading a Property is received and defines what to do with such requests. It returns a {{Promise}} and resolves with an {{ReadableStream}} object or an ECMAScript value conforming to DataSchema, or rejects with an error if the property is not found or the value cannot be retrieved.

The setPropertyReadHandler() method

Takes as arguments |name:string| and |handler:PropertyReadHandler|. Sets the service handler that defines what to do when a request is received for reading the specified Property matched by |name|. Throws on error. Returns a reference to |this| object for supporting chaining.

Note that there is no need to register handlers for handling requests for reading multiple or all Properties. The request and reply are transmitted in a single network request, but the ExposedThing may implement them using multiple calls to the single read handler.

The |handler| callback function should implement reading a Property and SHOULD be called by implementations when a request for reading a Property is received from the underlying platform.

There MUST be at most one handler for any given Property, so newly added handlers MUST replace the previous handlers. If no handler is initialized for any given Property, implementations SHOULD implement a default property read handler based on the Thing Description provided in the ||td|| internal slot.

Handling requests for reading a Property

Handling requests for reading multiple Poperties

Handling requests for reading all Properties

The setPropertyObserveHandler() method

Takes as arguments |name:string| and |handler:PropertyReadHandler|. Sets the service handler that defines what to do when a request is received for observing the specified Property matched by |name|. Throws on error. Returns a reference to |this| object for supporting chaining.

The |handler| callback function should implement reading a Property and resolve with an {{InteractionOutput}} object or reject with an error.

There MUST be at most one handler for any given Property, so newly added handlers MUST replace the previous handlers. If no handler is initialized for any given Property, implementations SHOULD implement a default property read handler based on the Thing Description.

Handling Property observe requests

The setPropertyUnobserveHandler() method

Takes as arguments |name:string| and |handler:PropertyReadHandler|. Sets the service handler that defines what to do when a request is received for unobserving the specified Property matched by |name|. Throws on error. Returns a reference to |this| object for supporting chaining.

The |handler| callback function should implement what to do when an unobserve request is received by the implementation.

There MUST be at most one handler for any given Property, so newly added handlers MUST replace the previous handlers. If no handler is initialized for any given Property, implementations SHOULD implement a default handler based on the Thing Description.

Handling Property unobserve requests

The PropertyWriteHandler callback

A function that is called when an external request for writing a Property is received and defines what to do with such requests. Takes as argument |value:InteractionOutput| and returns a {{Promise}}, resolved when the value of the Property - identified by the name provided when setting the handler has been updated -, or rejects with an error if the property is not found or the value cannot be updated.

Note that the code in this callback function can read the property before updating it in order to find out the old value, if needed. Therefore the old value is not provided to this function.

The value is provided by implementations as an {{InteractionOutput}} object in order to be able to represent values that are not described by a DataSchema, such as streams.

The setPropertyWriteHandler() method

Takes as arguments |name:string| and |handler:PropertyWriteHandler|. Sets the service handler that defines what to do when a request is received for writing the Property matched by |name| given when setting the handler. Throws on error. Returns a reference to |this| object for supporting chaining.

Note that even for readonly Properties it is possible to specify a write handler, as explained in Issue 199. In this case, the write handler may define in an application-specific way to fail the request.

There MUST be at most one write handler for any given Property, so newly added handlers MUST replace the previous handlers. If no write handler is initialized for any given Property, implementations SHOULD implement default property update if the Property is writeable and notifying observers on change if the Property is observeable, based on the Thing Description.

Handling requests for writing a Property

Handling requests for writing multiple Properties

The ActionHandler callback

A function that is called when an external request for invoking an Action is received and defines what to do with such requests. It is invoked with |params:InteractionOutput| and optionally with an |options:InteractionOptions| object. It returns a {{Promise}} that rejects with an error or resolves with the value returned by the Action as {{InteractionInput}}.

Application scripts MAY return a {{ReadableStream}} object from an {{ActionHandler}}. Implementations will then use the stream for constructing the Action's response.

The setActionHandler() method

Takes as arguments |name:string| and |action:ActionHandler|. Sets the handler function that defines what to do when a request is received to invoke the Action matched by |name|. Throws on error. Returns a reference to |this| object for supporting chaining.

The |action| callback function will implement an Action and SHOULD be called by implementations when a request for invoking the Action is received from the underlying platform.

There MUST be at most one handler for any given Action, so newly added handlers MUST replace the previous handlers.

Handling Action requests

The EventListenerHandler callback

A function that is called when an associated Event is triggered and provides the data to be sent with the Event to subscribers. Returns a {{Promise}} that resolves with {{InteractionInput}} value that represents the Event data, or rejects with an error.

Applications MAY return {{ReadableStream}} from an {{EventListenerHandler}} Implementations will then use the stream provided in {{InteractionOutput}} when constructing the event notification.

The EventSubscriptionHandler callback

A function that is called when an external request for subscribing to an Event is received and defines what to do with such requests. It is invoked with a |options:InteractionOptions| object provided by the implementation and coming from subscribers. It returns a {{Promise}} that rejects with an error or resolves when the subscription is accepted.

The setEventSubscribeHandler() method

Takes as arguments |name:string| and |handler:EventSubscriptionHandler|. Sets the handler function that defines what to do when a subscription request is received for the specified Event matched by |name|. Throws on error. Returns a reference to |this| object for supporting chaining.

The |handler| callback function SHOULD implement what to do when an subscribe request is received, for instance necessary initializations. Note that the handler for emitting Events is set separately.

There MUST be at most one event subscribe handler for any given Event, so newly added handlers MUST replace the previous handlers.

Handling Event subscribe requests

The setEventUnsubscribeHandler() method

Takes as arguments |name:string| and |handler:EventSubscriptionHandler|. Sets the handler function that defines what to do when the specified Event matched by |name| is unsubscribed from. Throws on error. Returns a reference to |this| object for supporting chaining.

The |handler| callback function SHOULD implement what to do when an unsubscribe request is received.

There MUST be at most one handler for any given Event, so newly added handlers MUST replace the previous handlers.

Handling Event unsubscribe requests

The setEventHandler() method

Takes as arguments |name:string| and |eventHandler:EventListenerHandler|. Sets the event handler function for the specified Event matched by |name|. Throws on error. Returns a reference to |this| object for supporting chaining.

The |eventHandler| callback function will implement what to do when the event is emitted. It SHOULD resolve with a value that represents the Event data, or reject with an error.

There MUST be at most one handler for any given Event, so newly added handlers MUST replace the previous handlers.

Handling Events

The emitEvent() method

The expose() method

The destroy() method

ExposedThing Examples

The next example illustrates how to create an {{ExposedThing}} based on a partial TD object constructed beforehands.

try {
  let temperaturePropertyDefinition = {
    type: "number",
    minimum: -50,
    maximum: 10000
  };
  let tdFragment = {
    properties: {
      temperature: temperaturePropertyDefinition
    },
    actions: {
      reset: {
        description: "Reset the temperature sensor",
        input: {
          temperature: temperatureValueDefinition
        },
        output: null,
        forms: []
      },
    },
    events: {
      onchange: temperatureValueDefinition
    }
  };
  let thing1 = await WOT.produce(tdFragment);
  // initialize Properties
  await thing1.writeProperty("temperature", 0);
  // add service handlers
  thing1.setPropertyReadHandler("temperature", () => {
     return readLocalTemperatureSensor();  // Promise
  });
  // start serving requests
  await thing1.expose();
} catch (err) {
   console.log("Error creating ExposedThing: " + err);
}

The next example illustrates how to add or modify a Property definition on an existing {{ExposedThing}}: take its |td| property, add or modify it, then create another {{ExposedThing}} with that.

try {
  // create a deep copy of thing1's TD
  let instance = JSON.parse(JSON.stringify(thing1.td));
  const statusValueDefinition = {
    type: "object",
    properties: {
      brightness: {
        type: "number",
        minimum: 0.0,
        maximum: 100.0,
        required: true
      },
      rgb: {
        type: "array",
        "minItems": 3,
        "maxItems": 3,
        items : {
            "type" : "number",
            "minimum": 0,
            "maximum": 255
        }
      }
  };
  instance["name"] = "mySensor";
  instance.properties["brightness"] = {
    type: "number",
    minimum: 0.0,
    maximum: 100.0,
    required: true,
  };
  instance.properties["status"] = statusValueDefinition;
  instance.actions["getStatus"] = {
    description: "Get status object",
    input: null,
    output: {
      status : statusValueDefinition;
    },
    forms: [...]
  };
  instance.events["onstatuschange"] = statusValueDefinition;
  instance.forms = [...];  // update
  var thing2 = new ExposedThing(instance);
  // TODO: add service handlers
  await thing2.expose();
  });
} catch (err) {
   console.log("Error creating ExposedThing: " + err);
}

Constructing {{ThingDiscovery}}

The start() method sets active to `true`. The stop() method sets the active property to |false|, but done may be still `false` if there are {{ThingDescription}} objects in the discovery results not yet consumed with next().

During successive calls of next(), the active property may be `true` or `false`, but the done property is set to `false` by next() only when both the active property is `false` and discovery results is empty.

The DiscoveryMethod enumeration

typedef DOMString DiscoveryMethod;

Represents the discovery type to be used:

• "any" does not provide any restriction
• "local" for discovering Things defined in the same device or connected to the device by wired or wireless means.
• "directory" for discovery based on a service provided by a Thing Directory.
• "multicast" for discovering Things in the device's network by using a supported multicast protocol.

The ThingFilter dictionary

Represents an object containing the constraints for discovering Things as key-value pairs.

dictionary ThingFilter {
  (DiscoveryMethod or DOMString) method = "any";
  USVString? url;
  USVString? query;
  object? fragment;
};

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 MAY 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 target entity serving the discovery request, for instance the URL of a Thing Directory (if method is `"directory"`), or otherwise the URL of a directly targeted Thing.

The query property represents a query string accepted by the implementation, for instance a SPARQL or JSON query. Support may be implemented locally in the WoT Runtime or remotely as a service in a Thing Directory.

The fragment property represents a template object used for matching property by property against discovered Things.

The start() method

The next() method

The stop() method

Discovery Examples

The following example finds {{ThingDescription}} objects of Things that are exposed by local hardware, regardless how many instances of WoT Runtime it is running. Note that the discovery can end (become inactive) before the internal discovery results queue is emptied, so we need to continue reading {{ThingDescription}} objects until done. This is typical with local and directory type discoveries.

let discovery = new ThingDiscovery({ method: "local" });
do {
  let td = await discovery.next();
  console.log("Found Thing Description for " + td.title);
  let thing = new ConsumedThing(td);
  console.log("Thing name: " + thing.getThingDescription().title);
} while (!discovery.done);

The next example finds {{ThingDescription}} objects of Things listed in a Thing Directory service. We set a timeout for safety.

let discoveryFilter = {
  method: "directory",
  url: "http://directory.wotservice.org"
};
let discovery = new ThingDiscovery(discoveryFilter);
setTimeout( () => {
    discovery.stop();
    console.log("Discovery stopped after timeout.");
  },
  3000);
do {
  let td = await discovery.next();
  console.log("Found Thing Description for " + td.title);
  let thing = new ConsumedThing(td);
  console.log("Thing name: " + thing.getThingDescription().title);
} while (!discovery.done);
if (discovery.error) {
  console.log("Discovery stopped because of an error: " + error.message);
}

The next example is for an open-ended multicast discovery, which likely won't complete soon (depending on the underlying protocol), so stopping it with a timeout is a good idea. It will likely deliver results one by one.

let discovery = new ThingDiscovery({ method: "multicast" });
setTimeout( () => {
    discovery.stop();
    console.log("Stopped open-ended discovery");
  },
  10000);
do {
  let td = await discovery.next();
  let thing = new ConsumedThing(td);
  console.log("Thing name: " + thing.getThingDescription().title);
} while (!discovery.done);

Scripting Runtime Security and Privacy Risks

This section is normative and contains specific risks relevant for the WoT Scripting Runtime.