Abstract

The Web of Things (WoT) provides layered interoperability between Things by using the WoT Interfaces.

This specification describes a programming interface representing the WoT Interface that allows scripts run on a Thing to discover and consume (retrieve) other Things and to expose Things characterized by properties, Actions and Events.

Scripting is an optional "convenience" building block in WoT and it is typically used in gateways that are able to run a WoT Runtime and script management, providing a convenient way to extend WoT support to new types of endpoints and implement WoT applications like Thing Directory.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

Implementers need to be aware that this specification is considered unstable. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation phase should subscribe to the repository and take part in the discussions.

Editor's note: The W3C WoT WG is asking for feedback

Please contribute to this draft using the GitHub Issue feature of the WoT Scripting API repository. For feedback on security and privacy considerations, please use the WoT Security and Privacy Issues.

This document was published by the Web of Things Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation.

Comments regarding this document are welcome. Please send them to public-wot-wg@w3.org (subscribe, archives).

Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2017 W3C Process Document.

1. Introduction

The overall WoT concepts are described in the WoT Architecture document. The Web of Things is made of entities (Things) that can describe their capabilities in a machine-interpretable format, the Thing Description (TD) and expose these capabilities through the WoT Interface. Support for scripting is optional for WoT devices.

By consuming a TD, a client Thing creates a runtime resource model that allows accessing the properties, Actions and Events exposed by the server Thing.

Exposing a Thing requires defining a Thing Description and instantiating a software stack needed to serve requests for accessing the exposed properties, Actions and Events. This specification describes how to expose and consume Things by a script.

Note

Typically scripts are meant to be used on devices able to provide resources (with a WoT interface) for managing (installing, updating, running) scripts, such as bridges or gateways that expose and control simpler devices as WoT Things.

For an introduction on how scripts could be used in Web of Things, check the Primer document. For some background on API design decisions check the Rationale document.

2. Use Cases

This section is non-normative.

The following scripting use cases are covered in this specification:

The following use cases are being considered for next versions:

3. The WoT object

The WoT object is the main API entry point and it is exposed by an implementation of the WoT Runtime. The WoT object has no internal state and provides methods for discovering, consuming and exposing a Thing.

Note

Browser implementations SHOULD use a namespace object such as wot, and Node.js-like runtimes MAY provide the API object through the require() or import mechanism. 

interface WoT {
    Observable<ConsumedThing> discover(optional ThingFilter filter);
    Promise<ConsumedThing>    consume(USVString url);
    Promise<ExposedThing>     expose(ThingInit init);
};
Editor's note

The algorithms for the WoT methods will be specified later.

3.1 The discover() method

Starts the discovery process that will provide ConsumedThing objects that match the optional argument ThingFilter . When the argument is not provided, starts the widest discovery the Thing Description and Protocol Bindings allow. Returns an Observable object that can be subscribed and unsubscribed to.

3.1.1 The ThingFilter dictionary

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

dictionary ThingFilter {
    (DiscoveryType or DOMString) method = "any";
    USVString                    url;
    Dictionary                   description;
};

The method property represents the discovery type that should be used in the discovery process. The possible values are defined by the DiscoveryMethod enumeration that can be extended by string values defined by solutions (with no guarantee of interoperability).

The url property represents additional information for the discovery method, such as the URL of the Thing Directory server to be used.

The description property represents additional information for the discovery method in the form of a set of key-value pairs, as defined in the Thing Description.

Editor's note

The DiscoveryMethod enumeration can be extended by the Thing Description with values that are not specified here. This extensibility of DiscoveryMethod by proprietary or private methods is a working assumption until consensus is formed and may be removed later.

Editor's note

The ThingFilter dictionary may be extended later with further attributes.

3.1.2 The DiscoveryMethod enumeration

enum DiscoveryMethod {
    "any",
    "local",
    "nearby",
    "directory",
    "broadcast",
    "other"
};

The DiscoveryMethod enumeration represents the discovery type to be used:

  • "any" does not provide any restriction
  • "local" for discovering Things defined in the same device
  • "nearby" for discovering Things nearby the device, e.g. by Bluetooth or NFC
  • "directory" for discovery based on a service provided by a directory or repository of Things
  • "broadcast" for an open ended discovery based on sending a request to a broadcast address
  • "other" for a proprietary method defined by the solution.

3.2 The consume() method

Accepts an url argument and returns a Promise of a ConsumedThing.

3.3 The expose() method

Returns a Promise of a locally created ExposedThing based on the provided initialization parameters.

Editor's note

The reason ExposedThings are created by a factory method instead of a constructor is that an ExposedThing may be created in the local WoT Runtime or in a remote runtime. Even though currently only local creation is supported, the method is designed with this possible future compatibility in mind.

3.3.1 The ThingInit dictionary

dictionary ThingInit {
    DOMString  name;
    USVString  url;
    Dictionary description;
};

The ThingInit dictionary contains properties to initialize a Thing:

  • The name attribute represents the user given name of the Thing.
  • The url attribute represents the address of the Thing.
  • The description attribute represents the Thing Description of the Thing.

3.4 Examples

Example 1: Discover Things via directory
let discoveryType = { method: "directory", url: "http://directory.wotservice.org" };
let subscription = wot.discover(discoveryType).subscribe(
  thing => { console.log("Found Thing " + thing.url); },
  error => { console.log("Discovery finished because an error: " + error.message); },
  () => { console.log("Discovery finished successfully");}
);
setTimeout(
  () => { subscription.unsubscribe(); console.log("Discovery timeout"); },
  5000);
Note

Note that canceling a discovery (through unsubscribe) may not be successful in all cases, for instance when discovery is based on open ended broadcast requests. However, once unsubscribe() has been called, implementations MUST suppress further event handling ( i.e. further discoveries and errors) on the Observable. Also, a discovery error may not mean the end of the discovery process. However, in order to respect Observable semantics (error always terminates processing), implementations MUST close or suppress further event handling on the Observable.

Example 2: Discover Things exposed by local hardware
let subscription = wot.discover({ method: "local" }).subscribe(
  thing => { console.log("Found local Thing " + thing.url); },
  error => { console.log("Discovery error: " + error.message); },
  () => { console.log("Discovery finished successfully");}
);
Example 3: Discover Things exposed nearby, e.g. via Bluetooth
let subscription = wot.discover({ method: "nearby", description: {protocol: "BLE4.2"} }).subscribe(
  thing => { console.log("Found nearby Thing " + thing.url); },
  error => { console.log("Discovery error: " + error.message); },
  () => { console.log("Discovery finished successfully");}
);
Example 4: Discover Things exposed in a proprietary way
let subscription = wot.discover({ method: "other", description: { solution: "XYZ123", key: "..."} }).subscribe(
  thing => { console.log("Found Thing " + thing.url); },
  error => { console.log("Discovery error: " + error.message); },
  () => { console.log("Discovery finished successfully");}
);

4. The ConsumedThing interface

The ConsumedThing interface is a client API for sending requests to servers in order to retrieve or update properties, invoke Actions, and observe properties, Actions and Events. 

interface ConsumedThing {
    readonly attribute DOMString        name;
    readonly attribute USVString        url;
    readonly attribute ThingDescription description;
    Promise<any>  invokeAction(DOMString name, any parameters);
    Promise<void> setProperty(DOMString name, any value);
    Promise<any>  getProperty(DOMString name);
    ConsumedThing addListener(DOMString eventName, ThingEventListener listener);
    ConsumedThing removeListener(DOMString eventName,
                                 ThingEventListener listener);
    ConsumedThing removeAllListeners(optional DOMString eventName);
    Observable    observe(DOMString name, RequestType requestType);
};

callback ThingEventListener = void (Event event);

Represents a local proxy object of the remote Thing.

4.1 The invokeAction() method

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

4.2 The setProperty() method

Takes the Property name as the name argument and the new value as the value argument, then requests from the underlying platform and the Protocol Bindings to update the Property on the remote Thing and return the result. Returns a Promise that resolves on success or rejects with an Error.

4.3 The getProperty() method

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

4.4 The addListener() method

Adds the listener provided in the argument listener to the Event name provided in the argument eventName.

4.5 The removeListener() method

Removes a listener from the Event identified by the provided eventName and listener argument.

4.6 The removeAllListeners() method

Removes all listeners for the Event provided by the eventName optional argument, or if that was not provided, then removes all listeners from all Events.

4.7 The observe() method

Returns an Observable for the Property, Event or Action specified in the name argument, allowing subscribing and unsubscribing to notifications. The requestType specifies whether a Property, an Event or an Action is observed.

Editor's note

The observe() method could replace addListener() and removeListener(), though they could be kept for convenience.

4.8 The ThingEventListener callback

A function called with an Event object when an event is emitted.

4.9 Events

Clients can subscribe to the Events defined in ExposedThing events. The event types are described in this section.

4.9.1 The PropertyChangeEvent interface

[Constructor(PropertyChangeEventInit init)]
interface PropertyChangeEvent : Event {
    readonly attribute PropertyChangeEventInit data;
};

The data attribute represents the changed Property.

4.9.1.1 The PropertyChangeEventInit dictionary
dictionary PropertyChangeEventInit {
    DOMString name;
    any       value;
};

The name> attribute represents the Property name.

The value attribute represents the new value of the Property.

4.9.2 The ActionInvocationEvent interface

[Constructor(ActionInvocationEventInit init)]
interface ActionInvocationEvent : Event {
    readonly attribute ActionInvocationEventInit data;
};

The data attribute represents the notification data from the Action invocation.

4.9.2.1 The ActionInvocationEventInit dictionary
dictionary ActionInvocationEventInit {
    DOMString actionName;
    any       returnValue;
};
Editor's note

Action parameters could be also included, but it's debatable because privacy reasons.

The actionName attribute represents the name of the Action that has been invoked.

The returnValue attribute represents the return value of the Action.

4.9.3 The ThingDescriptionChangeEvent interface

[Constructor(ThingDescriptionChangeEventInit init)]
interface ThingDescriptionChangeEvent : Event {
    readonly attribute ThingDescriptionChangeEventInit data;
};

The data attribute represents the changes that occurred to the Thing Description.

4.9.3.1 The ThingDescriptionChangeEventInit dictionary
dictionary ThingDescriptionChangeEventInit {
    TDChangeType     type;
    TDChangeMethod   method;
    DOMString        name;
    TDChangeData     data;
    ThingDescription description;
};
  • The type attribute represents the change type, whether has it been applied on properties, Actions or Events.
  • The method attribute tells what operation has been applied, addition, removal or change.
  • The name attribute represents the name of the Property, Action or event that has changed.
  • The description attribute is defined for the addition and change methods, and represents the new description.
  • The data attribute provides the initialization data for the added or changed elements.
4.9.3.1.1 The TDChangeMethod enumeration
4.9.3.1.2 The TDChangeType enumeration
  • The property value tells the operation was applied on a Property definition.
  • The action value tells the operation was applied on a action definition.
  • The event value tells the operation was applied on an event definition.
4.9.3.1.3 The TDChangeData type

Represents the new description of the changed element. Depending on the change type, it can be either a ThingPropertyInit, ThingActionInit, or ThingEventInit.

4.10 Examples

Below a ConsumedThing interface example is given.

Example 5: Consume a Thing
wot.consume("http://mmyservice.org/mySensor").then( thing => {
    console.log("Thing " + thing.name + " has been consumed.");
    console.log("{ " + JSON.serialize(thing) + " }");
    thing.addListener("onchange", function(event) {
        if (event instanceof PropertyChangeEvent) {
            console.log("Property " + event.name + " value has changed to " + event.value);
        }
    }).invokeAction("startMeasurement", ["Celsius"]);
  },
).catch(error => {
  console.log("Discovery finished because an error: " + error.message);
});

5. The ExposedThing interface

The ExposedThing interface is the server API that allows defining request handlers, properties, Actions, and Events to a Thing. 

typedef USVString ThingDescription;

callback RequestHandler = any (Request request);

interface ExposedThing {
    // define Thing Description modifiers
    ExposedThing  addProperty(ThingPropertyInit property);
    ExposedThing  removeProperty(DOMString name);
    ExposedThing  addAction(ThingActionInit action);
    ExposedThing  removeAction(DOMString name);
    ExposedThing  addEvent(ThingEventInit event);
    ExposedThing  removeEvent(DOMString name);
    // define request handlers
    ExposedThing  onRetrieveProperty(RequestHandler handler);
    ExposedThing  onUpdateProperty(RequestHandler handler);
    ExposedThing  onInvokeAction(RequestHandler handler);
    ExposedThing  onObserve(RequestHandler handler);
    // define how to expose and run the Thing
    Promise<void> register(optional USVString directory);
    Promise<void> unregister(optional USVString directory);
    Promise<void> start();
    Promise<void> stop();
    Promise<void> emitEvent(DOMString eventName, any payload);
};

ExposedThing implements ConsumedThing;

5.1 The ThingDescription type

WoT provides a unified representation for data exchange between Things, standardized in the Wot Things Description specification.

Note

In this version of the API, Thing Descriptions are represented as opaque strings, denoting a serialized form, for instance JSON or JSON-LD. See Issue 38 and Issue 45. Parsing and composing Thing Descriptions is left for external libraries until standardized here.

5.2 The Request interface

interface Request {
    readonly attribute RequestType type;
    readonly attribute USVString   from;
    readonly attribute DOMString   name;
    readonly attribute Dictionary  options;
    readonly attribute any         data;
    Promise respond(any response);
    void    respondWithError(Error error);
};

Represents an incoming request the ExposedThing is supposed to handle, for instance retrieving and updating properties, invoking Actions and observing Events (WoT interactions).

5.2.1 The RequestType enumeration

enum RequestType {
    "property",
    "action",
    "event",
    "td"
};
  • The value "property" represents requests to retrieve or update a Property.
  • The value "action" represents requests to invoke an Action.
  • The value "event" represents requests to emit an event.
  • The value "td" represents requests to change the Thing Description, i.e. to add, remove or modify properties, Actions or Events.
    Editor's note

    This functionality is here for the sake of completeness for future versions of the API. Currently there is no corresponding functionality at the ConsumedThing level and it is not guaranteed that a Thing Description could be remotely changed by scripting.

5.2.2 The respond() method

Sends a positive response to the Request based on the Protocol Bindings and includes the data specified by the data argument.

5.2.3 The respondWithError() method

Sends a negative response to the Request based on the Protocol Bindings and includes the error specified by the error argument.

5.3 The RequestHandler callback

Callback function for handling interaction requests. Receives an argument request of type Request and should return an object or value that is used by Protocol Bindings to reply to the request. The returned type is defined by the Thing Description.

5.4 The addProperty() method

Adds a Property defined by the argument and updates the Thing Description.

5.4.1 The ThingPropertyInit dictionary

dictionary ThingPropertyInit {
    DOMString              name;
    boolean                configurable = true;
    boolean                enumerable = true;
    boolean                writable = true;
    sequence<SemanticType> semanticTypes;
    ThingDescription       description;
    any                    value;
};

Represents the Thing Property description.

  • The name attribute represents the name of the Property.
  • The value attribute represents the value of the Property.
  • The configurable attribute defines whether the Property can be deleted from the object and whether its properties can be changed. The default value is false.
  • The enumerable attribute defines whether the Property can be listed and iterated. The default value is true.
  • The writable attribute defines whether the Property can be updated. The default value is true.
  • The semanticTypes attribute represents a list of semantic type annotations (e.g. labels, classifications etc) relevant to the Property, represented as SemanticType dictionaries.
  • The description attribute represents the Property description to be added to the Thing Description.

5.4.2 The SemanticType dictionary

dictionary SemanticType {
    DOMString name;
    USVString context;
};

Represents a semantic type annotation, containing a name and a context.

  • The name attribute represents the name of the semantic type in the given context.
  • The context attribute represents an URL link to the context of the semantic classification.
Editor's note

Semantic type examples to be added.

5.5 The removeProperty() method

Removes the Property specified by the name argument, updates the Thing Description and returns the object.

5.6 The addAction() method

Adds an Action to the Thing object as defined by the action argument of type ThingActionInit and updates the Thing Description.

5.6.1 The ThingActionInit dictionary

dictionary ThingActionInit {
    DOMString              name;
    ThingDescription       inputDataDescription;
    ThingDescription       outputDataDescription;
    sequence<SemanticType> semanticTypes;
    Function               action;
};

The ThingActionInit dictionary describes the arguments and the return value.

  • The name attribute provides the Action name.
  • The action attribute provides a function that defines the Action.
  • The inputDataDescription attribute provides the description of the input arguments.
  • The outputDataDescription attribute provides the description of the returned data.
  • The semanticTypes attribute provides a list of semantic type annotations (e.g. labels, classifications etc) relevant to the Action, represented as SemanticType dictionaries.

5.7 The removeAction() method

Removes the Action specified by the name argument, updates the Thing Description and returns the object.

5.8 The addEvent() method

Adds an event to the Thing object as defined by the event argument of type ThingEventInit and updates the Thing Description.

5.8.1 The ThingEventInit dictionary

dictionary ThingEventInit {
    DOMString              name;
    sequence<SemanticType> semanticTypes;
    ThingDescription       dataDescription;
};
  • The name attribute represents the event name.
  • The semanticTypes attribute represent a list of semantic type annotations attached to the event.
  • The dataDescription attribute represents the description of the data that is attached to the event.

5.9 The removeEvent() method

Removes the event specified by the name argument, updates the Thing Description and returns the object.

5.10 The onRetrieveProperty() method

Registers the handler function for Property retrieve requests received for the Thing, as defined by the handler property of type RequestHandler . The handler will receive an argument request of type Request where at least request.name is defined and represents the name of the Property to be retrieved.

5.11 The onUpdateProperty() method

Defines the handler function for Property update requests received for the Thing, as defined by the handler property of type RequestHandler . The handler will receive an argument request of type Request where request.name defines the name of the Property to be retrieved and request.data defines the new value of the Property.

5.12 The onInvokeAction() method

Defines the handler function for Action invocation requests received for the Thing, as defined by the handler property of type RequestHandler . The handler will receive an argument request of type Request where request.name defines the name of the Action to be invoked and request.data defines the input arguments for the Action as defined by the Thing Description.

5.13 The onObserve() method

Defines the handler function for observe requests received for the Thing, as defined by the handler property of type RequestHandler . The handler will receive an argument request of type Request where

5.14 The register() method

Generates the Thing Description given the properties, Actions and Event defined for this object. If a directory argument is given, make a request to register the Thing Description with the given WoT repository by invoking its register Action.

5.15 The unregister() method

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

5.16 The start() method

Start serving external requests for the Thing.

5.17 The stop() method

Stop serving external requests for the Thing.

5.18 The emitEvent() method

Emits an the event initialized with the event name specified by the eventName argument and data specified by the payload argument.

5.19 Events supported by ExposedThing

The following default events SHOULD be supported by ExposedThing implementations:

In addition, user defined events are specified by the Thing Description.

5.20 Examples

Below some ExposedThing interface examples are given.

Example 6: Create a new blank exposed Thing
WoT.createExposedThing(thingDescription)
  .then(function(thing) {
    // manually add properties, actions, and events
    thing.addProperty({
      name: "temperature",
      value: "0",
      writable: false
      // use default values for the rest
    }).addEvent({
      name: "onchange",
      outputDataDescription: {
        type: "float32"
      }
    }).addAction({
      name: "reset",
      action: () => { this.temperature = 0; }
    })
    // add server functionality
    .onRetrieveProperty( request => {
      console.log("Handling read request");
      return this.temperature;
    }).onObserve( request => {
      console.log("Handling observe request");
      // add listener identified by request.from
    }).onInvokeAction( request => {
      console.log("Handling action request");
    }).start();
  });
Example 7: Create a new exposed Thing from a TD URI
let thingDescription = '{
  "name": "mySensor",
  "url": "http://myservice.org/mySensor/description"
}';
WoT.createExposedThing(thingDescription)
  .then(function(thing) {
    // properties, actions and events are added based on the TD
    console.log("created " + thing.name });
    // now add the requests handlers
    thing.onRetrieveProperty(function(request) {
        console.log("Sending property '" + request.property + "' to " + request.from);
    }).onUpdateProperty(function(request) {
        console.log("Updating property '" + request.property + "' by " + request.from);
    }).onObserve(function(request) {
        console.log("Adding listener " + request.from);
        console.log("Observing " + request.type + " " + request.name +
            (request.subscribe? " recursively" : ""));
    }).start().then(function() {
       console.log("Thing started serving requests");
    });
  })
Example 8: Create a new exposed Thing from a Thing Description
let thingDescription = '{
  "name": "mySensor",
  "description": {
    "@context": [
      "http://w3c.github.io/wot/w3c-wot-td-context.jsonld",
      "http://w3c.github.io/wot/w3c-wot-common-context.jsonld",
    ],
    "@type": [ "Thing" ],
    "interaction": [
      // ...
    ]
    // ...
  }'
};
WoT.createExposedThing(thingDescription)
  .then(function(thing) {
    // properties, actions and events are added based on the TD
    // ...
  });

6. Security and Privacy

Editor's note

Please see the WoT Security and Privacy repository for work in progress regarding threat models, assets, risks, recommended mitigations, and best practices for security and privacy for systems using the Web of Things. Once complete, security and privacy considerations relevant to the Scripting API will be summarized in this section.

7. Terminology and conventions

The generic WoT terminology is defined in [WOT-ARCHITECTURE]: Thing, Thing Description (in short TD), Web of Things (in short WoT), WoT Interface, Protocol Bindings, WoT Runtime, Consuming a Thing Description, Thing Directory, Property, Action, Event etc.

Note

In this version of the specification, a WoT Runtime is assumed to run scripts that uses this API to define one or more Things that share a common event loop. Script deployment methods are out of scope of this version. In future versions, running multiple scripts (as modules) may be possible, and script deployment MAY be implemented using a manager Thing whose Actions permit script lifecycle management operations.

JSON-LD is defined in [JSON-LD] as a JSON document that is augmented with support for Linked Data by providing a @context property with a defining URI .

The terms URL and URL path are defined in [URL].

The following terms are defined in [HTML5] and are used in the context of browser implementations: browsing context, top-level browsing context, global object, incumbent settings object, Document, document base URL, Window, WindowProxy, origin, ASCII serialized origin, executing algorithms in parallel, queue a task, task source, iframe, valid MIME type.

A browsing context refers to the environment in which Document objects are presented to the user. A given browsing context has a single WindowProxy object, but it can have many Document objects, with their associated Window objects. The script execution context associated with the browsing context identifies the entity which invokes this API, which can be a web app, a web page, or an iframe.

The term secure context is defined in [WEBAPPSEC].

Error, EvalError, RangeError, ReferenceError, SyntaxError, TypeError, URIError , script execution context, Promise, JSON, JSON.stringify and JSON.parse are defined in [ECMASCRIPT].

DOMString, USVString, ArrayBuffer, BufferSource and any are defined in [WEBIDL].

The term event and the Event object are defined in DOM and Node.js.

Note

This specification uses the convention that an event listener will receive an Event object. This should work both in a browser environment and in a Node.js like environment.

Observables are proposed to be included in ECMAScript.

The algorithms utf-8 encode, and utf-8 decode are defined in [ENCODING].

IANA media types (formerly known as MIME types) are defined in RFC2046.

8. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, and SHOULD are to be interpreted as described in [RFC2119].

This document defines conformance criteria that apply to a single product: the UA (user agent) that implements the interfaces it contains.

This specification can be used for implementing the WoT Scripting API in multiple programming languages. The interface definitions are specified in [WEBIDL].

The user agent (UA) may be implemented in the browser, or in a separate runtime environment, such as Node.js or small embedded runtimes.

Implementations that use ECMAScript executed in a browser to implement the APIs defined in this document MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL].

Implementations that use TypeScript or ECMAScript in a runtime to implement the APIs defined in this document MUST implement them in a manner consistent with the TypeScript Bindings defined in the TypeScript specification [TYPESCRIPT].

This document serves a general description of the WoT Scripting API. Language and runtime specific issues are discussed in separate extensions of this document.

A. Changes

The following is a list of major changes to the document. For a complete list of changes, see the github change log. You can also view the recently closed bugs.

B. Open issues

The following problems are being discussed and need most attention:

C. Acknowledgements

Special thanks to former editor Johannes Hund for developing this specification. Also, the editors would like to thank Dave Raggett, Matthias Kovatsch, Michael Koster and Michael McCool for their comments and guidance.

D. References

D.1 Normative references

[ECMASCRIPT]
ECMAScript Language Specification. Ecma International. URL: https://tc39.github.io/ecma262/
[ENCODING]
Encoding Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://encoding.spec.whatwg.org/
[HTML5]
HTML5. Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. W3C. 28 October 2014. W3C Recommendation. URL: https://www.w3.org/TR/html5/
[JSON-LD]
JSON-LD 1.0. Manu Sporny; Gregg Kellogg; Markus Lanthaler. W3C. 16 January 2014. W3C Recommendation. URL: https://www.w3.org/TR/json-ld/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[TYPESCRIPT]
TypeScript Language Specification. Microsoft. 1 October 2012. URL: https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md
[URL]
URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/
[WEBAPPSEC]
Secure Contexts. W3C. 17 July 2015. URL: https://w3c.github.io/webappsec/specs/powerfulfeatures
[WEBIDL]
Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/
[WOT-ARCHITECTURE]
Web of Things Architecture. W3C. 20 August 2017. URL: https://w3c.github.io/wot-architecture/