MUA HỘ & SHIP TỪ MỸ VỀ VIỆT NAM

Abstract

The Web of Things is made of entities (Things) that can describe their capabilities in a machine-interpretable Thing Description (TD) and expose these capabilities through the WoT Interface, that is, network interactions modeled as Properties (for reading and writing values), Actions (to execute remote procedures with or without return values) and Events (for signaling notifications).

The main Web of Things (WoT) concepts are described in the Web of Things (WoT) Architecture 1.1 specification.

Scripting is an optional building block in WoT and it is typically used in gateways or browsers 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 such as TD Directory.

This specification describes an application programming interface (API) representing the WoT Interface that allows scripts to discover, operate Things and to expose locally defined Things characterized by WoT Interactions specified by a script.

The APIs defined in this document deliberately follow the Web of Things (WoT) Thing Description 1.1 specification closely. It is possible to implement more abstract APIs on top of them, or implementing directly the WoT network facing interface (i.e. the WoT Interface).

Editor's note

This specification is implemented at least by the Eclipse Thingweb project also known as node-wot, which is considered the reference open source implementation at the moment. Check its source code, including examples.

Defines the WoT API object as a singleton and contains the API methods, grouped by conformance classes.

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

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

Belongs to the WoT Consumer conformance class. Expects an td argument and returns a Promise that resolves with a ConsumedThing object that represents a client interface to operate with the Thing. The method MUST run the following steps:

Return a Promise promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
Let thing be a new ConsumedThing object constructed from td.
Set up the WoT Interactions based on introspecting td as explained in [WOT-TD] and [WOT-PROTOCOL-BINDINGS]. Make a request to the underlying platform to initialize the Protocol Bindings.

Editor's note

Implementations encapsulate the complexity of how to use the Protocol Bindings for implementing WoT interactions. In the future elements of that could be standardized.
Resolve promise with thing.

Editor's note

Note the difference between constructing ConsumedThing and using the consume() method: the latter also initializes the protocol bindings, whereas a simple constructed object will not have WoT Interactions initialized until they are invoked.

WebIDLtypedef object ExposedThingInit;  partial namespace WOT {   Promise<ExposedThing> produce(ExposedThingInit init); };

Belongs to the WoT Producer conformance class. Expects a init argument and returns a Promise that resolves with an ExposedThing object that extends ConsumedThing with a server interface, i.e. the ability to define request handlers. The init object is an instance of the ExposedThingInit type. Specifically, an ExposedThingInit value is a dictionary used for the initialization of an ExposedThing and it represents a Partial TD as described in the [WOT-ARCHITECTURE]. As such, it has the same structure of a Thing Description but it may omit some information. The method MUST run the following steps:

Return a Promise promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
Let thing be a new ExposedThing object constructed with init.
Resolve promise with thing.

To expand an ExposedThingInit given init and obtain a valid td as a result, run the following steps:

Run validate an ExposedThingInit on init. If that fails, throw SyntaxError and stop.
Let td be the result of running clone given init.
For each scheme in td.["securityDefinitions"], make a request to the underlying platform to check if it is supported by at least one Protocol Binding. If not, then remove scheme from td.
If td.["security"] does not exist in td.["securityDefinitions"], then remove security from td.
For each affordance in td.properties, td.actions and td.events, run the following sub-steps:
1. For each form in affordance.forms:
  1. If form.contentType is not recognized by the runtime as valid remove contentType from form.
  2. If form.href has an unknown schema, remove href from form.
  3. If form.href is absolute and its authority it is not recognized by the runtime as valid, remove href from form.
  4. If form.href is already in use by other ExposedThings, remove href from form.
Search for missing required properties in td accordingly to TD JSON Schema.

Editor's note

The editors find this step vague. It will be improved or removed in the next iteration.
For each missing property run these sub-steps:
1. If missing is title generate a runtime unique name and assign to title.
2. If missing is @context assign the latest supported Thing Description context URI.
3. If missing is instance assign the string 1.0.0.
4. If missing is forms generate a list of Forms using the available Protocol Bindings and content types encoders. Then assign the obtained list to forms.
5. If missing is security assign the label of the first supported SecurityScheme in securityDefinitions field. If no SecurityScheme is found generate a NoSecurityScheme called nosec and assign the string nosec to security.
  
  Issue 1
  
  The discussion about how to properly generate a value for security is still open. See issue #299
6. If missing is href define formStub as the partial Form that does not have href. Generate a valid url using the first Protocol Binding that satisfy the requirements of formStub. Assign url to href. If not Protocol Binding can be found remove formStub from td.
7. Add missing to td with value as value
Run validate a TD on td. If that fails re-throw the error and stop
Return td

To validate an ExposedThingInit given init, run the following steps:

Parse TD JSON Schema and load it in object called exposedThingInitSchema
let optional be a list containing the following strings: title, @context, instance, forms, security, and href.
For each property and sub-property key in exposedThingInitSchema equals to required execute the following steps:
1. if key value is an Array then remove all its elements equal to the elements in optional
2. if key value is a string then if value is equal to one of the elements in optional remove key from exposedThingInitSchema
Return the result of validating an object with JSON Schema given init and exposedThingInitSchema.

Editor's note

The validating an object with JSON Schema steps are still under discussion. Currently this specification reference to the validation process of JSONSchema. Please follow this document when validating init with exposedThingInitSchema. Notice that the working group is evaluating an alternative formal approach.

WebIDLpartial namespace WOT {   Promise<ThingDiscoveryProcess> discover(optional ThingFilter filter = {}); };

Belongs to the WoT Discovery conformance class. Starts the discovery process that will provide ThingDescription objects for Thing Descriptions that match an optional filter argument of type ThingFilter. The method MUST run the following steps:

Return a Promise promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
If discovery is not supported by the implementation, reject promise with NotSupportedError and stop.
Let discovery be a new ThingDiscoveryProcess object.
Set discovery.[[filter]] to filter.
Set discovery.[[url]] to undefined.
If filters in general are not supported by the implementation and filter is not undefined or null, reject promise with NotSupportedError and stop.
If discovery cannot be started by the underlying platform, reject promise with OperationError and stop.
Request the underlying platform to start the discovery process by any means supported and provisioned in the WoT Runtime for which the script has access to, passing discovery to it.
Resolve promise with discovery.

WebIDLpartial namespace WOT {   Promise<ThingDiscoveryProcess> exploreDirectory(USVString url,       optional ThingFilter filter = {}); };

Belongs to the WoT Discovery conformance class. Starts the discovery process that given a TD Directory URL, will provide ThingDescription objects for Thing Descriptions that match an optional filter argument of type ThingFilter. The method MUST run the following steps:

Return a Promise promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
If directory discovery is not supported by the implementation, reject promise with NotSupportedError and stop.
Let discovery be a new ThingDiscoveryProcess object.
Set discovery.[[url]] to url.
Set discovery.[[filter]] to filter.
Request the underlying platform to start the directory discovery process.

Note

This is a placeholder for more details in the discovery algorithm. Implementations should follow the procedures described in the [WOT-DISCOVERY] and [WOT-PROTOCOL-BINDINGS] specifications. Some normative steps are indicated below.
1. If url is not a TD Directory or if the underlying implementation cannot support the Protocol Binding indicated by url, reject promise with NotSupportedError and terminate these steps.
2. If filters in general are not supported by the implementation and filter is not undefined or null, reject promise with NotSupportedError and stop.
3. Run the discovery process given discovery.
  
  Note
  
  From this point on, errors are recorded only on error, but don't affect promise any longer.
Resolve promise with discovery.

WebIDLpartial namespace WOT {   Promise<ThingDescription> requestThingDescription(USVString url); };

Belongs to the WoT Discovery conformance class. Requests a Thing Description from the given URL. The method MUST run the following steps:

Return a Promise promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
If fetching a Thing Description is not supported by the implementation, reject promise with NotSupportedError and stop.
Let td be the result of making a request to the underlying platform to retrieve the Thing Description using the Protocol Binding specified by url. If retrieving td fails, reject promise with NotFoundError and stop.
Resolve promise with td.

As specified in the Web of Things (WoT) Thing Description 1.1 specification, WoT interactions extend DataSchema and include a number of possible Forms, out of which one is selected for the interaction. The Form contains a contentType to describe the data. For certain content types, a DataSchema is defined, based on JSON Schema, making possible to represent these contents as JavaScript types and eventually set range constraints on the data.

WebIDLtypedef 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]. The possible values MUST be of type 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.

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

WebIDL[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<DataSchemaValue> 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).

Parses the data returned by the WoT Interaction and returns a value with the type described by the interaction DataSchema if that exists, or by the contentType of the interaction Form. The method MUST run the following steps:

Return a Promise promise and execute the next steps in parallel.
If this.[[value]] is not undefined, resolve promise with that value and stop.
If this.data is not a ReadableStream or if dataUsed is true, or if form is not an object or if schema or its type are null or undefined, then reject promise with NotReadableError and stop.
If form.contentType is not application/json and if a mapping is not available in the Protocol Bindings from form.contentType to [JSON-SCHEMA], reject promise with NotSupportedError and stop.
Let reader be the result of getting a reader from data. If that threw an exception, reject promise with that exception and stop.
Let bytes be the result of reading all bytes from data with reader.
Set dataUsed to true.
If form.contentType is not application/json and if a mapping is available in the Protocol Bindings from form.contentType to [JSON-SCHEMA], transform bytes with that mapping.
Let json be the result of running parse JSON from bytes on bytes. If that throws, reject promise with that exception and stop.
Set [[value]] to the result of running check data schema on json and schema. If that throws, reject promise with that exception and stop.
Resolve promise with [[value]].

When invoked, MUST run the following steps:

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

To run the check data schema steps on payload and schema,

Let type be schema.type.
If type is "null" and if payload is not null, throw TypeError and stop, otherwise return null.
If type is "boolean" and payload is a falsy value or its byte length is 0, return false, otherwise return true.
If type is "integer" or "number",
1. If payload is not a number, throw TypeError and stop.
2. If form.minimum is defined and payload is smaller, or if form.maximum is defined and payload is bigger, throw a RangeError and stop.
If type is "string", return payload.
If type is "array", run these sub-steps:
1. If payload is not an array, throw TypeError and stop.
2. If form.minItems is defined and payload.length is less than that, or if form.maxItems is defined and payload.length is more than that, throw RangeError and stop.
3. Let payload be an array of items obtained by running the check data schema steps on each element item of payload and schema.items. If this throws at any stage, re-throw that exception and stop.
If type is "object", run these sub-steps:
1. If payload or schema.properties is not an object, throw TypeError and stop.
2. For each key in payload:
  1. Let prop be payload[key].
  2. Let propSchema be interaction.properties[key].
  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 stop.
3. Let required be schema.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 stop.
Return payload.

For a given ConsumedThing object thing, in order to create interaction request given a source, form and schema, run these steps:

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

For a given ConsumedThing object thing, in order to parse interaction response given response, form and schema, run these steps:

Let result be a new InteractionOutput object.
Let result.schema be schema.
Let result.form be form.
Let result.data be a new ReadableStream with the payload data of response as its underlying source.
Let result.dataUsed be false.
Return result.

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.

Reading data — Figure 1 Data structures used when reading data

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.

Writing data — Figure 2 Data structures used when writing data

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.

Invoking action — Figure 3 Data structures used when invoking an Action

When a ConsumedThing invokes an Action, 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.

The algorithms in this API define the errors to be reported to application scripts.

The errors reported to the other communication end are mapped and encapsulated by the Protocol Bindings.

Figure 4 Error handling in WoT interactions

Editor's note

This topic is still being discussed in Issue #200. A standardized error mapping would be needed in order to ensure consistency in mapping script errors to protocol errors and vice versa. In particular, when algorithms say "error received from the Protocol Bindings", that will be factored out as an explicit error mapping algorithm. Currently, that is encapsulated by implementations.

Represents a client API to operate a Thing. Belongs to the WoT Consumer conformance class.

WebIDL[SecureContext, Exposed=(Window,Worker)] interface ConsumedThing {   constructor(ThingDescription td);   Promise<InteractionOutput> readProperty(DOMString propertyName,                               optional InteractionOptions options = {});   Promise<PropertyReadMap> readAllProperties(                               optional InteractionOptions options = {});   Promise<PropertyReadMap> readMultipleProperties(                               sequence<DOMString> propertyNames,                               optional InteractionOptions options = {});   Promise<undefined> writeProperty(DOMString propertyName,                               InteractionInput value,                               optional InteractionOptions options = {});   Promise<undefined> writeMultipleProperties(                               PropertyWriteMap valueMap,                               optional InteractionOptions options = {});   /*Promise<undefined> writeAllProperties(                               PropertyWriteMap valueMap,                               optional InteractionOptions options = {});*/   Promise<InteractionOutput> invokeAction(DOMString actionName,                               optional InteractionInput params = {},                               optional InteractionOptions options = {});   Promise<Subscription> observeProperty(DOMString name,                               InteractionListener listener,                               optional ErrorListener onerror,                               optional InteractionOptions options = {});   Promise<Subscription> subscribeEvent(DOMString name,                               InteractionListener listener,                               optional ErrorListener onerror,                               optional InteractionOptions options = {});   ThingDescription getThingDescription(); };  dictionary InteractionOptions {   unsigned long formIndex;   object uriVariables;   any data; };  [SecureContext, Exposed=(Window,Worker)] interface Subscription {   readonly attribute boolean active;   Promise<undefined> stop(optional InteractionOptions options = {}); };  [SecureContext, Exposed=(Window,Worker)] interface PropertyReadMap {   readonly maplike<DOMString, InteractionOutput>; };  [SecureContext, Exposed=(Window,Worker)] interface PropertyWriteMap {   readonly maplike<DOMString, InteractionInput>; };  callback InteractionListener = undefined(InteractionOutput data); callback ErrorListener = undefined(Error error);

Editor's note: Where is the writeAllProperties method?

The writeAllProperties() method is still under discussion. Meanwhile, use the writeMultipleProperties() method instead.

A ConsumedThing object has the following internal slots:

Internal Slot	Initial value	Description (non-normative)
[[td]]	`null`	The Thing Description of the `ConsumedThing`.
[[activeSubscriptions]]	`{}`	An ordered map keyed on a string name representing the Event and value is a `Subscription` object.
[[activeObservations]]	`{}`	An ordered map keyed on a string name representing a Property and value is a `Subscription` object.

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

To create ConsumedThing with the ThingDescription td, run the following steps:

Run the validate a TD steps on td. If that fails, throw SyntaxError and stop.
Run the expand a TD steps on td. If that fails, re-throw the error and stop.
Let thing be a new ConsumedThing object.
Set the internal slot [[td]] of thing to td.
Return thing.

Returns the [[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.

Reads a Property value. Takes as arguments propertyName and optionally options. It returns a Promise that resolves with a Property value represented as an InteractionOutput object or rejects on error. The method MUST run the following steps:

Return a Promise promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
Let interaction be [[td]].properties.propertyName.
If interaction is undefined, reject promise with a NotFoundError and stop.
If option.formIndex is defined, let form be the Form associated with formIndex in interaction.forms array, otherwise let form be a Form in interaction.forms whose op is readproperty, selected by the implementation.
If form is failure, reject promise with a SyntaxError and stop.
Make a request to the underlying platform (via the Protocol Bindings) to retrieve the value of the propertyName Property using form and the optional URI templates given in options.uriVariables.
If the request fails, reject promise with the error received from the Protocol Bindings and stop.
Let response be the response received to the request.
Let data be the result of running parse interaction response on response, form and interaction. If that fails, reject promise with a SyntaxError and stop.
Resolve promise with data.

Reads multiple Property values with one request. Takes as arguments propertyNames and optionally options. It returns a Promise that resolves with a PropertyReadMap object that maps keys from propertyNames to values returned by this algorithm. The method MUST run the following steps:

Return a Promise promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
If option.formIndex is defined, let form be the Form associated with formIndex in the [[td]].forms array, otherwise let form be the Form in [[td]].forms array whose op is readmultipleproperties, as selected by the implementation.
If form is failure, reject promise with a SyntaxError and stop.
Let result be an object and for each string name in propertyNames add a property with key name and the value null.
Make a request to the underlying platform (via the Protocol Bindings) to retrieve the Property values given by propertyNames with form and optional URI templates given in options' uriVariables.
If this cannot be done with a single request with the Protocol Bindings, reject promise with a NotSupportedError and stop.
Process the response and for each key in result, run the following sub-steps:
1. Let value be result[key].
2. Let schema be this.[[td]].properties[key].
3. Let property be the result of running parse interaction response on value, form and schema.
If the above step throws at any point, reject promise with that exception and stop.
Resolve promise with result.

Reads all properties of the Thing with one request. Takes options as optional argument. It returns a Promise that resolves with a PropertyReadMap object that maps keys from Property names to values returned by this algorithm. The method MUST run the following steps:

Return a Promise promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
Let forms be subscription.[[interaction]].forms.
If forms is undefined, reject promise with a SyntaxError and stop.
If option.formIndex is not undefined and is less than forms.length, set subscription.[[form]] to forms.[formIndex].
Otherwise, set subscription.[[form]] to a Form in forms whose op is "readallproperties", as selected by the implementation.
If subscription.[[form]] is failure, reject promise with a SyntaxError and stop.
Make a request to the underlying platform using the Protocol Bindings to retrieve all the Property definitions from the TD given form and optional URI templates in options.uriVariables.
If this cannot be done with a single request with the Protocol Bindings of the Thing, then reject promise with a NotSupportedError and stop.
If the request fails, reject promise with the error received from the Protocol Bindings and stop.
Process the reply and let result be an object with the keys and values obtained in the reply.
Process the response and for each key in result, run the following sub-steps:
1. Let value be result[key].
2. Let schema be this.[[td]].properties[key].
3. Let property be the result of running parse interaction response on value, form and schema.
Resolve promise with result.

Writes a single Property. Takes as arguments propertyName, value and optionally options. It returns a Promise that resolves on success and rejects on failure. The method MUST run the following steps:

Return a Promise promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
Let interaction be this.[[td]].properties[propertyName].
If interaction is undefined, reject promise with a NotFoundError and stop.
If option.formIndex is not undefined, let form be the Form associated with formIndex in the interaction.forms array, otherwise let form be a Form in interaction.forms whose op is writeproperty, as selected by the implementation.
If form is failure, reject promise with a SyntaxError and stop.
Let data be the result of running the create interaction request steps given value, form and interaction. If that throws, reject promise with that exception and stop.
Make a request to the underlying platform (via the Protocol Bindings) to write the Property given by propertyName using data and the optional URI templates given in options' uriVariables.
If the request fails, reject promise with the error received from the Protocol Bindings and stop.
Otherwise resolve promise.

Editor's note

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.

Writes a multiple Property values with one request. Takes as arguments properties - as an object with keys being Property names and values as Property values - and optionally options. It returns a Promise that resolves on success and rejects on failure. The method MUST run the following steps:

Return a Promise promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
If option.formIndex is defined, let form be the Form associated with formIndex in the [[td]].forms array, otherwise let form be a Form in [[td]].forms array whose op is writemultipleproperties, as selected by the implementation.
If form is failure, reject promise with a SyntaxError and stop.
Let propertyNames be an array of string with as elements the keys of the properties object.
For each name in propertyNames, let property be this.[[td]].properties[name].
If property is null or undefined or is not writeable reject promise with NotSupportedError and stop.
Let result be an object and for each string name in propertyNames add a property with key name and let its value be null.
Let schemas be an object and for each name in propertyNames add a property with key name and let its value be this.[[td]].properties[name].
For each key key in properties, run the create interaction request steps given properties[key], form and the value for schema[key]. If that throws for any name, reject promise with that exception and stop.
Make a single request to the underlying platform (via the Protocol Bindings) to write each Property provided in properties with optional URI templates given in options' uriVariables.
If this cannot be done with a single request with the Protocol Bindings of the Thing, then reject promise with a NotSupportedError and stop.
If the request fails, return the error received from the Protocol Bindings and stop.
Otherwise resolve promise.

Makes a request for Property value change notifications. Takes as arguments propertyName, listener and optionally onerror and options. It returns a Promise that resolves on success and rejects on failure.

Editor's note

This algorithm allows for only one active Subscription per Property. If a new Subscription is made while an existing Subscription is active the runtime will throw an NotAllowedError.

The method MUST run the following steps:

Let thing be the reference of this ConsumedThing object.
Return a Promise promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
If listener is not a Function, reject promise with a TypeError and stop.
If onerror is not null and is not a Function, reject promise with a TypeError and stop.
If thing.[[activeObservations]][propertyName] [=map/exists], reject promise with a NotAllowedError and stop.
Let subscription be a new Subscription object with its internal slots set as follows:
- Let subscription.[[type]] be "property".
- Let subscription.[[name]] be propertyName.
- Let subscription.[[interaction]] be [[td]].properties[propertyName].
- Let subscription.[[thing]] be thing.
- Let forms be subscription.[[interaction]].forms.
- If forms is undefined, reject promise with a SyntaxError and stop.
- If option.formIndex is not undefined and is less than forms.length, set subscription.[[form]] to forms.[formIndex].
- Otherwise, set subscription.[[form]] to a Form in forms whose op is "observeproperty", as selected by the implementation.
- If subscription.[[form]] is failure, reject promise with a SyntaxError and stop.
- If subscription.[[interaction]] is undefined, reject promise with a NotFoundError and stop.
Make a request to the underlying platform to observe the Property identified by propertyName with form and optional URI templates given in options' uriVariables.
If the request fails, reject promise with the error received from the Protocol Bindings and stop.
Set thing.[[activeObservations]][|propertyName] to subscription and resolve promise.
Whenever the underlying platform detects a notification for this subscription keyed on propertyName with a new Property value value, run the following sub-steps:
- Let reply be the result of running parse interaction response with value, subscription.[[form]] and subscription.[[interaction]]. If that throws, reject promise with that exception and stop.
- Invoke listener given reply.
Whenever the underlying platform detects an error for this subscription, run the following sub-steps:
- If the error is irrecoverable and stops the subscription, set subscription.active to false and suppress further notifications.
- Let error be a new NetworkError and set its message to reflect the underlying error condition.
- If onerror is a Function, invoke it given error.

Makes a request for invoking an Action and return the result. Takes as arguments actionName, optionally params and optionally options. It returns a Promise that resolves with the result of the Action represented as an InteractionOutput object, or rejects with an error. The method MUST run the following steps:

Return a Promise promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
Let interaction be this.[[td]].actions[actionName].
If interaction is not an object, reject promise with a NotFoundError and stop.
Let forms be subscription.[[interaction]].forms.
If forms is undefined, reject promise with a SyntaxError and stop.
If option.formIndex is not undefined and is less than forms.length, set subscription.[[form]] to forms.[formIndex].
Otherwise, set subscription.[[form]] to a Form in forms whose op is "invokeaction", as selected by the implementation.
If subscription.[[form]] is failure, reject promise with a SyntaxError and stop.
Let args be the result of running the create interaction request steps on params, form and interaction. If that throws, reject promise with that exception and stop.
Make a request to the underlying platform (via the Protocol Bindings) to invoke the Action identified by actionName given args and options.uriVariables.
If the request fails locally or returns an error over the network, reject promise with the error received from the Protocol Bindings and stop.
Let value be the reply returned in the reply.
Let result be the result of running parse interaction response with value, form and interaction. If that throws, reject promise with that exception and stop.
Resolve promise with result.

Makes a request for subscribing to Event notifications. Takes as arguments eventName, listener and optionally onerror and options. It returns a Promise to signal success or failure.

Editor's note

This algorithm allows for only one active Subscription per Event. If a new Subscription is made while an existing Subscription is active the runtime will throw an NotAllowedError.

The method MUST run the following steps:

Let thing be the reference of this ConsumedThing object.
Return a Promise promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
If listener is not a Function, reject promise with a TypeError and stop.
If onerror is not null and is not a Function, reject promise with a TypeError and stop.
If thing.[[activeSubscriptions]][eventName] does not exist, reject promise with a NotAllowedError and stop.
Let subscription be a new Subscription object with its internal slots set as follows:
- Let subscription.[[type]] be "event".
- Let subscription.[[name]] be eventName.
- Let subscription.[[interaction]] be thing. [[td]].events[eventName].
- If subscription.[[interaction]] is undefined, reject promise with a NotFoundError and stop.
- Let subscription.[[thing]] be thing.
- If options.formIndex exists, then let subscription.[[form]] be thing.[[interaction]].forms[formIndex].
- Otherwise, let subscription.[[form]] be an implementation-defined Form from the subscription.[[interaction]].forms array whose op is "subscribeevent".
- If subscription.[[form]] does not exist, reject promise with a SyntaxError and stop.
Make a request to the underlying platform via the Protocol Bindings to subscribe to the Event identified by eventName with [[form]], optional URI templates given in options.uriVariables and optional subscription data given in options.data.
If the request fails, reject promise with the error received from the Protocol Bindings and stop.
Set eventName to thing.[[activeSubscriptions]][eventName] to subscription.
Resolve promise.
Whenever the underlying platform detects a notification for the Event subscription keyed on eventName, run the following sub-steps:
1. Invoke listener given the result of running parse interaction response on the data provided with the Event, subscription.[[form]] and subscription.[[interaction]].
Whenever the underlying platform detects an error for Event subscription keyed on eventName, run the following sub-steps:
- If the error is irrecoverable and stops the subscription, set subscription.active to false and suppress further notifications.
- Let error be a new NetworkError and set its message to reflect the underlying error condition.
- If onerror is a Function, invoke it given error.

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

Editor's note

The support for URI variables comes from the need, exposed by the Web of Things (WoT) Thing Description 1.1 specification, to be able to describe existing RESTful endpoints that use them. However, it should be possible to write a Thing Description that would use Actions for representing this kind of interactions and model the URI variables as action parameters. In that case, implementations can serialize the parameters as URI variables, and therefore, the options parameter could be dismissed.

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

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

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

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.

User provided callback that is given an argument of type Error and is used for conveying critical and non-critical errors from the Protocol Bindings to applications.

Represents a subscription to Property change and Event interactions.

The active boolean property denotes if the subscription is active, i.e. it is not stopped because of an error or because of invocation of the stop() method.

A Subscription object has the following internal slots:

Internal Slot	Initial value	Description (non-normative)
[[type]]	`null`	Indicates what WoT Interaction the `Subscription` refers to. The value can be either `"property"` or `"event"` or `null`.
[[name]]	`null`	The Property or Event name.
[[interaction]]	`null`	The Thing Description fragment that describes the WoT interaction.
[[form]]	`null`	The Form associated with the subscription.
[[thing]]	`null`	The `ConsumedThing` associated with the subscription.

Stops delivering notifications for the subscription. It takes an optional parameter options and returns a Promise. When invoked, the method MUST execute the following steps:

Return a Promise promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
If options' formIndex is defined, let unsubscribeForm be the Form associated with formIndex in [[interaction]]'s forms array.
Otherwise let unsubscribeForm be the result of running the find a matching unsubscribe form algorithm given [[form]].
If unsubscribeForm is failure, reject promise with a SyntaxError and stop.
If [[type]] is "property", make a request to the underlying platform via the Protocol Bindings to stop observing the Property identified by [[name]] with unsubscribeForm and optional URI templates given in options' uriVariables.
Otherwise, if [[type]] is "event", make a request to the underlying platform via the Protocol Bindings to unsubscribe from the Event identified by [[name]] with unsubscribeForm, with optional URI templates given in options' uriVariables and optional unsubscribe data given in options.data.
If the request fails, reject promise with the error received from the Protocol Bindings and stop.
Otherwise:
- set active to false.
- if [[type]] is "event", remove [[name]] from [[thing]].[[activeSubscriptions]] .
- if [[type]] is "property", remove [[name]] from [[thing]].[[activeObservations]] .
- Resolve promise.
If the underlying platform receives further notifications for this subscription, implementations SHOULD silently suppress them.

Note

This algorithm is under development and is non-normative. Implementations MAY choose another algorithm to find a matching unsubscribe Form to a given subscribe Form.

To find a matching unsubscribe form given subscribeForm in the context of a Subscription object, run the following steps:

Let results be an empty array.
For each form in [[interaction]].forms,
1. Add an internal slot [[matchLevel]] on form and set its value to 0.
2. If form.op is "unobserveproperty" if [[type]] is "property" or if form.op is "unsubscribeevent" if [[type]] is"event",
  1. Set the internal slot [[matchLevel]] on form to 1 and add form to results.
  2. If form.href and [[subscribeForm]].href are same origin-domain, increment form.[[matchLevel]].
  3. If form.contentType is equal to [[subscribeForm]]'s contentType and form.[[matchLevel]] is greater than 2, increment form.[[matchLevel]].
If results is empty, return null and terminate these steps.
Return the first form in results that has the highest [[matchLevel]] value.

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.

Example 2: Thing Client API example with data value

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", async (data) => {     try {       console.log("Temperature changed to: " + await data.value());     } catch (error) {       console.error("Cannot read the observed property temperature");       console.error(error);     }   });   // subscribe to the “ready” event defined in the TD   await thing.subscribeEvent("ready", async (eventData) => {     try {       console.log("Ready; index: " + await eventData.value());       // run the “startMeasurement” action defined by TD       await thing.invokeAction("startMeasurement", { units: "Celsius" });       console.log("Measurement started.");     } catch (error) {       console.error("Cannot read the ready event or startMeasurement failed");       console.error(error)     }   }); } catch (e) {   console.log("Error starting measurement."); }  setTimeout(async () => {   try {     const temperatureData = await thing.readProperty("temperature")     const temperature = await temperatureData.value();     console.log("Temperature: " + temperature);      await thing.unsubscribe("ready");     console.log("Unsubscribed from the ‘ready’ event.");   } catch (error) {     console.log("Error in the cleanup function");   } }, 10000);

The following shows an advance usage of InteractionOutput to read a property without a DataSchema.

Example 3: Thing Client API example with arrayBuffer

/* * takePicture affordance form: * "form": { *   "op": "invokeaction", *   "href" : "http://camera.example.com:5683/takePicture", *   "response": { *     "contentType": "image/jpeg", *     "contentCoding": "gzip" *   } *} * See https://www.w3.org/TR/wot-thing-description/#example-23 */ let response; let image; try {   response = await thing.invokeAction(“takePicture”));   image = await response.value() // throws NotReadableError --> schema not defined } catch(ex) {   image = await response.arrayBuffer();   // image: ArrayBuffer [0x1 0x2 0x3 0x5 0x15 0x23 ...] }

Finally, the next two examples shows the usage of a ReadableStream from an InteractionOutput.

Example 4: Thing Client API example with readable stream (e.g., video stream)

/*{ "video": {   "description" : "the video stream of this camera",   "forms": [     {       "op": "readproperty",       "href": "http://camera.example.com/live",       "subprotocol": "hls"       "contentType": "video/mp4"     }   ] }}*/  const video = await thing.readProperty("video") const reader = video.data.getReader() reader.read().then(function processVideo({ done, value }) {   if (done) {     console.log("live video stoped");     return;   }   const decoded = decode(value)   UI.show(decoded)   // Read some more, and call this function again   return reader.read().then(processText); });

Here consider that the JSON object is too big to be read wholly in the memory. Therefore, we use streaming processing to get the total number of the events recorded by the remote Web Thing.

Example 5: Thing Client API example with readable stream (e.g., counting json objects)

/* * "eventHistory": * { *   "description" : "A long list of the events recorded by this thing", *   "type": "array", *   "forms": [ *     { *       "op": "readproperty", *       "href": "http://recorder.example.com/eventHistory", *     } *   ] * } */  // Example of streaming processing: counting json objects let objectCounter = 0 const parser = new Parser() //User library for json streaming parsing (i.e. https://github.com/uhop/stream-json/wiki/Parser)  parser.on('data', data => data.name === 'startObject' && ++objectCounter); parser.on('end', () => console.log(`Found ${objectCounter} objects.`));  const response = await thing.readProperty(“eventHistory”) await response.data.pipeTo(parser);  // Found N objects

The ExposedThing interface is the server API to operate the Thing that allows defining request handlers, Property, Action, and Event interactions.

WebIDL[SecureContext, Exposed=(Window,Worker)] interface ExposedThing {   ExposedThing setPropertyReadHandler(DOMString name,           PropertyReadHandler handler);   ExposedThing setPropertyWriteHandler(DOMString name,           PropertyWriteHandler handler);   ExposedThing setPropertyObserveHandler(DOMString name,           PropertyReadHandler handler);   ExposedThing setPropertyUnobserveHandler(DOMString name,           PropertyReadHandler handler);   Promise<undefined> emitPropertyChange(DOMString name,           optional InteractionInput data);    ExposedThing setActionHandler(DOMString name, ActionHandler action);    ExposedThing setEventSubscribeHandler(DOMString name,           EventSubscriptionHandler handler);   ExposedThing setEventUnsubscribeHandler(DOMString name,           EventSubscriptionHandler handler);   Promise<undefined> emitEvent(DOMString name,           optional InteractionInput data);    Promise<undefined> expose();   Promise<undefined> destroy();    ThingDescription getThingDescription(); };  callback PropertyReadHandler = Promise<InteractionInput>(         optional InteractionOptions options = {});  callback PropertyWriteHandler = Promise<undefined>(         InteractionOutput value,         optional InteractionOptions options = {});  callback ActionHandler = Promise<InteractionInput>(         InteractionOutput params,         optional InteractionOptions options = {});  callback EventSubscriptionHandler = Promise<undefined>(         optional InteractionOptions options = {});

An ExposedThing object has the following internal slots:

Internal Slot	Initial value	Description (non-normative)
[[td]]	`null`	The Thing Description of the `ExposedThing`.
[[readHandlers]]	`{}`	A `Map` with property names as keys and `PropertyReadHandler`s as values
[[writeHandlers]]	`{}`	A `Map` with property names as keys and `PropertyWriteHandler`s as values
[[observeHandlers]]	`{}`	A `Map` with property names as keys and `PropertyReadHandler`s as values
[[unobserveHandlers]]	`{}`	A `Map` with property names as keys and `Function`s as values
[[actionHandlers]]	`{}`	A `Map` with action names as keys and `ActionHandler`s as values
[[subscribeHandlers]]	`{}`	A `Map` with event names as keys and `EventSubscriptionHandler`s as values
[[unsubscribeHandlers]]	`{}`	A `Map` with event names as keys and `EventSubscriptionHandler`s as values
[[propertyObservers]]	`{}`	A `Map` with property names as keys and an `Array` of listeners as values
[[eventListeners]]	`{}`	A `Map` with event names as keys and `Array` of listeners as values

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

Note

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.

Note

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.

To construct an ExposedThing with the ExposedThingInit init, run the following steps:

If invoking this method is not allowed for the current scripting context for security reasons, throw a SecurityError and stop.
Run the expand an ExposedThingInit steps on init. if that fails re-throw the error and stop. Otherwise store the obtained td
Run the expand a TD steps on td. If that fails, re-throw the error and stop.
Let thing be a new ExposedThing object.
Set the [[td]] of thing to td.
Return thing.

Returns the [[td]] of the ExposedThing object that represents the Thing Description of the Thing. Applications may consult the Thing metadata stored in [[td]] in order to introspect its capabilities before interacting with it.

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.

Takes as arguments name and handler. 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.

Editor's note

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.

When the method is invoked given name and handler, implementations MUST run the following steps:

If invoking this method is not allowed for the current scripting context for security reasons, throw a SecurityError and stop.
If [[td]].properties[name] does not exist, throw NotFoundError and stop.
Set this.[[readHandlers]][name] to handler.

When a network request for reading Property name is received by the implementation with options, run the following steps:

If this operation is not supported, send back a NotSupportedError according to the Protocol Bindings and stop.
If this operation is not allowed, send back a NotAllowedError according to the Protocol Bindings and stop.
Let value be the result of running the read server property steps with name and options:
1. Let interaction be [[td]].properties.name.
2. If a Property with name does not exist, throw NotFoundError and stop.
3. Let handler be null.
4. If there is a user provided PropertyReadHandler in [[readHandlers]] internal slot for interaction, let handler be that.
5. Otherwise, if there is a default read handler provided by the implementation, let handler be that.
6. If handler is null, throw NotSupportedError and stop.
7. Let value be the result of invoking handler given options. If that fails, throw the error and stop.
8. Return value.
  
  Note
  
  The value returned here SHOULD either conform to DataSchema or it SHOULD be an ReadableStream object created by the handler.
If the previous step has thrown an error, send the error back with the reply created by following the Protocol Bindings and stop.
Serialize and add the returned value to the reply created by following the Protocol Bindings.

When a network request for reading multiple Properties given in an object propertyNames is received with options, run the following read multiple properties steps on propertyNames and options:

If this operation is not supported, send back a NotSupportedError according to the Protocol Bindings and stop.
If this operation is not allowed, send back a NotAllowedError according to the Protocol Bindings and stop.
For each property with key name defined in propertyNames,
1. Let value be the result of running the read server property steps on name and options. If that throws, send back the error in the reply created by following the Protocol Bindings and stop.
2. Set propertyNames.name to value.
Reply to the request by sending a single reply created from propertyNames according to the Protocol Bindings.

When a network request for reading all Properties is received with options, run the following steps:

If this operation is not supported, send back a NotSupportedError according to the Protocol Bindings and stop.
If this operation is not allowed, send back a NotAllowedError according to the Protocol Bindings and stop.
Let properties be an object created with all properties defined in the Thing with values set to null.
Run the read multiple properties steps on properties and options.

Takes as arguments name and handler. 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.

When the method is invoked given name and handler, implementations MUST run the following steps:

If invoking this method is not allowed for the current scripting context for security reasons, throw a SecurityError and stop.
If this.[[td]].properties[name] does not exist, throw NotFoundError and stop.
Set this[[observeHandlers]][name] to handler.

When a network request for observing a Property name is received by the implementation with options, run the following steps:

If this operation is not supported, send back a NotSupportedError according to the Protocol Bindings and stop.
If this operation is not allowed, send back a NotAllowedError according to the Protocol Bindings and stop.
If this.[[td]].properties[name] does not exist, send back a NotFoundError in the reply and stop.
Internally save the request sender information together with options and this.[[propertyObservers]][name], in order to be able to notify about Property value changes.

Note

Every time the value of property changes, emitPropertyChange() needs to be explicitly called by the application script.

Takes as arguments name and handler. 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.

When the method is invoked given name and handler, implementations MUST run the following steps:

If invoking this method is not allowed for the current scripting context for security reasons, throw a SecurityError and stop.
If this.[[td]].properties[name] does not exist, throw NotFoundError and stop.
Set this.[[unobserveHandlers]][name] to handler.

When a network request for unobserving a Property name with options is received by the implementation, run the following steps:

If this operation is not supported, send back a NotSupportedError according to the Protocol Bindings and stop.
If this operation is not allowed, send back a NotAllowedError according to the Protocol Bindings and stop.
If this.[[td]].properties[name] does not exist, send back a NotFoundError in the reply and stop.
Let handler be this.[[unobserveHandlers]][name];
If handler is a Function, invoke that given options, then send back a reply following the Protocol Bindings and stop.
Otherwise, if this.[[propertyObservers]][name] exists, remove it from this.[[propertyObservers]], send back a reply as defined in the Protocol Bindings and stop.
Otherwise, send back a NotFoundError in the reply as defined in the Protocol Bindings and stop.

Takes the name argument, denoting a Property name, and optionally the data argument. Triggers emitting a notification to all observers of the specified Property with the data provided by the data argument, or if not provided, it is obtained by the observe handler or the by read handler associated with that Property. The method MUST run the following steps:

Let promise be a new Promise.
Return promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
Let name be the first argument.
Let property be this.[[td]].properties[name].
If property is undefined, reject promise with NotFoundError and stop.
Let data be the second argument.
If data is undefined, run the following sub-steps:
1. Let handler be null.
2. If name does not exist in [[readHandlers]], reject promise and stop.
3. Let handler be [[readHandlers]][name].
4. If handler is null or undefined, reject promise and stop.
5. Let handled be the result of invoking handler given null.
6. If handled is rejected, then reject promise and stop.
7. Otherwise if handled resolved with value, let data be value.
For each observer in [[propertyObservers]][name], run the following sub-steps:
1. Let options be the interaction options saved with observer.
2. Request the underlying platform to create a reply from data and options according to the Protocol Bindings.
  
  Editor's note
  
  This clause needs expanding and/or refer to an algorithm in [WOT-PROTOCOL-BINDINGS].
3. Send reply to observer.
Resolve promise.

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

Editor's note

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.

Note

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.

Takes as arguments name and handler. 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

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 observable, based on the Thing Description.

When the method is invoked given name and handler, implementations MUST run the following steps:

If invoking this method is not allowed for the current scripting context for security reasons, throw a SecurityError and stop.
If this.[[td]].properties[name] does not exist, throw NotFoundError and stop.
Set this.[[writeHandlers]][name] to handler.

When a network request for writing a Property name with a new value value and options is received, implementations MUST run the following update property steps, given name, value, options and mode set to "single":

If this operation is not supported, send back a NotSupportedError according to the Protocol Bindings and stop.
If this operation is not allowed, send back a NotAllowedError according to the Protocol Bindings and stop.
Let interaction be this.[[td]].properties[name].
If interaction is undefined, return a NotFoundError in the reply and stop.
Let handler be this.[[writeHandlers]][name].
If handler is undefined and if there is a default write handler provided by the implementation, let handler be that.
If handler is undefined, send back a NotSupportedError with the reply and stop.
Let promise be the result of invoking handler given name and options. If it fails, return the error in the reply and stop.
If mode is "single", reply to the request reporting success, following the Protocol Bindings and stop.

When a network request for writing multiple Properties given in an object propertyNames is received with options, run the following steps:

If this operation is not supported, send back a NotSupportedError according to the Protocol Bindings and stop.
If this operation is not allowed, send back a NotAllowedError according to the Protocol Bindings and stop.
For each property with key name and value value defined in propertyNames, run the update property steps with name, value, options and mode set to "multiple". If that fails, reply to the request with that error and stop.
Reply to the request by sending a single reply according to the Protocol Bindings.

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 given params and optionally with an options object. It returns a Promise that rejects with an error or resolves with the value returned by the Action as InteractionInput.

Note

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

Takes as arguments name and action. 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.

When the method is invoked given name and action, run the following steps:

If invoking this method is not allowed for the current scripting context for security reasons, throw a SecurityError and stop.
Let interaction be this.[[td]].actions[name].
If interaction is undefined, throw a NotFoundError and stop.
Set this.[[actionHandlers]][name] to action.

When a network request for invoking the Action identified by name is received given inputs and optionally options, run the following steps:

If this operation is not supported, send back a NotSupportedError according to the Protocol Bindings and stop.
If this operation is not allowed, send back a NotAllowedError according to the Protocol Bindings and stop.
Let interaction be this.[[td]].properties[name].
If interaction is undefined, return a NotFoundError in the reply and stop.
Let handler be this.[[actionHandlers]][name].
If handler is undefined, return a NotSupportedError with the reply created by following the Protocol Bindings and stop.
Let promise be the result of invoking handler given name, inputs and options.
If promise rejects, send the error with the reply and stop.
When promise resolves with data, use data to create and send the reply according to the Protocol Bindings.

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 given an options 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.

Takes as arguments name and handler. 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.

When the method is invoked given name and handler, run the following steps:

If invoking this method is not allowed for the current scripting context for security reasons, throw a SecurityError and stop.
Let interaction be this.[[td]].events[name].
If interaction is undefined, throw a NotFoundError and stop.
Set this.[[subscribeHandlers]][name] to handler.
Return this.

Takes as arguments name and handler. 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.

When the method is invoked given name and handler, run the following steps:

If invoking this method is not allowed for the current scripting context for security reasons, throw a SecurityError and stop.
Let interaction be this.[[td]].events[name].
If interaction is undefined, throw a NotFoundError and stop.
Set this.[[unsubscribeHandlers]][name] to handler.
Return this.

When an Event unsubscribe request for name is received by the underlying platform optionally with options, run the following steps:

If this operation is not supported, send back a NotSupportedError according to the Protocol Bindings and stop.
If this operation is not allowed, send back a NotAllowedError according to the Protocol Bindings and stop.
Let interaction be this.[[td]].events[name].
If interaction is undefined, send back a NotFoundError and stop.
If this.[[unsubscribeHandlers]][name] exists and is a Function, invoke it given options and stop.
Otherwise name [=map/exists] in this.[[eventListeners]], remove name.
Return this.

When an Event with name name is emitted with data by the emitEvent() method, run the following steps:

Let listeners be [[eventListeners]].name.
For each subscriber in listeners, run the following sub-steps:
1. Create an Event notification response according to the Protocol Bindings from data and subscriber, including its options.
2. If data is undefined, assume that the notification response will contain an empty data payload as specified by Protocol Bindings.
3. If the underlying protocol stack permits conveying event errors and if an error condition has been detected by the UA, create response as an error notification according to the Protocol Bindings, using data, subscriber and its options.
  
  Note
  
  The error reporting is protocol specific and it is encapsulated by implementations. On the client end, the error listener passed with the subscription will be invoked if the client UA detects the error.
4. Send response to the subscriber identified by subscriber.

Takes as arguments name denoting an Event name and optionally data. Triggers emitting the Event with the optional data. The method MUST run the following steps:

Return a Promise promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
Let interaction be [[td]].events.name.
If an Event with the name name is not found, reject promise with NotFoundError and stop.
Make a request to the underlying platform to emit an Event with optional data. Call the handling events steps.

Start serving external requests for the Thing, so that WoT Interactions using Properties, Actions and Events will be possible. The method MUST run the following steps:

Return a Promise promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
Run the expand a TD steps on the [[td]].
Run the validate a TD on [[td]]. If that fails, reject promise with a TypeError and stop.
For each key in [[td]].properties initialize this.[[propertyObservers]].key to an empty Array in order to store observe request data needed to notify the observers on value changes.
For each key in this.[[td]].events initialize this.[[eventListeners]].key to an empty Array in order to store subscribe request data needed to notify the subscribers on event emission.
Set up the WoT Interactions based on introspecting [[td]] as explained in [WOT-TD] and [WOT-PROTOCOL-BINDINGS]. Make a request to the underlying platform to initialize the Protocol Bindings and then start serving external requests for WoT Interactions (read, write and observe Properties, invoke Actions and manage Event subscriptions), based on the Protocol Bindings. Implementations MAY reject this step for any reason (e.g. if they want to enforce further checks and constraints on interaction forms).
If there was an error during the request, reject promise with an Error object error with error.message set to the error code seen by the Protocol Bindings and stop.
Otherwise resolve promise and stop.

Stop serving external requests for the Thing and destroy the object. Note that eventual unregistering should be done before invoking this method. The method MUST run the following steps:

Return a Promise promise and execute the next steps in parallel.
If invoking this method is not allowed for the current scripting context for security reasons, reject promise with a SecurityError and stop.
Make a request to the underlying platform to stop serving external requests for WoT Interactions, based on the Protocol Bindings.
If there was an error during the request, reject promise with an Error object error with its message set to the error code seen by the Protocol Bindings and stop.
Otherwise resolve promise and stop.

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

Example 6: Create ExposedThing with a simple Property

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.

Example 7: Add an object Property

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

The following will cover a set of examples for the generation of a Thing Description from an ExposedThingInit using expand an ExposedThingInit steps. As hypothesis the runtime supports HTTP and COAP protocol bindings and it is hosted at 192.168.0.1.

The next example shows how to exploit a ExposedThingInit to create a simple Thing Description with one Property with the default values.

Example 8: Create a Thing Description with one Property affordance

{   "properties" : {     "temperature":{}   } }

{   "@context": [     "https://www.w3.org/2019/wot/td/v1"   ],   "title": "Thing-123",   "securityDefinitions": {     "no_sec": {       "scheme": "nosec"     }   },   "security": "no_sec",   "properties": {     "temperature": {       "forms": [{         "href": "http://192.168.0.1:8080/properties/temperature",         "contentType": "application/json"       },       {       "href": "coap://192.168.0.1:9090/properties/temperature",       "contentType": "application/json"       }]     }   } }

Editor's note

TODO: add more examples where the ExposedThingInit contains suggested values that are replaced by the algorithm.

Discovery is a distributed application that requires provisioning and support from participating network nodes (clients, servers, directory services). This API models the client side of typical discovery schemes supported by various IoT deployments.

The ThingDiscoveryProcess object provides the properties and methods controlling the discovery process and returning the results.

WebIDL[SecureContext, Exposed=(Window,Worker)] interface ThingDiscoveryProcess {   constructor(optional ThingFilter filter = {});   readonly attribute boolean done;   readonly attribute Error? error;   undefined stop();   async iterable<ThingDescription>; };

The ThingDiscoveryProcess object has the following internal slots.

Internal Slot	Initial value	Description (non-normative)
[[filter]]	`undefined`	The `ThingFilter` object used in discovery.
[[url]]	`undefined`	A `URL` representing the TD Directory in a discovery.

The done property is true if the discovery has been stopped or completed with no more results to report.

The error property represents the last error that occurred during the discovery process. Typically used for critical errors that stop discovery.

The ThingDiscoveryProcess object implements the async iterator concept.

To create ThingDiscoveryProcess with a filter, run the following steps:

If filter is not an object or null, throw a TypeError and stop.
Let discovery be a new ThingDiscoveryProcess object.
Set discovery.[[filter]] to filter.
Set discovery.done to false.
Set discovery.error to null.
Return discovery.

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

WebIDLdictionary ThingFilter {   object? fragment;    };

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

Editor's note

The query property was temporarily removed from ThingFilter, until it is standardized in the WoT Discovery task force. It represented a query string accepted by the implementation, for instance a SPARQL or JSON query. Support was to be implemented locally in the WoT Runtime or remotely as a service in a TD Directory.

Editor's note

The url property was removed. It used to represent the target entity serving the discovery request, for instance the URL of a TD Directory, or the URL of a directly targeted Thing, but these are implemented by dedicated methods now.

Describes what to do during a discovery process that has already started. The algorithm, given discovery, runs the following steps:

Whenever a new link to a Thing Description is discovered and provided by the underlying platform, run the following sub-steps:
1. Retrieve td as a JSON object, using the Protocol Binding used by the underlying discovery process (as specified by link). In the case of an HTTP(S) Binding, this process could use the Fetch API for the td's retrieval.
2. If that fails, set the discovery.error property to SyntaxError, discard td and continue the discovery process.
Whenever a Thing Description td is discovered and provided by the underlying platform or by the previous step, run the following sub-steps:

Note

At this point implementations MAY control the flow of the discovery process (depending on memory constraints, for instance queue the results, or temporarily stop discovery if the queue is getting too large, or resume discovery when the queue is emptied sufficiently). These steps are run for each discovered/fetched td.
1. Let fragment be discovery.[[filter]].fragment.
2. If fragment is an object, then for each key defined in it:
  1. Check if that key exists in json and json[key is equal to fragment.key.
  2. If this is fails in any checks, discard td and continue the discovery process.
3. Yield td using asyncIterator.
  
  Editor's note
  
  Improve this step using proper asyncIterator terminology.
Whenever an error occurs during the discovery process, run the following sub-steps:

Note

The last error is retained. Implementations MAY choose to stop the discovery process if they consider it should be reported.
1. Let error be a new Error object. Set error.name to "DiscoveryError".
2. If there was an error code or message provided by the Protocol Bindings, set error.message to that value as string.
3. Set discovery.error to error.
4. If the error is irrecoverable and discovery has been stopped by the underlying platform, or if the implementation decided to stop the discovery process and report the error, set discovery.done to true and terminate these steps.

Stops or suppresses the discovery process. It might not be supported by all discovery methods and endpoints, however, any further discovery results or errors will be discarded and the discovery is marked as done. The method MUST run the following steps:

If invoking this method is not allowed for the current scripting context for security reasons, throw a SecurityError and stop.
Request the underlying platform to stop the discovery process. If this returns an error, or if it is not possible, for instance when discovery is based on open ended multicast requests, the implementation SHOULD discard subsequent discovered items.
Set the done property to true.

The following example finds ThingDescription objects of Things that are exposed by local hardware, regardless how many instances of WoT Runtime it is running Using the asyncIterator provided by the Discovery object, we can iterate asynchronously over the results and perform operations with the obtained ThingDescription objects.

Example 9: Fetch the Thing Description of a Thing

let url = "https://mythings.com/thing1"; let td = await WOT.requestThingDescription(url); console.log("Found Thing Description for " + td.title);

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

Example 10: Discover Things via directory

let discovery = await WOT.exploreDirectory("http://directory.wotservice.org"); setTimeout( () => {     discovery.stop();     console.log("Discovery stopped after timeout.");   },   3000); for await (const td of discovery) {   console.log("Found Thing Description for " + td.title);   let thing = new ConsumedThing(td);   console.log("Thing name: " + thing.getThingDescription().title); }; if (discovery.error) {   console.log("Discovery stopped because of an error: " + error.message); }

The next example is for a generic discovery, by any means provisioned to the WOT runtime, including local Things, if any is available.

Example 11: Discover Things in a network

let discovery = await WOT.discover(); setTimeout( () => {     discovery.stop();     console.log("Stopped open-ended discovery");   },   10000); for await (const td of discovery) {   console.log("Found Thing Description for " + td.title); }; if (discovery.error) {   console.log("Discovery stopped because of an error: " + error.message); }

Web of Things (WoT) Scripting API

Abstract

Status of This Document

1. Introduction

2. Use Case Scenarios

2.1 Consuming a Thing

2.2 Exposing a Thing

2.3 Discovery

3. Conformance

4. Terminology and conventions

5. The ThingDescription type

5.1 Fetching a Thing Description

5.2 Expanding a Thing Description

5.3 Validating a Thing Description

6. The WOT namespace

6.1 The consume() method

6.2 The produce() method

6.2.1 Expand an ExposedThingInit

6.2.2 Validating an ExposedThingInit

6.3 The discover() method

6.4 The exploreDirectory() method

6.5 The requestThingDescription() method

7. Handling interaction data

7.1 The InteractionInput type

7.2 The InteractionOutput interface

7.2.1 The value() function

7.2.2 The arrayBuffer() function

7.2.3 The check data schema algorithm

7.2.4 The create interaction request algorithm

7.2.5 The parse interaction response algorithm

7.3 Using InteractionInput and InteractionOutput

7.4 Error handling

8. The ConsumedThing interface

8.1 Internal slots for ConsumedThing

8.2 Constructing ConsumedThing

8.3 The getThingDescription() method

8.4 The readProperty() method

8.5 The readMultipleProperties() method

8.6 The readAllProperties() method

8.7 The writeProperty() method

8.8 The writeMultipleProperties() method

8.9 The observeProperty() method

8.10 The invokeAction() method

8.11 The subscribeEvent() method

8.12 The InteractionOptions dictionary

8.13 The PropertyReadMap type

8.14 The PropertyWriteMap type

8.15 The InteractionListener callback

8.16 The ErrorListener callback

8.17 The Subscription interface

8.17.1 Internal slots for Subscription

8.17.2 The stop() method

8.17.3 Finding an unsubscribe Form

8.18 ConsumedThing Examples

9. The ExposedThing interface

9.1 Internal slots for ExposedThing

9.2 Constructing ExposedThing

9.3 The getThingDescription() method

9.4 The PropertyReadHandler callback

9.5 The setPropertyReadHandler() method

9.6 Handling requests for reading a Property

9.7 Handling requests for reading multiple Properties

9.8 Handling requests for reading all Properties

9.9 The setPropertyObserveHandler() method

9.10 Handling Property observe requests

9.11 The setPropertyUnobserveHandler() method

9.12 Handling Property unobserve requests

9.13 The emitPropertyChange() method

9.14 The PropertyWriteHandler callback

9.15 The setPropertyWriteHandler() method

9.16 Handling requests for writing a Property

9.17 Handling requests for writing multiple Properties

9.18 The ActionHandler callback

9.19 The setActionHandler() method

9.20 Handling Action requests

9.21 The EventSubscriptionHandler callback

9.22 The setEventSubscribeHandler() method

9.23 Handling Event subscribe requests

9.24 The setEventUnsubscribeHandler() method

9.25 Handling Event unsubscribe requests

5. The `ThingDescription` type

6. The `WOT` namespace

6.1 The `consume()` method

6.2 The `produce()` method

6.3 The `discover()` method

6.4 The `exploreDirectory()` method

6.5 The `requestThingDescription()` method

7.1 The `InteractionInput` type

7.2 The `InteractionOutput` interface

7.2.1 The `value()` function

7.2.2 The `arrayBuffer()` function

7.3 Using `InteractionInput` and `InteractionOutput`

8. The `ConsumedThing` interface

8.1 Internal slots for `ConsumedThing`

8.2 Constructing `ConsumedThing`

8.3 The `getThingDescription()` method

8.4 The `readProperty()` method

8.5 The `readMultipleProperties()` method

8.6 The `readAllProperties()` method

8.7 The `writeProperty()` method

8.8 The `writeMultipleProperties()` method

8.9 The `observeProperty()` method

8.10 The `invokeAction()` method

8.11 The `subscribeEvent()` method

8.12 The `InteractionOptions` dictionary

8.13 The `PropertyReadMap` type

8.14 The `PropertyWriteMap` type

8.15 The `InteractionListener` callback

8.16 The `ErrorListener` callback

8.17 The `Subscription` interface

8.17.1 Internal slots for `Subscription`

8.17.2 The `stop()` method

9. The `ExposedThing` interface

9.2 Constructing `ExposedThing`

9.3 The `getThingDescription()` method

9.4 The `PropertyReadHandler` callback

9.5 The `setPropertyReadHandler()` method

9.9 The `setPropertyObserveHandler()` method

9.11 The `setPropertyUnobserveHandler()` method

9.13 The `emitPropertyChange()` method

9.14 The `PropertyWriteHandler` callback

9.15 The `setPropertyWriteHandler()` method

9.18 The `ActionHandler` callback

9.19 The `setActionHandler()` method

9.21 The `EventSubscriptionHandler` callback

9.22 The `setEventSubscribeHandler()` method

9.24 The `setEventUnsubscribeHandler()` method

9.27 The `emitEvent()` method

9.28 The `expose()` method

9.29 The `destroy()` method

10. The `ThingDiscoveryProcess` interface

10.1 Constructing `ThingDiscoveryProcess`

10.2 The `ThingFilter` dictionary

10.4 The `stop()` method