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

Refer to the ThingDiscovery section for how discovery should be implemented.

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. In this version of the specification only URI template variables are used, 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 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

The writeMultipleProperties() method

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.

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: " + value);
          });
          // subscribe to the “ready” event defined in the TD
          await thing.subscribeEvent("ready", eventData => {
            console.log("Ready; index: " + 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: “ + await thing.readProperty(“temperature”));
          await thing.unsubscribe(“ready”);
          console.log("Unsubscribed from the ‘ready’ event.");
        },
        10000);
      

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

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.

Handling Property read requests

Handling Property observe 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. 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.

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 setPropertyWriteHandler() method

Takes name as string argument and writeHandler as argument of type PropertyWriteHandler. Sets the service handler 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 and notifying observers on change, based on the Thing Description.

Handling Property write requests

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.

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 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 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 active 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(), active may be true or false, but done is set to false by next() only when both active 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 that of a Thing (otherwise).

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.