Web of Things (WoT) Scripting API

4.1 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);
}

4.2 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.

4.3 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.

5.1 The WOT interface

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

5.2 The consume() method

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

5.3 The produce() method

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

5.4 The discover() method

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

6.1 Constructing ConsumedThing

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

6.2 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.

6.3 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].

6.4 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.

6.5 The readProperty() method

6.6 The readMultipleProperties() method

6.7 The readAllProperties() method

6.8 The writeProperty() method

6.9 The writeMultipleProperties() method

6.10 The WotListener callback

User provided callback that takes any argument and is used for observing Property changes and handling Event notifications. Since subscribing to these are WoT interactions, they are not modelled with software events.

6.11 The observeProperty() method

6.12 The unobserveProperty() method

6.13 The invokeAction() method

6.14 The subscribeEvent() method

6.15 The unsubscribeEvent() method

6.16 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;
};

7.1 The arrayBuffer() function

1. Return a Promise promise and execute the next steps in parallel.
2. If data is not ReadableStream or if dataUsed is true, reject|promise| with NotReadableError and abort these steps.
3. Let reader be the result of getting a reader from data. If that threw an exception, reject promise with that exception and abort these steps.
4. Let bytes be the result of reading all bytes from data with reader.
5. Set dataUsed to true.
6. Let arrayBuffer be a new ArrayBuffer whose contents are bytes. If that throws, reject promise with that exception and abort these steps.
7. Resolve promise with arrayBuffer.

7.2 The value() function

1. Return a Promise promise and execute the next steps in parallel.
2. If the value of the [[value]] internal slot is not undefined, resolve promise with that value and abort these steps.
3. If the value of the data property is not a ReadableStream or if dataUsed is true, or if form is null or if schema or its type are null or undefined, reject promise with NotReadableError and abort these steps.
4. If form's contentType is not application/json and if a mapping is not available in the Protocol Bindings from form's contentType to [JSON-SCHEMA], reject promise with NotSupportedError and abort these steps.
5. Let reader be the result of getting a reader from data. If that threw an exception, reject promise with that exception and abort these steps.
6. Let bytes be the result of reading all bytes from data with reader.
7. Set dataUsed to true.
8. If form's contentType is not application/json and if a mapping is available in the Protocol Bindings from form's contentType to [JSON-SCHEMA], transform bytes with that mapping.
9. Let json be the result of running parse JSON from bytes on bytes. If that throws, reject promise with that exception and abort these steps.
10. Set [[value]] to the result of running check data schema on json and schema. If that throws, reject promise with that exception and abort these steps.
11. Resolve promise with [[value]].

7.3 The check data schema algorithm

1. Let type be schema's type.
2. If type is "null" and if payload is not null, throw TypeError and abort these steps, otherwise return null.
3. If type is "boolean" and payload is a falsey value or its byte length is 0, return false, otherwise return true.
4. If type is "integer" or "number",
   1. If payload is not a number, throw TypeError and abort these steps.
   2. If form's minimum is defined and payload is smaller, or if form's maximum is defined and payload is bigger, throw RangeError and abort these steps.
5. If type is "string", return payload.
6. If type is "array", run these sub-steps:
   1. If payload is not an array, throw TypeError and abort these steps.
   2. If form's minItems is defined and payload's length is less than that, or if form's maxItems is defined and payload's length is more than that, throw RangeError and abort these steps.
   3. Let payload be an array of items obtained by running the check data schema steps on each element item of payload and schema's items. If this throws at any stage, re-throw that exception and abort these steps.
7. If type is "object", run these sub-steps:
   1. If payload or schema's properties is not an object, throw TypeError and abort these steps.
   2. For each property key in payload,
      1. Let prop be the value of key.
      2. Let propSchema be the value of key in interaction's properties.
      3. Let prop be the result of running the check data schema steps on prop and propSchema. If this throws, re-throw that exception and abort these steps.
   3. Let required be schema's required if that is an array or an empty array otherwise.
   4. For each key in required, if key is not present in payload, throw SyntaxError and abort these steps.
8. Return payload.

7.4 The create interaction data algorithm

1. If source is an InteractionData object whose data is a ReadableStream, set its form to form, return source and abort these steps.
2. Let idata be a new an InteractionData object whose [[value]] internal slot is undefined, whose form is form, whose schema is set to schema and whose data is null.
3. If schema's type is defined, run these sub-steps:
   1. If type is "null" and source is not, throw TypeError and abort these steps.
   2. If type is "boolean" and source is a falsy value, set idata's [[value]] value to false, otherwise to true.
   3. If type is "integer" or "number" and source is not a number, or if form's minimum is defined and source is smaller, or if form's maximum is defined and source is bigger, throw RangeError and abort these steps.
   4. If type is "string" and source is not a string, let idata's [[value]] be the result of running serialize JSON to bytes on source. If that is failure, throw SyntaxError and abort these steps.
   5. If type is "array", run these sub-steps:
      1. If source is not an array, throw a TypeError and abort these steps.
      2. Let length be the length of source.
      3. If form's minItems is defined and length is less than that, or if form's maxItems is defined and length is more than that, throw RangeError and abort these steps.
      4. For each item in source, let itemschema be schema's items and let item be the result of running the create interaction data steps on item, form and itemschema. If this throws, re-throw that exception and abort these steps.
      5. Set data's [[value]] to source.
   6. If type is "object", run these sub-steps:
      1. If source is not an object, throw TypeError and abort these steps.
      2. If schema's properties is not an object, throw TypeError and abort these steps.
      3. For each property key in source,
         1. Let value be the value of key.
         2. Let propschema be the value of key in properties.
         3. Let value be the result of running the create interaction data steps on value, form and propschema. If this throws, re-throw that exception and abort these steps.
      4. If schema's required is an array, for each item in required check if item is a property name in source. If an item is not found in source, throw SyntaxError and abort these steps.
      5. Set data's [[value]] to source.
4. Set idata's data to a new ReadableStream created from idata's [[value]] internal slot as its underlying source.
5. Return idata.

7.5 The parse interaction response algorithm

1. Let result be a new InteractionData object.
2. Let result's schema be schema.
3. Let result's form be form.
4. Let result's data be a new ReadableStream with the payload data of response as its underlying source.
5. Let result's dataUsed be false.
6. Return result.

8.1 Constructing ExposedThing

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

8.2 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.

8.3 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 it when the value of the Property matching the name argument is obtained, or rejects with an error if the property is not found or the value cannot be retrieved.

8.4 The setPropertyReadHandler() method

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

The readHandler 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.

8.5 Handling Property read requests

8.6 Handling Property observe requests

8.7 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. It expects the requested new value as argument and returns a Promise which is resolved when the value of the Property that matches the name argument has been updated with value, or rejects with an error if the property is not found or the value cannot be updated.

8.8 The setPropertyWriteHandler() method

Takes name as string argument and writeHandler as argument of type PropertyWriteHandler. Sets the service handler that will be used for serving write requests for writing the specified Property matched by name. Throws on error. Returns a reference to this object for supporting chaining.

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.

8.9 Handling Property write requests

8.10 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 a params dictionary argument. It returns a Promise that rejects with an error or resolves if the action is successful.

8.11 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. May throw an 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.

8.12 Handling Action requests

8.13 The emitEvent() method

8.14 The expose() method

8.15 The destroy() method

8.16 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);
}

9.1 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.

9.2 The DiscoveryMethod enumeration

WebIDLtypedef 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.

9.3 The ThingFilter dictionary

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

WebIDLdictionary 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.

9.4 The start() method

9.5 The next() method

9.6 The stop() method

9.7 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);

10.1 Scripting Runtime Security and Privacy Risks

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