From d59dceabcd2c7d83cb353214ed3ff2f2c8b01b11 Mon Sep 17 00:00:00 2001 From: ashimura Date: Tue, 14 Feb 2017 11:24:39 +0900 Subject: [PATCH 001/464] Adding baseline CONTRIBUTING.md --- CONTRIBUTING.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..388d1e4f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,24 @@ +# Web of Things Working Group + +Contributions to this repository are intended to become part of Recommendation-track documents governed by the +[W3C Patent Policy](http://www.w3.org/Consortium/Patent-Policy-20040205/) and +[Software and Document License](http://www.w3.org/Consortium/Legal/copyright-software). To make substantive contributions to specifications, you must either participate +in the relevant W3C Working Group or make a non-member patent licensing commitment. + +If you are not the sole contributor to a contribution (pull request), please identify all +contributors in the pull request comment. + +To add a contributor (other than yourself, that's automatic), mark them one per line as follows: + +``` ++@github_username +``` + +If you added a contributor by mistake, you can remove them in a comment with: + +``` +-@github_username +``` + +If you are making a pull request on behalf of someone else but you had no part in designing the +feature, you can remove yourself with the above syntax. From f92313044693cba463826f54c583cd2ae15206a4 Mon Sep 17 00:00:00 2001 From: ashimura Date: Tue, 14 Feb 2017 11:24:40 +0900 Subject: [PATCH 002/464] Adding baseline README.md --- README.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..84c6efb8 --- /dev/null +++ b/README.md @@ -0,0 +1,5 @@ + +# Specification 'wot-scripting-api' + +This is the repository for wot-scripting-api. You're welcome to contribute! Let's make the Web rock our socks +off! From 2dcac1f79b71faeaaf2846a09190d29004b49e55 Mon Sep 17 00:00:00 2001 From: ashimura Date: Tue, 14 Feb 2017 11:24:40 +0900 Subject: [PATCH 003/464] Adding baseline index.html --- index.html | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 index.html diff --git a/index.html b/index.html new file mode 100644 index 00000000..37a127d6 --- /dev/null +++ b/index.html @@ -0,0 +1,38 @@ + + + + + Spec proposal + + + + +
+

+ This specification does neat stuff. +

+
+
+

+ This is an unofficial proposal. +

+
+ +
+

Introduction

+

+ See ReSpec's user guide + for how toget started! +

+
+ + From f071ffb2f3c45e4db0fa779f9b3d68a5a67cf033 Mon Sep 17 00:00:00 2001 From: ashimura Date: Tue, 14 Feb 2017 11:24:41 +0900 Subject: [PATCH 004/464] Adding baseline w3c.json --- w3c.json | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 w3c.json diff --git a/w3c.json b/w3c.json new file mode 100644 index 00000000..d6f8b345 --- /dev/null +++ b/w3c.json @@ -0,0 +1,5 @@ + { + "group": ["95969"] +, "contacts": ["ashimura"] +, "shortName": "wot-scripting-api" +} \ No newline at end of file From 4bdb4f6ad623c76428b0141fdd705a9a736d0e9b Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Thu, 23 Feb 2017 19:57:26 +0200 Subject: [PATCH 005/464] Initial draft: structure, use cases Signed-off-by: Zoltan Kis --- index.html | 372 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 355 insertions(+), 17 deletions(-) diff --git a/index.html b/index.html index 37a127d6..9a942a22 100644 --- a/index.html +++ b/index.html @@ -2,37 +2,375 @@ - Spec proposal + Web of Things Scripting API -
-

- This specification does neat stuff. -

+ +
+

+ This specification describes a programming interface to [the Web of Things](http://w3c.github.io/wot/current-practices/wot-practices.html) (WoT), that allows scripts run on a Thing to discover and access other Things through a Client API, provide resources characterized by properties, actions and events through a Server API, and access locally attached hardware through a Physical API. +

+
+ +
+

+ Implementers need to be aware that this specification is considered unstable. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation phase should subscribe to the [repository](https://github.com/w3c/wot-scripting-api) and take part in the discussions. +

+
+ +
+

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

+

+ The UA may be implemented in the browser, or in a separate runtime environment. +

+

+ This specification can be used for implementing the WoT Scripting API in multiple language bindings. Currently ECMAScript and TypeScript definitions are described in this document. For specifying bindings in other languages, extensions of this document may be created later. +

+

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

+

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

+

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

+
+ +

Terminology and conventions

+

+ A WoT runtime or simply Runtime is defined as a software stack that manages the lifecycle of WoT application scripts (see also the [Wikipedia definition](https://en.wikipedia.org/wiki/Runtime_system)). In the case of ECMAScript and TypeScript scripts, it consists of an ECMAScript interpreter, script lifecycle management, and an operating system API that provides access to local and remote resources. A Runtime can be modeled as a virtual machine in the sense that it should be completely isolated from other execution environments on memory address space, storage address space (file system), network namespace, etc. A runtime may be for instance a Node.js environment, an embedded runtime based on a small JavaScript engine, or provided by a browser. +

+

+ The following terms are defined in [[!WOT-PRACTICES]]: +

+
+
Thing
+
A physical or virtual entity that represents physicality, such as a device, a group of devices, a room, or a software stack that exposes WoT interfaces.
+ +
Thing Description
+
An RDF document (currently serialized in JSON-LD by default) that contains semantic and functional descriptions of a Thing: semantic context, interaction resources (such as properties, actions and events), communication (protocol, data serialization, bindings), and security related data (e.g. keys, certificates, policies etc).
+ +
WoT Interface
+
Resource-oriented Web interface (often called "Web API") that allows access to Things exposed over a network using different Protocol Bindings, as defined by Thing Descriptions.
+ +
Protocol Bindings
+
Mapping WoT Thing interactions to specific protocol suites. Protocol bindings are being defined for HTTP, CoAP, Bluetooth Smart (BLE), MQTT, WebSockets, etc.
+ +
JSON-LD
+
A JSON document that is augmented with support for Linked Data by providing an @context property with a defining URI [[!JSON-LD]].
+ +
+

+ Consuming a Thing Description means parsing the Thing Description and building a resource model with the use of Protocol Bindings that can be used in a script for accessing and controlling the Thing. A Thing when starts up, consumes its own TD, then it exposes its WoT interface as a server. Note that a script on a Thing may consume other TDs and expose a combined interface of the consumed Things. +

+

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

+

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

+

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

+

+ The term + + secure context is defined in [[!WEBAPPSEC]]. +

+

+ + Promise, + + JSON, + + JSON.stringify and + + JSON.parse + are defined in [[!ECMASCRIPT]]. +

+

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

+

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

+
+ +

Introduction

+

+ As described in the [WoT Current Practices](http://w3c.github.io/wot/current-practices/wot-practices.html#vision), the Web of Things is made of Things that can describe their capabilities in a machine-interpretable format, the Thing Description (TD). By consuming a TD, a Thing creates a runtime resource model that allows accessing the Thing by an application. +

+
+ +

Use Cases

+

+ The following scripting use cases are covered in this specification: +

    +
  • Discover Things by filters defined on Thing Descriptions.
    • +
  • Consume a TD of a remote Thing.
    • +
  • On a consumed Thing, +
      +
    • Get a property value.
      • +
    • Set a property value.
      • +
    • Invoke an action.
      • +
    • Add a listener to an event.
      • +
    • Remove a listener from an event.
      • +
    +
    • +
  • Create and expose a local Thing based on a Thing Description.
    • +
  • Programmatically create and expose a local Thing. This may include the following operations: +
      +
    • Add a property definition to the Thing.
      • +
    • Add an event definition to the Thing.
      • +
    • Add an action definition to the Thing.
      • +
    • Start the exposed Thing in order to process external requests.
      • +
    • Handle an external request to retrieve the Thing Description.
      • +
    • Handle an external request to add a listener to an event.
      • +
    • Handle an external request to remove a listener to an event.
      • +
    • Handle an external request to run an action: take the parameters from the request, execute the defined action, and return the result.
      • +
    • Emit an event, i.e. notify all listeners subscribed to that event.
      • +
    • Stop the exposed Thing. +
    +
    • +
+

+
+ +

Security and Privacy

+

+ The trust model, attacker model, threat model and possible mitigation + proposals for the Wot Scripting API are presented in the [Security and Privacy document](http://w3c.github.io/wot-scripting-api/security-privacy.html). This section presents the chosen + security and privacy model through normative requirements to implementations. +

+ +

Chain of Trust

+

+ Things discoverable and accessible in a WoT network SHOULD be identified and authenticated. +

+

+ The integrity of WoT communication SHOULD be ensured by implementations. +

-
-

- This is an unofficial proposal. -

+ +

Threat Model

+

+ The main threats are summarized in the [Security and Privacy document](http://w3c.github.io/web-nfc/security-privacy.html#threats-and-possible-solutions). +

+

+ In this specification the following threats are considered of the highest priority: +

    +
  • + Unauthorized gathering of user-sensitive information. +
    • +
  • + Vulnerability of the underlying protocols. +
    • +
  • + Protect the integrity of Things and Thing Descriptions. +
    • +
+

+
+ +

Security Mechanisms

+

Identification, Authentication, Authorization

+
+ +

Transport-level security

+
+ +

Application-level security

+
-
-

Introduction

+

Security policies

- See ReSpec's user guide - for how toget started! + This section summarizes the security policies which are specified as + normative requirements in the respective algorithms of this + specification.

+
+ +

WoT Data Representation

+
+ +

The WoT Discovery API

+
+ +

The WoT Client API

+
+ +

The WoT Server API

+
+ +

Changes

+

+ The following is a list of major changes to the document. For a complete list of changes, see the [github change log](https://github.com/w3c/wot-scripting-api/commits/master). You can also view the [recently closed bugs](https://github.com/w3c/wot-scripting-api/issues?page=1&state=closed). +

+
+ +

Open issues

+

+ The following problems are being discussed and need most attention: +

    +
  • Issue [1](https://github.com/w3c/wot-scripting-api/issues)
    • +
  • Issue [2](ghttps://github.com/w3c/wot-scripting-api/issues)
    • +
+

+
+ +

Acknowledgements

+

+ The editors would like to thank Dave Raggett, Matthias Kovatsch, and Michael Koster for their + comments and guidance to this document. +

+
+ From 8fc1aaebdd97e3c7c019cca3e065901d82836922 Mon Sep 17 00:00:00 2001 From: Kazuyuki Ashimura Date: Sat, 25 Feb 2017 01:26:33 +0900 Subject: [PATCH 006/464] updated as a template for ED --- index.html | 111 ++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 89 insertions(+), 22 deletions(-) diff --git a/index.html b/index.html index 37a127d6..33183504 100644 --- a/index.html +++ b/index.html @@ -2,37 +2,104 @@ - Spec proposal + Web of Things Scripting API -
-

- This specification does neat stuff. -

-
-
-

- This is an unofficial proposal. -

-
-
-

Introduction

-

- See ReSpec's user guide - for how toget started! -

-
+
+

+ This specification describes a programming interface to [the Web of Things](http://w3c.github.io/wot/current-practices/wot-practices.html) (WoT), that allows scripts run on a Thing to discover and access other Things through a Client API, provide resources characterized by properties, actions and events through a Server API, and access locally attached hardware through a Physical API. +

+
+ +
+

+ Implementers need to be aware that this specification is considered unstable. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation phase should subscribe to the [repository](https://github.com/w3c/wot-scripting-api) and take part in the discussions. +

+
+ + From 6b89fd9f8267bf1ec5202eabf2de85418f6fbe52 Mon Sep 17 00:00:00 2001 From: Kazuyuki Ashimura Date: Sat, 25 Feb 2017 01:33:48 +0900 Subject: [PATCH 007/464] add WoT to title --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 33183504..799b99d6 100644 --- a/index.html +++ b/index.html @@ -2,7 +2,7 @@ - Web of Things Scripting API + Web of Things (WoT) Scripting API + + + + + + +
+

Abstract

+

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

+

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

+

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

+
+
+

Status of This Document

+

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

+

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

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

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

+
+

+ This document was published by the Web of Things Working Group as an Editor's Draft. Comments regarding this document are welcome. Please send them to + public-wot-wg@w3.org@w3.org (subscribe, + archives). +

+

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

+

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

+

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

+ + +
+ +
+ +

1. Introduction

+

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

+

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

+

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

+
+
Note
+

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

+
+

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

+
+
+ +

2. Use Cases

+

This section is non-normative.

+

+ The following scripting use cases are covered in this specification: +

+
    +
  • Discover all Things in the WoT network by sending a broadcast request.
    • +
  • Discover Things running in the local WoT Runtime.
    • +
  • Discover nearby Things, for instance by NFC or Bluetooth.
    • +
  • Discover Things by sending a discovery request to a given registry.
    • +
  • Discover Things by filters defined on Thing Descriptions
    • +
  • Discover Things by semantic filters.
    • +
  • Stop or suppress an ongoing discovery process.
    • +
  • Fetch and consume a TD of a remote Thing.
    • +
  • On a consumed Thing, + +
    • +
  • Consume a thing.
    • +
  • Create and expose a local Thing based on a Thing Description.
    • +
  • Programmatically create and expose a local Thing. This may include the following use cases: +
      +
    • Create a local Thing.
      • +
    • Add a Property definition to the Thing.
      • +
    • Add an Event definition to the Thing.
      • +
    • Add an Action definition to the Thing.
      • +
    • Attach semantic information to an Action
      • +
    • Attach semantic information to a Property
      • +
    • Attach semantic information to an Event
      • +
    • + Emit an Event, i.e. notify all listeners subscribed to that Event. +
      • +
    • Register handlers for external requests: +
        +
      • to retrieve a Property value;
        • +
      • to update a Property value;
        • +
      • + to run an Action: take the parameters from the request, execute the defined action, and return the result; +
        • +
      • to add a listener to an Event;
        • +
      • to remove an Event listener.
        • +
      • to fetch the Thing Description;
        • +
      +
      • +
    +
    • +
  • Register the Thing.
    • +
  • Unregister the Thing.
    • +
  • Start the exposed Thing in order to process external requests.
    • +
  • Stop the exposed Thing.
    • +
+

+ The following use cases are being considered for next versions: +

+
    +
  • + Add, remove and update the definition of a Property on a Thing that runs in the same the WoT Runtime. +
    • +
  • + Add, remove and update the definition of an Action on a Thing that runs in the same the WoT Runtime. +
    • +
  • + Add, remove and update the definition of an Event on a Thing that runs in the same the WoT Runtime. +
    • +
+
+
+ +

3. The WoT object

+

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

+
+
Note
+

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

+
+ +
+
Editor's note
+

+ The algorithms for the WoT methods will be specified later. +

+
+
+

3.1 The discover() method

+

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

+
+

3.1.1 The ThingFilter dictionary

+

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

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

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

+

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

+

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

+
+
Editor's note
+

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

+
+
+
Editor's note
+

+ The ThingFilter dictionary may be extended later with further attributes.

+
+
+
+

3.1.2 The DiscoveryMethod enumeration

+ +

+ The DiscoveryMethod enumeration represents the discovery type to be used: +

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

3.2 The consume() method

+

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

+
+
+

3.3 The expose() method

+

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

+
+
Editor's note
+

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

+
+
+

3.3.1 The ThingInit dictionary

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

The ThingInit dictionary contains properties to initialize a Thing: +

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

3.4 Examples

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

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

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

4. The ConsumedThing interface

+

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

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

+ Represents a local proxy object of the remote Thing. +

+
    +
  • The name read-only attribute represents the name of the Thing.
    • +
  • The url read-only attribute represents the URL of the Thing.
    • +
  • + The description attribute read-only attribute represents the description of the Thing. +
    +
    Editor's note
    +

    + Parsing and exposing Thing Descriptions is discussed in Issue 38.

    +
    +
    • +
+
+

4.1 The invokeAction() method

+

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

+
+
+

4.2 The setProperty() method

+

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

+
+
+

4.3 The getProperty() method

+

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

+
+
+

4.4 The addListener() method

+

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

+
+
+

4.5 The removeListener() method

+

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

+
+
+

4.6 The removeAllListeners() method

+

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

+
+
+

4.7 The observe() method

+

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

+
+
Editor's note
+

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

+
+
+
+

4.8 The ThingEventListener callback

+

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

+
+
+

4.9 Events

+

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

+
+

4.9.1 The PropertyChangeEvent interface

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

+ The data attribute represents the changed Property. +

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

The name> attribute represents the Property name.

+

The value attribute represents the new value of the Property.

+
+
+
+

4.9.2 The ActionInvocationEvent interface

+ +

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

+
+
4.9.2.1 The ActionInvocationEventInit dictionary
+ +
+
Editor's note
+

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

+
+

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

+

+ The returnValue attribute represents the return value of the + Action. +

+
+
+
+

4.9.3 The ThingDescriptionChangeEvent interface

+ +

+ The data attribute represents the changes that occured to the Thing Description. +

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

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

+
+
+
+
+
+

4.10 Examples

+

+ Below a ConsumedThing + interface example is given. +

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

5. The ExposedThing interface

+

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

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

5.1 The ThingDescription type

+

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

+
+
Note
+

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

+
+
+
+

5.2 The Request interface

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

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

+
    +
  • + The type attribute represents the type of the request as defined in RequestType. +
    • +
  • + The from attribute represents the address of the client device issuing the request. The type of the address (URL, + UUID or other) is defined by the Thing Description. +
    • +
  • + The name attribute represents the name of the Property to be retrieved or updated, or the name of the invoked Action, or the event name to be observed. +
    • +
  • + The options attribute represents the options relevant to the request (e.g. the format or measurement units + for the returned value) as key-value pairs. The exact format is specified by the Thing Description. +
    • +
  • + The data attribute represents the value of the Property, + or the input data (arguments) of an Action. It is not used for retrieve requests and event requests, only for Property update and Action invocation requests. +
    • +
+
+

5.2.1 The RequestType enumeration

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

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

    +
    +
    • +
+
+
+

5.2.2 The respond() method

+

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

+
+
+

5.2.3 The respondWithError() method

+

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

+
+
+
+

5.3 The RequestHandler callback

+

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

+
+
+

5.4 The addProperty() method

+

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

+
+

5.4.1 The ThingPropertyInit dictionary

+ +

+ Represents the Thing + Property description. +

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

5.4.2 The SemanticType dictionary

+
+ 
dictionary SemanticType {
+    DOMString name;
+    USVString context;
+};
+
+

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

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

+ Semantic type examples to be added. +

+
+
+
+
+

5.5 The removeProperty() method

+

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

+
+
+

5.6 The addAction() method

+

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

+
+

5.6.1 The ThingActionInit dictionary

+ +

+ The ThingActionInit dictionary describes the arguments and the return value. +

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

5.7 The removeAction() method

+

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

+
+
+

5.8 The addEvent() method

+

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

+
+

5.8.1 The ThingEventInit dictionary

+ +
    +
  • The name attribute represents the event name.
    • +
  • The semanticTypes attribute represent a list of semantic type annotations attached + to the event.
    • +
  • The dataDescription attribute represents the description of the data that is + attached to the event.
    • +
+
+
+
+

5.9 The removeEvent() method

+

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

+
+
+

5.10 The onRetrieveProperty() method

+

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

+
+
+

5.11 The onUpdateProperty() method

+

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

+
+
+

5.12 The onInvokeAction() method

+

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

+
+
+

5.13 The onObserve() method

+

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

+
    +
  • + request.name defines the name of the Property or Action or event to be observed. +
    • +
  • + request.options.observeType is of type RequestType and defines whether a Property change or Action invocation or event emitting is observed, or the changes to the Thing Description are observed. +
    • +
  • + request.options.subscribe is true if subscription is turned or kept being turned on, and it is false when subscription is turned off. +
    • +
+
+
+

5.14 The register() method

+

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

+
+
+

5.15 The unregister() method

+

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

+
+
+

5.16 The start() method

+

+ Start serving external requests for the Thing. +

+
+
+

5.17 The stop() method

+

+ Stop serving external requests for the Thing. +

+
+
+

5.18 The emitEvent() method

+

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

+
+
+

5.19 Events supported by ExposedThing

+

+ The following default events SHOULD be supported by ExposedThing implementations: +

+ +

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

+
+
+

5.20 Examples

+

+ Below some ExposedThing + interface examples are given. +

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

6. Security and Privacy

+
+
Editor's note
+

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

+
+
+
+ +

7. Terminology and conventions

+

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

+
+
Note
+

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

+
+

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

+

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

+

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

+

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

+

+ The term + + secure context is defined in [WEBAPPSEC]. +

+

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

+

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

+

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

+
+
Note
+

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

+
+

+ Observables are proposed to be included in ECMAScript. +

+

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

+

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

+
+
+ +

8. Conformance

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+
+
+ +

A. Changes

+

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

+
+
+ +

B. Open issues

+

+ The following problems are being discussed and need most attention: +

+ +
+
+ +

C. Acknowledgements

+

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

+
+
+ +

D. References

+
+

D.1 Normative references

+
[ECMASCRIPT]
+
ECMAScript Language Specification. Ecma International. URL: https://tc39.github.io/ecma262/ +
[ENCODING]
+
Encoding Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://encoding.spec.whatwg.org/ +
[HTML5]
+
HTML5. Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. W3C. 28 October 2014. W3C Recommendation. URL: https://www.w3.org/TR/html5/ +
[JSON-LD]
+
JSON-LD 1.0. Manu Sporny; Gregg Kellogg; Markus Lanthaler. W3C. 16 January 2014. W3C Recommendation. URL: https://www.w3.org/TR/json-ld/ +
[RFC2119]
+
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119 +
[TYPESCRIPT]
+
TypeScript Language Specification. Microsoft. 1 October 2012. URL: https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md +
[URL]
+
URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/ +
[WEBAPPSEC]
+
Secure Contexts. W3C. 17 July 2015. URL: https://w3c.github.io/webappsec/specs/powerfulfeatures +
[WEBIDL]
+
Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/ +
[WOT-ARCHITECTURE]
+
Web of Things Architecture. W3C. 20 August 2017. URL: https://w3c.github.io/wot-architecture/ +
+
+
+
+ + + + + \ No newline at end of file From f26ce8a77f2a138f3788cde42861f587f17c97d9 Mon Sep 17 00:00:00 2001 From: Kazuyuki Ashimura Date: Tue, 12 Sep 2017 15:05:22 +0900 Subject: [PATCH 129/464] add --- Overview.html | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Overview.html b/Overview.html index f3f0fd81..60336406 100644 --- a/Overview.html +++ b/Overview.html @@ -832,11 +832,11 @@ font-weight: bold; } - + @@ -942,10 +942,10 @@

Web of Things (WoT) Scripting API

-

W3C Editor's Draft

+

W3C First Public Working Draft

This version:
-
https://w3c.github.io/wot-scripting-api/
+
https://www.w3.org/TR/2017/WD-wot-scripting-api-20170912/
Latest published version:
https://www.w3.org/TR/wot-scripting-api/
Latest editor's draft:
@@ -2474,4 +2474,4 @@

D.1 Normative refer - \ No newline at end of file + From e6957082b7e656a6e47d6b1d6d49f4879aa38bd9 Mon Sep 17 00:00:00 2001 From: Kazuyuki Ashimura Date: Tue, 12 Sep 2017 15:14:05 +0900 Subject: [PATCH 130/464] add --- Overview.html | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/Overview.html b/Overview.html index 60336406..ac874987 100644 --- a/Overview.html +++ b/Overview.html @@ -997,7 +997,7 @@

Abstract

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

@@ -1016,19 +1016,23 @@

Status of This Document

- This document was published by the Web of Things Working Group as an Editor's Draft. Comments regarding this document are welcome. Please send them to + This document was published by the Web of Things Working Group as a First Public Working Draft. + This document is intended to become a W3C Recommendation. +

+

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

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

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. - W3C maintains a public list of any patent + W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with From e5ab0e069a46bd5a93e466c2fe1de114ddcf99c8 Mon Sep 17 00:00:00 2001 From: Kazuyuki Ashimura Date: Tue, 12 Sep 2017 15:18:25 +0900 Subject: [PATCH 131/464] add --- Overview.html | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Overview.html b/Overview.html index ac874987..1c268fad 100644 --- a/Overview.html +++ b/Overview.html @@ -996,8 +996,7 @@

Abstract

class="internalDFN" data-link-type="dfn">Actions and Events.

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

From ce41540f4fe06f62371dd803faa39ae1f37e6d6b Mon Sep 17 00:00:00 2001 From: Kazuyuki Ashimura Date: Tue, 12 Sep 2017 15:29:23 +0900 Subject: [PATCH 132/464] add --- Overview.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Overview.html b/Overview.html index 1c268fad..65e3c381 100644 --- a/Overview.html +++ b/Overview.html @@ -996,7 +996,7 @@

Abstract

class="internalDFN" data-link-type="dfn">Actions and Events.

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

@@ -1020,8 +1020,8 @@

Status of This Document

Comments regarding this document are welcome. Please send them to - public-wot-wg@w3.org@w3.org (subscribe, - archives). + @@@fixed the email address@@@ public-wot-wg@w3.org (@@@fixed the email addres@@@ subscribe, + @@@fixed the URL@@@ archives).

Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate From 5ef04712f4003c2785e0314c00e51682a58406b1 Mon Sep 17 00:00:00 2001 From: Kazuyuki Ashimura Date: Tue, 12 Sep 2017 17:01:17 +0900 Subject: [PATCH 133/464] fixing --- Overview.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Overview.html b/Overview.html index 65e3c381..fbd40bf7 100644 --- a/Overview.html +++ b/Overview.html @@ -866,7 +866,7 @@ ], "wg": "Web of Things Working Group", "wgURI": "https://www.w3.org/WoT/WG/", - "wgPublicList": "public-wot-wg@w3.org", + "wgPublicList": "public-wot-wg", "issueBase": "https://www.github.com/w3c/wot-scripting-api/issues/", "githubAPI": "https://api.github.com/repos/w3c/wot-scripting-api", "otherLinks": [{ @@ -1020,7 +1020,7 @@

Status of This Document

Comments regarding this document are welcome. Please send them to - @@@fixed the email address@@@ public-wot-wg@w3.org (@@@fixed the email addres@@@ subscribe, + @@@fixed the email address ("wgPublicList": "public-wot-wg")@@@ public-wot-wg@w3.org (@@@fixed the email addres@@@ subscribe, @@@fixed the URL@@@ archives).

From bb9b08f4a1ba8e08fd9d28fdf622b4efc2913300 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Tue, 12 Sep 2017 11:38:45 +0300 Subject: [PATCH 134/464] Editorial fixes for FPWD Signed-off-by: Zoltan Kis --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index dabfd53f..b006144a 100644 --- a/index.html +++ b/index.html @@ -102,7 +102,7 @@ This specification describes a programming interface representing the WoT Interface that allows scripts run on a Thing to discover and consume (retrieve) other Things and to expose Things characterized by properties, Actions and Events.

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

From 49814a96d392f421355a813b2616bb9247b3aebd Mon Sep 17 00:00:00 2001 From: Kazuyuki Ashimura Date: Wed, 13 Sep 2017 14:22:19 +0900 Subject: [PATCH 135/464] fixing --- Overview.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Overview.html b/Overview.html index fbd40bf7..a2ab60db 100644 --- a/Overview.html +++ b/Overview.html @@ -996,7 +996,7 @@

Abstract

class="internalDFN" data-link-type="dfn">Actions and Events.

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

@@ -1020,8 +1020,8 @@

Status of This Document

Comments regarding this document are welcome. Please send them to - @@@fixed the email address ("wgPublicList": "public-wot-wg")@@@ public-wot-wg@w3.org (@@@fixed the email addres@@@ subscribe, - @@@fixed the URL@@@ archives). + public-wot-wg@w3.org (subscribe, + archives).

Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate From 3df0a41deb71d5c42ecfa3e8e10869313cf1240d Mon Sep 17 00:00:00 2001 From: Kazuyuki Ashimura Date: Wed, 13 Sep 2017 14:23:18 +0900 Subject: [PATCH 136/464] fixing --- Overview.html | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Overview.html b/Overview.html index a2ab60db..86ad7fdf 100644 --- a/Overview.html +++ b/Overview.html @@ -927,8 +927,8 @@ "date": "17 July 2015" } }, - "publishISODate": "2017-09-12T00:00:00.000Z", - "generatedSubtitle": "First Public Working Draft 12 September 2017" + "publishISODate": "2017-09-14T00:00:00.000Z", + "generatedSubtitle": "First Public Working Draft 14 September 2017" } @@ -942,10 +942,10 @@

Web of Things (WoT) Scripting API

-

W3C First Public Working Draft

+

W3C First Public Working Draft

This version:
-
https://www.w3.org/TR/2017/WD-wot-scripting-api-20170912/
+
https://www.w3.org/TR/2017/WD-wot-scripting-api-20170914/
Latest published version:
https://www.w3.org/TR/wot-scripting-api/
Latest editor's draft:
From 068c622de64ae57666070f3dcf76ae552237241f Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 13 Sep 2017 10:18:34 +0300 Subject: [PATCH 137/464] Fix #57, edits Signed-off-by: Zoltan Kis --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index b006144a..efbcbf98 100644 --- a/index.html +++ b/index.html @@ -26,7 +26,7 @@ ], wg: "Web of Things Working Group", wgURI: "https://www.w3.org/WoT/WG/", - wgPublicList: "public-wot-wg@w3.org", + wgPublicList: "public-wot-wg", issueBase: "https://www.github.com/w3c/wot-scripting-api/issues/", githubAPI: "https://api.github.com/repos/w3c/wot-scripting-api", otherLinks: [ @@ -102,7 +102,7 @@ This specification describes a programming interface representing the WoT Interface that allows scripts run on a Thing to discover and consume (retrieve) other Things and to expose Things characterized by properties, Actions and Events.

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

From 0aa932d5031392fda844beaaad7213c13d3cac91 Mon Sep 17 00:00:00 2001 From: Kazuyuki Ashimura Date: Wed, 13 Sep 2017 17:09:00 +0900 Subject: [PATCH 138/464] fixing --- Overview.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Overview.html b/Overview.html index 86ad7fdf..d1cea002 100644 --- a/Overview.html +++ b/Overview.html @@ -996,7 +996,8 @@

Abstract

class="internalDFN" data-link-type="dfn">Actions and Events.

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

From 9bfdefd300ceab670a9a510bd4b4c1e716ef446a Mon Sep 17 00:00:00 2001 From: Kazuyuki Ashimura Date: Thu, 14 Sep 2017 03:51:45 +0900 Subject: [PATCH 139/464] fix broken link --- Overview.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Overview.html b/Overview.html index d1cea002..8e9f54c0 100644 --- a/Overview.html +++ b/Overview.html @@ -997,7 +997,7 @@

Abstract

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

From 7f22e43a1c8178a375984503908234d6ed5d1bdc Mon Sep 17 00:00:00 2001 From: Kazuyuki Ashimura Date: Thu, 14 Sep 2017 04:00:04 +0900 Subject: [PATCH 140/464] fix typos and broken link --- Overview.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Overview.html b/Overview.html index 8e9f54c0..590ee849 100644 --- a/Overview.html +++ b/Overview.html @@ -1434,7 +1434,7 @@

3.2 The 3.3 The expose() method

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

Editor's note
@@ -1661,7 +1661,7 @@
4
Editor's note

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

@@ -1683,7 +1683,7 @@

4. };

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

From 49e94299959f92401982ad04e1c4871670c1c1e1 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 13 Sep 2017 22:47:59 +0300 Subject: [PATCH 141/464] Fix Pubrules issues Signed-off-by: Zoltan Kis --- index.html | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/index.html b/index.html index efbcbf98..d8c11ff6 100644 --- a/index.html +++ b/index.html @@ -102,7 +102,7 @@ This specification describes a programming interface representing the WoT Interface that allows scripts run on a Thing to discover and consume (retrieve) other Things and to expose Things characterized by properties, Actions and Events.

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

@@ -310,7 +310,7 @@

The DiscoveryMethod enumeration

The expose() method

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

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

The ActionInvocationEventInit dictionary

};

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

The actionName attribute represents the name of the Action that has been invoked. @@ -527,7 +527,7 @@

The ThingDescriptionChangeEvent interface

};

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

The ThingDescriptionChangeEventInit dictionary

@@ -1186,7 +1186,7 @@

Examples

Acknowledgements

- Special thanks to former editor Johannes Hund for developing this specification. Also, the editors would like to thank Dave Raggett, Matthias Kovatsch, Michael Koster and Michael McCool for their comments and guidance. + Special thanks to former editor Johannes Hund (until August 2017, when at Siemens AG) for developing this specification. Also, the editors would like to thank Dave Raggett, Matthias Kovatsch, Michael Koster and Michael McCool for their comments and guidance.

From c8c1b6528deef7717992e5381819313a551864da Mon Sep 17 00:00:00 2001 From: Kazuyuki Ashimura Date: Thu, 14 Sep 2017 07:41:29 +0900 Subject: [PATCH 142/464] add diff.html --- diff.html | 9758 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 9758 insertions(+) create mode 100644 diff.html diff --git a/diff.html b/diff.html new file mode 100644 index 00000000..c22818df --- /dev/null +++ b/diff.html @@ -0,0 +1,9758 @@ + + + + + + + + + + + Web of Things (WoT) Scripting API + + + + + + + + + + + + + + +
+

+Abstract +

+

+The + +Web +of +Things + +(WoT) +provides +layered +interoperability +between + +Things + +by +using +the + +WoT +Interface + +s. +

+

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

+

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

+
+
+

+Status +of +This +Document +

+

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

+

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

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

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

+
+

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

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

+

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

+

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

+

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

+
+ +
+

+ +1. + +Introduction +

+

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

+

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

+

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

+
+
+ +Note + +
+

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

+
+

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

+
+
+

+ +2. + +Use +Cases +

+

+ +This +section +is +non-normative. + +

+

+The +following +scripting +use +cases +are +covered +in +this +specification: +

+ +

+The +following +use +cases +are +being +considered +for +next +versions: +

+
    +
  • +Add, +remove +and +update +the +definition +of +a + +Property + +on +a +Thing +that +runs +in +the +same +the +WoT +Runtime. +
    • +
  • +Add, +remove +and +update +the +definition +of +an + +Action + +on +a +Thing +that +runs +in +the +same +the +WoT +Runtime. +
    • +
  • +Add, +remove +and +update +the +definition +of +an + +Event + +on +a +Thing +that +runs +in +the +same +the +WoT +Runtime. +
    • +
+
+
+

+ +3. + +The + + +WoT + + +object +

+

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

+
+
+ +Note + +
+

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

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

+The +algorithms +for +the +WoT +methods +will +be +specified +later. +

+
+
+

+ +3.1 + +The + + +discover() + + +method +

+

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

+
+

+ +3.1.1 + +The + + +ThingFilter + + +dictionary +

+

+The + + +ThingFilter + + +dictionary +that +represents +the +constraints +for +discovering + +Thing + +s +as +key-value +pairs. +

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

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

+

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

+

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

+
+
+ +Editor's +note + +
+

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

+
+
+
+ +Editor's +note + +
+

+The + + +ThingFilter + + +dictionary +may +be +extended +later +with +further +attributes. +

+
+
+
+

+ +3.1.2 + +The + + +DiscoveryMethod + + +enumeration +

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

+The + + +DiscoveryMethod + + +enumeration +represents +the +discovery +type +to +be +used: +

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

+ +3.2 + +The + + +consume() + + +method +

+

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

+
+
+

+ +3.3 + +The + + +expose() + + +method +

+

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

+
+
+ +Editor's +note + +
+

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

+
+
+

+ +3.3.1 + +The + + +ThingInit + + +dictionary +

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

+The + + +ThingInit + + +dictionary +contains +properties +to +initialize +a + +Thing +: +

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

+ +3.4 + +Examples +

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

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

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

+ +4. + +The + + +ConsumedThing + + +interface +

+

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

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

+Represents +a +local +proxy +object +of +the +remote + +Thing +. +

+
    +
  • +The + + +name + + +read-only +attribute +represents +the +name +of +the + +Thing +. +
    • +
  • +The + + +url + + +read-only +attribute +represents +the +URL +of +the + +Thing +. +
    • +
  • +The + + +description + + +attribute +read-only +attribute +represents +the +description +of +the + +Thing +. +
    +
    + +Editor's +note + +
    +

    +Parsing +and +exposing + +Thing +Description + +s +is +discussed +in + +Issue +38 +. +

    +
    +
    • +
+
+

+ +4.1 + +The + + +invokeAction() + + +method +

+

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

+
+
+

+ +4.2 + +The + + +setProperty() + + +method +

+

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

+
+
+

+ +4.3 + +The + + +getProperty() + + +method +

+

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

+
+
+

+ +4.4 + +The + + +addListener() + + +method +

+

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

+
+
+

+ +4.5 + +The + + +removeListener() + + +method +

+

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

+
+
+

+ +4.6 + +The + + +removeAllListeners() + + +method +

+

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

+
+
+

+ +4.7 + +The + + +observe() + + +method +

+

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

+
+
+ +Editor's +note + +
+

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

+
+
+
+

+ +4.8 + +The + + +ThingEventListener + + +callback +

+

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

+
+
+

+ +4.9 + +Events +

+

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

+
+

+ +4.9.1 + +The + + +PropertyChangeEvent + + +interface +

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

+The + + +data + + +attribute +represents +the +changed + +Property +. +

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

+The + + +name + + +> +attribute +represents +the + +Property + +name. +

+

+The + + +value + + +attribute +represents +the +new +value +of +the + +Property +. +

+
+
+
+

+ +4.9.2 + +The + + +ActionInvocationEvent + + +interface +

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

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

+
+
+ +4.9.2.1 + +The + + +ActionInvocationEventInit + + +dictionary +
+ +
+
+ +Editor's +note + +
+

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

+
+

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

+

+The + + +returnValue + + +attribute +represents +the +return +value +of +the + +Action +. +

+
+
+
+

+ +4.9.3 + +The + + +ThingDescriptionChangeEvent + + +interface +

+ +

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

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

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

+
+
+
+
+
+

+ +4.10 + +Examples +

+

+Below +a + + + +ConsumedThing + + + +interface +example +is +given. +

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

+ +5. + +The + + +ExposedThing + + +interface +

+

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

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

+ +5.1 + +The + + +ThingDescription + + +type +

+

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

+
+
+ +Note + +
+

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

+
+
+
+

+ +5.2 + +The + + +Request + + +interface +

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

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

+
    +
  • +The + + +type + + +attribute +represents +the +type +of +the +request +as +defined +in + + +RequestType + +. +
    • +
  • +The + + +from + + +attribute +represents +the +address +of +the +client +device +issuing +the +request. +The +type +of +the +address +(URL, +UUID +or +other) +is +defined +by +the + +Thing +Description +. +
    • +
  • +The + + +name + + +attribute +represents +the +name +of +the + +Property + +to +be +retrieved +or +updated, +or +the +name +of +the +invoked + +Action +, +or +the +event +name +to +be +observed. +
    • +
  • +The + + +options + + +attribute +represents +the +options +relevant +to +the +request +(e.g. +the +format +or +measurement +units +for +the +returned +value) +as +key-value +pairs. +The +exact +format +is +specified +by +the + +Thing +Description +. +
    • +
  • +The + + +data + + +attribute +represents +the +value +of +the + +Property +, +or +the +input +data +(arguments) +of +an + +Action +. +It +is +not +used +for +retrieve +requests +and +event +requests, +only +for + +Property + +update +and + +Action + +invocation +requests. +
    • +
+
+

+ +5.2.1 + +The + + +RequestType + + +enumeration +

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

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

    +
    +
    • +
+
+
+

+ +5.2.2 + +The + + +respond() + + +method +

+

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

+
+
+

+ +5.2.3 + +The + + +respondWithError() + + +method +

+

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

+
+
+
+

+ +5.3 + +The + + +RequestHandler + + +callback +

+

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

+
+
+

+ +5.4 + +The + + +addProperty() + + +method +

+

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

+
+

+ +5.4.1 + +The + + +ThingPropertyInit + + +dictionary +

+ +

+Represents +the + +Thing + + +Property + +description. +

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

+ +5.4.2 + +The + + +SemanticType + + +dictionary +

+
+ 
dictionary SemanticType {
+    DOMString name;
+    USVString context;
+};
+
+
+
+

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

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

+Semantic +type +examples +to +be +added. +

+
+
+
+
+

+ +5.5 + +The + + +removeProperty() + + +method +

+

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

+
+
+

+ +5.6 + +The + + +addAction() + + +method +

+

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

+
+

+ +5.6.1 + +The + + +ThingActionInit + + +dictionary +

+ +

+The + + +ThingActionInit + + +dictionary +describes +the +arguments +and +the +return +value. +

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

+ +5.7 + +The + + +removeAction() + + +method +

+

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

+
+
+

+ +5.8 + +The + + +addEvent() + + +method +

+

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

+
+

+ +5.8.1 + +The + + +ThingEventInit + + +dictionary +

+ +
    +
  • +The + + +name + + +attribute +represents +the +event +name. +
    • +
  • +The + + +semanticTypes + + +attribute +represent +a +list +of +semantic +type +annotations +attached +to +the +event. +
    • +
  • +The + + +dataDescription + + +attribute +represents +the +description +of +the +data +that +is +attached +to +the +event. +
    • +
+
+
+
+

+ +5.9 + +The + + +removeEvent() + + +method +

+

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

+
+
+

+ +5.10 + +The + + +onRetrieveProperty() + + +method +

+

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

+
+
+

+ +5.11 + +The + + +onUpdateProperty() + + +method +

+

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

+
+
+

+ +5.12 + +The + + +onInvokeAction() + + +method +

+

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

+
+
+

+ +5.13 + +The + + +onObserve() + + +method +

+

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

+
    +
  • + +request.name + +defines +the +name +of +the + +Property + +or + +Action + +or +event +to +be +observed. +
    • +
  • + +request.options.observeType + +is +of +type + + +RequestType + + +and +defines +whether +a + +Property + +change +or + +Action + +invocation +or +event +emitting +is +observed, +or +the +changes +to +the + +Thing +Description + +are +observed. +
    • +
  • + +request.options.subscribe + +is + +true + +if +subscription +is +turned +or +kept +being +turned +on, +and +it +is + +false + +when +subscription +is +turned +off. +
    • +
+
+
+

+ +5.14 + +The + + +register() + + +method +

+

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

+
+
+

+ +5.15 + +The + + +unregister() + + +method +

+

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

+
+
+

+ +5.16 + +The + + +start() + + +method +

+

+Start +serving +external +requests +for +the + +Thing +. +

+
+
+

+ +5.17 + +The + + +stop() + + +method +

+

+Stop +serving +external +requests +for +the + +Thing +. +

+
+
+

+ +5.18 + +The + + +emitEvent() + + +method +

+

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

+
+
+

+ +5.19 + +Events +supported +by +ExposedThing +

+

+The +following +default +events + +SHOULD + +be +supported +by + + +ExposedThing + + +implementations: +

+ +

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

+
+
+

+ +5.20 + +Examples +

+

+Below +some + + + +ExposedThing + + + +interface +examples +are +given. +

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

+ +6. + +Security +and +Privacy +

+
+
+ +Editor's +note + +
+

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

+
+
+
+

+ +7. + +Terminology +and +conventions +

+

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

+
+
+ +Note + +
+

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

+
+

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

+

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

+

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

+

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

+

+The +term + + +secure +context + + +is +defined +in +[ + + +WEBAPPSEC + + +]. +

+

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

+

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

+

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

+
+
+ +Note + +
+

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

+
+

+ + +Observable + +s + +are +proposed +to +be +included +in +ECMAScript. +

+

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

+

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

+
+
+

+ +8. + +Conformance +

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+
+
+

+ +A. + +Changes +

+

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

+
+
+

+ +B. + +Open +issues +

+

+The +following +problems +are +being +discussed +and +need +most +attention: +

+ +
+
+

+ +C. + +Acknowledgements +

+

+Special +thanks +to +former +editor +Johannes +Hund +(until +August +2017, +when +at +Siemens +AG) + +for +developing +this +specification. +Also, +the +editors +would +like +to +thank +Dave +Raggett, +Matthias +Kovatsch, +Michael +Koster +and +Michael +McCool +for +their +comments +and +guidance. +

+
+
+

+ +D. + +References +

+
+

+ +D.1 + +Normative +references +

+
+
+[ECMASCRIPT] +
+
+ + +ECMAScript +Language +Specification + +. +Ecma +International. +URL: + +https://tc39.github.io/ecma262/ + +
+
+[ENCODING] +
+
+ + +Encoding +Standard + +. +Anne +van +Kesteren. +WHATWG. +Living +Standard. +URL: + +https://encoding.spec.whatwg.org/ + +
+
+[HTML5] +
+
+ + +HTML5 + +. +Ian +Hickson; +Robin +Berjon; +Steve +Faulkner; +Travis +Leithead; +Erika +Doyle +Navara; +Theresa +O'Connor; +Silvia +Pfeiffer. +W3C. +28 +October +2014. +W3C +Recommendation. +URL: + +https://www.w3.org/TR/html5/ + +
+
+[JSON-LD] +
+
+ + +JSON-LD +1.0 + +. +Manu +Sporny; +Gregg +Kellogg; +Markus +Lanthaler. +W3C. +16 +January +2014. +W3C +Recommendation. +URL: + +https://www.w3.org/TR/json-ld/ + +
+
+[RFC2119] +
+
+ + +Key +words +for +use +in +RFCs +to +Indicate +Requirement +Levels + +. +S. +Bradner. +IETF. +March +1997. +Best +Current +Practice. +URL: + +https://tools.ietf.org/html/rfc2119 + +
+
+[TYPESCRIPT] +
+
+ + +TypeScript +Language +Specification + +. +Microsoft. +1 +October +2012. +URL: + +https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md + +
+
+[URL] +
+
+ + +URL +Standard + +. +Anne +van +Kesteren. +WHATWG. +Living +Standard. +URL: + +https://url.spec.whatwg.org/ + +
+
+[WEBAPPSEC] +
+
+ + +Secure +Contexts + +. +W3C. +17 +July +2015. +URL: + +https://w3c.github.io/webappsec/specs/powerfulfeatures + +
+
+[WEBIDL] +
+
+ + +Web +IDL + +. +Cameron +McCormack; +Boris +Zbarsky; +Tobie +Langel. +W3C. +15 +December +2016. +W3C +Editor's +Draft. +URL: + +https://heycam.github.io/webidl/ + +
+
+[WOT-ARCHITECTURE] +
+
+ + +Web +of +Things +Architecture + +. +W3C. +20 +August +2017. +URL: + +https://w3c.github.io/wot-architecture/ + +
+
+
+
+ + + + From 25f3ab0d1e90b2c4e5b825825adebe1c8755b7e1 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 18 Sep 2017 11:22:24 +0300 Subject: [PATCH 143/464] Fix #42. Update README.md with link to Contributions. Remove reference to TypeScript references. Signed-off-by: Zoltan Kis --- README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index ea4f45ef..57b1ac71 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,14 @@ # Specification 'Web of Things (WoT) Scripting API' -The main deliverable is the [WoT Scripting API Specification](./index.html). See the rendered version here: [http://w3c.github.io/wot-scripting-api/](http://w3c.github.io/wot-scripting-api/) +The main deliverable is the [WoT Scripting API Specification](./index.html). +See the rendered version here: [http://w3c.github.io/wot-scripting-api/](http://w3c.github.io/wot-scripting-api/) See the [rationale.md](./rationale.md) for explanation on API design choices. See the [primer.md](./primer/README.md) for explaining and illustrating the usage of the API. -See the [TypeScript definitions](./typescript-defs/wot.d.ts) for this API. - See the [applications/script-manager](./applications/script-manager/README.md) on the design of a Thing for script management. See the [applications/thing-directory](./applications/thing-directory/README.md) on the design of a Thing directory (reverse proxy) that would cache nearby Things, provide a single point of access and synchronize with the cached Things. -To make contributions, please provide pull-requests to the html file, see [github help](https://help.github.com/articles/using-pull-requests/). +To make contributions, please refer to [https://github.com/w3c/wotwg#contributing](https://github.com/w3c/wotwg#contributing). From 0683e2f38d4be6082e1747546af9702fde95be9f Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 18 Sep 2017 16:20:36 +0300 Subject: [PATCH 144/464] Move Overview.html and diff.html to releases/fpwd Signed-off-by: Zoltan Kis --- README.md | 6 ++++-- Overview.html => releases/fpwd/Overview.html | 0 diff.html => releases/fpwd/diff.html | 0 3 files changed, 4 insertions(+), 2 deletions(-) rename Overview.html => releases/fpwd/Overview.html (100%) rename diff.html => releases/fpwd/diff.html (100%) diff --git a/README.md b/README.md index 57b1ac71..32d026e9 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,9 @@ # Specification 'Web of Things (WoT) Scripting API' -The main deliverable is the [WoT Scripting API Specification](./index.html). -See the rendered version here: [http://w3c.github.io/wot-scripting-api/](http://w3c.github.io/wot-scripting-api/) +The main deliverable is the [WoT Scripting API Specification](./index.html). The [index.html](./index.html) file contains the latest Editors Draft. See the rendered version here: [http://w3c.github.io/wot-scripting-api/](http://w3c.github.io/wot-scripting-api/). + +Copies of the releases for [published versions](https://www.w3.org/TR/wot-scripting-api/) are found in [releases](./releases/). +The latest published version currently is the [First Public Working Draft](https://www.w3.org/TR/2017/WD-wot-scripting-api-20170914/). See the [rationale.md](./rationale.md) for explanation on API design choices. diff --git a/Overview.html b/releases/fpwd/Overview.html similarity index 100% rename from Overview.html rename to releases/fpwd/Overview.html diff --git a/diff.html b/releases/fpwd/diff.html similarity index 100% rename from diff.html rename to releases/fpwd/diff.html From 11e7b4916ee797d5e1dfcbefcd7c64a02157e0ed Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 18 Sep 2017 16:57:47 +0300 Subject: [PATCH 145/464] Add Johannes Hund as former editor Signed-off-by: Zoltan Kis --- index.html | 1 + 1 file changed, 1 insertion(+) diff --git a/index.html b/index.html index d8c11ff6..f460c27d 100644 --- a/index.html +++ b/index.html @@ -23,6 +23,7 @@ { name: "Zoltan Kis", company: "Intel", companyURL: "https://www.intel.com/" }, { name: "Kazuaki Nimura", company: "Fujitsu Ltd.", companyURL: "https://www.fujitsu.com/" }, { name: "Daniel Peintner", company: "Siemens AG", companyURL: "https://www.siemens.com/" }, + { name: "Johannes Hund", note: "Former Editor, when at Siemens AG" }, ], wg: "Web of Things Working Group", wgURI: "https://www.w3.org/WoT/WG/", From 1e55c09c25f01408bd51cdfbe2912f366ace0cb5 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 18 Sep 2017 17:00:38 +0300 Subject: [PATCH 146/464] Update CONTRIBUTING.md Signed-off-by: Zoltan Kis --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 388d1e4f..706c373d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,3 +22,5 @@ If you added a contributor by mistake, you can remove them in a comment with: If you are making a pull request on behalf of someone else but you had no part in designing the feature, you can remove yourself with the above syntax. + +For further guidelines, refer to [https://github.com/w3c/wotwg#contributing](https://github.com/w3c/wotwg#contributing). From c7faa3ea418b6b580268e5d8f160d3bae1ccf8fc Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 25 Sep 2017 13:27:19 +0300 Subject: [PATCH 147/464] Update use cases. Signed-off-by: Zoltan Kis --- index.html | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/index.html b/index.html index f460c27d..e1325eac 100644 --- a/index.html +++ b/index.html @@ -148,6 +148,9 @@
  • Discover Things by filters defined on Thing Descriptions
  • Discover Things by semantic filters.
  • Stop or suppress an ongoing discovery process.
    • +
  • + Optionally specify a timeout to the discovery process after which it is stopped/suppressed. +
  • Fetch and consume a TD of a remote Thing.
  • On a consumed Thing,
      @@ -172,9 +175,8 @@
    • -
  • Consume a thing.
    • -
  • Create and expose a local Thing based on a Thing Description.
    • -
  • Programmatically create and expose a local Thing. This may include the following use cases: +
  • Create and expose a local or remote Thing based on a Thing Description.
    • +
  • Programmatically create and expose a local or remote Thing. This may include the following use cases:
    • Create a local Thing.
    • Add a Property definition to the Thing.
      • @@ -186,6 +188,9 @@
    • Emit an Event, i.e. notify all listeners subscribed to that Event.
      • +
    • + Provide notifications for TD changes to clients subscribed to that. +
    • Register handlers for external requests:
      • to retrieve a Property value;
        • @@ -200,7 +205,7 @@
      • -
    • Register the Thing.
      • +
    • Register the Thing in order to make it discoverable and consumable.
    • Unregister the Thing.
    • Start the exposed Thing in order to process external requests.
    • Stop the exposed Thing.
      • @@ -210,13 +215,10 @@

      • - Add, remove and update the definition of a Property on a Thing that runs in the same the WoT Runtime. -
        • -
      • - Add, remove and update the definition of an Action on a Thing that runs in the same the WoT Runtime. + Attach an exposed Thing to proper protocol binding in order to access lower level functionality.
      • - Add, remove and update the definition of an Event on a Thing that runs in the same the WoT Runtime. + Create, start, stop, delete scripts in local or remote runtimes in order to implement Thing lifecycle management.
    • From eab93038cf9c6983846ba55631dbe4262b824266 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 25 Sep 2017 15:13:18 +0300 Subject: [PATCH 148/464] Update use cases based on comments in the Scripting call Signed-off-by: Zoltan Kis --- index.html | 30 +++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/index.html b/index.html index e1325eac..bedd2a60 100644 --- a/index.html +++ b/index.html @@ -140,6 +140,7 @@

    The following scripting use cases are covered in this specification:

    +

    Discovery

    • Discover all Things in the WoT network by sending a broadcast request.
    • Discover Things running in the local WoT Runtime.
      • @@ -151,7 +152,13 @@
    • Optionally specify a timeout to the discovery process after which it is stopped/suppressed.
      • -
    • Fetch and consume a TD of a remote Thing.
      • +
    +
    +

    Consuming a Thing

    +
      +
    • + Fetch and consume a TD of a Thing. The TD may be provided as a string, or as a file path, or specified by a URL. Consuming the Thing includes attaching to the protocol bindings in order to access lower level functionality. +
    • On a consumed Thing,
      • Get the value of a Property or set of properties.
        • @@ -175,7 +182,13 @@
      • -
    • Create and expose a local or remote Thing based on a Thing Description.
      • +
    +
    +

    Exposing a Thing

    +
      +
    • + Create and expose a Thing based on a Thing Description provided as a URL, or local file, or a string. Exposing the Thing includes attaching to the protocol bindings in order to access lower level functionality. +
    • Programmatically create and expose a local or remote Thing. This may include the following use cases:
      • Create a local Thing.
        • @@ -205,22 +218,25 @@
      • -
    • Register the Thing in order to make it discoverable and consumable.
      • -
    • Unregister the Thing.
      • +
    • Mark/unmark the Thing to be discoverable.
      • +
    • Mark/unmark the Thing to be consumable.
    • Start the exposed Thing in order to process external requests.
    • Stop the exposed Thing.
    +
    +

    Future use cases

    The following use cases are being considered for next versions:

      -
    • - Attach an exposed Thing to proper protocol binding in order to access lower level functionality. -
    • Create, start, stop, delete scripts in local or remote runtimes in order to implement Thing lifecycle management.
    +

    + Management use cases should be solved with exposing a special Thing that has an action for creating a Thing based on a TD. +

    +
    From acf18278b9ff4308ac7fbcbd9be641bd9b5b0a0c Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Mon, 9 Oct 2017 14:46:11 +0200 Subject: [PATCH 149/464] ThingFilter uses non-existing/wrong enum --- index.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index bedd2a60..fa2d9f23 100644 --- a/index.html +++ b/index.html @@ -272,7 +272,7 @@

    The ThingFilter dictionary

               dictionary ThingFilter {
-            (DiscoveryType or DOMString) method = "any";
+            (DiscoveryMethod or DOMString) method = "any";
             USVString url;
             Dictionary description;
           };
@@ -355,8 +355,8 @@ 
    The ThingInit dictionary
    >
 
     
     
    Examples
    
       
    -        let discoveryType = { method: "directory", url: "http://directory.wotservice.org" };
-        let subscription = wot.discover(discoveryType).subscribe(
+        let discoveryFilter = { method: "directory", url: "http://directory.wotservice.org" };
+        let subscription = wot.discover(discoveryFilter).subscribe(
           thing => { console.log("Found Thing " + thing.url); },
           error => { console.log("Discovery finished because an error: " + error.message); },
           () => { console.log("Discovery finished successfully");}

From 45276ba2af547580419993ee5801da70cfd68049 Mon Sep 17 00:00:00 2001
From: danielpeintner 
Date: Tue, 10 Oct 2017 10:47:11 +0200
Subject: [PATCH 150/464] remove unwanted bracket

---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index fa2d9f23..822065e4 100644
--- a/index.html
+++ b/index.html
@@ -501,7 +501,7 @@ 
    The PropertyChangeEventInit dictionary
    
                 any value;
             };
           
    
-          
    The name> attribute represents the Property name.
    
+          
    The name attribute represents the Property name.
    
           
    The value attribute represents the new value of the Property.
    From 8373e5829e59a779f1c3d9f602fda217c555213d Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Tue, 10 Oct 2017 10:58:08 +0200 Subject: [PATCH 151/464] flip order of bullet list item to match WebIDL order --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 822065e4..b6d0f9ca 100644 --- a/index.html +++ b/index.html @@ -570,10 +570,10 @@

    The ThingDescriptionChangeEventInit dictionary

    The name attribute represents the name of the Property, Action or event that has changed.
  • - The description attribute is defined for the addition and change methods, and represents the new description. + The data attribute provides the initialization data for the added or changed elements.
  • - The data attribute provides the initialization data for the added or changed elements. + The description attribute is defined for the addition and change methods, and represents the new description.
    • From 2ba27dc6efb8597a4da0ab38e283646870a12694 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Tue, 10 Oct 2017 11:29:43 +0200 Subject: [PATCH 152/464] change list item order to match WebIDL for ThingActionInit dictionary --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index b6d0f9ca..e7c14eb1 100644 --- a/index.html +++ b/index.html @@ -829,12 +829,12 @@

    The ThingActionInit dictionary

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

    From 7a1c1d04975916351668d13dcc8b2a9ae624caf8 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Tue, 10 Oct 2017 17:34:19 +0200 Subject: [PATCH 153/464] fix issue https://github.com/w3c/wot-scripting-api/issues/66 --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index e7c14eb1..d18c7d91 100644 --- a/index.html +++ b/index.html @@ -751,7 +751,7 @@

    The ThingPropertyInit dictionary

               dictionary ThingPropertyInit {
             DOMString name;
-            boolean configurable = true;
+            boolean configurable = false;
             boolean enumerable = true;
             boolean writable = true;
             sequence<SemanticType> semanticTypes;
@@ -765,7 +765,7 @@ 
    The ThingPropertyInit dictionary
    
             
  • The name attribute represents the name of the Property.
    • 
             
  • The value attribute represents the value of the Property.
    • 
             
  • 
-              The configurable attribute defines whether the Property can be deleted from the object and whether its properties can be changed. The default value is false.
+              The configurable attribute defines whether the Property can be deleted from the object and whether its type can be changed. The default value is false.
             
    • 
             
  • 
               The enumerable attribute defines whether the Property can be listed and iterated. The default value is true.

From 13612329b1da4ce032284f9b67eaa675ae7c6d9c Mon Sep 17 00:00:00 2001
From: Philippe Coval 
Date: Thu, 2 Nov 2017 17:15:08 +0100
Subject: [PATCH 154/464] Fix markdown images links

Currently HTML is escaped and images are not displayed at:
https://w3c.github.io/wot-scripting-api/primer/

Bug: https://github.com/w3c/wot-scripting-api/issues/79
Signed-off-by: Philippe Coval 
---
 primer/README.md | 36 ++++++++++++++++++------------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/primer/README.md b/primer/README.md
index 182ebc42..a05c12df 100644
--- a/primer/README.md
+++ b/primer/README.md
@@ -15,7 +15,7 @@ ExposedThing controls building block of WoT and manages life cycle of WoT Server
 Given a script that has ExposedThing command tied with device access function, ExposedThing generate a [WoT Thing Description
 (TD)](https://w3c.github.io/wot-thing-description/) and expose the server API.
 
-Fig.1
+![Fig.1](./images/Fig1.png)
 
 
 The followings shows the sequence of this figure.
@@ -28,41 +28,41 @@ The followings shows the sequence of this figure.
 
 At the runtime, when a WoTAPI is called,the callback is executed to control the Thing.
 
-Fig.2
+![Fig.2](./images/Fig2.png)
 
 #### (C) Runtime provisioning: add thing
 
 Given another script that has ExposedThing command tied with device access function, ExposedThing generate a TD and expose the server API.
 
-Fig.3
+![Fig.3](./images/Fig3.png)
 
 #### (D) Runtime: unregister thing
 
 A script that has an unregister thing can unregister the exposed thing, the callback function, and the TD.
 
-Fig.4
+![Fig.4](./images/Fig4.png)
 
 #### (E) Expose thing with semantics
 
 A script that comes with SemanticType generates a TD with semantic expression. It can be searched by accessing TD repository.
 
-Fig.5
+![Fig.5](./images/Fig5.png)
 
 #### (F) Runtime provisioning: Set permission to WoTAPI
 
 Generate a security token using e.g. IETF ACE and set permission to WoTAPI. Check the security token when WoTAPI is called.
 
-Fig.17
+![Fig.17](./images/Fig17.png)
 
 ### 1-1\. Using Expose Thing
 
 ExposedThing can be used in any layers i.e. Client, Cloud/Server, Gateway/Edge, and Device.
 
-Fig.6
+![Fig.6](./images/Fig6.png)
 
 ExposedThing in various layers and combinations.
 
-Fig.7
+![Fig.7](./images/Fig7.png)
 
 ### 2\. ConsumedThing in WoT Client
 
@@ -72,7 +72,7 @@ ConsumedThing controls building blocks of WoT and manages life cycle of WoT Clie
 
 Search a device initiates a discovery and set up a ConsumedThing API to use.
 
-Fig.8
+![Fig.8](./images/Fig8.png)
 
 The followings shows the sequence of this figure.
 (a) Search a device from an application using discovery API.
    
@@ -86,28 +86,28 @@ The followings shows the sequence of this figure.
 
 Application access the device with method call. ConsumedThing interprit the access as WoTAPI call.
 
-Fig.9
+![Fig.9](./images/Fig9.png)
 
 #### (C) Runtime provisioning: search and use another thing
 
 Search another device initiates a discovery and set up the Thing API to use. The sequence is the same with (a).
 
-Fig.10
+![Fig.10](./images/Fig10.png)
 
 ### 2-1\. Using Consumed Thing
 
 ConsumedThing can be used in any layers.
 
-Fig.11
+![Fig.11](./images/Fig11.png)
 
 ConsumedThing in various layers and combinations.
 
-Fig.12
+![Fig.12](./images/Fig12.png)
 
 ### 2-2\. Example: WoT Server and WoT Client
 A use case that uses a WoT Server and a WoT Client is shown here i.e. An electronic appliance with WoT server is controlled by a remote controller with WoT client.
 
-Fig.13
+![Fig.13](./images/Fig13.png)
 
 The followings shows the sequence of this Figure.
 (1) Script has ExposedThing call with callback function that has access method to a LED lamp.
    
@@ -142,7 +142,7 @@ The followings shows the sequence of how WoT servient works for the provisioning
 (iv) ConsumedThing expose Client API.
    
 (b) WoTAPI of Server receives a command for turn on. Then callback function registerd to ExposedThing is called. If the LED lamp is connected to Client, Protocol Binding interprit the command in the callback to appropriate WoTAPI command. If the LED lamp is connected to Legacy Communication, the callback function issues the legacy communication command to control the LED lamp.
 
-Fig.14
+![Fig.14](./images/Fig14.png)
 
 ### 3-2\. Event handling
 
@@ -154,7 +154,7 @@ The followings shows the sequence of how WoT servient works for the events handl
 - (g) Generate another event: Transform the event and issue as another event through ExposedThing/WoTAPI. TD#1 has definition of the event defined by the device and TD#2 has definition of new event that is transformed from the original event.
 - (h) Make linked data: Save the event/events and allow to access by a property call through WoTAPI. TD#2 has a property definition that returns the event/events data based on an URI call.
 
-Fig.18
+![Fig.18](./images/Fig18.png)
 
 ### 3-3\. Example: Voting
 A use case that uses WoT Servients and a WoT Client is shown here. WoT servient #3 maybe on the cloud provide devices shadow and consolidate devices and expose a service. A script for Thing to Thing (T2T) service provides two functions:
@@ -167,7 +167,7 @@ Four types of scripts are placed in the application layers:
 - Thing to thing service to WoT Servient #3
 - Voting script to WoT Client
 
-Fig.15
+![Fig.15](./images/Fig15.png)
 
 The followings shows the sequence of the fugure.
 
@@ -232,4 +232,4 @@ WoT Server are used in devices.
 WoT Servient are used in gateways / edges and on the Cloud service.
 WoT Client are used in clients.
 
-Fig.16
+![Fig.16](./images/Fig16.png)

From 48bb8799939f8bce36536baa52487a00f20d62d1 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Mon, 29 Jan 2018 13:53:59 +0200
Subject: [PATCH 155/464] Update the API according to discussion in #82 and #78

Signed-off-by: Zoltan Kis 
---
 index.html | 384 +++++++++++++++++++++--------------------------------
 1 file changed, 150 insertions(+), 234 deletions(-)

diff --git a/index.html b/index.html
index d18c7d91..775a64fa 100644
--- a/index.html
+++ b/index.html
@@ -100,7 +100,7 @@
       The Web of Things (WoT) provides layered interoperability between Things by using the WoT Interfaces.
     
    
     
    
-      This specification describes a programming interface representing the WoT Interface that allows scripts run on a Thing to discover and consume (retrieve) other Things and to expose Things characterized by properties, Actions and Events.
+      This specification describes a programming interface representing the WoT Interface that allows scripts run on a Thing to discover and consume (retrieve) other Things and to expose Things characterized by  WoT interactions, i.e. Properties, Actions and Events.
     
    
     
    
       Scripting is an optional "convenience" building block in WoT and it is typically used in gateways that are able to run a WoT Runtime and script management, providing a convenient way to extend WoT support to new types of endpoints and implement WoT applications like Thing Directory.
@@ -126,7 +126,7 @@
       By consuming a TD, a client Thing creates a runtime resource model that allows accessing the properties, Actions and Events exposed by the server Thing.
     
    
     
    
-      Exposing a Thing requires defining a Thing Description and instantiating a software stack needed to serve requests for accessing the exposed properties, Actions and Events. This specification describes how to expose and consume Things by a script.
+      Exposing a Thing requires defining a Thing Description (TD) and instantiating a software stack needed to serve requests for accessing the exposed properties, Actions and Events. Defining a This specification describes how to expose and consume Things by a script.
     
    
     
    
       Typically scripts are meant to be used on devices able to provide resources (with a WoT interface) for managing (installing, updating, running) scripts, such as bridges or gateways that expose and control simpler devices as WoT Things.
@@ -251,18 +251,86 @@ 
    The WoT object
    
       // [NamespaceObject]
       interface WoT {
         Observable<ConsumedThing> discover(optional ThingFilter filter);
-        Promise<ConsumedThing> consume(USVString url);
-        Promise<ExposedThing> expose(ThingInit init);
+        Promise<ThingDescription> fetch(USVString url);
+        ConsumedThing consume(ThingDescription td);
+        ExposedThing expose(ThingTemplate init);
       };
+      typedef USVString ThingDescription;

    • The algorithms for the WoT methods will be specified later.

    +
    +

    The ThingDescription type

    +

    + WoT provides a unified representation for data exchange between Things, standardized in the [Wot Things Description](https://w3c.github.io/wot-thing-description/) specification. +

    +

    + In this version of the API, Thing Descriptions are represented as opaque strings, denoting a serialized form, for instance JSON or JSON-LD. See [Issue 38](https://github.com/w3c/wot-scripting-api/issues/38) and [Issue 45](https://github.com/w3c/wot-scripting-api/issues/45). + Parsing and composing Thing Descriptions is left for external libraries until standardized here. +

    +
    + +
    +

    The ThingTemplate dictionary

    + 
    +        dictionary ThingTemplate {
+            DOMString name;
+            sequence<SemanticType> semanticTypes;
+            sequence<SemanticMetadata> metadata;
+        };
+
    +

    The ThingTemplate dictionary contains properties to initialize a Thing: +

      +
    • The name attribute represents the user given name of the Thing.
      • +
    • The semanticTypes attribute represents an array of SemanticType objects that describe the types supported by the Thing.
      • +
    • The metadata nullable attribute represents the metadata fields to be added to the Thing Description of the Thing.
      • +
    +

    +
    + +
    +

    The SemanticType dictionary

    + 
    +        dictionary SemanticType {
+            DOMString name;
+            USVString context;
+            DOMString prefix;
+        };
+
    +

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

      +
    • The name attribute represents the name of the semantic type in the given context.
      • +
    • The context attribute represents an URL link to the context of the semantic classification.
      • +
    +

    +

    + Semantic type examples to be added. +

    +
    + +
    +

    The SemanticMetadata dictionary

    + 
    +        dictionary SemanticMetadata {
+            SemanticType type;
+            any          value;
+        };
+
    +

    The SemanticMetadata dictionary describes the semantic metadata elements attached to a Thing: +

      +
    • The type attribute represents the semantic type name defined by a SemanticType object.
      • +
    • The value attribute represents the metadata value.
      • +
    +

    +
    +

    The discover() method

    - Starts the discovery process that will provide ConsumedThing objects that match the optional argument ThingFilter. When the argument is not provided, starts the widest discovery the Thing Description and Protocol Bindings allow. + Starts the discovery process that will provide ConsumedThing objects that match the optional argument ThingFilter. When the argument is not provided, starts the widest discovery the Thing Description and Protocol Bindings allow and support. Returns an [Observable](https://github.com/tc39/proposal-observable) object that can be subscribed and unsubscribed to.

    @@ -321,37 +389,23 @@

    The DiscoveryMethod enumeration

    +

    The fetch() method

    +

    + Accepts an url argument and returns a Promise that resolves with a ThingDescription. +

    +
    +

    The consume() method

    - Accepts an url argument and returns a Promise of a ConsumedThing. + Accepts an td argument of type ThingDescription and returns a ConsumedThing object instantiated based on that description.

    The expose() method

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

    -

    - The reason ExposedThings are created by a factory method instead of a constructor is that an ExposedThing may be created in the local WoT Runtime or in a remote runtime. Even though currently only local creation is supported, the method is designed with this possible future compatibility in mind. + Accepts an init argument of type ThingTemplate and returns an ExposedThing object, locally created based on the provided initialization parameters.

    -
    -

    The ThingInit dictionary

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

    The ThingInit dictionary contains properties to initialize a Thing: -

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

    -
    -
    +

    Examples

    @@ -400,17 +454,17 @@ 
    The ConsumedThing interface
    
     
           interface ConsumedThing {
         readonly attribute DOMString name;
-        readonly attribute USVString url;
         readonly attribute ThingDescription description;
         Promise<any> invokeAction(DOMString name, any parameters);
-        Promise<void> setProperty(DOMString name, any value);
-        Promise<any> getProperty(DOMString name);
-        ConsumedThing addListener(DOMString eventName, ThingEventListener listener);
-        ConsumedThing removeListener(DOMString eventName, ThingEventListener listener);
-        ConsumedThing removeAllListeners(optional DOMString eventName);
-        Observable observe(DOMString name, RequestType requestType);
+        Promise<void> writeProperty(DOMString name, any value);
+        Promise<any> readProperty(DOMString name);
+        Observable onEvent(DOMString name);
+        Observable onPropertyChange(DOMString name);
+        Observable onTDChange();
       };
-      callback ThingEventListener = void (Event event);
+      callback ThingEventListener = void (ThingEvent event);
+      callback PropertyChangeListener = void (PropertyChangeEvent change);
+      callback TDChangeListener = void (TDChangeEvent td);
     
    
     
    
       Represents a local proxy object of the remote Thing.
@@ -431,53 +485,58 @@ 
    The ConsumedThing interface
    -

    The setProperty() method

    +

    The writeProperty() method

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

    -

    The getProperty() method

    +

    The readProperty() method

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

    -

    The addListener() method

    +

    The onEvent() method

    - Adds the listener provided in the argument listener to the Event name provided in the argument eventName. + Returns an Observable for the Property, Event or Action specified in the name argument, allowing subscribing and unsubscribing to notifications. Takes an argument of type ThingEventListener.

    -

    The removeListener() method

    +

    The onPropertyChange() method

    - Removes a listener from the Event identified by the provided eventName and listener argument. + Returns an Observable for the Property specified in the name argument, allowing subscribing and unsubscribing to notifications. Takes an argument of type PropertyChangeListener.

    -

    The removeAllListeners() method

    +

    The onTDChange() method

    - Removes all listeners for the Event provided by the eventName optional argument, or if that was not provided, then removes all listeners from all Events. + Returns an Observable, allowing subscribing and unsubscribing to notifications to the Thing Description. Takes no arguments.

    -

    The observe() method

    +
    +

    The ThingEventListener callback

    - Returns an Observable for the Property, Event or Action specified in the name argument, allowing subscribing and unsubscribing to notifications. The requestType specifies whether a Property, an Event or an Action is observed. + A function called with an ThingEvent object when an event is emitted.

    -

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

    + +
    +

    The PropertyChangeListener callback

    +

    + A function called with an ThingProperty object.

    -
    -

    The ThingEventListener callback

    +
    +

    The TDChangeListener callback

    - A function called with an Event object when an event is emitted. + A function called with one optional argument of type ThingDescription.

    -

    Events

    +

    Thing Events

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

    @@ -537,21 +596,21 @@

    The ActionInvocationEventInit dictionary

    -
    -

    The ThingDescriptionChangeEvent interface

    +
    +

    The TDChangeEvent interface

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

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

    -
    -

    The ThingDescriptionChangeEventInit dictionary

    +
    +

    The TDChangeEventInit dictionary

    -            dictionary ThingDescriptionChangeEventInit {
+            dictionary TDChangeEventInit {
                 TDChangeType type;
                 TDChangeMethod method;
                 DOMString name;
@@ -605,8 +664,8 @@ 
    The TDChangeData type
    
               Represents the new description of the changed element. Depending on the change type, it can be either a ThingPropertyInit, ThingActionInit, or ThingEventInit.
    -
    -
    +
    +
    @@ -618,7 +677,7 @@

    Examples

    wot.consume("http://mmyservice.org/mySensor").then( thing => { console.log("Thing " + thing.name + " has been consumed."); console.log("{ " + JSON.serialize(thing) + " }"); - thing.addListener("onchange", function(event) { + thing.onPropertyChange("temperature", function(event) { if (event instanceof PropertyChangeEvent) { console.log("Property " + event.name + " value has changed to " + event.value); } @@ -637,108 +696,50 @@

    The ExposedThing interface

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

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

    The ThingDescription type

    +

    The start() method

    - WoT provides a unified representation for data exchange between Things, standardized in the [Wot Things Description](https://w3c.github.io/wot-thing-description/) specification. + Start serving external requests for the Thing.

    -

    - In this version of the API, Thing Descriptions are represented as opaque strings, denoting a serialized form, for instance JSON or JSON-LD. See [Issue 38](https://github.com/w3c/wot-scripting-api/issues/38) and [Issue 45](https://github.com/w3c/wot-scripting-api/issues/45). - Parsing and composing Thing Descriptions is left for external libraries until standardized here. +

    + +

    The stop() method

    +

    + Stop serving external requests for the Thing.

    -
    -

    The Request interface

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

    The register() method

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

      -
    • - The type attribute represents the type of the request as defined in RequestType. -
      • -
    • - The from attribute represents the address of the client device issuing the request. The type of the address (URL, UUID or other) is defined by the Thing Description. -
      • -
    • - The name attribute represents the name of the Property to be retrieved or updated, or the name of the invoked Action, or the event name to be observed. -
      • -
    • - The options attribute represents the options relevant to the request (e.g. the format or measurement units for the returned value) as key-value pairs. The exact format is specified by the Thing Description. -
      • -
    • - The data attribute represents the value of the Property, or the input data (arguments) of an Action. It is not used for retrieve requests and event requests, only for Property update and Action invocation requests. -
      • -
    + Generates the Thing Description given the properties, Actions and Event defined for this object. If a directory argument is given, make a request to register the Thing Description with the given WoT repository by invoking its register Action.

    -
    -

    The RequestType enumeration

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

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

      -
      • -
    -
    -

    The respond() method

    -

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

    -
    -

    The respondWithError() method

    -

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

    -
    -
    +
    + +

    The unregister() method

    +

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

    +
    -
    -

    The RequestHandler callback

    +

    The emitEvent() method

    - Callback function for handling interaction requests. Receives an argument request of type Request and should return an object or value that is used by Protocol Bindings to reply to the request. The returned type is defined by the Thing Description. + Emits an the event initialized with the event name specified by the eventName argument and data specified by the payload argument.

    @@ -782,26 +783,6 @@

    The ThingPropertyInit dictionary

    - -
    -

    The SemanticType dictionary

    - 
    -          dictionary SemanticType {
-            DOMString name;
-            USVString context;
-          };
-
    -

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

      -
    • The name attribute represents the name of the semantic type in the given context.
      • -
    • The context attribute represents an URL link to the context of the semantic classification.
      • -
    -

    -

    - Semantic type examples to be added. -

    -

    The removeProperty() method

    @@ -873,71 +854,6 @@

    The ThingEventInit dictionary

    -

    The onRetrieveProperty() method

    -

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

    -
    - -

    The onUpdateProperty() method

    -

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

    -
    - -

    The onInvokeAction() method

    -

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

    -
    - -

    The onObserve() method

    -

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

      -
    • - request.name defines the name of the Property or Action or event to be observed. -
      • -
    • - request.options.observeType is of type RequestType and defines whether a Property change or Action invocation or event emitting is observed, or the changes to the Thing Description are observed. -
      • -
    • - request.options.subscribe is true if subscription is turned or kept being turned on, and it is false when subscription is turned off. -
      • -
    -

    -
    - -

    The register() method

    -

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

    -
    - -

    The unregister() method

    -

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

    -
    - -

    The start() method

    -

    - Start serving external requests for the Thing. -

    -
    - -

    The stop() method

    -

    - Stop serving external requests for the Thing. -

    -
    - -

    The emitEvent() method

    -

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

    -
    -

    Events supported by ExposedThing

    @@ -945,7 +861,7 @@

    Events supported by ExposedThing

    From a814c2b20e19640366cb2b89795f73123b45a0b5 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Tue, 30 Jan 2018 14:06:51 +0200 Subject: [PATCH 156/464] Update use cases. Add callback types to Observables. Signed-off-by: Zoltan Kis --- index.html | 84 ++++++++++++++++++++++-------------------------------- 1 file changed, 34 insertions(+), 50 deletions(-) diff --git a/index.html b/index.html index 775a64fa..24ec9be1 100644 --- a/index.html +++ b/index.html @@ -157,29 +157,16 @@

    Consuming a Thing

    • - Fetch and consume a TD of a Thing. The TD may be provided as a string, or as a file path, or specified by a URL. Consuming the Thing includes attaching to the protocol bindings in order to access lower level functionality. + Fetch and consume a TD of a Thing. The TD may be provided in a string serialized format, or specified by a URL. Consuming the Thing includes parsing the TD and attaching to the protocol bindings in order to access lower level functionality.
    • On a consumed Thing,
    @@ -187,41 +174,38 @@

    Exposing a Thing

    • - Create and expose a Thing based on a Thing Description provided as a URL, or local file, or a string. Exposing the Thing includes attaching to the protocol bindings in order to access lower level functionality. + Exposing the Thing includes attaching to the protocol bindings in order to access lower level functionality. +
      • > +
    • + Create a local ExposedThing to be exposed, based on a Thing Description provided as a URL, or a in string serialized format, or out of a template or an existing ConsumedThing object.
      • +
    • Add a Property definition to the Thing.
      • +
    • Add an Event definition to the Thing.
      • +
    • Add an Action definition to the Thing.
      • +
    • Attach semantic information to an Action
      • +
    • Attach semantic information to a Property
      • +
    • Attach semantic information to an Event
      • +
    • + Emit an Event, i.e. notify all listeners subscribed to that Event.
      • -
    • Programmatically create and expose a local or remote Thing. This may include the following use cases: -
        -
      • Create a local Thing.
        • -
      • Add a Property definition to the Thing.
        • -
      • Add an Event definition to the Thing.
        • -
      • Add an Action definition to the Thing.
        • -
      • Attach semantic information to an Action
        • -
      • Attach semantic information to a Property
        • -
      • Attach semantic information to an Event
        • -
      • - Emit an Event, i.e. notify all listeners subscribed to that Event. -
        • -
      • - Provide notifications for TD changes to clients subscribed to that. -
        • -
      • Register handlers for external requests: -
          -
        • to retrieve a Property value;
          • -
        • to update a Property value;
          • -
        • - to run an Action: take the parameters from the request, execute the defined action, and return the result; -
          • -
        • to add a listener to an Event;
          • -
        • to remove an Event listener.
          • -
        • to fetch the Thing Description;
          • -
        -
        • -
      +
    • + Provide notifications for TD changes to clients subscribed to that.
    • Mark/unmark the Thing to be discoverable.
    • Mark/unmark the Thing to be consumable.
    • Start the exposed Thing in order to process external requests.
    • Stop the exposed Thing.
      • +
    • Register handlers for external requests: +
        +
      • to retrieve a Property value;
        • +
      • to update a Property value;
        • +
      • + to run an Action: take the parameters from the request, execute the defined action, and return the result; +
        • +
      • to add a listener to an Event;
        • +
      • to remove an Event listener.
        • +
      • to fetch the Thing Description;
        • +
      +

    Future use cases

    @@ -253,7 +237,7 @@

    The WoT object

    Observable<ConsumedThing> discover(optional ThingFilter filter); Promise<ThingDescription> fetch(USVString url); ConsumedThing consume(ThingDescription td); - ExposedThing expose(ThingTemplate init); + ExposedThing expose(optional Dictionary template); }; typedef USVString ThingDescription; @@ -458,9 +442,9 @@

    The ConsumedThing interface

    Promise<any> invokeAction(DOMString name, any parameters); Promise<void> writeProperty(DOMString name, any value); Promise<any> readProperty(DOMString name); - Observable onEvent(DOMString name); - Observable onPropertyChange(DOMString name); - Observable onTDChange(); + Observable<ThingEventListener> onEvent(DOMString name); + Observable<PropertyChangeListener> onPropertyChange(DOMString name); + Observable<TDChangeListener> onTDChange(); }; callback ThingEventListener = void (ThingEvent event); callback PropertyChangeListener = void (PropertyChangeEvent change); From b18f94954170d200005a01ff92b032de8d0a0443 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Tue, 30 Jan 2018 14:37:00 +0200 Subject: [PATCH 157/464] Change expose() to produce(), to reflect creation, not exposure of ExposedThings. See also #64. Signed-off-by: Zoltan Kis --- index.html | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/index.html b/index.html index 24ec9be1..70e7a244 100644 --- a/index.html +++ b/index.html @@ -177,7 +177,7 @@ Exposing the Thing includes attaching to the protocol bindings in order to access lower level functionality. >
  • - Create a local ExposedThing to be exposed, based on a Thing Description provided as a URL, or a in string serialized format, or out of a template or an existing ConsumedThing object.
    • + Create a local ExposedThing to be exposed, based on a Thing Description provided in string serialized format, or out of a template or an existing ConsumedThing object.
  • Add a Property definition to the Thing.
  • Add an Event definition to the Thing.
  • Add an Action definition to the Thing.
    • @@ -237,9 +237,10 @@

    The WoT object

    Observable<ConsumedThing> discover(optional ThingFilter filter); Promise<ThingDescription> fetch(USVString url); ConsumedThing consume(ThingDescription td); - ExposedThing expose(optional Dictionary template); + ExposedThing produce(optional ThingModel model); }; typedef USVString ThingDescription; + typedef (ThingTemplate or ThingDescription or ConsumedThing) ThingModel;

    @@ -249,7 +250,7 @@

    The WoT object

    The ThingDescription type

    - WoT provides a unified representation for data exchange between Things, standardized in the [Wot Things Description](https://w3c.github.io/wot-thing-description/) specification. + Representation of the Thing Description, a unified representation for data exchange between Things, standardized in the [Wot Things Description](https://w3c.github.io/wot-thing-description/) specification.

    In this version of the API, Thing Descriptions are represented as opaque strings, denoting a serialized form, for instance JSON or JSON-LD. See [Issue 38](https://github.com/w3c/wot-scripting-api/issues/38) and [Issue 45](https://github.com/w3c/wot-scripting-api/issues/45). @@ -287,8 +288,15 @@

    The SemanticType dictionary

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

      -
    • The name attribute represents the name of the semantic type in the given context.
      • -
    • The context attribute represents an URL link to the context of the semantic classification.
      • +
    • + The name attribute represents the name of the semantic type in the given context. +
      • +
    • + The context attribute represents an URL link to the context of the semantic classification. +
      • +
    • + The prefix attribute represents a short prefix associated with a context. +

    @@ -306,7 +314,9 @@

    The SemanticMetadata dictionary

    The SemanticMetadata dictionary describes the semantic metadata elements attached to a Thing:

      -
    • The type attribute represents the semantic type name defined by a SemanticType object.
      • +
    • + The type attribute represents the semantic type name defined by a SemanticType object. +
    • The value attribute represents the metadata value.

    From abe57145f2d956073ddf40c4f202848541cb6524 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 31 Jan 2018 13:53:38 +0200 Subject: [PATCH 158/464] Update the WoT API and the definitions; add SemanticAnnotations, ValueDefinition, request handlers for ExposedThing Signed-off-by: Zoltan Kis --- index.html | 446 +++++++++++++++++++++-------------------------------- 1 file changed, 173 insertions(+), 273 deletions(-) diff --git a/index.html b/index.html index 70e7a244..5e95b077 100644 --- a/index.html +++ b/index.html @@ -210,11 +210,11 @@

    Future use cases

    - The following use cases are being considered for next versions: + The following use cases are being considered out of scope for this version:

    • - Create, start, stop, delete scripts in local or remote runtimes in order to implement Thing lifecycle management. + Deploy, start, stop, delete scripts in local or remote runtimes in order to implement Thing lifecycle management.

    @@ -247,85 +247,10 @@

    The WoT object

    The algorithms for the WoT methods will be specified later.

    -
    -

    The ThingDescription type

    -

    - Representation of the Thing Description, a unified representation for data exchange between Things, standardized in the [Wot Things Description](https://w3c.github.io/wot-thing-description/) specification. -

    -

    - In this version of the API, Thing Descriptions are represented as opaque strings, denoting a serialized form, for instance JSON or JSON-LD. See [Issue 38](https://github.com/w3c/wot-scripting-api/issues/38) and [Issue 45](https://github.com/w3c/wot-scripting-api/issues/45). - Parsing and composing Thing Descriptions is left for external libraries until standardized here. -

    -
    - -
    -

    The ThingTemplate dictionary

    - 
    -        dictionary ThingTemplate {
-            DOMString name;
-            sequence<SemanticType> semanticTypes;
-            sequence<SemanticMetadata> metadata;
-        };
-
    -

    The ThingTemplate dictionary contains properties to initialize a Thing: -

      -
    • The name attribute represents the user given name of the Thing.
      • -
    • The semanticTypes attribute represents an array of SemanticType objects that describe the types supported by the Thing.
      • -
    • The metadata nullable attribute represents the metadata fields to be added to the Thing Description of the Thing.
      • -
    -

    -
    - -
    -

    The SemanticType dictionary

    - 
    -        dictionary SemanticType {
-            DOMString name;
-            USVString context;
-            DOMString prefix;
-        };
-
    -

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

      -
    • - The name attribute represents the name of the semantic type in the given context. -
      • -
    • - The context attribute represents an URL link to the context of the semantic classification. -
      • -
    • - The prefix attribute represents a short prefix associated with a context. -
      • -
    -

    -

    - Semantic type examples to be added. -

    -
    - -
    -

    The SemanticMetadata dictionary

    - 
    -        dictionary SemanticMetadata {
-            SemanticType type;
-            any          value;
-        };
-
    -

    The SemanticMetadata dictionary describes the semantic metadata elements attached to a Thing: -

      -
    • - The type attribute represents the semantic type name defined by a SemanticType object. -
      • -
    • The value attribute represents the metadata value.
      • -
    -

    -
    -

    The discover() method

    Starts the discovery process that will provide ConsumedThing objects that match the optional argument ThingFilter. When the argument is not provided, starts the widest discovery the Thing Description and Protocol Bindings allow and support. - Returns an [Observable](https://github.com/tc39/proposal-observable) object that can be subscribed and unsubscribed to. + Returns an [Observable](https://github.com/tc39/proposal-observable) object that can be subscribed to and unsubscribed from.

    The ThingFilter dictionary

    @@ -389,17 +314,116 @@

    The DiscoveryMethod enumeration

    +
    +

    The ThingDescription type

    +

    + Representation of the Thing Description, a unified representation for data exchange between Things, standardized in the [Wot Things Description](https://w3c.github.io/wot-thing-description/) specification. +

    +

    + In this version of the API, Thing Descriptions are represented as opaque strings, denoting a serialized form, for instance JSON or JSON-LD. See [Issue 38](https://github.com/w3c/wot-scripting-api/issues/38) and [Issue 45](https://github.com/w3c/wot-scripting-api/issues/45). + Parsing and composing Thing Descriptions is left for external libraries until standardized here. +

    +
    +

    The consume() method

    Accepts an td argument of type ThingDescription and returns a ConsumedThing object instantiated based on that description.

    -

    The expose() method

    +

    The produce() method

    - Accepts an init argument of type ThingTemplate and returns an ExposedThing object, locally created based on the provided initialization parameters. + Accepts an optional model argument of type ThingModel and returns an ExposedThing object, locally created based on the provided initialization parameters.

    -
    +
    + +
    +

    The ThingModel type

    +

    + A Thing model is used for producing a new ExposedThing and can be either a ThingTemplate, or a ThingDescription, or a ConsumedThing. +

    +
    + +
    +

    The SemanticAnnotations dictionary

    +

    + A dictionary that provides the semantic types and semantic metadata. +

    + 
    +        dictionary SemanticAnnotations {
+            sequence<SemanticType> semanticTypes;
+            sequence<SemanticMetadata> metadata;
+        };
+
    +
    + +
    +

    The SemanticType dictionary

    + 
    +        dictionary SemanticType {
+            DOMString name;
+            USVString context;
+            DOMString prefix;
+        };
+
    +

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

      +
    • + The name attribute represents the name of the semantic type in the given context. +
      • +
    • + The context attribute represents an URL link to the context of the semantic classification. +
      • +
    • + The prefix attribute represents a short prefix associated with a context. +
      • +
    +

    +

    + Semantic type examples to be added. +

    +
    + +
    +

    The SemanticMetadata dictionary

    + 
    +        dictionary SemanticMetadata {
+            SemanticType type;
+            any          value;
+        };
+
    +

    The SemanticMetadata dictionary describes a pair of semantic type and value: +

      +
    • + The type attribute represents the semantic type name defined by a SemanticType object. +
      • +
    • The value attribute represents the metadata value.
      • +
    +

    +
    + +
    +

    The ThingTemplate dictionary

    +

    + A Thing Template is a dictionary that provides the semantic types and semantic metadata at the ExposedThing description's root level. +

    + 
    +        dictionary ThingTemplate: SemanticAnnotations {
+            DOMString name;
+        };
+
    +

    The ThingTemplate dictionary extends SemanticAnnotations and contains properties to initialize a Thing: +

      +
    • + The name attribute represents the user given name of the Thing. +
      • +
    +

    +

    + Support for configuration and security data might be added later. +

    +

    Examples

    @@ -448,7 +472,7 @@ 
    The ConsumedThing interface
    
     
           interface ConsumedThing {
         readonly attribute DOMString name;
-        readonly attribute ThingDescription description;
+        readonly attribute ThingDescription td;
         Promise<any> invokeAction(DOMString name, any parameters);
         Promise<void> writeProperty(DOMString name, any value);
         Promise<any> readProperty(DOMString name);
@@ -457,16 +481,15 @@ 
    The ConsumedThing interface
    
         Observable<TDChangeListener> onTDChange();
       };
       callback ThingEventListener = void (ThingEvent event);
-      callback PropertyChangeListener = void (PropertyChangeEvent change);
-      callback TDChangeListener = void (TDChangeEvent td);
+      callback PropertyChangeListener = void (DOMString name, any value);
+      callback TDChangeListener = void (optional ThingDescription td);
     
    
     
    
       Represents a local proxy object of the remote Thing.
       
      
         
    • The name read-only attribute represents the name of the Thing.
      • 
-        
    • The url read-only attribute represents the URL of the Thing.
      • 
         
    • 
-          The description attribute read-only attribute represents the description of the Thing.
+          The td attribute read-only attribute represents the description of the Thing.
           
      
             Parsing and exposing Thing Descriptions is discussed in [Issue 38](https://github.com/w3c/wot-scripting-api/issues/38).
      
         
      • 
@@ -493,174 +516,59 @@ 
      The ConsumedThing interface
      
 
     
       
      The onEvent() method
      
       
      
-        Returns an Observable for the Property, Event or Action specified in the name argument, allowing subscribing and unsubscribing to notifications. Takes an argument of type ThingEventListener.
+        Returns an Observable for the Property, Event or Action specified in the name argument, allowing subscribing to and unsubscribing from notifications. Takes an argument of type ThingEventListener.
       
      
     
      
 
     
       
      The onPropertyChange() method
      
       
      
-        Returns an Observable for the Property specified in the name argument, allowing subscribing and unsubscribing to notifications. Takes an argument of type PropertyChangeListener.
+        Returns an Observable for the Property specified in the name argument, allowing subscribing to and unsubscribing from notifications. Takes an argument of type PropertyChangeListener.
       
      
     
      
 
     
       
      The onTDChange() method
      
       
      
-        Returns an Observable, allowing subscribing and unsubscribing to notifications to the Thing Description. Takes no arguments.
-      
      
-    
      
-
-    
      
-      
      The ThingEventListener callback
      
-      
      
-        A function called with an ThingEvent object when an event is emitted.
+        Returns an Observable, allowing subscribing to and unsubscribing from notifications to the Thing Description. Takes no arguments.
       
      
     
      
 
     
      
       
      The PropertyChangeListener callback
      
       
      
-        A function called with an ThingProperty object.
+        A function called with an name argument of type string that denotes the changed property name, and a value argument that denotes the new property value.
       
      
     
      
 
     
      
       
      The TDChangeListener callback
      
       
      
-        A function called with one optional argument of type ThingDescription.
+        A function called with one optional argument of type ThingDescription that denotes the new Thing Description.
       
      
     
      
 
-    
       
       Thing Events
      
+    
      
+      
      The ThingEventListener callback
      
       
      
-        Clients can subscribe to the Events defined in ExposedThing events. The event types are described in this section.
+        A function called with an ThingEvent object.
       
      
+    
      
 
-      
      
-        
      The PropertyChangeEvent interface
      
-        
      -          [Constructor(PropertyChangeEventInit init)]
-          interface PropertyChangeEvent: Event {
-            readonly attribute PropertyChangeEventInit data;
-          };
-        
      
-        
      
-            The data attribute represents the changed Property.
-        
      
-        
      
-          
      The PropertyChangeEventInit dictionary
      
-          
      -            dictionary PropertyChangeEventInit {
-                DOMString name;
-                any value;
-            };
-          
      
-          
      The name attribute represents the Property name.
      
-          
      The value attribute represents the new value of the Property.
      
-        
      
-      
      
-
-      
      
-        
      The ActionInvocationEvent interface
      
-        
      -          [Constructor(ActionInvocationEventInit init)]
-          interface ActionInvocationEvent: Event {
-              readonly attribute ActionInvocationEventInit data;
-          };
-        
      
-        
      
-            The data attribute represents the notification data from the Action invocation.
-        
      
-        
      
-          
      The ActionInvocationEventInit dictionary
      
-          
      -            dictionary ActionInvocationEventInit {
-                DOMString actionName;
-                any returnValue;
-            };
-          
      
-          
      
-            Action parameters could be also included, but it's debatable because privacy reasons.
-          
      
-          
      
-            The actionName attribute represents the name of the Action that has been invoked.
-          
      
-          
      
-            The returnValue attribute represents the return value of the Action.
-          
      
-        
      
-      
      
-
-      
      
-        
      The TDChangeEvent interface
      
-        
      -          [Constructor(TDChangeEventInit init)]
-          interface TDChangeEvent: Event {
-              readonly attribute TDChangeEventInit data;
-          };
-        
      
-        
      
-          The data attribute represents the changes that occurred to the Thing Description.
-        
      
-        
      
-          
      The TDChangeEventInit dictionary
      
-          
      -            dictionary TDChangeEventInit {
-                TDChangeType type;
-                TDChangeMethod method;
-                DOMString name;
-                TDChangeData data;
-                ThingDescription description;
-            };
-          
      
-          
        
-            
      • 
-              The type attribute represents the change type, whether has it been applied on properties, Actions or Events.
-            
        • 
-            
      • 
-             The method attribute tells what operation has been applied, addition, removal or change.
-            
        • 
-            
      • 
-              The name attribute represents the name of the Property, Action or event that has changed.
-            
        • 
-            
      • 
-              The data attribute provides the initialization data for the added or changed elements.
-            
        • 
-            
      • 
-              The description attribute is defined for the addition and change methods, and represents the new description.
-            
        • 
-          
      
-          
      
-            
      The TDChangeMethod enumeration
      
-            
      -              enum TDChangeMethod { "add", "remove", "change" };
-            
      
-            
        
-              
      • The add value denotes addition of a Property, Action or event.
        • 
-              
      • The remove value denotes removal of a Property, Action or event.
        • 
-              
      • The change value denotes a change applied on a Property, Action or event.
        • 
-            
      
-          
      
-          
      
-            
      The TDChangeType enumeration
      
-            
      -              enum TDChangeType { "property", "action", "event" };
-              typedef (ThingPropertyInit or ThingActionInit or ThingEventInit) TDChangeData;
-            
      
-            
        
-              
      • The property value tells the operation was applied on a Property definition.
        • 
-              
      • The action value tells the operation was applied on a action definition.
        • 
-              
      • The event value tells the operation was applied on an event definition.
        • 
-            
      
-          
      
-          
      
-            
      The TDChangeData type
      
-            
      
-              Represents the new description of the changed element. Depending on the change type, it can be either a ThingPropertyInit, ThingActionInit, or ThingEventInit.
-            
      
-          
      
-        
       
-      
       
-    
       
+    
      
+      
      The ThingEvent interface
      
+      
      
+        Clients can subscribe to the Events defined in ExposedThing events. The event types are described in this section.
+      
      
+      
      +        [Constructor(any data)]
+        interface ThingEvent {
+          readonly attribute DOMString name;
+          readonly attribute any data;
+        };
+      
      
+      
      
+          The data attribute represents the data attached to the event. The data type and values are defined in the Thing Description of the remote ExposedThing that exposes the event.
+      
      
+    
       
 
     
      
       
      Examples
      
@@ -668,16 +576,17 @@ 
      Examples
      
         Below a ConsumedThing interface example is given.
       
      
       
      -        wot.consume("http://mmyservice.org/mySensor").then( thing => {
+        wot.fetch("http://mmyservice.org/mySensor")
+        .then(td) => { consume(td)
+        .then(thing => {
             console.log("Thing " + thing.name + " has been consumed.");
             console.log("{ " + JSON.serialize(thing) + " }");
-            thing.onPropertyChange("temperature", function(event) {
-                if (event instanceof PropertyChangeEvent) {
-                    console.log("Property " + event.name + " value has changed to " + event.value);
+            thing.onPropertyChange("temperature", function(name, value) {
+                    console.log("Property " + name + " value has changed to " + value);
                 }
-            }).invokeAction("startMeasurement", ["Celsius"]);
+            }).invokeAction("startMeasurement", { units: "Celsius" });
           },
-        ).catch(error => {
+        )}).catch(error => {
           console.log("Discovery finished because an error: " + error.message);
         });
       
      
@@ -704,7 +613,12 @@ 
      The ExposedThing interface
      
         void removeAction(DOMString name);
         void addEvent(ThingEventInit event);
         void removeEvent(DOMString name);
+        void setActionHandler(DOMString actionName, Function action);
+        void setPropertyReadHandler(DOMString propertyName, PropertyReadHandler readHandler);
+        void setPropertyWriteHandler(DOMString propertyName, PropertyWriteHandler readHandler);
       };
+      callback PropertyReadHandler = any (DOMString propertyName);
+      callback PropertyWriteHandler = void (DOMString propertyName, any value);

    The start() method

    @@ -737,6 +651,22 @@

    The ExposedThing interface

    +
    +

    The ValueDefinition dictionary

    + 
    +        typedef DOMString ValueType;
+        dictionary ValueDefinition {
+          ValueType type;
+          any defaultValue;
+          any min;
+          any max;
+        };
+
    +

    + Represents a value definition, including type, minimum value, maximum value, and default value. +

    +
    +

    The addProperty() method

    Adds a Property defined by the argument and updates the Thing Description. @@ -744,14 +674,13 @@

    The ExposedThing interface

    The ThingPropertyInit dictionary

    -          dictionary ThingPropertyInit {
+          dictionary ThingPropertyInit: SemanticAnnotations {
             DOMString name;
+            ValueDefinition valueDescription;
+            any value;
             boolean configurable = false;
             boolean enumerable = true;
             boolean writable = true;
-            sequence<SemanticType> semanticTypes;
-            ThingDescription description;
-            any value;
           };

    @@ -768,12 +697,6 @@

    The ThingPropertyInit dictionary

  • The writable attribute defines whether the Property can be updated. The default value is true.
    • -
  • - The semanticTypes attribute represents a list of semantic type annotations (e.g. labels, classifications etc) relevant to the Property, represented as SemanticType dictionaries. -
    • -
  • - The description attribute represents the Property description to be added to the Thing Description. -

    • @@ -781,7 +704,7 @@

    The ThingPropertyInit dictionary

    The removeProperty() method

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

    @@ -792,12 +715,10 @@

    The ThingPropertyInit dictionary

    The ThingActionInit dictionary

    -          dictionary ThingActionInit {
+          dictionary ThingActionInit: SemanticAnnotations {
             DOMString name;
-            ThingDescription inputDataDescription;
-            ThingDescription outputDataDescription;
-            sequence<SemanticType> semanticTypes;
-            Function action;
+            sequence<ValueDefinition> inputDataDescription;
+            ValueDefinition outputDataDescription;
           };

    @@ -806,10 +727,6 @@

    The ThingActionInit dictionary

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

    • @@ -817,7 +734,7 @@

    The ThingActionInit dictionary

    The removeAction() method

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

    @@ -828,15 +745,13 @@

    The ThingActionInit dictionary

    The ThingEventInit dictionary

    -          dictionary ThingEventInit {
+          dictionary ThingEventInit: SemanticAnnotations {
             DOMString name;
-            sequence<SemanticType> semanticTypes;
-            ThingDescription dataDescription;
+            ValueDefinition dataDescription;
           };
    • The name attribute represents the event name.
      • -
    • The semanticTypes attribute represent a list of semantic type annotations attached to the event.
    • The dataDescription attribute represents the description of the data that is attached to the event.
    @@ -844,25 +759,10 @@

    The ThingEventInit dictionary

    The removeEvent() method

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

    -
    -

    Events supported by ExposedThing

    -

    - The following default events SHOULD be supported by ExposedThing implementations: -

    -

    -

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

    -
    -

    Examples

    From 36d65a6d3fe95f77138a27ca3a22cd21f1635e59 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 31 Jan 2018 17:35:19 +0200 Subject: [PATCH 159/464] Editorial pass to address review comments. Signed-off-by: Zoltan Kis --- index.html | 112 +++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 88 insertions(+), 24 deletions(-) diff --git a/index.html b/index.html index 5e95b077..750556e1 100644 --- a/index.html +++ b/index.html @@ -100,7 +100,7 @@ The Web of Things (WoT) provides layered interoperability between Things by using the WoT Interfaces.

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

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

    The ThingFilter dictionary

    dictionary ThingFilter { (DiscoveryMethod or DOMString) method = "any"; USVString url; - Dictionary description; + USVString query; + sequence<Dictionary> constraints; };

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

    - The url property represents additional information for the discovery method, such as the URL of the Thing Directory server to be used. + The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, such as a Thing Directory or a Thing.

    - The description property represents additional information for the discovery method in the form of a set of key-value pairs, as defined in the Thing Description. + The query> property represents a query string accepted by the implementation, for instance a SPARQL query. +

    +

    + The constraints property represents additional information for the discovery method in the form of a list of sets of key-value pairs, defined based on the semantic metadata of the Thing Description. The sequence elements are in OR relationship, and within an element the key-value pairs define AND type constraints.

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

    The DiscoveryMethod enumeration

    The ThingDescription type

    - Representation of the Thing Description, a unified representation for data exchange between Things, standardized in the [Wot Things Description](https://w3c.github.io/wot-thing-description/) specification. + Representation of the Thing Description, standardized in the [Wot Things Description](https://w3c.github.io/wot-thing-description/) specification.

    In this version of the API, Thing Descriptions are represented as opaque strings, denoting a serialized form, for instance JSON or JSON-LD. See [Issue 38](https://github.com/w3c/wot-scripting-api/issues/38) and [Issue 45](https://github.com/w3c/wot-scripting-api/issues/45). @@ -333,7 +337,18 @@

    The ThingDescription type

    The produce() method

    - Accepts an optional model argument of type ThingModel and returns an ExposedThing object, locally created based on the provided initialization parameters. + Accepts an optional model argument of type ThingModel and returns an ExposedThing object, locally created based on the provided initialization parameters. An ExposedThing can be created in the following ways: +

      +
    • + from an initial model (name and semantic annotations), then adding properties, actions, events and request handlers; +
      • +
    • + from a Thing Description, then adding request handlers; +
      • +
    • + from an existing ConsumedThing object, taking its Thing Description over, then adding request handlers. +
      • +

    @@ -355,6 +370,12 @@

    The SemanticAnnotations dictionary

    sequence<SemanticMetadata> metadata; }; +

    + The semanticTypes property denotes a list of SemanticType objects that define the semantic types that can be used in semantic metadata type-value pairs. +

    +

    + The metadata property denotes a list of SemanticMetadata objects (type-value pairs). +

    @@ -535,7 +556,7 @@

    The ConsumedThing interface

    The PropertyChangeListener callback

    - A function called with an name argument of type string that denotes the changed property name, and a value argument that denotes the new property value. + A function called with an name argument of type string that denotes the changed property name, and a value argument that denotes the new property value.

    @@ -559,14 +580,16 @@

    The ThingEvent interface

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

    -        [Constructor(any data)]
+        [Constructor(DOMString name, any data)]
         interface ThingEvent {
           readonly attribute DOMString name;
           readonly attribute any data;
         };

    - The data attribute represents the data attached to the event. The data type and values are defined in the Thing Description of the remote ExposedThing that exposes the event. + The name attribute represents the Event name. +

    + The data attribute represents the data attached to the event. The data type and values are defined in the Thing Description of the remote ExposedThing that exposes the event.

    @@ -613,12 +636,13 @@

    The ExposedThing interface

    void removeAction(DOMString name); void addEvent(ThingEventInit event); void removeEvent(DOMString name); - void setActionHandler(DOMString actionName, Function action); + void setActionHandler(DOMString actionName, ActionHandler action); void setPropertyReadHandler(DOMString propertyName, PropertyReadHandler readHandler); - void setPropertyWriteHandler(DOMString propertyName, PropertyWriteHandler readHandler); + void setPropertyWriteHandler(DOMString propertyName, PropertyWriteHandler writeHandler); }; - callback PropertyReadHandler = any (DOMString propertyName); - callback PropertyWriteHandler = void (DOMString propertyName, any value); + callback ActionHandler = Promise<any> (any parameters); + callback PropertyReadHandler = Promise<any> (DOMString propertyName); + callback PropertyWriteHandler = Promise<void> (DOMString propertyName, any value);

    The start() method

    @@ -657,13 +681,17 @@

    The ValueDefinition dictionary

    typedef DOMString ValueType; dictionary ValueDefinition { ValueType type; - any defaultValue; - any min; - any max; };

    - Represents a value definition, including type, minimum value, maximum value, and default value. + Represents a value definition, including type, and possible constraints like minimum value, maximum value, etc. +

      +
    • + The type property represents the type name of the value. +
    +

    +

    + The ValueType type represents a type name specified in the Thing Description.

    @@ -687,6 +715,9 @@

    The ThingPropertyInit dictionary

    Represents the Thing Property description.
    • The name attribute represents the name of the Property.
      • +
    • + The valueDescription attribute of type ValueDefinition represents the type of the Property. +
    • The value attribute represents the value of the Property.
    • The configurable attribute defines whether the Property can be deleted from the object and whether its type can be changed. The default value is false. @@ -763,6 +794,45 @@

      The ThingEventInit dictionary

    +
    +

    The ActionHandler callback

    +

    + A function called with any parameters that returns a Promise. +

    +
    + +
    +

    The PropertyReadHandler callback

    +

    + A function called with a propertyName argument that returns a Promise and resolves it with the value of the Property matching propertyName, or rejects with and error if the property is not found or the value cannot be retrieved. +

    +
    + +
    +

    The PropertyWriteHandler callback

    +

    + A function called with a propertyName and a value argument that returns a Promise and resolves it when the value of the Property matching propertyName is updated with value, or rejects with and error if the property is not found or the value cannot be updated. +

    +
    + +

    The setActionHandler() method

    +

    + Takes a actionName as string argument, and an action argument of type ActionHandler. Sets the handler function for the specified Action matched by actionName. Throws on error. +

    +
    + +

    The setPropertyReadHandler() method

    +

    + Takes a propertyName as string argument, and a readHandler argument of type PropertyReadHandler. Sets the handler function for reading the specified Property matched by propertyName. Throws on error. +

    +
    + +

    The setPropertyWriteHandler() method

    +

    + Takes a propertyName as string argument, and a writeHandler argument of type PropertyWriteHandler. Sets the handler function for writing the specified Property matched by propertyName. Throws on error. +

    +
    +

    Examples

    @@ -856,7 +926,7 @@

    Examples

    Terminology and conventions

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

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

    Examples

    BufferSource and any are defined in [[!WEBIDL]].

    -

    - The term event and the Event object are defined in [DOM](https://www.w3.org/TR/DOM-Level-2-Events/events.html) and [Node.js](https://nodejs.org/api/events.html). -

    -

    - This specification uses the convention that an event listener will receive an [Event](https://www.w3.org/TR/DOM-Level-2-Events/ecma-script-binding.html) object. This should work both in a browser environment and in a Node.js like environment. -

    Observables are proposed to be included in ECMAScript.

    From 0f8724e40dd32848674d19950e151eeec080c1ef Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Thu, 1 Feb 2018 10:36:08 +0200 Subject: [PATCH 160/464] Remove ConsumedThing from ThingModel. ExposedThing implements ConsumedThing. Signed-off-by: Zoltan Kis --- index.html | 32 ++++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/index.html b/index.html index 750556e1..6564bdd9 100644 --- a/index.html +++ b/index.html @@ -240,7 +240,7 @@

    The WoT object

    ExposedThing produce(optional ThingModel model); }; typedef USVString ThingDescription; - typedef (ThingTemplate or ThingDescription or ConsumedThing) ThingModel; + typedef (ThingTemplate or ThingDescription) ThingModel;

    @@ -335,7 +335,7 @@

    The ThingDescription type

    -

    The produce() method

    +

    The produce() method

    Accepts an optional model argument of type ThingModel and returns an ExposedThing object, locally created based on the provided initialization parameters. An ExposedThing can be created in the following ways:

    @@ -355,7 +355,7 @@

    The ThingDescription type

    The ThingModel type

    - A Thing model is used for producing a new ExposedThing and can be either a ThingTemplate, or a ThingDescription, or a ConsumedThing. + A Thing model is used for producing a new ExposedThing and can be either a ThingTemplate, or a ThingDescription.

    @@ -619,9 +619,13 @@

    Examples

    The ExposedThing interface

    - The ExposedThing interface is the server API that allows defining request handlers, properties, Actions, and Events to a Thing. + The ExposedThing interface is the server API that allows defining request handlers, properties, Actions, and Events to a Thing. It also implements the ConsumedThing interface. An ExposedThing is created by the produce() method. +

    +

    + It is under consideration to use a constructor for ExposedThing instead of a factory method. 

    +      ExposedThing implements ConsumedThing;
       interface ExposedThing {
         // define how to expose and run the Thing
         Promise<void> start();
@@ -675,10 +679,22 @@ 
    The ExposedThing interface
    +
    +

    The ValueType type

    + 
    +        typedef DOMString ValueType;
+
    +

    + The ValueType type represents a type name specified in the Thing Description. +

    +

    + ValueType is under development, currently it is a string that in principle can denote any type supported by the Thing Description and the WoT Runtime, such as "boolean", "integer", "number", "string", "array", "object. +

    +
    +

    The ValueDefinition dictionary

    -        typedef DOMString ValueType;
         dictionary ValueDefinition {
           ValueType type;
         };
@@ -690,8 +706,8 @@ 
    The ValueDefinition dictionary
    
             The type property represents the type name of the value.
         
       
    
-      
    
-        The ValueType type represents a type name specified in the Thing Description.
+      
    
+        The Thing Description [specification](https://w3c.github.io/wot-thing-description/) supports constraints like range for numbers and array size. These are not yet represented in this version.
    From 61dcf59d0308f6b1e6e21f7f75e7c52f1cd61dd0 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Fri, 2 Feb 2018 16:03:11 +0200 Subject: [PATCH 161/464] Update examples. Update handler signatures for supporting generic handlers. Signed-off-by: Zoltan Kis --- index.html | 157 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 88 insertions(+), 69 deletions(-) diff --git a/index.html b/index.html index 6564bdd9..d9bf186e 100644 --- a/index.html +++ b/index.html @@ -603,14 +603,19 @@

    Examples

    .then(td) => { consume(td) .then(thing => { console.log("Thing " + thing.name + " has been consumed."); - console.log("{ " + JSON.serialize(thing) + " }"); - thing.onPropertyChange("temperature", function(name, value) { - console.log("Property " + name + " value has changed to " + value); - } - }).invokeAction("startMeasurement", { units: "Celsius" }); + let subscription = thing.onPropertyChange("temperature") + .subscribe(function(name, value) { + console.log("Property " + name + " value has changed to " + value); + }); + thing.invokeAction("startMeasurement", { units: "Celsius" }) + .then(() => { console.log("Temperature measurement started."); }) + .catch(e => { + console.log("Error starting measurement."); + subscription.cancel(); + }) }, )}).catch(error => { - console.log("Discovery finished because an error: " + error.message); + console.log("Error during fetch or consume: " + error.message); });
    @@ -640,9 +645,9 @@

    The ExposedThing interface

    void removeAction(DOMString name); void addEvent(ThingEventInit event); void removeEvent(DOMString name); - void setActionHandler(DOMString actionName, ActionHandler action); - void setPropertyReadHandler(DOMString propertyName, PropertyReadHandler readHandler); - void setPropertyWriteHandler(DOMString propertyName, PropertyWriteHandler writeHandler); + void setActionHandler(ActionHandler action, optional DOMString actionName); + void setPropertyReadHandler(PropertyReadHandler readHandler, optional DOMString propertyName); + void setPropertyWriteHandler(PropertyWriteHandler writeHandler, optional DOMString propertyName); }; callback ActionHandler = Promise<any> (any parameters); callback PropertyReadHandler = Promise<any> (DOMString propertyName); @@ -692,18 +697,18 @@

    The ValueType type

    -
    -

    The ValueDefinition dictionary

    +
    +

    The ValueTypeDefinition dictionary

    -        dictionary ValueDefinition {
-          ValueType type;
+        dictionary ValueTypeDefinition {
+          ValueType typeName;
         };

    Represents a value definition, including type, and possible constraints like minimum value, maximum value, etc.

    • - The type property represents the type name of the value. + The typeName property represents the type name of the value.

    @@ -720,7 +725,7 @@

    The ThingPropertyInit dictionary

               dictionary ThingPropertyInit: SemanticAnnotations {
             DOMString name;
-            ValueDefinition valueDescription;
+            ValueTypeDefinition type;
             any value;
             boolean configurable = false;
             boolean enumerable = true;
@@ -732,7 +737,7 @@ 
    The ThingPropertyInit dictionary
    
           
      
             
    • The name attribute represents the name of the Property.
      • 
             
    • 
-              The valueDescription attribute of type ValueDefinition represents the type of the Property.
+              The type attribute represents the type and accepted value range for the Property by a of type ValueTypeDefinition object.
             
      • 
             
    • The value attribute represents the value of the Property.
      • 
             
    • 
@@ -764,8 +769,8 @@ 
      The ThingActionInit dictionary
      
         
                 dictionary ThingActionInit: SemanticAnnotations {
             DOMString name;
-            sequence<ValueDefinition> inputDataDescription;
-            ValueDefinition outputDataDescription;
+            sequence<ValueTypeDefinition> inputDataDescription;
+            ValueTypeDefinition outputDataDescription;
           };
       
      
       
      
@@ -794,7 +799,7 @@ 
      The ThingEventInit dictionary
      
         
                 dictionary ThingEventInit: SemanticAnnotations {
             DOMString name;
-            ValueDefinition dataDescription;
+            ValueTypeDefinition dataDescription;
           };
         
      
         
        
@@ -833,19 +838,19 @@ 
        The PropertyWriteHandler callback
        
 
     
         
        The setActionHandler() method
        
       
        
-        Takes a actionName as string argument, and an action argument of type ActionHandler. Sets the handler function for the specified Action matched by actionName. Throws on error.
+        Takes a actionName as an optional string argument, and an action argument of type ActionHandler. Sets the handler function for the specified Action matched by actionName if actionName is specified, otherwise sets it for any action. Throws on error.
       
        
     
        
 
     
         
        The setPropertyReadHandler() method
        
       
        
-        Takes a propertyName as string argument, and a readHandler argument of type PropertyReadHandler. Sets the handler function for reading the specified Property matched by propertyName. Throws on error.
+        Takes a propertyName as an optional string argument, and a readHandler argument of type PropertyReadHandler. Sets the handler function for reading the specified Property matched by propertyName if propertyName is specified, otherwise sets it for reading any property. Throws on error.
       
        
     
        
 
     
         
        The setPropertyWriteHandler() method
        
       
        
-        Takes a propertyName as string argument, and a writeHandler argument of type PropertyWriteHandler. Sets the handler function for writing the specified Property matched by propertyName. Throws on error.
+        Takes a propertyName as an optional string argument, and a writeHandler argument of type PropertyWriteHandler. Sets the handler function for writing the specified Property matched by propertyName if the propertyName is specified, otherwise sets it for writing any properties. Throws on error.
       
        
     
        
 
@@ -858,31 +863,43 @@ 
        Examples
        
       
                 WoT.createExposedThing(thingDescription)
           .then(function(thing) {
-            // manually add properties, actions, and events
-            thing.addProperty({
-              name: "temperature",
-              value: "0",
-              writable: false
-              // use default values for the rest
-            }).addEvent({
-              name: "onchange",
-              outputDataDescription: {
-                type: "float32"
-              }
-            }).addAction({
-              name: "reset",
-              action: () => { this.temperature = 0; }
-            })
-            // add server functionality
-            .onRetrieveProperty( request => {
-              console.log("Handling read request");
-              return this.temperature;
-            }).onObserve( request => {
-              console.log("Handling observe request");
-              // add listener identified by request.from
-            }).onInvokeAction( request => {
-              console.log("Handling action request");
-            }).start();
+            try {
+              // manually add properties, actions, and events
+              thing.addProperty({
+                name: "temperature",
+                value: "0",
+                type: { typeName: "double" },
+                writable: false
+                // use default values for the rest
+              });
+
+              thing.addEvent({
+                name: "onchange",
+                outputDataDescription: {
+                  type: "double"
+                }
+              });
+
+              thing.addAction({
+                name: "reset",
+                action: () => { this.temperature = 0; }
+              });
+
+              // add server functionality
+              thing.setPropertyReadHandler( propertyName => {
+                console.log("Handling read request for " + propertyName);
+                return new Promise((resolve, reject) => {
+                if (this.hasOwnProperty(propertyName))
+                  resolve(this[propertyName]);
+                else reject('Property not found');
+              });
+            } catch(e) {
+              console.log("Error");
+            }
+
+            thing.start()
+            .then (() => { thing.register();})
+            .catch((err) => { console.log("Error");});
           });
       
        
 
@@ -891,23 +908,27 @@ 
        Examples
        
           "name": "mySensor",
           "url": "http://myservice.org/mySensor/description"
         }';
-        WoT.createExposedThing(thingDescription)
-          .then(function(thing) {
-            // properties, actions and events are added based on the TD
-            console.log("created " + thing.name });
-            // now add the requests handlers
-            thing.onRetrieveProperty(function(request) {
-                console.log("Sending property '" + request.property + "' to " + request.from);
-            }).onUpdateProperty(function(request) {
-                console.log("Updating property '" + request.property + "' by " + request.from);
-            }).onObserve(function(request) {
-                console.log("Adding listener " + request.from);
-                console.log("Observing " + request.type + " " + request.name +
-                    (request.subscribe? " recursively" : ""));
-            }).start().then(function() {
-               console.log("Thing started serving requests");
+        WoT.fetch("http://myservice.org/mySensor/description")
+        .then(td => {
+          let e_thing = WoT.produce(td);
+          // properties, actions and events are added based on the TD
+          console.log("created " + thing.name });
+          // now add the requests handlers
+          try {
+            e_thing.setPropertyReadHandler(propertyName => {
+              console.log("Handling read request for " + propertyName);
+              return new Promise((resolve, reject) => {
+              if (this.hasOwnProperty(propertyName))
+                resolve(this[propertyName]);
+              else reject('Property not found');
             });
-          })
+            e_thing.start();
+          } catch(error) {
+            console.log("Error");
+          }
+        }
+
+        });
       
    @@ -919,17 +940,15 @@ 
    Examples
    
               "http://w3c.github.io/wot/w3c-wot-common-context.jsonld",
             ],
             "@type": [ "Thing" ],
-            "interaction": [
+            "interactions": [
               // ...
             ]
             // ...
           }'
         };
-        WoT.createExposedThing(thingDescription)
-          .then(function(thing) {
-            // properties, actions and events are added based on the TD
-            // ...
-          });
+        let e_thing = WoT.produce(thingDescription);
+        // properties, actions and events are added based on the TD
+        // ...
    From 351de3755fda1265dd8d672228688d96ea53304e Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 5 Feb 2018 13:53:25 +0200 Subject: [PATCH 162/464] Editorial fix for ReSpec errors Signed-off-by: Zoltan Kis --- index.html | 60 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 31 insertions(+), 29 deletions(-) diff --git a/index.html b/index.html index d9bf186e..04ce9d2a 100644 --- a/index.html +++ b/index.html @@ -252,6 +252,33 @@

    The WoT object

    Starts the discovery process that will provide ConsumedThing objects that match the optional argument ThingFilter. When the argument is not provided, starts the widest discovery the Thing Description and Protocol Bindings allow and support. Returns an [Observable](https://github.com/tc39/proposal-observable) object that can be subscribed to and unsubscribed from.

    + +
    +

    The DiscoveryMethod enumeration

    + 
    +          typedef DOMString DiscoveryMethod;
+
    +

    + DiscoveryMethod represents the discovery type to be used: +

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

    +
    +

    The ThingFilter dictionary

    @@ -259,7 +286,7 @@

    The ThingFilter dictionary

               dictionary ThingFilter {
-            (DiscoveryMethod or DOMString) method = "any";
+            DiscoveryMethod method = "any";
             USVString url;
             USVString query;
             sequence<Dictionary> constraints;
@@ -272,7 +299,7 @@ 
    The ThingFilter dictionary
    
           The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, such as a Thing Directory or a Thing.
         
    
         
    
-          The query> property represents a query string accepted by the implementation, for instance a SPARQL query.
+          The query property represents a query string accepted by the implementation, for instance a SPARQL query.
         
    
         
    
           The constraints property represents additional information for the discovery method in the form of a list of sets of key-value pairs, defined based on the semantic metadata of the Thing Description. The sequence elements are in OR relationship, and within an element the key-value pairs define AND type constraints.
@@ -284,32 +311,6 @@ 
    The ThingFilter dictionary
    
           The ThingFilter dictionary may be extended later with further attributes.
    - -
    -

    The DiscoveryMethod enumeration

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

    - The DiscoveryMethod enumeration represents the discovery type to be used: -

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

    -

    The fetch() method

    @@ -587,7 +588,8 @@

    The ThingEvent interface

    };

    - The name attribute represents the Event name. + The name attribute represents the Event name. +

    The data attribute represents the data attached to the event. The data type and values are defined in the Thing Description of the remote ExposedThing that exposes the event.

    From 45d0598d7ab4e9beb6fc144ccaccbfcd070942ad Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 5 Feb 2018 17:11:26 +0200 Subject: [PATCH 163/464] Add section for Observables. Remove optionality from some arguments and dictionary members. Signed-off-by: Zoltan Kis --- index.html | 87 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 79 insertions(+), 8 deletions(-) diff --git a/index.html b/index.html index 04ce9d2a..d4cfd67d 100644 --- a/index.html +++ b/index.html @@ -237,7 +237,7 @@

    The WoT object

    Observable<ConsumedThing> discover(optional ThingFilter filter); Promise<ThingDescription> fetch(USVString url); ConsumedThing consume(ThingDescription td); - ExposedThing produce(optional ThingModel model); + ExposedThing produce(ThingModel model); }; typedef USVString ThingDescription; typedef (ThingTemplate or ThingDescription) ThingModel; @@ -338,7 +338,7 @@

    The ThingDescription type

    The produce() method

    - Accepts an optional model argument of type ThingModel and returns an ExposedThing object, locally created based on the provided initialization parameters. An ExposedThing can be created in the following ways: + Accepts a model argument of type ThingModel and returns an ExposedThing object, locally created based on the provided initialization parameters. An ExposedThing can be created in the following ways:

    • from an initial model (name and semantic annotations), then adding properties, actions, events and request handlers; @@ -383,8 +383,8 @@

      The SemanticAnnotations dictionary

      The SemanticType dictionary

               dictionary SemanticType {
-            DOMString name;
-            USVString context;
+            required DOMString name;
+            required USVString context;
             DOMString prefix;
         };
      @@ -432,7 +432,7 @@

      The ThingTemplate dictionary

               dictionary ThingTemplate: SemanticAnnotations {
-            DOMString name;
+            required DOMString name;
         };

      The ThingTemplate dictionary extends SemanticAnnotations and contains properties to initialize a Thing: @@ -955,6 +955,80 @@

      Examples

    +
    +

    Observables

    +

    + Observables are proposed to be included in ECMAScript and are used for handling pushed data associated with various possible sources, for instance events, timers, streams, etc. A minimal required implementation is described here. +

    +

    + This section is informal and contains rather laconic information for implementations on what to support for interoperability. +

    + 
    +      interface Observable {
+        Subscription subscribe((Observer or OnNext) next,
+                               optional OnError error,
+                               optional OnComplete complete);
+      };
+      interface Subscription {
+        void unsubscribe();
+        readonly attribute boolean closed;
+      };
+      interface Observer {
+        void next(any value);
+        void error(Error error);
+        void complete();
+      };
+      callback OnNext = void (any value);
+      callback OnError = void (Error error);
+      callback OnComplete = void ();
+
    + +
    +

    The Observer interface

    +

    + The Observer interface defines the callbacks needed to handle an Observable: +

      +
    • + The next() function, as well as the OnNext callback takes the next sample for the data in the value argument. +
      • +
    • + The error() function, as well as the OnError callback takes an error in the value argument. It is called when an error occured in producing the data the client should know about. +
      • +
    • + The complete() function, as well as the OnComplete callback is called when the data source has finished sending values. +
      • +
    +

    +
    + +
    +

    The Subscription interface

    +

    + Contains the closed property of type boolean that tells if the subscription is closed or active. +

    +

    + Also, contains the unsubscribe() method that cancels the subscription, i.e. makes a request to the underlying platform to stop receiving data from the source, and sets the closed property to false. +

    +
    + +
    +

    The Observer interface

    +

    + The Observable interface enabled subscribing to pushed data notifications by the subscribe() method: +

      +
    • + If the subscribe() method is called with an Observer object, initialize the data, error and completion handling callbacks from that object, or throw on error. +
      • +
    • + Otherwise, if the subscribe() method is called with a function, initialize the data handler callback with that function. If the next argument is provided and is a function, initialize the error handling callback with that function, or throw on error. If the third argument is provided and is a function, initialize the completion handler with that function, or throw on error. +
      • +
    • + After callback initializations, the implementation should request the underlying platform to provide data, error and completion notifications for the supported data source. +
      • +
    +
    +
    +

    Security and Privacy

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

    Examples

    BufferSource and any are defined in [[!WEBIDL]].

    -

    - Observables are proposed to be included in ECMAScript. -

    The algorithms utf-8 encode, and From 144e580693b1bacaeb460f74562bf7b1cb6403bc Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 5 Feb 2018 17:39:16 +0200 Subject: [PATCH 164/464] Add explanations for ExposedThing handlers. Signed-off-by: Zoltan Kis --- index.html | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index d4cfd67d..6e908135 100644 --- a/index.html +++ b/index.html @@ -834,7 +834,10 @@

    The PropertyReadHandler callback

    The PropertyWriteHandler callback

    - A function called with a propertyName and a value argument that returns a Promise and resolves it when the value of the Property matching propertyName is updated with value, or rejects with and error if the property is not found or the value cannot be updated. + A function called with a propertyName and a value argument that returns a Promise and resolves it when the value of the Property matching propertyName is updated with value, or rejects with and error if the property is not found or the value cannot be updated. The property is updated by the implementation with the value that is resolved by this callback. +

    +

    + Note that this function is invoked by implementations before the property is updated, so the client code in this function can invoke the readProperty() method to find out the old value of the property, if needed. Therefore the old value is not provided to this method.

    @@ -842,18 +845,33 @@

    The PropertyWriteHandler callback

    Takes a actionName as an optional string argument, and an action argument of type ActionHandler. Sets the handler function for the specified Action matched by actionName if actionName is specified, otherwise sets it for any action. Throws on error.

    +

    + If provided, this callback function will implement invoking an Action and SHOULD be called by implementations when a request for invoking a Action is received from the underlying platform. +

    +

    + There SHOULD be exactly one handler for any given Action. If no handler is initialized for any given Action, implementations SHOULD return error if the action is invoked by any client. +

    The setPropertyReadHandler() method

    Takes a propertyName as an optional string argument, and a readHandler argument of type PropertyReadHandler. Sets the handler function for reading the specified Property matched by propertyName if propertyName is specified, otherwise sets it for reading any property. Throws on error.

    +

    + If provided, this callback function will implement reading a Property and SHOULD be called by implementations when a request for reading a Property is received from the underlying platform. +

    +

    + There SHOULD be at most one handler for any given Property. If no handler is initialized for any given Property, implementations SHOULD implement default property read without calling this hook. +

    The setPropertyWriteHandler() method

    Takes a propertyName as an optional string argument, and a writeHandler argument of type PropertyWriteHandler. Sets the handler function for writing the specified Property matched by propertyName if the propertyName is specified, otherwise sets it for writing any properties. Throws on error.

    +

    + There SHOULD be at most one write handler for any given Property. If no write handler is initialized for any given Property, implementations SHOULD implement default property update and notifying observers. +

    @@ -955,7 +973,7 @@

    Examples

    -
    +

    Observables

    Observables are proposed to be included in ECMAScript and are used for handling pushed data associated with various possible sources, for instance events, timers, streams, etc. A minimal required implementation is described here. From 9bb32944617f0df6ad9f1486890d32ee4556c971 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 7 Feb 2018 15:25:38 +0200 Subject: [PATCH 165/464] Editorial fixes based on comments Signed-off-by: Zoltan Kis --- index.html | 139 +++++++++++++++++------------------------------------ 1 file changed, 43 insertions(+), 96 deletions(-) diff --git a/index.html b/index.html index 6e908135..ceb2d44a 100644 --- a/index.html +++ b/index.html @@ -175,7 +175,7 @@

    • Exposing the Thing includes attaching to the protocol bindings in order to access lower level functionality. -
      • > +
    • Create a local ExposedThing to be exposed, based on a Thing Description provided in string serialized format, or out of a template or an existing ConsumedThing object.
    • Add a Property definition to the Thing.
      • @@ -326,7 +326,6 @@

      The ThingDescription type

      In this version of the API, Thing Descriptions are represented as opaque strings, denoting a serialized form, for instance JSON or JSON-LD. See [Issue 38](https://github.com/w3c/wot-scripting-api/issues/38) and [Issue 45](https://github.com/w3c/wot-scripting-api/issues/45). - Parsing and composing Thing Descriptions is left for external libraries until standardized here.

    @@ -498,13 +497,10 @@

    The ConsumedThing interface

    Promise<any> invokeAction(DOMString name, any parameters); Promise<void> writeProperty(DOMString name, any value); Promise<any> readProperty(DOMString name); - Observable<ThingEventListener> onEvent(DOMString name); - Observable<PropertyChangeListener> onPropertyChange(DOMString name); - Observable<TDChangeListener> onTDChange(); + Observable onEvent(DOMString name); + Observable onPropertyChange(DOMString name); + Observable onTDChange(); }; - callback ThingEventListener = void (ThingEvent event); - callback PropertyChangeListener = void (DOMString name, any value); - callback TDChangeListener = void (optional ThingDescription td);

    Represents a local proxy object of the remote Thing. @@ -538,63 +534,31 @@

    The ConsumedThing interface

    The onEvent() method

    - Returns an Observable for the Property, Event or Action specified in the name argument, allowing subscribing to and unsubscribing from notifications. Takes an argument of type ThingEventListener. + Returns an Observable for the Event specified in the name argument, allowing subscribing to and unsubscribing from notifications.

    -
    - -

    The onPropertyChange() method

    - Returns an Observable for the Property specified in the name argument, allowing subscribing to and unsubscribing from notifications. Takes an argument of type PropertyChangeListener. + The callback function passed to the subscribe() method when invoked on the returned observer will receive the event data each time the event is fired.

    -

    The onTDChange() method

    +

    The onPropertyChange() method

    - Returns an Observable, allowing subscribing to and unsubscribing from notifications to the Thing Description. Takes no arguments. + Returns an Observable for the Property specified in the name argument, allowing subscribing to and unsubscribing from notifications.

    -
    - -
    -

    The PropertyChangeListener callback

    - A function called with an name argument of type string that denotes the changed property name, and a value argument that denotes the new property value. + The callback function passed to the subscribe() method when invoked on the returned observer will receive the new property value each time it is changed.

    -
    -

    The TDChangeListener callback

    +

    The onTDChange() method

    - A function called with one optional argument of type ThingDescription that denotes the new Thing Description. + Returns an Observable, allowing subscribing to and unsubscribing from notifications to the Thing Description.

    -
    - -
    -

    The ThingEventListener callback

    - A function called with an ThingEvent object. + The callback function passed to the subscribe() method when invoked on the returned observer will receive the new Thing Description each time it is changed.

    -
    -

    The ThingEvent interface

    -

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

    - 
    -        [Constructor(DOMString name, any data)]
-        interface ThingEvent {
-          readonly attribute DOMString name;
-          readonly attribute any data;
-        };
-
    -

    - The name attribute represents the Event name. -

    -

    - The data attribute represents the data attached to the event. The data type and values are defined in the Thing Description of the remote ExposedThing that exposes the event. -

    -
    -

    Examples

    @@ -606,8 +570,8 @@

    Examples

    .then(thing => { console.log("Thing " + thing.name + " has been consumed."); let subscription = thing.onPropertyChange("temperature") - .subscribe(function(name, value) { - console.log("Property " + name + " value has changed to " + value); + .subscribe(function(value) { + console.log("Temperature + " has changed to " + value); }); thing.invokeAction("startMeasurement", { units: "Celsius" }) .then(() => { console.log("Temperature measurement started."); }) @@ -689,32 +653,13 @@

    The ExposedThing interface

    The ValueType type

    -        typedef DOMString ValueType;
+        typedef any ValueType;

    The ValueType type represents a type name specified in the Thing Description.

    - ValueType is under development, currently it is a string that in principle can denote any type supported by the Thing Description and the WoT Runtime, such as "boolean", "integer", "number", "string", "array", "object. -

    -
    - -
    -

    The ValueTypeDefinition dictionary

    - 
    -        dictionary ValueTypeDefinition {
-          ValueType typeName;
-        };
-
    -

    - Represents a value definition, including type, and possible constraints like minimum value, maximum value, etc. -

      -
    • - The typeName property represents the type name of the value. -
    -

    -

    - The Thing Description [specification](https://w3c.github.io/wot-thing-description/) supports constraints like range for numbers and array size. These are not yet represented in this version. + ValueType is under development, currently it can denote any type supported by the Thing Description and the WoT Runtime, such as "boolean", "number", "string", "array", or "object".

    @@ -727,7 +672,7 @@

    The ThingPropertyInit dictionary

               dictionary ThingPropertyInit: SemanticAnnotations {
             DOMString name;
-            ValueTypeDefinition type;
+            ValueType type;
             any value;
             boolean configurable = false;
             boolean enumerable = true;
@@ -739,7 +684,7 @@ 
    The ThingPropertyInit dictionary
    
           
      
             
    • The name attribute represents the name of the Property.
      • 
             
    • 
-              The type attribute represents the type and accepted value range for the Property by a of type ValueTypeDefinition object.
+              The type attribute represents the type for the Property.
             
      • 
             
    • The value attribute represents the value of the Property.
      • 
             
    • 
@@ -771,15 +716,15 @@ 
      The ThingActionInit dictionary
      
         
                 dictionary ThingActionInit: SemanticAnnotations {
             DOMString name;
-            sequence<ValueTypeDefinition> inputDataDescription;
-            ValueTypeDefinition outputDataDescription;
+            ValueType inputDataDescription;
+            ValueType outputDataDescription;
           };
       
      
       
      
         The ThingActionInit dictionary describes the arguments and the return value.
         
        
           
      • The name attribute provides the Action name.
        • 
-          
      • The inputDataDescription attribute provides the description of the input arguments.
        • 
+          
      • The inputDataDescription attribute provides the description of the input arguments (argument list is represented by an object).
        • 
           
      • The outputDataDescription attribute provides the description of the returned data.
        • 
         
      
       
      
@@ -801,12 +746,12 @@ 
      The ThingEventInit dictionary
      
         
                 dictionary ThingEventInit: SemanticAnnotations {
             DOMString name;
-            ValueTypeDefinition dataDescription;
+            ValueType dataDescription;
           };
         
      
         
        
           
      • The name attribute represents the event name.
        • 
-          
      • The dataDescription attribute represents the description of the data that is attached to the event.
        • 
+          
      • The dataDescription attribute represents the type of the data that is attached to the event.
        •
    @@ -837,7 +782,7 @@

    The PropertyWriteHandler callback

    A function called with a propertyName and a value argument that returns a Promise and resolves it when the value of the Property matching propertyName is updated with value, or rejects with and error if the property is not found or the value cannot be updated. The property is updated by the implementation with the value that is resolved by this callback.

    - Note that this function is invoked by implementations before the property is updated, so the client code in this function can invoke the readProperty() method to find out the old value of the property, if needed. Therefore the old value is not provided to this method. + Note that this function is invoked by implementations before the property is updated, so the code in this callback function can invoke the readProperty() method to find out the old value of the property, if needed. Therefore the old value is not provided to this method.

    @@ -888,38 +833,41 @@

    Examples

    thing.addProperty({ name: "temperature", value: "0", - type: { typeName: "double" }, + type: "number", writable: false // use default values for the rest }); - thing.addEvent({ name: "onchange", - outputDataDescription: { - type: "double" - } + dataDescription: "number" }); - thing.addAction({ name: "reset", action: () => { this.temperature = 0; } }); - // add server functionality - thing.setPropertyReadHandler( propertyName => { + thing.setPropertyReadHandler(propertyName => { console.log("Handling read request for " + propertyName); return new Promise((resolve, reject) => { - if (this.hasOwnProperty(propertyName)) - resolve(this[propertyName]); - else reject('Property not found'); + if (this.hasOwnProperty(propertyName)) + resolve(this[propertyName]); + else + reject('Property not found'); + }, + e => { + console.log("Error"); + }); }); - } catch(e) { - console.log("Error"); + } catch (err) { + console.log("Thing creation error."); } - thing.start() - .then (() => { thing.register();}) - .catch((err) => { console.log("Error");}); + .then (() => { + thing.register(); + }); + }) + .catch (err => { + console.log("Error"); }); @@ -947,7 +895,6 @@

    Examples

    console.log("Error"); } } - }); From ba217f6721967de17957b988d398db5e85df73b7 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Thu, 8 Feb 2018 10:33:54 +0200 Subject: [PATCH 166/464] Editorial pass: examples, use cases, notes, various small clarifications. Removed duplicated statements. Signed-off-by: Zoltan Kis --- index.html | 92 +++++++++++++++++++++++++++++------------------------- 1 file changed, 49 insertions(+), 43 deletions(-) diff --git a/index.html b/index.html index ceb2d44a..58057adf 100644 --- a/index.html +++ b/index.html @@ -123,14 +123,17 @@ The Web of Things is made of entities (Things) that can describe their capabilities in a machine-interpretable format, the Thing Description (TD) and expose these capabilities through the WoT Interface. Support for scripting is optional for WoT devices.

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

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

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

    +

    + This specification does not make assumptions on how the WoT Runtime handles and runs scripts, including single or multiple tenancy, script deployment and lifecycle management. The API already supports the generic mechanisms that make it possible to implement script management, for instance by exposing a manager Thing whose Actions (action handlers) implement script lifecycle management operations. +

    For an introduction on how scripts could be used in Web of Things, check the [Primer](https://w3c.github.io/wot-scripting-api/primer) document. For some background on API design decisions check the [Rationale](https://w3c.github.io/wot-scripting-api/rationale) document.

    @@ -138,7 +141,7 @@

    Use Cases

    - The following scripting use cases are covered in this specification: + The following scripting use cases are supported in this specification:

    Discovery

      @@ -157,11 +160,14 @@

      Consuming a Thing

      • - Fetch and consume a TD of a Thing. The TD may be provided in a string serialized format, or specified by a URL. Consuming the Thing includes parsing the TD and attaching to the protocol bindings in order to access lower level functionality. + Fetch a Thing Description of a Thing given its URL. +
        • +
      • + Consume a TD of a Thing, including parsing the TD and generating the protocol bindings in order to access lower level functionality.
      • On a consumed Thing,
          -
        • Get the value of a Property or set of properties.
          • +
        • Read the value of a Property or set of properties.
        • Observe value changes to a Property.
        • Set the value of a Property or a set of properties.
        • Invoke an Action.
          • @@ -174,13 +180,14 @@

          Exposing a Thing

          • - Exposing the Thing includes attaching to the protocol bindings in order to access lower level functionality. + Exposing the Thing includes generating the protocol bindings in order to access lower level functionality.
          • Create a local ExposedThing to be exposed, based on a Thing Description provided in string serialized format, or out of a template or an existing ConsumedThing object.
          • Add a Property definition to the Thing.
          • Add an Event definition to the Thing.
          • Add an Action definition to the Thing.
            • +
          • Attach semantic information to the Thing
          • Attach semantic information to an Action
          • Attach semantic information to a Property
          • Attach semantic information to an Event
            • @@ -188,7 +195,7 @@ Emit an Event, i.e. notify all listeners subscribed to that Event.
          • - Provide notifications for TD changes to clients subscribed to that. + Provide notifications for TD changes to clients subscribed to that.
          • Mark/unmark the Thing to be discoverable.
          • Mark/unmark the Thing to be consumable.
            • @@ -201,31 +208,15 @@
          • to run an Action: take the parameters from the request, execute the defined action, and return the result;
            • -
          • to add a listener to an Event;
            • -
          • to remove an Event listener.
            • -
          • to fetch the Thing Description;
      -

      Future use cases

      -

      - The following use cases are being considered out of scope for this version: -

      -
        -
      • - Deploy, start, stop, delete scripts in local or remote runtimes in order to implement Thing lifecycle management. -
        • -
      -

      - Management use cases should be solved with exposing a special Thing that has an action for creating a Thing based on a TD. -

      -

    The WoT object

    -

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

    The WoT object is the API entry point and it is exposed by an implementation of the WoT Runtime. The WoT object does not expose properties, only methods for discovering, consuming and exposing a Thing.

    Browser implementations SHOULD use a namespace object such as `wot`, and [Node.js](https://nodejs.org/en/)-like runtimes MAY provide the API object through the [`require()`](https://nodejs.org/api/modules.html) or [`import`](http://www.ecma-international.org/ecma-262/6.0/#sec-imports) mechanism. @@ -448,18 +439,23 @@

    The ThingTemplate dictionary

    Examples

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

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

             let subscription = wot.discover({ method: "local" }).subscribe(
@@ -468,15 +464,28 @@ 
    The ThingTemplate dictionary
    
           () => { console.log("Discovery finished successfully");}
         );
    - 
    -        let subscription = wot.discover({ method: "nearby", description: {protocol: "BLE4.2"} }).subscribe(
+      
    +        let subscription = wot.discover({ method: "local" }).subscribe({
+          next: thing => { console.log("Found local Thing " + thing.url); },
+          error: err => { console.log("Discovery error: " + err.message); },
+          complete: () => { console.log("Discovery finished successfully");}
+        });
+      
    
+      
    +        let subscription = wot.discover({
+          method: "nearby",
+          constraints: [{ protocol: "BLE-4.2" }, { protocol: "NFC"}]
+        }).subscribe(
           thing => { console.log("Found nearby Thing " + thing.url); },
           error => { console.log("Discovery error: " + error.message); },
           () => { console.log("Discovery finished successfully");}
         );
       
    
       
    -        let subscription = wot.discover({ method: "other", description: { solution: "XYZ123", key: "..."} }).subscribe(
+        let subscription = wot.discover({
+          method: "other",
+          constraints: [{ solution: "XYZ123", key: "..."}]
+        }).subscribe(
           thing => { console.log("Found Thing " + thing.url); },
           error => { console.log("Discovery error: " + error.message); },
           () => { console.log("Discovery finished successfully");}
@@ -488,7 +497,7 @@ 
    The ThingTemplate dictionary
    
   
    
     
    The ConsumedThing interface
    
     
    
-      The ConsumedThing interface is a client API for sending requests to servers in order to retrieve or update properties, invoke Actions, and observe properties, Actions and Events.
+      The ConsumedThing interface is a client API for sending requests to servers in order to retrieve or update Properties, invoke Actions, and observe Properties, Actions and Events.
     
    
     
           interface ConsumedThing {
@@ -577,7 +586,7 @@ 
    Examples
    
               .then(() => { console.log("Temperature measurement started."); })
               .catch(e => {
                  console.log("Error starting measurement.");
-                 subscription.cancel();
+                 subscription.unsubscribe();
                })
           },
         )}).catch(error => {
@@ -671,8 +680,8 @@ 
    The ValueType type
    
         
    The ThingPropertyInit dictionary
    
         
               dictionary ThingPropertyInit: SemanticAnnotations {
-            DOMString name;
-            ValueType type;
+            required DOMString name;
+            required ValueType type;
             any value;
             boolean configurable = false;
             boolean enumerable = true;
@@ -715,7 +724,7 @@ 
    The ThingPropertyInit dictionary
    
         
    The ThingActionInit dictionary
    
         
               dictionary ThingActionInit: SemanticAnnotations {
-            DOMString name;
+            required DOMString name;
             ValueType inputDataDescription;
             ValueType outputDataDescription;
           };
@@ -724,8 +733,8 @@ 
    The ThingActionInit dictionary
    
         The ThingActionInit dictionary describes the arguments and the return value.
         
      
           
    • The name attribute provides the Action name.
      • 
-          
    • The inputDataDescription attribute provides the description of the input arguments (argument list is represented by an object).
      • 
-          
    • The outputDataDescription attribute provides the description of the returned data.
      • 
+          
    • The inputDataDescription attribute provides the description of the input arguments (argument list is represented by an object). If missing, it means the action does not accept arguments.
      • 
+          
    • The outputDataDescription attribute provides the description of the returned data. If missing, it means the action does not return data.
      • 
         
    
       
    
       
    
@@ -745,13 +754,13 @@ 
    The ThingActionInit dictionary
    
         
    The ThingEventInit dictionary
    
         
               dictionary ThingEventInit: SemanticAnnotations {
-            DOMString name;
+            required DOMString name;
             ValueType dataDescription;
           };
         
    
         
      
           
    • The name attribute represents the event name.
      • 
-          
    • The dataDescription attribute represents the type of the data that is attached to the event.
      • 
+          
    • The dataDescription attribute represents the type of the data that is attached to the event. If missing, it means the event does not carry data.
      •
    @@ -1004,9 +1013,6 @@

    The Observer interface

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

    -

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

    JSON-LD is defined in [[!JSON-LD]] as a JSON document that is augmented with support for Linked Data by providing a @context property with a defining URI . From 2bfe65fbbfc793641cfd0dcd720c38842852de1d Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 12 Feb 2018 13:49:18 +0200 Subject: [PATCH 167/464] Fix review comments: examples, TD alignment etc. Signed-off-by: Zoltan Kis --- index.html | 118 ++++++++++++++++++++++++----------------------------- 1 file changed, 53 insertions(+), 65 deletions(-) diff --git a/index.html b/index.html index 58057adf..a32dd9cc 100644 --- a/index.html +++ b/index.html @@ -329,17 +329,14 @@

    The ThingDescription type

    The produce() method

    Accepts a model argument of type ThingModel and returns an ExposedThing object, locally created based on the provided initialization parameters. An ExposedThing can be created in the following ways: -

    +

    @@ -444,7 +441,7 @@

    The ThingTemplate dictionary

    url: "http://directory.wotservice.org" }; let subscription = wot.discover(discoveryFilter).subscribe( - thing => { console.log("Found Thing " + thing.url); }, + thing => { console.log("Found Thing " + thing.name); }, error => { console.log("Discovery finished because an error: " + error.message); }, () => { console.log("Discovery finished successfully");} ); @@ -459,14 +456,14 @@

    The ThingTemplate dictionary

             let subscription = wot.discover({ method: "local" }).subscribe(
-          thing => { console.log("Found local Thing " + thing.url); },
+          thing => { console.log("Found local Thing " + thing.name); },
           error => { console.log("Discovery error: " + error.message); },
           () => { console.log("Discovery finished successfully");}
         );
       
             let subscription = wot.discover({ method: "local" }).subscribe({
-          next: thing => { console.log("Found local Thing " + thing.url); },
+          next: thing => { console.log("Found local Thing " + thing.name); },
           error: err => { console.log("Discovery error: " + err.message); },
           complete: () => { console.log("Discovery finished successfully");}
         });
@@ -476,7 +473,7 @@ 
    The ThingTemplate dictionary
    
           method: "nearby",
           constraints: [{ protocol: "BLE-4.2" }, { protocol: "NFC"}]
         }).subscribe(
-          thing => { console.log("Found nearby Thing " + thing.url); },
+          thing => { console.log("Found nearby Thing " + thing.name); },
           error => { console.log("Discovery error: " + error.message); },
           () => { console.log("Discovery finished successfully");}
         );
@@ -486,7 +483,7 @@ 
    The ThingTemplate dictionary
    
           method: "other",
           constraints: [{ solution: "XYZ123", key: "..."}]
         }).subscribe(
-          thing => { console.log("Found Thing " + thing.url); },
+          thing => { console.log("Found Thing " + thing.name); },
           error => { console.log("Discovery error: " + error.message); },
           () => { console.log("Discovery finished successfully");}
         );
@@ -575,7 +572,7 @@ 
    Examples
    
       
    
       
             wot.fetch("http://mmyservice.org/mySensor")
-        .then(td) => { consume(td)
+        .then(td) => { wot.consume(td)
         .then(thing => {
             console.log("Thing " + thing.name + " has been consumed.");
             let subscription = thing.onPropertyChange("temperature")
@@ -624,9 +621,9 @@ 
    The ExposedThing interface
    
         void setPropertyReadHandler(PropertyReadHandler readHandler, optional DOMString propertyName);
         void setPropertyWriteHandler(PropertyWriteHandler writeHandler, optional DOMString propertyName);
       };
-      callback ActionHandler = Promise<any> (any parameters);
-      callback PropertyReadHandler = Promise<any> (DOMString propertyName);
-      callback PropertyWriteHandler = Promise<void> (DOMString propertyName, any value);
+      callback ActionHandler = Promise<any>(any parameters);
+      callback PropertyReadHandler = Promise<any>();
+      callback PropertyWriteHandler = Promise<void>(any value);
     
    
 
     
     
    The start() method
    
@@ -683,9 +680,8 @@ 
    The ThingPropertyInit dictionary
    
             required DOMString name;
             required ValueType type;
             any value;
-            boolean configurable = false;
-            boolean enumerable = true;
             boolean writable = true;
+            boolean observable = true;
           };

    @@ -697,13 +693,10 @@

    The ThingPropertyInit dictionary

  • The value attribute represents the value of the Property.
  • - The configurable attribute defines whether the Property can be deleted from the object and whether its type can be changed. The default value is false. -
    • -
  • - The enumerable attribute defines whether the Property can be listed and iterated. The default value is true. + The writable attribute defines whether the Property can be updated. The default value is true.
  • - The writable attribute defines whether the Property can be updated. The default value is true. + The observable attribute defines whether the Property changes can be observed by an external client. The default value is true.

    • @@ -835,49 +828,44 @@

    Examples

    -        WoT.createExposedThing(thingDescription)
-          .then(function(thing) {
-            try {
-              // manually add properties, actions, and events
-              thing.addProperty({
-                name: "temperature",
-                value: "0",
-                type: "number",
-                writable: false
-                // use default values for the rest
-              });
-              thing.addEvent({
-                name: "onchange",
-                dataDescription: "number"
-              });
-              thing.addAction({
-                name: "reset",
-                action: () => { this.temperature = 0; }
-              });
-              // add server functionality
-              thing.setPropertyReadHandler(propertyName => {
-                console.log("Handling read request for " + propertyName);
-                return new Promise((resolve, reject) => {
-                    if (this.hasOwnProperty(propertyName))
-                      resolve(this[propertyName]);
-                    else
-                      reject('Property not found');
-                  },
-                  e => {
-                    console.log("Error");
-                  });
+        let thing = WoT.produce(thingDescription);
+        try {
+          // manually add properties, actions, and events
+          thing.addProperty({
+            name: "temperature",
+            value: "0",
+            type: "number",
+            writable: false
+            // use default values for the rest
+          });
+          thing.addEvent({
+            name: "onchange",
+            dataDescription: "number"
+          });
+          thing.addAction({
+            name: "reset",
+            action: () => { this.temperature = 0; }
+          });
+          // add server functionality
+          thing.setPropertyReadHandler(propertyName => {
+            console.log("Handling read request for " + propertyName);
+            return new Promise((resolve, reject) => {
+                if (this.hasOwnProperty(propertyName))
+                  resolve(this[propertyName]);
+                else
+                  reject('Property not found');
+              },
+              e => {
+                console.log("Error");
               });
-            } catch (err) {
-               console.log("Thing creation error.");
-            }
-            thing.start()
-            .then (() => {
-              thing.register();
-            });
-          })
-          .catch (err => {
-            console.log("Error");
           });
+        } catch (err) {
+           console.log("Thing creation error.");
+        }
+        thing.start()
+        .then (() => {
+          thing.register();
+        });
       
    @@ -986,9 +974,9 @@ 
    The Subscription interface
    -

    The Observer interface

    +

    The Observable interface

    - The Observable interface enabled subscribing to pushed data notifications by the subscribe() method: + The Observable interface enabled subscribing to pushed data notifications by the subscribe() method:

    • If the subscribe() method is called with an Observer object, initialize the data, error and completion handling callbacks from that object, or throw on error. From ef36afb1da7d8c7d046b8d6df621f326daed9f02 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Tue, 13 Feb 2018 14:41:15 +0200 Subject: [PATCH 168/464] Addressed review comments. Changed ValueType to DataSchema. Clarified discovery constraint matching. Signed-off-by: Zoltan Kis --- index.html | 109 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 64 insertions(+), 45 deletions(-) diff --git a/index.html b/index.html index a32dd9cc..d9c5ca0a 100644 --- a/index.html +++ b/index.html @@ -187,10 +187,10 @@
    • Add a Property definition to the Thing.
    • Add an Event definition to the Thing.
    • Add an Action definition to the Thing.
      • -
    • Attach semantic information to the Thing
      • -
    • Attach semantic information to an Action
      • -
    • Attach semantic information to a Property
      • -
    • Attach semantic information to an Event
      • +
    • Attach semantic information to the Thing.
      • +
    • Attach semantic information to an Action.
      • +
    • Attach semantic information to a Property.
      • +
    • Attach semantic information to an Event.
    • Emit an Event, i.e. notify all listeners subscribed to that Event.
      • @@ -235,7 +235,7 @@

      The WoT object

      - The algorithms for the WoT methods will be specified later. + The algorithms for the WoT methods will be specified later, including error handling and security considerations.

      The discover() method

      @@ -286,6 +286,9 @@

      The ThingFilter dictionary

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

      +

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

      The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, such as a Thing Directory or a Thing.

      @@ -293,13 +296,18 @@

      The ThingFilter dictionary

      The query property represents a query string accepted by the implementation, for instance a SPARQL query.

      - The constraints property represents additional information for the discovery method in the form of a list of sets of key-value pairs, defined based on the semantic metadata of the Thing Description. The sequence elements are in OR relationship, and within an element the key-value pairs define AND type constraints. -

      -

      - The DiscoveryMethod enumeration can be extended by the Thing Description with values that are not specified here. This extensibility of DiscoveryMethod by proprietary or private methods is a working assumption until consensus is formed and may be removed later. + The constraints property represents additional information for the discovery method in the form of a list of sets of property-value pairs (dictionaries). The list elements (dictionaries) are in OR relationship, and within a constraint dictionary the key-value pairs are in AND relationship. Implementations SHOULD make the following mapping from the constraint dictionaries to SemanticAnnotations: for each property-value pair in a constraint dictionary, +

        +
      • + Each property name in the constraint dictionary SHOULD match the either the `name` property of a defined SemanticType on the target Thing object, or the name of a Property on the target Thing. +
        • +
      • + When the name matches, the values are compared. If the values match, the constraint is matched. +
        • +

      - The ThingFilter dictionary may be extended later with further attributes.

      + Semantic annotations need revisiting in order to simplify their representation. In the [[WOT-TD]] specification they represent the `@type` construct. At the moment only `@context`, `@type` and `@id` constructs are used in the TD.

    @@ -331,7 +339,7 @@

    The ThingDescription type

    Accepts a model argument of type ThingModel and returns an ExposedThing object, locally created based on the provided initialization parameters. An ExposedThing can be created in the following ways:
    1. - from an initial model (name and semantic annotations), then adding properties, actions, events and request handlers; + from an initial model (including a user given name and semantic annotations), then adding properties, actions, events and request handlers;
    2. from a Thing Description (possibly of a ConsumedThing object), then adding request handlers. @@ -415,7 +423,7 @@

      The SemanticMetadata dictionary

      The ThingTemplate dictionary

      - A Thing Template is a dictionary that provides the semantic types and semantic metadata at the ExposedThing description's root level. + A Thing Template is a dictionary that provides a user given name, and the semantic types and semantic metadata attached to the ExposedThing Thing Description's root level. 

               dictionary ThingTemplate: SemanticAnnotations {
@@ -499,7 +507,8 @@ 
      The ConsumedThing interface
      
     
             interface ConsumedThing {
         readonly attribute DOMString name;
-        readonly attribute ThingDescription td;
+        void setName(DOMString name);
+        ThingDescription getThingDescription();
         Promise<any> invokeAction(DOMString name, any parameters);
         Promise<void> writeProperty(DOMString name, any value);
         Promise<any> readProperty(DOMString name);
@@ -509,17 +518,29 @@ 
      The ConsumedThing interface
      
       };
     
      
     
      
-      Represents a local proxy object of the remote Thing.
+      ConsumedThing represents a local proxy object of the remote Thing.
       
        
-        
      • The name read-only attribute represents the name of the Thing.
        • 
         
      • 
-          The td attribute read-only attribute represents the description of the Thing.
-          
        
-            Parsing and exposing Thing Descriptions is discussed in [Issue 38](https://github.com/w3c/wot-scripting-api/issues/38).
        
+          The name read-only attribute represents the user given name of the Thing.
         
        • 
       
      
     
      
 
+    
       
      The setName() method
      
+      
      
+        Takes a name parameter and sets the name of the Thing, as used in applications. Applications can provide a maximum 128 bytes long name, but implementations may reject (by throwing a `RangeError`) or truncate the provided name, depending on the capabilities of the underlying platform. Setting name throws `TypeError` on other invalid (not string) input.
+      
      
+    
      
+
+    
       
      The getThingDescription() method
      
+      
      
+        Returns the Thing Description of the Thing.
+      
      
+      
      
+        In this version, introspection based on TD is out of scope. Parsing and exposing Thing Descriptions is discussed in [Issue 38](https://github.com/w3c/wot-scripting-api/issues/38).
+      
      
+    
      
+
     
       
      The invokeAction() method
      
       
      
         Takes the Action name from the name argument and the list of parameters, then requests from the underlying platform and the Protocol Bindings to invoke the Action on the remote Thing and return the result. Returns a Promise that resolves with the return value or rejects with an Error.
@@ -571,22 +592,20 @@ 
      Examples
      
         Below a ConsumedThing interface example is given.
       
      
       
      -        wot.fetch("http://mmyservice.org/mySensor")
-        .then(td) => { wot.consume(td)
-        .then(thing => {
-            console.log("Thing " + thing.name + " has been consumed.");
-            let subscription = thing.onPropertyChange("temperature")
-              .subscribe(function(value) {
-                console.log("Temperature + " has changed to " + value);
-              });
-            thing.invokeAction("startMeasurement", { units: "Celsius" })
-              .then(() => { console.log("Temperature measurement started."); })
-              .catch(e => {
-                 console.log("Error starting measurement.");
-                 subscription.unsubscribe();
-               })
-          },
-        )}).catch(error => {
+        wot.fetch("http://mmyservice.org/mySensor").then(td => {
+          let thing = wot.consume(td);
+          console.log("Thing " + thing.name + " has been consumed.");
+          let subscription = thing.onPropertyChange("temperature")
+            .subscribe(function(value) {
+              console.log("Temperature + " has changed to " + value);
+            });
+          thing.invokeAction("startMeasurement", { units: "Celsius" })
+            .then(() => { console.log("Temperature measurement started."); })
+            .catch(e => {
+               console.log("Error starting measurement.");
+               subscription.unsubscribe();
+             })
+        }).catch(error => {
           console.log("Error during fetch or consume: " + error.message);
         });
       
      
@@ -656,16 +675,16 @@ 
      The ExposedThing interface
      
       
      
     
      
 
-    
      
-      
      The ValueType type
      
+    
      
+      
      The DataSchema type
      
       
      -        typedef any ValueType;
+        typedef USVString DataSchema;
       
      
       
      
-        The ValueType type represents a type name specified in the Thing Description.
+        The DataSchema type represents a type name specified in the Thing Description in a serialized form, for instance JSON Schema.
       
      
       
      
-        ValueType is under development, currently it can denote any type supported by the Thing Description and the WoT Runtime, such as "boolean", "number", "string", "array", or "object".
+        DataSchema is under development, currently it can denote any type supported by the Thing Description and the WoT Runtime, such as simple type like "boolean", "number", "string", or "array", or "object" that may specify value range etc.
       
      
     
      
 
@@ -678,7 +697,7 @@ 
      The ThingPropertyInit dictionary
      
         
                 dictionary ThingPropertyInit: SemanticAnnotations {
             required DOMString name;
-            required ValueType type;
+            required DataSchema type;
             any value;
             boolean writable = true;
             boolean observable = true;
@@ -718,8 +737,8 @@ 
      The ThingActionInit dictionary
      
         
                 dictionary ThingActionInit: SemanticAnnotations {
             required DOMString name;
-            ValueType inputDataDescription;
-            ValueType outputDataDescription;
+            DataSchema inputDataDescription;
+            DataSchema outputDataDescription;
           };
       
      
       
      
@@ -748,7 +767,7 @@ 
      The ThingEventInit dictionary
      
         
                 dictionary ThingEventInit: SemanticAnnotations {
             required DOMString name;
-            ValueType dataDescription;
+            DataSchema dataDescription;
           };
         
      
         
        
@@ -920,7 +939,7 @@ 
        Examples
        
   
        
     
        Observables
        
     
        
-      Observables are proposed to be included in ECMAScript and are used for handling pushed data associated with various possible sources, for instance events, timers, streams, etc. A minimal required implementation is described here.
+      Observables are proposed to be included in ECMAScript and are used for handling pushed data associated with various possible sources, for instance events, timers, streams, etc. A minimal required implementation is described here.
     
        
     
        
       This section is informal and contains rather laconic information for implementations on what to support for interoperability.
@@ -989,7 +1008,7 @@ 
        The Observable interface
        
           
         
      
     
      
-
      +

    Security and Privacy

    From 168d9518bc116800aefbe23895c18ec9ef180a51 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 14 Feb 2018 17:08:48 +0100 Subject: [PATCH 169/464] fix respec issues as suggested in https://github.com/w3c/respec/issues/1508#issuecomment-365604286 --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index d9c5ca0a..7776bd7e 100644 --- a/index.html +++ b/index.html @@ -993,7 +993,7 @@

    The Subscription interface

    -

    The Observable interface

    +

    The Observable interface

    The Observable interface enabled subscribing to pushed data notifications by the subscribe() method:

      From f0c17b1dd378854469456193fc5218ae76b8dbd9 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Thu, 15 Feb 2018 14:03:53 +0200 Subject: [PATCH 170/464] Add support for chaining in ExposedThing Signed-off-by: Zoltan Kis --- index.html | 41 +++++++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/index.html b/index.html index d9c5ca0a..9b01b08a 100644 --- a/index.html +++ b/index.html @@ -630,15 +630,16 @@

      The ExposedThing interface

      Promise<void> unregister(optional USVString directory); Promise<void> emitEvent(DOMString eventName, any payload); // define Thing Description modifiers - void addProperty(ThingPropertyInit property); - void removeProperty(DOMString name); - void addAction(ThingActionInit action); - void removeAction(DOMString name); - void addEvent(ThingEventInit event); - void removeEvent(DOMString name); - void setActionHandler(ActionHandler action, optional DOMString actionName); - void setPropertyReadHandler(PropertyReadHandler readHandler, optional DOMString propertyName); - void setPropertyWriteHandler(PropertyWriteHandler writeHandler, optional DOMString propertyName); + ExposedThing addProperty(ThingPropertyInit property); + ExposedThing removeProperty(DOMString name); + ExposedThing addAction(ThingActionInit action); + ExposedThing removeAction(DOMString name); + ExposedThing addEvent(ThingEventInit event); + ExposedThing removeEvent(DOMString name); + // define request handlers + ExposedThing setActionHandler(ActionHandler action, optional DOMString actionName); + ExposedThing setPropertyReadHandler(PropertyReadHandler readHandler, optional DOMString propertyName); + ExposedThing setPropertyWriteHandler(PropertyWriteHandler writeHandler, optional DOMString propertyName); }; callback ActionHandler = Promise<any>(any parameters); callback PropertyReadHandler = Promise<any>(); @@ -690,9 +691,9 @@

      The DataSchema type

      The addProperty() method

      - Adds a Property defined by the argument and updates the Thing Description. + Adds a Property defined by the argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.

      -
      +

      The ThingPropertyInit dictionary

                 dictionary ThingPropertyInit: SemanticAnnotations {
@@ -724,13 +725,13 @@ 
      The ThingPropertyInit dictionary
      
 
     
       
      The removeProperty() method
      
       
      
-        Removes the Property specified by the name argument and updates the Thing Description.
+        Removes the Property specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
      
     
      
 
     
       
      The addAction() method
      
       
      
-        Adds an Action to the Thing object as defined by the action argument of type ThingActionInit and updates the Thing Description.
+        Adds an Action to the Thing object as defined by the action argument of type ThingActionInit and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
      
       
      
         
      The ThingActionInit dictionary
      
@@ -754,13 +755,13 @@ 
      The ThingActionInit dictionary
      
 
     
       
      The removeAction() method
      
       
      
-        Removes the Action specified by the name argument and updates the Thing Description.
+        Removes the Action specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
      
     
      
 
     
       
      The addEvent() method
      
       
      
-        Adds an event to the Thing object as defined by the event argument of type ThingEventInit and updates the Thing Description.
+        Adds an event to the Thing object as defined by the event argument of type ThingEventInit and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
      
       
      
         
      The ThingEventInit dictionary
      
@@ -779,7 +780,7 @@ 
      The ThingEventInit dictionary
      
 
     
       
      The removeEvent() method
      
       
      
-        Removes the event specified by the name argument and updates the Thing Description.
+        Removes the event specified by the name argument and updates the Thing Description. Returns a reference to the same object for supporting chaining.
       
      
     
      
 
@@ -809,7 +810,7 @@ 
      The PropertyWriteHandler callback
      
 
     
       
      The setActionHandler() method
      
       
      
-        Takes a actionName as an optional string argument, and an action argument of type ActionHandler. Sets the handler function for the specified Action matched by actionName if actionName is specified, otherwise sets it for any action. Throws on error.
+        Takes a actionName as an optional string argument, and an action argument of type ActionHandler. Sets the handler function for the specified Action matched by actionName if actionName is specified, otherwise sets it for any action. Throws on error. Returns a reference to the same object for supporting chaining.
       
      
       
      
         If provided, this callback function will implement invoking an Action and SHOULD be called by implementations when a request for invoking a Action is received from the underlying platform.
@@ -821,7 +822,7 @@ 
      The PropertyWriteHandler callback
      
 
     
       
      The setPropertyReadHandler() method
      
       
      
-        Takes a propertyName as an optional string argument, and a readHandler argument of type PropertyReadHandler. Sets the handler function for reading the specified Property matched by propertyName if propertyName is specified, otherwise sets it for reading any property. Throws on error.
+        Takes a propertyName as an optional string argument, and a readHandler argument of type PropertyReadHandler. Sets the handler function for reading the specified Property matched by propertyName if propertyName is specified, otherwise sets it for reading any property. Throws on error. Returns a reference to the same object for supporting chaining.
       
      
       
      
         If provided, this callback function will implement reading a Property and SHOULD be called by implementations when a request for reading a Property is received from the underlying platform.
@@ -833,7 +834,7 @@ 
      The PropertyWriteHandler callback
      
 
     
       
      The setPropertyWriteHandler() method
      
       
      
-        Takes a propertyName as an optional string argument, and a writeHandler argument of type PropertyWriteHandler. Sets the handler function for writing the specified Property matched by propertyName if the propertyName is specified, otherwise sets it for writing any properties. Throws on error.
+        Takes a propertyName as an optional string argument, and a writeHandler argument of type PropertyWriteHandler. Sets the handler function for writing the specified Property matched by propertyName if the propertyName is specified, otherwise sets it for writing any properties. Throws on error. Returns a reference to the same object for supporting chaining.
       
      
       
      
         There SHOULD be at most one write handler for any given Property. If no write handler is initialized for any given Property, implementations SHOULD implement default property update and notifying observers.
@@ -936,7 +937,7 @@ 
      Examples
      
     
       
   
       
 
-  
      
+  
      
     
      Observables
      
     
      
       Observables are proposed to be included in ECMAScript and are used for handling pushed data associated with various possible sources, for instance events, timers, streams, etc. A minimal required implementation is described here.

From c67f89ea7baf0628ca1c6ca3b8a8e3a698e8b774 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Fri, 16 Feb 2018 11:01:08 +0200
Subject: [PATCH 171/464] Use schema, inputSchema, outputSchema from updated TD
 spec

Signed-off-by: Zoltan Kis 
---
 index.html | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/index.html b/index.html
index 8c5d14c2..ee3fd991 100644
--- a/index.html
+++ b/index.html
@@ -682,7 +682,7 @@ 
      The DataSchema type
      
         typedef USVString DataSchema;

      - The DataSchema type represents a type name specified in the Thing Description in a serialized form, for instance JSON Schema. + The DataSchema type represents a data type specified in the Thing Description in a serialized form.

      DataSchema is under development, currently it can denote any type supported by the Thing Description and the WoT Runtime, such as simple type like "boolean", "number", "string", or "array", or "object" that may specify value range etc. @@ -698,7 +698,7 @@

      The ThingPropertyInit dictionary

                 dictionary ThingPropertyInit: SemanticAnnotations {
             required DOMString name;
-            required DataSchema type;
+            required DataSchema schema;
             any value;
             boolean writable = true;
             boolean observable = true;
@@ -709,7 +709,7 @@ 
      The ThingPropertyInit dictionary
      
           
        
             
      • The name attribute represents the name of the Property.
        • 
             
      • 
-              The type attribute represents the type for the Property.
+              The schema attribute represents the data type for the Property described by DataSchema.
             
        • 
             
      • The value attribute represents the value of the Property.
        • 
             
      • 
@@ -738,16 +738,16 @@ 
        The ThingActionInit dictionary
        
         
                   dictionary ThingActionInit: SemanticAnnotations {
             required DOMString name;
-            DataSchema inputDataDescription;
-            DataSchema outputDataDescription;
+            DataSchema inputSchema;
+            DataSchema outputSchema;
           };
       
        
       
        
         The ThingActionInit dictionary describes the arguments and the return value.
         
          
           
        • The name attribute provides the Action name.
          • 
-          
        • The inputDataDescription attribute provides the description of the input arguments (argument list is represented by an object). If missing, it means the action does not accept arguments.
          • 
-          
        • The outputDataDescription attribute provides the description of the returned data. If missing, it means the action does not return data.
          • 
+          
        • The inputSchema attribute provides the description of the input arguments (argument list is represented by an object). If missing, it means the action does not accept arguments.
          • 
+          
        • The outputSchema attribute provides the description of the returned data. If missing, it means the action does not return data.
          •
      @@ -768,12 +768,12 @@

      The ThingEventInit dictionary

                 dictionary ThingEventInit: SemanticAnnotations {
             required DOMString name;
-            DataSchema dataDescription;
+            DataSchema schema;
           };
      • The name attribute represents the event name.
        • -
      • The dataDescription attribute represents the type of the data that is attached to the event. If missing, it means the event does not carry data.
        • +
      • The schema attribute represents the type of the data that is attached to the event. If missing, it means the event does not carry data.
      @@ -854,13 +854,13 @@

      Examples

      thing.addProperty({ name: "temperature", value: "0", - type: "number", + schema: "number", writable: false // use default values for the rest }); thing.addEvent({ name: "onchange", - dataDescription: "number" + schema: "number" }); thing.addAction({ name: "reset", From a76fbcac908838768e93815b0d249ba3f5ca40e7 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Fri, 16 Feb 2018 15:26:06 +0200 Subject: [PATCH 172/464] Add support for TD links. Fix schema examples. Signed-off-by: Zoltan Kis --- index.html | 47 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index ee3fd991..1ec46daa 100644 --- a/index.html +++ b/index.html @@ -173,6 +173,8 @@
    • Invoke an Action.
    • Observe Events emitted by the Thing.
    • Observe changes to the Thing Description of the Thing.
      • +
    • Get the Thing Description.
      • +
    • Get the list of linked resources based on the Thing Description.
    @@ -509,6 +511,7 @@

    The ConsumedThing interface

    readonly attribute DOMString name; void setName(DOMString name); ThingDescription getThingDescription(); + sequence<TDLink> getLinks(); Promise<any> invokeAction(DOMString name, any parameters); Promise<void> writeProperty(DOMString name, any value); Promise<any> readProperty(DOMString name); @@ -541,6 +544,41 @@

    The ConsumedThing interface

    +

    The getLinks() method

    +

    + Returns the list of linked resources in Thing Description of the Thing in the form of a list of TDLink objects. +

    +
    +

    The TDLink dictionary

    +

    + Contains a hyperlink reference, a relation type and a media type. +

    + 
    +          dictionary TDLink {
+              required USVString href;
+              USVString mediaType;
+              DOMString rel;
+          };
+
    +

    The TDLink dictionary contains the following properties: +

    +

    +
    +
    + + + +

    The invokeAction() method

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

    The DataSchema type

    The DataSchema type represents a data type specified in the Thing Description in a serialized form.

    - DataSchema is under development, currently it can denote any type supported by the Thing Description and the WoT Runtime, such as simple type like "boolean", "number", "string", or "array", or "object" that may specify value range etc. + DataSchema is under development, currently it can denote any type supported by the Thing Description and the WoT Runtime.

    @@ -854,13 +892,13 @@

    Examples

    thing.addProperty({ name: "temperature", value: "0", - schema: "number", + schema: '{ \"type\": \"number\" }', writable: false // use default values for the rest }); thing.addEvent({ name: "onchange", - schema: "number" + schema: '{ \"type\": \"number\" }' }); thing.addAction({ name: "reset", @@ -1125,6 +1163,9 @@

    The Observable interface

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

    +

    + The terms hyperlink reference and relation type are defined in [[!HTML5]] and RFC8288. +

    From a38a250800f3945f656bc8982daf2a3283e83775 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 19 Feb 2018 15:30:53 +0200 Subject: [PATCH 173/464] Remove ConsumedThing.name. Move getLinks() to experimental extensions section. Add getProperties(), getActions(), getEvents(). Signed-off-by: Zoltan Kis --- index.html | 144 +++++++++++++++++++++++++++++------------------------ 1 file changed, 80 insertions(+), 64 deletions(-) diff --git a/index.html b/index.html index 1ec46daa..0b2adb2a 100644 --- a/index.html +++ b/index.html @@ -508,10 +508,7 @@

    The ConsumedThing interface

           interface ConsumedThing {
-        readonly attribute DOMString name;
-        void setName(DOMString name);
         ThingDescription getThingDescription();
-        sequence<TDLink> getLinks();
         Promise<any> invokeAction(DOMString name, any parameters);
         Promise<void> writeProperty(DOMString name, any value);
         Promise<any> readProperty(DOMString name);
@@ -522,19 +519,8 @@ 
    The ConsumedThing interface

    ConsumedThing represents a local proxy object of the remote Thing. -

      -
    • - The name read-only attribute represents the user given name of the Thing. -
      • -

    -

    The setName() method

    -

    - Takes a name parameter and sets the name of the Thing, as used in applications. Applications can provide a maximum 128 bytes long name, but implementations may reject (by throwing a `RangeError`) or truncate the provided name, depending on the capabilities of the underlying platform. Setting name throws `TypeError` on other invalid (not string) input. -

    -
    -

    The getThingDescription() method

    Returns the Thing Description of the Thing. @@ -544,41 +530,6 @@

    The ConsumedThing interface

    -

    The getLinks() method

    -

    - Returns the list of linked resources in Thing Description of the Thing in the form of a list of TDLink objects. -

    -
    -

    The TDLink dictionary

    -

    - Contains a hyperlink reference, a relation type and a media type. -

    - 
    -          dictionary TDLink {
-              required USVString href;
-              USVString mediaType;
-              DOMString rel;
-          };
-
    -

    The TDLink dictionary contains the following properties: -

    -

    -
    -
    - - - -

    The invokeAction() method

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

    The ExposedThing interface

    Promise<void> unregister(optional USVString directory); Promise<void> emitEvent(DOMString eventName, any payload); // define Thing Description modifiers - ExposedThing addProperty(ThingPropertyInit property); + ExposedThing addProperty(ThingProperty property); ExposedThing removeProperty(DOMString name); - ExposedThing addAction(ThingActionInit action); + ExposedThing addAction(ThingAction action); ExposedThing removeAction(DOMString name); - ExposedThing addEvent(ThingEventInit event); + ExposedThing addEvent(ThingEvent event); ExposedThing removeEvent(DOMString name); // define request handlers ExposedThing setActionHandler(ActionHandler action, optional DOMString actionName); @@ -731,10 +682,10 @@

    The DataSchema type

    Adds a Property defined by the argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.

    -
    -

    The ThingPropertyInit dictionary

    +
    +

    The ThingProperty dictionary

    -          dictionary ThingPropertyInit: SemanticAnnotations {
+          dictionary ThingProperty: SemanticAnnotations {
             required DOMString name;
             required DataSchema schema;
             any value;
@@ -769,19 +720,19 @@ 
    The ThingPropertyInit dictionary
    
 
     
     
    The addAction() method
    
       
    
-        Adds an Action to the Thing object as defined by the action argument of type ThingActionInit and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+        Adds an Action to the Thing object as defined by the action argument of type ThingAction and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
    
-      
    
-        
    The ThingActionInit dictionary
    
+      
    
+        
    The ThingAction dictionary
    
         
    -          dictionary ThingActionInit: SemanticAnnotations {
+          dictionary ThingAction: SemanticAnnotations {
             required DOMString name;
             DataSchema inputSchema;
             DataSchema outputSchema;
           };
       
    
       
    
-        The ThingActionInit dictionary describes the arguments and the return value.
+        The ThingAction dictionary describes the arguments and the return value.
         
      
           
    • The name attribute provides the Action name.
      • 
           
    • The inputSchema attribute provides the description of the input arguments (argument list is represented by an object). If missing, it means the action does not accept arguments.
      • 
@@ -799,12 +750,12 @@ 
      The ThingActionInit dictionary
      
 
     
       
      The addEvent() method
      
       
      
-        Adds an event to the Thing object as defined by the event argument of type ThingEventInit and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+        Adds an event to the Thing object as defined by the event argument of type ThingEvent and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
      
-      
      
-        
      The ThingEventInit dictionary
      
+      
      
+        
      The ThingEvent dictionary
      
         
      -          dictionary ThingEventInit: SemanticAnnotations {
+          dictionary ThingEvent: SemanticAnnotations {
             required DOMString name;
             DataSchema schema;
           };
@@ -975,6 +926,71 @@ 
      Examples
      
     
       
   
       
 
+  
      
+    
      Experimental extensions to the ConsumedThing interface
      
+    
      
+      The ThingDescription related functionality, such as enumerating Properties, Actions, Events and links (introspection) is an API extension that is out of scope for this specification. However, the draft interfaces are defined here for informative purposes.
+    
      
+    
      +      partial interface ConsumedThing {
+        sequence<ThingProperty> getProperties();
+        sequence<ThingAction> getActions();
+        sequence<ThingEvent> getEvents();
+        sequence<TDLink> getLinks();
+      };
+    
      
+
+    
       
      The getProperties() method
      
+      
      
+        Returns the list of Properties defined in the Thing Description of the Thing in the form of a list of ThingProperty objects.
+      
      
+    
      
+
+    
       
      The getActions() method
      
+      
      
+        Returns the list of Actions defined in the Thing Description of the Thing in the form of a list of ThingAction objects.
+      
      
+    
      
+
+    
       
      The getEvents() method
      
+      
      
+        Returns the list of Events defined in the Thing Description of the Thing in the form of a list of ThingEvent objects.
+      
      
+    
      
+
+    
       
      The getLinks() method
      
+      
      
+        Returns the list of linked resources in Thing Description of the Thing in the form of a list of TDLink objects.
+      
      
+      
      
+        
      The TDLink dictionary
      
+        
      
+          Contains a hyperlink reference, a relation type and a media type.
+        
      
+        
      +          dictionary TDLink {
+              required USVString href;
+              USVString mediaType;
+              DOMString rel;
+          };
+        
      
+        
      The TDLink dictionary contains the following properties:
+          
        
+            
      • 
+              The href attribute represents a hyperlink reference.
+            
        • 
+            
      • 
+              The rel attribute represents a relation type.
+            
        • 
+            
      • 
+              The mediaType attribute represents a IANA media type. For TDs there will be registered media types, so applications will be able to check whether an `href` link points to a TD, i.e. whether the link is fetcheable with this API.
+            
        • 
+          
      
+        
      
+      
       
+    
      
+  
      
+
   
      
     
      Observables
      
     
      

From 2870cab30f5103a9eae717df6a92938c1c04bdbd Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Tue, 20 Feb 2018 13:39:15 +0200
Subject: [PATCH 174/464] Fix examples containing thing.name. Add ed note about
 constraints.

Signed-off-by: Zoltan Kis 
---
 index.html | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/index.html b/index.html
index 0b2adb2a..c0fcc675 100644
--- a/index.html
+++ b/index.html
@@ -308,6 +308,9 @@ 
      The ThingFilter dictionary
      
             
           
    
         
    
+        
    
+          Constraints are experimental feature, implementations are not required to support them.
+        
    
         
    
           Semantic annotations need revisiting in order to simplify their representation. In the [[WOT-TD]] specification they represent the `@type` construct. At the moment only `@context`, `@type` and `@id` constructs are used in the TD.
         
    
@@ -451,7 +454,7 @@ 
    The ThingTemplate dictionary
    
           url: "http://directory.wotservice.org"
         };
         let subscription = wot.discover(discoveryFilter).subscribe(
-          thing => { console.log("Found Thing " + thing.name); },
+          thing => { console.log("Found Thing " + await thing.readProperty('name'); },
           error => { console.log("Discovery finished because an error: " + error.message); },
           () => { console.log("Discovery finished successfully");}
         );
@@ -466,14 +469,14 @@ 
    The ThingTemplate dictionary
    
       
    
       
             let subscription = wot.discover({ method: "local" }).subscribe(
-          thing => { console.log("Found local Thing " + thing.name); },
+          thing => { console.log("Found local Thing " + await thing.readProperty('name'); },
           error => { console.log("Discovery error: " + error.message); },
           () => { console.log("Discovery finished successfully");}
         );
       
    
       
             let subscription = wot.discover({ method: "local" }).subscribe({
-          next: thing => { console.log("Found local Thing " + thing.name); },
+          thing => { console.log("Found local Thing " + await thing.readProperty('name'); },
           error: err => { console.log("Discovery error: " + err.message); },
           complete: () => { console.log("Discovery finished successfully");}
         });
@@ -483,7 +486,7 @@ 
    The ThingTemplate dictionary
    
           method: "nearby",
           constraints: [{ protocol: "BLE-4.2" }, { protocol: "NFC"}]
         }).subscribe(
-          thing => { console.log("Found nearby Thing " + thing.name); },
+          thing => { console.log("Found nearby Thing " + await thing.readProperty('name'); },
           error => { console.log("Discovery error: " + error.message); },
           () => { console.log("Discovery finished successfully");}
         );
@@ -493,7 +496,7 @@ 
    The ThingTemplate dictionary
    
           method: "other",
           constraints: [{ solution: "XYZ123", key: "..."}]
         }).subscribe(
-          thing => { console.log("Found Thing " + thing.name); },
+          thing => { console.log("Found Thing " + await thing.readProperty('name'); },
           error => { console.log("Discovery error: " + error.message); },
           () => { console.log("Discovery finished successfully");}
         );
@@ -581,8 +584,10 @@ 
    Examples
    
         Below a ConsumedThing interface example is given.
       
    
       
    -        wot.fetch("http://mmyservice.org/mySensor").then(td => {
+        try {
+          let td = await wot.fetch("http://mmyservice.org/mySensor");
           let thing = wot.consume(td);
+          let thingName = await thing.readProperty('name');
           console.log("Thing " + thing.name + " has been consumed.");
           let subscription = thing.onPropertyChange("temperature")
             .subscribe(function(value) {
@@ -594,9 +599,9 @@ 
    Examples
    
                console.log("Error starting measurement.");
                subscription.unsubscribe();
              })
-        }).catch(error => {
+        } catch(error) {
           console.log("Error during fetch or consume: " + error.message);
-        });
+        };
       
    
     
     
   
     
@@ -885,8 +890,7 @@ 
    Examples
    
         WoT.fetch("http://myservice.org/mySensor/description")
         .then(td => {
           let e_thing = WoT.produce(td);
-          // properties, actions and events are added based on the TD
-          console.log("created " + thing.name });
+          // properties, actions and events have been added based on the TD
           // now add the requests handlers
           try {
             e_thing.setPropertyReadHandler(propertyName => {

From 7631629b42228133563196883e1b6d0862703ebc Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Wed, 21 Feb 2018 16:59:24 +0200
Subject: [PATCH 175/464] Re-add ConsumedThing.name

Signed-off-by: Zoltan Kis 
---
 index.html | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/index.html b/index.html
index c0fcc675..3ac75bd3 100644
--- a/index.html
+++ b/index.html
@@ -454,7 +454,7 @@ 
    The ThingTemplate dictionary
    
           url: "http://directory.wotservice.org"
         };
         let subscription = wot.discover(discoveryFilter).subscribe(
-          thing => { console.log("Found Thing " + await thing.readProperty('name'); },
+          thing => { console.log("Found Thing " + thing.name); },
           error => { console.log("Discovery finished because an error: " + error.message); },
           () => { console.log("Discovery finished successfully");}
         );
@@ -469,14 +469,14 @@ 
    The ThingTemplate dictionary
    
       
    
       
             let subscription = wot.discover({ method: "local" }).subscribe(
-          thing => { console.log("Found local Thing " + await thing.readProperty('name'); },
+          thing => { console.log("Found local Thing " + thing.name); },
           error => { console.log("Discovery error: " + error.message); },
           () => { console.log("Discovery finished successfully");}
         );
       
    
       
             let subscription = wot.discover({ method: "local" }).subscribe({
-          thing => { console.log("Found local Thing " + await thing.readProperty('name'); },
+          thing => { console.log("Found local Thing " + thing.name); },
           error: err => { console.log("Discovery error: " + err.message); },
           complete: () => { console.log("Discovery finished successfully");}
         });
@@ -486,7 +486,7 @@ 
    The ThingTemplate dictionary
    
           method: "nearby",
           constraints: [{ protocol: "BLE-4.2" }, { protocol: "NFC"}]
         }).subscribe(
-          thing => { console.log("Found nearby Thing " + await thing.readProperty('name'); },
+          thing => { console.log("Found nearby Thing " + thing.name); },
           error => { console.log("Discovery error: " + error.message); },
           () => { console.log("Discovery finished successfully");}
         );
@@ -496,7 +496,7 @@ 
    The ThingTemplate dictionary
    
           method: "other",
           constraints: [{ solution: "XYZ123", key: "..."}]
         }).subscribe(
-          thing => { console.log("Found Thing " + await thing.readProperty('name'); },
+          thing => { console.log("Found Thing " + thing.name); },
           error => { console.log("Discovery error: " + error.message); },
           () => { console.log("Discovery finished successfully");}
         );
@@ -511,6 +511,7 @@ 
    The ConsumedThing interface
    
     
    
     
           interface ConsumedThing {
+        readonly attribute DOMString name;
         ThingDescription getThingDescription();
         Promise<any> invokeAction(DOMString name, any parameters);
         Promise<void> writeProperty(DOMString name, any value);
@@ -524,6 +525,11 @@ 
    The ConsumedThing interface
    
       ConsumedThing represents a local proxy object of the remote Thing.
     
    
 
+    
     
    The name property
    
+      
    
+        The `name` property represents the name of the Thing as specified in the TD. In this version it is read only.
+      
    
+    
    
     
     
    The getThingDescription() method
    
       
    
         Returns the Thing Description of the Thing.
@@ -587,7 +593,6 @@ 
    Examples
    
         try {
           let td = await wot.fetch("http://mmyservice.org/mySensor");
           let thing = wot.consume(td);
-          let thingName = await thing.readProperty('name');
           console.log("Thing " + thing.name + " has been consumed.");
           let subscription = thing.onPropertyChange("temperature")
             .subscribe(function(value) {

From 59d97a971f45427bfa7e9523a511169bb7f21462 Mon Sep 17 00:00:00 2001
From: Matthias Kovatsch 
Date: Sat, 3 Mar 2018 22:41:21 +0100
Subject: [PATCH 176/464] Change ThingProperty defaults

Default false is more sensible for writeable and even more for observable
---
 index.html | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/index.html b/index.html
index 3ac75bd3..2e67b4d4 100644
--- a/index.html
+++ b/index.html
@@ -699,8 +699,8 @@ 
    The ThingProperty dictionary
    
             required DOMString name;
             required DataSchema schema;
             any value;
-            boolean writable = true;
-            boolean observable = true;
+            boolean writable = false;
+            boolean observable = false;
           };
         
    
         
    

From 568b65f10165737c5de84b4f6e16897d3c3315ba Mon Sep 17 00:00:00 2001
From: Matthias Kovatsch 
Date: Sat, 3 Mar 2018 22:43:21 +0100
Subject: [PATCH 177/464] Use singular for field names (LD convention)

The field `semanticTypes` of SemanticAnnotations should be `semanticType`.
---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index 3ac75bd3..3dd7d417 100644
--- a/index.html
+++ b/index.html
@@ -367,7 +367,7 @@ 
    The SemanticAnnotations dictionary
    
       
    
       
             dictionary SemanticAnnotations {
-            sequence<SemanticType> semanticTypes;
+            sequence<SemanticType> semanticType;
             sequence<SemanticMetadata> metadata;
         };
       
    

From 12c3ceddd2999e395e9332955e1f8433a21405e3 Mon Sep 17 00:00:00 2001
From: Matthias Kovatsch 
Date: Sun, 4 Mar 2018 15:12:12 +0100
Subject: [PATCH 178/464] Follow consistent Properties-Actions-Events order

Always follow the same order for consistency and easier reference/navigation.
---
 index.html | 68 +++++++++++++++++++++++++++---------------------------
 1 file changed, 34 insertions(+), 34 deletions(-)

diff --git a/index.html b/index.html
index 3ac75bd3..34fd3875 100644
--- a/index.html
+++ b/index.html
@@ -168,8 +168,8 @@
       
  • On a consumed Thing,
         
      
           
    • Read the value of a Property or set of properties.
      • 
-          
    • Observe value changes to a Property.
      • 
           
    • Set the value of a Property or a set of properties.
      • 
+          
    • Observe value changes of a Property.
      • 
           
    • Invoke an Action.
      • 
           
    • Observe Events emitted by the Thing.
      • 
           
    • Observe changes to the Thing Description of the Thing.
      • 
@@ -187,11 +187,11 @@
       
    • 
         Create a local ExposedThing to be exposed, based on a Thing Description provided in string serialized format, or out of a template or an existing ConsumedThing object.
      • 
       
    • Add a Property definition to the Thing.
      • 
-      
    • Add an Event definition to the Thing.
      • 
       
    • Add an Action definition to the Thing.
      • 
+      
    • Add an Event definition to the Thing.
      • 
       
    • Attach semantic information to the Thing.
      • 
-      
    • Attach semantic information to an Action.
      • 
       
    • Attach semantic information to a Property.
      • 
+      
    • Attach semantic information to an Action.
      • 
       
    • Attach semantic information to an Event.
      • 
       
    • 
         Emit an Event, i.e. notify all listeners subscribed to that Event.
@@ -507,17 +507,17 @@ 
      The ThingTemplate dictionary
      
   
      
     
      The ConsumedThing interface
      
     
      
-      The ConsumedThing interface is a client API for sending requests to servers in order to retrieve or update Properties, invoke Actions, and observe Properties, Actions and Events.
+      The ConsumedThing interface is a client API for sending requests to servers in order to retrieve or update Properties, invoke Actions, and observe Properties and Events.
     
      
     
             interface ConsumedThing {
         readonly attribute DOMString name;
         ThingDescription getThingDescription();
-        Promise<any> invokeAction(DOMString name, any parameters);
-        Promise<void> writeProperty(DOMString name, any value);
         Promise<any> readProperty(DOMString name);
-        Observable onEvent(DOMString name);
+        Promise<void> writeProperty(DOMString name, any value);
+        Promise<any> invokeAction(DOMString name, any parameters);
         Observable onPropertyChange(DOMString name);
+        Observable onEvent(DOMString name);
         Observable onTDChange();
       };
     
      
@@ -539,9 +539,9 @@ 
      The ConsumedThing interface
      
       
      
     
      
 
-    
       
      The invokeAction() method
      
+    
       
      The readProperty() method
      
       
      
-        Takes the Action name from the name argument and the list of parameters, then requests from the underlying platform and the Protocol Bindings to invoke the Action on the remote Thing and return the result. Returns a Promise that resolves with the return value or rejects with an Error.
+        Takes the Property name as the name argument, then requests from the underlying platform  and the Protocol Bindings to retrieve the Property on the remote Thing and return the result. Returns a Promise that resolves with the Property value or rejects with an Error.
       
      
     
      
 
@@ -551,27 +551,27 @@ 
      The ConsumedThing interface
      
       
      
     
      
 
-    
       
      The readProperty() method
      
+    
       
      The invokeAction() method
      
       
      
-        Takes the Property name as the name argument, then requests from the underlying platform  and the Protocol Bindings to retrieve the Property on the remote Thing and return the result. Returns a Promise that resolves with the Property value or rejects with an Error.
+        Takes the Action name from the name argument and the list of parameters, then requests from the underlying platform and the Protocol Bindings to invoke the Action on the remote Thing and return the result. Returns a Promise that resolves with the return value or rejects with an Error.
       
      
     
      
 
-    
       
      The onEvent() method
      
+    
       
      The onPropertyChange() method
      
       
      
-        Returns an Observable for the Event specified in the name argument, allowing subscribing to and unsubscribing from notifications.
+        Returns an Observable for the Property specified in the name argument, allowing subscribing to and unsubscribing from notifications.
       
      
       
      
-        The callback function passed to the subscribe() method when invoked on the returned observer will receive the event data each time the event is fired.
+        The callback function passed to the subscribe() method when invoked on the returned observer will receive the new property value each time it is changed.
       
      
     
      
 
-    
       
      The onPropertyChange() method
      
+    
       
      The onEvent() method
      
       
      
-        Returns an Observable for the Property specified in the name argument, allowing subscribing to and unsubscribing from notifications.
+        Returns an Observable for the Event specified in the name argument, allowing subscribing to and unsubscribing from notifications.
       
      
       
      
-        The callback function passed to the subscribe() method when invoked on the returned observer will receive the new property value each time it is changed.
+        The callback function passed to the subscribe() method when invoked on the returned observer will receive the event data each time the event is fired.
       
      
     
      
 
@@ -636,13 +636,13 @@ 
      The ExposedThing interface
      
         ExposedThing addEvent(ThingEvent event);
         ExposedThing removeEvent(DOMString name);
         // define request handlers
-        ExposedThing setActionHandler(ActionHandler action, optional DOMString actionName);
         ExposedThing setPropertyReadHandler(PropertyReadHandler readHandler, optional DOMString propertyName);
         ExposedThing setPropertyWriteHandler(PropertyWriteHandler writeHandler, optional DOMString propertyName);
+        ExposedThing setActionHandler(ActionHandler action, optional DOMString actionName);
       };
-      callback ActionHandler = Promise<any>(any parameters);
       callback PropertyReadHandler = Promise<any>();
       callback PropertyWriteHandler = Promise<void>(any value);
+      callback ActionHandler = Promise<any>(any parameters);
     
    • 
 
     
     
    The start() method
    
@@ -783,13 +783,6 @@ 
    The ThingEvent dictionary
    
       
    
     
    
 
-    
    
-      
    The ActionHandler callback
    
-      
    
-        A function called with any parameters that returns a Promise.
-      
    
-    
    
-
     
    
       
    The PropertyReadHandler callback
    
       
    
@@ -807,15 +800,10 @@ 
    The PropertyWriteHandler callback
    
       
    
     
    
 
-    
     
    The setActionHandler() method
    
-      
    
-        Takes a actionName as an optional string argument, and an action argument of type ActionHandler. Sets the handler function for the specified Action matched by actionName if actionName is specified, otherwise sets it for any action. Throws on error. Returns a reference to the same object for supporting chaining.
-      
    
-      
    
-        If provided, this callback function will implement invoking an Action and SHOULD be called by implementations when a request for invoking a Action is received from the underlying platform.
-      
    
+    
    
+      
    The ActionHandler callback
    
       
    
-        There SHOULD be exactly one handler for any given Action. If no handler is initialized for any given Action, implementations SHOULD return error if the action is invoked by any client.
+        A function called with any parameters that returns a Promise.
       
    
     
    
 
@@ -840,6 +828,18 @@ 
    The PropertyWriteHandler callback
    
       
    
     
    
 
+    
     
    The setActionHandler() method
    
+      
    
+        Takes a actionName as an optional string argument, and an action argument of type ActionHandler. Sets the handler function for the specified Action matched by actionName if actionName is specified, otherwise sets it for any action. Throws on error. Returns a reference to the same object for supporting chaining.
+      
    
+      
    
+        If provided, this callback function will implement invoking an Action and SHOULD be called by implementations when a request for invoking a Action is received from the underlying platform.
+      
    
+      
    
+        There SHOULD be exactly one handler for any given Action. If no handler is initialized for any given Action, implementations SHOULD return error if the action is invoked by any client.
+      
    
+    
    
+
     
    
       
    Examples
    
       
    

From 5abc9ff904e27597c2a9e7df852dd5b0e29561b3 Mon Sep 17 00:00:00 2001
From: Matthias Kovatsch 
Date: Mon, 5 Mar 2018 00:07:49 +0100
Subject: [PATCH 179/464] Fix examples

Changed examples to new API.
Tested with node-wot, except `setPropertyReadHandler()`.
---
 index.html | 127 ++++++++++++++++++++++++-----------------------------
 1 file changed, 57 insertions(+), 70 deletions(-)

diff --git a/index.html b/index.html
index 3ac75bd3..6972d51a 100644
--- a/index.html
+++ b/index.html
@@ -847,90 +847,77 @@ 
    Examples
    
       
    
 
       
    -        let thing = WoT.produce(thingDescription);
         try {
-          // manually add properties, actions, and events
+          var thing = WoT.produce({ name: "tempSensor" });
+          // manually add Interactions
           thing.addProperty({
             name: "temperature",
-            value: "0",
-            schema: '{ \"type\": \"number\" }',
-            writable: false
+            value: 0.0,
+            schema: '{ "type": "number" }'
             // use default values for the rest
-          });
-          thing.addEvent({
-            name: "onchange",
-            schema: '{ \"type\": \"number\" }'
-          });
-          thing.addAction({
+          }).addProperty({
+            name: "max",
+            value: 0.0,
+            schema: '{ "type": "number" }'
+            // use default values for the rest
+          }).addAction({
             name: "reset",
-            action: () => { this.temperature = 0; }
+            // no input, no output
+          }).addEvent({
+            name: "onchange",
+            schema: '{ "type": "number" }'
           });
           // add server functionality
-          thing.setPropertyReadHandler(propertyName => {
-            console.log("Handling read request for " + propertyName);
-            return new Promise((resolve, reject) => {
-                if (this.hasOwnProperty(propertyName))
-                  resolve(this[propertyName]);
-                else
-                  reject('Property not found');
-              },
-              e => {
-                console.log("Error");
-              });
-          });
+          thing.setActionHandler( () => {
+            console.log("Resetting maximum");
+            thing.writeProperty("max", 0.0);
+          }, "reset");
+
+          thing.start();
+
+          setInterval( async () => {
+            let mock = Math.random()*100;
+            thing.writeProperty("temperature", mock);
+            let old = await thing.readProperty("max");
+            if (old < mock) {
+              thing.writeProperty("max", mock);
+              thing.emitEvent("onchange");
+            }
+          }, 1000);
+
         } catch (err) {
-           console.log("Thing creation error.");
+           console.log("Script error: " + err);
         }
-        thing.start()
-        .then (() => {
-          thing.register();
-        });
       
    
 
-      
    -        let thingDescription = '{
-          "name": "mySensor",
-          "url": "http://myservice.org/mySensor/description"
-        }';
-        WoT.fetch("http://myservice.org/mySensor/description")
-        .then(td => {
-          let e_thing = WoT.produce(td);
-          // properties, actions and events have been added based on the TD
-          // now add the requests handlers
-          try {
-            e_thing.setPropertyReadHandler(propertyName => {
-              console.log("Handling read request for " + propertyName);
-              return new Promise((resolve, reject) => {
-              if (this.hasOwnProperty(propertyName))
-                resolve(this[propertyName]);
-              else reject('Property not found');
-            });
-            e_thing.start();
-          } catch(error) {
-            console.log("Error");
-          }
+      
    +        let thingDescription = '{ "@context": [ "https://w3c.github.io/wot/w3c-wot-td-context.jsonld", "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ], "@type": [ "Thing", "Sensor" ], "name": "mySensor", "geo:location": "testspace", "interaction": [ { "@type": [ "Property", "Temperature" ], "name": "prop1", "schema": { "type": "number" }, "saref:TemperatureUnit": "degree_Celsius" } ] }';
+        try {
+          // note that produce() fails if thingDescription contains error
+          let thing = WoT.produce(thingDescription);
+          // Interactions were added from TD
+          // add server functionality
+          thing.setPropertyReadHandler( (propertyName) => {
+            console.log("Handling read request for " + propertyName);
+            return new Promise((resolve, reject) => {
+              resolve(Math.random(100));
+            })
+          }, "prop1");
+          thing.start();
+        } catch(err) {
+          console.log("Script error: " + err);
         }
-        });
       
    
 
-      
    -        let thingDescription = '{
-          "name": "mySensor",
-          "description": {
-            "@context": [
-              "http://w3c.github.io/wot/w3c-wot-td-context.jsonld",
-              "http://w3c.github.io/wot/w3c-wot-common-context.jsonld",
-            ],
-            "@type": [ "Thing" ],
-            "interactions": [
-              // ...
-            ]
-            // ...
-          }'
-        };
-        let e_thing = WoT.produce(thingDescription);
-        // properties, actions and events are added based on the TD
-        // ...
+      
    +        // fetch an external TD, e.g., to set up a proxy for that Thing
+        WoT.fetch("http://myservice.org/mySensor/description").then(td => {
+          // WoT.produce() ignores instance-specific metadata (security, form)
+          let thing = WoT.produce(td);
+          // Interactions were added from TD
+          // add server functionality
+          // ...
+        });
       
    
     
     
   
     

From cee858305de4819c911cd3ef825142d61a3c8439 Mon Sep 17 00:00:00 2001
From: Matthias Kovatsch 
Date: Mon, 5 Mar 2018 00:21:23 +0100
Subject: [PATCH 180/464] Change ThingProperty defaults in text

---
 index.html | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/index.html b/index.html
index 2e67b4d4..76471877 100644
--- a/index.html
+++ b/index.html
@@ -712,10 +712,10 @@ 
    The ThingProperty dictionary
    
             
             
  • The value attribute represents the value of the Property.
    • 
             
  • 
-              The writable attribute defines whether the Property can be updated. The default value is true.
+              The writable attribute defines whether the Property can be updated. The default value is false.
             
    • 
             
  • 
-              The observable attribute defines whether the Property changes can be observed by an external client. The default value is true.
+              The observable attribute defines whether the Property changes can be observed by an external client. The default value is false.
             
    • 
           
         
    

From 329d87cdcb5f367a12a22ee14c6afc64b729726f Mon Sep 17 00:00:00 2001
From: Matthias Kovatsch 
Date: Mon, 5 Mar 2018 00:23:02 +0100
Subject: [PATCH 181/464] Use singular for semanticTypes in text

---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index 3dd7d417..d41653b2 100644
--- a/index.html
+++ b/index.html
@@ -372,7 +372,7 @@ 
    The SemanticAnnotations dictionary
    
         };

    - The semanticTypes property denotes a list of SemanticType objects that define the semantic types that can be used in semantic metadata type-value pairs. + The semanticType property denotes a list of SemanticType objects that define the semantic types that can be used in semantic metadata type-value pairs.

    The metadata property denotes a list of SemanticMetadata objects (type-value pairs). From 488abb574471f1af263d5283faff8599ad04216f Mon Sep 17 00:00:00 2001 From: Matthias Kovatsch Date: Mon, 5 Mar 2018 14:13:09 +0100 Subject: [PATCH 182/464] Update of setPropertyReadHandler() --- index.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index 6972d51a..2a074470 100644 --- a/index.html +++ b/index.html @@ -896,9 +896,9 @@

    Examples

    // note that produce() fails if thingDescription contains error let thing = WoT.produce(thingDescription); // Interactions were added from TD - // add server functionality - thing.setPropertyReadHandler( (propertyName) => { - console.log("Handling read request for " + propertyName); + // add server functionality (a Property handler specifically for prop1) + thing.setPropertyReadHandler( () => { + console.log("Handling read request for prop1"); return new Promise((resolve, reject) => { resolve(Math.random(100)); }) From 6a26ddc58586f1037a76040921ed5e1235c95a3f Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 7 Mar 2018 15:13:07 +0200 Subject: [PATCH 183/464] Fix ExposedThing callback signatures and descriptions. Signed-off-by: Zoltan Kis --- index.html | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/index.html b/index.html index 200a6e3b..6bcd85b3 100644 --- a/index.html +++ b/index.html @@ -640,9 +640,9 @@

    The ExposedThing interface

    ExposedThing setPropertyWriteHandler(PropertyWriteHandler writeHandler, optional DOMString propertyName); ExposedThing setActionHandler(ActionHandler action, optional DOMString actionName); }; - callback PropertyReadHandler = Promise<any>(); - callback PropertyWriteHandler = Promise<void>(any value); - callback ActionHandler = Promise<any>(any parameters); + callback PropertyReadHandler = Promise<any>(DOMString name); + callback PropertyWriteHandler = Promise<void>(DOMString name, any value); + callback ActionHandler = Promise<any>(DOMString name, any parameters);

    The start() method

    @@ -786,14 +786,14 @@

    The ThingEvent dictionary

    The PropertyReadHandler callback

    - A function called with a propertyName argument that returns a Promise and resolves it with the value of the Property matching propertyName, or rejects with and error if the property is not found or the value cannot be retrieved. + A function called with a name argument that returns a Promise and resolves it with the value of the Property matching name, or rejects with and error if the property is not found or the value cannot be retrieved.

    The PropertyWriteHandler callback

    - A function called with a propertyName and a value argument that returns a Promise and resolves it when the value of the Property matching propertyName is updated with value, or rejects with and error if the property is not found or the value cannot be updated. The property is updated by the implementation with the value that is resolved by this callback. + A function called with a name and a value argument that returns a Promise and resolves it when the value of the Property matching name is updated with value, or rejects with and error if the property is not found or the value cannot be updated. The property is updated by the implementation with the value that is resolved by this callback.

    Note that this function is invoked by implementations before the property is updated, so the code in this callback function can invoke the readProperty() method to find out the old value of the property, if needed. Therefore the old value is not provided to this method. @@ -803,7 +803,7 @@

    The PropertyWriteHandler callback

    The ActionHandler callback

    - A function called with any parameters that returns a Promise. + A function called with a name argument that provides the action name, and another parameter that provides the arguments, either as a simple type or an `object` (multiple arguments are represented by an `object` or an `array`). It returns a Promise.

    From fa1e087b9883fd0085f9860e711ce475cc69fdcc Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 7 Mar 2018 15:32:08 +0200 Subject: [PATCH 184/464] Update examples Signed-off-by: Zoltan Kis --- index.html | 30 +++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/index.html b/index.html index 6bcd85b3..059bb2cd 100644 --- a/index.html +++ b/index.html @@ -872,9 +872,10 @@

    Examples

    console.log("Resetting maximum"); thing.writeProperty("max", 0.0); }, "reset"); - - thing.start(); - + thing.start().then(() => { + thing.register(); + }); + // define Thing business logic setInterval( async () => { let mock = Math.random()*100; thing.writeProperty("temperature", mock); @@ -884,9 +885,8 @@

    Examples

    thing.emitEvent("onchange"); } }, 1000); - } catch (err) { - console.log("Script error: " + err); + console.log("Error creating ExposedThing: " + err); } @@ -896,7 +896,23 @@

    Examples

    // note that produce() fails if thingDescription contains error let thing = WoT.produce(thingDescription); // Interactions were added from TD - // add server functionality (a Property handler specifically for prop1) + // add generic handler for reading any property + thing.setPropertyReadHandler(propertyName => { + console.log("Handling read request for " + propertyName); + return new Promise((resolve, reject) => { + if (this.hasOwnProperty(propertyName)) + // application can dispatch fetching property values + // if (propertyName === 'prop1') { ... } + // but in general, just read the property value + resolve(this[propertyName]); + else + reject('Property not found'); + }, + e => { + console.log("Error"); + }); + }); + // add specific handler for reading prop1, replaces the generic handler thing.setPropertyReadHandler( () => { console.log("Handling read request for prop1"); return new Promise((resolve, reject) => { @@ -905,7 +921,7 @@

    Examples

    }, "prop1"); thing.start(); } catch(err) { - console.log("Script error: " + err); + console.log("Error creating ExposedThing: " + err); } From 475fee8dc63611842644c7b0f82952d9ece94bb9 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 7 Mar 2018 15:45:12 +0200 Subject: [PATCH 185/464] Editorial changes and clarifications for handlers Signed-off-by: Zoltan Kis --- index.html | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/index.html b/index.html index 059bb2cd..cf669a57 100644 --- a/index.html +++ b/index.html @@ -786,14 +786,14 @@

    The ThingEvent dictionary

    The PropertyReadHandler callback

    - A function called with a name argument that returns a Promise and resolves it with the value of the Property matching name, or rejects with and error if the property is not found or the value cannot be retrieved. + A function called with a name argument that returns a Promise and resolves it with the value of the Property matching name, or rejects with an error if the property is not found or the value cannot be retrieved.

    The PropertyWriteHandler callback

    - A function called with a name and a value argument that returns a Promise and resolves it when the value of the Property matching name is updated with value, or rejects with and error if the property is not found or the value cannot be updated. The property is updated by the implementation with the value that is resolved by this callback. + A function called with a name and a value argument that returns a Promise which is resolved when the value of the Property matching name is updated with value, or rejects with an error if the property is not found or the value cannot be updated.

    Note that this function is invoked by implementations before the property is updated, so the code in this callback function can invoke the readProperty() method to find out the old value of the property, if needed. Therefore the old value is not provided to this method. @@ -809,28 +809,28 @@

    The ActionHandler callback

    The setPropertyReadHandler() method

    - Takes a propertyName as an optional string argument, and a readHandler argument of type PropertyReadHandler. Sets the handler function for reading the specified Property matched by propertyName if propertyName is specified, otherwise sets it for reading any property. Throws on error. Returns a reference to the same object for supporting chaining. + Takes readHandler as argument of type PropertyReadHandler and a propertyName as an optional string argument. Sets the handler function for reading the specified Property matched by propertyName if propertyName is specified, otherwise sets it for reading any property. Throws on error. Returns a reference to the same object for supporting chaining.

    If provided, this callback function will implement reading a Property and SHOULD be called by implementations when a request for reading a Property is received from the underlying platform.

    - There SHOULD be at most one handler for any given Property. If no handler is initialized for any given Property, implementations SHOULD implement default property read without calling this hook. + There SHOULD be at most one handler for any given Property and newly added handlers replace the old handlers. If no handler is initialized for any given Property, implementations SHOULD implement default property read without calling this hook.

    The setPropertyWriteHandler() method

    - Takes a propertyName as an optional string argument, and a writeHandler argument of type PropertyWriteHandler. Sets the handler function for writing the specified Property matched by propertyName if the propertyName is specified, otherwise sets it for writing any properties. Throws on error. Returns a reference to the same object for supporting chaining. + Takes writeHandler as argument of type PropertyWriteHandler and propertyName as an optional string argument. Sets the handler function for writing the specified Property matched by propertyName if the propertyName is specified, otherwise sets it for writing any properties. Throws on error. Returns a reference to the same object for supporting chaining.

    - There SHOULD be at most one write handler for any given Property. If no write handler is initialized for any given Property, implementations SHOULD implement default property update and notifying observers. + There SHOULD be at most one write handler for any given Property and newly added handlers replace the old handlers. If no write handler is initialized for any given Property, implementations SHOULD implement default property update and notifying observers.

    The setActionHandler() method

    - Takes a actionName as an optional string argument, and an action argument of type ActionHandler. Sets the handler function for the specified Action matched by actionName if actionName is specified, otherwise sets it for any action. Throws on error. Returns a reference to the same object for supporting chaining. + Takes action as argument of type ActionHandler, and actionName as an optional string argument. Sets the handler function for the specified Action matched by actionName if actionName is specified, otherwise sets it for any action. Throws on error. Returns a reference to the same object for supporting chaining.

    If provided, this callback function will implement invoking an Action and SHOULD be called by implementations when a request for invoking a Action is received from the underlying platform. From 2b99647c45ec0eed342f451d7bb0e4ddb0f2272f Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 14 Mar 2018 17:14:58 +0200 Subject: [PATCH 186/464] Remove generic handler support for now. Update examples. Signed-off-by: Zoltan Kis --- index.html | 60 +++++++++++++++++++++++------------------------------- 1 file changed, 25 insertions(+), 35 deletions(-) diff --git a/index.html b/index.html index cf669a57..abcc507e 100644 --- a/index.html +++ b/index.html @@ -636,13 +636,13 @@

    The ExposedThing interface

    ExposedThing addEvent(ThingEvent event); ExposedThing removeEvent(DOMString name); // define request handlers - ExposedThing setPropertyReadHandler(PropertyReadHandler readHandler, optional DOMString propertyName); - ExposedThing setPropertyWriteHandler(PropertyWriteHandler writeHandler, optional DOMString propertyName); - ExposedThing setActionHandler(ActionHandler action, optional DOMString actionName); + ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler); + ExposedThing setPropertyWriteHandler(DOMString name, PropertyWriteHandler writeHandler); + ExposedThing setActionHandler(DOMString name, ActionHandler action); }; - callback PropertyReadHandler = Promise<any>(DOMString name); - callback PropertyWriteHandler = Promise<void>(DOMString name, any value); - callback ActionHandler = Promise<any>(DOMString name, any parameters); + callback PropertyReadHandler = Promise<any>(); + callback PropertyWriteHandler = Promise<void>(any value); + callback ActionHandler = Promise<any>(any parameters);

    The start() method

    @@ -786,14 +786,14 @@

    The ThingEvent dictionary

    The PropertyReadHandler callback

    - A function called with a name argument that returns a Promise and resolves it with the value of the Property matching name, or rejects with an error if the property is not found or the value cannot be retrieved. + A function that returns a Promise and resolves it with the value of the Property matching the name argument to the setPropertyReadHandler function, or rejects with an error if the property is not found or the value cannot be retrieved.

    The PropertyWriteHandler callback

    - A function called with a name and a value argument that returns a Promise which is resolved when the value of the Property matching name is updated with value, or rejects with an error if the property is not found or the value cannot be updated. + A function called with value as argument that returns a Promise which is resolved when the value of the Property matching the name argument to the setPropertyReadHandler function is updated with value, or rejects with an error if the property is not found or the value cannot be updated.

    Note that this function is invoked by implementations before the property is updated, so the code in this callback function can invoke the readProperty() method to find out the old value of the property, if needed. Therefore the old value is not provided to this method. @@ -803,37 +803,37 @@

    The PropertyWriteHandler callback

    The ActionHandler callback

    - A function called with a name argument that provides the action name, and another parameter that provides the arguments, either as a simple type or an `object` (multiple arguments are represented by an `object` or an `array`). It returns a Promise. + A function called with a parameters dictionary argument assembled by the WoT runtime based on the Thing Description and the external client request. It returns a Promise that rejects with an error or resolves if the action is successful or ongoing (may also resolve with a control object such as an Observable for actions that need progress notifications or that can be canceled).

    The setPropertyReadHandler() method

    - Takes readHandler as argument of type PropertyReadHandler and a propertyName as an optional string argument. Sets the handler function for reading the specified Property matched by propertyName if propertyName is specified, otherwise sets it for reading any property. Throws on error. Returns a reference to the same object for supporting chaining. + Takes name as string argument and readHandler as argument of type PropertyReadHandler. Sets the handler function for reading the specified Property matched by name. Throws on error. Returns a reference to the same object for supporting chaining.

    - If provided, this callback function will implement reading a Property and SHOULD be called by implementations when a request for reading a Property is received from the underlying platform. + The readHandler callback function will implement reading a Property and SHOULD be called by implementations when a request for reading a Property is received from the underlying platform.

    - There SHOULD be at most one handler for any given Property and newly added handlers replace the old handlers. If no handler is initialized for any given Property, implementations SHOULD implement default property read without calling this hook. + There SHOULD be at most one handler for any given Property and newly added handlers replace the old handlers. If no handler is initialized for any given Property, implementations SHOULD implement a default property read handler.

    The setPropertyWriteHandler() method

    - Takes writeHandler as argument of type PropertyWriteHandler and propertyName as an optional string argument. Sets the handler function for writing the specified Property matched by propertyName if the propertyName is specified, otherwise sets it for writing any properties. Throws on error. Returns a reference to the same object for supporting chaining. + Takes name as string argument and writeHandler as argument of type PropertyWriteHandler. Sets the handler function for writing the specified Property matched by name. Throws on error. Returns a reference to the same object for supporting chaining.

    - There SHOULD be at most one write handler for any given Property and newly added handlers replace the old handlers. If no write handler is initialized for any given Property, implementations SHOULD implement default property update and notifying observers. + There SHOULD be at most one write handler for any given Property and newly added handlers replace the old handlers. If no write handler is initialized for any given Property, implementations SHOULD implement default property update and notifying observers on change.

    The setActionHandler() method

    - Takes action as argument of type ActionHandler, and actionName as an optional string argument. Sets the handler function for the specified Action matched by actionName if actionName is specified, otherwise sets it for any action. Throws on error. Returns a reference to the same object for supporting chaining. + Takes name as string argument and action as argument of type ActionHandler. Sets the handler function for the specified Action matched by name. Throws on error. Returns a reference to the same object for supporting chaining.

    - If provided, this callback function will implement invoking an Action and SHOULD be called by implementations when a request for invoking a Action is received from the underlying platform. + If provided, this callback function will implement invoking an Action and SHOULD be called by implementations when a request for invoking a Action is received from the underlying platform. The callback will receive a parameters dictionary argument.

    There SHOULD be exactly one handler for any given Action. If no handler is initialized for any given Action, implementations SHOULD return error if the action is invoked by any client. @@ -868,10 +868,10 @@

    Examples

    schema: '{ "type": "number" }' }); // add server functionality - thing.setActionHandler( () => { + thing.setActionHandler("reset", () => { console.log("Resetting maximum"); thing.writeProperty("max", 0.0); - }, "reset"); + }); thing.start().then(() => { thing.register(); }); @@ -896,29 +896,19 @@

    Examples

    // note that produce() fails if thingDescription contains error let thing = WoT.produce(thingDescription); // Interactions were added from TD - // add generic handler for reading any property - thing.setPropertyReadHandler(propertyName => { - console.log("Handling read request for " + propertyName); + // WoT adds generic handler for reading any property + // define a specific handler for one property + let name = "examplePropertyName"; + thing.setPropertyReadHandler(name, () => { + console.log("Handling read request for " + name); return new Promise((resolve, reject) => { - if (this.hasOwnProperty(propertyName)) - // application can dispatch fetching property values - // if (propertyName === 'prop1') { ... } - // but in general, just read the property value - resolve(this[propertyName]); - else - reject('Property not found'); + let examplePropertyValue = 5; + resolve(examplePropertyValue); }, e => { console.log("Error"); }); }); - // add specific handler for reading prop1, replaces the generic handler - thing.setPropertyReadHandler( () => { - console.log("Handling read request for prop1"); - return new Promise((resolve, reject) => { - resolve(Math.random(100)); - }) - }, "prop1"); thing.start(); } catch(err) { console.log("Error creating ExposedThing: " + err); From a9203ab18c1317e383c88abc642cbefe3b1c2d5a Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Fri, 16 Mar 2018 09:06:38 +0100 Subject: [PATCH 187/464] fix warning: No for dictionary SemanticType relates again to https://github.com/w3c/respec/issues/1508 --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index abcc507e..3e6d430b 100644 --- a/index.html +++ b/index.html @@ -380,7 +380,7 @@

    The SemanticAnnotations dictionary

    -

    The SemanticType dictionary

    +

    The SemanticType dictionary

             dictionary SemanticType {
             required DOMString name;

From c56d8dd90cc3f351d1486005fc068d41606b1df1 Mon Sep 17 00:00:00 2001
From: danielpeintner 
Date: Fri, 16 Mar 2018 11:15:18 +0100
Subject: [PATCH 188/464] fix html issues

* 
        or 
         not allowed as child of 
        
* replace < with <
* add missing 
        
* change  to  for now
* remove unnecessary 
---
 index.html | 206 ++++++++++++++++++++++++++---------------------------
 1 file changed, 103 insertions(+), 103 deletions(-)

diff --git a/index.html b/index.html
index 3e6d430b..cf5998b7 100644
--- a/index.html
+++ b/index.html
@@ -253,23 +253,23 @@ 
        The DiscoveryMethod enumeration

    DiscoveryMethod represents the discovery type to be used: -

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

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

    The ThingFilter dictionary

    The constraints property represents additional information for the discovery method in the form of a list of sets of property-value pairs (dictionaries). The list elements (dictionaries) are in OR relationship, and within a constraint dictionary the key-value pairs are in AND relationship. Implementations SHOULD make the following mapping from the constraint dictionaries to SemanticAnnotations: for each property-value pair in a constraint dictionary, -

      -
    • - Each property name in the constraint dictionary SHOULD match the either the `name` property of a defined SemanticType on the target Thing object, or the name of a Property on the target Thing. -
      • -
    • - When the name matches, the values are compared. If the values match, the constraint is matched. -
      • -

    +
      +
    • + Each property name in the constraint dictionary SHOULD match the either the `name` property of a defined SemanticType on the target Thing object, or the name of a Property on the target Thing. +
      • +
    • + When the name matches, the values are compared. If the values match, the constraint is matched. +
      • +

    Constraints are experimental feature, implementations are not required to support them.

    @@ -342,15 +342,15 @@

    The ThingDescription type

    The produce() method

    Accepts a model argument of type ThingModel and returns an ExposedThing object, locally created based on the provided initialization parameters. An ExposedThing can be created in the following ways: -

      -
    1. - from an initial model (including a user given name and semantic annotations), then adding properties, actions, events and request handlers; -
      2. -
    2. - from a Thing Description (possibly of a ConsumedThing object), then adding request handlers. -
      3. -

    +
      +
    1. + from an initial model (including a user given name and semantic annotations), then adding properties, actions, events and request handlers; +
      2. +
    2. + from a Thing Description (possibly of a ConsumedThing object), then adding request handlers. +
      3. +
    @@ -390,18 +390,18 @@

    The SemanticType dictionary

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

      -
    • - The name attribute represents the name of the semantic type in the given context. -
      • -
    • - The context attribute represents an URL link to the context of the semantic classification. -
      • -
    • - The prefix attribute represents a short prefix associated with a context. -
      • -

    +
      +
    • + The name attribute represents the name of the semantic type in the given context. +
      • +
    • + The context attribute represents an URL link to the context of the semantic classification. +
      • +
    • + The prefix attribute represents a short prefix associated with a context. +
      • +

    Semantic type examples to be added.

    @@ -416,13 +416,13 @@

    The SemanticMetadata dictionary

    };

    The SemanticMetadata dictionary describes a pair of semantic type and value: -

      -
    • - The type attribute represents the semantic type name defined by a SemanticType object. -
      • -
    • The value attribute represents the metadata value.
      • -

    +
      +
    • + The type attribute represents the semantic type name defined by a SemanticType object. +
      • +
    • The value attribute represents the metadata value.
      • +
    @@ -436,12 +436,12 @@

    The ThingTemplate dictionary

    };

    The ThingTemplate dictionary extends SemanticAnnotations and contains properties to initialize a Thing: -

      -
    • - The name attribute represents the user given name of the Thing. -
      • -

    +
      +
    • + The name attribute represents the user given name of the Thing. +
      • +

    Support for configuration and security data might be added later.

    @@ -705,20 +705,20 @@

    The ThingProperty dictionary

    Represents the Thing Property description. -

      -
    • The name attribute represents the name of the Property.
      • -
    • - The schema attribute represents the data type for the Property described by DataSchema. -
      • -
    • The value attribute represents the value of the Property.
      • -
    • - The writable attribute defines whether the Property can be updated. The default value is false. -
      • -
    • - The observable attribute defines whether the Property changes can be observed by an external client. The default value is false. -
      • -

    +
      +
    • The name attribute represents the name of the Property.
      • +
    • + The schema attribute represents the data type for the Property described by DataSchema. +
      • +
    • The value attribute represents the value of the Property.
      • +
    • + The writable attribute defines whether the Property can be updated. The default value is false. +
      • +
    • + The observable attribute defines whether the Property changes can be observed by an external client. The default value is false. +
      • +
    @@ -743,12 +743,12 @@

    The ThingAction dictionary

    The ThingAction dictionary describes the arguments and the return value. +

    • The name attribute provides the Action name.
    • The inputSchema attribute provides the description of the input arguments (argument list is represented by an object). If missing, it means the action does not accept arguments.
    • The outputSchema attribute provides the description of the returned data. If missing, it means the action does not return data.
    -

    @@ -880,7 +880,7 @@

    Examples

    let mock = Math.random()*100; thing.writeProperty("temperature", mock); let old = await thing.readProperty("max"); - if (old < mock) { + if (old < mock) { thing.writeProperty("max", mock); thing.emitEvent("onchange"); } @@ -977,18 +977,18 @@

    The TDLink dictionary

    };

    The TDLink dictionary contains the following properties: -

      -
    • - The href attribute represents a hyperlink reference. -
      • -
    • - The rel attribute represents a relation type. -
      • -
    • - The mediaType attribute represents a IANA media type. For TDs there will be registered media types, so applications will be able to check whether an `href` link points to a TD, i.e. whether the link is fetcheable with this API. -
      • -

    +
      +
    • + The href attribute represents a hyperlink reference. +
      • +
    • + The rel attribute represents a relation type. +
      • +
    • + The mediaType attribute represents a IANA media type. For TDs there will be registered media types, so applications will be able to check whether an `href` link points to a TD, i.e. whether the link is fetcheable with this API. +
      • +
    @@ -1025,18 +1025,18 @@

    Observables

    The Observer interface

    The Observer interface defines the callbacks needed to handle an Observable: -

      -
    • - The next() function, as well as the OnNext callback takes the next sample for the data in the value argument. -
      • -
    • - The error() function, as well as the OnError callback takes an error in the value argument. It is called when an error occured in producing the data the client should know about. -
      • -
    • - The complete() function, as well as the OnComplete callback is called when the data source has finished sending values. -
      • -

    +
      +
    • + The next() function, as well as the OnNext callback takes the next sample for the data in the value argument. +
      • +
    • + The error() function, as well as the OnError callback takes an error in the value argument. It is called when an error occured in producing the data the client should know about. +
      • +
    • + The complete() function, as well as the OnComplete callback is called when the data source has finished sending values. +
      • +
    @@ -1053,17 +1053,18 @@

    The Subscription interface

    The Observable interface

    The Observable interface enabled subscribing to pushed data notifications by the subscribe() method: -

      -
    • - If the subscribe() method is called with an Observer object, initialize the data, error and completion handling callbacks from that object, or throw on error. -
      • -
    • - Otherwise, if the subscribe() method is called with a function, initialize the data handler callback with that function. If the next argument is provided and is a function, initialize the error handling callback with that function, or throw on error. If the third argument is provided and is a function, initialize the completion handler with that function, or throw on error. -
      • -
    • - After callback initializations, the implementation should request the underlying platform to provide data, error and completion notifications for the supported data source. -
      • -
    +

    +
      +
    • + If the subscribe() method is called with an Observer object, initialize the data, error and completion handling callbacks from that object, or throw on error. +
      • +
    • + Otherwise, if the subscribe() method is called with a function, initialize the data handler callback with that function. If the next argument is provided and is a function, initialize the error handling callback with that function, or throw on error. If the third argument is provided and is a function, initialize the completion handler with that function, or throw on error. +
      • +
    • + After callback initializations, the implementation should request the underlying platform to provide data, error and completion notifications for the supported data source. +
      • +
    @@ -1079,7 +1080,6 @@

    The Observable interface

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

    The terms URL and From d1cecefa558992f8e93d2fc80d3de71d3797dab0 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Tue, 20 Mar 2018 21:28:13 +0200 Subject: [PATCH 189/464] Update Open Issues section Signed-off-by: Zoltan Kis --- index.html | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/index.html b/index.html index abcc507e..caf8014c 100644 --- a/index.html +++ b/index.html @@ -1218,6 +1218,18 @@

    The Observable interface

    The following problems are being discussed and need most attention:

      +
    • + Revised API for tracking the TD better (https://github.com/w3c/wot-scripting-api/issues/96). +
      • +
    • + Security related metadata (https://github.com/w3c/wot-scripting-api/issues/91). +
      • +
    • + Defining DataSchema better (https://github.com/w3c/wot-scripting-api/issues/89). +
      • +
    • + Providing Protocol Binding for ExposedThing (https://github.com/w3c/wot-scripting-api/issues/45). +
    • Retrieving information from Thing Description (https://github.com/w3c/wot-scripting-api/issues/38)
    • Script management and runtime related issues (https://github.com/w3c/wot-scripting-api/issues/)
    From dde2fefcffc4be5bf84d2b46ccb6dae5659872b5 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Tue, 20 Mar 2018 21:44:20 +0200 Subject: [PATCH 190/464] Update the Changes section Signed-off-by: Zoltan Kis --- index.html | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index 03e1e316..eab959b3 100644 --- a/index.html +++ b/index.html @@ -1211,6 +1211,31 @@

    The Observable interface

    The following is a list of major changes to the document. For a complete list of changes, see the [github change log](https://github.com/w3c/wot-scripting-api/commits/master). You can also view the [recently closed bugs](https://github.com/w3c/wot-scripting-api/issues?page=1&state=closed).

    +

    +

      +
    • + Synchronized the Scripting API with the [Thing Description specification](https://w3c.github.io/wot-thing-description/). Defined ThingDescription, ThingTemplate, SemanticAnnotations, SemanticType, SemanticMetadata, input and output data descriptions, etc. +
      • +
    • + Separated consume() to fetch() and consume(). +
      • +
    • + Changed expose() to accept a Thing Template. +
      • +
    • + Instead of addListener(), removeListener() introduced onEvent(), onPropertyChange(), onTDChange(). +
      • +
    • + Revised ExposedThing handlers for Property, Action and Event. +
      • +
    • + Added an informal section on TD introspection. +
      • +
    • + Added informal section for Observable. +
      • +
    +

    Open issues

    @@ -1228,7 +1253,7 @@

    The Observable interface

    Defining DataSchema better (https://github.com/w3c/wot-scripting-api/issues/89).
  • - Providing Protocol Binding for ExposedThing (https://github.com/w3c/wot-scripting-api/issues/45). + Providing Protocol Binding for ExposedThing (https://github.com/w3c/wot-scripting-api/issues/45).
  • Retrieving information from Thing Description (https://github.com/w3c/wot-scripting-api/issues/38)
  • Script management and runtime related issues (https://github.com/w3c/wot-scripting-api/issues/)
    • From 1b3c4ce0e360d0154dedf43d673a1329c6d2930f Mon Sep 17 00:00:00 2001 From: ashimura Date: Sat, 24 Mar 2018 23:50:56 +0900 Subject: [PATCH 191/464] add wd2 --- releases/wd2/Overview.html | 1737 ++++ releases/wd2/diff.html | 15000 +++++++++++++++++++++++++++++++++++ 2 files changed, 16737 insertions(+) create mode 100644 releases/wd2/Overview.html create mode 100644 releases/wd2/diff.html diff --git a/releases/wd2/Overview.html b/releases/wd2/Overview.html new file mode 100644 index 00000000..74f9c6c2 --- /dev/null +++ b/releases/wd2/Overview.html @@ -0,0 +1,1737 @@ + + + Web of Things (WoT) Scripting API + + + +
    + +

    Web of Things (WoT) Scripting API

    + +

    W3C Editor's Draft

    +
    +
    This version:
    https://w3c.github.io/wot-scripting-api/
    Latest published version:
    https://www.w3.org/TR/wot-scripting-api/
    +
    Latest editor's draft:
    https://w3c.github.io/wot-scripting-api/
    + + + + + + +
    Editors:
    +
    Zoltan Kis (Intel)
    Kazuaki Nimura (Fujitsu Ltd.)
    Daniel Peintner (Siemens AG)
    Johannes Hund (Former Editor, when at Siemens AG)
    + + +
    Contributors:
    + In the GitHub repository +
    Repository:
    + We are on GitHub +
    + File a bug +
    +
    + + + +

    + Copyright © + 2017-2018 + + W3C® + (MIT, + ERCIM, + Keio, Beihang). + + W3C liability, + trademark and + permissive document license + rules apply. +

    +
    +

    Abstract

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

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

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

    Status of This Document

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

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

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

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

    + This document was published by the Web of Things Working Group as an Editor's Draft. + + + Comments regarding this document are welcome. Please send them to + public-wot-wg@w3.org + (subscribe, + archives). + + + + +

    +

    +Changes from the previous publication can be found in Appendix A. + +A diff-marked version of this document is also available for comparison purposes. +

    +

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

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

    This document is governed by the 1 February 2018 W3C Process Document. +

    1. Introduction

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

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

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

    Note

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

    Note

    +This specification does not make assumptions on how the WoT Runtime handles and runs scripts, including single or multiple tenancy, script deployment and lifecycle management. The API already supports the generic mechanisms that make it possible to implement script management, for instance by exposing a manager Thing whose Actions (action handlers) implement script lifecycle management operations. +

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

    2. Use Cases

    This section is non-normative.

    +The following scripting use cases are supported in this specification: +

    2.1 Discovery

      +
    • Discover all Things in the WoT network by sending a broadcast request.
      • +
    • Discover Things running in the local WoT Runtime.
      • +
    • Discover nearby Things, for instance by NFC or Bluetooth.
      • +
    • Discover Things by sending a discovery request to a given registry.
      • +
    • Discover Things by filters defined on Thing Descriptions
      • +
    • Discover Things by semantic filters.
      • +
    • Stop or suppress an ongoing discovery process.
      • +
    • +Optionally specify a timeout to the discovery process after which it is stopped/suppressed. +
      • +

    2.2 Consuming a Thing

    2.3 Exposing a Thing

      +
    • +Exposing the Thing includes generating the protocol bindings in order to access lower level functionality. +
      • +
    • +Create a local ExposedThing to be exposed, based on a Thing Description provided in string serialized format, or out of a template or an existing ConsumedThing object.
      • +
    • Add a Property definition to the Thing.
      • +
    • Add an Action definition to the Thing.
      • +
    • Add an Event definition to the Thing.
      • +
    • Attach semantic information to the Thing.
      • +
    • Attach semantic information to a Property.
      • +
    • Attach semantic information to an Action.
      • +
    • Attach semantic information to an Event.
      • +
    • +Emit an Event, i.e. notify all listeners subscribed to that Event. +
      • +
    • +Provide notifications for TD changes to clients subscribed to that. +
      • +
    • Mark/unmark the Thing to be discoverable.
      • +
    • Mark/unmark the Thing to be consumable.
      • +
    • Start the exposed Thing in order to process external requests.
      • +
    • Stop the exposed Thing.
      • +
    • Register handlers for external requests: +
        +
      • to retrieve a Property value;
        • +
      • to update a Property value;
        • +
      • +to run an Action: take the parameters from the request, execute the defined action, and return the result; +
        • +
      +
      • +

    3. The WoT object

    The WoT object is the API entry point and it is exposed by an implementation of the WoT Runtime. The WoT object does not expose properties, only methods for discovering, consuming and exposing a Thing. +

    Note

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

    Editor's note

    +The algorithms for the WoT methods will be specified later, including error handling and security considerations. +

    3.1 The discover() method

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

    3.1.1 The DiscoveryMethod enumeration

    +DiscoveryMethod represents the discovery type to be used: +

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

    3.1.2 The ThingFilter dictionary

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

    dictionary ThingFilter {
+    DiscoveryMethod      method = "any";
+    USVString            url;
+    USVString            query;
+    sequence<Dictionary> constraints;
+};

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

    Editor's note

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

    +The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, such as a Thing Directory or a Thing. +

    +The query property represents a query string accepted by the implementation, for instance a SPARQL query. +

    +The constraints property represents additional information for the discovery method in the form of a list of sets of property-value pairs (dictionaries). The list elements (dictionaries) are in OR relationship, and within a constraint dictionary the key-value pairs are in AND relationship. Implementations SHOULD make the following mapping from the constraint dictionaries to SemanticAnnotations: for each property-value pair in a constraint dictionary, +

      +
    • +Each property name in the constraint dictionary SHOULD match the either the name property of a defined SemanticType on the target Thing object, or the name of a Property on the target Thing. +
      • +
    • +When the name matches, the values are compared. If the values match, the constraint is matched. +
      • +
    Editor's note

    +Constraints are experimental feature, implementations are not required to support them. +

    Editor's note

    +Semantic annotations need revisiting in order to simplify their representation. In the [WOT-TD] specification they represent the @type construct. At the moment only @context, @type and @id constructs are used in the TD. +

    3.2 The fetch() method

    +Accepts an url argument and returns a Promise that resolves with a ThingDescription. +

    3.3 The ThingDescription type

    +Representation of the Thing Description, standardized in the Wot Things Description specification. +

    Note

    +In this version of the API, Thing Descriptions are represented as opaque strings, denoting a serialized form, for instance JSON or JSON-LD. See Issue 38 and Issue 45. +

    3.4 The consume() method

    +Accepts an td argument of type ThingDescription and returns a ConsumedThing object instantiated based on that description. +

    3.5 The produce() method

    +Accepts a model argument of type ThingModel and returns an ExposedThing object, locally created based on the provided initialization parameters. An ExposedThing can be created in the following ways: +

      +
    1. +from an initial model (including a user given name and semantic annotations), then adding properties, actions, events and request handlers; +
      2. +
    2. +from a Thing Description (possibly of a ConsumedThing object), then adding request handlers. +
      3. +

    3.6 The ThingModel type

    +A Thing model is used for producing a new ExposedThing and can be either a ThingTemplate, or a ThingDescription. +

    3.7 The SemanticAnnotations dictionary

    +A dictionary that provides the semantic types and semantic metadata. +

    +The semanticType property denotes a list of SemanticType objects that define the semantic types that can be used in semantic metadata type-value pairs. +

    +The metadata property denotes a list of SemanticMetadata objects (type-value pairs). +

    3.8 The SemanticType dictionary

    dictionary SemanticType {
+    required DOMString name;
+    required USVString context;
+             DOMString prefix;
+};

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

      +
    • +The name attribute represents the name of the semantic type in the given context. +
      • +
    • +The context attribute represents an URL link to the context of the semantic classification. +
      • +
    • +The prefix attribute represents a short prefix associated with a context. +
      • +
    Editor's note

    +Semantic type examples to be added. +

    3.9 The SemanticMetadata dictionary

    dictionary SemanticMetadata {
+    SemanticType type;
+    any          value;
+};

    The SemanticMetadata dictionary describes a pair of semantic type and value: +

      +
    • +The type attribute represents the semantic type name defined by a SemanticType object. +
      • +
    • The value attribute represents the metadata value.
      • +

    3.10 The ThingTemplate dictionary

    +A Thing Template is a dictionary that provides a user given name, and the semantic types and semantic metadata attached to the ExposedThing +Thing Description's root level. +

    dictionary ThingTemplate : SemanticAnnotations {
+    required DOMString name;
+};

    The ThingTemplate dictionary extends SemanticAnnotations and contains properties to initialize a Thing: +

      +
    • +The name attribute represents the user given name of the Thing. +
      • +
    Editor's note

    +Support for configuration and security data might be added later. +

    3.11 Examples

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

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

    Example 2: Discover Things exposed by local hardware
    let subscription = wot.discover({ method: "local" }).subscribe(
+  thing => { console.log("Found local Thing " + thing.name); },
+  error => { console.log("Discovery error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);
    Example 3: Same as above but with different Observable syntax
    let subscription = wot.discover({ method: "local" }).subscribe({
+  thing => { console.log("Found local Thing " + thing.name); },
+  error: err => { console.log("Discovery error: " + err.message); },
+  complete: () => { console.log("Discovery finished successfully");}
+});
    Example 4: Discover Things exposed nearby, via Bluetooth or NFC
    let subscription = wot.discover({
+  method: "nearby",
+  constraints: [{ protocol: "BLE-4.2" }, { protocol: "NFC"}]
+}).subscribe(
+  thing => { console.log("Found nearby Thing " + thing.name); },
+  error => { console.log("Discovery error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);
    Example 5: Discover Things exposed in a proprietary way
    let subscription = wot.discover({
+  method: "other",
+  constraints: [{ solution: "XYZ123", key: "..."}]
+}).subscribe(
+  thing => { console.log("Found Thing " + thing.name); },
+  error => { console.log("Discovery error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);

    4. The ConsumedThing interface

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

    +ConsumedThing represents a local proxy object of the remote Thing. +

    4.1 The name property

    +The name property represents the name of the Thing as specified in the TD. In this version it is read only. +

    4.2 The getThingDescription() method

    +Returns the Thing Description of the Thing. +

    Editor's note

    +In this version, introspection based on TD is out of scope. Parsing and exposing Thing Descriptions is discussed in Issue 38. +

    4.3 The readProperty() method

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

    4.4 The writeProperty() method

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

    4.5 The invokeAction() method

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

    4.6 The onPropertyChange() method

    +Returns an Observable for the Property specified in the name argument, allowing subscribing to and unsubscribing from notifications. +

    +The callback function passed to the subscribe() method when invoked on the returned observer will receive the new property value each time it is changed. +

    4.7 The onEvent() method

    +Returns an Observable for the Event specified in the name argument, allowing subscribing to and unsubscribing from notifications. +

    +The callback function passed to the subscribe() method when invoked on the returned observer will receive the event data each time the event is fired. +

    4.8 The onTDChange() method

    +Returns an Observable, allowing subscribing to and unsubscribing from notifications to the Thing Description. +

    +The callback function passed to the subscribe() method when invoked on the returned observer will receive the new Thing Description each time it is changed. +

    4.9 Examples

    +Below a ConsumedThing interface example is given. +

    Example 6: Consume a Thing
    try {
+  let td = await wot.fetch("http://mmyservice.org/mySensor");
+  let thing = wot.consume(td);
+  console.log("Thing " + thing.name + " has been consumed.");
+  let subscription = thing.onPropertyChange("temperature")
+    .subscribe(function(value) {
+      console.log("Temperature + " has changed to " + value);
+    });
+  thing.invokeAction("startMeasurement", { units: "Celsius" })
+    .then(() => { console.log("Temperature measurement started."); })
+    .catch(e => {
+       console.log("Error starting measurement.");
+       subscription.unsubscribe();
+     })
+} catch(error) {
+  console.log("Error during fetch or consume: " + error.message);
+};

    5. The ExposedThing interface

    +The ExposedThing interface is the server API that allows defining request handlers, properties, Actions, and Events to a Thing. It also implements the ConsumedThing interface. An ExposedThing is created by the produce() method. +

    Editor's note

    +It is under consideration to use a constructor for ExposedThing instead of a factory method. + 

    ExposedThing implements ConsumedThing;
+
+interface ExposedThing {
+    // define how to expose and run the Thing
+    Promise<void> start();
+    Promise<void> stop();
+    Promise<void> register(optional USVString directory);
+    Promise<void> unregister(optional USVString directory);
+    Promise<void> emitEvent(DOMString eventName, any payload);
+    // define Thing Description modifiers
+    ExposedThing  addProperty(ThingProperty property);
+    ExposedThing  removeProperty(DOMString name);
+    ExposedThing  addAction(ThingAction action);
+    ExposedThing  removeAction(DOMString name);
+    ExposedThing  addEvent(ThingEvent event);
+    ExposedThing  removeEvent(DOMString name);
+    // define request handlers
+    ExposedThing  setPropertyReadHandler(DOMString name,
+                                         PropertyReadHandler readHandler);
+    ExposedThing  setPropertyWriteHandler(DOMString name,
+                                          PropertyWriteHandler writeHandler);
+    ExposedThing  setActionHandler(DOMString name, ActionHandler action);
+};
+
+callback PropertyReadHandler = Promise<any> ();
+
+callback PropertyWriteHandler = Promise<void> (any value);
+
+callback ActionHandler = Promise<any> (any parameters);

    5.1 The start() method

    +Start serving external requests for the Thing. +

    5.2 The stop() method

    +Stop serving external requests for the Thing. +

    5.3 The register() method

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

    5.4 The unregister() method

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

    5.5 The emitEvent() method

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

    5.6 The DataSchema type

    +The DataSchema type represents a data type specified in the Thing Description in a serialized form. +

    Editor's note

    +DataSchema is under development, currently it can denote any type supported by the Thing Description and the WoT Runtime. +

    5.7 The addProperty() method

    +Adds a Property defined by the argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining. +

    5.7.1 The ThingProperty dictionary

    dictionary ThingProperty : SemanticAnnotations {
+    required DOMString  name;
+    required DataSchema schema;
+             any        value;
+             boolean    writable = false;
+             boolean    observable = false;
+};

    +Represents the Thing +Property description. +

      +
    • The name attribute represents the name of the Property.
      • +
    • +The schema attribute represents the data type for the Property described by DataSchema. +
      • +
    • The value attribute represents the value of the Property.
      • +
    • +The writable attribute defines whether the Property can be updated. The default value is false. +
      • +
    • +The observable attribute defines whether the Property changes can be observed by an external client. The default value is false. +
      • +

    5.8 The removeProperty() method

    +Removes the Property specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining. +

    5.9 The addAction() method

    +Adds an Action to the Thing object as defined by the action argument of type ThingAction and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining. +

    5.9.1 The ThingAction dictionary

    +The ThingAction dictionary describes the arguments and the return value. +

      +
    • The name attribute provides the Action name.
      • +
    • The inputSchema attribute provides the description of the input arguments (argument list is represented by an object). If missing, it means the action does not accept arguments.
      • +
    • The outputSchema attribute provides the description of the returned data. If missing, it means the action does not return data.
      • +

    5.10 The removeAction() method

    +Removes the Action specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining. +

    5.11 The addEvent() method

    +Adds an event to the Thing object as defined by the event argument of type ThingEvent and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining. +

    5.11.1 The ThingEvent dictionary

    dictionary ThingEvent : SemanticAnnotations {
+    required DOMString  name;
+             DataSchema schema;
+};
      +
    • The name attribute represents the event name.
      • +
    • The schema attribute represents the type of the data that is attached to the event. If missing, it means the event does not carry data.
      • +

    5.12 The removeEvent() method

    +Removes the event specified by the name argument and updates the Thing Description. Returns a reference to the same object for supporting chaining. +

    5.13 The PropertyReadHandler callback

    +A function that returns a Promise and resolves it with the value of the Property matching the name argument to the setPropertyReadHandler function, or rejects with an error if the property is not found or the value cannot be retrieved. +

    5.14 The PropertyWriteHandler callback

    +A function called with value as argument that returns a Promise which is resolved when the value of the Property matching the name argument to the setPropertyReadHandler function is updated with value, or rejects with an error if the property is not found or the value cannot be updated. +

    Editor's note

    +Note that this function is invoked by implementations before the property is updated, so the code in this callback function can invoke the readProperty() method to find out the old value of the property, if needed. Therefore the old value is not provided to this method. +

    5.15 The ActionHandler callback

    +A function called with a parameters dictionary argument assembled by the WoT runtime based on the Thing Description and the external client request. It returns a Promise that rejects with an error or resolves if the action is successful or ongoing (may also resolve with a control object such as an Observable for actions that need progress notifications or that can be canceled). +

    5.16 The setPropertyReadHandler() method

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

    +The readHandler callback function will implement reading a Property and SHOULD be called by implementations when a request for reading a Property is received from the underlying platform. +

    +There SHOULD be at most one handler for any given Property and newly added handlers replace the old handlers. If no handler is initialized for any given Property, implementations SHOULD implement a default property read handler. +

    5.17 The setPropertyWriteHandler() method

    +Takes name as string argument and writeHandler as argument of type PropertyWriteHandler. Sets the handler function for writing the specified Property matched by name. Throws on error. Returns a reference to the same object for supporting chaining. +

    +There SHOULD be at most one write handler for any given Property and newly added handlers replace the old handlers. If no write handler is initialized for any given Property, implementations SHOULD implement default property update and notifying observers on change. +

    5.18 The setActionHandler() method

    +Takes name as string argument and action as argument of type ActionHandler. Sets the handler function for the specified Action matched by name. Throws on error. Returns a reference to the same object for supporting chaining. +

    +If provided, this callback function will implement invoking an Action and SHOULD be called by implementations when a request for invoking a Action is received from the underlying platform. The callback will receive a parameters dictionary argument. +

    +There SHOULD be exactly one handler for any given Action. If no handler is initialized for any given Action, implementations SHOULD return error if the action is invoked by any client. +

    5.19 Examples

    +Below some ExposedThing interface examples are given. +

    Example 7: Create a new blank exposed Thing
    try {
+  var thing = WoT.produce({ name: "tempSensor" });
+  // manually add Interactions
+  thing.addProperty({
+    name: "temperature",
+    value: 0.0,
+    schema: '{ "type": "number" }'
+    // use default values for the rest
+  }).addProperty({
+    name: "max",
+    value: 0.0,
+    schema: '{ "type": "number" }'
+    // use default values for the rest
+  }).addAction({
+    name: "reset",
+    // no input, no output
+  }).addEvent({
+    name: "onchange",
+    schema: '{ "type": "number" }'
+  });
+  // add server functionality
+  thing.setActionHandler("reset", () => {
+    console.log("Resetting maximum");
+    thing.writeProperty("max", 0.0);
+  });
+  thing.start().then(() => {
+      thing.register();
+  });
+  // define Thing business logic
+  setInterval( async () => {
+    let mock = Math.random()*100;
+    thing.writeProperty("temperature", mock);
+    let old = await thing.readProperty("max");
+    if (old < mock) {
+      thing.writeProperty("max", mock);
+      thing.emitEvent("onchange");
+    }
+  }, 1000);
+} catch (err) {
+   console.log("Error creating ExposedThing: " + err);
+}
    Example 8: Create a new exposed Thing from a Thing Description
    let thingDescription = '{ "@context": [ "https://w3c.github.io/wot/w3c-wot-td-context.jsonld", "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ], "@type": [ "Thing", "Sensor" ], "name": "mySensor", "geo:location": "testspace", "interaction": [ { "@type": [ "Property", "Temperature" ], "name": "prop1", "schema": { "type": "number" }, "saref:TemperatureUnit": "degree_Celsius" } ] }';
+try {
+  // note that produce() fails if thingDescription contains error
+  let thing = WoT.produce(thingDescription);
+  // Interactions were added from TD
+  // WoT adds generic handler for reading any property
+  // define a specific handler for one property
+  let name = "examplePropertyName";
+  thing.setPropertyReadHandler(name, () => {
+    console.log("Handling read request for " + name);
+    return new Promise((resolve, reject) => {
+        let examplePropertyValue = 5;
+        resolve(examplePropertyValue);
+      },
+      e => {
+        console.log("Error");
+      });
+  });
+  thing.start();
+} catch(err) {
+   console.log("Error creating ExposedThing: " + err);
+}
    Example 9: Create a new exposed Thing from a TD URI
    // fetch an external TD, e.g., to set up a proxy for that Thing
+WoT.fetch("http://myservice.org/mySensor/description").then(td => {
+  // WoT.produce() ignores instance-specific metadata (security, form)
+  let thing = WoT.produce(td);
+  // Interactions were added from TD
+  // add server functionality
+  // ...
+});

    6. Experimental extensions to the ConsumedThing interface

    This section is non-normative.

    +The ThingDescription related functionality, such as enumerating Properties, Actions, Events and links (introspection) is an API extension that is out of scope for this specification. However, the draft interfaces are defined here for informative purposes. +

    6.1 The getProperties() method

    +Returns the list of Properties defined in the Thing Description of the Thing in the form of a list of ThingProperty objects. +

    6.2 The getActions() method

    +Returns the list of Actions defined in the Thing Description of the Thing in the form of a list of ThingAction objects. +

    6.3 The getEvents() method

    +Returns the list of Events defined in the Thing Description of the Thing in the form of a list of ThingEvent objects. +

    7. Observables

    This section is non-normative.

    +Observables are proposed to be included in ECMAScript and are used for handling pushed data associated with various possible sources, for instance events, timers, streams, etc. A minimal required implementation is described here. +

    Editor's note

    +This section is informal and contains rather laconic information for implementations on what to support for interoperability. +

    interface Observable {
+    Subscription subscribe((Observer or OnNext) next,
+                           optional OnError error,
+                           optional OnComplete complete);
+};
+
+interface Subscription {
+    void unsubscribe();
+    readonly attribute boolean closed;
+};
+
+interface Observer {
+    void next(any value);
+    void error(Error error);
+    void complete();
+};
+
+callback OnNext = void (any value);
+
+callback OnError = void (Error error);
+
+callback OnComplete = void ();

    7.1 The Observer interface

    +The Observer interface defines the callbacks needed to handle an Observable: +

      +
    • +The next() function, as well as the OnNext callback takes the next sample for the data in the value argument. +
      • +
    • +The error() function, as well as the OnError callback takes an error in the value argument. It is called when an error occured in producing the data the client should know about. +
      • +
    • +The complete() function, as well as the OnComplete callback is called when the data source has finished sending values. +
      • +

    7.2 The Subscription interface

    +Contains the closed property of type boolean that tells if the subscription is closed or active. +

    +Also, contains the unsubscribe() method that cancels the subscription, i.e. makes a request to the underlying platform to stop receiving data from the source, and sets the closed property to false. +

    7.3 The Observable interface

    +The Observable interface enabled subscribing to pushed data notifications by the subscribe() method: +

      +
    • +If the subscribe() method is called with an Observer object, initialize the data, error and completion handling callbacks from that object, or throw on error. +
      • +
    • +Otherwise, if the subscribe() method is called with a function, initialize the data handler callback with that function. If the next argument is provided and is a function, initialize the error handling callback with that function, or throw on error. If the third argument is provided and is a function, initialize the completion handler with that function, or throw on error. +
      • +
    • +After callback initializations, the implementation should request the underlying platform to provide data, error and completion notifications for the supported data source. +
      • +

    8. Security and Privacy

    Editor's note

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

    9. Terminology and conventions

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

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

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

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

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

    +The term + + secure context is defined in [WEBAPPSEC]. +

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

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

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

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

    +The terms hyperlink reference and relation type are defined in [HTML5] and RFC8288. +

    10. Conformance

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

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

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

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

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

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

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

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

    A. Changes

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

      +
    • +Synchronized the Scripting API with the Thing Description specification. Defined ThingDescription, ThingTemplate, SemanticAnnotations, SemanticType, SemanticMetadata, input and output data descriptions, etc. +
      • +
    • +Separated consume() to fetch() and consume(). +
      • +
    • +Changed expose() to accept a Thing Template. +
      • +
    • +Instead of addListener(), removeListener() introduced onEvent(), onPropertyChange(), onTDChange(). +
      • +
    • +Revised ExposedThing handlers for Property, Action and Event. +
      • +
    • +Added an informal section on TD introspection. +
      • +
    • +Added informal section for Observable. +
      • +

    B. Open issues

    +The following problems are being discussed and need most attention: +

    C. Acknowledgements

    +Special thanks to former editor Johannes Hund (until August 2017, when at Siemens AG) for developing this specification. Also, the editors would like to thank Dave Raggett, Matthias Kovatsch, Michael Koster and Michael McCool for their comments and guidance. +

    D. References

    D.1 Normative references

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

    D.2 Informative references

    [WOT-TD]
    WoT Thing Description . W3C. 20 August 2017. URL: https://w3c.github.io/wot-thing-description/ +
    diff --git a/releases/wd2/diff.html b/releases/wd2/diff.html new file mode 100644 index 00000000..1ff0e8e1 --- /dev/null +++ b/releases/wd2/diff.html @@ -0,0 +1,15000 @@ + + + + + + + + + + + + +Web of Things (WoT) Scripting API + + + + + + + + + + + +"false"> + +
    + +

    +Web +of +Things +(WoT) +Scripting +API +

    +

    + +W3C + +First +Public +Working + +Editor's + +Draft +14 +September +2017 + + +

    +
    +
    +This +version: +
    +
    +https://www.w3.org/TR/2017/WD-wot-scripting-api-20170914/ + + +https://w3c.github.io/wot-scripting-api/ + + +
    +
    +Latest +published +version: +
    +
    + +https://www.w3.org/TR/wot-scripting-api/ + +
    +
    +Latest +editor's +draft: +
    +
    + +https://w3c.github.io/wot-scripting-api/ + +
    +
    +Editors: +
    +
    + +Zoltan +Kis +, + + +( + + +Intel + +) + +
    +
    + +Kazuaki +Nimura +, + + +( + + +Fujitsu +Ltd. + +) + +
    +
    + +Daniel +Peintner +, + + +( + + +Siemens +AG + +) +
    + +Johannes +Hund + +(Former +Editor, +when +at +Siemens +AG) + +
    +
    +Contributors: +
    +
    + +In +the +GitHub +repository + +
    +
    +Repository: +
    +
    + +We +are +on +GitHub + +
    +
    + +File +a +bug + +
    +
    +

    + +Copyright + +© +2017 + +2017-2018 + + + +W3C + + + +® + +( + + +MIT + +, + + +ERCIM + +, + +Keio +, + +Beihang + +). + +W3C + + +liability +, + +trademark + +and + +permissive +document +license + +rules +apply. +

    +
    +
    +
    +

    +Abstract +

    +

    +The + +Web +of +Things + +(WoT) +provides +layered +interoperability +between + +Things + +by +using +the + +WoT +Interface + +s. +

    +

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

    +

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

    +
    +
    +

    +Status +of +This +Document +

    +

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

    +

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

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

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

    +
    +

    +This +document +was +published +by +the + +Web +of +Things +Working +Group + +as +a +First +Public +Working + +an +Editor's + +Draft. +This +document +is +intended +to +become +a +W3C +Recommendation. + +Comments +regarding +this +document +are +welcome. +Please +send +them +to + +public-wot-wg@w3.org + +( + +subscribe +, + +archives + +). +

    +

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

    +

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

    +

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

    +
    + +
    +

    + +1. + +Introduction +

    +

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

    +

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

    +

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

    +
    +
    + +Note + +
    +

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

    +
    +
    +
    + +Note +

    +This +specification +does +not +make +assumptions +on +how +the + +WoT +Runtime + +handles +and +runs +scripts, +including +single +or +multiple +tenancy, +script +deployment +and +lifecycle +management. +The +API +already +supports +the +generic +mechanisms +that +make +it +possible +to +implement +script +management, +for +instance +by +exposing +a +manager + +Thing + +whose + +Actions + +(action +handlers) +implement +script +lifecycle +management +operations. +

    +

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

    +
    +
    +

    + +2. + +Use +Cases +

    +

    + +This +section +is +non-normative. + +

    +

    +The +following +scripting +use +cases +are +covered + +supported + +in +this +specification: +

    +
    +

    + +2.1 + +Discovery +

    +
      +
    • +Discover +all + +Thing + +s +in +the +WoT +network +by +sending +a +broadcast +request. +
      • +
    • +Discover + +Thing + +s +running +in +the +local + +WoT +Runtime +. +
      • +
    • +Discover +nearby + +Thing + +s, +for +instance +by +NFC +or +Bluetooth. +
      • +
    • +Discover + +Thing + +s +by +sending +a +discovery +request +to +a +given +registry. +
      • +
    • +Discover + +Thing + +s +by +filters +defined +on + +Thing +Description + +s +
      • +
    • +Discover + +Thing + +s +by +semantic +filters. +
      • +
    • +Stop +or +suppress +an +ongoing +discovery +process. +
      • +
    • +Optionally +specify +a +timeout +to +the +discovery +process +after +which +it +is +stopped/suppressed. +

    +2.2 + +Consuming +a +Thing +

    +Consume + +
    +
    +

    + +2.3 + +Exposing + +a +thing. + +Thing +

    • +Exposing +the + +Thing + +includes +generating +the +protocol +bindings +in +order +to +access +lower +level +functionality. + +
      • +
    • +Create +and +expose + +a +local +Thing + + + +ExposedThing + + +to +be +exposed, + +based +on +a + +Thing +Description +. +Programmatically +create +and +expose +a +local +Thing +. +This +may +include +the +following +use +cases: +Create + + +provided +in +string +serialized +format, +or +out +of + +a +local +Thing +. + +template +or +an +existing + +ConsumedThing + +object. + +
      • +
    • +Add +a + +Property + +definition +to +the + +Thing +. +
      • +
    • +Add +an +Event + + +Action + + +definition +to +the + +Thing +. +
      • +
    • +Add +an +Action + + +Event + + +definition +to +the + +Thing +. +
      • +
    • +Attach +semantic +information +to +an +Action + +the + +Thing +. +
      • +
    • +Attach +semantic +information +to +a + +Property +. +
      • +
    • +Attach +semantic +information +to +an + +Action +.
    • +Attach +semantic +information +to +an + +Event +. +
      • +
    • +Emit +an + +Event +, +i.e. +notify +all +listeners +subscribed +to +that + +Event +. +
      • +
    • +Register +handlers + +Provide +notifications + +for +external +requests: +to +retrieve +a +Property +value; +to +update +a +Property + + +TD + + +value; +to +run +an +Action +: +take +the +parameters +from +the +request, +execute +the +defined +action, +and +return +the +result; +to +add +a +listener + +changes + +to +an +Event +; + +clients +subscribed + +to +remove +an +Event +listener. + +that. + +
      • +
    • +to +fetch + +Mark/unmark + +the +Thing +Description +; +Register +the +Thing. + +to +be +discoverable. + +
      • +
    • +Unregister + +Mark/unmark + +the +Thing. + +Thing +to +be +consumable. + +
      • +
    • +Start +the +exposed + +Thing + +in +order +to +process +external +requests. +
      • +
    • +Stop +the +exposed + +Thing +. +
      • +The +following +use +cases +are +being +considered + +
    • +Register +handlers + +for +next +versions: + +external +requests: + +
        +
      • +Add, +remove +and +update +the +definition +of + +to +retrieve + +a + +Property + +on +a +Thing +that +runs +in +the +same +the +WoT +Runtime. + +value; + +
        • +
      • +Add, +remove +and + +to + +update +the +definition +of +an +Action +on + +a +Thing +that +runs +in +the +same +the +WoT +Runtime. + + +Property + +value; + +
        • +
      • +Add, +remove +and +update +the +definition +of + +to +run + +an +Event +on +a +Thing +that +runs +in + + +Action +: +take + +the +same + +parameters +from + +the +WoT +Runtime. + +request, +execute +the +defined +action, +and +return +the +result; + +
        • +
      +
      • +
    +
    +
    +
    +

    + +3. + +The + + +WoT + + +object +

    +

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

    +
    +
    + +Note + +
    +

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

    +
    +
    +
    interface "idlInterfaceID"><a data-lt="WoT" href="#dom-wot" class=
+"internalDFN" data-link-type="dfn" data-for=
+""> {
+<span class="idlMethod" id="idl-def-wot-discover(filter)" data-idl=
+
+"idlInterfaceID">WoT {
+    "idlMethType"><a href="#dfn-observable" class="internalDFN"
+data-link-type="dfn">Observable<<a href="#dom-consumedthing"
+class="internalDFN" data-link-type=
+
+"idlMethType">Observable<
+"dfn">ConsumedThing> "idlMethName"><a data-lt="discover()|discover()|discover"
+data-lt-nodefault="" href="#dom-wot-discover()" class="internalDFN"
+data-link-type="dfn" data-for=
+"WoT">discover<a href="#dom-thingfilter"
+class="internalDFN" data-link-type=
+
+"idlMethName">discover(optional 
+"dfn">ThingFilter filter);
+<span class="idlMethod" id="idl-def-wot-consume(url)" data-idl=""
+data-title="consume" data-dfn-for="wot">    <span class=
+
+data-title="fetch" data-dfn-for="wot">    
+"idlMethType">"https://heycam.github.io/webidl/#idl-promise">Promise<<a href="#dom-consumedthing"
+
+"https://heycam.github.io/webidl/#idl-promise">Promise<
+class="internalDFN" data-link-type=
+"dfn">    <span class=
+"idlMethName"><a data-lt="consume()|consume()|consume"
+data-lt-nodefault="" href="#dom-wot-consume()" class="internalDFN"
+data-link-type="dfn" data-for="WoT">consume(<span class=
+
+"dfn">ThingDescription> fetch(
+"idlParam">USVString url);
+<span class="idlMethod" id="idl-def-wot-expose(init)" data-idl=""
+data-title="expose" data-dfn-for="wot">    <span class=
+"idlMethType"><a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<<a href="#dom-exposedthing"
+class="internalDFN" data-link-type=
+"dfn">     <span class=
+"idlMethName"><a data-lt="expose()|expose()|expose"
+data-lt-nodefault="" href="#dom-wot-expose()" class="internalDFN"
+data-link-type="dfn" data-for="WoT">expose(<span class=
+"idlParam"><a href="#dom-thinginit"
+class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">init
+};
+
+data-title="consume" data-dfn-for="wot">    ConsumedThing             consume(ThingDescription td);
+
+data-title="produce" data-dfn-for="wot">    ExposedThing              produce(ThingModel model);
+};
+
+data-title="ThingDescription">typedef USVString ThingDescription;
+
+data-title="ThingModel">typedef (ThingTemplate or ThingDescription) 
+
+ThingModel
+
+;
+
+
+
    +
    +
    +
    + +Editor's +note + +
    +

    +The +algorithms +for +the +WoT +methods +will +be +specified +later. + +later, +including +error +handling +and +security +considerations. + +

    +
    +
    +

    + +3.1 + +The + + +discover() + + +method +

    +

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

    +
    +

    + +3.1.1 + +The + + +DiscoveryMethod + +enumeration +

    
+"idl-def-discoverymethod" data-idl="" data-title=
+"DiscoveryMethod">typedef DOMString 
+
+DiscoveryMethod
+
+;
+

    +DiscoveryMethod + +represents +the +discovery +type +to +be +used: +

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

    +3.1.2 + +The + + + +ThingFilter + + +dictionary +

    +

    +The + + +ThingFilter + + +dictionary +that +represents +the +constraints +for +discovering + +Thing + +s +as +key-value +pairs. +

    +
    +
    "ThingFilter">dictionary <a data-lt=
+"ThingFilter" href="#dom-thingfilter" class="internalDFN"
+data-link-type="dfn" data-for=
+""> {
+
+"ThingFilter">dictionary ThingFilter {
+
+    "idlMemberType">(DiscoveryType or <a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="method"
+href="#dom-thingfilter-method" class="internalDFN" data-link-type=
+"dfn" data-for=
+"ThingFilter"> = <span class=
+
+"idlMemberType">DiscoveryMethod      method = 
+"idlMemberValue">"any";
+    "https://heycam.github.io/webidl/#idl-USVString">USVString<a data-lt="url"
+href="#dom-thingfilter-url" class="internalDFN" data-link-type=
+"dfn" data-for="ThingFilter">
+<span class="idlMember" id="idl-def-thingfilter-description"
+data-idl="" data-title="description" data-dfn-for=
+"thingfilter">    <span class=
+"idlMemberType">Dictionary                   <span class=
+"idlMemberName"><a data-lt="description" href=
+"#dom-thingfilter-description" class="internalDFN" data-link-type=
+"dfn" data-for=
+"ThingFilter">
+
+"https://heycam.github.io/webidl/#idl-USVString">USVString            url;
+
+data-title="query" data-dfn-for="thingfilter">    USVString            query;
+
+data-idl="" data-title="constraints" data-dfn-for=
+"thingfilter">    sequence<Dictionary> constraints;
+
+};
+
+
    +
    +

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

    +The +url +property +represents +additional +information +for +the +discovery +method, +such +as +the +URL +of +the +Thing +Directory +server +to +be +used. +The +description +property +represents +additional +information +for +the +discovery +method +in +the +form +of +a +set +of +key-value +pairs, +as +defined +in +the +Thing +Description +. + +
    +
    + +Editor's +note + +
    +

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

    +
    +Editor's +note + +

    +The + + +ThingFilter + +url + + + +property +represents +additional +information +for +the +discovery +method, +such +as +the +URL +of +the +target +entity +serving +the +discovery +request, +such +as +a + +Thing +Directory + + +dictionary +may +be +extended +later +with +further +attributes. + +or +a +Thing. + +

    +3.1.2 + +

    +The + + +DiscoveryMethod + +query + + + +enumeration +<span class="idlEnum" id= +"idl-def-discoverymethod" data-idl="" data-title= +"DiscoveryMethod">enum <a data-lt= +"DiscoveryMethod" href="#dom-discoverymethod" class="internalDFN" +data-link-type="dfn" data-for= +""> { + <a href="#dom-discoverymethod-any" class= +"idlEnumItem">"any", + <a href="#dom-discoverymethod-local" class= +"idlEnumItem">"local", + <a href="#dom-discoverymethod-nearby" class= +"idlEnumItem">"nearby", + <a href="#dom-discoverymethod-directory" class= +"idlEnumItem">"directory", + <a href="#dom-discoverymethod-broadcast" class= +"idlEnumItem">"broadcast", + <a href="#dom-discoverymethod-other" class= +"idlEnumItem">"other" +}; + +property +represents +a +query +string +accepted +by +the +implementation, +for +instance +a +SPARQL +query. +

    +

    +The + + +DiscoveryMethod + +constraints + + +enumeration + + +property + +represents +additional +information +for + +the +discovery +type + +method +in +the +form +of +a +list +of +sets +of +property-value +pairs +(dictionaries). +The +list +elements +(dictionaries) +are +in +OR +relationship, +and +within +a +constraint +dictionary +the +key-value +pairs +are +in +AND +relationship. +Implementations + +SHOULD + +make +the +following +mapping +from +the +constraint +dictionaries + +to +be +used: +" + + + +any + +SemanticAnnotations + + +" +does +not +provide +any +restriction + +: +for +each +property-value +pair +in +a +constraint +dictionary, +

      +
    • +" + +Each +property +name +in +the +constraint +dictionary + +SHOULD + +match +the +either +the + + +local + +name + + +" +for +discovering +Thing +s + +property +of +a + +defined +in +the +same +device +" + + + +nearby + +SemanticType + + +" +for +discovering +Thing + + +s +nearby + +on + +the +device, +e.g. +by +Bluetooth + +target + +Thing + +object, + +or +NFC + +the +name +of +a + +Property + +on +the +target + +Thing +. +
      • +
    • +" + +When +the +name +matches, +the +values +are +compared. +If +the +values +match, +the +constraint +is +matched. +
    +Editor's +note +

    +Constraints +are +experimental +feature, +implementations +are +not +required +to +support +them. +

    + +Editor's +note +

    +Semantic +annotations +need +revisiting +in +order +to +simplify +their +representation. +In +the +[ + +WOT-TD + +] +specification +they +represent +the + + +directory + +@type + +construct. +At +the +moment +only + +@context +, +@type + +and + +@id + + +constructs +are +used +in +the + +TD +.

    +" +for +discovery +based +on +a +service +provided +by +a +directory +or +repository +of +Thing +s +" + + +3.2 + +The + + +broadcast + +fetch() + + + +" +for + +method +

    +Accepts + +an +open +ended +discovery +based +on +sending + + +url + +argument +and +returns + +a +request +to + + + +Promise + +that +resolves +with + +a +broadcast +address +" + + + +other + +ThingDescription +.

    +3.3 + +The + +ThingDescription + + + +" +for +a +proprietary +method +defined +by + +type +

    +Representation +of + +the +solution. + + +Thing +Description +, +standardized +in +the + +Wot +Things +Description + +specification. +

    +Note +

    +In +this +version +of +the +API, + +Thing +Description + +s +are +represented +as +opaque +strings, +denoting +a +serialized +form, +for +instance +JSON +or +JSON-LD. +See + +Issue +38 + +and + +Issue +45 +.

    +
    +
    +

    + +3.2 + +3.4 + + +The + + +consume() + + +method +

    +

    +Accepts +an + +url + +td + + +argument +and +returns +a + +of +type + + +Promise + + + +ThingDescription + + + +of + +and +returns + +a + + +ConsumedThing + +. + + +object +instantiated +based +on +that +description. + +

    +
    +
    +

    + +3.3 + +3.5 + + +The + + +expose() + +produce() + + + +method +

    +

    +Returns + +Accepts + +a + +model + +argument +of +type + +ThingModel + +Promise + + + +of +a +locally +created + +and +returns +an + + +ExposedThing + + +object, +locally +created + +based +on +the +provided +initialization +parameters. +Editor's +note +The +reason + +An + + +ExposedThing + + +s +are + +can +be + +created +by + +in +the +following +ways: +

    1. +from +an +initial +model +(including + +a +factory +method +instead + +user +given +name +and + +semantic +annotations + +), +then +adding +properties, +actions, +events +and +request +handlers; +
    2. +from +a + +Thing +Description + +(possibly + +of +a +constructor + + + +ConsumedThing + +object), +then +adding +request +handlers. +

    +3.6 + +The + +ThingModel + +type +

    +A +Thing +model + +is +that +an + +used +for +producing +a +new + + +ExposedThing + + +may + +and +can + +be +created +in +the +local +WoT +Runtime + +either +a + +ThingTemplate +, +or +in + +a +remote +runtime. +Even +though +currently +only +local +creation +is +supported, +the +method +is +designed +with +this +possible +future +compatibility +in +mind. + + + +ThingDescription +. +

    +
    +
    +

    + +3.3.1 + +3.7 + + +The + + +ThingInit + +SemanticAnnotations + + + +dictionary +

    +

    +A +dictionary +that +provides +the +semantic +types +and +semantic +metadata. +

    +
    +
    "idl-def-thinginit" data-idl="" data-title=
+"ThingInit">dictionary <a data-lt=
+"ThingInit" href="#dom-thinginit" class="internalDFN"
+data-link-type="dfn" data-for=
+""> {
+<span class="idlMember" id="idl-def-thinginit-name" data-idl=""
+data-title="name" data-dfn-for="thinginit">    <span class=
+"idlMemberType"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name"
+href="#dom-thinginit-name" class="internalDFN" data-link-type="dfn"
+data-for="ThingInit">
+<span class="idlMember" id="idl-def-thinginit-url" data-idl=""
+data-title="url" data-dfn-for="thinginit">    <span class=
+
+"idl-def-semanticannotations" data-idl="" data-title=
+"SemanticAnnotations">dictionary SemanticAnnotations {
+
+"idl-def-semanticannotations-semantictype" data-idl="" data-title=
+"semanticType" data-dfn-for="semanticannotations">    
+"idlMemberType">"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-lt="url"
+href="#dom-thinginit-url" class="internalDFN" data-link-type="dfn"
+data-for="ThingInit">
+<span class="idlMember" id="idl-def-thinginit-description"
+data-idl="" data-title="description" data-dfn-for=
+"thinginit">    <span class=
+"idlMemberType">Dictionary <span class=
+"idlMemberName"><a data-lt="description" href=
+"#dom-thinginit-description" class="internalDFN" data-link-type=
+"dfn" data-for=
+"ThingInit">
+
+"https://heycam.github.io/webidl/#idl-sequence">sequence<SemanticType>     semanticType;
+
+data-idl="" data-title="metadata" data-dfn-for=
+"semanticannotations">    sequence<SemanticMetadata> metadata;
+
+};
+
+
    +
    +

    +The + + +ThingInit + +semanticType + +property +denotes +a +list +of + +SemanticType + + + +objects +that +define +the +semantic +types +that +can +be +used +in +semantic +metadata +type-value +pairs. +

    +The + +metadata + +property +denotes +a +list +of + +SemanticMetadata + +objects +(type-value +pairs). +

    +3.8 + +The + +SemanticType + +dictionary +contains +properties +to +initialize + +

    +
    +
    "idl-def-semantictype" data-idl="" data-title=
+"SemanticType">dictionary SemanticType {
+
+data-title="name" data-dfn-for=
+"semantictype">    required DOMString name;
+
+"" data-title="context" data-dfn-for=
+"semantictype">    required USVString context;
+
+"" data-title="prefix" data-dfn-for=
+"semantictype">             DOMString prefix;
+};
+

    +Represents + +a +Thing +: + +semantic +type +annotation, +containing +a +name, +a +context +and +a +prefix. + +

    +
      +
    • +The + + +name + + +attribute +represents +the +user +given + +name +of +the +Thing +. + +semantic +type +in +the +given +context. + +
      • +
    • +The + + +url + +context + + + +attribute +represents +an +URL +link +to + +the +address + +context + +of +the +Thing +. + +semantic +classification. + +
      • +
    • +The + + +description + +prefix + +attribute +represents +a +short +prefix +associated +with +a +context. +
    +Editor's +note +

    +Semantic +type +examples +to +be +added. +

    +3.9 + +The + +SemanticMetadata + +dictionary +

    
+"idl-def-semanticmetadata" data-idl="" data-title=
+"SemanticMetadata">dictionary SemanticMetadata {
+
+data-idl="" data-title="type" data-dfn-for=
+"semanticmetadata">    SemanticType type;
+
+data-idl="" data-title="value" data-dfn-for=
+"semanticmetadata">    any          value;
+};
+

    +The + +SemanticMetadata + +dictionary +describes +a +pair +of +semantic +type +and +value: +

    • +The + +type + + + +attribute +represents +the +semantic +type +name +defined +by +a + +SemanticType + +object. +
    • +The + +value + +attribute +represents +the +metadata +value. +

    +3.10 + +The + +ThingTemplate + +dictionary +

    +A +Thing +Template +is +a +dictionary +that +provides +a +user +given +name, +and +the +semantic +types +and +semantic +metadata +attached +to +the + +ExposedThing + +Thing +Description + +'s +root +level. +

    
+"idl-def-thingtemplate" data-idl="" data-title=
+"ThingTemplate">dictionary ThingTemplate : SemanticAnnotations {
+
+data-title="name" data-dfn-for=
+"thingtemplate">    required DOMString name;
+};
+

    +The + +ThingTemplate + +dictionary +extends + +SemanticAnnotations + +and +contains +properties +to +initialize +a + +Thing +:

    • +The + +name + +attribute +represents +the +user +given +name + +of +the + +Thing +. +
      • +
    +
    +
    + +Editor's +note +

    +Support +for +configuration +and +security +data +might +be +added +later. +

    +
    +
    +

    + +3.4 + +3.11 + + +Examples +

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

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

    +
    +
    +
    + +Example +2 + +: +Discover +Things +exposed +by +local +hardware + +
    +<span class= + +
    let subscription = wot.discover({ method: "local" }).subscribe(
+  thing => { console.log("hljs-string">"Found local Thing " + thing.url); },
+
+"hljs-string">"Found local Thing " + thing.name); },
+
+  error => { console.log("Discovery error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);
+
    +
    +
    +
    + +Example +3 + +: +Same +as +above +but +with +different +Observable +syntax +
    
+"hljs-keyword">let subscription = wot.discover({ method: "local" }).subscribe({
+  thing => { console.log("Found local Thing " + thing.name); },
+  error: 
+"hljs-function">err => { console.log("Discovery error: " + err.message); },
+  complete: 
+"hljs-function">() => { console.log("Discovery finished successfully");}
+});
+
    +Example +4 +: +Discover +Things +exposed +nearby, +e.g. + +via +Bluetooth +or +NFC + + +
    +<span class= +"hljs-keyword">let} }).subscribe( + +
    "hljs-keyword">let subscription = wot.discover({
+  method: 
+"hljs-string">"nearby",
+  constraints: [{ 
+"hljs-attr">protocol: "BLE-4.2" }, { protocol: "NFC"}]
+}).subscribe(
+
+  thing => { console.log("hljs-string">"Found nearby Thing " + thing.url); },
+
+"hljs-string">"Found nearby Thing " + thing.name); },
+
+  error => { console.log("Discovery error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);
+
    +
    +
    +
    + +Example +4 + +5 + + +: +Discover +Things +exposed +in +a +proprietary +way + +
    +<span class= +"hljs-keyword">let} }).subscribe( + +
    "hljs-keyword">let subscription = wot.discover({
+  method: 
+"hljs-string">"other",
+  constraints: [{ 
+"hljs-attr">solution: "XYZ123", key: "..."}]
+}).subscribe(
+
+  thing => { console.log("hljs-string">"Found Thing " + thing.url); },
+
+"hljs-string">"Found Thing " + thing.name); },
+
+  error => { console.log("Discovery error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);
+
    +
    +
    +
    +
    +

    + +4. + +The + + +ConsumedThing + + +interface +

    +

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

    +
    +
    "ConsumedThing">interface <a data-lt=
+"ConsumedThing" href="#dom-consumedthing" class="internalDFN"
+data-link-type="dfn" data-for=
+""> {
+
+"ConsumedThing">interface ConsumedThing {
+
+    readonly attribute "https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name"
+href="#dom-consumedthing-name" class="internalDFN" data-link-type=
+"dfn" data-for="ConsumedThing">
+<span class="idlAttribute" id="idl-def-consumedthing-url" data-idl=
+"" data-title="url" data-dfn-for=
+"consumedthing">    readonly attribute <span class=
+"idlAttrType"><a href=
+"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-lt="url"
+href="#dom-consumedthing-url" class="internalDFN" data-link-type=
+"dfn" data-for="ConsumedThing">
+<span class="idlAttribute" id="idl-def-consumedthing-description"
+data-idl="" data-title="description" data-dfn-for=
+"consumedthing">    readonly attribute <span class=
+"idlAttrType"><a href="#dom-thingdescription" class="internalDFN"
+
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name;
+
+"idl-def-consumedthing-getthingdescription" data-idl="" data-title=
+"getThingDescription" data-dfn-for="consumedthing">    
+data-link-type=
+"dfn">ThingDescription "idlAttrName"><a data-lt="description" href=
+"#dom-consumedthing-description" class="internalDFN"
+data-link-type="dfn" data-for=
+"ConsumedThing">
+<span class="idlMethod" id=
+"idl-def-consumedthing-invokeaction(name,parameters)" data-idl=""
+data-title="invokeAction" data-dfn-for=
+"consumedthing">    <a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="invokeAction()|invokeaction()|invokeAction"
+data-lt-nodefault="" href="#dom-consumedthing-invokeaction()"
+class="internalDFN" data-link-type="dfn" data-for=
+"ConsumedThing">invokeAction(<span class=
+"idlParam"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class="idlMethod" id=
+"idl-def-consumedthing-setproperty(name,value)" data-idl=""
+data-title="setProperty" data-dfn-for=
+"consumedthing">    <a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="setProperty()|setproperty()|setProperty"
+data-lt-nodefault="" href="#dom-consumedthing-setproperty()" class=
+"internalDFN" data-link-type="dfn" data-for=
+"ConsumedThing">setProperty(<span class=
+"idlParam"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+
+"idlMethName">getThingDescription();
+
+"idl-def-consumedthing-getproperty(name)" data-idl="" data-title=
+"getProperty" data-dfn-for="consumedthing">    <span class=
+
+"idl-def-consumedthing-readproperty-name" data-idl="" data-title=
+"readProperty" data-dfn-for="consumedthing">    
+"idlMethType">"https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="getProperty()|getproperty()|getProperty"
+data-lt-nodefault="" href="#dom-consumedthing-getproperty()" class=
+"internalDFN" data-link-type="dfn" data-for=
+"ConsumedThing">getProperty(<span class=
+
+"https://heycam.github.io/webidl/#idl-promise">Promise<any>     readProperty(
+"idlParam">DOMString name);
+"idl-def-consumedthing-addlistener(eventname,listener)" data-idl=""
+data-title="addListener" data-dfn-for=
+
+"idl-def-consumedthing-writeproperty-name-value" data-idl=""
+data-title="writeProperty" data-dfn-for=
+
+"consumedthing">    "#dom-consumedthing" class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlMethName"><a data-lt="addListener()|addlistener()|addListener"
+data-lt-nodefault="" href="#dom-consumedthing-addlistener()" class=
+"internalDFN" data-link-type="dfn" data-for=
+"ConsumedThing">addListener(<span class=
+
+"https://heycam.github.io/webidl/#idl-promise">Promise<void>    writeProperty(
+"idlParam">"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a href="#dom-thingeventlistener"
+class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">listener
+
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name, any value);
+
+"idl-def-consumedthing-removelistener(eventname,listener)"
+data-idl="" data-title="removeListener" data-dfn-for=
+
+"idl-def-consumedthing-invokeaction-name-parameters" data-idl=""
+data-title="invokeAction" data-dfn-for=
+
+"consumedthing">    "#dom-consumedthing" class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlMethName"><a data-lt=
+"removeListener()|removelistener()|removeListener"
+data-lt-nodefault="" href="#dom-consumedthing-removelistener()"
+class="internalDFN" data-link-type="dfn" data-for=
+"ConsumedThing">removeListener(<span class=
+"idlParam"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString,
+                                 <span class=
+
+"https://heycam.github.io/webidl/#idl-promise">Promise<any>     invokeAction(
+"idlParam">"#dom-thingeventlistener" class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">listener
+
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name, any parameters);
+
+"idl-def-consumedthing-removealllisteners(eventname)" data-idl=""
+data-title="removeAllListeners" data-dfn-for=
+
+"idl-def-consumedthing-onpropertychange-name" data-idl=""
+data-title="onPropertyChange" data-dfn-for=
+
+"consumedthing">    "#dom-consumedthing" class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlMethName"><a data-lt=
+"removeAllListeners()|removealllisteners()|removeAllListeners"
+data-lt-nodefault="" href="#dom-consumedthing-removealllisteners()"
+class="internalDFN" data-link-type="dfn" data-for=
+"ConsumedThing">removeAllListeners(<span class=
+"idlParam">optional <a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class="idlMethod" id=
+"idl-def-consumedthing-observe(name,requesttype)" data-idl=""
+data-title="observe" data-dfn-for="consumedthing">    <span class=
+"idlMethType"><a href="#dfn-observable" class="internalDFN"
+data-link-type="dfn">Observable    <span class=
+"idlMethName"><a data-lt="observe()|observe()|observe"
+data-lt-nodefault="" href="#dom-consumedthing-observe()" class=
+"internalDFN" data-link-type="dfn" data-for=
+"ConsumedThing">observe(<span class=
+
+"#dom-observable" class="internalDFN" data-link-type=
+"dfn">Observable       onPropertyChange(
+"idlParam">"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a href="#dom-requesttype"
+
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name);
+
+data-idl="" data-title="onEvent" data-dfn-for=
+"consumedthing">    Observable       
+class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">requestType
+};
+<span class="idlCallback" id="idl-def-thingeventlistener" data-idl=
+"" data-title="ThingEventListener">callback <span class=
+"idlCallbackID"><a data-lt="ThingEventListener" href=
+"#dom-thingeventlistener" class="internalDFN" data-link-type="dfn"
+data-for=
+""> = <span class=
+"idlCallbackType">void<span class=
+"idlParamType"><a href="#dfn-event" class="internalDFN"
+data-link-type="dfn">Event <span class=
+"idlParamName">
+event
+);
+
+"dfn">onEvent(DOMString name);
+
+data-idl="" data-title="onTDChange" data-dfn-for=
+"consumedthing">    Observable       onTDChange();
+};
+
+
+
    +
    +

    +Represents + + +ConsumedThing + +represents + +a +local +proxy +object +of +the +remote + +Thing +. +

    +
    +

    + +4.1 + +The + + +name + + +read-only +attribute +represents +the +name +of +the +Thing +. + +property +

    +The + +url + +name + + +read-only +attribute + +property + +represents +the +URL + +name + +of +the + +Thing + +as +specified +in +the + +TD + +. +In +this +version +it +is +read +only. +

    +4.2 + +The + + +description + +getThingDescription() + + + +attribute +read-only +attribute +represents + +method +

    +Returns + +the +description + + +Thing +Description + +of +the + +Thing +. +

    +
    +
    + +Editor's +note + +
    +

    +In +this +version, +introspection +based +on + +TD + +is +out +of +scope. + +Parsing +and +exposing + +Thing +Description + +s +is +discussed +in + +Issue +38 +. +

    +
    +
    +
    +

    + +4.1 + +4.3 + + +The + + +invokeAction() + +readProperty() + + + +method +

    +

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

    +
    +
    +

    + +4.2 + +4.4 + + +The + + +setProperty() + +writeProperty() + + + +method +

    +

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

    +
    +
    +

    + +4.3 + +4.5 + + +The + + +getProperty() + +invokeAction() + + + +method +

    +

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

    +
    +
    +

    + +4.4 + +4.6 + + +The + + +addListener() + +onPropertyChange() + + + +method +

    +

    +Adds +the +listener +provided +in +the +argument +listener +to +the +Event +name +provided +in +the +argument +eventName +. +4.5 +The + +Returns +an + + +removeListener() + +Observable + + +method +Removes +a +listener +from + + +for + +the +Event + + +Property + + +identified +by + +specified +in + +the +provided + + +eventName + +name + + +argument, +allowing +subscribing +to + +and +listener +argument. + +unsubscribing +from +notifications. + +

    +4.6 + +

    +The +callback +function +passed +to +the + + +removeAllListeners() + +subscribe() + + +method +Removes +all +listeners +for + +when +invoked +on + +the +Event +provided +by + +returned +observer +will +receive + +the +eventName +optional +argument, +or +if +that +was +not +provided, +then +removes +all +listeners +from +all +Events +. + +new +property +value +each +time +it +is +changed. + +

    +
    +
    +

    + +4.7 + +The + + +observe() + +onEvent() + + + +method +

    +

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

    +Editor's +note +The +observe() +method +could +replace +addListener() +and +removeListener() +, +though +they +could +be +kept +for +convenience. +4.8 + +

    +The +ThingEventListener + +callback +A + +function +called +with +an +Event +object +when +an +event +is +emitted. +4.9 +Events +Clients +can +subscribe + +passed + +to +the +Events +defined +in +ExposedThing +events +. +The +event +types +are +described +in +this +section. +4.9.1 +The +PropertyChangeEvent +interface +<span class="idlInterface" id= +"idl-def-propertychangeevent" data-idl="" data-title= +"PropertyChangeEvent">[<span class= +"extAttrName"><a href= +"https://heycam.github.io/webidl/#Constructor">Constructor<a href="#dom-propertychangeeventinit" +class="internalDFN" data-link-type= +"dfn"> <span class= +"idlParamName">init] +interface <a data-lt= +"PropertyChangeEvent" href="#dom-propertychangeevent" class= +"internalDFN" data-link-type="dfn" data-for= +""> : <span class= +"idlSuperclass"><a href="#dfn-event" class="internalDFN" +data-link-type="dfn">Event { +<span class="idlAttribute" id="idl-def-propertychangeevent-data" +data-idl="" data-title="data" data-dfn-for= +"propertychangeevent"> readonly attribute <span class= +"idlAttrType"><a href="#dom-propertychangeeventinit" class= +"internalDFN" data-link-type= +"dfn"> <span class= +"idlAttrName"><a data-lt="data" href= +"#dom-propertychangeevent-data" class="internalDFN" data-link-type= +"dfn" data-for= +"PropertyChangeEvent"> +}; +The +data +attribute +represents +the +changed +Property +. +4.9.1.1 +The + + +PropertyChangeEventInit +dictionary +<span class="idlDictionary" id= +"idl-def-propertychangeeventinit" data-idl="" data-title= +"PropertyChangeEventInit">dictionary <span class= +"idlDictionaryID"><a data-lt="PropertyChangeEventInit" href= +"#dom-propertychangeeventinit" class="internalDFN" data-link-type= +"dfn" data-for=""> { +<span class="idlMember" id="idl-def-propertychangeeventinit-name" +data-idl="" data-title="name" data-dfn-for= +"propertychangeeventinit"> <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name" +href="#dom-propertychangeeventinit-name" class="internalDFN" +data-link-type="dfn" data-for= +"PropertyChangeEventInit"> +<span class="idlMember" id="idl-def-propertychangeeventinit-value" +data-idl="" data-title="value" data-dfn-for= +"propertychangeeventinit"> <a href= +"https://heycam.github.io/webidl/#idl-any">any<a data-lt="value" +href="#dom-propertychangeeventinit-value" class="internalDFN" +data-link-type="dfn" data-for= +"PropertyChangeEventInit"> +}; +The +name +> +attribute +represents +the +Property +name. +The +value + +subscribe() + + +attribute +represents +the +new +value +of + +method +when +invoked +on + +the +Property +. +4.9.2 +The +ActionInvocationEvent +interface +<span class="idlInterface" id= +"idl-def-actioninvocationevent" data-idl="" data-title= +"ActionInvocationEvent">[<span class= +"extAttrName"><a href= +"https://heycam.github.io/webidl/#Constructor">Constructor<a href="#dom-actioninvocationeventinit" +class="internalDFN" data-link-type= +"dfn">] +interface <a data-lt= +"ActionInvocationEvent" href="#dom-actioninvocationevent" class= +"internalDFN" data-link-type="dfn" data-for= +""> : <span class= +"idlSuperclass"><a href="#dfn-event" class="internalDFN" +data-link-type="dfn">Event { +<span class="idlAttribute" id="idl-def-actioninvocationevent-data" +data-idl="" data-title="data" data-dfn-for= +"actioninvocationevent"> readonly attribute <span class= +"idlAttrType"><a href="#dom-actioninvocationeventinit" class= +"internalDFN" data-link-type= +"dfn"><a data-lt="data" +href="#dom-actioninvocationevent-data" class="internalDFN" +data-link-type="dfn" data-for= +"ActionInvocationEvent"> +}; +The +data +attribute +represents + +returned +observer +will +receive + +the +notification + +event + +data +from +the +Action +invocation. +4.9.2.1 +The +ActionInvocationEventInit +dictionary +<span class="idlDictionary" id= +"idl-def-actioninvocationeventinit" data-idl="" data-title= +"ActionInvocationEventInit">dictionary <span class= +"idlDictionaryID"><a data-lt="ActionInvocationEventInit" href= +"#dom-actioninvocationeventinit" class="internalDFN" +data-link-type="dfn" data-for= +""> { +<span class="idlMember" id= +"idl-def-actioninvocationeventinit-actionname" data-idl="" +data-title="actionName" data-dfn-for= +"actioninvocationeventinit"> <span class= +"idlMemberType"><a data-lt="actionName" +href="#dom-actioninvocationeventinit-actionname" class= +"internalDFN" data-link-type="dfn" data-for= +"ActionInvocationEventInit"> +<span class="idlMember" id= +"idl-def-actioninvocationeventinit-returnvalue" data-idl="" +data-title="returnValue" data-dfn-for= +"actioninvocationeventinit"> <span class= +"idlMemberType"><a data-lt="returnValue" +href="#dom-actioninvocationeventinit-returnvalue" class= +"internalDFN" data-link-type="dfn" data-for= +"ActionInvocationEventInit"> +}; +Editor's +note +Action +parameters +could +be +also +included, +but +it's +debatable +because +privacy +reasons. +The +actionName +attribute +represents +the +name +of +the +Action +that +has +been +invoked. +The +returnValue +attribute +represents +the +return +value +of + +each +time + +the +Action +. + +event +is +fired. + +

    +
    +
    +

    + +4.9.3 + +4.8 + + +The + + +ThingDescriptionChangeEvent + +onTDChange() + + + +interface +<span class="idlInterface" id= +"idl-def-thingdescriptionchangeevent" data-idl="" data-title= +"ThingDescriptionChangeEvent">[<span class= +"extAttrName"><a href= +"https://heycam.github.io/webidl/#Constructor">Constructor<a href="#dom-thingdescriptionchangeeventinit" +class="internalDFN" data-link-type= +"dfn">] +interface <a data-lt= +"ThingDescriptionChangeEvent" href= +"#dom-thingdescriptionchangeevent" class="internalDFN" +data-link-type="dfn" data-for= +""><a href="#dfn-event" +class="internalDFN" data-link-type="dfn">Event { +<span class="idlAttribute" id= +"idl-def-thingdescriptionchangeevent-data" data-idl="" data-title= +"data" data-dfn-for= +"thingdescriptionchangeevent"> readonly attribute <span class= +"idlAttrType"><a href="#dom-thingdescriptionchangeeventinit" class= +"internalDFN" data-link-type= +"dfn"><a data-lt="data" +href="#dom-thingdescriptionchangeevent-data" class="internalDFN" +data-link-type="dfn" data-for= +"ThingDescriptionChangeEvent"> +}; + +method +

    +

    +The + +Returns +an + + +data + +Observable + + +attribute +represents +the +changes +that +occurred + +, +allowing +subscribing +to +and +unsubscribing +from +notifications + +to +the + +Thing +Description +. +

    +4.9.3.1 +The +ThingDescriptionChangeEventInit +dictionary +<span class="idlDictionary" id= +"idl-def-thingdescriptionchangeeventinit" data-idl="" data-title= +"ThingDescriptionChangeEventInit">dictionary <span class= +"idlDictionaryID"><a data-lt="ThingDescriptionChangeEventInit" +href="#dom-thingdescriptionchangeeventinit" class="internalDFN" +data-link-type="dfn" data-for= +""> { +<span class="idlMember" id= +"idl-def-thingdescriptionchangeeventinit-type" data-idl="" +data-title="type" data-dfn-for= +"thingdescriptionchangeeventinit"> <span class= +"idlMemberType"><a href="#dom-tdchangetype" class="internalDFN" +data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-lt="type" href= +"#dom-thingdescriptionchangeeventinit-type" class="internalDFN" +data-link-type="dfn" data-for= +"ThingDescriptionChangeEventInit"> +<span class="idlMember" id= +"idl-def-thingdescriptionchangeeventinit-method" data-idl="" +data-title="method" data-dfn-for= +"thingdescriptionchangeeventinit"> <span class= +"idlMemberType"><a href="#dom-tdchangemethod" class="internalDFN" +data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-lt="method" href= +"#dom-thingdescriptionchangeeventinit-method" class="internalDFN" +data-link-type="dfn" data-for= +"ThingDescriptionChangeEventInit"> +<span class="idlMember" id= +"idl-def-thingdescriptionchangeeventinit-name" data-idl="" +data-title="name" data-dfn-for= +"thingdescriptionchangeeventinit"> <span class= +"idlMemberType"><a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name" +href="#dom-thingdescriptionchangeeventinit-name" class= +"internalDFN" data-link-type="dfn" data-for= +"ThingDescriptionChangeEventInit"> +<span class="idlMember" id= +"idl-def-thingdescriptionchangeeventinit-data" data-idl="" +data-title="data" data-dfn-for= +"thingdescriptionchangeeventinit"> <span class= +"idlMemberType"><a href="#dom-tdchangedata" class="internalDFN" +data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-lt="data" href= +"#dom-thingdescriptionchangeeventinit-data" class="internalDFN" +data-link-type="dfn" data-for= +"ThingDescriptionChangeEventInit"> +<span class="idlMember" id= +"idl-def-thingdescriptionchangeeventinit-description" data-idl="" +data-title="description" data-dfn-for= +"thingdescriptionchangeeventinit"> <span class= +"idlMemberType"><a href="#dom-thingdescription" class="internalDFN" +data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-lt="description" href= +"#dom-thingdescriptionchangeeventinit-description" class= +"internalDFN" data-link-type="dfn" data-for= +"ThingDescriptionChangeEventInit"> +}; +The +type +attribute +represents +the +change +type, +whether +has +it +been +applied +on +properties, +Actions +or +Events +. +The +method +attribute +tells +what +operation +has +been +applied, +addition, +removal +or +change. +The +name +attribute +represents +the +name +of +the +Property +, +Action +or +event +that +has +changed. +The +description +attribute +is +defined +for +the +addition +and +change +methods, +and +represents +the +new +description. +The +data +attribute +provides +the +initialization +data +for +the +added +or +changed +elements. +4.9.3.1.1 +The +TDChangeMethod +enumeration +<span class="idlEnum" id= +"idl-def-tdchangemethod" data-idl="" data-title= +"TDChangeMethod">enum <a data-lt= +"TDChangeMethod" href="#dom-tdchangemethod" class="internalDFN" +data-link-type="dfn" data-for= +""> { + <a href="#dom-tdchangemethod-add" class= +"idlEnumItem">"add", + <a href="#dom-tdchangemethod-remove" class= +"idlEnumItem">"remove", + <a href="#dom-tdchangemethod-change" class= +"idlEnumItem">"change" +}; +The +add +value +denotes +addition +of +a +Property +, +Action +or +event. +The +remove +value +denotes +removal +of +a +Property +, +Action +or +event. +The +change +value +denotes +a +change +applied +on +a +Property +, +Action +or +event. +4.9.3.1.2 +The +TDChangeType +enumeration +<span class="idlEnum" id= +"idl-def-tdchangetype" data-idl="" data-title= +"TDChangeType">enum <a data-lt= +"TDChangeType" href="#dom-tdchangetype" class="internalDFN" +data-link-type="dfn" data-for= +""> { + <a href="#dom-tdchangetype-property" class= +"idlEnumItem">"property", + <a href="#dom-tdchangetype-action" class= +"idlEnumItem">"action", + <a href="#dom-tdchangetype-event" class= +"idlEnumItem">"event" +}; +<span class="idlTypedef" id="idl-def-tdchangedata" data-idl="" +data-title="TDChangeData">typedef <span class= +"idlTypedefType">(<a href="#dom-thingpropertyinit" class= +"internalDFN" data-link-type= +"dfn"> or <a href= +"#dom-thingactioninit" class="internalDFN" data-link-type= +"dfn"> or <a href= +"#dom-thingeventinit" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlTypedefID"><a data-lt="TDChangeData" href="#dom-tdchangedata" +class="internalDFN" data-link-type="dfn" data-for= +""> +TDChangeData +; + +

    +The +property +value +tells + +callback +function +passed +to + +the +operation +was +applied +on +a +Property +definition. +The + + +action + +subscribe() + + +value +tells +the +operation +was +applied + +method +when +invoked + +on +a +action +definition. +The +event +value +tells + +the +operation +was +applied +on +an +event +definition. +4.9.3.1.3 +The +TDChangeData +type +Represents + +returned +observer +will +receive + +the +new +description +of +the +changed +element. +Depending +on +the +change +type, + + +Thing +Description + +each +time + +it +can +be +either +a +ThingPropertyInit +, +ThingActionInit +, +or +ThingEventInit +. + +is +changed. + +

    +
    +
    +

    + +4.10 + +4.9 + + +Examples +

    +

    +Below +a + + + +ConsumedThing + + + +interface +example +is +given. +

    +
    +
    + +Example +5 + +6 + + +: +Consume +a +Thing + +
    +wot.consume(<span class= +"hljs-string">"http://mmyservice.org/mySensor" { + .log(<span class= +"hljs-string">"Thing " + thing.name + <span class= +"hljs-string">" has been consumed."); + .log(<span class= +"hljs-string">"{ " + <span class= +"hljs-built_in">JSON.serialize(thing) + <span class= +"hljs-string">" }"); + thing.addListener(<span class= +"hljs-string">"onchange", <span class= +"hljs-function"><span class= +"hljs-keyword">function(<span class= +"hljs-params">event{ + (event <span class= +"hljs-keyword">instanceof PropertyChangeEvent) { + <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Property " + event.name + <span class= +"hljs-string">" value has changed to " + event.value); + } + }).invokeAction(<span class= +"hljs-string">"startMeasurement", [<span class= +"hljs-string">"Celsius"]); + }, +).catch(<span class= +"hljs-params">error { + .log(<span class= +"hljs-string">"Discovery finished because an error: " + error.message); +}); + +
    try {
+  let td = await wot.fetch("http://mmyservice.org/mySensor");
+  let thing = wot.consume(td);
+  console.log("Thing " + thing.name + " has been consumed.");
+  let subscription = thing.onPropertyChange("temperature")
+    .subscribe(function(value) {
+      console.log("Temperature + " has changed to " + value);
+    });
+  thing.invokeAction("startMeasurement", { units: "Celsius" })
+    .then(() => { console.log("Temperature measurement started."); })
+    .catch(e => {
+       console.log("Error starting measurement.");
+       subscription.unsubscribe();
+     })
+} catch(error) {
+  console.log("Error during fetch or consume: " + error.message);
+};
+
+
    +
    +
    +
    +
    +

    + +5. + +The + + +ExposedThing + + +interface +

    +

    +The + + +ExposedThing + + +interface +is +the +server +API +that +allows +defining +request +handlers, +properties, + +Actions +, +and + +Events + +to +a + +Thing +. +It +also +implements +the + +ConsumedThing + +interface. +An + +ExposedThing + +is +created +by +the + +produce() + +method. + +

    +<span class="idlTypedef" id= +"idl-def-thingdescription" data-idl="" data-title= +"ThingDescription">typedef <a href= +"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-lt="ThingDescription" +href="#dom-thingdescription" class="internalDFN" data-link-type= +"dfn" data-for=""> + +
    +
    +<span class="idlCallback" id="idl-def-requesthandler" data-idl="" +data-title="RequestHandler">callback <span class= +"idlCallbackID"><a data-lt="RequestHandler" href= +"#dom-requesthandler" class="internalDFN" data-link-type="dfn" +data-for=""> = <span class= +"idlCallbackType"><a href= +"https://heycam.github.io/webidl/#idl-any">any<a href="#dom-request" +class="internalDFN" data-link-type= +"dfn"> <span class= +"idlParamName">request + + +Editor's +note +

    +It +is +under +consideration +to +use +a +constructor +for + +ExposedThing + +instead +of +a +factory +method. +

    
+"#dom-exposedthing" class="internalDFN" data-link-type=
+"dfn">ExposedThing implements ConsumedThing;
+
+interface "idlInterfaceID"><a data-lt="ExposedThing" href="#dom-exposedthing"
+class="internalDFN" data-link-type="dfn" data-for=
+""> {
+
+"idlInterfaceID">ExposedThing {
+
+"idlSectionComment">    // define how to expose and run the Thing
+
+data-title="start" data-dfn-for="exposedthing">    Promise<void> start();
+
+data-title="stop" data-dfn-for="exposedthing">    Promise<void> stop();
+
+"idl-def-exposedthing-register-directory" data-idl="" data-title=
+"register" data-dfn-for="exposedthing">    Promise<void> register(optional USVString directory);
+
+"idl-def-exposedthing-unregister-directory" data-idl="" data-title=
+"unregister" data-dfn-for="exposedthing">    Promise<void> unregister(optional USVString directory);
+
+"idl-def-exposedthing-emitevent-eventname-payload" data-idl=""
+data-title="emitEvent" data-dfn-for="exposedthing">    Promise<void> emitEvent(DOMString eventName, any payload);
+
+    // define Thing Description modifiers
+"idl-def-exposedthing-addproperty(property)" data-idl=""
+data-title="addProperty" data-dfn-for=
+"exposedthing">    <a href=
+"#dom-exposedthing" class="internalDFN" data-link-type=
+
+"idl-def-exposedthing-addproperty-property" data-idl="" data-title=
+"addProperty" data-dfn-for="exposedthing">    
+"dfn">ExposedThing  "idlMethName"><a data-lt="addProperty()|addproperty()|addProperty"
+data-lt-nodefault="" href="#dom-exposedthing-addproperty()" class=
+"internalDFN" data-link-type="dfn" data-for=
+"ExposedThing">addProperty(<span class=
+"idlParam"><a href=
+"#dom-thingpropertyinit" class="internalDFN" data-link-type=
+"dfn"> <span class=
+
+"idlMethName">addProperty(ThingProperty 
+"idlParamName">property);
+"idl-def-exposedthing-removeproperty(name)" data-idl="" data-title=
+
+"idl-def-exposedthing-removeproperty-name" data-idl="" data-title=
+
+"removeProperty" data-dfn-for="exposedthing">    ExposedThing  "idlMethName"><a data-lt=
+"removeProperty()|removeproperty()|removeProperty"
+data-lt-nodefault="" href="#dom-exposedthing-removeproperty()"
+class="internalDFN" data-link-type="dfn" data-for=
+"ExposedThing">removeProperty(<span class=
+
+"idlMethName">removeProperty(
+"idlParam">DOMString name);
+<span class="idlMethod" id="idl-def-exposedthing-addaction(action)"
+
+    ExposedThing  "idlMethName"><a data-lt="addAction()|addaction()|addAction"
+data-lt-nodefault="" href="#dom-exposedthing-addaction()" class=
+"internalDFN" data-link-type="dfn" data-for=
+"ExposedThing">addAction(<span class=
+"idlParam"><a href=
+"#dom-thingactioninit" class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">action
+<span class="idlMethod" id=
+"idl-def-exposedthing-removeaction(name)" data-idl="" data-title=
+"removeAction" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href="#dom-exposedthing" class="internalDFN"
+
+"idlMethName">addAction(
+data-link-type=
+"dfn">ThingAction action);
+
+data-idl="" data-title="removeAction" data-dfn-for=
+"exposedthing">    
+"dfn">ExposedThing  "idlMethName"><a data-lt=
+"removeAction()|removeaction()|removeAction" data-lt-nodefault=""
+href="#dom-exposedthing-removeaction()" class="internalDFN"
+data-link-type="dfn" data-for=
+"ExposedThing">removeAction(<span class=
+
+"idlMethName">removeAction(
+"idlParam">DOMString name);
+<span class="idlMethod" id="idl-def-exposedthing-addevent(event)"
+
+    ExposedThing  "idlMethName"><a data-lt="addEvent()|addevent()|addEvent"
+data-lt-nodefault="" href="#dom-exposedthing-addevent()" class=
+"internalDFN" data-link-type="dfn" data-for=
+"ExposedThing">addEvent(<span class=
+"idlParam"><a href="#dom-thingeventinit"
+
+"idlMethName">
+class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">event
+<span class="idlMethod" id="idl-def-exposedthing-removeevent(name)"
+
+"dfn">addEvent(ThingEvent event);
+    ExposedThing  "idlMethName"><a data-lt="removeEvent()|removeevent()|removeEvent"
+data-lt-nodefault="" href="#dom-exposedthing-removeevent()" class=
+"internalDFN" data-link-type="dfn" data-for=
+"ExposedThing">removeEvent(<span class=
+"idlParam"><a href=
+
+"idlMethName">removeEvent(
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name);
+    // define request handlers
+"idl-def-exposedthing-onretrieveproperty(handler)" data-idl=""
+data-title="onRetrieveProperty" data-dfn-for=
+
+"idl-def-exposedthing-setpropertyreadhandler-name-readhandler"
+data-idl="" data-title="setPropertyReadHandler" data-dfn-for=
+
+"exposedthing">    ExposedThing  "idlMethName"><a data-lt=
+"onRetrieveProperty()|onretrieveproperty()|onRetrieveProperty"
+data-lt-nodefault="" href="#dom-exposedthing-onretrieveproperty()"
+class="internalDFN" data-link-type="dfn" data-for=
+"ExposedThing">onRetrieveProperty(<span class=
+"idlParam"><a href="#dom-requesthandler"
+class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">handler
+
+"idlMethName">setPropertyReadHandler(DOMString name,
+                                         
+"idlParam">PropertyReadHandler readHandler);
+
+"idl-def-exposedthing-onupdateproperty(handler)" data-idl=""
+data-title="onUpdateProperty" data-dfn-for=
+
+"idl-def-exposedthing-setpropertywritehandler-name-writehandler"
+data-idl="" data-title="setPropertyWriteHandler" data-dfn-for=
+
+"exposedthing">    ExposedThing  "idlMethName"><a data-lt=
+"onUpdateProperty()|onupdateproperty()|onUpdateProperty"
+data-lt-nodefault="" href="#dom-exposedthing-onupdateproperty()"
+class="internalDFN" data-link-type="dfn" data-for=
+"ExposedThing">onUpdateProperty(<span class=
+"idlParam"><a href="#dom-requesthandler"
+class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">handler
+
+"idlMethName">setPropertyWriteHandler(DOMString name,
+                                          
+"idlParam">PropertyWriteHandler writeHandler);
+
+"idl-def-exposedthing-oninvokeaction(handler)" data-idl=""
+data-title="onInvokeAction" data-dfn-for=
+
+"idl-def-exposedthing-setactionhandler-name-action" data-idl=""
+data-title="setActionHandler" data-dfn-for=
+
+"exposedthing">    ExposedThing  "idlMethName"><a data-lt=
+"onInvokeAction()|oninvokeaction()|onInvokeAction"
+data-lt-nodefault="" href="#dom-exposedthing-oninvokeaction()"
+class="internalDFN" data-link-type="dfn" data-for=
+"ExposedThing">onInvokeAction(<span class=
+"idlParam"><a href="#dom-requesthandler"
+class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">handler
+<span class="idlMethod" id=
+"idl-def-exposedthing-onobserve(handler)" data-idl="" data-title=
+"onObserve" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href="#dom-exposedthing" class="internalDFN"
+data-link-type=
+"dfn">  <span class=
+"idlMethName"><a data-lt="onObserve()|onobserve()|onObserve"
+data-lt-nodefault="" href="#dom-exposedthing-onobserve()" class=
+"internalDFN" data-link-type="dfn" data-for=
+"ExposedThing">onObserve(<span class=
+"idlParam"><a href="#dom-requesthandler"
+class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">handler
+<span class=
+"idlSectionComment">    // define how to expose and run the Thing
+<span class="idlMethod" id=
+"idl-def-exposedthing-register(directory)" data-idl="" data-title=
+"register" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="register()|register()|register"
+data-lt-nodefault="" href="#dom-exposedthing-register()" class=
+"internalDFN" data-link-type="dfn" data-for=
+"ExposedThing">register(<span class=
+"idlParam">optional <a href=
+"https://heycam.github.io/webidl/#idl-USVString">USVString
+<span class="idlMethod" id=
+"idl-def-exposedthing-unregister(directory)" data-idl=""
+data-title="unregister" data-dfn-for=
+"exposedthing">    <a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="unregister()|unregister()|unregister"
+data-lt-nodefault="" href="#dom-exposedthing-unregister()" class=
+"internalDFN" data-link-type="dfn" data-for=
+"ExposedThing">unregister(<span class=
+"idlParam">optional <a href=
+"https://heycam.github.io/webidl/#idl-USVString">USVString
+<span class="idlMethod" id="idl-def-exposedthing-start()" data-idl=
+"" data-title="start" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="start()|start()|start"
+data-lt-nodefault="" href="#dom-exposedthing-start()" class=
+"internalDFN" data-link-type="dfn" data-for=
+"ExposedThing">start
+<span class="idlMethod" id="idl-def-exposedthing-stop()" data-idl=
+"" data-title="stop" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="stop()|stop()|stop"
+data-lt-nodefault="" href="#dom-exposedthing-stop()" class=
+"internalDFN" data-link-type="dfn" data-for=
+"ExposedThing">stop
+<span class="idlMethod" id=
+"idl-def-exposedthing-emitevent(eventname,payload)" data-idl=""
+data-title="emitEvent" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="emitEvent()|emitevent()|emitEvent"
+data-lt-nodefault="" href="#dom-exposedthing-emitevent()" class=
+"internalDFN" data-link-type="dfn" data-for=
+"ExposedThing">emitEvent(<span class=
+
+"idlMethName">setActionHandler(
+"idlParam">"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name, ActionHandler action);
+
+};
+<a href="#dom-exposedthing" class=
+"internalDFN" data-link-type=
+"dfn"> implements <a href=
+"#dom-consumedthing" class="internalDFN" data-link-type=
+"dfn">
+
+data-idl="" data-title="PropertyReadHandler">callback PropertyReadHandler = Promise<any> ();
+
+ConsumedThing
+
+data-idl="" data-title="PropertyWriteHandler">callback PropertyWriteHandler = Promise<void> (any value);
+
+data-title="ActionHandler">callback ActionHandler = 
+Promise
+
+
+;
+
+<
+
+href="https://heycam.github.io/webidl/#idl-any">
+any
+
+>
+
+(
+
+any
+
+parameters
+
+);
+
+
+
    +
    +
    +

    + +5.1 + +The + + +ThingDescription + +start() + + + +type + +method + +

    +

    +WoT +provides +a +unified +representation + +Start +serving +external +requests + +for +data +exchange +between +Thing +s, +standardized +in + +the +Wot +Things +Description +specification. +Note +In +this +version +of +the +API, + + +Thing +Description +s +are +represented +as +opaque +strings, +denoting +a +serialized +form, +for +instance +JSON +or +JSON-LD. +See +Issue +38 +and +Issue +45 + +. +Parsing +and +composing +Thing +Description +s +is +left +for +external +libraries +until +standardized +here. + +

    +
    +
    +

    + +5.2 + +The + + +Request + +stop() + + + +interface + +method + +

    +<span class="idlInterface" id= +"idl-def-request" data-idl="" data-title= +"Request">interface <a data-lt= +"Request" href="#dom-request" class="internalDFN" data-link-type= +"dfn" data-for=""> { +<span class="idlAttribute" id="idl-def-request-type" data-idl="" +data-title="type" data-dfn-for= +"request"> readonly attribute <a href= +"#dom-requesttype" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlAttrName"><a data-lt="type" href="#dom-request-type" class= +"internalDFN" data-link-type="dfn" data-for= +"Request"> +<span class="idlAttribute" id="idl-def-request-from" data-idl="" +data-title="from" data-dfn-for= +"request"> readonly attribute <a href= +"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-lt="from" +href="#dom-request-from" class="internalDFN" data-link-type="dfn" +data-for="Request"> +<span class="idlAttribute" id="idl-def-request-name" data-idl="" +data-title="name" data-dfn-for= +"request"> readonly attribute <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name" +href="#dom-request-name" class="internalDFN" data-link-type="dfn" +data-for="Request"> +<span class="idlAttribute" id="idl-def-request-options" data-idl="" +data-title="options" data-dfn-for= +"request"> readonly attribute <span class= +"idlAttrType">Dictionary <span class= +"idlAttrName"><a data-lt="options" href="#dom-request-options" +class="internalDFN" data-link-type="dfn" data-for= +"Request"> +<span class="idlAttribute" id="idl-def-request-data" data-idl="" +data-title="data" data-dfn-for= +"request"> readonly attribute <a href= +"https://heycam.github.io/webidl/#idl-any">any<a data-lt="data" +href="#dom-request-data" class="internalDFN" data-link-type="dfn" +data-for="Request"> +<span class="idlMethod" id="idl-def-request-respond(response)" +data-idl="" data-title="respond" data-dfn-for= +"request"> <a href= +"https://heycam.github.io/webidl/#idl-promise">Promise<a data-lt="respond()|respond()|respond" +data-lt-nodefault="" href="#dom-request-respond()" class= +"internalDFN" data-link-type="dfn" data-for= +"Request">respond<span class= +"idlParamType"><a href= +"https://heycam.github.io/webidl/#idl-any">any +<span class="idlMethod" id= +"idl-def-request-respondwitherror(error)" data-idl="" data-title= +"respondWithError" data-dfn-for="request"> <span class= +"idlMethType">void<a data-lt= +"respondWithError()|respondwitherror()|respondWithError" +data-lt-nodefault="" href="#dom-request-respondwitherror()" class= +"internalDFN" data-link-type="dfn" data-for= +"Request">respondWithError(<span class= +"idlParam"><a href= +"https://heycam.github.io/webidl/#idl-Error">Error +}; + +

    +Represents +an +incoming +request + +Stop +serving +external +requests +for + +the + +Thing +.

    +5.3 + +The + + +ExposedThing + +register() + + + +method +

    +Generates +the + +Thing +Description + + +is +supposed +to +handle, +for +instance +retrieving +and +updating + +given +the + +properties, +invoking + + +Actions + +and +observing +Events + + +Event + + +(WoT +interactions). +The +type +attribute +represents +the +type +of +the +request +as + +defined +in +RequestType +. +The + +for +this +object. +If +a + + +from + +directory + + +attribute +represents +the +address +of +the +client +device +issuing +the +request. +The +type +of +the +address +(URL, +UUID +or +other) + +argument + +is +defined +by + +given, +make +a +request +to +register + +the + +Thing +Description +. +The +name +attribute +represents +the +name +of +the +Property + + +to +be +retrieved +or +updated, +or +the +name +of +the +invoked +Action +, +or +the +event +name +to +be +observed. +The +options +attribute +represents +the +options +relevant +to +the +request +(e.g. +the +format +or +measurement +units +for + +with + +the +returned +value) +as +key-value +pairs. +The +exact +format +is +specified + +given +WoT +repository + +by +the +Thing +Description +. +The + +invoking +its + + +data + +register + + +attribute +represents +the +value +of +the +Property +, +or +the +input +data +(arguments) +of +an + + +Action +. +It +is +not +used +for +retrieve +requests +and +event +requests, +only +for +Property +update +and +Action +invocation +requests. +5.2.1 +The +RequestType + +

    +
    +
    +

    +enumeration +<span class="idlEnum" id="idl-def-requesttype" +data-idl="" data-title="RequestType">enum <span class= +"idlEnumID"><a data-lt="RequestType" href="#dom-requesttype" class= +"internalDFN" data-link-type="dfn" data-for= +""> { + <a href="#dom-requesttype-property" class= +"idlEnumItem">"property", + <a href="#dom-requesttype-action" class= +"idlEnumItem">"action", + <a href="#dom-requesttype-event" class= +"idlEnumItem">"event", + +}; + + +5.4 + + +The +value +" + + + +property + +unregister() + + + +" +represents +requests +to +retrieve +or +update + +method +

    +If + +a +Property +. +The +value +" + + +action +" +represents +requests +to +invoke +an +Action +. +The +value +" +event +" +represents +requests +to +emit +an +event. +The +value +" +td + +directory + + +" +represents +requests + +argument +is +given, +make +a +request + +to +change + +unregister + +the + +Thing +Description +, +i.e. +to +add, +remove +or +modify +properties, +Actions + + +or +Events +. +Editor's +note +This +functionality +is +here +for + +with + +the +sake +of +completeness +for +future +versions +of + +given +WoT +repository +by +invoking +its + +unregister + +Action +. +Then, +and +in + +the +API. +Currently +there +is + +case + +no +corresponding +functionality +at + +arguments +were +provided +to +this +function, +stop + +the +ConsumedThing + + +Thing + + +level + +and +it +is +not +guaranteed +that +a + +remove +the + +Thing +Description +could +be +remotely +changed +by +scripting. + +. +

    +
    +
    +

    +5.2.2 + + +5.5 + + +The + + +respond() + +emitEvent() + + + +method +

    +

    +Sends +a +positive +response +to + +Emits +an +the +event +initialized +with +the +event +name +specified +by + +the + +Request + +eventName + + +based +on +the +Protocol +Bindings + +argument + +and +includes +the + +data +specified +by +the +data + + +payload + +argument. +

    +
    +
    +

    +5.2.3 + + +5.6 + + +The + + +respondWithError() + +DataSchema + + + +method +Sends +a +negative +response +to +the + +type +

    
+"idl-def-dataschema" data-idl="" data-title=
+"DataSchema">typedef USVString 
+
+
+Request
+
+DataSchema
+
+
+
+based
+on
+the
+Protocol
+Bindings
+and
+includes
+the
+error
+specified
+by
+the
+error
+argument.
+
+5.3
+
+
+;
+

    +The + + +RequestHandler + +DataSchema + + +callback +Callback +function +for +handling +interaction +requests. +Receives +an +argument +request +of + + +type +represents +a +data +type + +specified + +in +the + +Thing +Description + +in +a +serialized +form. +

    + +Editor's +note +

    + +Request + +DataSchema + + + +and +should +return +an +object +or +value +that + +is +used +by +Protocol +Bindings +to +reply +to +the +request. +The +returned + +under +development, +currently +it +can +denote +any + +type +is +defined + +supported + +by +the + +Thing +Description + +and +the + +WoT +Runtime + +. +

    +
    +
    +
    +

    +5.4 + + +5.7 + + +The + + +addProperty() + + +method +

    +

    +Adds +a + +Property + +defined +by +the +argument +and +updates +the + +Thing +Description +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. + +

    +
    +

    + +5.4.1 + +5.7.1 + + +The + + +ThingPropertyInit + +ThingProperty + + + +dictionary +

    +
    +
    "idl-def-thingpropertyinit" data-idl="" data-title=
+"ThingPropertyInit">dictionary <span class=
+"idlDictionaryID"><a data-lt="ThingPropertyInit" href=
+"#dom-thingpropertyinit" class="internalDFN" data-link-type="dfn"
+data-for=""> {
+<span class="idlMember" id="idl-def-thingpropertyinit-name"
+data-idl="" data-title="name" data-dfn-for=
+"thingpropertyinit">    <a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name"
+href="#dom-thingpropertyinit-name" class="internalDFN"
+data-link-type="dfn" data-for=
+"ThingPropertyInit">
+<span class="idlMember" id="idl-def-thingpropertyinit-configurable"
+data-idl="" data-title="configurable" data-dfn-for=
+"thingpropertyinit">    <a href=
+"https://heycam.github.io/webidl/#idl-boolean">boolean<a data-lt="configurable"
+href="#dom-thingpropertyinit-configurable" class="internalDFN"
+data-link-type="dfn" data-for=
+"ThingPropertyInit">
+<span class="idlMember" id="idl-def-thingpropertyinit-enumerable"
+data-idl="" data-title="enumerable" data-dfn-for=
+"thingpropertyinit">    <a href=
+"https://heycam.github.io/webidl/#idl-boolean">boolean<a data-lt="enumerable"
+href="#dom-thingpropertyinit-enumerable" class="internalDFN"
+data-link-type="dfn" data-for=
+"ThingPropertyInit">
+<span class="idlMember" id="idl-def-thingpropertyinit-writable"
+
+"idl-def-thingproperty" data-idl="" data-title=
+"ThingProperty">dictionary ThingProperty : SemanticAnnotations {
+
+data-title="name" data-dfn-for=
+"thingproperty">    required DOMString  name;
+
+"" data-title="schema" data-dfn-for=
+"thingproperty">    required DataSchema schema;
+
+"" data-title="value" data-dfn-for=
+"thingproperty">             any        value;
+"thingpropertyinit">    <a href=
+"https://heycam.github.io/webidl/#idl-boolean">boolean<a data-lt="writable"
+href="#dom-thingpropertyinit-writable" class="internalDFN"
+data-link-type="dfn" data-for=
+"ThingPropertyInit"> = <span class=
+"idlMemberValue">true
+<span class="idlMember" id=
+"idl-def-thingpropertyinit-semantictypes" data-idl="" data-title=
+"semanticTypes" data-dfn-for="thingpropertyinit">    <span class=
+"idlMemberType"><a href=
+"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-semantictype"
+class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlMemberName"><a data-lt="semanticTypes" href=
+"#dom-thingpropertyinit-semantictypes" class="internalDFN"
+data-link-type="dfn" data-for=
+"ThingPropertyInit">
+<span class="idlMember" id="idl-def-thingpropertyinit-description"
+data-idl="" data-title="description" data-dfn-for=
+"thingpropertyinit">    <a href=
+"#dom-thingdescription" class="internalDFN" data-link-type=
+"dfn">       <span class=
+"idlMemberName"><a data-lt="description" href=
+"#dom-thingpropertyinit-description" class="internalDFN"
+data-link-type="dfn" data-for=
+"ThingPropertyInit">
+<span class="idlMember" id="idl-def-thingpropertyinit-value"
+data-idl="" data-title="value" data-dfn-for=
+"thingpropertyinit">    <a href=
+"https://heycam.github.io/webidl/#idl-any">any<a data-lt="value"
+href="#dom-thingpropertyinit-value" class="internalDFN"
+data-link-type="dfn" data-for=
+"ThingPropertyInit">
+
+"thingproperty">             boolean    writable = false;
+
+data-idl="" data-title="observable" data-dfn-for=
+"thingproperty">             boolean    observable = false;
+
+};
+
+
    +
    +

    +Represents +the + +Thing + + +Property + +description. +

    +
      +
    • +The + + +name + + +attribute +represents +the +name +of +the + +Property +. +
      • +
    • +The + + +value + +schema + + + +attribute +represents +the +value +of + +data +type +for + +the + +Property + +described +by + +DataSchema + +. +
      • +
    • +The + + +configurable + +value + + + +attribute +defines +whether +the +Property +can +be +deleted +from + +represents + +the +object +and +whether +its +properties +can +be +changed. +The +default + +value +is +false +. + +of +the + +Property +. +
      • +
    • +The + + +enumerable + +writable + + + +attribute +defines +whether +the + +Property + +can +be +listed +and +iterated. + +updated. + +The +default +value +is + +true + +false + +. +
      • +
    • +The + + +writable + +observable + + + +attribute +defines +whether +the + +Property + +changes + +can +be +updated. + +observed +by +an +external +client. + +The +default +value +is + +true + +false + +. +
      • +The +semanticTypes +attribute +represents +a +list +of +semantic +type +annotations +(e.g. +labels, +classifications +etc) +relevant +to +the +Property +, +represented +as +SemanticType +dictionaries. +The +description +attribute +represents +the +Property +description +to +be +added +to +the +Thing +Description +. + +
    +
    +5.4.2 +The +SemanticType +dictionary +<span class="idlDictionary" id= +"idl-def-semantictype" data-idl="" data-title= +"SemanticType">dictionary <a data-lt= +"SemanticType" href="#dom-semantictype" class="internalDFN" +data-link-type="dfn" data-for= +""> { +<span class="idlMember" id="idl-def-semantictype-name" data-idl="" +data-title="name" data-dfn-for="semantictype"> <span class= +"idlMemberType"><a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name" +href="#dom-semantictype-name" class="internalDFN" data-link-type= +"dfn" data-for="SemanticType"> +<span class="idlMember" id="idl-def-semantictype-context" data-idl= +"" data-title="context" data-dfn-for= +"semantictype"> <a href= +"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-lt="context" +href="#dom-semantictype-context" class="internalDFN" +data-link-type="dfn" data-for= +"SemanticType"> +}; +Represents +a +semantic +type +annotation, +containing +a +name +and +a +context. +The +name +attribute +represents +the +name +of +the +semantic +type +in +the +given +context. +The +context +attribute +represents +an +URL +link +to +the +context +of +the +semantic +classification. +Editor's +note +Semantic +type +examples +to +be +added. + +
    +
    +

    + +5.5 + +5.8 + + +The + + +removeProperty() + + +method +

    +

    +Removes +the + +Property + +specified +by +the + +name + +argument, + +argument +and + +updates +the + +Thing +Description +and +returns + +. +Throws +on +error. +Returns +a +reference +to + +the +object. + +same +object +for +supporting +chaining. + +

    +
    +
    +

    + +5.6 + +5.9 + + +The + + +addAction() + + +method +

    +

    +Adds +an + +Action + +to +the + +Thing + +object +as +defined +by +the + +action + +argument +of +type + + +ThingActionInit + +ThingAction + + + +and +updates +the + +Thing +Description +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. + +

    +
    +

    + +5.6.1 + +5.9.1 + + +The + + +ThingActionInit + +ThingAction + + + +dictionary +

    +
    +
    "idl-def-thingactioninit" data-idl="" data-title=
+"ThingActionInit">dictionary <span class=
+"idlDictionaryID"><a data-lt="ThingActionInit" href=
+"#dom-thingactioninit" class="internalDFN" data-link-type="dfn"
+data-for=""> {
+<span class="idlMember" id="idl-def-thingactioninit-name" data-idl=
+"" data-title="name" data-dfn-for=
+"thingactioninit">    <a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name"
+href="#dom-thingactioninit-name" class="internalDFN"
+data-link-type="dfn" data-for=
+"ThingActionInit">
+<span class="idlMember" id=
+"idl-def-thingactioninit-inputdatadescription" data-idl=""
+data-title="inputDataDescription" data-dfn-for=
+"thingactioninit">    <a href=
+"#dom-thingdescription" class="internalDFN" data-link-type=
+"dfn">       <span class=
+"idlMemberName"><a data-lt="inputDataDescription" href=
+"#dom-thingactioninit-inputdatadescription" class="internalDFN"
+data-link-type="dfn" data-for=
+"ThingActionInit">
+<span class="idlMember" id=
+"idl-def-thingactioninit-outputdatadescription" data-idl=""
+data-title="outputDataDescription" data-dfn-for=
+"thingactioninit">    <a href=
+"#dom-thingdescription" class="internalDFN" data-link-type=
+"dfn">       <span class=
+"idlMemberName"><a data-lt="outputDataDescription" href=
+"#dom-thingactioninit-outputdatadescription" class="internalDFN"
+data-link-type="dfn" data-for=
+"ThingActionInit">
+<span class="idlMember" id="idl-def-thingactioninit-semantictypes"
+data-idl="" data-title="semanticTypes" data-dfn-for=
+"thingactioninit">    <a href=
+"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-semantictype"
+
+"idl-def-thingaction" data-idl="" data-title=
+"ThingAction">dictionary ThingAction : SemanticAnnotations {
+
+data-title="name" data-dfn-for=
+"thingaction">    required DOMString  
+class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlMemberName"><a data-lt="semanticTypes" href=
+"#dom-thingactioninit-semantictypes" class="internalDFN"
+data-link-type="dfn" data-for=
+"ThingActionInit">
+<span class="idlMember" id="idl-def-thingactioninit-action"
+data-idl="" data-title="action" data-dfn-for=
+"thingactioninit">    <span class=
+"idlMemberType">Function               <span class=
+"idlMemberName"><a data-lt="action" href=
+"#dom-thingactioninit-action" class="internalDFN" data-link-type=
+"dfn" data-for=
+"ThingActionInit">
+
+"dfn">name;
+
+data-idl="" data-title="inputSchema" data-dfn-for=
+"thingaction">             DataSchema inputSchema;
+
+data-idl="" data-title="outputSchema" data-dfn-for=
+"thingaction">             DataSchema outputSchema;
+
+};
+
+
    +
    +

    +The + + +ThingActionInit + +ThingAction + + + +dictionary +describes +the +arguments +and +the +return +value. +

    +
      +
    • +The + + +name + + +attribute +provides +the + +Action + +name. +
      • +
    • +The +action +attribute +provides +a +function +that +defines +the +Action +. +The + + + +inputDataDescription + +inputSchema + + + +attribute +provides +the +description +of +the +input +arguments +(argument +list +is +represented +by +an +object). +If +missing, +it +means +the +action +does +not +accept + +arguments. +
      • +
    • +The + + +outputDataDescription + +outputSchema + + + +attribute +provides +the +description +of +the +returned +data. +The +semanticTypes +attribute +provides +a +list +of +semantic +type +annotations +(e.g. +labels, +classifications +etc) +relevant +to + +If +missing, +it +means + +the +Action +, +represented +as +SemanticType +dictionaries. + +action +does +not +return +data. + +
      • +
    +
    +
    +
    +

    + +5.7 + +5.10 + + +The + + +removeAction() + + +method +

    +

    +Removes +the + +Action + +specified +by +the + +name + +argument, + +argument +and + +updates +the + +Thing +Description +and +returns + +. +Throws +on +error. +Returns +a +reference +to + +the +object. + +same +object +for +supporting +chaining. + +

    +
    +
    +

    + +5.8 + +5.11 + + +The + + +addEvent() + + +method +

    +

    +Adds +an +event +to +the + +Thing + +object +as +defined +by +the + +event + +argument +of +type + + +ThingEventInit + +ThingEvent + + + +and +updates +the + +Thing +Description +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. + +

    +
    +

    + +5.8.1 + +5.11.1 + + +The + + +ThingEventInit + +ThingEvent + + + +dictionary +

    +
    +
    "idl-def-thingeventinit" data-idl="" data-title=
+"ThingEventInit">dictionary <span class=
+"idlDictionaryID"><a data-lt="ThingEventInit" href=
+"#dom-thingeventinit" class="internalDFN" data-link-type="dfn"
+data-for=""> {
+<span class="idlMember" id="idl-def-thingeventinit-name" data-idl=
+"" data-title="name" data-dfn-for="thingeventinit">    <span class=
+"idlMemberType"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-lt="name"
+href="#dom-thingeventinit-name" class="internalDFN" data-link-type=
+"dfn" data-for=
+"ThingEventInit">
+<span class="idlMember" id="idl-def-thingeventinit-semantictypes"
+data-idl="" data-title="semanticTypes" data-dfn-for=
+"thingeventinit">    <a href=
+"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-semantictype"
+
+"idl-def-thingevent" data-idl="" data-title=
+"ThingEvent">dictionary ThingEvent : SemanticAnnotations {
+
+data-title="name" data-dfn-for=
+"thingevent">    required DOMString  
+class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlMemberName"><a data-lt="semanticTypes" href=
+"#dom-thingeventinit-semantictypes" class="internalDFN"
+data-link-type="dfn" data-for=
+"ThingEventInit">
+<span class="idlMember" id="idl-def-thingeventinit-datadescription"
+data-idl="" data-title="dataDescription" data-dfn-for=
+"thingeventinit">    <a href=
+"#dom-thingdescription" class="internalDFN" data-link-type=
+"dfn">       <span class=
+"idlMemberName"><a data-lt="dataDescription" href=
+"#dom-thingeventinit-datadescription" class="internalDFN"
+data-link-type="dfn" data-for=
+"ThingEventInit">
+
+"dfn">name;
+
+data-title="schema" data-dfn-for=
+"thingevent">             DataSchema schema;
+
+};
+
+
    +
    +
      +
    • +The + + +name + + +attribute +represents +the +event +name. +
      • +
    • +The +semanticTypes +attribute +represent +a +list +of +semantic +type +annotations +attached +to +the +event. +The + + + +dataDescription + +schema + + + +attribute +represents +the +description + +type + +of +the +data +that +is +attached +to +the +event. +If +missing, +it +means +the +event +does +not +carry +data. + +
      • +
    +
    +
    +
    +

    + +5.9 + +5.12 + + +The + + +removeEvent() + + +method +

    +

    +Removes +the +event +specified +by +the + +name + +argument, + +argument +and + +updates +the + +Thing +Description +and +returns + +. +Returns +a +reference +to + +the +object. + +same +object +for +supporting +chaining. + +

    +
    +
    +

    + +5.10 + +5.13 + + +The + + +onRetrieveProperty() + +PropertyReadHandler + + + +method + +callback + +

    +

    +Registers +the +handler + +A + +function +for + +that +returns +a +Promise +and +resolves +it +with +the +value +of +the + +Property + +retrieve +requests +received +for + +matching + +the +Thing +, +as +defined +by + + +name + +argument +to + +the + +handler + +setPropertyReadHandler + + +function, +or +rejects +with +an +error +if +the + +property +of +type + +is +not +found +or +the +value +cannot +be +retrieved. +

    + +5.14 + +The + + +RequestHandler + +PropertyWriteHandler + + + +callback +

    +A +function +called +with + +value + + +. +The +handler +will +receive +an + +as + +argument +request + +that +returns +a +Promise +which +is +resolved +when +the +value + +of +type + +the + +Property + +matching +the + + +name + +argument +to +the + + +Request + +setPropertyReadHandler + + +function +is +updated +with + +value +, +or +rejects +with +an +error +if +the +property +is +not +found +or +the +value +cannot +be +updated. +

    + +Editor's +note + +where +at +least +request.name + +
    +

    +Note +that +this +function + +is +defined +and +represents + +invoked +by +implementations +before + +the +name + +property +is +updated, +so +the +code +in +this +callback +function +can +invoke +the + +readProperty() + +method +to +find +out +the +old +value + +of +the +Property + +property, +if +needed. +Therefore +the +old +value +is +not +provided + +to +be +retrieved. + +this +method. + +

    +
    +
    +
    +

    + +5.11 + +5.15 + + +The + + +onUpdateProperty() + +ActionHandler + + + +method + +callback + +

    +

    +Defines +the +handler + +A + +function +for +Property + +called +with +a + +parameters + +dictionary +argument +assembled +by +the + +WoT +runtime + + +update +requests +received +for + +based +on + +the + +Thing +, +as +defined +by + +Description + +and + +the +external +client +request. +It +returns +a +Promise +that +rejects +with +an +error +or +resolves +if +the +action +is +successful +or +ongoing +(may +also +resolve +with +a +control +object +such +as +an + + +handler + +Observable + + +property +of +type + + +for +actions +that +need +progress +notifications +or +that +can +be +canceled). +

    +5.16 + +The + + +RequestHandler + +setPropertyReadHandler() + + + +method +

    +Takes + +name + + +. +The +handler +will +receive +an + +as +string +argument +and + +readHandler + +as + +argument +request + +of +type + + +Request + +PropertyReadHandler + + +where +request.name +defines + +. +Sets + +the +name +of + +handler +function +for +reading + +the +specified + +Property + +matched +by + +name +. +Throws +on +error. +Returns +a +reference + +to +be +retrieved + +the +same +object +for +supporting +chaining. +

    +The + +readHandler + +callback +function +will +implement +reading +a + +Property + +and +request.data +defines + + +SHOULD + +be +called +by +implementations +when +a +request +for +reading +a + +Property + +is +received +from + +the +new +value +of + +underlying +platform. +

    +There + +SHOULD + +be +at +most +one +handler +for +any +given + +Property + +and +newly +added +handlers +replace + +the +old +handlers. +If +no +handler +is +initialized +for +any +given + +Property +. + +, +implementations + +SHOULD + +implement +a +default +property +read +handler. + +

    +
    +
    +

    + +5.12 + +5.17 + + +The + + +onInvokeAction() + +setPropertyWriteHandler() + + + +method +

    +

    +Defines +the +handler +function +for +Action +invocation +requests +received +for +the +Thing +, +as +defined +by +the + +Takes + + +handler + +name + + +property +of +type + +as +string +argument +and + + +RequestHandler + +writeHandler + + +. +The +handler +will +receive +an + +as + +argument +request + +of +type + + +Request + +PropertyWriteHandler + + +where +request.name +defines + +. +Sets + +the +name +of + +handler +function +for +writing + +the +Action + +specified + +Property + + +matched +by + +name +. +Throws +on +error. +Returns +a +reference + +to +be +invoked +and +request.data +defines + +the +input +arguments + +same +object + +for +the +Action + +supporting +chaining. +

    +There + +SHOULD + +be +at +most +one +write +handler +for +any +given + +Property + + +as +defined +by + +and +newly +added +handlers +replace + +the +Thing +Description +. + +old +handlers. +If +no +write +handler +is +initialized +for +any +given + +Property +, +implementations + +SHOULD + +implement +default +property +update +and +notifying +observers +on +change. + +

    +
    +
    +

    + +5.13 + +5.18 + + +The + + +onObserve() + +setActionHandler() + + + +method +

    +

    +Defines +the +handler +function +for +observe +requests +received +for +the +Thing +, + +Takes + +name + +as +defined +by +the + +string +argument +and + + +handler + +action + + +property + +as +argument + +of +type + + +RequestHandler + +ActionHandler + + +. +The + +. +Sets +the + +handler +function +for +the +specified + +Action + +matched +by + +name +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +

    +If +provided, +this +callback +function + +will +receive + +implement +invoking + +an +argument + + +Action + +and + +SHOULD + +be +called +by +implementations +when +a + +request +of +type + +for +invoking +a + +Action + +is +received +from +the +underlying +platform. +The +callback +will +receive +a + + +parameters + +dictionary +argument. +

    +There + +SHOULD + +be +exactly +one +handler +for +any +given + +Action +. +If +no +handler +is +initialized +for +any +given + +Action +, +implementations + +SHOULD + +return +error +if +the +action +is +invoked +by +any +client. +

    + +5.19 + +Examples +

    +Below +some + + +Request + +ExposedThing + + + + +where + +interface +examples +are +given. + +

    +
    +
    +request.name +defines +the +name +of +the +Property +or +Action +or +event + + +Example +7 +: +Create +a +new +blank +exposed +Thing +
    try {  
+"hljs-keyword">var thing = WoT.produce({ name: "tempSensor" });
+  // manually add Interactions
+  thing.addProperty({
+    name: 
+"hljs-string">"temperature",
+    value: 
+"hljs-number">0.0,
+    schema: 
+"hljs-string">'{ "type": "number" }'
+    
+"hljs-comment">// use default values for the rest
+  }).addProperty({
+    name: 
+"hljs-string">"max",
+    value: 
+"hljs-number">0.0,
+    schema: 
+"hljs-string">'{ "type": "number" }'
+    
+"hljs-comment">// use default values for the rest
+  }).addAction({
+    name: 
+"hljs-string">"reset",
+    // no input, no output
+  }).addEvent({
+    name: 
+"hljs-string">"onchange",
+    schema: 
+"hljs-string">'{ "type": "number" }'
+  });
+  // add server functionality
+  thing.setActionHandler("reset", () => {
+    console.log(
+"hljs-string">"Resetting maximum");
+    thing.writeProperty("max", 0.0);
+  });
+  thing.start().then(() => {
+      thing.register();
+  });
+  // define Thing business logic
+  setInterval( async () => {
+    let mock = 
+"hljs-built_in">Math.random()*100;
+    thing.writeProperty("temperature", mock);
+    let old = 
+"hljs-keyword">await thing.readProperty("max");
+    if (old < mock) {
+      thing.writeProperty("max", mock);
+      thing.emitEvent("onchange");
+    }
+  }, 1000);
+} catch (err) {
+   console.log(
+"hljs-string">"Error creating ExposedThing: " + err);
+}
+
    +Example +8 +: +Create +a +new +exposed +Thing +from +a +Thing +Description +
    
+"hljs-keyword">let thingDescription = '{ "@context": [ "https://w3c.github.io/wot/w3c-wot-td-context.jsonld", "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ], "@type": [ "Thing", "Sensor" ], "name": "mySensor", "geo:location": "testspace", "interaction": [ { "@type": [ "Property", "Temperature" ], "name": "prop1", "schema": { "type": "number" }, "saref:TemperatureUnit": "degree_Celsius" } ] }';
+try {  
+"hljs-comment">// note that produce() fails if thingDescription contains error
+  
+"hljs-keyword">let thing = WoT.produce(thingDescription);
+  
+"hljs-comment">// Interactions were added from TD
+  
+"hljs-comment">// WoT adds generic handler for reading any property
+  
+"hljs-comment">// define a specific handler for one property
+  let name = 
+"hljs-string">"examplePropertyName";
+  thing.setPropertyReadHandler(name, () => {
+    console.log(
+"hljs-string">"Handling read request for " + name);
+    return 
+"hljs-keyword">new Promise((resolve, reject) => {
+        
+"hljs-keyword">let examplePropertyValue = 5;
+        resolve(examplePropertyValue);
+      },
+      e => {
+        console.log(
+"hljs-string">"Error");
+      });
+  });
+  thing.start();
+} catch(err) {
+   console.log(
+"hljs-string">"Error creating ExposedThing: " + err);
+}
+
    +Example +9 +: +Create +a +new +exposed +Thing +from +a +TD +URI +
    
+"hljs-comment">// fetch an external TD, e.g., to set up a proxy for that Thing
+WoT.fetch("http://myservice.org/mySensor/description").then(td => {
+  
+"hljs-comment">// WoT.produce() ignores instance-specific metadata (security, form)
+  let thing = WoT.produce(td);  
+"hljs-comment">// Interactions were added from TD
+  // add server functionality  // ...
+});
+

    +6. + +Experimental +extensions + +to +be +observed. + +the + +ConsumedThing + +interface +

    +request.options.observeType + + +This +section + +is +of +type + +non-normative. +

    +The + + +RequestType + +ThingDescription + + + +and +defines +whether +a +Property +change +or + +related +functionality, +such +as +enumerating + +Properties +, +Action + +invocation +or +event +emitting +is +observed, +or +the +changes +to +the +Thing +Description + +s, + +Event + + +are +observed. +request.options.subscribe +is +true +if +subscription +is +turned +or +kept +being +turned +on, + +s + +and +it + +links +(introspection) + +is +false +when +subscription + +an +API +extension +that + +is +turned +off. + +out +of +scope +for +this +specification. +However, +the +draft +interfaces +are +defined +here +for +informative +purposes. +

    
+"idl-def-consumedthing-partial-1" data-idl="" data-title=
+"ConsumedThing">partial interface ConsumedThing {
+
+data-idl="" data-title="getProperties" data-dfn-for=
+"consumedthing">    sequence<ThingProperty> getProperties();
+
+data-idl="" data-title="getActions" data-dfn-for=
+"consumedthing">    sequence<ThingAction>   getActions();
+
+data-idl="" data-title="getEvents" data-dfn-for=
+"consumedthing">    sequence<ThingEvent>    getEvents();
+
+data-idl="" data-title="getLinks" data-dfn-for=
+"consumedthing">    sequence<TDLink>        getLinks();
+};
+

    + +5.14 + +6.1 + + +The + + +register() + +getProperties() + + + +method +

    +

    +Generates +the +Thing +Description +given + +Returns + +the +properties, +Actions +and +Event + +list +of + +Properties + + +defined +for +this +object. +If +a +directory +argument +is +given, +make +a +request +to +register + +in + +the + +Thing +Description + +with + +of + +the +given +WoT +repository +by +invoking +its + + +Thing + +in +the +form +of +a +list +of + + +register + +ThingProperty + + +Action +. + + +objects. + +

    +
    +
    +

    +5.15 + + +6.2 + + +The + + +unregister() + +getActions() + + + +method +

    +

    +If +a +directory +argument +is +given, +make +a +request +to +unregister +the +Thing +Description +with + +Returns + +the +given +WoT +repository +by +invoking +its +unregister + +list +of + +Action +. +Then, +and + + +s +defined + +in +the +case +no +arguments +were +provided +to +this +function, +stop +the + + +Thing +Description + + +and +remove + +of + +the + +Thing +Description +. + + +in +the +form +of +a +list +of + +ThingAction + +objects. + +

    +
    +
    +

    + +5.16 + +6.3 + + +The + + +start() + +getEvents() + + + +method +

    +

    +Start +serving +external +requests +for + +Returns + +the +list +of + +Event + +s +defined +in +the + +Thing +. + +Description + +of +the + +Thing + +in +the +form +of +a +list +of + +ThingEvent + +objects. + +

    +
    + +
    +
    +

    + +5.20 + +7. + + +Examples + +Observables +

    +

    +Below +some + + +This +section +is +non-normative. + +ExposedThing + +

    +

    + +Observables + +are + +proposed + + +interface +examples + +to +be +included +in +ECMAScript +and + +are +given. + +used +for +handling +pushed +data +associated +with +various +possible +sources, +for +instance +events, +timers, +streams, +etc. +A +minimal +required +implementation +is +described +here. + +

    +
    +
    + +Example +6 + +Editor's +note + + +: +Create +a +new +blank +exposed +Thing + +
    +

    +This +section +is +informal +and +contains +rather +laconic +information +for +implementations +on +what +to +support +for +interoperability. +

    
+"idl-def-observable" data-idl="" data-title=
+"Observable">interface Observable {
+
+"idl-def-observable-subscribe-next-error-complete" data-idl=""
+data-title="subscribe" data-dfn-for="observable">    Subscription subscribe((Observer or OnNext) next,
+                           
+"idlParam">optional OnError error,
+                           
+"idlParam">optional OnComplete complete);
+};
+
+data-title="Subscription">interface Subscription {
+
+data-idl="" data-title="unsubscribe" data-dfn-for=
+"subscription">    void unsubscribe();
+
+data-idl="" data-title="closed" data-dfn-for=
+"subscription">    readonly attribute boolean closed;
+};
+
+data-title="Observer">interface Observer {
+
+"" data-title="next" data-dfn-for="observer">    void next(any value);
+
+"" data-title="error" data-dfn-for="observer">    void error(Error error);
+
+data-title="complete" data-dfn-for="observer">    void complete();
+};
+
+data-title="OnNext">callback OnNext = void (any value);
+
+data-title="OnError">callback OnError = void (Error error);
+
+data-title="OnComplete">callback OnComplete = 
+void
+
+();
+
+
+<pre class="highlight hljs javascript" aria-busy="false" aria-live=
+"polite">WoT.createExposedThing(thingDescription)
+  .then(<span class=
+"hljs-keyword">function(<span class=
+"hljs-params">thing{
+    <span class=
+"hljs-comment">// manually add properties, actions, and events
+    thing.addProperty({
+      : <span class=
+"hljs-string">"temperature",
+      : <span class=
+"hljs-string">"0",
+      : <span class=
+"hljs-literal">false
+      <span class=
+"hljs-comment">// use default values for the rest
+    }).addEvent({
+      : <span class=
+"hljs-string">"onchange",
+      : {
+        : <span class=
+"hljs-string">"float32"
+      }
+    }).addAction({
+      : <span class=
+"hljs-string">"reset",
+      : <span class=
+"hljs-function"><span class=
+"hljs-params">() { <span class=
+"hljs-keyword">this.temperature = <span class=
+"hljs-number">0; }
+    })
+    
+    .onRetrieveProperty( <span class=
+"hljs-params">request {
+      .log(<span class=
+"hljs-string">"Handling read request");
+       <span class=
+"hljs-keyword">this.temperature;
+    }).onObserve( <span class=
+"hljs-params">request {
+      .log(<span class=
+"hljs-string">"Handling observe request");
+      <span class=
+"hljs-comment">// add listener identified by request.from
+    }).onInvokeAction( <span class=
+"hljs-params">request {
+      .log(<span class=
+"hljs-string">"Handling action request");
+    }).start();
+});
+
+
    +
    +
    +

    +Example +7 + + +7.1 + + +The + +: +Create +a +new +exposed +Thing +from +a +TD +URI + + +Observer + +let thingDescription = '{ + "name": "mySensor", + "url": "http://myservice.org/mySensor/description" +}'; +WoT.createExposedThing(thingDescription) + .then(function(thing) { + // properties, actions and events are added based on the TD + console.log("created " + thing.name }); + // now add the requests handlers + thing.onRetrieveProperty(function(request) { + console.log("Sending property '" + request.property + "' to " + request.from); + }).onUpdateProperty(function(request) { + console.log("Updating property '" + request.property + "' by " + request.from); + }).onObserve(function(request) { + console.log("Adding listener " + request.from); + console.log("Observing " + request.type + " " + request.name + + (request.subscribe? " recursively" : "")); + }).start().then(function() { + console.log("Thing started serving requests"); + }); +}) + + +interface +

    +The + + +Observer + +Example +8 + + +interface +defines +the +callbacks +needed +to +handle +an + +Observable +:

    • +The + +next() + +function, +as +well +as +the + +OnNext + +callback +takes +the +next +sample +for +the +data +in +the + +value + +argument. +
    • +The + +error() + +function, +as +well +as +the + +OnError + +callback +takes +an +error +in +the + +value + +argument. +It +is +called +when +an +error +occured +in +producing +the +data +the +client +should +know +about. +
    • +The + +complete() + +function, +as +well +as +the + +OnComplete + +callback +is +called +when +the +data +source +has +finished +sending +values. +

    +7.2 + + +The + +: +Create + + +Subscription + +interface +

    +Contains +the + +closed + +property +of +type + +boolean + +that +tells +if +the +subscription +is +closed +or +active. +

    +Also, +contains +the + +unsubscribe + +() +method +that +cancels +the +subscription, +i.e. +makes + +a +new +exposed +Thing + +request +to +the +underlying +platform +to +stop +receiving +data + +from +a +Thing +Description + +the +source, +and +sets +the + +closed + +property +to + +false +.

    +7.3 + + +The + +let thingDescription = '{ + "name": "mySensor", + "description": { + "@context": [ + "http://w3c.github.io/wot/w3c-wot-td-context.jsonld", + "http://w3c.github.io/wot/w3c-wot-common-context.jsonld", + ], + "@type": [ "Thing" ], + "interaction": [ + // ... + ] + // ... + }' +}; +WoT.createExposedThing(thingDescription) + .then(function(thing) { + // properties, actions and events are added based on the TD + // ... +}); + + +Observable + + +interface +

    +The + +Observable + +interface +enabled +subscribing +to +pushed +data +notifications +by +the + +subscribe + +() +method: +

    • +If +the + +subscribe() + +method +is +called +with +an + +Observer + +object, +initialize +the +data, +error +and +completion +handling +callbacks +from +that +object, +or +throw +on +error. +
    • +Otherwise, +if +the + +subscribe() + +method +is +called +with +a +function, +initialize +the +data +handler +callback +with +that +function. +If +the +next +argument +is +provided +and +is +a +function, +initialize +the +error +handling +callback +with +that +function, +or +throw +on +error. +If +the +third +argument +is +provided +and +is +a +function, +initialize +the +completion +handler +with +that +function, +or +throw +on +error. +
    • +After +callback +initializations, +the +implementation +should +request +the +underlying +platform +to +provide +data, +error +and +completion +notifications +for +the +supported +data +source. +
    +
    +
    +
    +

    + +6. + +8. + + +Security +and +Privacy +

    +
    +
    + +Editor's +note + +
    +

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

    +
    +
    +
    +

    + +7. + +9. + + +Terminology +and +conventions +

    +

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

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

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

    +

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

    +

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

    +

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

    +

    +The +term + + +secure +context + + +is +defined +in +[ + + +WEBAPPSEC + + +]. +

    +

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

    +

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

    +

    +The +term +event +and +the +Event +object +are +defined +in +DOM +and +Node.js +. +Note +This +specification +uses +the +convention +that +an +event +listener +will +receive +an +Event +object. +This +should +work +both +in +a +browser +environment +and +in +a +Node.js +like +environment. +Observable +s +are +proposed +to +be +included +in +ECMAScript. +The + +algorithms + + +utf-8 +encode + +, +and + + +utf-8 +decode + + +are +defined +in +[ + + +ENCODING + + +]. +

    +

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

    +

    +The +terms + +hyperlink +reference + +and + +relation +type + +are +defined +in +[ + +HTML5 + +] +and + +RFC8288 +.

    +
    +
    +

    + +8. + +10. + + +Conformance +

    +

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

    +

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

    +

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

    +

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

    +

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

    +

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

    +

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

    +

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

    +
    +
    +

    + +A. + +Changes +

    +

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

    +
      +
    • +Synchronized +the +Scripting +API +with +the + +Thing +Description +specification +. +Defined + +ThingDescription +, +ThingTemplate +, +SemanticAnnotations +, +SemanticType +, +SemanticMetadata +, +input +and +output +data +descriptions, +etc. +
    • +Separated + +consume() + +to + +fetch() + +and + +consume() +.
    • +Changed + +expose() + +to +accept +a + +Thing +Template +.
    • +Instead +of + +addListener() +, +removeListener() + +introduced + +onEvent() +, +onPropertyChange() +, +onTDChange() +.
    • +Revised + +ExposedThing + +handlers +for +Property, +Action +and +Event. +
    • +Added +an +informal +section +on + +TD + +introspection. +
    • +Added +informal +section +for + +Observable +.
    +
    +
    +

    + +B. + +Open +issues +

    +

    +The +following +problems +are +being +discussed +and +need +most +attention: +

    + +
    +
    +

    + +C. + +Acknowledgements +

    +

    +Special +thanks +to +former +editor +Johannes +Hund +(until +August +2017, +when +at +Siemens +AG) + +for +developing +this +specification. +Also, +the +editors +would +like +to +thank +Dave +Raggett, +Matthias +Kovatsch, +Michael +Koster +and +Michael +McCool +for +their +comments +and +guidance. +

    +
    +
    +

    + +D. + +References +

    +
    +

    + +D.1 + +Normative +references +

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

    + +D.2 + +Informative +references +

    +[WOT-TD] +
    +WoT +Thing +Description + +. +W3C. +20 +August +2017. +URL: + +https://w3c.github.io/wot-thing-description/ +
    +
    + + + + From 91f9315f994d68f5fe9905c3a2a0b3263b1cdd8f Mon Sep 17 00:00:00 2001 From: ashimura Date: Sat, 24 Mar 2018 23:59:42 +0900 Subject: [PATCH 192/464] updating for pubrules checker --- releases/wd2/Overview.html | 14 ++-- releases/wd2/diff.html | 129 ++++++++++++++++++++++--------------- 2 files changed, 85 insertions(+), 58 deletions(-) diff --git a/releases/wd2/Overview.html b/releases/wd2/Overview.html index 74f9c6c2..14b28cf7 100644 --- a/releases/wd2/Overview.html +++ b/releases/wd2/Overview.html @@ -880,8 +880,8 @@ "date": "17 July 2015" } }, - "publishISODate": "2018-03-20T00:00:00.000Z", - "generatedSubtitle": "Editor's Draft 20 March 2018" + "publishISODate": "2018-03-27T00:00:00.000Z", + "generatedSubtitle": "Working Draft 27 March 2018" }

    Web of Things (WoT) Scripting API

    -

    W3C Editor's Draft

    +

    W3C Working Draft

    -
    This version:
    https://w3c.github.io/wot-scripting-api/
    Latest published version:
    https://www.w3.org/TR/wot-scripting-api/
    +
    This version:
    https://www.w3.org/TR/2018/WD-wot-scripting-api-20180327/
    +
    Latest published version:
    https://www.w3.org/TR/wot-scripting-api/
    Latest editor's draft:
    https://w3c.github.io/wot-scripting-api/
    +
    Previous version:
    https://www.w3.org/TR/2017/WD-wot-scripting-api-20170914/
    @@ -974,7 +976,7 @@

    W3C maintains a public list of any patent + W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes @@ -1734,4 +1736,4 @@

    [WEBIDL]
    Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/
    [WOT-ARCHITECTURE]
    Web of Things Architecture. W3C. 20 August 2017. URL: https://w3c.github.io/wot-architecture/

    D.2 Informative references

    [WOT-TD]
    WoT Thing Description . W3C. 20 August 2017. URL: https://w3c.github.io/wot-thing-description/ -
    +
    diff --git a/releases/wd2/diff.html b/releases/wd2/diff.html index 1ff0e8e1..f14a2c9d 100644 --- a/releases/wd2/diff.html +++ b/releases/wd2/diff.html @@ -915,8 +915,8 @@ "date": "17 July 2015" } }, - "publishISODate": "2018-03-20T00:00:00.000Z", - "generatedSubtitle": "Editor's Draft 20 March 2018" + "publishISODate": "2018-03-27T00:00:00.000Z", + "generatedSubtitle": "Working Draft 27 March 2018" } ]]> @@ -957,23 +957,21 @@

    Scripting API

    -

    +

    W3C First Public -Working -Editor's - +Working Draft 14 September 2017 -

    +Previous +version: +
    +https://www.w3.org/TR/2017/WD-wot-scripting-api-20170914/ +
    Editors:
    @@ -1515,6 +1518,34 @@

    ).

    +Changes +from +the +previous +publication +can +be +found +in + +Appendix +A +. +A + +diff-marked +version + +of +this +document +is +also +available +for +comparison +purposes. +

    Publication as a @@ -1595,7 +1626,7 @@

    maintains a - + public list of @@ -1717,17 +1748,17 @@

    Consuming a Thing -
  • -2.3 + +
    • +
  • + + +2.3 Exposing a Thing - -
    • - - -
  • +
  • 3. @@ -2768,11 +2799,7 @@

    TDLink dictionary - -

    • - - - +
  • @@ -4078,9 +4105,7 @@

    return the result; - -

    • - +

    @@ -5145,11 +5170,10 @@

    to support them. -

    - -Editor's +

    +Editor's note -

    +

    Semantic annotations need @@ -5163,10 +5187,11 @@

    In the [ - + WOT-TD - -] + + +] specification they represent @@ -8760,9 +8785,8 @@

    s, standardized in - the -Wot +Wot Things Description specification. @@ -8771,8 +8795,9 @@

    this version of + the -API, +API, Thing @@ -9148,15 +9173,20 @@

    Action invocation requests. -5.2.1 -The -RequestType

    -enumeration +5.2.1 + + +5.4 + + +The +RequestType +enumeration <span class="idlEnum" id="idl-def-requesttype" data-idl="" data-title="RequestType">enum <span class= "idlEnumID"><a data-lt="RequestType" href="#dom-requesttype" class= @@ -9170,13 +9200,8 @@

    "idlEnumItem">"event", }; - - -5.4 - - The -value +value " @@ -9205,9 +9230,7 @@

    The value " - - -action +action " represents requests @@ -9230,7 +9253,9 @@

    The value " -td + + +td directory @@ -14988,8 +15013,8 @@

    Web of Things (WoT) Scripting API

    -

    W3C Working Draft

    +

    W3C Working Draft

    -
    This version:
    https://www.w3.org/TR/2018/WD-wot-scripting-api-20180327/
    +
    This version:
    https://www.w3.org/TR/2018/WD-wot-scripting-api-20180329/
    Latest published version:
    https://www.w3.org/TR/wot-scripting-api/
    Latest editor's draft:
    https://w3c.github.io/wot-scripting-api/
    Previous version:
    https://www.w3.org/TR/2017/WD-wot-scripting-api-20170914/
    diff --git a/releases/wd2/diff.html b/releases/wd2/diff.html index a6d86941..f2fcbf67 100644 --- a/releases/wd2/diff.html +++ b/releases/wd2/diff.html @@ -915,8 +915,8 @@ "date": "17 July 2015" } }, - "publishISODate": "2018-03-27T00:00:00.000Z", - "generatedSubtitle": "Working Draft 27 March 2018" + "publishISODate": "2018-03-29T00:00:00.000Z", + "generatedSubtitle": "Working Draft 29 March 2018" } ]]> @@ -957,7 +957,7 @@

    Scripting API

    -

    +

    W3C @@ -970,8 +970,8 @@

    September 2017 -

    +
    + +

    5. The ExposedThing interface

    +

    The ExposedThing interface is + the server API that allows defining request handlers, + properties, Actions, and Events to a + Thing. It also implements the ConsumedThing interface. An ExposedThing is created by the produce() method.

    +
    +
    + Editor's note +
    +

    It is under consideration to use a constructor + for ExposedThing instead of + a factory method.

    +
    +
    + 
    ExposedThing implements ConsumedThing;
+
+interface ExposedThing {
+    // define how to expose and run the Thing
+    Promise<void> start();
+    Promise<void> stop();
+    Promise<void> register(optional USVString directory);
+    Promise<void> unregister(optional USVString directory);
+    Promise<void> emitEvent(DOMString eventName, any payload);
+    // define Thing Description modifiers
+    ExposedThing  addProperty(ThingProperty property);
+    ExposedThing  removeProperty(DOMString name);
+    ExposedThing  addAction(ThingAction action);
+    ExposedThing  removeAction(DOMString name);
+    ExposedThing  addEvent(ThingEvent event);
+    ExposedThing  removeEvent(DOMString name);
+    // define request handlers
+    ExposedThing  setPropertyReadHandler(DOMString name,
+                                         PropertyReadHandler readHandler);
+    ExposedThing  setPropertyWriteHandler(DOMString name,
+                                          PropertyWriteHandler writeHandler);
+    ExposedThing  setActionHandler(DOMString name, ActionHandler action);
 };
 
-callback PropertyReadHandler = Promise<any> ();
-
-callback PropertyWriteHandler = Promise<void> (any value);
-
-callback ActionHandler = Promise<any> (any parameters);

    5.1 The start() method

    -Start serving external requests for the Thing. -

    5.2 The stop() method

    -Stop serving external requests for the Thing. -

    5.3 The register() method

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

    5.4 The unregister() method

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

    5.5 The emitEvent() method

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

    5.6 The DataSchema type

    -The DataSchema type represents a data type specified in the Thing Description in a serialized form. -

    Editor's note

    -DataSchema is under development, currently it can denote any type supported by the Thing Description and the WoT Runtime. -

    5.7 The addProperty() method

    -Adds a Property defined by the argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining. -

    5.7.1 The ThingProperty dictionary

    dictionary ThingProperty : SemanticAnnotations {
-    required DOMString  name;
-    required DataSchema schema;
-             any        value;
-             boolean    writable = false;
-             boolean    observable = false;
-};

    -Represents the Thing -Property description. -

      -
    • The name attribute represents the name of the Property.
      • -
    • -The schema attribute represents the data type for the Property described by DataSchema. -
      • -
    • The value attribute represents the value of the Property.
      • -
    • -The writable attribute defines whether the Property can be updated. The default value is false. -
      • -
    • -The observable attribute defines whether the Property changes can be observed by an external client. The default value is false. -
      • -

    5.8 The removeProperty() method

    -Removes the Property specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining. -

    5.9 The addAction() method

    -Adds an Action to the Thing object as defined by the action argument of type ThingAction and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining. -

    5.9.1 The ThingAction dictionary

    -The ThingAction dictionary describes the arguments and the return value. -

      -
    • The name attribute provides the Action name.
      • -
    • The inputSchema attribute provides the description of the input arguments (argument list is represented by an object). If missing, it means the action does not accept arguments.
      • -
    • The outputSchema attribute provides the description of the returned data. If missing, it means the action does not return data.
      • -

    5.10 The removeAction() method

    -Removes the Action specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining. -

    5.11 The addEvent() method

    -Adds an event to the Thing object as defined by the event argument of type ThingEvent and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining. -

    5.11.1 The ThingEvent dictionary

    dictionary ThingEvent : SemanticAnnotations {
-    required DOMString  name;
-             DataSchema schema;
-};
      -
    • The name attribute represents the event name.
      • -
    • The schema attribute represents the type of the data that is attached to the event. If missing, it means the event does not carry data.
      • -

    5.12 The removeEvent() method

    -Removes the event specified by the name argument and updates the Thing Description. Returns a reference to the same object for supporting chaining. -

    5.13 The PropertyReadHandler callback

    -A function that returns a Promise and resolves it with the value of the Property matching the name argument to the setPropertyReadHandler function, or rejects with an error if the property is not found or the value cannot be retrieved. -

    5.14 The PropertyWriteHandler callback

    -A function called with value as argument that returns a Promise which is resolved when the value of the Property matching the name argument to the setPropertyReadHandler function is updated with value, or rejects with an error if the property is not found or the value cannot be updated. -

    Editor's note

    -Note that this function is invoked by implementations before the property is updated, so the code in this callback function can invoke the readProperty() method to find out the old value of the property, if needed. Therefore the old value is not provided to this method. -

    5.15 The ActionHandler callback

    -A function called with a parameters dictionary argument assembled by the WoT runtime based on the Thing Description and the external client request. It returns a Promise that rejects with an error or resolves if the action is successful or ongoing (may also resolve with a control object such as an Observable for actions that need progress notifications or that can be canceled). -

    5.16 The setPropertyReadHandler() method

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

    -The readHandler callback function will implement reading a Property and SHOULD be called by implementations when a request for reading a Property is received from the underlying platform. -

    -There SHOULD be at most one handler for any given Property and newly added handlers replace the old handlers. If no handler is initialized for any given Property, implementations SHOULD implement a default property read handler. -

    5.17 The setPropertyWriteHandler() method

    -Takes name as string argument and writeHandler as argument of type PropertyWriteHandler. Sets the handler function for writing the specified Property matched by name. Throws on error. Returns a reference to the same object for supporting chaining. -

    -There SHOULD be at most one write handler for any given Property and newly added handlers replace the old handlers. If no write handler is initialized for any given Property, implementations SHOULD implement default property update and notifying observers on change. -

    5.18 The setActionHandler() method

    -Takes name as string argument and action as argument of type ActionHandler. Sets the handler function for the specified Action matched by name. Throws on error. Returns a reference to the same object for supporting chaining. -

    -If provided, this callback function will implement invoking an Action and SHOULD be called by implementations when a request for invoking a Action is received from the underlying platform. The callback will receive a parameters dictionary argument. -

    -There SHOULD be exactly one handler for any given Action. If no handler is initialized for any given Action, implementations SHOULD return error if the action is invoked by any client. -

    5.19 Examples

    -Below some ExposedThing interface examples are given. -

    Example 7: Create a new blank exposed Thing
    try {
-  var thing = WoT.produce({ name: "tempSensor" });
+callback PropertyReadHandler = Promise<any> ();
+
+callback PropertyWriteHandler = Promise<void> (any value);
+
+callback ActionHandler = Promise<any> (any parameters);
    +
    +
    +

    5.1 + The start() + method

    +

    Start serving external requests for the Thing.

    +
    +
    +

    5.2 + The stop() method

    +

    Stop serving external requests for the Thing.

    +
    +
    +

    5.3 The register() + method

    +

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

    +
    +
    +

    5.4 The unregister() + method

    +

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

    +
    +
    +

    5.5 The emitEvent() + method

    +

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

    +
    +
    +

    5.6 The DataSchema type

    +
    + 
    typedef USVString DataSchema;
    +
    +

    The DataSchema type + represents a data type specified + in the Thing Description in a serialized + form.

    +
    +
    + Editor's note +
    +

    DataSchema is under + development, currently it can denote any type supported by + the Thing Description and the WoT Runtime.

    +
    +
    +
    +

    5.7 The addProperty() + method

    +

    Adds a Property defined by the argument and + updates the Thing Description. + Throws on error. Returns a reference to the same object for + supporting chaining.

    +
    +

    5.7.1 The ThingProperty + dictionary

    +
    + 
    dictionary ThingProperty : SemanticAnnotations {
+    required DOMString  name;
+    required DataSchema schema;
+             any        value;
+             boolean    writable = false;
+             boolean    observable = false;
+};
    +
    +

    Represents the Thing Property + description.

    +
      +
    • The name + attribute represents the name of the Property. +
      • +
    • The schema attribute represents + the data type for the Property + described by DataSchema. +
      • +
    • The value + attribute represents the value of the Property. +
      • +
    • The writable attribute + defines whether the Property can be + updated. The default value is false. +
      • +
    • The observable attribute + defines whether the Property changes + can be observed by an external client. The default + value is false. +
      • +
    +
    +
    +
    +

    5.8 The removeProperty() + method

    +

    Removes the Property specified by the + name argument and updates the Thing Description. Throws on error. Returns a + reference to the same object for supporting chaining.

    +
    +
    +

    5.9 The addAction() + method

    +

    Adds an Action to the Thing object as + defined by the action argument of type ThingAction and updates the Thing Description. Throws on error. Returns a + reference to the same object for supporting chaining.

    +
    +

    5.9.1 The ThingAction + dictionary

    + +

    The ThingAction + dictionary describes the arguments and the return + value.

    +
      +
    • The name attribute provides the + Action name. +
      • +
    • The inputSchema + attribute provides the description of the input arguments + (argument list is represented by an object). If missing, + it means the action does not accept arguments.
      • +
    • The outputSchema + attribute provides the description of the returned data. + If missing, it means the action does not return + data.
      • +
    +
    +
    +
    +

    5.10 The removeAction() + method

    +

    Removes the Action specified by the + name argument and updates the Thing Description. Throws on error. Returns a + reference to the same object for supporting chaining.

    +
    +
    +

    5.11 The addEvent() + method

    +

    Adds an event to the Thing object as + defined by the event argument of type ThingEvent and updates the Thing Description. Throws on error. Returns a + reference to the same object for supporting chaining.

    +
    +

    5.11.1 The ThingEvent + dictionary

    +
    + 
    dictionary ThingEvent : SemanticAnnotations {
+    required DOMString  name;
+             DataSchema schema;
+};
    +
    +
      +
    • The name attribute represents the + event name.
      • +
    • The schema attribute represents + the type of the data that is attached to the event. If + missing, it means the event does not carry data.
      • +
    +
    +
    +
    +

    5.12 The removeEvent() + method

    +

    Removes the event specified by the name + argument and updates the Thing + Description. Returns a reference to the same object for + supporting chaining.

    +
    +
    +

    5.13 The PropertyReadHandler + callback

    +

    A function that returns a Promise and resolves it with the + value of the Property matching the + name argument to the + setPropertyReadHandler function, or rejects with + an error if the property is not found or the value cannot be + retrieved.

    +
    +
    +

    5.14 The PropertyWriteHandler + callback

    +

    A function called with value as argument that + returns a Promise which is resolved when the value of the + Property matching the name argument to + the setPropertyReadHandler function is updated + with value, or rejects with an error if the + property is not found or the value cannot be updated.

    +
    +
    + Editor's note +
    +

    Note that this function is invoked by + implementations before the property is updated, so the code + in this callback function can invoke the + readProperty() method to find out the old + value of the property, if needed. Therefore the old value + is not provided to this method.

    +
    +
    +
    +

    5.15 The ActionHandler + callback

    +

    A function called with a parameters + dictionary argument assembled by the WoT runtime based on the Thing Description and the external client request. + It returns a Promise that rejects with an error or resolves + if the action is successful or ongoing (may also resolve with + a control object such as an Observable for actions that need + progress notifications or that can be canceled).

    +
    +
    +

    5.16 The setPropertyReadHandler() + method

    +

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

    +

    The readHandler callback function will + implement reading a Property and + SHOULD be called by + implementations when a request for reading a Property is received from the underlying + platform.

    +

    There SHOULD be at + most one handler for any given Property and + newly added handlers replace the old handlers. If no handler + is initialized for any given Property, + implementations SHOULD implement a default property read + handler.

    +
    +
    +

    + 5.17 The setPropertyWriteHandler() + method

    +

    Takes name as string argument and + writeHandler as argument of type PropertyWriteHandler. + Sets the handler function for writing the specified Property matched by name. Throws on + error. Returns a reference to the same object for supporting + chaining.

    +

    There SHOULD be at + most one write handler for any given Property and newly added handlers replace the old + handlers. If no write handler is initialized for any given + Property, implementations SHOULD implement default property update + and notifying observers on change.

    +
    +
    +

    5.18 The setActionHandler() + method

    +

    Takes name as string argument and + action as argument of type ActionHandler. Sets the handler + function for the specified Action matched by + name. Throws on error. Returns a reference to + the same object for supporting chaining.

    +

    If provided, this callback function will implement + invoking an Action and SHOULD be called by implementations when + a request for invoking a Action is received + from the underlying platform. The callback will receive a + parameters dictionary argument.

    +

    There SHOULD be + exactly one handler for any given Action. If no + handler is initialized for any given Action, + implementations SHOULD return error if the action is invoked by + any client.

    +
    +
    +

    5.19 + Examples

    +

    Below some ExposedThing interface examples + are given.

    +
    +
    + Example 7: Create a new blank exposed + Thing +
    + 
    +        try {
+  var thing = WoT.produce({ name: "tempSensor" });
   // manually add Interactions
   thing.addProperty({
-    name: "temperature",
-    value: 0.0,
-    schema: '{ "type": "number" }'
-    // use default values for the rest
+    name: "temperature",
+    value: 0.0,
+    schema: '{ "type": "number" }'
+    // use default values for the rest
   }).addProperty({
-    name: "max",
-    value: 0.0,
-    schema: '{ "type": "number" }'
-    // use default values for the rest
+    name: "max",
+    value: 0.0,
+    schema: '{ "type": "number" }'
+    // use default values for the rest
   }).addAction({
-    name: "reset",
+    name: "reset",
     // no input, no output
   }).addEvent({
-    name: "onchange",
-    schema: '{ "type": "number" }'
+    name: "onchange",
+    schema: '{ "type": "number" }'
   });
   // add server functionality
-  thing.setActionHandler("reset", () => {
-    console.log("Resetting maximum");
-    thing.writeProperty("max", 0.0);
+  thing.setActionHandler("reset", () => {
+    console.log("Resetting maximum");
+    thing.writeProperty("max", 0.0);
   });
-  thing.start().then(() => {
+  thing.start().then(() => {
       thing.register();
   });
   // define Thing business logic
   setInterval( async () => {
-    let mock = Math.random()*100;
-    thing.writeProperty("temperature", mock);
-    let old = await thing.readProperty("max");
+    let mock = Math.random()*100;
+    thing.writeProperty("temperature", mock);
+    let old = await thing.readProperty("max");
     if (old < mock) {
-      thing.writeProperty("max", mock);
+      thing.writeProperty("max", mock);
       thing.emitEvent("onchange");
     }
   }, 1000);
 } catch (err) {
-   console.log("Error creating ExposedThing: " + err);
-}
    Example 8: Create a new exposed Thing from a Thing Description
    let thingDescription = '{ "@context": [ "https://w3c.github.io/wot/w3c-wot-td-context.jsonld", "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ], "@type": [ "Thing", "Sensor" ], "name": "mySensor", "geo:location": "testspace", "interaction": [ { "@type": [ "Property", "Temperature" ], "name": "prop1", "schema": { "type": "number" }, "saref:TemperatureUnit": "degree_Celsius" } ] }';
+   console.log("Error creating ExposedThing: " + err);
+}
    +
    +
    +
    + Example 8: Create a new exposed Thing from + a Thing Description +
    + 
    +        let thingDescription = '{ "@context": [ "https://w3c.github.io/wot/w3c-wot-td-context.jsonld", "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ], "@type": [ "Thing", "Sensor" ], "name": "mySensor", "geo:location": "testspace", "interaction": [ { "@type": [ "Property", "Temperature" ], "name": "prop1", "schema": { "type": "number" }, "saref:TemperatureUnit": "degree_Celsius" } ] }';
 try {
-  // note that produce() fails if thingDescription contains error
-  let thing = WoT.produce(thingDescription);
-  // Interactions were added from TD
-  // WoT adds generic handler for reading any property
-  // define a specific handler for one property
-  let name = "examplePropertyName";
+  // note that produce() fails if thingDescription contains error
+  let thing = WoT.produce(thingDescription);
+  // Interactions were added from TD
+  // WoT adds generic handler for reading any property
+  // define a specific handler for one property
+  let name = "examplePropertyName";
   thing.setPropertyReadHandler(name, () => {
-    console.log("Handling read request for " + name);
-    return new Promise((resolve, reject) => {
-        let examplePropertyValue = 5;
+    console.log("Handling read request for " + name);
+    return new Promise((resolve, reject) => {
+        let examplePropertyValue = 5;
         resolve(examplePropertyValue);
       },
       e => {
-        console.log("Error");
+        console.log("Error");
       });
   });
   thing.start();
 } catch(err) {
-   console.log("Error creating ExposedThing: " + err);
-}
    Example 9: Create a new exposed Thing from a TD URI
    // fetch an external TD, e.g., to set up a proxy for that Thing
-WoT.fetch("http://myservice.org/mySensor/description").then(td => {
-  // WoT.produce() ignores instance-specific metadata (security, form)
+   console.log("Error creating ExposedThing: " + err);
+}
    +
    +
    +
    + Example 9: Create a new exposed Thing from + a TD URI +
    + 
    +        // fetch an external TD, e.g., to set up a proxy for that Thing
+WoT.fetch("http://myservice.org/mySensor/description").then(td => {
+  // WoT.produce() ignores instance-specific metadata (security, form)
   let thing = WoT.produce(td);
-  // Interactions were added from TD
+  // Interactions were added from TD
   // add server functionality
   // ...
-});

    6. Experimental extensions to the ConsumedThing interface

    This section is non-normative.

    -The ThingDescription related functionality, such as enumerating Properties, Actions, Events and links (introspection) is an API extension that is out of scope for this specification. However, the draft interfaces are defined here for informative purposes. -

    6.1 The getProperties() method

    -Returns the list of Properties defined in the Thing Description of the Thing in the form of a list of ThingProperty objects. -

    6.2 The getActions() method

    -Returns the list of Actions defined in the Thing Description of the Thing in the form of a list of ThingAction objects. -

    6.3 The getEvents() method

    -Returns the list of Events defined in the Thing Description of the Thing in the form of a list of ThingEvent objects. -

    7. Observables

    This section is non-normative.

    -Observables are proposed to be included in ECMAScript and are used for handling pushed data associated with various possible sources, for instance events, timers, streams, etc. A minimal required implementation is described here. -

    Editor's note

    -This section is informal and contains rather laconic information for implementations on what to support for interoperability. -

    interface Observable {
-    Subscription subscribe((Observer or OnNext) next,
-                           optional OnError error,
-                           optional OnComplete complete);
+});
    +
    +
    +
    +
    + +

    + 6. Experimental extensions to the + ConsumedThing interface

    +

    This section is non-normative.

    +

    The ThingDescription related + functionality, such as enumerating Properties, + Actions, Events and links (introspection) is an + API extension that is out of scope for this specification. + However, the draft interfaces are defined here for informative + purposes.

    + +
    +

    6.1 The getProperties() + method

    +

    Returns the list of Properties defined in + the Thing Description of the Thing in the form of a list of ThingProperty objects.

    +
    +
    +

    6.2 The getActions() + method

    +

    Returns the list of Actions defined in the + Thing Description of the Thing in the form of a list of ThingAction objects.

    +
    +
    +

    6.3 The getEvents() + method

    +

    Returns the list of Events defined in the + Thing Description of the Thing in the form of a list of ThingEvent objects.

    +
    + +
    +
    + +

    7. + Observables

    +

    This section is non-normative.

    +

    Observables are proposed to + be included in ECMAScript and are used for handling pushed data + associated with various possible sources, for instance events, + timers, streams, etc. A minimal required implementation is + described here.

    +
    +
    + Editor's note +
    +

    This section is informal and contains rather + laconic information for implementations on what to support + for interoperability.

    +
    +
    + 
    interface Observable {
+    Subscription subscribe((Observer or OnNext) next,
+                           optional OnError error,
+                           optional OnComplete complete);
 };
 
-interface Subscription {
-    void unsubscribe();
-    readonly attribute boolean closed;
+interface Subscription {
+    void unsubscribe();
+    readonly attribute boolean closed;
 };
 
-interface Observer {
-    void next(any value);
-    void error(Error error);
-    void complete();
+interface Observer {
+    void next(any value);
+    void error(Error error);
+    void complete();
 };
 
-callback OnNext = void (any value);
-
-callback OnError = void (Error error);
-
-callback OnComplete = void ();

    7.1 The Observer interface

    -The Observer interface defines the callbacks needed to handle an Observable: -

      -
    • -The next() function, as well as the OnNext callback takes the next sample for the data in the value argument. -
      • -
    • -The error() function, as well as the OnError callback takes an error in the value argument. It is called when an error occured in producing the data the client should know about. -
      • -
    • -The complete() function, as well as the OnComplete callback is called when the data source has finished sending values. +callback OnNext = void (any value); + +callback OnError = void (Error error); + +callback OnComplete = void (); + +
      +

      7.1 The Observer interface

      +

      The Observer interface + defines the callbacks needed to handle an Observable:

      +
        +
      • The next() function, + as well as the OnNext callback takes the next + sample for the data in the value + argument.
        • +
      • The error() + function, as well as the OnError callback + takes an error in the value argument. It is + called when an error occured in producing the data the + client should know about.
        • +
      • The complete() + function, as well as the OnComplete + callback is called when the data source has finished + sending values.
        • +
      +
      +
      +

      7.2 The Subscription interface

      +

      Contains the closed property of + type boolean that tells if the subscription is + closed or active.

      +

      Also, contains the unsubscribe() + method that cancels the subscription, i.e. makes a request to + the underlying platform to stop receiving data from the + source, and sets the closed property to + false.

      +
      +
      +

      7.3 The Observable interface

      +

      The Observable interface + enabled subscribing to pushed data notifications by the + subscribe() + method:

      +
        +
      • If the subscribe() method is called with + an Observer object, + initialize the data, error and completion handling + callbacks from that object, or throw on error.
        • -

      7.2 The Subscription interface

      -Contains the closed property of type boolean that tells if the subscription is closed or active. -

      -Also, contains the unsubscribe() method that cancels the subscription, i.e. makes a request to the underlying platform to stop receiving data from the source, and sets the closed property to false. -

      7.3 The Observable interface

      -The Observable interface enabled subscribing to pushed data notifications by the subscribe() method: -

        -
      • -If the subscribe() method is called with an Observer object, initialize the data, error and completion handling callbacks from that object, or throw on error. -
        • -
      • -Otherwise, if the subscribe() method is called with a function, initialize the data handler callback with that function. If the next argument is provided and is a function, initialize the error handling callback with that function, or throw on error. If the third argument is provided and is a function, initialize the completion handler with that function, or throw on error. -
        • -
      • -After callback initializations, the implementation should request the underlying platform to provide data, error and completion notifications for the supported data source. -
        • -

    8. Security and Privacy

    Editor's note

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

    9. Terminology and conventions

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

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

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

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

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

    -The term - - secure context is defined in [WEBAPPSEC]. -

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

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

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

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

    -The terms hyperlink reference and relation type are defined in [HTML5] and RFC8288. -

    10. Conformance

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

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

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

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

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

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

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

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

    A. Changes

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

      -
    • -Synchronized the Scripting API with the Thing Description specification. Defined ThingDescription, ThingTemplate, SemanticAnnotations, SemanticType, SemanticMetadata, input and output data descriptions, etc. -
      • -
    • -Separated consume() to fetch() and consume(). -
      • -
    • -Changed expose() to accept a Thing Template. -
      • -
    • -Instead of addListener(), removeListener() introduced onEvent(), onPropertyChange(), onTDChange(). -
      • -
    • -Revised ExposedThing handlers for Property, Action and Event. -
      • -
    • -Added an informal section on TD introspection. -
      • -
    • -Added informal section for Observable. -
      • -

    B. Open issues

    -The following problems are being discussed and need most attention: -

    C. Acknowledgements

    -Special thanks to former editor Johannes Hund (until August 2017, when at Siemens AG) for developing this specification. Also, the editors would like to thank Dave Raggett, Matthias Kovatsch, Michael Koster and Michael McCool for their comments and guidance. -

    D. References

    D.1 Normative references

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

    D.2 Informative references

    [WOT-TD]
    WoT Thing Description . W3C. 20 August 2017. URL: https://w3c.github.io/wot-thing-description/ -
    +
  • Otherwise, if the subscribe() method is + called with a function, initialize the data handler + callback with that function. If the next argument is + provided and is a function, initialize the error handling + callback with that function, or throw on error. If the + third argument is provided and is a function, initialize + the completion handler with that function, or throw on + error.
    • +
  • After callback initializations, the implementation + should request the underlying platform to provide data, + error and completion notifications for the supported data + source.
    • + +
    +
    +
    + +

    8. Security and + Privacy

    +
    +
    + Editor's note +
    +

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

    +
    +
    +
    + +

    9. Terminology and conventions

    +

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

    +

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

    +

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

    +

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

    +

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

    +

    The term + secure + context is defined in [WEBAPPSEC].

    +

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

    +

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

    +

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

    +

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

    +

    The terms hyperlink reference and + relation + type are defined in [HTML5] and RFC8288.

    +
    +
    + +

    10. + Conformance

    +

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

    +

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

    +

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

    +

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

    +

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

    +

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

    +

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

    +

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

    +
    +
    + +

    A. Changes

    +

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

    +
      +
    • Synchronized the Scripting API with the Thing + Description specification. Defined + ThingDescription, ThingTemplate, + SemanticAnnotations, SemanticType, + SemanticMetadata, input and output data + descriptions, etc. +
      • +
    • Separated consume() to fetch() + and consume().
      • +
    • Changed expose() to accept a Thing Template. +
      • +
    • Instead of addListener(), + removeListener() introduced + onEvent(), onPropertyChange(), + onTDChange().
      • +
    • Revised ExposedThing handlers for Property, + Action and Event.
      • +
    • Added an informal section on TD introspection. +
      • +
    • Added informal section for Observable.
      • +
    +
    +
    + +

    B. Open issues

    +

    The following problems are being discussed and need most + attention:

    + +
    +
    + +

    C. + Acknowledgements

    +

    Special thanks to former editor Johannes Hund (until August + 2017, when at Siemens AG) for developing this specification. + Also, the editors would like to thank Dave Raggett, Matthias + Kovatsch, Michael Koster and Michael McCool for their comments + and guidance.

    +
    +
    + +

    D. + References

    +
    +

    D.1 Normative references

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

    D.2 Informative references

    +
    +
    [WOT-TD]
    +
    + WoT + Thing Description . W3C. 20 August 2017. URL: + https://w3c.github.io/wot-thing-description/ +
    +
    +
    +
    + + + + diff --git a/releases/wd2/diff.html b/releases/wd2/diff.html index f2fcbf67..9f0f91fb 100644 --- a/releases/wd2/diff.html +++ b/releases/wd2/diff.html @@ -9,90 +9,90 @@ "width=device-width, initial-scale=1, shrink-to-fit=no" /> Web of Things (WoT) Scripting API Scripting API -

    +

    W3C @@ -970,9 +970,9 @@

    September 2017 -

    diff --git a/releases/wd2/diff.html b/releases/wd2/diff.html index 9f0f91fb..3b5529da 100644 --- a/releases/wd2/diff.html +++ b/releases/wd2/diff.html @@ -5335,7 +5335,7 @@

    standardized in the - + Wot Things Description @@ -9542,12 +9542,12 @@

    a data type - + specified in the - + Thing Description @@ -14486,7 +14486,7 @@

    API with the - + Thing Description specification @@ -15001,7 +15001,7 @@

    references

    [WOT-TD] -
    +
    WoT Thing Description @@ -15012,8 +15012,8 @@

    August 2017. URL: - -https://w3c.github.io/wot-thing-description/ + +https://www.w3.org/TR/2018/WD-wot-thing-description-20180405/

    Table of

    1. Introduction

    -

    The overall WoT concepts are described in the WoT Architecture - document. The Web of Things is made of entities (The overall WoT concepts are described in the + + WoT Architecture document. The Web of Things is made of entities (Things) that can describe their capabilities in a machine-interpretable format, the

    [WOT-ARCHITECTURE]
    - Web of - Things Architecture. W3C. 20 August 2017. URL: - https://w3c.github.io/wot-architecture/ + + Web of Things Architecture. W3C. 14 September 2017. URL: + https://www.w3.org/TR/2017/WD-wot-architecture-20170914/
    diff --git a/releases/wd2/diff.html b/releases/wd2/diff.html index 3b5529da..6ead521d 100644 --- a/releases/wd2/diff.html +++ b/releases/wd2/diff.html @@ -2795,13 +2795,10 @@

    The TDLink - -dictionary - - - - - + + +dictionary +
  • @@ -2963,7 +2960,7 @@

    described in the - + WoT Architecture @@ -2977,7 +2974,7 @@

    of entities ( - + Thing s) @@ -3002,7 +2999,7 @@

    capabilities through the - + WoT Interface . @@ -4107,9 +4104,7 @@

    return the result; - -

    • - +

    @@ -5191,11 +5186,11 @@

    In the [ - - -WOT-TD - -] + +WOT-TD + + +] specification they represent @@ -5763,10 +5758,8 @@

    of SemanticType - - - -objects + +objects that define the @@ -5781,20 +5774,22 @@

    metadata type-value pairs. -

    +

    The - + metadata - + property denotes a list of - + SemanticMetadata - -objects + + + +objects (type-value pairs).

    @@ -8789,8 +8784,9 @@

    s, standardized in + the -Wot +Wot Things Description specification. @@ -8799,9 +8795,8 @@

    this version of - the -API, +API, Thing @@ -9177,20 +9172,15 @@

    Action invocation requests. +5.2.1 +The +RequestType

    -5.2.1 - - -5.4 - - -The -RequestType -enumeration +enumeration <span class="idlEnum" id="idl-def-requesttype" data-idl="" data-title="RequestType">enum <span class= "idlEnumID"><a data-lt="RequestType" href="#dom-requesttype" class= @@ -9204,8 +9194,13 @@

    "idlEnumItem">"event", }; + + +5.4 + + The -value +value " @@ -11740,17 +11735,16 @@

    will receive a - - -parameters - + +parameters + dictionary argument. -

    +

    There - + SHOULD - + be exactly one @@ -11758,9 +11752,9 @@

    for any given - + Action -. +. If no handler @@ -11769,13 +11763,13 @@

    for any given - + Action -, +, implementations - + SHOULD - + return error if @@ -11786,15 +11780,16 @@

    by any client. -

    - -5.19 +

    +5.19 Examples

    Below some - + + + Request @@ -14973,7 +14968,7 @@

    [WOT-ARCHITECTURE]
    - + Web of @@ -14982,20 +14977,14 @@

    . W3C. -20 -August +14 +September 2017. URL: - -https://w3c.github.io/wot-architecture/ - -

    - -

    -
    -

    - -D.2 + +https://www.w3.org/TR/2017/WD-wot-architecture-20170914/ +

    +D.2 Informative references @@ -15008,13 +14997,20 @@

    . W3C. + 20 August 2017. URL: - -https://www.w3.org/TR/2018/WD-wot-thing-description-20180405/ -

    +https://w3c.github.io/wot-architecture/ + + +https://www.w3.org/TR/2018/WD-wot-thing-description-20180405/ + + + + +

    URL path are defined in [URL].

    +

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

    + serialized origin, + + executing algorithms + + + in parallel, + + + queue a task, + + + task source, + + + iframe, + + + valid MIME type.

    +

    A browsing context refers to the environment in which hyperlink reference and relation type are defined in [HTML5] and HTML52] and RFC8288.

    @@ -4691,15 +4710,20 @@

    https://www.w3.org/TR/encoding/ -
    [HTML5]
    +
    [HTML52]
    HTML5. - Ian Hickson; Robin Berjon; Steve Faulkner; Travis - Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia - Pfeiffer. W3C. 28 October 2014. W3C Recommendation. URL: - https://www.w3.org/TR/html5/ + "https://www.w3.org/TR/html52/">HTML 5.2. + Steve Faulkner; + Arron Eicholz; + Travis Leithead; + Alex Danilo; + Sangwhan Moon; + Erika Doyle Navara; + Theresa O'Connor; + Robin Berjon. + W3C. 14 December 2017. W3C Recommendation. URL: + https://www.w3.org/TR/html52/
    [JSON-LD]
    diff --git a/releases/wd2/diff.html b/releases/wd2/diff.html index 6ead521d..886d50b7 100644 --- a/releases/wd2/diff.html +++ b/releases/wd2/diff.html @@ -1745,17 +1745,17 @@

    Consuming a Thing - - -
  • - - -2.3 +
  • +2.3 Exposing a Thing -
  • + +
    • + + +
  • 3. @@ -1874,13 +1874,12 @@

    Examples 4. - The -ConsumedThing +ConsumedThing interface 4.1 -The +The invokeAction() @@ -2795,10 +2794,13 @@

    The TDLink - - -dictionary -

    • + +dictionary + + + + +
  • @@ -4104,7 +4106,9 @@

    return the result; -

    • + + +

    @@ -7438,9 +7442,7 @@

    Action is observed. - -

    -Editor's +Editor's note The observe() @@ -7458,7 +7460,9 @@

    kept for convenience. -4.8 + +

    +4.8

    The @@ -8784,9 +8788,8 @@

    s, standardized in - the -Wot +Wot Things Description specification. @@ -8795,8 +8798,9 @@

    this version of + the -API, +API, Thing @@ -10015,10 +10019,7 @@

    Thing Description . - - - -5.4.2 +5.4.2 The SemanticType dictionary @@ -10081,7 +10082,9 @@

    the semantic classification. -Editor's + + +Editor's note Semantic type @@ -10091,6 +10094,7 @@

    added. +

    @@ -11142,9 +11146,8 @@

    Description and - the -external +external client request. It @@ -11159,8 +11162,9 @@

    or resolves if + the -action +action is successful or @@ -11735,16 +11739,17 @@

    will receive a - -parameters - + + +parameters + dictionary argument. -

    +

    There - + SHOULD - + be exactly one @@ -11752,9 +11757,9 @@

    for any given - + Action -. +. If no handler @@ -11763,13 +11768,13 @@

    for any given - + Action -, +, implementations - + SHOULD - + return error if @@ -11780,16 +11785,15 @@

    by any client. -

    -5.19 +

    + +5.19 Examples

    Below some - - - + Request @@ -13717,8 +13721,11 @@

    in [ - -HTML5 +HTML5 + + +HTML52 + ] @@ -13731,60 +13738,60 @@

    of browser implementations: - + browsing context , - - + + top-level browsing context , - + global object , - + incumbent settings object , - + Document , - + document base URL , - - + + Window , - - + + WindowProxy , - - + + origin , - + ASCII serialized @@ -13793,32 +13800,32 @@

    , executing algorithms - - + + in parallel , - - + + queue a task , - - + + task source , - + iframe , - - + + valid MIME type @@ -14157,8 +14164,8 @@

    defined in [ - -HTML5 + +HTML52 ] and @@ -14783,39 +14790,67 @@

    -
    -[HTML5] +[HTML5] + +
    +[HTML52] +
    - + -HTML5 +HTML5 + +HTML +5.2 + . -Ian +Ian Hickson; Robin Berjon; + Steve Faulkner; +Arron +Eicholz; + Travis Leithead; +Alex +Danilo; +Sangwhan +Moon; + Erika Doyle Navara; Theresa O'Connor; -Silvia +Silvia Pfeiffer. + +Robin +Berjon. + W3C. -28 +28 October 2014. + +14 +December +2017. + W3C Recommendation. URL: - -https://www.w3.org/TR/html5/ +https://www.w3.org/TR/html5/ + + +https://www.w3.org/TR/html52/ +
    From 50e0519761b1b61c0e8be1d2082795a1dfa58174 Mon Sep 17 00:00:00 2001 From: ashimura Date: Thu, 5 Apr 2018 03:55:17 +0900 Subject: [PATCH 201/464] fix minor typos on URLs --- releases/wd2/Overview.html | 18 +++---- releases/wd2/diff.html | 97 ++++++++++++++++++++------------------ 2 files changed, 59 insertions(+), 56 deletions(-) diff --git a/releases/wd2/Overview.html b/releases/wd2/Overview.html index f1c6c45f..518845eb 100644 --- a/releases/wd2/Overview.html +++ b/releases/wd2/Overview.html @@ -894,7 +894,7 @@ "date": "1 October 2012" }, "WEBAPPSEC": { - "href": "https://w3c.github.io/webappsec/specs/powerfulfeatures", + "href": "https://w3c.github.io/webappsec/specs/powerfulfeatures/", "title": "Secure Contexts", "publisher": "W3C", "date": "17 July 2015" @@ -1694,7 +1694,7 @@

    1.

    For an introduction on how scripts could be used in Web of Things, check the Primer + "https://w3c.github.io/wot-scripting-api/primer/">Primer document. For some background on API design decisions check the Rationale @@ -4540,15 +4540,15 @@

    ECMASCRIPT].

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

    @@ -4561,7 +4561,7 @@

    ENCODING].

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

    + RFC2046.

    The terms hyperlink reference and relation @@ -4760,10 +4760,10 @@

    [WEBAPPSEC]

    + "https://w3c.github.io/webappsec/specs/powerfulfeatures/"> Secure Contexts. W3C. 17 July 2015. URL: https://w3c.github.io/webappsec/specs/powerfulfeatures + "https://w3c.github.io/webappsec/specs/powerfulfeatures/">https://w3c.github.io/webappsec/specs/powerfulfeatures/
    [WEBIDL]
    diff --git a/releases/wd2/diff.html b/releases/wd2/diff.html index 886d50b7..6c3b306d 100644 --- a/releases/wd2/diff.html +++ b/releases/wd2/diff.html @@ -909,7 +909,7 @@ "date": "1 October 2012" }, "WEBAPPSEC": { - "href": "https://w3c.github.io/webappsec/specs/powerfulfeatures", + "href": "https://w3c.github.io/webappsec/specs/powerfulfeatures/", "title": "Secure Contexts", "publisher": "W3C", "date": "17 July 2015" @@ -3247,7 +3247,7 @@

    , check the - + Primer document. @@ -4106,9 +4106,7 @@

    return the result; - - - +

    @@ -7545,9 +7543,7 @@

    . 4.9.1.1 The - - -PropertyChangeEventInit +PropertyChangeEventInit dictionary <span class="idlDictionary" id= "idl-def-propertychangeeventinit" data-idl="" data-title= @@ -7579,7 +7575,9 @@

    Property name. The -value + + +value subscribe() @@ -8718,20 +8716,16 @@

    "idlCallbackID">PropertyWriteHandler = Promise<void> (any value); - -data-title="ActionHandler">callback +data-title="ActionHandler">callback ActionHandler = Promise - - -; - -< + +< href="https://heycam.github.io/webidl/#idl-any"> any @@ -8739,10 +8733,16 @@

    > ( - -any - -parameters + + +any + + +; + + + +parameters ); @@ -11739,17 +11739,16 @@

    will receive a - - -parameters - + +parameters + dictionary argument. -

    +

    There - + SHOULD - + be exactly one @@ -11757,9 +11756,9 @@

    for any given - + Action -. +. If no handler @@ -11768,13 +11767,13 @@

    for any given - + Action -, +, implementations - + SHOULD - + return error if @@ -11785,15 +11784,16 @@

    by any client. -

    - -5.19 +

    +5.19 Examples

    Below some - + + + Request @@ -14012,8 +14012,8 @@

    ].

    - - + + DOMString , @@ -14022,18 +14022,18 @@

    USVString , - + ArrayBuffer , - + BufferSource and - + any @@ -14144,7 +14144,7 @@

    are defined in - + RFC2046 .

    @@ -14956,7 +14956,7 @@

    [WEBAPPSEC]
    - + Secure Contexts @@ -14967,8 +14967,11 @@

    July 2015. URL: - -https://w3c.github.io/webappsec/specs/powerfulfeatures +https://w3c.github.io/webappsec/specs/powerfulfeatures + + +https://w3c.github.io/webappsec/specs/powerfulfeatures/ +

    From 85c76e7281fd2c46fad2f4d2d7b36bc0f1a1f4f5 Mon Sep 17 00:00:00 2001 From: ashimura Date: Thu, 5 Apr 2018 04:02:13 +0900 Subject: [PATCH 202/464] fix remaining Editor's Draft --- releases/wd2/Overview.html | 2 +- releases/wd2/diff.html | 41 +++++++++++++++++--------------------- 2 files changed, 19 insertions(+), 24 deletions(-) diff --git a/releases/wd2/Overview.html b/releases/wd2/Overview.html index 518845eb..2293edc4 100644 --- a/releases/wd2/Overview.html +++ b/releases/wd2/Overview.html @@ -1064,7 +1064,7 @@

    Status of This Document

    This document was published by the Web of Things Working Group as - an Editor's Draft. Comments regarding this document are + a Working Draft. Comments regarding this document are welcome. Please send them to public-wot-wg@w3.org (subscribe, diff --git a/releases/wd2/diff.html b/releases/wd2/diff.html index 6c3b306d..a9fbeae8 100644 --- a/releases/wd2/diff.html +++ b/releases/wd2/diff.html @@ -1476,14 +1476,11 @@

    Group as -a -First +a +First Public -Working -an -Editor's - +Working Draft. This document @@ -8716,16 +8713,20 @@

    "idlCallbackID">PropertyWriteHandler = Promise<void> (any value); - -data-title="ActionHandler">callback +data-title="ActionHandler">callback ActionHandler = Promise - -< + + +; + +< href="https://heycam.github.io/webidl/#idl-any"> any @@ -8733,16 +8734,10 @@

    > ( - - -any - - -; - - - -parameters + +any + +parameters ); @@ -11146,8 +11141,9 @@

    Description and + the -external +external client request. It @@ -11162,9 +11158,8 @@

    or resolves if - the -action +action is successful or From 29f38c2097da34d74631c8371559468f252c3905 Mon Sep 17 00:00:00 2001 From: ashimura Date: Thu, 5 Apr 2018 04:08:58 +0900 Subject: [PATCH 203/464] fix remaining Editor's Draft --- releases/wd2/Overview.html | 4 +++- releases/wd2/diff.html | 19 ++++++++++--------- 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/releases/wd2/Overview.html b/releases/wd2/Overview.html index 2293edc4..9d8eb7cf 100644 --- a/releases/wd2/Overview.html +++ b/releases/wd2/Overview.html @@ -1064,7 +1064,9 @@

    Status of This Document

    This document was published by the Web of Things Working Group as - a Working Draft. Comments regarding this document are + a Working Draft. + This document is intended to become a W3C Recommendation. + Comments regarding this document are welcome. Please send them to public-wot-wg@w3.org (subscribe, diff --git a/releases/wd2/diff.html b/releases/wd2/diff.html index a9fbeae8..168ffb23 100644 --- a/releases/wd2/diff.html +++ b/releases/wd2/diff.html @@ -1482,16 +1482,17 @@

    Working Draft. -This +This document is intended to become a + W3C + Recommendation. - Comments regarding this @@ -7564,7 +7565,9 @@

    "PropertyChangeEventInit"> }; The -name + + +name > attribute represents @@ -7572,9 +7575,7 @@

    Property name. The - - -value +value subscribe() @@ -11141,9 +11142,8 @@

    Description and - the -external +external client request. It @@ -11158,8 +11158,9 @@

    or resolves if + the -action +action is successful or From 229a1bcbc0e08b3af259b18e3d1c3f2ef065877c Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 30 Apr 2018 11:48:48 +0300 Subject: [PATCH 204/464] API update: change WebIDL Signed-off-by: Zoltan Kis --- index.html | 499 ++++++++++++++++++++--------------------------------- 1 file changed, 184 insertions(+), 315 deletions(-) diff --git a/index.html b/index.html index eab959b3..b5ba38de 100644 --- a/index.html +++ b/index.html @@ -227,22 +227,104 @@

    The WoT object

    // [SecureContext] // [NamespaceObject] interface WoT { - Observable<ConsumedThing> discover(optional ThingFilter filter); + Observable<ThingDescription> discover(optional ThingFilter filter); Promise<ThingDescription> fetch(USVString url); ConsumedThing consume(ThingDescription td); ExposedThing produce(ThingModel model); }; typedef USVString ThingDescription; - typedef (ThingTemplate or ThingDescription) ThingModel; + typedef (ThingTemplate or ThingDescription or ConsumedThing) ThingModel; +

    + The fetch() method could be merged into discover(), i.e. discover({ url: tdURL }) is equivalent to former fetch(tdURL). Alternatively, both could be replaced by `fetch(optional (ThingFilter or USVString) locator)`, where `locator` can be a URL (for direct fetch) or a `ThingFilter` (for discovery). +

    +

    The algorithms for the WoT methods will be specified later, including error handling and security considerations.

    +
    +

    The ThingTemplate dictionary

    +

    + A `ThingTemplate` is a dictionary that provides Thing related semantic metadata. +

    + 
    +        typedef (object or USVString or sequence<USVString>) JsonLdDefinition;
+        interface ThingTemplate {
+          getter JsonLdDefinition (USVString name);
+          setter void (USVString name, JsonLdDefinition value);
+        };
+
    +

    + The JsonLdDefinition type can be either a JSON object, a string representing an IRI, or an array of strings. +

    +

    The ThingTemplate dictionary initializes a Thing: +

    +
      +
    • + The @context attribute represents a semantic context as USVString. +
      • +
    • + The @type attribute represents a semantic type as USVString. +
      • +
    • + The @id attribute represents an identifier, typically a URI, IRI, or URN as USVString. +
      • +
    • + The base attribute represents a base URL as USVString. +
      • +
    • + The name attribute represents a user given name as DOMString. +
      • +
    • + Apart from the core semantic properties defined above, others may also be defined on a Thing, for instance "gms:COVParams" (with namespace definition), or "iotschema:unit" etc. +
      • +
    +

    + Support for configuration and security metadata will be added later. +

    +
    + +
    +

    The ThingDescription type

    +

    + Representation of the Thing Description, standardized in the [Wot Things Description](https://w3c.github.io/wot-thing-description/) specification. +

    +

    + In this version of the API, Thing Descriptions are represented as an opaque `USVString` representing a serialized TD. +

    +
    + +

    The fetch() method

    +

    + Accepts an url argument of type `USVString` and returns a Promise that resolves with a ThingDescription. +

    +
    + +

    The consume() method

    +

    + Accepts an td argument of type ThingDescription and returns a ConsumedThing object instantiated based on that description. +

    +
    + +

    The produce() method

    +

    + Accepts a model argument of type ThingTemplate and returns an ExposedThing object, locally created based on the provided initialization parameters. An ExposedThing can be created in the following ways: +

    +
      +
    1. + from an initial model (including a user given name and semantic metadata properties), then adding Properties, Actions, Events and request handlers; +
      2. +
    2. + from a Thing Description (possibly of a ConsumedThing object), then adding request handlers. +
      3. +
    +
    +

    The discover() method

    - Starts the discovery process that will provide ConsumedThing objects that match the optional argument ThingFilter. When the argument is not provided, starts the widest discovery the Thing Description and Protocol Bindings allow and support. + Starts the discovery process that will provide ThingDescriptions that match the optional argument ThingFilter. When the argument is not provided, uses all supported discovery methods. Returns an [Observable](https://github.com/tc39/proposal-observable) object that can be subscribed to and unsubscribed from.

    @@ -256,15 +338,17 @@

    The DiscoveryMethod enumeration

    • "any" does not provide any restriction
      • -
    • "local" for discovering Things defined in the same device
    • - "nearby" for discovering Things nearby the device, e.g. by Bluetooth or NFC + "local" for discovering Things defined in the same device
    • "directory" for discovery based on a service provided by a directory or repository of Things
    • - "broadcast" for an open ended discovery based on sending a request to a broadcast address + "nfc" for discovering Things in the device's proximity by using NFC +
      • +
    • + "ble" for discovering Things by using Bluetooth Low Energy (BLE)
    • "other" for a proprietary method defined by the solution. @@ -292,161 +376,28 @@

      The ThingFilter dictionary

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

      - The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, such as a Thing Directory or a Thing. + The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, such as a Thing Directory (if method is "directory") or a Thing (otherwise).

      - The query property represents a query string accepted by the implementation, for instance a SPARQL query. + The query property represents a query string accepted by the implementation, for instance a SPARQL or JSON query.

      - The constraints property represents additional information for the discovery method in the form of a list of sets of property-value pairs (dictionaries). The list elements (dictionaries) are in OR relationship, and within a constraint dictionary the key-value pairs are in AND relationship. Implementations SHOULD make the following mapping from the constraint dictionaries to SemanticAnnotations: for each property-value pair in a constraint dictionary, + The constraints property represents additional information for the discovery method in the form of a list of sets of property-value pairs (dictionaries). The list elements (dictionaries) are in OR relationship, and within a constraint dictionary the key-value pairs are in AND relationship. Implementations SHOULD make the following mapping from the constraint dictionaries to ThingTemplate: for each property-value pair in a constraint dictionary,

      • - Each property name in the constraint dictionary SHOULD match the either the `name` property of a defined SemanticType on the target Thing object, or the name of a Property on the target Thing. + Each property name in the constraint dictionary SHOULD match the name of a Property on the target ThingTemplate.
      • When the name matches, the values are compared. If the values match, the constraint is matched.

      - Constraints are experimental feature, implementations are not required to support them. -

      -

      - Semantic annotations need revisiting in order to simplify their representation. In the [[WOT-TD]] specification they represent the `@type` construct. At the moment only `@context`, `@type` and `@id` constructs are used in the TD. + Queries and constraints are experimental features. Implementations are not required to support them.

    -

    The fetch() method

    -

    - Accepts an url argument and returns a Promise that resolves with a ThingDescription. -

    -
    - -
    -

    The ThingDescription type

    -

    - Representation of the Thing Description, standardized in the [Wot Things Description](https://w3c.github.io/wot-thing-description/) specification. -

    -

    - In this version of the API, Thing Descriptions are represented as opaque strings, denoting a serialized form, for instance JSON or JSON-LD. See [Issue 38](https://github.com/w3c/wot-scripting-api/issues/38) and [Issue 45](https://github.com/w3c/wot-scripting-api/issues/45). -

    -
    - -

    The consume() method

    -

    - Accepts an td argument of type ThingDescription and returns a ConsumedThing object instantiated based on that description. -

    -
    - -

    The produce() method

    -

    - Accepts a model argument of type ThingModel and returns an ExposedThing object, locally created based on the provided initialization parameters. An ExposedThing can be created in the following ways: -

    -
      -
    1. - from an initial model (including a user given name and semantic annotations), then adding properties, actions, events and request handlers; -
      2. -
    2. - from a Thing Description (possibly of a ConsumedThing object), then adding request handlers. -
      3. -
    -
    - -
    -

    The ThingModel type

    -

    - A Thing model is used for producing a new ExposedThing and can be either a ThingTemplate, or a ThingDescription. -

    -
    - -
    -

    The SemanticAnnotations dictionary

    -

    - A dictionary that provides the semantic types and semantic metadata. -

    - 
    -        dictionary SemanticAnnotations {
-            sequence<SemanticType> semanticType;
-            sequence<SemanticMetadata> metadata;
-        };
-
    -

    - The semanticType property denotes a list of SemanticType objects that define the semantic types that can be used in semantic metadata type-value pairs. -

    -

    - The metadata property denotes a list of SemanticMetadata objects (type-value pairs). -

    -
    - -
    -

    The SemanticType dictionary

    - 
    -        dictionary SemanticType {
-            required DOMString name;
-            required USVString context;
-            DOMString prefix;
-        };
-
    -

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

    -
      -
    • - The name attribute represents the name of the semantic type in the given context. -
      • -
    • - The context attribute represents an URL link to the context of the semantic classification. -
      • -
    • - The prefix attribute represents a short prefix associated with a context. -
      • -
    -

    - Semantic type examples to be added. -

    -
    - -
    -

    The SemanticMetadata dictionary

    - 
    -        dictionary SemanticMetadata {
-            SemanticType type;
-            any          value;
-        };
-
    -

    The SemanticMetadata dictionary describes a pair of semantic type and value: -

    -
      -
    • - The type attribute represents the semantic type name defined by a SemanticType object. -
      • -
    • The value attribute represents the metadata value.
      • -
    -
    - -
    -

    The ThingTemplate dictionary

    -

    - A Thing Template is a dictionary that provides a user given name, and the semantic types and semantic metadata attached to the ExposedThing Thing Description's root level. -

    - 
    -        dictionary ThingTemplate: SemanticAnnotations {
-            required DOMString name;
-        };
-
    -

    The ThingTemplate dictionary extends SemanticAnnotations and contains properties to initialize a Thing: -

    -
      -
    • - The name attribute represents the user given name of the Thing. -
      • -
    -

    - Support for configuration and security data might be added later. -

    -
    -

    Examples

             let discoveryFilter = {
@@ -454,7 +405,11 @@ 
    The ThingTemplate dictionary
    
           url: "http://directory.wotservice.org"
         };
         let subscription = wot.discover(discoveryFilter).subscribe(
-          thing => { console.log("Found Thing " + thing.name); },
+          td => {
+            console.log("Found Thing " + td.name);
+            // fetch the TD and create a ConsumedThing
+            let thing = wot.consume(td);
+          },
           error => { console.log("Discovery finished because an error: " + error.message); },
           () => { console.log("Discovery finished successfully");}
         );
@@ -469,24 +424,24 @@ 
    The ThingTemplate dictionary
    
       
    
       
             let subscription = wot.discover({ method: "local" }).subscribe(
-          thing => { console.log("Found local Thing " + thing.name); },
+          td => { console.log("Found local Thing " + td.name); },
           error => { console.log("Discovery error: " + error.message); },
           () => { console.log("Discovery finished successfully");}
         );
       
    
       
             let subscription = wot.discover({ method: "local" }).subscribe({
-          thing => { console.log("Found local Thing " + thing.name); },
+          td => { console.log("Found local Thing " + td.name); },
           error: err => { console.log("Discovery error: " + err.message); },
           complete: () => { console.log("Discovery finished successfully");}
         });
       
    
       
             let subscription = wot.discover({
-          method: "nearby",
-          constraints: [{ protocol: "BLE-4.2" }, { protocol: "NFC"}]
+          method: "ble",
+          constraints: [{ protocol: "BLE-4.2" }]
         }).subscribe(
-          thing => { console.log("Found nearby Thing " + thing.name); },
+          td => { console.log("Found nearby Thing " + td.name); },
           error => { console.log("Discovery error: " + error.message); },
           () => { console.log("Discovery finished successfully");}
         );
@@ -496,7 +451,7 @@ 
    The ThingTemplate dictionary
    
           method: "other",
           constraints: [{ solution: "XYZ123", key: "..."}]
         }).subscribe(
-          thing => { console.log("Found Thing " + thing.name); },
+          td => { console.log("Found Thing " + td.name); },
           error => { console.log("Discovery error: " + error.message); },
           () => { console.log("Discovery finished successfully");}
         );
@@ -510,80 +465,53 @@ 
    The ConsumedThing interface
    
       The ConsumedThing interface is a client API for sending requests to servers in order to retrieve or update Properties, invoke Actions, and observe Properties and Events.
     
    
     
    -      interface ConsumedThing {
-        readonly attribute DOMString name;
-        ThingDescription getThingDescription();
-        Promise<any> readProperty(DOMString name);
-        Promise<void> writeProperty(DOMString name, any value);
-        Promise<any> invokeAction(DOMString name, any parameters);
-        Observable onPropertyChange(DOMString name);
-        Observable onEvent(DOMString name);
-        Observable onTDChange();
+      interface ConsumedThing: ThingTemplate {
+        readonly attribute maplike<DOMString, ThingProperty> properties;
+        readonly attribute maplike<DOMString, ThingAction> actions;
+        readonly attribute maplike<DOMString, ThingEvent> events;
+        sequence<WebLink> links();
+      };
+      ConsumedThing implements Observable;  // for TD changes
+      [NoInterfaceObject]
+      interface Interaction: ThingTemplate {  // abstract class
+        sequence<Form> forms();
+      };
+      interface ThingProperty: Interaction {
+        readonly attribute DataSchema schema;
+        readonly attribute boolean writable;
+        readonly attribute boolean observable;
+        Promise get();
+        Promise set(any value);
+        Observable observe();  // may allow options later
+      };
+      interface ThingAction: Interaction {
+        readonly attribute DataSchema inputSchema;
+        readonly attribute DataSchema outputSchema;
+        Promise run(any parameters);
+      };
+      interface ThingEvent: Interaction {
+        readonly attribute DataSchema schema;
+        readonly attribute any data;
+      };
+      ThingEvent implements Observable;
+      typedef JSON DataSchema;
+      dictionary WebLink {
+        required USVString href;
+        USVString mediaType;
+        DOMString rel;
+        DOMString anchor;
+      };
+      dictionary Form {
+        required USVString href;
+        USVString mediaType;
+        DOMString rel;
+        DOMString security; // TBD
       };
     
    
     
    
       ConsumedThing represents a local proxy object of the remote Thing.
     
    
 
-    
     
    The name property
    
-      
    
-        The `name` property represents the name of the Thing as specified in the TD. In this version it is read only.
-      
    
-    
    
-    
     
    The getThingDescription() method
    
-      
    
-        Returns the Thing Description of the Thing.
-      
    
-      
    
-        In this version, introspection based on TD is out of scope. Parsing and exposing Thing Descriptions is discussed in [Issue 38](https://github.com/w3c/wot-scripting-api/issues/38).
-      
    
-    
    
-
-    
     
    The readProperty() method
    
-      
    
-        Takes the Property name as the name argument, then requests from the underlying platform  and the Protocol Bindings to retrieve the Property on the remote Thing and return the result. Returns a Promise that resolves with the Property value or rejects with an Error.
-      
    
-    
    
-
-    
     
    The writeProperty() method
    
-      
    
-        Takes the Property name as the name argument and the new value as the value argument, then requests from the underlying platform and the Protocol Bindings to update the Property on the remote Thing and return the result. Returns a Promise that resolves on success or rejects with an Error.
-      
    
-    
    
-
-    
     
    The invokeAction() method
    
-      
    
-        Takes the Action name from the name argument and the list of parameters, then requests from the underlying platform and the Protocol Bindings to invoke the Action on the remote Thing and return the result. Returns a Promise that resolves with the return value or rejects with an Error.
-      
    
-    
    
-
-    
     
    The onPropertyChange() method
    
-      
    
-        Returns an Observable for the Property specified in the name argument, allowing subscribing to and unsubscribing from notifications.
-      
    
-      
    
-        The callback function passed to the subscribe() method when invoked on the returned observer will receive the new property value each time it is changed.
-      
    
-    
    
-
-    
     
    The onEvent() method
    
-      
    
-        Returns an Observable for the Event specified in the name argument, allowing subscribing to and unsubscribing from notifications.
-      
    
-      
    
-        The callback function passed to the subscribe() method when invoked on the returned observer will receive the event data each time the event is fired.
-      
    
-    
    
-
-    
     
    The onTDChange() method
    
-      
    
-        Returns an Observable, allowing subscribing to and unsubscribing from notifications to the Thing Description.
-      
    
-      
    
-        The callback function passed to the subscribe() method when invoked on the returned observer will receive the new Thing Description each time it is changed.
-      
    
-    
    
-
     
    
       
    Examples
    
       
    
@@ -591,14 +519,14 @@ 
    Examples
    
       
    
       
             try {
-          let td = await wot.fetch("http://mmyservice.org/mySensor");
+          let td = await wot.discover({ url: "http://mmyservice.org/mySensor"});
           let thing = wot.consume(td);
           console.log("Thing " + thing.name + " has been consumed.");
           let subscription = thing.onPropertyChange("temperature")
             .subscribe(function(value) {
               console.log("Temperature + " has changed to " + value);
             });
-          thing.invokeAction("startMeasurement", { units: "Celsius" })
+          thing.actions["startMeasurement"].run({ units: "Celsius" })
             .then(() => { console.log("Temperature measurement started."); })
             .catch(e => {
                console.log("Error starting measurement.");
@@ -623,17 +551,17 @@ 
    The ExposedThing interface
    
       ExposedThing implements ConsumedThing;
       interface ExposedThing {
         // define how to expose and run the Thing
-        Promise<void> start();
-        Promise<void> stop();
+        Promise<void> expose();
+        Promise<void> destroy();
         Promise<void> register(optional USVString directory);
         Promise<void> unregister(optional USVString directory);
         Promise<void> emitEvent(DOMString eventName, any payload);
         // define Thing Description modifiers
-        ExposedThing addProperty(ThingProperty property);
+        ExposedThing addProperty(ThingPropertyInit property);
         ExposedThing removeProperty(DOMString name);
-        ExposedThing addAction(ThingAction action);
+        ExposedThing addAction(ThingActionInit action);
         ExposedThing removeAction(DOMString name);
-        ExposedThing addEvent(ThingEvent event);
+        ExposedThing addEvent(ThingEventInit event);
         ExposedThing removeEvent(DOMString name);
         // define request handlers
         ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
@@ -645,27 +573,27 @@ 
    The ExposedThing interface
    
       callback ActionHandler = Promise<any>(any parameters);
     
    
 
-    
     
    The start() method
    
+    
     
    The expose() method
    
       
    
         Start serving external requests for the Thing.
       
    
     
    
 
-    
     
    The stop() method
    
+    
     
    The register() method
    
       
    
-        Stop serving external requests for the Thing.
+        Generates the Thing Description given the properties, Actions and Event defined for this object. If a directory argument is given, make a request to register the Thing Description with the given WoT repository by invoking its register Action.
       
    
     
    
 
-    
     
    The register() method
    
+    
     
    The unregister() method
    
       
    
-        Generates the Thing Description given the properties, Actions and Event defined for this object. If a directory argument is given, make a request to register the Thing Description with the given WoT repository by invoking its register Action.
+        If a directory argument is given, make a request to unregister the Thing Description with the given WoT repository by invoking its unregister Action.
       
    
     
    
 
-    
     
    The unregister() method
    
+    
     
    The destroy() method
    
       
    
-        If a directory argument is given, make a request to unregister the Thing Description with the given WoT repository by invoking its unregister Action. Then, and in the case no arguments were provided to this function, stop the Thing and remove the Thing Description.
+        Stop serving external requests for the Thing and destroy the object. Note that eventual unregistering should be done before invoking this method.
       
    
     
    
 
@@ -692,11 +620,10 @@ 
    The DataSchema type
    
       
    
         Adds a Property defined by the argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
    
-      
    
-        
    The ThingProperty dictionary
    
+      
    
+        
    The ThingPropertyInit dictionary
    
         
    -          dictionary ThingProperty: SemanticAnnotations {
-            required DOMString name;
+          dictionary ThingPropertyInit: ThingTemplate {
             required DataSchema schema;
             any value;
             boolean writable = false;
@@ -707,7 +634,9 @@ 
    The ThingProperty dictionary
    
           Represents the Thing Property description.
         
    
         
      
-          
    • The name attribute represents the name of the Property.
      • 
+          
    • 
+            The name attribute represents the name of the Property.
+          
      • 
           
    • 
             The schema attribute represents the data type for the Property described by DataSchema.
           
      • 
@@ -732,11 +661,10 @@ 
      The ThingProperty dictionary
      
       
      
         Adds an Action to the Thing object as defined by the action argument of type ThingAction and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
      
-      
      
-        
      The ThingAction dictionary
      
+      
      
+        
      The ThingActionInit dictionary
      
         
      -          dictionary ThingAction: SemanticAnnotations {
-            required DOMString name;
+          dictionary ThingActionInit: ThingTemplate {
             DataSchema inputSchema;
             DataSchema outputSchema;
           };
@@ -745,9 +673,15 @@ 
      The ThingAction dictionary
      
         The ThingAction dictionary describes the arguments and the return value.
       
      
         
        
-          
      • The name attribute provides the Action name.
        • 
-          
      • The inputSchema attribute provides the description of the input arguments (argument list is represented by an object). If missing, it means the action does not accept arguments.
        • 
-          
      • The outputSchema attribute provides the description of the returned data. If missing, it means the action does not return data.
        • 
+          
      • 
+            The name attribute provides the Action name.
+          
        • 
+          
      • 
+            The inputSchema attribute provides the description of the input arguments (argument list is represented by an object). If missing, it means the action does not accept arguments.
+          
        • 
+          
      • 
+            The outputSchema attribute provides the description of the returned data. If missing, it means the action does not return data.
+          
        • 
         
      
       
      
     
       
@@ -762,16 +696,16 @@ 
      The ThingAction dictionary
      
       
      
         Adds an event to the Thing object as defined by the event argument of type ThingEvent and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
      
-      
      
-        
      The ThingEvent dictionary
      
+      
      
+        
      The ThingEventInit dictionary
      
         
      -          dictionary ThingEvent: SemanticAnnotations {
+          dictionary ThingEventInit: ThingTemplate {
             required DOMString name;
             DataSchema schema;
           };
         
      
         
        
-          
      • The name attribute represents the event name.
        • 
+          
      • The name attribute represents the event name.
        • 
           
      • The schema attribute represents the type of the data that is attached to the event. If missing, it means the event does not carry data.
        • 
         
      
       
      
@@ -928,71 +862,6 @@ 
      Examples
      
     
       
   
     
 
-  
    
-    
    Experimental extensions to the ConsumedThing interface
    
-    
    
-      The ThingDescription related functionality, such as enumerating Properties, Actions, Events and links (introspection) is an API extension that is out of scope for this specification. However, the draft interfaces are defined here for informative purposes.
-    
    
-    
    -      partial interface ConsumedThing {
-        sequence<ThingProperty> getProperties();
-        sequence<ThingAction> getActions();
-        sequence<ThingEvent> getEvents();
-        sequence<TDLink> getLinks();
-      };
-    
    
-
-    
     
    The getProperties() method
    
-      
    
-        Returns the list of Properties defined in the Thing Description of the Thing in the form of a list of ThingProperty objects.
-      
    
-    
    
-
-    
     
    The getActions() method
    
-      
    
-        Returns the list of Actions defined in the Thing Description of the Thing in the form of a list of ThingAction objects.
-      
    
-    
    
-
-    
     
    The getEvents() method
    
-      
    
-        Returns the list of Events defined in the Thing Description of the Thing in the form of a list of ThingEvent objects.
-      
    
-    
    
-
-    
     
    The getLinks() method
    
-      
    
-        Returns the list of linked resources in Thing Description of the Thing in the form of a list of TDLink objects.
-      
    
-      
    
-        
    The TDLink dictionary
    
-        
    
-          Contains a hyperlink reference, a relation type and a media type.
-        
    
-        
    -          dictionary TDLink {
-              required USVString href;
-              USVString mediaType;
-              DOMString rel;
-          };
-        
    
-        
    The TDLink dictionary contains the following properties:
-        
    
-        
      
-          
    • 
-            The href attribute represents a hyperlink reference.
-          
      • 
-          
    • 
-            The rel attribute represents a relation type.
-          
      • 
-          
    • 
-            The mediaType attribute represents a IANA media type. For TDs there will be registered media types, so applications will be able to check whether an `href` link points to a TD, i.e. whether the link is fetcheable with this API.
-          
      • 
-        
    
-      
     
-    
    
-  
    
-
   
    
     
    Observables
    
     
    
@@ -1214,7 +1083,7 @@ 
    The Observable interface
    
     
    
       
      
         
    • 
-          Synchronized the Scripting API with the [Thing Description specification](https://w3c.github.io/wot-thing-description/). Defined ThingDescription, ThingTemplate, SemanticAnnotations, SemanticType, SemanticMetadata, input and output data descriptions, etc.
+          Synchronized the Scripting API with the [Thing Description specification](https://w3c.github.io/wot-thing-description/). Defined ThingDescription, ThingTemplate, ThingMetadata, SemanticType, SemanticMetadata, input and output data descriptions, etc.
         
      • 
         
    • 
           Separated consume() to fetch() and consume().

From c8e52f96a52b8e35810313c0ece9df0e942f4b05 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Mon, 7 May 2018 10:49:31 +0300
Subject: [PATCH 205/464] Update WebIDL according to newest TD spec

Signed-off-by: Zoltan Kis 
---
 index.html | 211 +++++++++++++++++++++++++++++------------------------
 1 file changed, 117 insertions(+), 94 deletions(-)

diff --git a/index.html b/index.html
index b5ba38de..f5dbe289 100644
--- a/index.html
+++ b/index.html
@@ -244,41 +244,61 @@ 
      The WoT object
      
       The algorithms for the WoT methods will be specified later, including error handling and security considerations.
     
      
 
+    
      
+    
      The ThingDescription type
      
+      
      
+        Serialized representation of the Thing Description (a JSON-LD document).
+      
      
+      
      
+        In this version of the API, Thing Descriptions are represented as an opaque `USVString` that can be transmitted between devices.
+      
      
+    
      
+
     
      
       
      The ThingTemplate dictionary
      
       
      
-        A `ThingTemplate` is a dictionary that provides Thing related semantic metadata.
+        A `ThingTemplate` is a dictionary that provides Thing related semantic metadata used for initializing a Thing Description as defined in [[!WOT-TD]].
       
      
       
      -        typedef (object or USVString or sequence<USVString>) JsonLdDefinition;
-        interface ThingTemplate {
-          getter JsonLdDefinition (USVString name);
-          setter void (USVString name, JsonLdDefinition value);
-        };
+        typedef (object or USVString or sequence<USVString>) TDValue;
+        typedef Dictionary ThingTemplate;
+        // interface ThingTemplate {
+        //  getter TDValue (DOMString name);
+        //  setter void (DOMString name, TDValue value);
+        // };
       
      
       
      
-        The JsonLdDefinition type can be either a JSON object, a string representing an IRI, or an array of strings.
+        The TDValue type can be either a JSON object, a string representing an IRI, or an array of strings, as defined in [[!WOT-TD]].
       
      
-      
      The ThingTemplate dictionary initializes a Thing:
+      
      The ThingTemplate dictionary initializes a Thing as defined in [[!WOT-TD]]:
       
      
       
        
         
      • 
-          The @context attribute represents a semantic context as USVString.
+          The name mandatory attribute represents the name of the Thing as DOMString.
+        
        • 
+        
      • 
+          The id optional attribute represents a unique identifier of the Thing, typically a URI, IRI, or URN as USVString. Note that this is not the same as the JSON-LD `@id` attribute.
         
        • 
         
      • 
-          The @type attribute represents a semantic type as USVString.
+          The base optional attribute represents a base URL as USVString.
         
        • 
         
      • 
-          The @id attribute represents an identifier, typically a URI, IRI, or URN as USVString.
+          The description optional attribute of type DOMString represents a human readable description of the Thing.
         
        • 
         
      • 
-          The base attribute represents a base URL as USVString.
+          The support optional attribute of type DOMString represents human readable information about the TD maintainer.
         
        • 
         
      • 
-          The name attribute represents a user given name as DOMString.
+          The security optional attribute represents security metadata defined by the Security dictionary;
         
        • 
         
      • 
-          Apart from the core semantic properties defined above, others may also be defined on a Thing, for instance "gms:COVParams" (with namespace definition), or "iotschema:unit" etc.
+          The @context optional attribute represents a semantic context as USVString.
+        
        • 
+        
      • 
+          The @type optional attribute represents a semantic type as USVString.
+        
        • 
+        
      • 
+          Apart from the core semantic properties defined above, others may also be defined on a Thing, for instance `@id`, "gms:COVParams" (with namespace definition), or "iotschema:unit" etc.
         
        • 
       
      
       
      
@@ -286,38 +306,28 @@ 
      The ThingTemplate dictionary
      
       
      
     
       
 
-    
      
-    
      The ThingDescription type
      
-      
      
-        Representation of the Thing Description, standardized in the [Wot Things Description](https://w3c.github.io/wot-thing-description/) specification.
-      
      
-      
      
-        In this version of the API, Thing Descriptions are represented as an opaque `USVString` representing a serialized TD.
-      
      
-    
      
-
     
       
       The fetch() method
      
       
      
-        Accepts an url argument of type `USVString` and returns a Promise that resolves with a ThingDescription.
+        Accepts an url argument of type `USVString` that represents a URL (e.g. `file://` or `https://`) and returns a Promise that resolves with a ThingDescription (a serialized JSON-LD document of type `USVString`).
       
      
     
      
 
     
       
       The consume() method
      
       
      
-        Accepts an td argument of type ThingDescription and returns a ConsumedThing object instantiated based on that description.
+        Accepts an td argument of type ThingDescription and returns a ConsumedThing object instantiated based on parsing that description.
       
      
     
      
 
     
       
      The produce() method
      
       
      
-        Accepts a model argument of type ThingTemplate and returns an ExposedThing object, locally created based on the provided initialization parameters. An ExposedThing can be created in the following ways:
+        Accepts a model argument of type ThingModel and returns an ExposedThing object. An ExposedThing can be created in the following ways:
       
      
       
        
         
      1. 
-          from an initial model (including a user given name and semantic metadata properties), then adding Properties, Actions, Events and request handlers;
+          from a ThingTemplate, then adding Properties, Actions, Events and request handlers;
         
        2. 
         
      2. 
-          from a Thing Description (possibly of a ConsumedThing object), then adding request handlers.
+          from a Thing Description or a ConsumedThing object, then adding request handlers.
         
        3. 
       
      
     
       
@@ -350,9 +360,6 @@ 
      The DiscoveryMethod enumeration
      
           
    • 
             "ble" for discovering Things by using Bluetooth Low Energy (BLE)
           
      • 
-          
    • 
-            "other" for a proprietary method defined by the solution.
-          
      • 
         
    
       
    
 
@@ -370,28 +377,28 @@ 
    The ThingFilter dictionary
    
           };
         
    
         
    
-          The method property represents the discovery type that should be used in the discovery process. The possible values are defined by the DiscoveryMethod enumeration that can be extended by string values defined by solutions (with no guarantee of interoperability).
-        
    
-        
    
-          The DiscoveryMethod enumeration can be extended by the Thing Description with values that are not specified here. This extensibility of DiscoveryMethod by proprietary or private methods is a working assumption until consensus is formed and may be removed later.
+          The method property represents the discovery type that should be used in the discovery process. The possible values are defined by the DiscoveryMethod enumeration that MAY be extended by string values defined by solutions (with no guarantee of interoperability).
         
    
         
    
-          The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, such as a Thing Directory (if method is "directory") or a Thing (otherwise).
+          The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, for instance a Thing Directory (if method is "directory") or a Thing (otherwise).
         
    
         
    
           The query property represents a query string accepted by the implementation, for instance a SPARQL or JSON query.
         
    
         
    
-          The constraints property represents additional information for the discovery method in the form of a list of sets of property-value pairs (dictionaries). The list elements (dictionaries) are in OR relationship, and within a constraint dictionary the key-value pairs are in AND relationship. Implementations SHOULD make the following mapping from the constraint dictionaries to ThingTemplate: for each property-value pair in a constraint dictionary,
+          The constraints property represents additional information for the discovery method in the form of a list of sets of property-value pairs (dictionaries). The list elements (dictionaries) are in OR relationship, and within a constraint dictionary the key-value pairs are in AND relationship. Implementations SHOULD make the following mapping from the constraint dictionaries to ThingTemplate.
         
    
-        
      
+        
      
+          For each property-value pair in a constraint dictionary,
+          
        
           
      • 
             Each property name in the constraint dictionary SHOULD match the name of a Property on the target ThingTemplate.
           
        • 
           
      • 
             When the name matches, the values are compared. If the values match, the constraint is matched.
           
        • 
-        
      
+          
    
+        
    
         
    
           Queries and constraints are experimental features. Implementations are not required to support them.
         
    
@@ -448,8 +455,9 @@ 
    The ThingFilter dictionary
    
       
             let subscription = wot.discover({
-          method: "other",
-          constraints: [{ solution: "XYZ123", key: "..."}]
+          method: "myOwnMethod", // not standardized
+          url: myDirectoryURL,
+          constraints: [{ account: "XYZ123", key: "..."}]
         }).subscribe(
           td => { console.log("Found Thing " + td.name); },
           error => { console.log("Discovery error: " + error.message); },
@@ -469,43 +477,74 @@ 
    The ConsumedThing interface
    
         readonly attribute maplike<DOMString, ThingProperty> properties;
         readonly attribute maplike<DOMString, ThingAction> actions;
         readonly attribute maplike<DOMString, ThingEvent> events;
-        sequence<WebLink> links();
+        readonly attribute FrozenArray<WebLink> links;
       };
       ConsumedThing implements Observable;  // for TD changes
       [NoInterfaceObject]
-      interface Interaction: ThingTemplate {  // abstract class
-        sequence<Form> forms();
+      interface Interaction {  // abstract class
+        readonly attribute FrozenArray<Form> forms;
+      };
+      enum JSONType { "boolean", "number", "string", "null", "object", "array" };
+      typedef (unsigned long or unrestricted double) Number;
+      dictionary PropertyTemplate {
+        DOMString label;
+        boolean writable = false;
+        boolean observable = false;
+        boolean const;  // TBD
+        boolean required;
+      };
+      dictionary SimplePropertyInit: PropertyTemplate {
+        required DOMString type;  // null, boolean, string
+        any value;
+      };
+      dictionary NumberPropertyInit: PropertyTemplate {
+        DOMString type = "number";
+        Number value;
+        Number minimum;
+        Number maximum;
       };
-      interface ThingProperty: Interaction {
-        readonly attribute DataSchema schema;
-        readonly attribute boolean writable;
-        readonly attribute boolean observable;
-        Promise get();
+      dictionary ObjectPropertyInit: PropertyTemplate {
+        DOMString type = "object";
+        object value;
+      };
+      dictionary ArrayPropertyInit: PropertyTemplate {
+        DOMString type = "array";
+        sequence<any> value;
+        unsigned long minItems;
+        unsigned long maxItems;
+      };
+      typedef (SimplePropertyInit or NumberPropertyInit or ObjectPropertyInit or ArrayPropertyInit) PropertyInit;
+      interface ThingProperty: PropertyTemplate {
+        readonly attribute DOMString type;
+        Promise<any> get();
         Promise set(any value);
-        Observable observe();  // may allow options later
+      };
+      ThingProperty implements Observable;
+      dictionary ActionInit {
+        PropertyInit input;
+        PropertyInit output;
+        DOMString description;
+        DOMString label;
       };
       interface ThingAction: Interaction {
-        readonly attribute DataSchema inputSchema;
-        readonly attribute DataSchema outputSchema;
-        Promise run(any parameters);
+        readonly attribute PropertyInit input;
+        readonly attribute PropertyInit output;
+        readonly attribute DOMString description;
+        readonly attribute DOMString label;
+        Promise run();
       };
-      interface ThingEvent: Interaction {
-        readonly attribute DataSchema schema;
-        readonly attribute any data;
+      interface ThingEvent : ThingProperty {
       };
-      ThingEvent implements Observable;
-      typedef JSON DataSchema;
-      dictionary WebLink {
+      dictionary Link {
         required USVString href;
         USVString mediaType;
         DOMString rel;
-        DOMString anchor;
       };
-      dictionary Form {
-        required USVString href;
-        USVString mediaType;
-        DOMString rel;
-        DOMString security; // TBD
+      dictionary WebLink: Link {
+        USVString anchor;
+      };
+      dictionary Form: Link {
+        DOMString security;
       };

    @@ -519,7 +558,7 @@

    Examples

             try {
-          let td = await wot.discover({ url: "http://mmyservice.org/mySensor"});
+          let td = await wot.discover({ url: "http://mmyservice.org/myDirectory"});
           let thing = wot.consume(td);
           console.log("Thing " + thing.name + " has been consumed.");
           let subscription = thing.onPropertyChange("temperature")
@@ -544,9 +583,6 @@ 
    The ExposedThing interface
    
     
    
       The ExposedThing interface is the server API that allows defining request handlers, properties, Actions, and Events to a Thing. It also implements the ConsumedThing interface. An ExposedThing is created by the produce() method.
     
    
-    
    
-      It is under consideration to use a constructor for ExposedThing instead of a factory method.
-    
    
     
           ExposedThing implements ConsumedThing;
       interface ExposedThing {
@@ -557,11 +593,11 @@ 
    The ExposedThing interface
    
         Promise<void> unregister(optional USVString directory);
         Promise<void> emitEvent(DOMString eventName, any payload);
         // define Thing Description modifiers
-        ExposedThing addProperty(ThingPropertyInit property);
+        ExposedThing addProperty(ThingProperty property);
         ExposedThing removeProperty(DOMString name);
-        ExposedThing addAction(ThingActionInit action);
+        ExposedThing addAction(ThingAction action);
         ExposedThing removeAction(DOMString name);
-        ExposedThing addEvent(ThingEventInit event);
+        ExposedThing addEvent(ThingEvent event);
         ExposedThing removeEvent(DOMString name);
         // define request handlers
         ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
@@ -603,19 +639,6 @@ 
    The ExposedThing interface
    -
    -

    The DataSchema type

    - 
    -        typedef USVString DataSchema;
-
    -

    - The DataSchema type represents a data type specified in the Thing Description in a serialized form. -

    -

    - DataSchema is under development, currently it can denote any type supported by the Thing Description and the WoT Runtime. -

    -
    -

    The addProperty() method

    Adds a Property defined by the argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining. @@ -624,10 +647,10 @@

    The DataSchema type

    The ThingPropertyInit dictionary

               dictionary ThingPropertyInit: ThingTemplate {
-            required DataSchema schema;
-            any value;
+            required TDValueType schema;
             boolean writable = false;
             boolean observable = false;
+            any value;
           };

    @@ -638,7 +661,7 @@

    The ThingPropertyInit dictionary

    The name attribute represents the name of the Property.
  • - The schema attribute represents the data type for the Property described by DataSchema. + The schema attribute represents the data type for the Property described by TDValueType.
  • The value attribute represents the value of the Property.
  • @@ -665,8 +688,8 @@

    The ThingPropertyInit dictionary

    The ThingActionInit dictionary

               dictionary ThingActionInit: ThingTemplate {
-            DataSchema inputSchema;
-            DataSchema outputSchema;
+            TDValueType inputSchema;
+            TDValueType outputSchema;
           };

    @@ -701,7 +724,7 @@

    The ThingEventInit dictionary

               dictionary ThingEventInit: ThingTemplate {
             required DOMString name;
-            DataSchema schema;
+            TDValueType schema;
           };
      @@ -948,7 +971,7 @@

      The Observable interface

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

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

      The terms URL and @@ -1119,7 +1142,7 @@

      The Observable interface

      Security related metadata (https://github.com/w3c/wot-scripting-api/issues/91).
    • - Defining DataSchema better (https://github.com/w3c/wot-scripting-api/issues/89). + Defining TDValueType better (https://github.com/w3c/wot-scripting-api/issues/89).
    • Providing Protocol Binding for ExposedThing (https://github.com/w3c/wot-scripting-api/issues/45). From 0ba0981f85416bd9475681f9a3199882941a28b3 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Tue, 8 May 2018 17:07:58 +0300 Subject: [PATCH 206/464] Move data definitions to separate sections. Remove discovery constraints. Signed-off-by: Zoltan Kis --- index.html | 90 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 46 insertions(+), 44 deletions(-) diff --git a/index.html b/index.html index f5dbe289..63a7f055 100644 --- a/index.html +++ b/index.html @@ -232,8 +232,14 @@

      The WoT object

      ConsumedThing consume(ThingDescription td); ExposedThing produce(ThingModel model); }; + typedef (ThingInit or ThingDescription or ConsumedThing) ThingModel; typedef USVString ThingDescription; - typedef (ThingTemplate or ThingDescription or ConsumedThing) ThingModel; + typedef Dictionary ThingInit; + typedef (object or USVString or sequence<USVString>) TDValue; + interface ThingTemplate { + getter TDValue (DOMString name); + setter void (DOMString name, TDValue value); + };

      @@ -254,23 +260,22 @@

      The ThingDescription type

    • +
    +

    The ThingInit dictionary

    +

    + `ThingInit` is a dictionary used for initializing a ThingTemplate. +

    +
    +
    -

    The ThingTemplate dictionary

    +

    The ThingTemplate interface

    - A `ThingTemplate` is a dictionary that provides Thing related semantic metadata used for initializing a Thing Description as defined in [[!WOT-TD]]. + `ThingTemplate` is an abstract interface that defines Thing related semantic metadata used for initializing a Thing Description as defined in [[!WOT-TD]]. The properties are of type TDValue.

    - 
    -        typedef (object or USVString or sequence<USVString>) TDValue;
-        typedef Dictionary ThingTemplate;
-        // interface ThingTemplate {
-        //  getter TDValue (DOMString name);
-        //  setter void (DOMString name, TDValue value);
-        // };
-

    The TDValue type can be either a JSON object, a string representing an IRI, or an array of strings, as defined in [[!WOT-TD]].

    -

    The ThingTemplate dictionary initializes a Thing as defined in [[!WOT-TD]]: +

    The ThingInit dictionary initializes a ThingTemplate using the following attributes.

    • @@ -335,7 +340,7 @@

      The ThingTemplate dictionary

      The discover() method

      Starts the discovery process that will provide ThingDescriptions that match the optional argument ThingFilter. When the argument is not provided, uses all supported discovery methods. - Returns an [Observable](https://github.com/tc39/proposal-observable) object that can be subscribed to and unsubscribed from. + Returns an [Observable](https://github.com/tc39/proposal-observable) object that can be subscribed to and unsubscribed from. Errors are also signaled at the subscription object.

      @@ -373,7 +378,6 @@

      The ThingFilter dictionary

      DiscoveryMethod method = "any"; USVString url; USVString query; - sequence<Dictionary> constraints; };

      @@ -383,26 +387,15 @@

      The ThingFilter dictionary

      The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, for instance a Thing Directory (if method is "directory") or a Thing (otherwise).

      - The query property represents a query string accepted by the implementation, for instance a SPARQL or JSON query. -

      -

      - The constraints property represents additional information for the discovery method in the form of a list of sets of property-value pairs (dictionaries). The list elements (dictionaries) are in OR relationship, and within a constraint dictionary the key-value pairs are in AND relationship. Implementations SHOULD make the following mapping from the constraint dictionaries to ThingTemplate. -

      -

      - For each property-value pair in a constraint dictionary, -

        -
      • - Each property name in the constraint dictionary SHOULD match the name of a Property on the target ThingTemplate. -
        • -
      • - When the name matches, the values are compared. If the values match, the constraint is matched. -
        • -
      + The query property represents a query string accepted by the implementation, for instance a SPARQL or JSON query. Support may be implemented locally in the WoT Runtime or remotely as a service in a Thing Directory.

      - Queries and constraints are experimental features. Implementations are not required to support them. + Queries are experimental features. Implementations are not required to support them.

      +

      + If queries are specified, but not supported, implementations should signal a `NotSupportedError` on the subscription objects. For security errors (e.g. authentication error) a `SecurityError` should be signaled. For query validation errors a `TypeError` should be signaled. For other errors an `Error` should be signaled. +

      Examples

      @@ -467,23 +460,12 @@

      The ThingFilter dictionary

    -
    -

    The ConsumedThing interface

    +
    +

    Data types used in a Thing

    - The ConsumedThing interface is a client API for sending requests to servers in order to retrieve or update Properties, invoke Actions, and observe Properties and Events. + Every Thing describes its metadata as defined in ThingTemplate, and basic interactions as defined in ConsumedThing: Properties, Actions and Events. The following data types are used for representing these interactions, as defined in [[!WOT-TD]]. 

    -      interface ConsumedThing: ThingTemplate {
-        readonly attribute maplike<DOMString, ThingProperty> properties;
-        readonly attribute maplike<DOMString, ThingAction> actions;
-        readonly attribute maplike<DOMString, ThingEvent> events;
-        readonly attribute FrozenArray<WebLink> links;
-      };
-      ConsumedThing implements Observable;  // for TD changes
-      [NoInterfaceObject]
-      interface Interaction {  // abstract class
-        readonly attribute FrozenArray<Form> forms;
-      };
       enum JSONType { "boolean", "number", "string", "null", "object", "array" };
       typedef (unsigned long or unrestricted double) Number;
       dictionary PropertyTemplate {
@@ -535,6 +517,26 @@ 
    The ConsumedThing interface
    
       };
       interface ThingEvent : ThingProperty {
       };
+
    +
    + +
    +

    The ConsumedThing interface

    +

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

    + 
    +      interface ConsumedThing: ThingTemplate {
+        readonly attribute maplike<DOMString, ThingProperty> properties;
+        readonly attribute maplike<DOMString, ThingAction> actions;
+        readonly attribute maplike<DOMString, ThingEvent> events;
+        readonly attribute FrozenArray<WebLink> links;
+      };
+      ConsumedThing implements Observable;  // for TD changes
+      [NoInterfaceObject]
+      interface Interaction {  // abstract class
+        readonly attribute FrozenArray<Form> forms;
+      };
       dictionary Link {
         required USVString href;
         USVString mediaType;

From c103157a282f02b9675ec914a316a715e52d1f89 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Wed, 9 May 2018 19:21:51 +0300
Subject: [PATCH 207/464] Refactor type system. Add templates for discovery.
 Reorganize sections. Fix some of the examples.

Signed-off-by: Zoltan Kis 
---
 index.html | 234 ++++++++++++++++++++---------------------------------
 1 file changed, 89 insertions(+), 145 deletions(-)

diff --git a/index.html b/index.html
index 63a7f055..ddd1160a 100644
--- a/index.html
+++ b/index.html
@@ -232,14 +232,9 @@ 
    The WoT object
    
         ConsumedThing consume(ThingDescription td);
         ExposedThing produce(ThingModel model);
       };
-      typedef (ThingInit or ThingDescription or ConsumedThing) ThingModel;
       typedef USVString ThingDescription;
-      typedef Dictionary ThingInit;
-      typedef (object or USVString or sequence<USVString>) TDValue;
-      interface ThingTemplate {
-        getter TDValue (DOMString name);
-        setter void (DOMString name, TDValue value);
-       };
+      typedef dictionary ThingTemplate;
+      typedef (ThingTemplate or ThingDescription or ConsumedThing) ThingModel;

    @@ -260,22 +255,10 @@

    The ThingDescription type

    -
    -

    The ThingInit dictionary

    -

    - `ThingInit` is a dictionary used for initializing a ThingTemplate. -

    -
    -
    -

    The ThingTemplate interface

    +

    The ThingTemplate dictionary

    - `ThingTemplate` is an abstract interface that defines Thing related semantic metadata used for initializing a Thing Description as defined in [[!WOT-TD]]. The properties are of type TDValue. -

    -

    - The TDValue type can be either a JSON object, a string representing an IRI, or an array of strings, as defined in [[!WOT-TD]]. -

    -

    The ThingInit dictionary initializes a ThingTemplate using the following attributes. + `ThingTemplate` is a dictionary used for initializing a Thing. It contains properties representing semantic metadata and interactions (Properties, Actions and Events) used for initializing a Thing Description as defined in [[!WOT-TD]].

    • @@ -296,6 +279,15 @@

      The ThingTemplate interface

    • The security optional attribute represents security metadata defined by the Security dictionary;
      • +
    • + The properties optional attribute represents a dictionary with keys that correspond to Property names and values of type PropertyInit. +
      • +
    • + The actions optional attribute represents a dictionary with keys that correspond to Action names and values of type ActionInit. +
      • +
    • + The events optional attribute represents a dictionary with keys that correspond to Event names and values of type EventInit. +
    • The @context optional attribute represents a semantic context as USVString.
      • @@ -378,6 +370,7 @@

      The ThingFilter dictionary

      DiscoveryMethod method = "any"; USVString url; USVString query; + ThingTemplate template; };

      @@ -389,8 +382,11 @@

      The ThingFilter dictionary

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

      +

      + The template property represents a ThingTemplate dictionary used for matching against discovered Things. +

      - Queries are experimental features. Implementations are not required to support them. + Queries and templates are experimental features. Implementations are not required to support them. The template matching algorithm will be defined later, but there are two possibilities: either direct matching (property to property) or serializing the template and matching that against TDs.

    @@ -465,10 +461,39 @@

    Data types used in a Thing

    Every Thing describes its metadata as defined in ThingTemplate, and basic interactions as defined in ConsumedThing: Properties, Actions and Events. The following data types are used for representing these interactions, as defined in [[!WOT-TD]].

    +

    Links and Forms

    + 
    +      [NoInterfaceObject]
+      dictionary Link {
+        required USVString href;
+        USVString mediaType;
+        DOMString rel;
+      };
+      dictionary WebLink: Link {
+        USVString anchor;
+      };
+      dictionary Form: Link {
+        DOMString security;
+      };
+
    +
    +

    The Interaction interface

    + 
    +      interface Interaction {  // abstract class
+        readonly attribute DOMString name;
+        readonly attribute FrozenArray<Form> forms;
+      };
+      dictionary InteractionInit {
+        DOMString name;
+        sequence<Form> forms;
+      };
+
    +
    +

    Properties

           enum JSONType { "boolean", "number", "string", "null", "object", "array" };
       typedef (unsigned long or unrestricted double) Number;
-      dictionary PropertyTemplate {
+      dictionary PropertyTemplate: InteractionInit {
         DOMString label;
         boolean writable = false;
         boolean observable = false;
@@ -496,28 +521,38 @@ 
    Data types used in a Thing
    
         unsigned long maxItems;
       };
       typedef (SimplePropertyInit or NumberPropertyInit or ObjectPropertyInit or ArrayPropertyInit) PropertyInit;
-      interface ThingProperty: PropertyTemplate {
+      interface ThingProperty: Interaction {
         readonly attribute DOMString type;
         Promise<any> get();
         Promise set(any value);
       };
       ThingProperty implements Observable;
-      dictionary ActionInit {
+
    +
    +

    Actions

    + 
    +      dictionary ActionInit: InteractionInit {
+        DOMString label;
         PropertyInit input;
         PropertyInit output;
         DOMString description;
-        DOMString label;
       };
       interface ThingAction: Interaction {
         readonly attribute PropertyInit input;
         readonly attribute PropertyInit output;
         readonly attribute DOMString description;
         readonly attribute DOMString label;
-        Promise run();
+        Promise<any> run();
       };
+
    +
    +

    Events

    + 
           interface ThingEvent : ThingProperty {
       };
+      typedef PropertyInit EventInit;
    +
    @@ -526,28 +561,15 @@

    The ConsumedThing interface

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

    -      interface ConsumedThing: ThingTemplate {
+      interface ConsumedThing {
         readonly attribute maplike<DOMString, ThingProperty> properties;
         readonly attribute maplike<DOMString, ThingAction> actions;
         readonly attribute maplike<DOMString, ThingEvent> events;
         readonly attribute FrozenArray<WebLink> links;
+        // getter for ThingTemplate properties
+        getter any(DOMString name);
       };
       ConsumedThing implements Observable;  // for TD changes
-      [NoInterfaceObject]
-      interface Interaction {  // abstract class
-        readonly attribute FrozenArray<Form> forms;
-      };
-      dictionary Link {
-        required USVString href;
-        USVString mediaType;
-        DOMString rel;
-      };
-      dictionary WebLink: Link {
-        USVString anchor;
-      };
-      dictionary Form: Link {
-        DOMString security;
-      };

    ConsumedThing represents a local proxy object of the remote Thing. @@ -560,21 +582,26 @@

    Examples

             try {
-          let td = await wot.discover({ url: "http://mmyservice.org/myDirectory"});
-          let thing = wot.consume(td);
-          console.log("Thing " + thing.name + " has been consumed.");
-          let subscription = thing.onPropertyChange("temperature")
-            .subscribe(function(value) {
-              console.log("Temperature + " has changed to " + value);
-            });
-          thing.actions["startMeasurement"].run({ units: "Celsius" })
-            .then(() => { console.log("Temperature measurement started."); })
-            .catch(e => {
-               console.log("Error starting measurement.");
-               subscription.unsubscribe();
-             })
+          let subscription = wot.discover({ method: "local" }).subscribe(
+            td => {
+              let thing = wot.consume(td);
+              console.log("Thing " + thing.name + " has been consumed.");
+              let subscription = thing.onPropertyChange("temperature")
+                .subscribe(function(value) {
+                  console.log("Temperature + " has changed to " + value);
+                });
+              thing.actions["startMeasurement"].run({ units: "Celsius" })
+                .then(() => { console.log("Temperature measurement started."); })
+                .catch(e => {
+                   console.log("Error starting measurement.");
+                   subscription.unsubscribe();
+                 })
+            },
+            error => { console.log("Discovery error: " + error.message); },
+            () => { console.log("Discovery finished successfully");}
+          );
         } catch(error) {
-          console.log("Error during fetch or consume: " + error.message);
+          console.log("Error: " + error.message);
         };
    @@ -588,6 +615,10 @@

    The ExposedThing interface

           ExposedThing implements ConsumedThing;
       interface ExposedThing {
+        // getter for ThingTemplate properties
+        getter any(DOMString name);
+        // setter for ThingTemplate properties
+        setter void(DOMString name, any value);
         // define how to expose and run the Thing
         Promise<void> expose();
         Promise<void> destroy();
@@ -645,35 +676,6 @@ 
    The ExposedThing interface
    
       
    
         Adds a Property defined by the argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
    
-      
    
-        
    The ThingPropertyInit dictionary
    
-        
    -          dictionary ThingPropertyInit: ThingTemplate {
-            required TDValueType schema;
-            boolean writable = false;
-            boolean observable = false;
-            any value;
-          };
-        
    
-        
    
-          Represents the Thing Property description.
-        
    
-        
      
-          
    • 
-            The name attribute represents the name of the Property.
-          
      • 
-          
    • 
-            The schema attribute represents the data type for the Property described by TDValueType.
-          
      • 
-          
    • The value attribute represents the value of the Property.
      • 
-          
    • 
-            The writable attribute defines whether the Property can be updated. The default value is false.
-          
      • 
-          
    • 
-            The observable attribute defines whether the Property changes can be observed by an external client. The default value is false.
-          
      • 
-        
    
-      
    
      
 
     
     
    The removeProperty() method
    
@@ -686,29 +688,6 @@ 
    The ThingPropertyInit dictionary
    
       
    
         Adds an Action to the Thing object as defined by the action argument of type ThingAction and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
    
-      
    
-        
    The ThingActionInit dictionary
    
-        
    -          dictionary ThingActionInit: ThingTemplate {
-            TDValueType inputSchema;
-            TDValueType outputSchema;
-          };
-      
    
-      
    
-        The ThingAction dictionary describes the arguments and the return value.
-      
    
-        
      
-          
    • 
-            The name attribute provides the Action name.
-          
      • 
-          
    • 
-            The inputSchema attribute provides the description of the input arguments (argument list is represented by an object). If missing, it means the action does not accept arguments.
-          
      • 
-          
    • 
-            The outputSchema attribute provides the description of the returned data. If missing, it means the action does not return data.
-          
      • 
-        
    
-      
    
     
     
 
     
     
    The removeAction() method
    
@@ -721,19 +700,6 @@ 
    The ThingActionInit dictionary
    
       
    
         Adds an event to the Thing object as defined by the event argument of type ThingEvent and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
    
-      
    
-        
    The ThingEventInit dictionary
    
-        
    -          dictionary ThingEventInit: ThingTemplate {
-            required DOMString name;
-            TDValueType schema;
-          };
-        
    
-        
      
-          
    • The name attribute represents the event name.
      • 
-          
    • The schema attribute represents the type of the data that is attached to the event. If missing, it means the event does not carry data.
      • 
-        
    
-      
    
     
    
 
     
     
    The removeEvent() method
    
@@ -1108,25 +1074,7 @@ 
    The Observable interface
    
     
    
       
      
         
    • 
-          Synchronized the Scripting API with the [Thing Description specification](https://w3c.github.io/wot-thing-description/). Defined ThingDescription, ThingTemplate, ThingMetadata, SemanticType, SemanticMetadata, input and output data descriptions, etc.
-        
      • 
-        
    • 
-          Separated consume() to fetch() and consume().
-        
      • 
-        
    • 
-          Changed expose() to accept a Thing Template.
-        
      • 
-        
    • 
-          Instead of addListener(), removeListener() introduced onEvent(), onPropertyChange(), onTDChange().
-        
      • 
-        
    • 
-          Revised ExposedThing handlers for Property, Action and Event.
-        
      • 
-        
    • 
-          Added an informal section on TD introspection.
-        
      • 
-        
    • 
-          Added informal section for Observable.
+          Synchronized the Scripting API with the [Thing Description specification](https://w3c.github.io/wot-thing-description/). Defined ThingDescription, ThingTemplate, data type descriptions, etc. Refined discovery filtering.
         
      • 
       
    
     
    
@@ -1143,13 +1091,9 @@ 
    The Observable interface
    
         
  • 
           Security related metadata (https://github.com/w3c/wot-scripting-api/issues/91).
         
    • 
-        
  • 
-          Defining TDValueType better (https://github.com/w3c/wot-scripting-api/issues/89).
-        
    • 
         
  • 
           Providing Protocol Binding for ExposedThing (https://github.com/w3c/wot-scripting-api/issues/45).
         
    • 
-        
  •  Retrieving information from Thing Description (https://github.com/w3c/wot-scripting-api/issues/38) 
    • 
         
  •  Script management and runtime related issues (https://github.com/w3c/wot-scripting-api/issues/) 
    • 
       
   
    

From 57a2ec34a4fdf6759301cf5e4fd3d763874aac5e Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Fri, 11 May 2018 16:30:49 +0300
Subject: [PATCH 208/464] Updated the examples. Small fixes.

Signed-off-by: Zoltan Kis 
---
 index.html | 96 ++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 61 insertions(+), 35 deletions(-)

diff --git a/index.html b/index.html
index ddd1160a..059a0539 100644
--- a/index.html
+++ b/index.html
@@ -237,10 +237,6 @@ 
    The WoT object
    
       typedef (ThingTemplate or ThingDescription or ConsumedThing) ThingModel;
    -

    - The fetch() method could be merged into discover(), i.e. discover({ url: tdURL }) is equivalent to former fetch(tdURL). Alternatively, both could be replaced by `fetch(optional (ThingFilter or USVString) locator)`, where `locator` can be a URL (for direct fetch) or a `ThingFilter` (for discovery). -

    -

    The algorithms for the WoT methods will be specified later, including error handling and security considerations.

    @@ -258,7 +254,7 @@

    The ThingDescription type

    The ThingTemplate dictionary

    - `ThingTemplate` is a dictionary used for initializing a Thing. It contains properties representing semantic metadata and interactions (Properties, Actions and Events) used for initializing a Thing Description as defined in [[!WOT-TD]]. + `ThingTemplate` is a dictionary that contains properties representing semantic metadata and interactions (Properties, Actions and Events). It is used for initializing an internal representation of a Thing Description as defined in [[!WOT-TD]].

    • @@ -288,6 +284,9 @@

      The ThingTemplate dictionary

    • The events optional attribute represents a dictionary with keys that correspond to Event names and values of type EventInit.
      • +
    • + The links optional attribute represents an array WebLink objects. +
    • The @context optional attribute represents a semantic context as USVString.
      • @@ -433,19 +432,23 @@

      The ThingFilter dictionary

      }); 
      -        let subscription = wot.discover({
+        let bleSub = wot.discover({
           method: "ble",
           constraints: [{ protocol: "BLE-4.2" }]
         }).subscribe(
           td => { console.log("Found nearby Thing " + td.name); },
-          error => { console.log("Discovery error: " + error.message); },
-          () => { console.log("Discovery finished successfully");}
+          error => { console.log("Discovery error: " + error.message); }
+        );
+        let nfcSub = wot.discover({ method: "nfc" }).subscribe(
+          td => { console.log("Found nearby Thing " + td.name); },
+          error => { console.log("Discovery error: " + error.message); }
         );
       
               let subscription = wot.discover({
           method: "myOwnMethod", // not standardized
           url: myDirectoryURL,
+          // includes non-standard, app-specific property "constraints"
           constraints: [{ account: "XYZ123", key: "..."}]
         }).subscribe(
           td => { console.log("Found Thing " + td.name); },
@@ -480,7 +483,7 @@ 
      Data types used in a Thing
      
     
      The Interaction interface
      
     
             interface Interaction {  // abstract class
-        readonly attribute DOMString name;
+        // readonly attribute DOMString name;
         readonly attribute FrozenArray<Form> forms;
       };
       dictionary InteractionInit {
@@ -773,31 +776,43 @@ 
      Examples
      
 
       
               try {
-          var thing = WoT.produce({ name: "tempSensor" });
-          // manually add Interactions
-          thing.addProperty({
-            name: "temperature",
-            value: 0.0,
-            schema: '{ "type": "number" }'
-            // use default values for the rest
-          }).addProperty({
-            name: "max",
-            value: 0.0,
-            schema: '{ "type": "number" }'
-            // use default values for the rest
-          }).addAction({
-            name: "reset",
-            // no input, no output
-          }).addEvent({
-            name: "onchange",
-            schema: '{ "type": "number" }'
-          });
-          // add server functionality
-          thing.setActionHandler("reset", () => {
-            console.log("Resetting maximum");
-            thing.writeProperty("max", 0.0);
+          var thing = WoT.produce({
+            name: "tempSensor",
+            properties: {
+              temperature: {
+                type: "number",
+                value: 0.0,
+                minimum: -50,
+                maximum: 10000,
+                forms: []
+              },
+            },
+            actions: {
+              reset: {
+                description: "Reset the temperature sensor",
+                input: {
+                  temperature: {
+                    type: "number",
+                    value: 0.0,
+                    minimum: -50,
+                    maximum: 10000
+                  }
+                },
+                output: null,
+                forms: []
+              },
+            },
+            events: {
+              onchange: {
+                type: "number",
+                minimum: -50,
+                maximum: 10000,
+                forms: []
+              },
+            },
+            links: []
           });
-          thing.start().then(() => {
+          thing.expose().then(() => {
               thing.register();
           });
           // define Thing business logic
@@ -816,7 +831,18 @@ 
      Examples
      
       
      
 
       
      -        let thingDescription = '{ "@context": [ "https://w3c.github.io/wot/w3c-wot-td-context.jsonld", "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ], "@type": [ "Thing", "Sensor" ], "name": "mySensor", "geo:location": "testspace", "interaction": [ { "@type": [ "Property", "Temperature" ], "name": "prop1", "schema": { "type": "number" }, "saref:TemperatureUnit": "degree_Celsius" } ] }';
+        let thingDescription = '{ \
+          "name": "mySensor", \
+          "@context": [ "https://w3c.github.io/wot/w3c-wot-td-context.jsonld",\
+             "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ],\
+          "@type": [ "Thing", "Sensor" ], \
+          "geo:location": "testspace", \
+          "properties": { \
+            "prop1": { \
+              "type": "number",\
+              "@type": [ "Property", "Temperature" ], \
+              "saref:TemperatureUnit": "degree_Celsius" \
+          } } }';
         try {
           // note that produce() fails if thingDescription contains error
           let thing = WoT.produce(thingDescription);
@@ -834,7 +860,7 @@ 
      Examples
      
                 console.log("Error");
               });
           });
-          thing.start();
+          thing.expose();
         } catch(err) {
            console.log("Error creating ExposedThing: " + err);
         }

From d979a6fb471f2cf2603b7b6ae8f476a61dbb4a8f Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Fri, 11 May 2018 20:43:27 +0300
Subject: [PATCH 209/464] Add ThingCoreProperties and ThingProperties
 definitions

Signed-off-by: Zoltan Kis 
---
 index.html | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/index.html b/index.html
index 059a0539..0f073f13 100644
--- a/index.html
+++ b/index.html
@@ -232,8 +232,14 @@ 
      The WoT object
      
         ConsumedThing consume(ThingDescription td);
         ExposedThing produce(ThingModel model);
       };
-      typedef USVString ThingDescription;
+      enum ThingCoreProperties {
+        "name", "id", "base", "description", "support", "security",
+        "actions", "properties", "events", "links",
+        "@context", "@type"
+      };
+      typedef (ThingCoreProperties or DOMString) ThingProperties;
       typedef dictionary ThingTemplate;
+      typedef USVString ThingDescription;
       typedef (ThingTemplate or ThingDescription or ConsumedThing) ThingModel;
     
      
 
@@ -254,7 +260,7 @@ 
      The ThingDescription type
      
     
      
       
      The ThingTemplate dictionary
      
       
      
-        `ThingTemplate` is a dictionary that contains properties representing semantic metadata and interactions (Properties, Actions and Events). It is used for initializing an internal representation of a Thing Description as defined in [[!WOT-TD]].
+        `ThingTemplate` is a dictionary that contains properties representing semantic metadata and interactions (Properties, Actions and Events). It is used for initializing an internal representation of a Thing Description as defined in [[!WOT-TD]]. The set of core properties is defined by the ThingCoreProperties enumeration. In addition, ThingTemplate may contain other properties as well as defined in the Thing Description from which the Thing object is created.
       
      
       
        
         
      • 
@@ -294,7 +300,7 @@ 
        The ThingTemplate dictionary
        
           The @type optional attribute represents a semantic type as USVString.
         
        • 
         
      • 
-          Apart from the core semantic properties defined above, others may also be defined on a Thing, for instance `@id`, "gms:COVParams" (with namespace definition), or "iotschema:unit" etc.
+          Apart from the core properties defined above, others may also be defined on a Thing, for instance `@id`, "gms:COVParams" (with namespace definition), or "iotschema:unit" etc.
         
        • 
       
      
       
      

From 6b7f59c73f0416ba24a22c2f18a778a4da839628 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Mon, 14 May 2018 11:16:53 +0300
Subject: [PATCH 210/464] Add Security dictionary

Signed-off-by: Zoltan Kis 
---
 index.html | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/index.html b/index.html
index 0f073f13..cf8c2c94 100644
--- a/index.html
+++ b/index.html
@@ -279,7 +279,7 @@ 
      The ThingTemplate dictionary
      
           The support optional attribute of type DOMString represents human readable information about the TD maintainer.
         
         
    • 
-          The security optional attribute represents security metadata defined by the Security dictionary;
+          The security optional attribute represents security metadata defined by the Security dictionary;
         
      • 
         
    • 
           The properties optional attribute represents a dictionary with keys that correspond to Property names and values of type PropertyInit.
@@ -308,6 +308,30 @@ 
      The ThingTemplate dictionary
      
       
      
     
      •  
 
+    
      
+      
       The Security dictionary
      
+      
      
+        Contains security related configuration.
+      
      
+    
      +      enum SecurityScheme { "basic", "digest", "oauth2" };
+      dictionary Security {
+        required SecurityScheme scheme;
+        USVString authentication;
+      };
+    
      
+      
      
+        
        
+          
      • 
+            The scheme property represents the identification of the security scheme to be used for the Thing.
+          
        • 
+          
      • 
+            The authentication property represents the location of the authentication information.
+          
        • 
+        
      
+      
      
+    
      
+
     
       
       The fetch() method
      
       
      
         Accepts an url argument of type `USVString` that represents a URL (e.g. `file://` or `https://`) and returns a Promise that resolves with a ThingDescription (a serialized JSON-LD document of type `USVString`).

From 109e49f1cdd49191c1f246208e174d65f141b63b Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Thu, 17 May 2018 17:47:11 +0300
Subject: [PATCH 211/464] Remove ThingCoreProperties. Add typeDefinitions and
 securityDefinitions to ThingTemplate, add support for referencing type
 information. Update examples. Small changes on structures.

Signed-off-by: Zoltan Kis 
---
 index.html | 263 +++++++++++++++++++++++++++++++----------------------
 1 file changed, 152 insertions(+), 111 deletions(-)

diff --git a/index.html b/index.html
index cf8c2c94..540ddb9b 100644
--- a/index.html
+++ b/index.html
@@ -232,12 +232,6 @@ 
      The WoT object
      
         ConsumedThing consume(ThingDescription td);
         ExposedThing produce(ThingModel model);
       };
-      enum ThingCoreProperties {
-        "name", "id", "base", "description", "support", "security",
-        "actions", "properties", "events", "links",
-        "@context", "@type"
-      };
-      typedef (ThingCoreProperties or DOMString) ThingProperties;
       typedef dictionary ThingTemplate;
       typedef USVString ThingDescription;
       typedef (ThingTemplate or ThingDescription or ConsumedThing) ThingModel;
@@ -257,7 +251,7 @@ 
      The ThingDescription type
      
       
      
     
      
 
-    
      
+    
      
       
      The ThingTemplate dictionary
      
       
      
         `ThingTemplate` is a dictionary that contains properties representing semantic metadata and interactions (Properties, Actions and Events). It is used for initializing an internal representation of a Thing Description as defined in [[!WOT-TD]]. The set of core properties is defined by the ThingCoreProperties enumeration. In addition, ThingTemplate may contain other properties as well as defined in the Thing Description from which the Thing object is created.
@@ -282,7 +276,7 @@ 
      The ThingTemplate dictionary
      
           The security optional attribute represents security metadata defined by the Security dictionary;
         
         
    • 
-          The properties optional attribute represents a dictionary with keys that correspond to Property names and values of type PropertyInit.
+          The properties optional attribute represents a dictionary with keys that correspond to Property names and values of type PropertyTemplate.
         
      • 
         
    • 
           The actions optional attribute represents a dictionary with keys that correspond to Action names and values of type ActionInit.
@@ -293,6 +287,12 @@ 
      The ThingTemplate dictionary
      
         
    • 
           The links optional attribute represents an array WebLink objects.
         
      • 
+        
    • 
+          The securityDefinitions optional attribute represents a dictionary where property names are security configuration names, and values are Security dictionaries.
+        
      • 
+        
    • 
+          The typeDefinitions optional attribute represents a dictionary where property names are type names, and values are  dictionaries.
+        
      • 
         
    • 
           The @context optional attribute represents a semantic context as USVString.
         
      • 
@@ -317,7 +317,7 @@ 
       The Security dictionary
      
       enum SecurityScheme { "basic", "digest", "oauth2" };
       dictionary Security {
         required SecurityScheme scheme;
-        USVString authentication;
+        any input;
       };
     
      
       
      
@@ -326,7 +326,7 @@ 
       The Security dictionary
      
             The scheme property represents the identification of the security scheme to be used for the Thing.
           
           
    • 
-            The authentication property represents the location of the authentication information.
+            The input property represents security initialization data.
           
      •

    @@ -494,97 +494,145 @@

    Data types used in a Thing

    Every Thing describes its metadata as defined in ThingTemplate, and basic interactions as defined in ConsumedThing: Properties, Actions and Events. The following data types are used for representing these interactions, as defined in [[!WOT-TD]].

    -

    Links and Forms

    - 
    -      [NoInterfaceObject]
-      dictionary Link {
-        required USVString href;
-        USVString mediaType;
-        DOMString rel;
-      };
-      dictionary WebLink: Link {
-        USVString anchor;
-      };
-      dictionary Form: Link {
-        DOMString security;
-      };
-
    +

    Links and Forms

    + 
    +        [NoInterfaceObject]
+        dictionary Link {
+          required USVString href;
+          USVString mediaType;
+          DOMString rel;
+        };
+        dictionary WebLink: Link {
+          USVString anchor;
+        };
+        dictionary Form: Link {
+          DOMString security;
+        };
+
    -

    The Interaction interface

    - 
    -      interface Interaction {  // abstract class
-        // readonly attribute DOMString name;
-        readonly attribute FrozenArray<Form> forms;
-      };
-      dictionary InteractionInit {
-        DOMString name;
-        sequence<Form> forms;
-      };
-
    + +

    Value types

    +

    + Value types are used in Property, Event and Action parameter definitions in a ThingTemplate. Basically correspond to a JSON object definition. +

    +

    + A type definition is either a ValueType object or a string that matches a property name in the typeDefinitions dictionary of the ThingTemplate the type definition is used in. +

    + 
    +        enum JSONType { "boolean", "number", "string", "object", "array" };
+        typedef (unsigned long or unrestricted double) Number;
+        dictionary BooleanValueType {
+          const type = "boolean";
+          boolean value;
+        };
+        dictionary StringValueType {
+          const type = "string";
+          USVString value;
+        };
+        dictionary NumberValueType {
+          const type = "number";
+          Number value;
+          Number minimum;
+          Number maximum;
+        };
+        dictionary ObjectValueType {
+          const type = "object";
+          object value;
+        };
+        dictionary ArrayValueType {
+          const type = "array";
+          FrozenArray<any> value;
+          unsigned long minItems;
+          unsigned long maxItems;
+        };
+        typedef (BooleanValueType or StringValueType or NumberValueType or ObjectValueType or ArrayValueType) ValueType;
+        typedef (ValueType or DOMString) TypeDefinition;
+
    -

    Properties

    - 
    -      enum JSONType { "boolean", "number", "string", "null", "object", "array" };
-      typedef (unsigned long or unrestricted double) Number;
-      dictionary PropertyTemplate: InteractionInit {
-        DOMString label;
-        boolean writable = false;
-        boolean observable = false;
-        boolean const;  // TBD
-        boolean required;
-      };
-      dictionary SimplePropertyInit: PropertyTemplate {
-        required DOMString type;  // null, boolean, string
-        any value;
-      };
-      dictionary NumberPropertyInit: PropertyTemplate {
-        DOMString type = "number";
-        Number value;
-        Number minimum;
-        Number maximum;
-      };
-      dictionary ObjectPropertyInit: PropertyTemplate {
-        DOMString type = "object";
-        object value;
-      };
-      dictionary ArrayPropertyInit: PropertyTemplate {
-        DOMString type = "array";
-        sequence<any> value;
-        unsigned long minItems;
-        unsigned long maxItems;
-      };
-      typedef (SimplePropertyInit or NumberPropertyInit or ObjectPropertyInit or ArrayPropertyInit) PropertyInit;
-      interface ThingProperty: Interaction {
-        readonly attribute DOMString type;
-        Promise<any> get();
-        Promise set(any value);
-      };
-      ThingProperty implements Observable;
-
    + +
    +

    The ThingProperty interface

    +

    + The ThingProperty interface is used in ConsumedThing and ExposedThing objects to represent Thing Property interactions. +

    +

    + The PropertyTemplate dictionary is used for initializing Property objects in a ThingTemplate dictionary used for creating an ExposedThing object. It MUST implement one of the ValueType dictionaries. +

    + 
    +        dictionary PropertyTemplate {
+          required TypeDefinition type;
+          DOMString label;
+          boolean writable = false;
+          boolean observable = false;
+          boolean const;
+          boolean required;
+          sequence<Form> forms;
+        };
+        PropertyTemplate implements ValueType;
+        interface ThingProperty {
+          // getter for PropertyTemplate properties
+          getter any(DOMString name);
+          // get and set interface for the Property
+          Promise<any> get();
+          Promise set(any value);
+        };
+        ThingProperty implements PropertyTemplate;
+        ThingProperty implements Observable;
+
    +

    + The ThingProperty interface contains all the properties defined on PropertyTemplate as read-only properties. +

    +

    + The type read-only property represents the type definition for the Property. If it matches a JSONType, then it MUST implement the corresponding ValueType dictionary. Otherwise, if it matches a property name in the typeDefinitions dictionary of the parent ThingTemplate, then implementations SHOULD use the dictionary value of the matched property for property type definition. +

    +

    + The label read-only property represents a text label for the Property. +

    +

    + The writable read-only property tells whether the Property value can be updated. If it is `false`, then the `set(value)` method SHOULD always reject. +

    +

    + The observable read-only property tells whether the Property supports subscribing to value change notifications. If it is `false`, then the `subscribe()` method SHOULD always fail. +

    +

    + The const read-only property tells whether the Property value is a constant. If `true`, the `set()` and `subscribe()` methods SHOULD always fail. +

    +

    + The required read-only property tells whether the Property should be always present on the ExposedThing object. +

    +

    + The forms read-only property represents the protocol bindings initialization data. +

    -

    Actions

    - 
    -      dictionary ActionInit: InteractionInit {
-        DOMString label;
-        PropertyInit input;
-        PropertyInit output;
-        DOMString description;
-      };
-      interface ThingAction: Interaction {
-        readonly attribute PropertyInit input;
-        readonly attribute PropertyInit output;
-        readonly attribute DOMString description;
-        readonly attribute DOMString label;
-        Promise<any> run();
-      };
-
    + +
    +

    The ThingAction interface

    + 
    +        dictionary ActionInit: InteractionInit {
+          DOMString label;
+          TypeDefinition input;
+          TypeDefinition output;
+          DOMString description;
+          sequence<Form> forms;
+        };
+        interface ThingAction: Interaction {
+          readonly attribute TypeDefinition input;
+          readonly attribute TypeDefinition output;
+          readonly attribute DOMString description;
+          readonly attribute DOMString label;
+          readonly attribute FrozenArray<Form> forms;
+          Promise<any> run();
+        };
+
    +

    Events

    - 
    -      interface ThingEvent : ThingProperty {
-      };
-      typedef PropertyInit EventInit;
-
    + 
    +        interface ThingEvent {
+        };
+        ThingEvent implements ThingProperty;
+        typedef PropertyTemplate EventInit;
+
    @@ -808,37 +856,30 @@

    Examples

    try { var thing = WoT.produce({ name: "tempSensor", - properties: { - temperature: { + typeDefinitions: { + TemperatureValueType: { type: "number", value: 0.0, minimum: -50, maximum: 10000, forms: [] - }, + } + }, + properties: { + temperature: "TemperatureValueType" }, actions: { reset: { description: "Reset the temperature sensor", input: { - temperature: { - type: "number", - value: 0.0, - minimum: -50, - maximum: 10000 - } + temperature: "TemperatureValueType" }, output: null, forms: [] }, }, events: { - onchange: { - type: "number", - minimum: -50, - maximum: 10000, - forms: [] - }, + onchange: "TemperatureValueType" }, links: [] }); From e8d4735186d6785b1155035394e4fb7e19e6c7e8 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 23 May 2018 14:54:37 +0300 Subject: [PATCH 212/464] Clarify ValueType vs PropertyTemplate. Remove typeDefinitions and securityDefinitions. Signed-off-by: Zoltan Kis --- index.html | 140 ++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 95 insertions(+), 45 deletions(-) diff --git a/index.html b/index.html index 540ddb9b..691beb71 100644 --- a/index.html +++ b/index.html @@ -254,7 +254,7 @@

    The ThingDescription type

    The ThingTemplate dictionary

    - `ThingTemplate` is a dictionary that contains properties representing semantic metadata and interactions (Properties, Actions and Events). It is used for initializing an internal representation of a Thing Description as defined in [[!WOT-TD]]. The set of core properties is defined by the ThingCoreProperties enumeration. In addition, ThingTemplate may contain other properties as well as defined in the Thing Description from which the Thing object is created. + `ThingTemplate` is a dictionary that contains properties representing semantic metadata and interactions (Properties, Actions and Events). It is used for initializing an internal representation of a Thing Description as defined in [[!WOT-TD]]. The set of core properties is defined below. In addition, ThingTemplate may contain other properties as well as defined in the Thing Description from which the Thing object is created.

    • @@ -287,12 +287,6 @@

      The ThingTemplate dictionary

    • The links optional attribute represents an array WebLink objects.
      • -
    • - The securityDefinitions optional attribute represents a dictionary where property names are security configuration names, and values are Security dictionaries. -
      • -
    • - The typeDefinitions optional attribute represents a dictionary where property names are type names, and values are dictionaries. -
    • The @context optional attribute represents a semantic context as USVString.
      • @@ -515,38 +509,37 @@

      Data types used in a Thing

      Value types are used in Property, Event and Action parameter definitions in a ThingTemplate. Basically correspond to a JSON object definition.

      -

      - A type definition is either a ValueType object or a string that matches a property name in the typeDefinitions dictionary of the ThingTemplate the type definition is used in. - 

               enum JSONType { "boolean", "number", "string", "object", "array" };
         typedef (unsigned long or unrestricted double) Number;
-        dictionary BooleanValueType {
+        dictionary ValueType {
+          required boolean type;
+          boolean required;
+        };
+        dictionary BooleanValueType: ValueType {
           const type = "boolean";
           boolean value;
         };
-        dictionary StringValueType {
+        dictionary StringValueType: ValueType {
           const type = "string";
           USVString value;
         };
-        dictionary NumberValueType {
+        dictionary NumberValueType: ValueType {
           const type = "number";
           Number value;
           Number minimum;
           Number maximum;
         };
-        dictionary ObjectValueType {
+        dictionary ObjectValueType: ValueType {
           const type = "object";
-          object value;
+          maplike<DOMString, ValueType> properties;
         };
-        dictionary ArrayValueType {
+        dictionary ArrayValueType: ValueType {
           const type = "array";
-          FrozenArray<any> value;
+          FrozenArray<ValueType> items;
           unsigned long minItems;
           unsigned long maxItems;
         };
-        typedef (BooleanValueType or StringValueType or NumberValueType or ObjectValueType or ArrayValueType) ValueType;
-        typedef (ValueType or DOMString) TypeDefinition;
    @@ -559,16 +552,13 @@

    The ThingProperty interface

    The PropertyTemplate dictionary is used for initializing Property objects in a ThingTemplate dictionary used for creating an ExposedThing object. It MUST implement one of the ValueType dictionaries. 

    -        dictionary PropertyTemplate {
-          required TypeDefinition type;
+        dictionary PropertyTemplate: ValueType {
           DOMString label;
           boolean writable = false;
           boolean observable = false;
           boolean const;
-          boolean required;
           sequence<Form> forms;
         };
-        PropertyTemplate implements ValueType;
         interface ThingProperty {
           // getter for PropertyTemplate properties
           getter any(DOMString name);
@@ -583,7 +573,7 @@ 
    The ThingProperty interface
    
         The ThingProperty interface contains all the properties defined on PropertyTemplate as read-only properties.
       
    
       
    
-        The type read-only property represents the type definition for the Property. If it matches a JSONType, then it MUST implement the corresponding ValueType dictionary. Otherwise, if it matches a property name in the typeDefinitions dictionary of the parent ThingTemplate, then implementations SHOULD use the dictionary value of the matched property for property type definition.
+        The type read-only property represents the type definition for the Property. If it matches a JSONType, then it MUST implement the corresponding ValueType dictionary.
       
    
       
    
         The label read-only property represents a text label for the Property.
@@ -610,14 +600,14 @@ 
    The ThingAction interface
    
       
             dictionary ActionInit: InteractionInit {
           DOMString label;
-          TypeDefinition input;
-          TypeDefinition output;
+          ValueType input;
+          ValueType output;
           DOMString description;
           sequence<Form> forms;
         };
         interface ThingAction: Interaction {
-          readonly attribute TypeDefinition input;
-          readonly attribute TypeDefinition output;
+          readonly attribute ValueType input;
+          readonly attribute ValueType output;
           readonly attribute DOMString description;
           readonly attribute DOMString label;
           readonly attribute FrozenArray<Form> forms;
@@ -852,34 +842,34 @@ 
    Examples
    
         Below some ExposedThing interface examples are given.
       
    
 
-      
    +      
             try {
+          var temperatureValueDefinition = {
+            type: "number",
+            value: 0.0,
+            minimum: -50,
+            maximum: 10000
+          };
+          var temperaturePropertyDefinition = temperatureValueDefinition;
+          // add the 'forms' property
+          temperaturePropertyDefinition.forms = [ ... ];
           var thing = WoT.produce({
             name: "tempSensor",
-            typeDefinitions: {
-              TemperatureValueType: {
-                type: "number",
-                value: 0.0,
-                minimum: -50,
-                maximum: 10000,
-                forms: []
-              }
-            },
             properties: {
-              temperature: "TemperatureValueType"
+              temperature: temperaturePropertyDefinition
             },
             actions: {
               reset: {
                 description: "Reset the temperature sensor",
                 input: {
-                  temperature: "TemperatureValueType"
+                  temperature: temperatureValueDefinition
                 },
                 output: null,
                 forms: []
               },
             },
             events: {
-              onchange: "TemperatureValueType"
+              onchange: temperatureValueDefinition
             },
             links: []
           });
@@ -890,10 +880,10 @@ 
    Examples
    
           setInterval( async () => {
             let mock = Math.random()*100;
             thing.writeProperty("temperature", mock);
-            let old = await thing.readProperty("max");
-            if (old < mock) {
-              thing.writeProperty("max", mock);
-              thing.emitEvent("onchange");
+            let old = await thing.readProperty("temperature");
+            if (old < mock) {
+              thing.writeProperty("temperature", mock);
+              thing.emitEvent("onchange", mock);
             }
           }, 1000);
         } catch (err) {
@@ -901,6 +891,66 @@ 
    Examples
    
         }
       
    
 
+      
    +        try {
+          var 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
+                }
+              }
+          };
+          var statusPropertyDefinition = statusValueDefinition;
+          // add the 'forms' property
+          statusPropertyDefinition["forms"] = [];
+          var thing = WoT.produce({
+            name: "mySensor",
+            properties: {
+              brightness: {
+                type: "number",
+                value: 0.0,
+                minimum: 0.0,
+                maximum: 100.0,
+                required: true,
+              },
+              status: statusPropertyDefinition
+            },
+            actions: {
+              status: {
+                description: "Get status object",
+                input: null,
+                output: {
+                  status : statusValueDefinition;
+                },
+                forms: []
+              },
+            },
+            events: {
+              onstatuschange: statusValueDefinition;
+            },
+            links: []
+          });
+          thing.expose().then(() => {
+              thing.register();
+          });
+        } catch (err) {
+           console.log("Error creating ExposedThing: " + err);
+        }
+      
    
+
       
             let thingDescription = '{ \
           "name": "mySensor", \

From f326b6909ec79b97075ce9de2515846f6ad5b809 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Mon, 28 May 2018 16:52:39 +0300
Subject: [PATCH 213/464] Move register() and unregister() to the WoT object.
 Improve ThingFilter for discovery. Improve Security dictionary. Editorial
 fixes.

Signed-off-by: Zoltan Kis 
---
 index.html | 128 ++++++++++++++++++++++++++---------------------------
 1 file changed, 64 insertions(+), 64 deletions(-)

diff --git a/index.html b/index.html
index 691beb71..26f7d56f 100644
--- a/index.html
+++ b/index.html
@@ -221,7 +221,7 @@ 
    The WoT object
    
     
    The WoT object is the API entry point and it is exposed by an implementation of the WoT Runtime. The WoT object does not expose properties, only methods for discovering, consuming and exposing a Thing.
     
    
     
    
-       Browser implementations SHOULD use a namespace object such as `wot`, and [Node.js](https://nodejs.org/en/)-like runtimes MAY provide the API object through the [`require()`](https://nodejs.org/api/modules.html) or [`import`](http://www.ecma-international.org/ecma-262/6.0/#sec-imports) mechanism.
+       Browser implementations SHOULD use a namespace object such as wot, and [Node.js](https://nodejs.org/en/)-like runtimes MAY provide the API object through the [`require()`](https://nodejs.org/api/modules.html) or [`import`](http://www.ecma-international.org/ecma-262/6.0/#sec-imports) mechanism.
     
    
     
           // [SecureContext]
@@ -231,6 +231,8 @@ 
    The WoT object
    
         Promise<ThingDescription> fetch(USVString url);
         ConsumedThing consume(ThingDescription td);
         ExposedThing produce(ThingModel model);
+        Promise<void> register(USVString directory, ExposedThing thing);
+        Promise<void> unregister(USVString directory, ExposedThing thing);
       };
       typedef dictionary ThingTemplate;
       typedef USVString ThingDescription;
@@ -247,24 +249,21 @@ 
    The ThingDescription type
    
         Serialized representation of the Thing Description (a JSON-LD document).
       
    
       
    
-        In this version of the API, Thing Descriptions are represented as an opaque `USVString` that can be transmitted between devices.
+        In this version of the API, Thing Descriptions are represented as an opaque USVString that can be transmitted between devices.

    The ThingTemplate dictionary

    - `ThingTemplate` is a dictionary that contains properties representing semantic metadata and interactions (Properties, Actions and Events). It is used for initializing an internal representation of a Thing Description as defined in [[!WOT-TD]]. The set of core properties is defined below. In addition, ThingTemplate may contain other properties as well as defined in the Thing Description from which the Thing object is created. + ThingTemplate is a dictionary that contains properties representing semantic metadata and interactions (Properties, Actions and Events). It is used for initializing an internal representation of a Thing Description as defined in [[!WOT-TD]]. The set of core properties is defined below. In addition, ThingTemplate may contain other properties as well as defined in the Thing Description from which the Thing object is created.

    • - The name mandatory attribute represents the name of the Thing as DOMString. + The name optional attribute represents the name of the Thing as DOMString.
    • - The id optional attribute represents a unique identifier of the Thing, typically a URI, IRI, or URN as USVString. Note that this is not the same as the JSON-LD `@id` attribute. -
      • -
    • - The base optional attribute represents a base URL as USVString. + The id optional attribute represents an application provided hint for the unique identifier of the Thing, typically a URI, IRI, or URN as USVString. Note that this is not the same as the JSON-LD @id attribute. Also note that the WoT Runtime may override this with a different value when exposing the Thing.
    • The description optional attribute of type DOMString represents a human readable description of the Thing. @@ -294,7 +293,7 @@

      The ThingTemplate dictionary

      The @type optional attribute represents a semantic type as USVString.
    • - Apart from the core properties defined above, others may also be defined on a Thing, for instance `@id`, "gms:COVParams" (with namespace definition), or "iotschema:unit" etc. + Apart from the core properties defined above, others may also be defined on a Thing, for instance "@id", "gms:COVParams" (with namespace definition), or "iotschema:unit" etc.

    @@ -308,19 +307,28 @@

    The Security dictionary

    Contains security related configuration. 

    -      enum SecurityScheme { "basic", "digest", "oauth2" };
       dictionary Security {
-        required SecurityScheme scheme;
-        any input;
+        required DOMString scheme;
+        any in;
       };

    • - The scheme property represents the identification of the security scheme to be used for the Thing. -
      • + The scheme property represents the identification of the security scheme to be used for the Thing, for instance +
        +
      • "basic+https",
        • +
      • "digest+https",
        • +
      • "bearer+https",
        • +
      • "bearer+coaps",
        • +
      • "pop+https",
        • +
      • "pop+coaps",
        • +
      • "apikey+https",
        • +
      • "apikey+coaps",
        • +
      • "ocf+coaps".
        • +
    • - The input property represents security initialization data. + The in property represents security initialization data as described in the [Security metadata description](https://github.com/w3c/wot-security/blob/master/wot-security-metadata.md).

    @@ -328,7 +336,7 @@

    The Security dictionary

    The fetch() method

    - Accepts an url argument of type `USVString` that represents a URL (e.g. `file://` or `https://`) and returns a Promise that resolves with a ThingDescription (a serialized JSON-LD document of type `USVString`). + Accepts an url argument of type USVString that represents a URL (e.g. "file://..." or "https://...") and returns a Promise that resolves with a ThingDescription (a serialized JSON-LD document of type USVString).

    @@ -352,11 +360,40 @@

    The Security dictionary

    +

    The register() method

    +

    + Takes two mandatory arguments: +

    +

    +

    + Generate the Thing Description as td, given the Properties, Actions and Events defined for this ExposedThing object. Then make a request to register td to the given WoT Thing Directory. +

    +
    + +

    The unregister() method

    +

    + Takes two mandatory arguments: +

    +

    +

    + Makes a request to unregister the thing from the given WoT Thing Directory. +

    +
    +

    The discover() method

    Starts the discovery process that will provide ThingDescriptions that match the optional argument ThingFilter. When the argument is not provided, uses all supported discovery methods. Returns an [Observable](https://github.com/tc39/proposal-observable) object that can be subscribed to and unsubscribed from. Errors are also signaled at the subscription object.

    +

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

    The DiscoveryMethod enumeration

    @@ -369,16 +406,13 @@

    The DiscoveryMethod enumeration

    • "any" does not provide any restriction
    • - "local" for discovering Things defined in the same device -
      • -
    • - "directory" for discovery based on a service provided by a directory or repository of Things + "local" for discovering Things defined in the same device or connected to the device by wired or wireless means.
    • - "nfc" for discovering Things in the device's proximity by using NFC + "directory" for discovery based on a service provided by a Thing Directory.
    • - "ble" for discovering Things by using Bluetooth Low Energy (BLE) + "multicast" for discovering Things in the device's network by using a supported multicast protocol.
    @@ -413,7 +447,7 @@

    The ThingFilter dictionary

    - If queries are specified, but not supported, implementations should signal a `NotSupportedError` on the subscription objects. For security errors (e.g. authentication error) a `SecurityError` should be signaled. For query validation errors a `TypeError` should be signaled. For other errors an `Error` should be signaled. + If queries are specified, but not supported, implementations should signal a NotSupportedError on the subscription objects. For security errors (e.g. authentication error) a SecurityError should be signaled. For query validation errors a TypeError should be signaled. For other errors an Error should be signaled.

    @@ -438,9 +472,6 @@

    The ThingFilter dictionary

    }, 5000); -

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

             let subscription = wot.discover({ method: "local" }).subscribe(
           td => { console.log("Found local Thing " + td.name); },
@@ -456,17 +487,14 @@ 
    The ThingFilter dictionary
    
         });
       
    +        // Use a proprietary extension of "local" discovery via "constraints"
         let bleSub = wot.discover({
-          method: "ble",
-          constraints: [{ protocol: "BLE-4.2" }]
+          method: "local",
+          constraints: [{ protocol: "BLE-4.2" }, { protocol: "NFC" }]
         }).subscribe(
           td => { console.log("Found nearby Thing " + td.name); },
           error => { console.log("Discovery error: " + error.message); }
         );
-        let nfcSub = wot.discover({ method: "nfc" }).subscribe(
-          td => { console.log("Found nearby Thing " + td.name); },
-          error => { console.log("Discovery error: " + error.message); }
-        );
       
             let subscription = wot.discover({
@@ -579,13 +607,13 @@ 
    The ThingProperty interface
    
         The label read-only property represents a text label for the Property.
       
    
       
    
-        The writable read-only property tells whether the Property value can be updated. If it is `false`, then the `set(value)` method SHOULD always reject.
+        The writable read-only property tells whether the Property value can be updated. If it is false, then the set(value) method SHOULD always reject.
       
    
       
    
-        The observable read-only property tells whether the Property supports subscribing to value change notifications. If it is `false`, then the `subscribe()` method SHOULD always fail.
+        The observable read-only property tells whether the Property supports subscribing to value change notifications. If it is false, then the subscribe() method SHOULD always fail.
       
    
       
    
-        The const read-only property tells whether the Property value is a constant. If `true`, the `set()` and `subscribe()` methods SHOULD always fail.
+        The const read-only property tells whether the Property value is a constant. If true, the set() and subscribe() methods SHOULD always fail.
       
    
       
    
         The required read-only property tells whether the Property should be always present on the ExposedThing object.
@@ -693,8 +721,6 @@ 
    The ExposedThing interface
    
         // define how to expose and run the Thing
         Promise<void> expose();
         Promise<void> destroy();
-        Promise<void> register(optional USVString directory);
-        Promise<void> unregister(optional USVString directory);
         Promise<void> emitEvent(DOMString eventName, any payload);
         // define Thing Description modifiers
         ExposedThing addProperty(ThingProperty property);
@@ -715,19 +741,7 @@ 
    The ExposedThing interface
    
 
     
     
    The expose() method
    
       
    
-        Start serving external requests for the Thing.
-      
    
-    
    
-
-    
     
    The register() method
    
-      
    
-        Generates the Thing Description given the properties, Actions and Event defined for this object. If a directory argument is given, make a request to register the Thing Description with the given WoT repository by invoking its register Action.
-      
    
-    
    
-
-    
     
    The unregister() method
    
-      
    
-        If a directory argument is given, make a request to unregister the Thing Description with the given WoT repository by invoking its unregister Action.
+        Start serving external requests for the Thing, so that WoT interactions using Properties, Actions and Events will be possible.
       
    
     
    
 
@@ -1097,46 +1111,32 @@ 
    The Observable interface
    
       The following terms are defined in [[!HTML5]] and are used in the context of browser implementations:
       
       browsing context,
-
       
       top-level browsing context,
-
       
       global object,
-
       
       incumbent settings object,
-
       
       Document,
-
       
       document base URL,
-
       
       Window,
-
       
       WindowProxy,
-
       
       origin,
-
       
       ASCII serialized origin,
-
       executing algorithms 
       in parallel,
-
       
       queue a task,
-
       
       task source,
-
       
       iframe,
-
       
       valid MIME type.
     
    

From a28542a0ccc4dcd11a84d2ed05042bea157502ed Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Mon, 28 May 2018 21:37:35 +0300
Subject: [PATCH 214/464] Align with the current TD spec

Signed-off-by: Zoltan Kis 
---
 index.html | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/index.html b/index.html
index 26f7d56f..5e087420 100644
--- a/index.html
+++ b/index.html
@@ -256,11 +256,11 @@ 
    The ThingDescription type
    
     
    
       
    The ThingTemplate dictionary
    
       
    
-        ThingTemplate is a dictionary that contains properties representing semantic metadata and interactions (Properties, Actions and Events). It is used for initializing an internal representation of a Thing Description as defined in [[!WOT-TD]]. The set of core properties is defined below. In addition, ThingTemplate may contain other properties as well as defined in the Thing Description from which the Thing object is created.
+        ThingTemplate is a dictionary that contains properties representing semantic metadata and interactions (Properties, Actions and Events). It is used for initializing an internal representation of a Thing Description as defined in [[!WOT-TD]], and it is also used in ThingFilter. The set of core properties is defined below. In addition, ThingTemplate may contain other properties as well as defined in the Thing Description from which the Thing object is created.
       
    
       
      
         
    • 
-          The name optional attribute represents the name of the Thing as DOMString.
+          The name attribute represents the name of the Thing as DOMString. In the Thing Description this attribute is mandatory, but in ThingFilter it is optional.
         
      • 
         
    • 
           The id optional attribute represents an application provided hint for the unique identifier of the Thing, typically a URI, IRI, or URN as USVString. Note that this is not the same as the JSON-LD @id attribute. Also note that the WoT Runtime may override this with a different value when exposing the Thing.
@@ -542,7 +542,9 @@ 
      Data types used in a Thing
      
         typedef (unsigned long or unrestricted double) Number;
         dictionary ValueType {
           required boolean type;
-          boolean required;
+          boolean required = "false";
+          DOMString description;
+          boolean const;
         };
         dictionary BooleanValueType: ValueType {
           const type = "boolean";
@@ -551,6 +553,7 @@ 
      Data types used in a Thing
      
         dictionary StringValueType: ValueType {
           const type = "string";
           USVString value;
+          sequence<DOMString>? enum;
         };
         dictionary NumberValueType: ValueType {
           const type = "number";

From e93c508ef2f525f73adcb23e215e0099b9766a81 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Tue, 5 Jun 2018 11:19:31 +0300
Subject: [PATCH 215/464] Added Interaction definition. Fixed most warnings by
 defining the missing sections.

Signed-off-by: Zoltan Kis 
---
 index.html | 429 ++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 328 insertions(+), 101 deletions(-)

diff --git a/index.html b/index.html
index 5e087420..66ae5db2 100644
--- a/index.html
+++ b/index.html
@@ -97,10 +97,10 @@
 
   
      
     
      
-      The Web of Things (WoT) provides layered interoperability between Things by using the WoT Interfaces.
+      The overall Web of Things (WoT) concepts are described in the [WoT Architecture](https://w3c.github.io/wot-architecture/) document. The Web of Things is made of entities (Things) that can describe their capabilities in a machine-interpretable format, the Thing Description (TD) and expose these capabilities through the WoT Interface, 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.
     
      
     
      
-      This specification describes a programming interface representing the WoT Interface that allows scripts run on a Thing to discover and consume (retrieve) other Things and to expose Things characterized by  WoT Interactions, i.e. Properties, Actions and Events.
+      This specification describes a programming interface representing the WoT Interface that allows scripts run on a Thing to discover and consume (retrieve) other Thing Descriptions and to expose Things characterized by  WoT Interactions specified by a script.
     
      
     
      
       Scripting is an optional "convenience" building block in WoT and it is typically used in gateways that are able to run a WoT Runtime and script management, providing a convenient way to extend WoT support to new types of endpoints and implement WoT applications like Thing Directory.
@@ -119,14 +119,13 @@
 
   
       
      Introduction
      
     
      
-      The overall WoT concepts are described in the [WoT Architecture](https://w3c.github.io/wot-architecture/) document.
-      The Web of Things is made of entities (Things) that can describe their capabilities in a machine-interpretable format, the Thing Description (TD) and expose these capabilities through the WoT Interface. Support for scripting is optional for WoT devices.
+      WoT provides layered interoperability based on how Things are modeled: as being "consumed" and "exposed".
     
      
     
      
-      By consuming a TD, a client Thing creates a runtime resource model that allows accessing the Properties, Actions and Events exposed by the server Thing.
+      By consuming a TD, a client Thing creates a runtime resource model that allows accessing the Properties, Actions and Events exposed by the  server Thing exposed on a remote device.
     
      
     
      
-      Exposing a Thing requires defining a Thing Description (TD) and instantiating a software stack needed to serve requests for accessing the exposed Properties, Actions and Events. This specification describes how to expose and consume Things by a script.
+      Exposing a Thing requires defining a Thing Description (TD) and instantiating a software stack to serve requests for accessing the exposed Properties, Actions and Events. This specification describes how to expose and consume Things by a script.
     
      
     
      
       Typically scripts are meant to be used on devices able to provide resources (with a WoT interface) for managing (installing, updating, running) scripts, such as bridges or gateways that expose and control simpler devices as WoT Things.
@@ -147,10 +146,10 @@
     
        
       
      • Discover all Things in the WoT network by sending a broadcast request.
        • 
       
      • Discover Things running in the local WoT Runtime.
        • 
-      
      • Discover nearby Things, for instance by NFC or Bluetooth.
        • 
+      
      • Discover nearby Things, for instance connected by NFC or Bluetooth.
        • 
       
      • Discover Things by sending a discovery request to a given registry.
        • 
       
      • Discover Things by filters defined on Thing Descriptions
        • 
-      
      • Discover Things by semantic filters.
        • 
+      
      • Discover Things by semantic queries.
        • 
       
      • Stop or suppress an ongoing discovery process.
        • 
       
      • 
           Optionally specify a timeout to the discovery process after which it is stopped/suppressed.
@@ -221,7 +220,7 @@ 
        The WoT object
        
     
        The WoT object is the API entry point and it is exposed by an implementation of the WoT Runtime. The WoT object does not expose properties, only methods for discovering, consuming and exposing a Thing.
     
        
     
        
-       Browser implementations SHOULD use a namespace object such as wot, and [Node.js](https://nodejs.org/en/)-like runtimes MAY provide the API object through the [`require()`](https://nodejs.org/api/modules.html) or [`import`](http://www.ecma-international.org/ecma-262/6.0/#sec-imports) mechanism.
+       Browser implementations SHOULD use a namespace object such as navigator.wot. Node.js-like runtimes MAY provide the API object through the require() or import mechanism.
     
        
     
               // [SecureContext]
@@ -243,6 +242,10 @@ 
        The WoT object
        
       The algorithms for the WoT methods will be specified later, including error handling and security considerations.
     
        
 
+    
        
+      The ThingModel type represents either a ThingTemplate, or a ThingDescription or a ConsumedThing object.
+    
        
+
     
        
     
        The ThingDescription type
        
       
        
@@ -275,7 +278,7 @@ 
        The ThingTemplate dictionary
        
           The security optional attribute represents security metadata defined by the Security dictionary;
         
        • 
         
      • 
-          The properties optional attribute represents a dictionary with keys that correspond to Property names and values of type PropertyTemplate.
+          The properties optional attribute represents a dictionary with keys that correspond to Property names and values of type PropertyInit.
         
        • 
         
      • 
           The actions optional attribute represents a dictionary with keys that correspond to Action names and values of type ActionInit.
@@ -284,7 +287,7 @@ 
        The ThingTemplate dictionary
        
           The events optional attribute represents a dictionary with keys that correspond to Event names and values of type EventInit.
         
        • 
         
      • 
-          The links optional attribute represents an array WebLink objects.
+          The links optional attribute represents an array of WebLink objects.
         
        • 
         
      • 
           The @context optional attribute represents a semantic context as USVString.
@@ -306,32 +309,29 @@ 
         The Security dictionary
        
       
        
         Contains security related configuration.
       
        
-    
        -      dictionary Security {
-        required DOMString scheme;
-        any in;
-      };
-    
        
+      
        +        dictionary Security {
+          required DOMString scheme;
+          any in;
+        };
+      
        
       
        
+        The scheme property represents the identification of the security scheme to be used for the Thing, for instance
         
          
-          
        • 
-            The scheme property represents the identification of the security scheme to be used for the Thing, for instance
-            
            
-              
          •  "basic+https",
            • 
-              
          •  "digest+https",
            • 
-              
          •  "bearer+https",
            • 
-              
          •  "bearer+coaps",
            • 
-              
          •  "pop+https", 
            • 
-              
          •  "pop+coaps", 
            • 
-              
          •  "apikey+https", 
            • 
-              
          •  "apikey+coaps", 
            • 
-              
          •  "ocf+coaps". 
            • 
-          
          
-          
        • 
-            The in property represents security initialization data as described in the [Security metadata description](https://github.com/w3c/wot-security/blob/master/wot-security-metadata.md).
-          
          • 
+          
        •  "basic+https",
          • 
+          
        •  "digest+https",
          • 
+          
        •  "bearer+https",
          • 
+          
        •  "bearer+coaps",
          • 
+          
        •  "pop+https", 
          • 
+          
        •  "pop+coaps", 
          • 
+          
        •  "apikey+https", 
          • 
+          
        •  "apikey+coaps", 
          • 
+          
        •  "ocf+coaps". 
          • 
         
        
       
        
+      
        
+        The in property represents security initialization data as described in the [Security metadata description](https://github.com/w3c/wot-security/blob/master/wot-security-metadata.md).
+      
        
     
      
 
     
       
       The fetch() method
      
@@ -516,62 +516,239 @@ 
      Data types used in a Thing
      
     
      
       Every Thing describes its metadata as defined in ThingTemplate, and basic interactions as defined in ConsumedThing: Properties, Actions and Events. The following data types are used for representing these interactions, as defined in [[!WOT-TD]].
     
      
-    
      Links and Forms
      
+
+    
      The Link dictionary
      
       
      -        [NoInterfaceObject]
         dictionary Link {
           required USVString href;
           USVString mediaType;
           DOMString rel;
         };
+      
      
+      
      
+        The href property is a hypertext reference that defines the Link.
+      
      
+      
      
+        The mediaType property represents the IANA media type associated with the Link.
+      
      
+      
      
+        The rel property represents a semantic label that specifies how to interact with the linked resource.
+      
      
+    
      
+
+    
      The WebLink dictionary
      
+      
               dictionary WebLink: Link {
           USVString anchor;
         };
+      
      
+      
      
+        The anchor property represents a URI that overrides the default context of a Link.
+      
      
+    
      
+
+    
      The Form dictionary
      
+      
               dictionary Form: Link {
-          DOMString security;
+          Security security;
         };
       
      
+      
      
+        The security property represents the security requirements for the linked resource.
+      
      
     
      
 
-    
      Value types
      
+    
      Value types
      
       
      
         Value types are used in Property, Event and Action parameter definitions in a ThingTemplate. Basically correspond to a JSON object definition.
       
      
+
+      
      The JSONType enumeration type
      
+        
      +          enum JSONType { "boolean", "number", "string", "object", "array" };
+        
      
+        
      
+          Defines the types that values can take, i.e. "boolean", "number", "string", "object" and "array".
+        
      
+      
      
+
+      
      The Number type
      
+        
      +          typedef (long or unrestricted double) Number;
+        
      
+        
      
+          A number is either an integer or floating point number supported by the underlying platform. A number value may have associated a permited range between a minimum and maximum value.
+        
      
+      
      
+
+      
      The ValueType dictionary
      
+        
      +          dictionary ValueType {
+            required JSONType type;
+            boolean required = "false";
+            DOMString description;
+            boolean const;
+          };
+        
      
+        
      
+          Represents the common properties of a value type definition.
+        
      
+        
      
+          The type property represents the value type enumerated in JSONType.
+        
      
+        
      
+          The required property tells whether this value is required to be speficied.
+        
      
+        
      
+          The description property represents a textual description of the value.
+        
      
+        
      
+          The const property tells whether this value is constant.
+        
      
+      
      
+
+      
      The NumberValueType dictionary
      
+        
      +          dictionary NumberValueType: ValueType {
+            const type = "number";
+            Number value;
+            Number minimum;
+            Number maximum;
+          };
+        
      
+        
      
+          The type property MUST have the value "number".
+        
      
+        
      
+          The value property represents the numeric value.
+        
      
+        
      
+          The minimum property may be present when the value is of type "number" and if present, it defines the minimum value that can be used.
+        
      
+        
      
+          The maximum property may be present when the value is of type "number" and if present, it defines the maximum value that can be used.
+        
      
+      
      
+
+      
      The BooleanValueType dictionary
      
+        
      +          dictionary BooleanValueType: ValueType {
+            const type = "boolean";
+            boolean value;
+          };
+        
      
+        
      
+          The type property MUST have the value "boolean".
+        
      
+        
      
+          The value property represents the boolean value.
+        
      
+      
      
+
+      
      The StringValueType dictionary
      
+        
      +          dictionary StringValueType: ValueType {
+            const type = "string";
+            USVString value;
+            sequence<DOMString>? enum;
+          };
+        
      
+        
      
+          The type property MUST have the value "string".
+        
      
+        
      
+          The value property represents the string value.
+        
      
+        
      
+          The enum property represents the list of allowed string values as a string array.
+        
      
+      
      
+
+      
      The ObjectValueType dictionary
      
+        
      +          dictionary ObjectValueType: ValueType {
+            const type = "object";
+            maplike<DOMString, ValueType> properties;
+          };
+        
      
+        
      
+          The type property MUST have the value "object".
+        
      
+        
      
+          The properties property is a dictionary that contains the object properties.
+        
      
+      
      
+
+      
      The ArrayValueType dictionary
      
+        
      +          dictionary ArrayValueType: ValueType {
+            const type = "array";
+            FrozenArray<ValueType> items;
+            unsigned long minItems;
+            unsigned long maxItems;
+          };
+        
      
+        
      
+          The type property MUST have the value "array".
+        
      
+        
      
+          The items property is an array of ValueType elements.
+        
      
+        
      
+          The minItems property represents the minimum number of elements required to be in the array.
+        
      
+        
      
+          The maxItems property represents the maximum number of elements that can be specified in the array.
+        
      
+      
      
+    
      
+
+    
      
+      
      The Interaction interface
      
+      
      
+        The Interaction interface is an abstract class to represent Thing interactions: Properties, Actions and Events.
+      
      
+      
      
+        The InteractionInit dictionary holds the common properties of PropertyInit, ActionInit and EventInit dictionaries used for initializing ThingProperty, ThingAction and ThingEvent objects in a ThingTemplate dictionary used for creating an ExposedThing object.
+      
      
+
       
      -        enum JSONType { "boolean", "number", "string", "object", "array" };
-        typedef (unsigned long or unrestricted double) Number;
-        dictionary ValueType {
-          required boolean type;
-          boolean required = "false";
-          DOMString description;
-          boolean const;
-        };
-        dictionary BooleanValueType: ValueType {
-          const type = "boolean";
-          boolean value;
-        };
-        dictionary StringValueType: ValueType {
-          const type = "string";
-          USVString value;
-          sequence<DOMString>? enum;
-        };
-        dictionary NumberValueType: ValueType {
-          const type = "number";
-          Number value;
-          Number minimum;
-          Number maximum;
-        };
-        dictionary ObjectValueType: ValueType {
-          const type = "object";
-          maplike<DOMString, ValueType> properties;
-        };
-        dictionary ArrayValueType: ValueType {
-          const type = "array";
-          FrozenArray<ValueType> items;
-          unsigned long minItems;
-          unsigned long maxItems;
+        interface Interaction {
+          attribute DOMString label;
+          readonly attribute FrozenArray<Form> forms;
+          readonly attribute FrozenArray<Link> links;
         };
+        Interaction implements Observable;
       
      
+      
      
+        The label property represents a text label for the interaction.
+      
      
+      
      
+        The forms read-only property represents the protocol bindings initialization data.
+      
      
+      
      
+        The links read-only property represents an array of Links attached to the interaction.
+      
      
+
+      
      The InteractionInit dictionary
      
+        
      +          dictionary InteractionInit {
+            DOMString label;
+            sequence<Form> forms;
+            sequence<Link> links;
+          };
+        
      
+        
      
+          The label property initializes the text label for the interaction.
+        
      
+        
      
+          The forms read-only property initializes the protocol bindings initialization data.
+        
      
+        
      
+          The links read-only property initializes the array of Links attached to the interaction.
+        
      
+      
      
+
     
      
 
     
      
@@ -580,35 +757,25 @@ 
      The ThingProperty interface
      
         The ThingProperty interface is used in ConsumedThing and ExposedThing objects to represent Thing Property interactions.
       
      
       
      
-        The PropertyTemplate dictionary is used for initializing Property objects in a ThingTemplate dictionary used for creating an ExposedThing object. It MUST implement one of the ValueType dictionaries.
+        The PropertyInit dictionary is used for initializing Property objects in a ThingTemplate dictionary used for creating an ExposedThing object. It MUST implement one of the ValueType dictionaries.
       
      
       
      -        dictionary PropertyTemplate: ValueType {
-          DOMString label;
-          boolean writable = false;
-          boolean observable = false;
-          boolean const;
-          sequence<Form> forms;
-        };
-        interface ThingProperty {
-          // getter for PropertyTemplate properties
+        interface ThingProperty: Interaction {
+          // getter for PropertyInit properties
           getter any(DOMString name);
           // get and set interface for the Property
           Promise<any> get();
           Promise set(any value);
         };
-        ThingProperty implements PropertyTemplate;
+        ThingProperty implements PropertyInit;
         ThingProperty implements Observable;
       
      
       
      
-        The ThingProperty interface contains all the properties defined on PropertyTemplate as read-only properties.
+        The ThingProperty interface contains all the properties defined on PropertyInit as read-only properties.
       
      
       
      
         The type read-only property represents the type definition for the Property. If it matches a JSONType, then it MUST implement the corresponding ValueType dictionary.
       
      
-      
      
-        The label read-only property represents a text label for the Property.
-      
      
       
      
         The writable read-only property tells whether the Property value can be updated. If it is false, then the set(value) method SHOULD always reject.
       
      
@@ -616,44 +783,95 @@ 
      The ThingProperty interface
      
         The observable read-only property tells whether the Property supports subscribing to value change notifications. If it is false, then the subscribe() method SHOULD always fail.
       
      
       
      
-        The const read-only property tells whether the Property value is a constant. If true, the set() and subscribe() methods SHOULD always fail.
+        The const read-only property - defined in ValueType - tells whether the Property value is a constant. If true, the set() and subscribe() methods SHOULD always fail.
       
      
       
      
-        The required read-only property tells whether the Property should be always present on the ExposedThing object.
+        The required read-only property  - defined in ValueType - tells whether the Property should be always present on the ExposedThing object.
       
      
       
      
-        The forms read-only property represents the protocol bindings initialization data.
+        The get() method will fetch the value of the Property. Returns a Promise that resolves with the value, or rejects with an error.
+      
      
+      
      
+        The set() method will attempt to set the value of the Propertyspecified in the value argument. Returns a Promise that resolves on success, or rejects on an error.
       
      
+
+      
      The PropertyInit dictionary
      
+        
      +          dictionary PropertyInit: InteractionInit {
+            boolean writable = false;
+            boolean observable = false;
+          };
+          PropertyInit implements ValueType;
+        
      
+      
      
+        The writable property initializes access to the Property value. The default value is false.
+      
      
+      
      
+        The observable property initializes observability access to the Property. The default value is false.
+      
      
+      
      
     
      
 
     
      
       
      The ThingAction interface
      
       
      -        dictionary ActionInit: InteractionInit {
-          DOMString label;
-          ValueType input;
-          ValueType output;
-          DOMString description;
-          sequence<Form> forms;
-        };
         interface ThingAction: Interaction {
           readonly attribute ValueType input;
           readonly attribute ValueType output;
           readonly attribute DOMString description;
-          readonly attribute DOMString label;
-          readonly attribute FrozenArray<Form> forms;
           Promise<any> run();
         };
       
      
+      
      
+        The input read-only property represents the input of type ValueType to the ThingAction. Multiple arguments can be provided by applications as an array or as an object.
+      
      
+      
      
+        The output read-only property represents the output of type ValueType of the ThingAction.
+      
      
+      
      
+        The description read-only property represents a human-readable textual description of the Action interaction.
+      
      
+      
      
+        The run() method when invoked, starts the Action interaction and returns a Promise that will reject with an error or will resolve with a value defined by the output property.
+      
      
+
+      
      The ActionInit dictionary
      
+        
      +          dictionary ActionInit: InteractionInit {
+            ValueType input;
+            ValueType output;
+            DOMString description;
+          };
+        
      
+        
      
+          The input property initializes the input of type ValueType to the ThingAction. Multiple arguments can be provided by applications as an array or as an object.
+        
      
+        
      
+          The output property initializes the output of type ValueType of the ThingAction. The value is overridden when the action is executed.
+        
      
+        
      
+          The description read-only property initializes a human-readable textual description of the Action interaction.
+        
      
+      
      
     
      
 
-    
      Events
      
+    
      The ThingEvent interface
      
       
               interface ThingEvent {
         };
         ThingEvent implements ThingProperty;
-        typedef PropertyTemplate EventInit;
       
      
+      
      
+        The data events are carrying is represented as a Property. ThingEvent SHOULD also implement the event mechanism of the underlying platform (such as a DOM Event or a Node.js Event).
+      
      
+      
      The EventInit dictionary
      
+        
      +          typedef PropertyInit EventInit;
+        
      
+        
      
+          The value an event is carrying is initialized as a Property value.
+        
      
+      
      
     
      
   
      
 
@@ -676,6 +894,18 @@ 
      The ConsumedThing interface
      
     
      
       ConsumedThing represents a local proxy object of the remote Thing.
     
      
+    
      
+      The properties property represents a dictionary of ThingProperty items.
+    
      
+    
      
+      The actions property represents a dictionary of ThingAction items.
+    
      
+    
      
+      The events property represents a dictionary of ThingEvent items.
+    
      
+    
    • 
+      The links property represents an array of WebLink objects.
+    
      • 
 
     
      
       
      Examples
      
@@ -1235,9 +1465,6 @@ 
      The Observable interface
      
       The following problems are being discussed and need most attention:
     
      
       
        
-        
      • 
-          Revised API for tracking the TD better (https://github.com/w3c/wot-scripting-api/issues/96).
-        
        • 
         
      • 
           Security related metadata (https://github.com/w3c/wot-scripting-api/issues/91).
         
        • 

From d27ab85e4c4ca19a985eab840a3bce2ce5c9b1d2 Mon Sep 17 00:00:00 2001
From: danielpeintner 
Date: Thu, 7 Jun 2018 16:50:27 +0200
Subject: [PATCH 216/464] fix respec issues (see
 https://github.com/w3c/respec/issues/1508)

---
 index.html | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/index.html b/index.html
index 66ae5db2..939937b4 100644
--- a/index.html
+++ b/index.html
@@ -305,7 +305,7 @@ 
        The ThingTemplate dictionary
        
     
       
 
     
      
-      
       The Security dictionary
      
+      
       The Security dictionary
      
       
      
         Contains security related configuration.
       
      
@@ -572,7 +572,7 @@ 
      Data types used in a Thing
      
         
      
       
      
 
-      
      The Number type
      
+      
      The Number type
      
         
                 typedef (long or unrestricted double) Number;
         
      

From 5a486ea042634de293a42a11648caee4ff901ccb Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Mon, 11 Jun 2018 21:09:01 +0300
Subject: [PATCH 217/464] Fix JSONType, Interaction and PropertyInit
 definitions

Signed-off-by: Zoltan Kis 
---
 index.html | 37 +++++++++++++------------------------
 1 file changed, 13 insertions(+), 24 deletions(-)

diff --git a/index.html b/index.html
index 939937b4..9f3c21c5 100644
--- a/index.html
+++ b/index.html
@@ -565,10 +565,10 @@ 
      Data types used in a Thing
      
 
       
      The JSONType enumeration type
      
         
      -          enum JSONType { "boolean", "number", "string", "object", "array" };
+          enum JSONType { "boolean", "integer", "number", "string", "object", "array" };
         
      
         
      
-          Defines the types that values can take, i.e. "boolean", "number", "string", "object" and "array".
+          Defines the types that values can take, i.e. "boolean", "integer", "number", "string", "object" and "array".
         
      
       
      
 
@@ -610,17 +610,17 @@ 
      Data types used in a Thing
      
       
      The NumberValueType dictionary
      
         
                 dictionary NumberValueType: ValueType {
-            const type = "number";
+            required DOMString type;
             Number value;
             Number minimum;
             Number maximum;
           };
         
      
         
      
-          The type property MUST have the value "number".
+          The type property MUST have either the value "number" (representing a floating point number) or "integer" (representing an integer) as defined by the underlying platform.
         
      
         
      
-          The value property represents the numeric value.
+          The value property represents the numeric value, cast to integer if type is "integer" or to floating point number if the value of type is "number". If not provided in the dictionary object, it SHOULD be initialized to "undefined". The value null is not accepted.
         
      
         
      
           The minimum property may be present when the value is of type "number" and if present, it defines the minimum value that can be used.
@@ -641,7 +641,7 @@ 
      Data types used in a Thing
      
           The type property MUST have the value "boolean".
         
      
         
      
-          The value property represents the boolean value.
+          The value property represents the boolean value. If not provided in the dictionary object, it SHOULD be initialized to "undefined". The value null is not accepted.
         
      
       
      
 
@@ -649,7 +649,7 @@ 
      Data types used in a Thing
      
         
                 dictionary StringValueType: ValueType {
             const type = "string";
-            USVString value;
+            USVString? value;
             sequence<DOMString>? enum;
           };
         
      
@@ -657,7 +657,7 @@ 
      Data types used in a Thing
      
           The type property MUST have the value "string".
         
      
         
      
-          The value property represents the string value.
+          The value property represents the string value. If not provided in the dictionary object, it SHOULD be initialized as undefined.
         
      
         
      
           The enum property represents the list of allowed string values as a string array.
@@ -668,14 +668,14 @@ 
      Data types used in a Thing
      
         
                 dictionary ObjectValueType: ValueType {
             const type = "object";
-            maplike<DOMString, ValueType> properties;
+            maplike<DOMString, ValueType>? properties;
           };
         
      
         
      
           The type property MUST have the value "object".
         
      
         
      
-          The properties property is a dictionary that contains the object properties.
+          The properties property is a dictionary that contains the object properties. If not provided in the dictionary object, it SHOULD be initialized to "undefined". The value null is accepted, as well as an empty object.
         
      
       
      
 
@@ -692,7 +692,7 @@ 
      Data types used in a Thing
      
           The type property MUST have the value "array".
         
      
         
      
-          The items property is an array of ValueType elements.
+          The items property is an array of ValueType elements. If not provided in the dictionary object, it SHOULD be initialized to "undefined". The value null is not accepted.
         
      
         
      
           The minItems property represents the minimum number of elements required to be in the array.
@@ -716,7 +716,6 @@ 
      The Interaction interface
      
         interface Interaction {
           attribute DOMString label;
           readonly attribute FrozenArray<Form> forms;
-          readonly attribute FrozenArray<Link> links;
         };
         Interaction implements Observable;
    @@ -724,29 +723,18 @@

    The Interaction interface

    The label property represents a text label for the interaction.

    - The forms read-only property represents the protocol bindings initialization data. -

    -

    - The links read-only property represents an array of Links attached to the interaction. + The forms read-only property represents the protocol bindings initialization data and is initialized by the WoT Runtime.

    The InteractionInit dictionary

               dictionary InteractionInit {
             DOMString label;
-            sequence<Form> forms;
-            sequence<Link> links;
           };

    The label property initializes the text label for the interaction.

    -

    - The forms read-only property initializes the protocol bindings initialization data. -

    -

    - The links read-only property initializes the array of Links attached to the interaction. -

    @@ -796,6 +784,7 @@

    The ThingProperty interface

    The PropertyInit dictionary

    + Defines the standardized part of the dictionary that initializes a ThingProperty object. 
               dictionary PropertyInit: InteractionInit {
             boolean writable = false;

From 44181db826f6242515ea357b2afda58a651d056b Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Mon, 11 Jun 2018 21:21:30 +0300
Subject: [PATCH 218/464] Fix ExposedThing add...() methods by adding a 'name'
 argument

Signed-off-by: Zoltan Kis 
---
 index.html | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/index.html b/index.html
index 9f3c21c5..269b3929 100644
--- a/index.html
+++ b/index.html
@@ -945,11 +945,11 @@ 
    The ExposedThing interface
    
         Promise<void> destroy();
         Promise<void> emitEvent(DOMString eventName, any payload);
         // define Thing Description modifiers
-        ExposedThing addProperty(ThingProperty property);
+        ExposedThing addProperty(DOMString name, ThingProperty property);
         ExposedThing removeProperty(DOMString name);
-        ExposedThing addAction(ThingAction action);
+        ExposedThing addAction(DOMString name, ThingAction action);
         ExposedThing removeAction(DOMString name);
-        ExposedThing addEvent(ThingEvent event);
+        ExposedThing addEvent(DOMString name, ThingEvent event);
         ExposedThing removeEvent(DOMString name);
         // define request handlers
         ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
@@ -981,7 +981,7 @@ 
    The ExposedThing interface
    
 
     
     
    The addProperty() method
    
       
    
-        Adds a Property defined by the argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+        Adds a Property with name defined by the name argument and qualifiers and initialization value provided by the property argument of type ThingProperty. It updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
    
     
     
 
@@ -993,7 +993,7 @@ 
    The ExposedThing interface
    
 
     
     
    The addAction() method
    
       
    
-        Adds an Action to the Thing object as defined by the action argument of type ThingAction and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+        Adds an Action with name defined by the name argument and qualifiers and initialization value provided by the action argument of type ThingActionto the Thing object and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
    
     
     
 
@@ -1005,7 +1005,7 @@ 
    The ExposedThing interface
    
 
     
     
    The addEvent() method
    
       
    
-        Adds an event to the Thing object as defined by the event argument of type ThingEvent and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+        Adds an event with name defined by the name argument and qualifiers and initialization value provided by the event argument of type ThingEventto the Thing object and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
    
     
    
 

From 86a783300d94583880980fffe9c9dae99bf1b1b3 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Tue, 12 Jun 2018 18:09:51 +0300
Subject: [PATCH 219/464] Fix #120: parameters to adding interactions

Signed-off-by: Zoltan Kis 
---
 index.html | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/index.html b/index.html
index 269b3929..7cc09a3e 100644
--- a/index.html
+++ b/index.html
@@ -808,7 +808,7 @@ 
    The ThingAction interface
    
           readonly attribute ValueType input;
           readonly attribute ValueType output;
           readonly attribute DOMString description;
-          Promise<any> run();
+          Promise<any> run(any input);
         };

    @@ -945,11 +945,11 @@

    The ExposedThing interface

    Promise<void> destroy(); Promise<void> emitEvent(DOMString eventName, any payload); // define Thing Description modifiers - ExposedThing addProperty(DOMString name, ThingProperty property); + ExposedThing addProperty(DOMString name, ThingPropertyInit property); ExposedThing removeProperty(DOMString name); - ExposedThing addAction(DOMString name, ThingAction action); + ExposedThing addAction(DOMString name, ThingActionInit action); ExposedThing removeAction(DOMString name); - ExposedThing addEvent(DOMString name, ThingEvent event); + ExposedThing addEvent(DOMString name, ThingEventInit event); ExposedThing removeEvent(DOMString name); // define request handlers ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler); @@ -981,7 +981,7 @@

    The ExposedThing interface

    The addProperty() method

    - Adds a Property with name defined by the name argument and qualifiers and initialization value provided by the property argument of type ThingProperty. It updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining. + Adds a Property with name defined by the name argument and qualifiers and initialization value provided by the property argument of type PropertyInit. It updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.

    @@ -993,7 +993,7 @@

    The ExposedThing interface

    The addAction() method

    - Adds an Action with name defined by the name argument and qualifiers and initialization value provided by the action argument of type ThingActionto the Thing object and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining. + Adds an Action with name defined by the name argument and qualifiers and initialization value provided by the action argument of type ActionInitto the Thing object and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.

    @@ -1005,7 +1005,7 @@

    The ExposedThing interface

    The addEvent() method

    - Adds an event with name defined by the name argument and qualifiers and initialization value provided by the event argument of type ThingEventto the Thing object and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining. + Adds an event with name defined by the name argument and qualifiers and initialization value provided by the event argument of type EventInitto the Thing object and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.

    From fb1c06d9b9c5584c5da4efaf172ec975a185a5cb Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Tue, 12 Jun 2018 19:38:15 +0300 Subject: [PATCH 220/464] Fix ValueType usage. Add the value-matching algorithm. Signed-off-by: Zoltan Kis --- index.html | 159 +++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 131 insertions(+), 28 deletions(-) diff --git a/index.html b/index.html index 7cc09a3e..947e70a2 100644 --- a/index.html +++ b/index.html @@ -611,7 +611,6 @@

    Data types used in a Thing

               dictionary NumberValueType: ValueType {
             required DOMString type;
-            Number value;
             Number minimum;
             Number maximum;
           };
@@ -619,9 +618,6 @@ 
    Data types used in a Thing
    
         
    
           The type property MUST have either the value "number" (representing a floating point number) or "integer" (representing an integer) as defined by the underlying platform.
         
    
-        
    
-          The value property represents the numeric value, cast to integer if type is "integer" or to floating point number if the value of type is "number". If not provided in the dictionary object, it SHOULD be initialized to "undefined". The value null is not accepted.
-        
    
         
    
           The minimum property may be present when the value is of type "number" and if present, it defines the minimum value that can be used.
         
    
@@ -634,31 +630,23 @@ 
    Data types used in a Thing
    
         
               dictionary BooleanValueType: ValueType {
             const type = "boolean";
-            boolean value;
           };
         
    
         
    
           The type property MUST have the value "boolean".
         
    
-        
    
-          The value property represents the boolean value. If not provided in the dictionary object, it SHOULD be initialized to "undefined". The value null is not accepted.
-

    The StringValueType dictionary

               dictionary StringValueType: ValueType {
             const type = "string";
-            USVString? value;
             sequence<DOMString>? enum;
           };

    The type property MUST have the value "string".

    -

    - The value property represents the string value. If not provided in the dictionary object, it SHOULD be initialized as undefined. -

    The enum property represents the list of allowed string values as a string array.

    @@ -668,14 +656,18 @@

    Data types used in a Thing

               dictionary ObjectValueType: ValueType {
             const type = "object";
-            maplike<DOMString, ValueType>? properties;
+            maplike<DOMString, ValueType>? properties;
+            sequence<DOMString> required;
           };

    The type property MUST have the value "object".

    - The properties property is a dictionary that contains the object properties. If not provided in the dictionary object, it SHOULD be initialized to "undefined". The value null is accepted, as well as an empty object. + The properties property is a dictionary that contains the names and types of each of the object properties. If not provided in the dictionary object, it SHOULD be initialized to undefined. The value null is accepted, as well as an empty object. +

    +

    + The required property is a string array that containes the names that are mandatory to be present from the object properties. If not provided, it SHOULD be initialized to undefined. An empty array is accepted.

    @@ -683,7 +675,7 @@

    Data types used in a Thing

               dictionary ArrayValueType: ValueType {
             const type = "array";
-            FrozenArray<ValueType> items;
+            ValueType? items;
             unsigned long minItems;
             unsigned long maxItems;
           };
@@ -692,7 +684,7 @@ 
    Data types used in a Thing
    
           The type property MUST have the value "array".
         
    
         
    
-          The items property is an array of ValueType elements. If not provided in the dictionary object, it SHOULD be initialized to "undefined". The value null is not accepted.
+          The items property represents the type of the elements in the array. If not provided in the dictionary object, it SHOULD be initialized to "undefined". The value null is accepted.
         
    
         
    
           The minItems property represents the minimum number of elements required to be in the array.
@@ -780,7 +772,7 @@ 
    The ThingProperty interface
    
         The get() method will fetch the value of the Property. Returns a Promise that resolves with the value, or rejects with an error.
       
    
       
    
-        The set() method will attempt to set the value of the Propertyspecified in the value argument. Returns a Promise that resolves on success, or rejects on an error.
+        The set() method will attempt to set the value of the Propertyspecified in the value argument whose type SHOULD match the o9ne specified by the type property. Returns a Promise that resolves on success, or rejects on an error.
       
    
 
       
    The PropertyInit dictionary
    
@@ -789,6 +781,7 @@ 
    The ThingProperty interface
    
           dictionary PropertyInit: InteractionInit {
             boolean writable = false;
             boolean observable = false;
+            any value;  // initialization value
           };
           PropertyInit implements ValueType;
    @@ -798,6 +791,9 @@

    The ThingProperty interface

    The observable property initializes observability access to the Property. The default value is false.

    +

    + The value property represents the initialization value of the property. Its type should match the one defined in the type property. If not provided in the dictionary object, it SHOULD be initialized as undefined. +

    @@ -805,30 +801,30 @@

    The ThingProperty interface

    The ThingAction interface

             interface ThingAction: Interaction {
-          readonly attribute ValueType input;
-          readonly attribute ValueType output;
+          readonly attribute ValueType? input;
+          readonly attribute ValueType? output;
           readonly attribute DOMString description;
-          Promise<any> run(any input);
+          Promise<any> run(optional any inputValue);
         };

    - The input read-only property represents the input of type ValueType to the ThingAction. Multiple arguments can be provided by applications as an array or as an object. + The input read-only property represents the input of type ValueType to the ThingAction. Multiple arguments can be provided by applications as an array or as an object. If the value is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided.

    - The output read-only property represents the output of type ValueType of the ThingAction. + The output read-only property represents the output of type ValueType of the ThingAction. If the value is null or undefined, the action does not return any values.

    The description read-only property represents a human-readable textual description of the Action interaction.

    - The run() method when invoked, starts the Action interaction and returns a Promise that will reject with an error or will resolve with a value defined by the output property. + The run() method when invoked, starts the Action interaction with the input value provided by the inputValue argument. If inputValue is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided. Otherwise the type of inputValue SHOULD match the ValueType definition in the input property. Returns a Promise that will reject with an error or will resolve with a value of type defined by the output property.

    The ActionInit dictionary

               dictionary ActionInit: InteractionInit {
             ValueType input;
-            ValueType output;
+            ValueType? output;
             DOMString description;
           };
    @@ -836,7 +832,7 @@

    The ThingAction interface

    The input property initializes the input of type ValueType to the ThingAction. Multiple arguments can be provided by applications as an array or as an object.

    - The output property initializes the output of type ValueType of the ThingAction. The value is overridden when the action is executed. + The output property initializes the output of type ValueType of the ThingAction.

    The description read-only property initializes a human-readable textual description of the Action interaction. @@ -862,6 +858,113 @@

    The ThingAction interface

    + +

    The value-matching algorithm

    +

    + The value-matching algorithm is applied to a value input in relation to a valueType property of type ValueType, for instance the value and type properties of a PropertyInit object, or the inputValue parameter to the run() method of a ThingAction object in relation to the same object. It executes the following steps: +

      +
    1. + If valueType.type is not defined, or does not fully match a string enumerated in JSONType, return false. +
      2. +
    2. + Otherwise, if valueType.type is "boolean": if value is either true or false, then return true, otherwise return false. +
      3. +
    3. + Otherwise, if valueType.type is "integer": if value is not an integer type defined by the underlying platform (such as long or long long), then return false, otherwise execute the following sub-steps: +
        +
      1. + If valueType.minimum is defined and value is not greater or equal than that value, return false. +
        2. +
      2. + If valueType.maximum is defined and value is not less or equal than that value, return false. +
        3. +
      3. + Return true. +
        4. +
      +
      4. +
    4. + Otherwise, if valueType.type is "number", if value is not an integer or floating point type defined by the underlying platform (such as long or long long or double), then return false, otherwise otherwise execute the following sub-steps: +
        +
      1. + If valueType.minimum is defined and value is not greater or equal than that value, return false. +
        2. +
      2. + If valueType.maximum is defined and value is not less or equal than that value, return false. +
        3. +
      3. + Return true. +
        4. +
      +
      5. +
    5. + Otherwise, if valueType.type is "string": if value is not a string type defined by the underlying platform, then return false, otherwise return true. In this case the algorithm expects a third parameter valueType.enum and runs the following sub-steps: +
        +
      • + If valueType.enum is an array of strings, then if value fully matches one of the strings defined in the array, return true. +
        • +
      • + Otherwise, return false. +
        • +
      +
      6. +
    6. + Otherwise, if valueType.type is "array", execute the following sub-steps: +
        +
      1. + If valueType.minItems is defined, and value is not an array that contains at least valueType.minItems elements, return false. +
        2. +
      2. + If valueType.maxItems is defined, and value is not an array that contains at maximum valueType.maxItems elements, return false. +
        3. +
      3. + Otherwise, if value is not an array, return false. +
        4. +
      4. + Otherwise, if valueType.items is undefined, return false. +
        5. +
      5. + Otherwise, if valueType.items is null, return true (i.e. any type is accepted as array element, including heterogenous arrays). +
        6. +
      6. + Otherwise, for each element of the array value run the value-matching algorithm against the valueType.items object. If any of these runs returns false, then return false. +
        7. +
      7. + Otherwise, return true. +
        8. +
      +
      7. +
    7. + Otherwise, if type is "object", execute the following sub-steps: +
        +
      1. + If value is not an Object or null, return false. +
        2. +
      2. + If valueType.properties is not defined or is not null or it is not an object, return false. +
        3. +
      3. + If valueType.properties is null, return true (i.e. accept any object value). +
        4. +
      4. + For each string in the valueType.required array, if it does not match a property name in the value.properties object or in the value object, then return false. +
        5. +
      5. + For each property with name propName and value propValueType found in valueType.properties, run the following sub-steps: +
          +
        1. + If the result of applying the value-matching algorithm on the value value[propName] and propValueType is false, then return false. +
          2. +
        +
        6. +
      6. + Return true. +
      +
      8. +
    +

    +
    +
    @@ -945,11 +1048,11 @@

    The ExposedThing interface

    Promise<void> destroy(); Promise<void> emitEvent(DOMString eventName, any payload); // define Thing Description modifiers - ExposedThing addProperty(DOMString name, ThingPropertyInit property); + ExposedThing addProperty(DOMString name, PropertyInit property); ExposedThing removeProperty(DOMString name); - ExposedThing addAction(DOMString name, ThingActionInit action); + ExposedThing addAction(DOMString name, ActionInit action); ExposedThing removeAction(DOMString name); - ExposedThing addEvent(DOMString name, ThingEventInit event); + ExposedThing addEvent(DOMString name, EventInit event); ExposedThing removeEvent(DOMString name); // define request handlers ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler); From 6612d3953fd02a88c10a97ca68bbe28dd8c4d2c5 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 13 Jun 2018 14:45:18 +0300 Subject: [PATCH 221/464] Align data type names to the TD naming Signed-off-by: Zoltan Kis --- index.html | 72 +++++++++++++++++++++++++++--------------------------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/index.html b/index.html index 947e70a2..1689b478 100644 --- a/index.html +++ b/index.html @@ -563,9 +563,9 @@

    Data types used in a Thing

    Value types are used in Property, Event and Action parameter definitions in a ThingTemplate. Basically correspond to a JSON object definition.

    -

    The JSONType enumeration type

    +

    The DataType enumeration type

    -          enum JSONType { "boolean", "integer", "number", "string", "object", "array" };
+          enum DataType { "boolean", "integer", "number", "string", "object", "array" };

    Defines the types that values can take, i.e. "boolean", "integer", "number", "string", "object" and "array". @@ -581,10 +581,10 @@

    Data types used in a Thing

    -

    The ValueType dictionary

    +

    The DataSchema dictionary

    -          dictionary ValueType {
-            required JSONType type;
+          dictionary DataSchema {
+            required DataType type;
             boolean required = "false";
             DOMString description;
             boolean const;
@@ -594,7 +594,7 @@ 
    Data types used in a Thing
    
           Represents the common properties of a value type definition.
         
    
         
    
-          The type property represents the value type enumerated in JSONType.
+          The type property represents the value type enumerated in DataType.
         
    
         
    
           The required property tells whether this value is required to be speficied.
@@ -607,9 +607,9 @@ 
    Data types used in a Thing
    -

    The NumberValueType dictionary

    +

    The NumberSchema dictionary

    -          dictionary NumberValueType: ValueType {
+          dictionary NumberSchema: DataSchema {
             required DOMString type;
             Number minimum;
             Number maximum;
@@ -626,9 +626,9 @@ 
    Data types used in a Thing
    -

    The BooleanValueType dictionary

    +

    The BooleanSchema dictionary

    -          dictionary BooleanValueType: ValueType {
+          dictionary BooleanSchema: DataSchema {
             const type = "boolean";
           };
    @@ -637,9 +637,9 @@

    Data types used in a Thing

    -

    The StringValueType dictionary

    +

    The StringSchema dictionary

    -          dictionary StringValueType: ValueType {
+          dictionary StringSchema: DataSchema {
             const type = "string";
             sequence<DOMString>? enum;
           };
@@ -652,11 +652,11 @@ 
    Data types used in a Thing
    -

    The ObjectValueType dictionary

    +

    The ObjectSchema dictionary

    -          dictionary ObjectValueType: ValueType {
+          dictionary ObjectSchema: DataSchema {
             const type = "object";
-            maplike<DOMString, ValueType>? properties;
+            maplike<DOMString, DataSchema>? properties;
             sequence<DOMString> required;
           };
    @@ -671,11 +671,11 @@

    Data types used in a Thing

    -

    The ArrayValueType dictionary

    +

    The ArraySchema dictionary

    -          dictionary ArrayValueType: ValueType {
+          dictionary ArraySchema: DataSchema {
             const type = "array";
-            ValueType? items;
+            DataSchema? items;
             unsigned long minItems;
             unsigned long maxItems;
           };
@@ -737,7 +737,7 @@ 
    The ThingProperty interface
    
         The ThingProperty interface is used in ConsumedThing and ExposedThing objects to represent Thing Property interactions.
       
    
       
    
-        The PropertyInit dictionary is used for initializing Property objects in a ThingTemplate dictionary used for creating an ExposedThing object. It MUST implement one of the ValueType dictionaries.
+        The PropertyInit dictionary is used for initializing Property objects in a ThingTemplate dictionary used for creating an ExposedThing object. It MUST implement one of the DataSchema dictionaries.
       
    
       
             interface ThingProperty: Interaction {
@@ -754,7 +754,7 @@ 
    The ThingProperty interface
    
         The ThingProperty interface contains all the properties defined on PropertyInit as read-only properties.
       
    
       
    
-        The type read-only property represents the type definition for the Property. If it matches a JSONType, then it MUST implement the corresponding ValueType dictionary.
+        The type read-only property represents the type definition for the Property. If it matches a DataType, then it MUST implement the corresponding DataSchema dictionary.
       
    
       
    
         The writable read-only property tells whether the Property value can be updated. If it is false, then the set(value) method SHOULD always reject.
@@ -763,10 +763,10 @@ 
    The ThingProperty interface
    
         The observable read-only property tells whether the Property supports subscribing to value change notifications. If it is false, then the subscribe() method SHOULD always fail.
       
    
       
    
-        The const read-only property - defined in ValueType - tells whether the Property value is a constant. If true, the set() and subscribe() methods SHOULD always fail.
+        The const read-only property - defined in DataSchema - tells whether the Property value is a constant. If true, the set() and subscribe() methods SHOULD always fail.
       
    
       
    
-        The required read-only property  - defined in ValueType - tells whether the Property should be always present on the ExposedThing object.
+        The required read-only property  - defined in DataSchema - tells whether the Property should be always present on the ExposedThing object.
       
    
       
    
         The get() method will fetch the value of the Property. Returns a Promise that resolves with the value, or rejects with an error.
@@ -783,7 +783,7 @@ 
    The ThingProperty interface
    
             boolean observable = false;
             any value;  // initialization value
           };
-          PropertyInit implements ValueType;
+          PropertyInit implements DataSchema;
         
    
       
    
         The writable property initializes access to the Property value. The default value is false.
@@ -801,38 +801,38 @@ 
    The ThingProperty interface
    
       
    The ThingAction interface
    
       
             interface ThingAction: Interaction {
-          readonly attribute ValueType? input;
-          readonly attribute ValueType? output;
+          readonly attribute DataSchema? input;
+          readonly attribute DataSchema? output;
           readonly attribute DOMString description;
           Promise<any> run(optional any inputValue);
         };
       
    
       
    
-        The input read-only property represents the input of type ValueType to the ThingAction. Multiple arguments can be provided by applications as an array or as an object. If the value is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided.
+        The input read-only property represents the input of type DataSchema to the ThingAction. Multiple arguments can be provided by applications as an array or as an object. If the value is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided.
       
    
       
    
-        The output read-only property represents the output of type ValueType of the ThingAction. If the value is null or undefined, the action does not return any values.
+        The output read-only property represents the output of type DataSchema of the ThingAction. If the value is null or undefined, the action does not return any values.
       
    
       
    
         The description read-only property represents a human-readable textual description of the Action interaction.
       
    
       
    
-        The run() method when invoked, starts the Action interaction with the input value provided by the inputValue argument. If inputValue is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided. Otherwise the type of inputValue SHOULD match the ValueType definition in the input property. Returns a Promise that will reject with an error or will resolve with a value of type defined by the output property.
+        The run() method when invoked, starts the Action interaction with the input value provided by the inputValue argument. If inputValue is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided. Otherwise the type of inputValue SHOULD match the DataSchema definition in the input property. Returns a Promise that will reject with an error or will resolve with a value of type defined by the output property.
       
    
 
       
    The ActionInit dictionary
    
         
               dictionary ActionInit: InteractionInit {
-            ValueType input;
-            ValueType? output;
+            DataSchema input;
+            DataSchema? output;
             DOMString description;
           };
         
    
         
    
-          The input property initializes the input of type ValueType to the ThingAction. Multiple arguments can be provided by applications as an array or as an object.
+          The input property initializes the input of type DataSchema to the ThingAction. Multiple arguments can be provided by applications as an array or as an object.
         
    
         
    
-          The output property initializes the output of type ValueType of the ThingAction.
+          The output property initializes the output of type DataSchema of the ThingAction.
         
    
         
    
           The description read-only property initializes a human-readable textual description of the Action interaction.
@@ -861,10 +861,10 @@ 
    The ThingAction interface
    
 
     
    The value-matching algorithm
    
       
    
-        The value-matching algorithm is applied to a value input in relation to a valueType property of type ValueType, for instance the value and type properties of a PropertyInit object, or the inputValue parameter to the run() method of a ThingAction object in relation to the same object. It executes the following steps:
+        The value-matching algorithm is applied to a value input in relation to a valueType property of type DataSchema, for instance the value and type properties of a PropertyInit object, or the inputValue parameter to the run() method of a ThingAction object in relation to the same object. It executes the following steps:
         
      
           
    1. 
-            If valueType.type is not defined, or does not fully match a string enumerated in JSONType, return false.
+            If valueType.type is not defined, or does not fully match a string enumerated in DataType, return false.
           
      2. 
           
    2. 
             Otherwise, if valueType.type is "boolean": if value is either true or false, then return true, otherwise return false.
@@ -950,10 +950,10 @@ 
      The ThingAction interface
      
                 For each string in the valueType.required array, if it does not match a property name in the value.properties object or in the value object, then return false.
               
      3. 
               
    3. 
-                For each property with name propName and value propValueType found in valueType.properties, run the following sub-steps:
+                For each property with name propName and value propDataSchema found in valueType.properties, run the following sub-steps:
                 
        
                   
      1. 
-                    If the result of applying the value-matching algorithm on the value value[propName] and propValueType is false, then return false.
+                    If the result of applying the value-matching algorithm on the value value[propName] and propDataSchema is false, then return false.
                   
        2. 
                 
      
               
      4. 

From 71decb543cbd15ddcde77540d465b036e7782640 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Wed, 13 Jun 2018 15:11:39 +0300
Subject: [PATCH 222/464] Move Data types section to the end

Signed-off-by: Zoltan Kis 
---
 index.html | 1418 ++++++++++++++++++++++++++--------------------------
 1 file changed, 709 insertions(+), 709 deletions(-)

diff --git a/index.html b/index.html
index 1689b478..3ea46364 100644
--- a/index.html
+++ b/index.html
@@ -511,833 +511,833 @@ 
      The ThingFilter dictionary
      
     
     
   
     
 
-  
    
-    
    Data types used in a Thing
    
+  
    
+    
    The ConsumedThing interface
    
     
    
-      Every Thing describes its metadata as defined in ThingTemplate, and basic interactions as defined in ConsumedThing: Properties, Actions and Events. The following data types are used for representing these interactions, as defined in [[!WOT-TD]].
+      The ConsumedThing interface is a client API for sending requests to servers in order to retrieve or update Properties, invoke Actions, and observe Properties and Events.
+    
    
+    
    +      interface ConsumedThing {
+        readonly attribute maplike<DOMString, ThingProperty> properties;
+        readonly attribute maplike<DOMString, ThingAction> actions;
+        readonly attribute maplike<DOMString, ThingEvent> events;
+        readonly attribute FrozenArray<WebLink> links;
+        // getter for ThingTemplate properties
+        getter any(DOMString name);
+      };
+      ConsumedThing implements Observable;  // for TD changes
+    
    
+    
    
+      ConsumedThing represents a local proxy object of the remote Thing.
+    
    
+    
    
+      The properties property represents a dictionary of ThingProperty items.
+    
    
+    
    
+      The actions property represents a dictionary of ThingAction items.
+    
    
+    
    
+      The events property represents a dictionary of ThingEvent items.
     
    
+    
  • 
+      The links property represents an array of WebLink objects.
+    
    • 
 
-    
    The Link dictionary
    
-      
    -        dictionary Link {
-          required USVString href;
-          USVString mediaType;
-          DOMString rel;
+    
    
+      
    Examples
    
+      
    
+        Below a ConsumedThing interface example is given.
+      
    
+      
    +        try {
+          let subscription = wot.discover({ method: "local" }).subscribe(
+            td => {
+              let thing = wot.consume(td);
+              console.log("Thing " + thing.name + " has been consumed.");
+              let subscription = thing.onPropertyChange("temperature")
+                .subscribe(function(value) {
+                  console.log("Temperature + " has changed to " + value);
+                });
+              thing.actions["startMeasurement"].run({ units: "Celsius" })
+                .then(() => { console.log("Temperature measurement started."); })
+                .catch(e => {
+                   console.log("Error starting measurement.");
+                   subscription.unsubscribe();
+                 })
+            },
+            error => { console.log("Discovery error: " + error.message); },
+            () => { console.log("Discovery finished successfully");}
+          );
+        } catch(error) {
+          console.log("Error: " + error.message);
         };
       
    
+    
     
+  
     
+
+  
    
+    
    The ExposedThing interface
    
+    
    
+      The ExposedThing interface is the server API that allows defining request handlers, properties, Actions, and Events to a Thing. It also implements the ConsumedThing interface. An ExposedThing is created by the produce() method.
+    
    
+    
    +      ExposedThing implements ConsumedThing;
+      interface ExposedThing {
+        // getter for ThingTemplate properties
+        getter any(DOMString name);
+        // setter for ThingTemplate properties
+        setter void(DOMString name, any value);
+        // define how to expose and run the Thing
+        Promise<void> expose();
+        Promise<void> destroy();
+        Promise<void> emitEvent(DOMString eventName, any payload);
+        // define Thing Description modifiers
+        ExposedThing addProperty(DOMString name, PropertyInit property);
+        ExposedThing removeProperty(DOMString name);
+        ExposedThing addAction(DOMString name, ActionInit action);
+        ExposedThing removeAction(DOMString name);
+        ExposedThing addEvent(DOMString name, EventInit event);
+        ExposedThing removeEvent(DOMString name);
+        // define request handlers
+        ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
+        ExposedThing setPropertyWriteHandler(DOMString name, PropertyWriteHandler writeHandler);
+        ExposedThing setActionHandler(DOMString name, ActionHandler action);
+      };
+      callback PropertyReadHandler = Promise<any>();
+      callback PropertyWriteHandler = Promise<void>(any value);
+      callback ActionHandler = Promise<any>(any parameters);
+    
    
+
+    
     
    The expose() method
    
       
    
-        The href property is a hypertext reference that defines the Link.
+        Start serving external requests for the Thing, so that WoT interactions using Properties, Actions and Events will be possible.
       
    
+    
    
+
+    
     
    The destroy() method
    
       
    
-        The mediaType property represents the IANA media type associated with the Link.
+        Stop serving external requests for the Thing and destroy the object. Note that eventual unregistering should be done before invoking this method.
       
    
+    
    
+
+    
     
    The emitEvent() method
    
       
    
-        The rel property represents a semantic label that specifies how to interact with the linked resource.
+        Emits an the event initialized with the event name specified by the eventName argument and data specified by the payload argument.
       
    
     
    
 
-    
    The WebLink dictionary
    
-      
    -        dictionary WebLink: Link {
-          USVString anchor;
-        };
-      
    
+    
     
    The addProperty() method
    
       
    
-        The anchor property represents a URI that overrides the default context of a Link.
+        Adds a Property with name defined by the name argument and qualifiers and initialization value provided by the property argument of type PropertyInit. It updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+      
    
+    
     
+
+    
     
    The removeProperty() method
    
+      
    
+        Removes the Property specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
    
     
    
 
-    
    The Form dictionary
    
-      
    -        dictionary Form: Link {
-          Security security;
-        };
-      
    
+    
     
    The addAction() method
    
       
    
-        The security property represents the security requirements for the linked resource.
+        Adds an Action with name defined by the name argument and qualifiers and initialization value provided by the action argument of type ActionInitto the Thing object and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+      
    
+    
     
+
+    
     
    The removeAction() method
    
+      
    
+        Removes the Action specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
    
     
    
 
-    
    Value types
    
+    
     
    The addEvent() method
    
       
    
-        Value types are used in Property, Event and Action parameter definitions in a ThingTemplate. Basically correspond to a JSON object definition.
+        Adds an event with name defined by the name argument and qualifiers and initialization value provided by the event argument of type EventInitto the Thing object and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
    
+    
    
 
-      
    The DataType enumeration type
    
-        
    -          enum DataType { "boolean", "integer", "number", "string", "object", "array" };
-        
    
-        
    
-          Defines the types that values can take, i.e. "boolean", "integer", "number", "string", "object" and "array".
-        
    
-      
    
+    
     
    The removeEvent() method
    
+      
    
+        Removes the event specified by the name argument and updates the Thing Description. Returns a reference to the same object for supporting chaining.
+      
    
+    
    
 
-      
    The Number type
    
-        
    -          typedef (long or unrestricted double) Number;
-        
    
-        
    
-          A number is either an integer or floating point number supported by the underlying platform. A number value may have associated a permited range between a minimum and maximum value.
-        
    
-      
    
+    
    
+      
    The PropertyReadHandler callback
    
+      
    
+        A function that returns a Promise and resolves it with the value of the Property matching the name argument to the setPropertyReadHandler function, or rejects with an error if the property is not found or the value cannot be retrieved.
+      
    
+    
    
 
-      
    The DataSchema dictionary
    
-        
    -          dictionary DataSchema {
-            required DataType type;
-            boolean required = "false";
-            DOMString description;
-            boolean const;
-          };
-        
    
-        
    
-          Represents the common properties of a value type definition.
-        
    
-        
    
-          The type property represents the value type enumerated in DataType.
-        
    
-        
    
-          The required property tells whether this value is required to be speficied.
-        
    
-        
    
-          The description property represents a textual description of the value.
-        
    
-        
    
-          The const property tells whether this value is constant.
-        
    
-      
    
+    
    
+      
    The PropertyWriteHandler callback
    
+      
    
+        A function called with value as argument that returns a Promise which is resolved when the value of the Property matching the name argument to the setPropertyReadHandler function is updated with value, or rejects with an error if the property is not found or the value cannot be updated.
+      
    
+      
    
+        Note that this function is invoked by implementations before the property is updated, so the code in this callback function can invoke the readProperty() method to find out the old value of the property, if needed. Therefore the old value is not provided to this method.
+      
    
+    
    
 
-      
    The NumberSchema dictionary
    
-        
    -          dictionary NumberSchema: DataSchema {
-            required DOMString type;
-            Number minimum;
-            Number maximum;
-          };
-        
    
-        
    
-          The type property MUST have either the value "number" (representing a floating point number) or "integer" (representing an integer) as defined by the underlying platform.
-        
    
-        
    
-          The minimum property may be present when the value is of type "number" and if present, it defines the minimum value that can be used.
-        
    
-        
    
-          The maximum property may be present when the value is of type "number" and if present, it defines the maximum value that can be used.
-        
    
-      
    
+    
    
+      
    The ActionHandler callback
    
+      
    
+        A function called with a parameters dictionary argument assembled by the WoT runtime based on the Thing Description and the external client request. It returns a Promise that rejects with an error or resolves if the action is successful or ongoing (may also resolve with a control object such as an Observable for actions that need progress notifications or that can be canceled).
+      
    
+    
    
 
-      
    The BooleanSchema dictionary
    
-        
    -          dictionary BooleanSchema: DataSchema {
-            const type = "boolean";
-          };
-        
    
-        
    
-          The type property MUST have the value "boolean".
-        
    
-      
    
+    
     
    The setPropertyReadHandler() method
    
+      
    
+        Takes name as string argument and readHandler as argument of type PropertyReadHandler. Sets the handler function for reading the specified Property matched by name. Throws on error. Returns a reference to the same object for supporting chaining.
+      
    
+      
    
+         The readHandler callback function will implement reading a Property and SHOULD be called by implementations when a request for reading a Property is received from the underlying platform.
+      
    
+      
    
+        There SHOULD be at most one handler for any given Property and newly added handlers replace the old handlers. If no handler is initialized for any given Property, implementations SHOULD implement a default property read handler.
+      
    
+    
    
 
-      
    The StringSchema dictionary
    
-        
    -          dictionary StringSchema: DataSchema {
-            const type = "string";
-            sequence<DOMString>? enum;
-          };
-        
    
-        
    
-          The type property MUST have the value "string".
-        
    
-        
    
-          The enum property represents the list of allowed string values as a string array.
-        
    
-      
    
-
-      
    The ObjectSchema dictionary
    
-        
    -          dictionary ObjectSchema: DataSchema {
-            const type = "object";
-            maplike<DOMString, DataSchema>? properties;
-            sequence<DOMString> required;
-          };
-        
    
-        
    
-          The type property MUST have the value "object".
-        
    
-        
    
-          The properties property is a dictionary that contains the names and types of each of the object properties. If not provided in the dictionary object, it SHOULD be initialized to undefined. The value null is accepted, as well as an empty object.
-        
    
-        
    
-          The required property is a string array that containes the names that are mandatory to be present from the object properties. If not provided, it SHOULD be initialized to undefined. An empty array is accepted.
-        
    
-      
    
-
-      
    The ArraySchema dictionary
    
-        
    -          dictionary ArraySchema: DataSchema {
-            const type = "array";
-            DataSchema? items;
-            unsigned long minItems;
-            unsigned long maxItems;
-          };
-        
    
-        
    
-          The type property MUST have the value "array".
-        
    
-        
    
-          The items property represents the type of the elements in the array. If not provided in the dictionary object, it SHOULD be initialized to "undefined". The value null is accepted.
-        
    
-        
    
-          The minItems property represents the minimum number of elements required to be in the array.
-        
    
-        
    
-          The maxItems property represents the maximum number of elements that can be specified in the array.
-        
    
-      
    
-    
    
-
-    
    
-      
    The Interaction interface
    
-      
    
-        The Interaction interface is an abstract class to represent Thing interactions: Properties, Actions and Events.
-      
    
-      
    
-        The InteractionInit dictionary holds the common properties of PropertyInit, ActionInit and EventInit dictionaries used for initializing ThingProperty, ThingAction and ThingEvent objects in a ThingTemplate dictionary used for creating an ExposedThing object.
-      
    
-
-      
    -        interface Interaction {
-          attribute DOMString label;
-          readonly attribute FrozenArray<Form> forms;
-        };
-        Interaction implements Observable;
-      
    
+    
     
    The setPropertyWriteHandler() method
    
       
    
-        The label property represents a text label for the interaction.
+        Takes name as string argument and writeHandler as argument of type PropertyWriteHandler. Sets the handler function for writing the specified Property matched by name. Throws on error. Returns a reference to the same object for supporting chaining.
       
    
       
    
-        The forms read-only property represents the protocol bindings initialization data and is initialized by the WoT Runtime.
+        There SHOULD be at most one write handler for any given Property and newly added handlers replace the old handlers. If no write handler is initialized for any given Property, implementations SHOULD implement default property update and notifying observers on change.
       
    
-
-      
    The InteractionInit dictionary
    
-        
    -          dictionary InteractionInit {
-            DOMString label;
-          };
-        
    
-        
    
-          The label property initializes the text label for the interaction.
-        
    
-      
    
-
     
    
 
-    
    
-      
    The ThingProperty interface
    
-      
    
-        The ThingProperty interface is used in ConsumedThing and ExposedThing objects to represent Thing Property interactions.
-      
    
-      
    
-        The PropertyInit dictionary is used for initializing Property objects in a ThingTemplate dictionary used for creating an ExposedThing object. It MUST implement one of the DataSchema dictionaries.
-      
    
-      
    -        interface ThingProperty: Interaction {
-          // getter for PropertyInit properties
-          getter any(DOMString name);
-          // get and set interface for the Property
-          Promise<any> get();
-          Promise set(any value);
-        };
-        ThingProperty implements PropertyInit;
-        ThingProperty implements Observable;
-      
    
-      
    
-        The ThingProperty interface contains all the properties defined on PropertyInit as read-only properties.
-      
    
-      
    
-        The type read-only property represents the type definition for the Property. If it matches a DataType, then it MUST implement the corresponding DataSchema dictionary.
-      
    
-      
    
-        The writable read-only property tells whether the Property value can be updated. If it is false, then the set(value) method SHOULD always reject.
-      
    
-      
    
-        The observable read-only property tells whether the Property supports subscribing to value change notifications. If it is false, then the subscribe() method SHOULD always fail.
-      
    
-      
    
-        The const read-only property - defined in DataSchema - tells whether the Property value is a constant. If true, the set() and subscribe() methods SHOULD always fail.
-      
    
-      
    
-        The required read-only property  - defined in DataSchema - tells whether the Property should be always present on the ExposedThing object.
-      
    
-      
    
-        The get() method will fetch the value of the Property. Returns a Promise that resolves with the value, or rejects with an error.
-      
    
+    
     
    The setActionHandler() method
    
       
    
-        The set() method will attempt to set the value of the Propertyspecified in the value argument whose type SHOULD match the o9ne specified by the type property. Returns a Promise that resolves on success, or rejects on an error.
+        Takes name as string argument and action as argument of type ActionHandler. Sets the handler function for the specified Action matched by name. Throws on error. Returns a reference to the same object for supporting chaining.
       
    
-
-      
    The PropertyInit dictionary
    
-        Defines the standardized part of the dictionary that initializes a ThingProperty object.
-        
    -          dictionary PropertyInit: InteractionInit {
-            boolean writable = false;
-            boolean observable = false;
-            any value;  // initialization value
-          };
-          PropertyInit implements DataSchema;
-        
    
       
    
-        The writable property initializes access to the Property value. The default value is false.
+        If provided, this callback function will implement invoking an Action and SHOULD be called by implementations when a request for invoking a Action is received from the underlying platform. The callback will receive a parameters dictionary argument.
       
    
       
    
-        The observable property initializes observability access to the Property. The default value is false.
+        There SHOULD be exactly one handler for any given Action. If no handler is initialized for any given Action, implementations SHOULD return error if the action is invoked by any client.
       
    
-        
    
-          The value property represents the initialization value of the property. Its type should match the one defined in the type property. If not provided in the dictionary object, it SHOULD be initialized as undefined.
-        
    
-      
    
     
    
 
-    
    
-      
    The ThingAction interface
    
-      
    -        interface ThingAction: Interaction {
-          readonly attribute DataSchema? input;
-          readonly attribute DataSchema? output;
-          readonly attribute DOMString description;
-          Promise<any> run(optional any inputValue);
-        };
-      
    
-      
    
-        The input read-only property represents the input of type DataSchema to the ThingAction. Multiple arguments can be provided by applications as an array or as an object. If the value is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided.
-      
    
-      
    
-        The output read-only property represents the output of type DataSchema of the ThingAction. If the value is null or undefined, the action does not return any values.
-      
    
-      
    
-        The description read-only property represents a human-readable textual description of the Action interaction.
-      
    
+    
    
+      
    Examples
    
       
    
-        The run() method when invoked, starts the Action interaction with the input value provided by the inputValue argument. If inputValue is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided. Otherwise the type of inputValue SHOULD match the DataSchema definition in the input property. Returns a Promise that will reject with an error or will resolve with a value of type defined by the output property.
+        Below some ExposedThing interface examples are given.
       
    
 
-      
    The ActionInit dictionary
    
-        
    -          dictionary ActionInit: InteractionInit {
-            DataSchema input;
-            DataSchema? output;
-            DOMString description;
+      
    +        try {
+          var temperatureValueDefinition = {
+            type: "number",
+            value: 0.0,
+            minimum: -50,
+            maximum: 10000
           };
-        
    
-        
    
-          The input property initializes the input of type DataSchema to the ThingAction. Multiple arguments can be provided by applications as an array or as an object.
-        
    
-        
    
-          The output property initializes the output of type DataSchema of the ThingAction.
-        
    
-        
    
-          The description read-only property initializes a human-readable textual description of the Action interaction.
-        
    
-      
    
-    
    
-
-    
    The ThingEvent interface
    
-      
    -        interface ThingEvent {
-        };
-        ThingEvent implements ThingProperty;
+          var temperaturePropertyDefinition = temperatureValueDefinition;
+          // add the 'forms' property
+          temperaturePropertyDefinition.forms = [ ... ];
+          var thing = WoT.produce({
+            name: "tempSensor",
+            properties: {
+              temperature: temperaturePropertyDefinition
+            },
+            actions: {
+              reset: {
+                description: "Reset the temperature sensor",
+                input: {
+                  temperature: temperatureValueDefinition
+                },
+                output: null,
+                forms: []
+              },
+            },
+            events: {
+              onchange: temperatureValueDefinition
+            },
+            links: []
+          });
+          thing.expose().then(() => {
+              thing.register();
+          });
+          // define Thing business logic
+          setInterval( async () => {
+            let mock = Math.random()*100;
+            thing.writeProperty("temperature", mock);
+            let old = await thing.readProperty("temperature");
+            if (old < mock) {
+              thing.writeProperty("temperature", mock);
+              thing.emitEvent("onchange", mock);
+            }
+          }, 1000);
+        } catch (err) {
+           console.log("Error creating ExposedThing: " + err);
+        }
       
    
-      
    
-        The data events are carrying is represented as a Property. ThingEvent SHOULD also implement the event mechanism of the underlying platform (such as a DOM Event or a Node.js Event).
-      
    
-      
    The EventInit dictionary
    
-        
    -          typedef PropertyInit EventInit;
-        
    
-        
    
-          The value an event is carrying is initialized as a Property value.
-        
    
-      
    
-    
    
 
-    
    The value-matching algorithm
    
-      
    
-        The value-matching algorithm is applied to a value input in relation to a valueType property of type DataSchema, for instance the value and type properties of a PropertyInit object, or the inputValue parameter to the run() method of a ThingAction object in relation to the same object. It executes the following steps:
-        
      
-          
    1. 
-            If valueType.type is not defined, or does not fully match a string enumerated in DataType, return false.
-          
      2. 
-          
    2. 
-            Otherwise, if valueType.type is "boolean": if value is either true or false, then return true, otherwise return false.
-          
      3. 
-          
    3. 
-            Otherwise, if valueType.type is "integer": if value is not an integer type defined by the underlying platform (such as long or long long), then return false, otherwise execute the following sub-steps:
-            
        
-              
      1. 
-                If valueType.minimum is defined and value is not greater or equal than that value, return false.
-              
        2. 
-              
      2. 
-                If valueType.maximum is defined and value is not less or equal than that value, return false.
-              
        3. 
-              
      3. 
-                Return true.
-              
        4. 
-            
      
-          
      4. 
-          
    4. 
-            Otherwise, if valueType.type is "number", if value is not an integer or floating point type defined by the underlying platform (such as long or long long or double), then return false, otherwise otherwise execute the following sub-steps:
-            
        
-              
      1. 
-                If valueType.minimum is defined and value is not greater or equal than that value, return false.
-              
        2. 
-              
      2. 
-                If valueType.maximum is defined and value is not less or equal than that value, return false.
-              
        3. 
-              
      3. 
-                Return true.
-              
        4. 
-            
      
-          
      5. 
-          
    5. 
-            Otherwise, if valueType.type is "string": if value is not a string type defined by the underlying platform, then return false, otherwise return true. In this case the algorithm expects a third parameter valueType.enum and runs the following sub-steps:
-            
        
-              
      • 
-                If valueType.enum is an array of strings, then if value fully matches one of the strings defined in the array, return true.
-              
        • 
-              
      • 
-                Otherwise, return false.
-              
        • 
-            
      
-          
      6. 
-          
    6. 
-            Otherwise, if valueType.type is "array", execute the following sub-steps:
-            
        
-              
      1. 
-                If valueType.minItems is defined, and value is not an array that contains at least valueType.minItems elements, return false.
-              
        2. 
-              
      2. 
-                If valueType.maxItems is defined, and value is not an array that contains at maximum valueType.maxItems elements, return false.
-              
        3. 
-              
      3. 
-                Otherwise, if value is not an array, return false.
-              
        4. 
-              
      4. 
-                Otherwise, if valueType.items is undefined, return false.
-              
        5. 
-              
      5. 
-                Otherwise, if valueType.items is null, return true (i.e. any type is accepted as array element, including heterogenous arrays).
-              
        6. 
-              
      6. 
-                Otherwise, for each element of the array value run the value-matching algorithm against the valueType.items object. If any of these runs returns false, then return false.
-              
        7. 
-              
      7. 
-                Otherwise, return true.
-              
        8. 
-            
      
-          
      7. 
-          
    7. 
-            Otherwise, if type is "object", execute the following sub-steps:
-            
        
-              
      1. 
-                If value is not an Object or null, return false.
-              
        2. 
-              
      2. 
-                If valueType.properties is not defined or is not null or it is not an object, return false.
-              
        3. 
-              
      3. 
-                If valueType.properties is null, return true (i.e. accept any object value).
-              
        4. 
-              
      4. 
-                For each string in the valueType.required array, if it does not match a property name in the value.properties object or in the value object, then return false.
-              
        5. 
-              
      5. 
-                For each property with name propName and value propDataSchema found in valueType.properties, run the following sub-steps:
-                
          
-                  
        1. 
-                    If the result of applying the value-matching algorithm on the value value[propName] and propDataSchema is false, then return false.
-                  
          2. 
-                
        
-              
        6. 
-              
      6. 
-                Return true.
-            
      
-          
      8. 
-        
    
-      
    
-    
    
+      
    +        try {
+          var 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
+                }
+              }
+          };
+          var statusPropertyDefinition = statusValueDefinition;
+          // add the 'forms' property
+          statusPropertyDefinition["forms"] = [];
+          var thing = WoT.produce({
+            name: "mySensor",
+            properties: {
+              brightness: {
+                type: "number",
+                value: 0.0,
+                minimum: 0.0,
+                maximum: 100.0,
+                required: true,
+              },
+              status: statusPropertyDefinition
+            },
+            actions: {
+              status: {
+                description: "Get status object",
+                input: null,
+                output: {
+                  status : statusValueDefinition;
+                },
+                forms: []
+              },
+            },
+            events: {
+              onstatuschange: statusValueDefinition;
+            },
+            links: []
+          });
+          thing.expose().then(() => {
+              thing.register();
+          });
+        } catch (err) {
+           console.log("Error creating ExposedThing: " + err);
+        }
+      
    
 
-  
    
+      
    +        let thingDescription = '{ \
+          "name": "mySensor", \
+          "@context": [ "https://w3c.github.io/wot/w3c-wot-td-context.jsonld",\
+             "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ],\
+          "@type": [ "Thing", "Sensor" ], \
+          "geo:location": "testspace", \
+          "properties": { \
+            "prop1": { \
+              "type": "number",\
+              "@type": [ "Property", "Temperature" ], \
+              "saref:TemperatureUnit": "degree_Celsius" \
+          } } }';
+        try {
+          // note that produce() fails if thingDescription contains error
+          let thing = WoT.produce(thingDescription);
+          // Interactions were added from TD
+          // WoT adds generic handler for reading any property
+          // define a specific handler for one property
+          let name = "examplePropertyName";
+          thing.setPropertyReadHandler(name, () => {
+            console.log("Handling read request for " + name);
+            return new Promise((resolve, reject) => {
+                let examplePropertyValue = 5;
+                resolve(examplePropertyValue);
+              },
+              e => {
+                console.log("Error");
+              });
+          });
+          thing.expose();
+        } catch(err) {
+           console.log("Error creating ExposedThing: " + err);
+        }
+      
    
 
-  
    
-    
    The ConsumedThing interface
    
-    
    
-      The ConsumedThing interface is a client API for sending requests to servers in order to retrieve or update Properties, invoke Actions, and observe Properties and Events.
-    
    
-    
    -      interface ConsumedThing {
-        readonly attribute maplike<DOMString, ThingProperty> properties;
-        readonly attribute maplike<DOMString, ThingAction> actions;
-        readonly attribute maplike<DOMString, ThingEvent> events;
-        readonly attribute FrozenArray<WebLink> links;
-        // getter for ThingTemplate properties
-        getter any(DOMString name);
-      };
-      ConsumedThing implements Observable;  // for TD changes
-    
    
-    
    
-      ConsumedThing represents a local proxy object of the remote Thing.
-    
    
-    
    
-      The properties property represents a dictionary of ThingProperty items.
-    
    
-    
    
-      The actions property represents a dictionary of ThingAction items.
-    
    
+      
    +        // fetch an external TD, e.g., to set up a proxy for that Thing
+        WoT.fetch("http://myservice.org/mySensor/description").then(td => {
+          // WoT.produce() ignores instance-specific metadata (security, form)
+          let thing = WoT.produce(td);
+          // Interactions were added from TD
+          // add server functionality
+          // ...
+        });
+      
    
+    
     
+  
     
+
+  
    
+    
    Data types used in a Thing
    
     
    
-      The events property represents a dictionary of ThingEvent items.
+      Every Thing describes its metadata as defined in ThingTemplate, and basic interactions as defined in ConsumedThing: Properties, Actions and Events. The following data types are used for representing these interactions, as defined in [[!WOT-TD]].
     
    
-    
  • 
-      The links property represents an array of WebLink objects.
-    
    • 
 
-    
    
-      
    Examples
    
+    
    The Link dictionary
    
+      
    +        dictionary Link {
+          required USVString href;
+          USVString mediaType;
+          DOMString rel;
+        };
+      
    
       
    
-        Below a ConsumedThing interface example is given.
+        The href property is a hypertext reference that defines the Link.
       
    
-      
    -        try {
-          let subscription = wot.discover({ method: "local" }).subscribe(
-            td => {
-              let thing = wot.consume(td);
-              console.log("Thing " + thing.name + " has been consumed.");
-              let subscription = thing.onPropertyChange("temperature")
-                .subscribe(function(value) {
-                  console.log("Temperature + " has changed to " + value);
-                });
-              thing.actions["startMeasurement"].run({ units: "Celsius" })
-                .then(() => { console.log("Temperature measurement started."); })
-                .catch(e => {
-                   console.log("Error starting measurement.");
-                   subscription.unsubscribe();
-                 })
-            },
-            error => { console.log("Discovery error: " + error.message); },
-            () => { console.log("Discovery finished successfully");}
-          );
-        } catch(error) {
-          console.log("Error: " + error.message);
-        };
-      
    
-    
     
-  
     
-
-  
    
-    
    The ExposedThing interface
    
-    
    
-      The ExposedThing interface is the server API that allows defining request handlers, properties, Actions, and Events to a Thing. It also implements the ConsumedThing interface. An ExposedThing is created by the produce() method.
-    
    
-    
    -      ExposedThing implements ConsumedThing;
-      interface ExposedThing {
-        // getter for ThingTemplate properties
-        getter any(DOMString name);
-        // setter for ThingTemplate properties
-        setter void(DOMString name, any value);
-        // define how to expose and run the Thing
-        Promise<void> expose();
-        Promise<void> destroy();
-        Promise<void> emitEvent(DOMString eventName, any payload);
-        // define Thing Description modifiers
-        ExposedThing addProperty(DOMString name, PropertyInit property);
-        ExposedThing removeProperty(DOMString name);
-        ExposedThing addAction(DOMString name, ActionInit action);
-        ExposedThing removeAction(DOMString name);
-        ExposedThing addEvent(DOMString name, EventInit event);
-        ExposedThing removeEvent(DOMString name);
-        // define request handlers
-        ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
-        ExposedThing setPropertyWriteHandler(DOMString name, PropertyWriteHandler writeHandler);
-        ExposedThing setActionHandler(DOMString name, ActionHandler action);
-      };
-      callback PropertyReadHandler = Promise<any>();
-      callback PropertyWriteHandler = Promise<void>(any value);
-      callback ActionHandler = Promise<any>(any parameters);
-    
    
-
-    
     
    The expose() method
    
       
    
-        Start serving external requests for the Thing, so that WoT interactions using Properties, Actions and Events will be possible.
+        The mediaType property represents the IANA media type associated with the Link.
+      
    
+      
    
+        The rel property represents a semantic label that specifies how to interact with the linked resource.
       
    
     
    
 
-    
     
    The destroy() method
    
+    
    The WebLink dictionary
    
+      
    +        dictionary WebLink: Link {
+          USVString anchor;
+        };
+      
    
       
    
-        Stop serving external requests for the Thing and destroy the object. Note that eventual unregistering should be done before invoking this method.
+        The anchor property represents a URI that overrides the default context of a Link.
       
    
     
    
 
-    
     
    The emitEvent() method
    
+    
    The Form dictionary
    
+      
    +        dictionary Form: Link {
+          Security security;
+        };
+      
    
       
    
-        Emits an the event initialized with the event name specified by the eventName argument and data specified by the payload argument.
+        The security property represents the security requirements for the linked resource.
       
    
     
    
 
-    
     
    The addProperty() method
    
+    
    
+      
    The Interaction interface
    
       
    
-        Adds a Property with name defined by the name argument and qualifiers and initialization value provided by the property argument of type PropertyInit. It updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+        The Interaction interface is an abstract class to represent Thing interactions: Properties, Actions and Events.
       
    
-    
     
-
-    
     
    The removeProperty() method
    
       
    
-        Removes the Property specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+        The InteractionInit dictionary holds the common properties of PropertyInit, ActionInit and EventInit dictionaries used for initializing ThingProperty, ThingAction and ThingEvent objects in a ThingTemplate dictionary used for creating an ExposedThing object.
       
    
-    
    
 
-    
     
    The addAction() method
    
+      
    +        interface Interaction {
+          attribute DOMString label;
+          readonly attribute FrozenArray<Form> forms;
+        };
+        Interaction implements Observable;
+      
    
       
    
-        Adds an Action with name defined by the name argument and qualifiers and initialization value provided by the action argument of type ActionInitto the Thing object and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+        The label property represents a text label for the interaction.
       
    
-    
     
-
-    
     
    The removeAction() method
    
       
    
-        Removes the Action specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+        The forms read-only property represents the protocol bindings initialization data and is initialized by the WoT Runtime.
       
    
+
+      
    The InteractionInit dictionary
    
+        
    +          dictionary InteractionInit {
+            DOMString label;
+          };
+        
    
+        
    
+          The label property initializes the text label for the interaction.
+        
    
+      
    
+
     
    
 
-    
     
    The addEvent() method
    
+    
    
+      
    The ThingProperty interface
    
       
    
-        Adds an event with name defined by the name argument and qualifiers and initialization value provided by the event argument of type EventInitto the Thing object and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+        The ThingProperty interface is used in ConsumedThing and ExposedThing objects to represent Thing Property interactions.
       
    
-    
    
-
-    
     
    The removeEvent() method
    
       
    
-        Removes the event specified by the name argument and updates the Thing Description. Returns a reference to the same object for supporting chaining.
+        The PropertyInit dictionary is used for initializing Property objects in a ThingTemplate dictionary used for creating an ExposedThing object. It MUST implement one of the DataSchema dictionaries.
       
    
-    
    
-
-    
    
-      
    The PropertyReadHandler callback
    
+      
    +        interface ThingProperty: Interaction {
+          // getter for PropertyInit properties
+          getter any(DOMString name);
+          // get and set interface for the Property
+          Promise<any> get();
+          Promise set(any value);
+        };
+        ThingProperty implements PropertyInit;
+        ThingProperty implements Observable;
+      
    
       
    
-        A function that returns a Promise and resolves it with the value of the Property matching the name argument to the setPropertyReadHandler function, or rejects with an error if the property is not found or the value cannot be retrieved.
+        The ThingProperty interface contains all the properties defined on PropertyInit as read-only properties.
       
    
-    
    
-
-    
    
-      
    The PropertyWriteHandler callback
    
       
    
-        A function called with value as argument that returns a Promise which is resolved when the value of the Property matching the name argument to the setPropertyReadHandler function is updated with value, or rejects with an error if the property is not found or the value cannot be updated.
+        The type read-only property represents the type definition for the Property. If it matches a DataType, then it MUST implement the corresponding DataSchema dictionary.
       
    
-      
    
-        Note that this function is invoked by implementations before the property is updated, so the code in this callback function can invoke the readProperty() method to find out the old value of the property, if needed. Therefore the old value is not provided to this method.
+      
    
+        The writable read-only property tells whether the Property value can be updated. If it is false, then the set(value) method SHOULD always reject.
       
    
-    
    
-
-    
    
-      
    The ActionHandler callback
    
       
    
-        A function called with a parameters dictionary argument assembled by the WoT runtime based on the Thing Description and the external client request. It returns a Promise that rejects with an error or resolves if the action is successful or ongoing (may also resolve with a control object such as an Observable for actions that need progress notifications or that can be canceled).
+        The observable read-only property tells whether the Property supports subscribing to value change notifications. If it is false, then the subscribe() method SHOULD always fail.
       
    
-    
    
-
-    
     
    The setPropertyReadHandler() method
    
       
    
-        Takes name as string argument and readHandler as argument of type PropertyReadHandler. Sets the handler function for reading the specified Property matched by name. Throws on error. Returns a reference to the same object for supporting chaining.
+        The const read-only property - defined in DataSchema - tells whether the Property value is a constant. If true, the set() and subscribe() methods SHOULD always fail.
       
    
       
    
-         The readHandler callback function will implement reading a Property and SHOULD be called by implementations when a request for reading a Property is received from the underlying platform.
+        The required read-only property  - defined in DataSchema - tells whether the Property should be always present on the ExposedThing object.
       
    
       
    
-        There SHOULD be at most one handler for any given Property and newly added handlers replace the old handlers. If no handler is initialized for any given Property, implementations SHOULD implement a default property read handler.
+        The get() method will fetch the value of the Property. Returns a Promise that resolves with the value, or rejects with an error.
+      
    
+      
    
+        The set() method will attempt to set the value of the Propertyspecified in the value argument whose type SHOULD match the o9ne specified by the type property. Returns a Promise that resolves on success, or rejects on an error.
       
    
-    
    
 
-    
     
    The setPropertyWriteHandler() method
    
+      
    The PropertyInit dictionary
    
+        Defines the standardized part of the dictionary that initializes a ThingProperty object.
+        
    +          dictionary PropertyInit: InteractionInit {
+            boolean writable = false;
+            boolean observable = false;
+            any value;  // initialization value
+          };
+          PropertyInit implements DataSchema;
+        
    
       
    
-        Takes name as string argument and writeHandler as argument of type PropertyWriteHandler. Sets the handler function for writing the specified Property matched by name. Throws on error. Returns a reference to the same object for supporting chaining.
+        The writable property initializes access to the Property value. The default value is false.
       
    
       
    
-        There SHOULD be at most one write handler for any given Property and newly added handlers replace the old handlers. If no write handler is initialized for any given Property, implementations SHOULD implement default property update and notifying observers on change.
+        The observable property initializes observability access to the Property. The default value is false.
       
    
+        
    
+          The value property represents the initialization value of the property. Its type should match the one defined in the type property. If not provided in the dictionary object, it SHOULD be initialized as undefined.
+        
    
+      
    
     
    
 
-    
     
    The setActionHandler() method
    
+    
    
+      
    The ThingAction interface
    
+      
    +        interface ThingAction: Interaction {
+          readonly attribute DataSchema? input;
+          readonly attribute DataSchema? output;
+          readonly attribute DOMString description;
+          Promise<any> run(optional any inputValue);
+        };
+      
    
       
    
-        Takes name as string argument and action as argument of type ActionHandler. Sets the handler function for the specified Action matched by name. Throws on error. Returns a reference to the same object for supporting chaining.
+        The input read-only property represents the input of type DataSchema to the ThingAction. Multiple arguments can be provided by applications as an array or as an object. If the value is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided.
       
    
       
    
-        If provided, this callback function will implement invoking an Action and SHOULD be called by implementations when a request for invoking a Action is received from the underlying platform. The callback will receive a parameters dictionary argument.
+        The output read-only property represents the output of type DataSchema of the ThingAction. If the value is null or undefined, the action does not return any values.
       
    
       
    
-        There SHOULD be exactly one handler for any given Action. If no handler is initialized for any given Action, implementations SHOULD return error if the action is invoked by any client.
+        The description read-only property represents a human-readable textual description of the Action interaction.
       
    
-    
    
-
-    
    
-      
    Examples
    
       
    
-        Below some ExposedThing interface examples are given.
+        The run() method when invoked, starts the Action interaction with the input value provided by the inputValue argument. If inputValue is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided. Otherwise the type of inputValue SHOULD match the DataSchema definition in the input property. Returns a Promise that will reject with an error or will resolve with a value of type defined by the output property.
       
    
 
-      
    -        try {
-          var temperatureValueDefinition = {
-            type: "number",
-            value: 0.0,
-            minimum: -50,
-            maximum: 10000
+      
    The ActionInit dictionary
    
+        
    +          dictionary ActionInit: InteractionInit {
+            DataSchema input;
+            DataSchema? output;
+            DOMString description;
           };
-          var temperaturePropertyDefinition = temperatureValueDefinition;
-          // add the 'forms' property
-          temperaturePropertyDefinition.forms = [ ... ];
-          var thing = WoT.produce({
-            name: "tempSensor",
-            properties: {
-              temperature: temperaturePropertyDefinition
-            },
-            actions: {
-              reset: {
-                description: "Reset the temperature sensor",
-                input: {
-                  temperature: temperatureValueDefinition
-                },
-                output: null,
-                forms: []
-              },
-            },
-            events: {
-              onchange: temperatureValueDefinition
-            },
-            links: []
-          });
-          thing.expose().then(() => {
-              thing.register();
-          });
-          // define Thing business logic
-          setInterval( async () => {
-            let mock = Math.random()*100;
-            thing.writeProperty("temperature", mock);
-            let old = await thing.readProperty("temperature");
-            if (old < mock) {
-              thing.writeProperty("temperature", mock);
-              thing.emitEvent("onchange", mock);
-            }
-          }, 1000);
-        } catch (err) {
-           console.log("Error creating ExposedThing: " + err);
-        }
+        
    
+        
    
+          The input property initializes the input of type DataSchema to the ThingAction. Multiple arguments can be provided by applications as an array or as an object.
+        
    
+        
    
+          The output property initializes the output of type DataSchema of the ThingAction.
+        
    
+        
    
+          The description read-only property initializes a human-readable textual description of the Action interaction.
+        
    
+      
    
+    
    
+
+    
    The ThingEvent interface
    
+      
    +        interface ThingEvent {
+        };
+        ThingEvent implements ThingProperty;
       
    
+      
    
+        The data events are carrying is represented as a Property. ThingEvent SHOULD also implement the event mechanism of the underlying platform (such as a DOM Event or a Node.js Event).
+      
    
+      
    The EventInit dictionary
    
+        
    +          typedef PropertyInit EventInit;
+        
    
+        
    
+          The value an event is carrying is initialized as a Property value.
+        
    
+      
    
+    
    
 
-      
    -        try {
-          var 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
-                }
-              }
+    
    Value types
    
+      
    
+        Value types are used in Property, Event and Action parameter definitions in a ThingTemplate. Basically correspond to a JSON object definition.
+      
    
+
+      
    The DataType enumeration type
    
+        
    +          enum DataType { "boolean", "integer", "number", "string", "object", "array" };
+        
    
+        
    
+          Defines the types that values can take, i.e. "boolean", "integer", "number", "string", "object" and "array".
+        
    
+      
    
+
+      
    The Number type
    
+        
    +          typedef (long or unrestricted double) Number;
+        
    
+        
    
+          A number is either an integer or floating point number supported by the underlying platform. A number value may have associated a permited range between a minimum and maximum value.
+        
    
+      
    
+
+      
    The DataSchema dictionary
    
+        
    +          dictionary DataSchema {
+            required DataType type;
+            boolean required = "false";
+            DOMString description;
+            boolean const;
           };
-          var statusPropertyDefinition = statusValueDefinition;
-          // add the 'forms' property
-          statusPropertyDefinition["forms"] = [];
-          var thing = WoT.produce({
-            name: "mySensor",
-            properties: {
-              brightness: {
-                type: "number",
-                value: 0.0,
-                minimum: 0.0,
-                maximum: 100.0,
-                required: true,
-              },
-              status: statusPropertyDefinition
-            },
-            actions: {
-              status: {
-                description: "Get status object",
-                input: null,
-                output: {
-                  status : statusValueDefinition;
-                },
-                forms: []
-              },
-            },
-            events: {
-              onstatuschange: statusValueDefinition;
-            },
-            links: []
-          });
-          thing.expose().then(() => {
-              thing.register();
-          });
-        } catch (err) {
-           console.log("Error creating ExposedThing: " + err);
-        }
-      
    
+        
    
+        
    
+          Represents the common properties of a value type definition.
+        
    
+        
    
+          The type property represents the value type enumerated in DataType.
+        
    
+        
    
+          The required property tells whether this value is required to be speficied.
+        
    
+        
    
+          The description property represents a textual description of the value.
+        
    
+        
    
+          The const property tells whether this value is constant.
+        
    
+      
    
 
-      
    -        let thingDescription = '{ \
-          "name": "mySensor", \
-          "@context": [ "https://w3c.github.io/wot/w3c-wot-td-context.jsonld",\
-             "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ],\
-          "@type": [ "Thing", "Sensor" ], \
-          "geo:location": "testspace", \
-          "properties": { \
-            "prop1": { \
-              "type": "number",\
-              "@type": [ "Property", "Temperature" ], \
-              "saref:TemperatureUnit": "degree_Celsius" \
-          } } }';
-        try {
-          // note that produce() fails if thingDescription contains error
-          let thing = WoT.produce(thingDescription);
-          // Interactions were added from TD
-          // WoT adds generic handler for reading any property
-          // define a specific handler for one property
-          let name = "examplePropertyName";
-          thing.setPropertyReadHandler(name, () => {
-            console.log("Handling read request for " + name);
-            return new Promise((resolve, reject) => {
-                let examplePropertyValue = 5;
-                resolve(examplePropertyValue);
-              },
-              e => {
-                console.log("Error");
-              });
-          });
-          thing.expose();
-        } catch(err) {
-           console.log("Error creating ExposedThing: " + err);
-        }
-      
    
+      
    The NumberSchema dictionary
    
+        
    +          dictionary NumberSchema: DataSchema {
+            required DOMString type;
+            Number minimum;
+            Number maximum;
+          };
+        
    
+        
    
+          The type property MUST have either the value "number" (representing a floating point number) or "integer" (representing an integer) as defined by the underlying platform.
+        
    
+        
    
+          The minimum property may be present when the value is of type "number" and if present, it defines the minimum value that can be used.
+        
    
+        
    
+          The maximum property may be present when the value is of type "number" and if present, it defines the maximum value that can be used.
+        
    
+      
    
 
-      
    -        // fetch an external TD, e.g., to set up a proxy for that Thing
-        WoT.fetch("http://myservice.org/mySensor/description").then(td => {
-          // WoT.produce() ignores instance-specific metadata (security, form)
-          let thing = WoT.produce(td);
-          // Interactions were added from TD
-          // add server functionality
-          // ...
-        });
-      
    
-    
     
-  
     
+      
    The BooleanSchema dictionary
    
+        
    +          dictionary BooleanSchema: DataSchema {
+            const type = "boolean";
+          };
+        
    
+        
    
+          The type property MUST have the value "boolean".
+        
    
+      
    
+
+      
    The StringSchema dictionary
    
+        
    +          dictionary StringSchema: DataSchema {
+            const type = "string";
+            sequence<DOMString>? enum;
+          };
+        
    
+        
    
+          The type property MUST have the value "string".
+        
    
+        
    
+          The enum property represents the list of allowed string values as a string array.
+        
    
+      
    
+
+      
    The ObjectSchema dictionary
    
+        
    +          dictionary ObjectSchema: DataSchema {
+            const type = "object";
+            maplike<DOMString, DataSchema>? properties;
+            sequence<DOMString> required;
+          };
+        
    
+        
    
+          The type property MUST have the value "object".
+        
    
+        
    
+          The properties property is a dictionary that contains the names and types of each of the object properties. If not provided in the dictionary object, it SHOULD be initialized to undefined. The value null is accepted, as well as an empty object.
+        
    
+        
    
+          The required property is a string array that containes the names that are mandatory to be present from the object properties. If not provided, it SHOULD be initialized to undefined. An empty array is accepted.
+        
    
+      
    
+
+      
    The ArraySchema dictionary
    
+        
    +          dictionary ArraySchema: DataSchema {
+            const type = "array";
+            DataSchema? items;
+            unsigned long minItems;
+            unsigned long maxItems;
+          };
+        
    
+        
    
+          The type property MUST have the value "array".
+        
    
+        
    
+          The items property represents the type of the elements in the array. If not provided in the dictionary object, it SHOULD be initialized to "undefined". The value null is accepted.
+        
    
+        
    
+          The minItems property represents the minimum number of elements required to be in the array.
+        
    
+        
    
+          The maxItems property represents the maximum number of elements that can be specified in the array.
+        
    
+      
    
+    
    
+
+    
    The value-matching algorithm
    
+      
    
+        The value-matching algorithm is applied to a value input in relation to a valueType property of type DataSchema, for instance the value and type properties of a PropertyInit object, or the inputValue parameter to the run() method of a ThingAction object in relation to the same object. It executes the following steps:
+        
      
+          
    1. 
+            If valueType.type is not defined, or does not fully match a string enumerated in DataType, return false.
+          
      2. 
+          
    2. 
+            Otherwise, if valueType.type is "boolean": if value is either true or false, then return true, otherwise return false.
+          
      3. 
+          
    3. 
+            Otherwise, if valueType.type is "integer": if value is not an integer type defined by the underlying platform (such as long or long long), then return false, otherwise execute the following sub-steps:
+            
        
+              
      1. 
+                If valueType.minimum is defined and value is not greater or equal than that value, return false.
+              
        2. 
+              
      2. 
+                If valueType.maximum is defined and value is not less or equal than that value, return false.
+              
        3. 
+              
      3. 
+                Return true.
+              
        4. 
+            
      
+          
      4. 
+          
    4. 
+            Otherwise, if valueType.type is "number", if value is not an integer or floating point type defined by the underlying platform (such as long or long long or double), then return false, otherwise otherwise execute the following sub-steps:
+            
        
+              
      1. 
+                If valueType.minimum is defined and value is not greater or equal than that value, return false.
+              
        2. 
+              
      2. 
+                If valueType.maximum is defined and value is not less or equal than that value, return false.
+              
        3. 
+              
      3. 
+                Return true.
+              
        4. 
+            
      
+          
      5. 
+          
    5. 
+            Otherwise, if valueType.type is "string": if value is not a string type defined by the underlying platform, then return false, otherwise return true. In this case the algorithm expects a third parameter valueType.enum and runs the following sub-steps:
+            
        
+              
      • 
+                If valueType.enum is an array of strings, then if value fully matches one of the strings defined in the array, return true.
+              
        • 
+              
      • 
+                Otherwise, return false.
+              
        • 
+            
      
+          
      6. 
+          
    6. 
+            Otherwise, if valueType.type is "array", execute the following sub-steps:
+            
        
+              
      1. 
+                If valueType.minItems is defined, and value is not an array that contains at least valueType.minItems elements, return false.
+              
        2. 
+              
      2. 
+                If valueType.maxItems is defined, and value is not an array that contains at maximum valueType.maxItems elements, return false.
+              
        3. 
+              
      3. 
+                Otherwise, if value is not an array, return false.
+              
        4. 
+              
      4. 
+                Otherwise, if valueType.items is undefined, return false.
+              
        5. 
+              
      5. 
+                Otherwise, if valueType.items is null, return true (i.e. any type is accepted as array element, including heterogenous arrays).
+              
        6. 
+              
      6. 
+                Otherwise, for each element of the array value run the value-matching algorithm against the valueType.items object. If any of these runs returns false, then return false.
+              
        7. 
+              
      7. 
+                Otherwise, return true.
+              
        8. 
+            
      
+          
      7. 
+          
    7. 
+            Otherwise, if type is "object", execute the following sub-steps:
+            
        
+              
      1. 
+                If value is not an Object or null, return false.
+              
        2. 
+              
      2. 
+                If valueType.properties is not defined or is not null or it is not an object, return false.
+              
        3. 
+              
      3. 
+                If valueType.properties is null, return true (i.e. accept any object value).
+              
        4. 
+              
      4. 
+                For each string in the valueType.required array, if it does not match a property name in the value.properties object or in the value object, then return false.
+              
        5. 
+              
      5. 
+                For each property with name propName and value propDataSchema found in valueType.properties, run the following sub-steps:
+                
          
+                  
        1. 
+                    If the result of applying the value-matching algorithm on the value value[propName] and propDataSchema is false, then return false.
+                  
          2. 
+                
        
+              
        6. 
+              
      6. 
+                Return true.
+            
      
+          
      8. 
+        
    
+      
    
+    
    
+
+  
    
 
   
    
     
    Observables
    

From 7d12b257276a92e1462bd95db874693521b75255 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Wed, 13 Jun 2018 15:12:41 +0300
Subject: [PATCH 223/464] Move Security dictionary to the Security section

Signed-off-by: Zoltan Kis 
---
 index.html | 59 +++++++++++++++++++++++++++---------------------------
 1 file changed, 29 insertions(+), 30 deletions(-)

diff --git a/index.html b/index.html
index 3ea46364..fe1d9f2b 100644
--- a/index.html
+++ b/index.html
@@ -304,36 +304,6 @@ 
    The ThingTemplate dictionary
    
       
    
     
     
 
-    
    
-      
     The Security dictionary
    
-      
    
-        Contains security related configuration.
-      
    
-      
    -        dictionary Security {
-          required DOMString scheme;
-          any in;
-        };
-      
    
-      
    
-        The scheme property represents the identification of the security scheme to be used for the Thing, for instance
-        
      
-          
    •  "basic+https",
      • 
-          
    •  "digest+https",
      • 
-          
    •  "bearer+https",
      • 
-          
    •  "bearer+coaps",
      • 
-          
    •  "pop+https", 
      • 
-          
    •  "pop+coaps", 
      • 
-          
    •  "apikey+https", 
      • 
-          
    •  "apikey+coaps", 
      • 
-          
    •  "ocf+coaps". 
      • 
-        
    
-      
    
-      
    
-        The in property represents security initialization data as described in the [Security metadata description](https://github.com/w3c/wot-security/blob/master/wot-security-metadata.md).
-      
    
-    
    
-
     
     
     The fetch() method
    
       
    
         Accepts an url argument of type USVString that represents a URL (e.g. "file://..." or "https://...") and returns a Promise that resolves with a ThingDescription (a serialized JSON-LD document of type USVString).
@@ -1418,6 +1388,35 @@ 
    The Observable interface
    
     
    
      Please see the WoT Security and Privacy repository for work in progress regarding threat models, assets, risks, recommended mitigations, and best practices for security and privacy for systems using the Web of Things. Once complete, security and privacy considerations relevant to the Scripting API will be summarized in this section.
     
    
+    
    
+      
     The Security dictionary
    
+      
    
+        Contains security related configuration.
+      
    
+      
    +        dictionary Security {
+          required DOMString scheme;
+          any in;
+        };
+      
    
+      
    
+        The scheme property represents the identification of the security scheme to be used for the Thing, for instance
+        
      
+          
    •  "basic+https",
      • 
+          
    •  "digest+https",
      • 
+          
    •  "bearer+https",
      • 
+          
    •  "bearer+coaps",
      • 
+          
    •  "pop+https", 
      • 
+          
    •  "pop+coaps", 
      • 
+          
    •  "apikey+https", 
      • 
+          
    •  "apikey+coaps", 
      • 
+          
    •  "ocf+coaps". 
      • 
+        
    
+      
    
+      
    
+        The in property represents security initialization data as described in the [Security metadata description](https://github.com/w3c/wot-security/blob/master/wot-security-metadata.md).
+      
    
+    
    
   
    
 
   
     
    Terminology and conventions
    

From 2eaa4f75f8e2e545f25da3c20eb5e92ccf6d96d0 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Wed, 13 Jun 2018 16:18:44 +0300
Subject: [PATCH 224/464] Add security configuration types

Signed-off-by: Zoltan Kis 
---
 index.html | 174 ++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 153 insertions(+), 21 deletions(-)

diff --git a/index.html b/index.html
index fe1d9f2b..2ebb5262 100644
--- a/index.html
+++ b/index.html
@@ -275,7 +275,7 @@ 
    The ThingTemplate dictionary
    
           The support optional attribute of type DOMString represents human readable information about the TD maintainer.
         
         
  • 
-          The security optional attribute represents security metadata defined by the Security dictionary;
+          The security optional attribute represents security metadata defined by the SecurityScheme dictionary;
         
    • 
         
  • 
           The properties optional attribute represents a dictionary with keys that correspond to Property names and values of type PropertyInit.
@@ -892,7 +892,7 @@ 
    Data types used in a Thing
    
     
    The Form dictionary
    
       
             dictionary Form: Link {
-          Security security;
+          SecurityScheme security;
         };
       
    
       
    
@@ -1388,33 +1388,165 @@ 
    The Observable interface
    
     
    
      Please see the WoT Security and Privacy repository for work in progress regarding threat models, assets, risks, recommended mitigations, and best practices for security and privacy for systems using the Web of Things. Once complete, security and privacy considerations relevant to the Scripting API will be summarized in this section.
     
    
-    
    
-      
     The Security dictionary
    
+
+    
    The SecuritySchemeType enumeration type
    
+      
    +        enum SecuritySchemeType { "basic", "digest", "bearer", "pop", "oauth2", "apikey" };
+      
    
+      
    
+        Defines the supported security schemes, i.e. "basic", "digest", "bearer", "pop", "oauth2" and "apikey".
+      
    
+    
    
+
+    
    The AuthenticationType enumeration type
    
+      
    +        enum AuthenticationType { "header", "body", "query", "cookie" };
+      
    
+      
    
+        Defines the  location of the authentication information, i.e. "header", "body", "query" and "cookie".
+      
    
+    
    
+
+    
    
+      
     The SecurityScheme dictionary
    
       
    
-        Contains security related configuration.
+        Represents the base class for security related configuration. One of the subclasses (differentiated by scheme) SHOULD be used.
       
    
       
    -        dictionary Security {
-          required DOMString scheme;
-          any in;
+        dictionary SecurityScheme {
+          required SecuritySchemeType scheme;
         };
       
    
       
    
-        The scheme property represents the identification of the security scheme to be used for the Thing, for instance
-        
      
-          
    •  "basic+https",
      • 
-          
    •  "digest+https",
      • 
-          
    •  "bearer+https",
      • 
-          
    •  "bearer+coaps",
      • 
-          
    •  "pop+https", 
      • 
-          
    •  "pop+coaps", 
      • 
-          
    •  "apikey+https", 
      • 
-          
    •  "apikey+coaps", 
      • 
-          
    •  "ocf+coaps". 
      • 
-        
    
+        The scheme property represents the identification of the security scheme to be used for the Thing.
+      
    
+    
    
+
+    
    
+      
     The BasicSecurityScheme dictionary
    
+      
    +        dictionary BasicSecurityScheme: SecurityScheme {
+          const scheme = "basic";
+          DOMString in;
+          DOMString pname;
+        };
+      
    
+      
    
+        The scheme property represents the identification of the security scheme to be used for the Thing.
+      
    
+      
    
+        The in property of type AuthenticationType represents represents the location of the authentication information.
+      
    
+      
    
+        The pname property represents the authentication parameter name.
+      
    
+    
    
+
+    
    
+      
     The DigestSecurityScheme dictionary
    
+      
    +        dictionary DigestSecurityScheme: BasicSecurityScheme {
+          const scheme = "digest";
+          DOMString qop = "auth";
+        };
+      
    
+      
    
+        The scheme property represents the identification of the security scheme and MUST be "digest".
+      
    
+      
    
+        The qop property represents the quality of protection. The default value is "auth". The other accepted value is "auth-int".
+      
    
+    
    
+
+    
    
+      
     The BearerSecurityScheme dictionary
    
+      
    +        dictionary BearerSecurityScheme: BasicSecurityScheme {
+          const scheme = "bearer";
+          USVString authorizationURL;
+          DOMString alg = "ES256";
+          DOMString format = "jwt";
+        };
+      
    
+      
    
+        The scheme property represents the identification of the security scheme and MUST be "bearer".
+      
    
+      
    
+        The authorizationURL property represents the authorization server URL.
+      
    
+      
    
+        The alg property represents the encoding, encryption or digest algorithm. Accepted values include "MD5", "ES256", "ES512-256". The default value is "ES256".
+      
    
+      
    
+        The format property represents the format of the authentication information. Accepted values are "jwt" (the default value), "jwe" and "jws".
+      
    
+    
    
+
+    
    
+      
     The PopSecurityScheme dictionary
    
+      
    
+        Represents the proof-of-possession token authentication security configuration.
+      
    
+      
    +        dictionary PopSecurityScheme: DigestSecurityScheme {
+          const scheme = "pop";
+        };
+      
    
+      
    
+        The scheme property represents the identification of the security scheme and MUST be "pop".
+      
    
+    
    
+
+    
    
+      
     The ApikeySecurityScheme dictionary
    
+      
    
+        Represents the API key authentication security configuration, where the access token is opaque and is not using a standard token format.
+      
    
+      
    +        dictionary ApikeySecurityScheme: BasicSecurityScheme {
+          const scheme = "apikey";
+        };
+      
    
+      
    
+        The scheme property represents the identification of the security scheme and MUST be "apikey".
+      
    
+    
    
+
+    
    
+      
     The OAuth2SecurityScheme dictionary
    
+      
    
+        Represents the OAuth2 authentication security configuration.
+      
    
+      
    +        dictionary OAuth2SecurityScheme: SecurityScheme {
+          const scheme = "oauth2";
+          USVString tokenURL;
+          USVString authorizationURL;
+          USVString refreshURL;
+          sequence<DOMString> scopes;
+          DOMString flow = "implicit";
+        };
+      
    
+      
    
+        The scheme property represents the identification of the security scheme and MUST be "oauth2".
+      
    
+      
    
+        The tokenURL property represents the URL of the token server.
+      
    
+      
    
+        The authorizationURL property represents the URL of the authorization server.
+      
    
+      
    
+        The refreshURL property represents the URL of the refresh server.
+      
    
+      
    
+        The scopes property represents the authorization scope identifiers as an array of strings.
+      
    
+      
    
+        The flow property represents the authorization flow of type. Accepted values are: "implicit" (the default value), "password", "client", or "code".
       
    
       
    
-        The in property represents security initialization data as described in the [Security metadata description](https://github.com/w3c/wot-security/blob/master/wot-security-metadata.md).
+         For the "implicit" flow the authorizationURL and scopes properties are required. For the "password" and "client" flows the tokenURL and scopes properties are required. For the "code" flow the authorizationURL, tokenURL and scopes properties are required.
       
    
     
    
   
    

From c4d5188016a888a41e0b13981ded5222b31eb251 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Wed, 13 Jun 2018 16:22:27 +0300
Subject: [PATCH 225/464] Add support for 'null' type (requiring null value)

Signed-off-by: Zoltan Kis 
---
 index.html | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/index.html b/index.html
index 2ebb5262..ce15935c 100644
--- a/index.html
+++ b/index.html
@@ -1071,10 +1071,10 @@ 
    The ThingAction interface
    
 
       
    The DataType enumeration type
    
         
    -          enum DataType { "boolean", "integer", "number", "string", "object", "array" };
+          enum DataType { "boolean", "integer", "number", "string", "object", "array", "null" };
         
    
         
    
-          Defines the types that values can take, i.e. "boolean", "integer", "number", "string", "object" and "array".
+          Defines the types that values can take, i.e. "null" "boolean", "integer", "number", "string", "object" and "array".
         
    
       
    
 
@@ -1208,6 +1208,9 @@ 
    The ThingAction interface
    
           
  • 
             If valueType.type is not defined, or does not fully match a string enumerated in DataType, return false.
           
    • 
+          
  • 
+            Otherwise, if valueType.type is "null": if value is null, return true, otherwise return false.
+          
    • 
           
  • 
             Otherwise, if valueType.type is "boolean": if value is either true or false, then return true, otherwise return false.
           
    • 

From 7454d7e969a2e1a8b1bf1b120f0e71b993ffea41 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Wed, 13 Jun 2018 16:40:11 +0300
Subject: [PATCH 226/464] Make ActionInit.input nullable

Signed-off-by: Zoltan Kis 
---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index ce15935c..1cbfc450 100644
--- a/index.html
+++ b/index.html
@@ -1028,7 +1028,7 @@ 
    The ThingAction interface
    
       
    The ActionInit dictionary
    
         
               dictionary ActionInit: InteractionInit {
-            DataSchema input;
+            DataSchema? input;
             DataSchema? output;
             DOMString description;
           };

From 6421f80fa334ca85b6c51e71276f1dd12391dcdc Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Wed, 13 Jun 2018 17:10:54 +0300
Subject: [PATCH 227/464] Fix #123: Remove redundant getter in ExposedThing

Signed-off-by: Zoltan Kis 
---
 index.html | 2 --
 1 file changed, 2 deletions(-)

diff --git a/index.html b/index.html
index 1cbfc450..313f74f2 100644
--- a/index.html
+++ b/index.html
@@ -553,8 +553,6 @@ 
    The ExposedThing interface
    
     
           ExposedThing implements ConsumedThing;
       interface ExposedThing {
-        // getter for ThingTemplate properties
-        getter any(DOMString name);
         // setter for ThingTemplate properties
         setter void(DOMString name, any value);
         // define how to expose and run the Thing

From 7f07474fe8a97066f99a0449350bee55cec61527 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Mon, 2 Jul 2018 12:30:32 +0300
Subject: [PATCH 228/464] Fix #127: align names from get/set/run to
 read/write/invoke

Signed-off-by: Zoltan Kis 
---
 index.html | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/index.html b/index.html
index 313f74f2..187e74c2 100644
--- a/index.html
+++ b/index.html
@@ -528,7 +528,7 @@ 
    Examples
    
                 .subscribe(function(value) {
                   console.log("Temperature + " has changed to " + value);
                 });
-              thing.actions["startMeasurement"].run({ units: "Celsius" })
+              thing.actions["startMeasurement"].invoke({ units: "Celsius" })
                 .then(() => { console.log("Temperature measurement started."); })
                 .catch(e => {
                    console.log("Error starting measurement.");
@@ -947,8 +947,8 @@ 
    The ThingProperty interface
    
           // getter for PropertyInit properties
           getter any(DOMString name);
           // get and set interface for the Property
-          Promise<any> get();
-          Promise set(any value);
+          Promise<any> read();
+          Promise write(any value);
         };
         ThingProperty implements PropertyInit;
         ThingProperty implements Observable;
@@ -972,10 +972,10 @@ 
    The ThingProperty interface
    
         The required read-only property  - defined in DataSchema - tells whether the Property should be always present on the ExposedThing object.
       
    
       
    
-        The get() method will fetch the value of the Property. Returns a Promise that resolves with the value, or rejects with an error.
+        The read() method will fetch the value of the Property. Returns a Promise that resolves with the value, or rejects with an error.
       
    
       
    
-        The set() method will attempt to set the value of the Propertyspecified in the value argument whose type SHOULD match the o9ne specified by the type property. Returns a Promise that resolves on success, or rejects on an error.
+        The write() method will attempt to set the value of the Propertyspecified in the value argument whose type SHOULD match the o9ne specified by the type property. Returns a Promise that resolves on success, or rejects on an error.
       
    
 
       
    The PropertyInit dictionary
    
@@ -1007,7 +1007,7 @@ 
    The ThingAction interface
    
           readonly attribute DataSchema? input;
           readonly attribute DataSchema? output;
           readonly attribute DOMString description;
-          Promise<any> run(optional any inputValue);
+          Promise<any> invoke(optional any inputValue);
         };
       
    
       
    
@@ -1020,7 +1020,7 @@ 
    The ThingAction interface
    
         The description read-only property represents a human-readable textual description of the Action interaction.
       
    
       
    
-        The run() method when invoked, starts the Action interaction with the input value provided by the inputValue argument. If inputValue is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided. Otherwise the type of inputValue SHOULD match the DataSchema definition in the input property. Returns a Promise that will reject with an error or will resolve with a value of type defined by the output property.
+        The invoke() method when invoked, starts the Action interaction with the input value provided by the inputValue argument. If inputValue is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided. Otherwise the type of inputValue SHOULD match the DataSchema definition in the input property. Returns a Promise that will reject with an error or will resolve with a value of type defined by the output property.
       
    
 
       
    The ActionInit dictionary
    
@@ -1201,7 +1201,7 @@ 
    The ThingAction interface
    
 
     
    The value-matching algorithm
    
       
    
-        The value-matching algorithm is applied to a value input in relation to a valueType property of type DataSchema, for instance the value and type properties of a PropertyInit object, or the inputValue parameter to the run() method of a ThingAction object in relation to the same object. It executes the following steps:
+        The value-matching algorithm is applied to a value input in relation to a valueType property of type DataSchema, for instance the value and type properties of a PropertyInit object, or the inputValue parameter to the invoke() method of a ThingAction object in relation to the same object. It executes the following steps:
         
      
           
    1. 
             If valueType.type is not defined, or does not fully match a string enumerated in DataType, return false.

From f1622e4d748ec183f53d32f3aa8c5229f3bc95b4 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Tue, 3 Jul 2018 16:24:09 +0300
Subject: [PATCH 229/464] Add algorithms for property read and write handlers.
 Regroup functions in ExposedThing WebIDL definition.

Signed-off-by: Zoltan Kis 
---
 index.html | 54 ++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 44 insertions(+), 10 deletions(-)

diff --git a/index.html b/index.html
index 187e74c2..e3114894 100644
--- a/index.html
+++ b/index.html
@@ -558,18 +558,19 @@ 
      The ExposedThing interface
      
         // define how to expose and run the Thing
         Promise<void> expose();
         Promise<void> destroy();
-        Promise<void> emitEvent(DOMString eventName, any payload);
-        // define Thing Description modifiers
+        // define Properties
         ExposedThing addProperty(DOMString name, PropertyInit property);
+        ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
+        ExposedThing setPropertyWriteHandler(DOMString name, PropertyWriteHandler writeHandler);
         ExposedThing removeProperty(DOMString name);
+        // define Actions
         ExposedThing addAction(DOMString name, ActionInit action);
+        ExposedThing setActionHandler(DOMString name, ActionHandler action);
         ExposedThing removeAction(DOMString name);
+        // define Events
         ExposedThing addEvent(DOMString name, EventInit event);
+        Promise<void> emitEvent(DOMString eventName, any payload);
         ExposedThing removeEvent(DOMString name);
-        // define request handlers
-        ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
-        ExposedThing setPropertyWriteHandler(DOMString name, PropertyWriteHandler writeHandler);
-        ExposedThing setActionHandler(DOMString name, ActionHandler action);
       };
       callback PropertyReadHandler = Promise<any>();
       callback PropertyWriteHandler = Promise<void>(any value);
@@ -633,17 +634,17 @@ 
      The ExposedThing interface
      
     
      
       
      The PropertyReadHandler callback
      
       
      
-        A function that returns a Promise and resolves it with the value of the Property matching the name argument to the setPropertyReadHandler function, or rejects with an error if the property is not found or the value cannot be retrieved.
+        A function that is called when an external request for reading a Property is received. It should return a Promise and resolves it with the value of the Property matching the name argument to the setPropertyReadHandler function, or rejects with an error if the property is not found or the value cannot be retrieved.
       
      
     
      
 
     
      
       
      The PropertyWriteHandler callback
      
       
      
-        A function called with value as argument that returns a Promise which is resolved when the value of the Property matching the name argument to the setPropertyReadHandler function is updated with value, or rejects with an error if the property is not found or the value cannot be updated.
+        A function that is called when an external request for writing a Property is received. It is given the requested new value as argument and should return a Promise which is resolved when the value of the Property matching the name argument to the setPropertyReadHandler function is updated with value, or rejects with an error if the property is not found or the value cannot be updated.
       
      
       
      
-        Note that this function is invoked by implementations before the property is updated, so the code in this callback function can invoke the readProperty() method to find out the old value of the property, if needed. Therefore the old value is not provided to this method.
+        Note that this function is invoked by implementations before the property is updated and it actually defines what to do when a write request is received. The code in this callback function can invoke the read() method to find out the old value of the property, if needed. Therefore the old value is not provided to this function.
       
      
     
      
 
@@ -664,6 +665,23 @@ 
      The ActionHandler callback
      
       
      
         There SHOULD be at most one handler for any given Property and newly added handlers replace the old handlers. If no handler is initialized for any given Property, implementations SHOULD implement a default property read handler.
       
      
+      
      
+        When an external request for reading Property propertyName is received, the runtime SHOULD execute the following steps:
+        
        
+          
      1. 
+            Return a Promise promise and execute the next steps asynchronously.
+          
        2. 
+          
      2. 
+            If a Property with propertyName does not exist, reject promise with a ReferenceError and terminate these steps.
+          
        3. 
+          
      3. 
+            Otherwise, if no read handler has been defined for propertyName, resolve promise with the value of the Property named propertyName provided by the  runtime implementation and terminate these steps.
+          
        4. 
+          
      4. 
+            Otherwise, invoke the read handler associated with propertyName. If it rejects, then reject promise with the same error, and resolve promise with the same value.
+          
        5. 
+        
      
+      
      
     
    
 
     
     
    The setPropertyWriteHandler() method
    
@@ -673,8 +691,24 @@ 
    The ActionHandler callback
    
       
    
         There SHOULD be at most one write handler for any given Property and newly added handlers replace the old handlers. If no write handler is initialized for any given Property, implementations SHOULD implement default property update and notifying observers on change.
       
    
+      
    
+        When an external request for writing a Property propertyName with a new value value is received, the runtime SHOULD execute the following steps:
+        
      
+          
    1. 
+            Return a Promise promise and execute the next steps asynchronously.
+          
      2. 
+          
    2. 
+            If a Property with propertyName does not exist, reject promise with a ReferenceError and terminate these steps.
+          
      3. 
+          
    3. 
+            Otherwise, if no write handler has been defined for propertyName, the runtime implementation SHOULD update the Property value with value, resolve promise and terminate these steps.
+          
      4. 
+          
    4. 
+            Otherwise, invoke the write handler associated with propertyName providing value as argument. If it rejects, then reject promise with the same error, and resolve promise with the same value.
+          
      5. 
+        
    
+      
    
     
    
-
     
     
    The setActionHandler() method
    
       
    
         Takes name as string argument and action as argument of type ActionHandler. Sets the handler function for the specified Action matched by name. Throws on error. Returns a reference to the same object for supporting chaining.

From 294dbf16b3de0fe5200fd179955f38202eb3d5e4 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Tue, 3 Jul 2018 16:33:38 +0300
Subject: [PATCH 230/464] Fix example 7 for read and write handlers.

Signed-off-by: Zoltan Kis 
---
 index.html | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/index.html b/index.html
index e3114894..0b0b8a57 100644
--- a/index.html
+++ b/index.html
@@ -764,10 +764,9 @@ 
    Examples
    
           // define Thing business logic
           setInterval( async () => {
             let mock = Math.random()*100;
-            thing.writeProperty("temperature", mock);
-            let old = await thing.readProperty("temperature");
+            let old = await thing["temperature"].read();
             if (old < mock) {
-              thing.writeProperty("temperature", mock);
+              await thing["temperature"].write(mock);
               thing.emitEvent("onchange", mock);
             }
           }, 1000);

From 0899f4e1b7656efdb148699b52cbd3ca6d551d41 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Tue, 3 Jul 2018 22:14:45 +0300
Subject: [PATCH 231/464] Fix #129: WebIDL errors. Rename conflicting fields.

Signed-off-by: Zoltan Kis 
---
 index.html | 73 ++++++++++++++++++++++++++++++++----------------------
 1 file changed, 44 insertions(+), 29 deletions(-)

diff --git a/index.html b/index.html
index 0b0b8a57..9231d997 100644
--- a/index.html
+++ b/index.html
@@ -226,14 +226,14 @@ 
    The WoT object
    
       // [SecureContext]
       // [NamespaceObject]
       interface WoT {
-        Observable<ThingDescription> discover(optional ThingFilter filter);
+        Observable discover(optional ThingFilter filter);
         Promise<ThingDescription> fetch(USVString url);
         ConsumedThing consume(ThingDescription td);
         ExposedThing produce(ThingModel model);
         Promise<void> register(USVString directory, ExposedThing thing);
         Promise<void> unregister(USVString directory, ExposedThing thing);
       };
-      typedef dictionary ThingTemplate;
+      typedef object ThingTemplate;
       typedef USVString ThingDescription;
       typedef (ThingTemplate or ThingDescription or ConsumedThing) ThingModel;
     
    
@@ -488,14 +488,26 @@ 
    The ConsumedThing interface
    
     
    
     
           interface ConsumedThing {
-        readonly attribute maplike<DOMString, ThingProperty> properties;
-        readonly attribute maplike<DOMString, ThingAction> actions;
-        readonly attribute maplike<DOMString, ThingEvent> events;
+        readonly attribute Properties properties;
+        readonly attribute Actions actions;
+        readonly attribute Events events;
         readonly attribute FrozenArray<WebLink> links;
         // getter for ThingTemplate properties
         getter any(DOMString name);
       };
       ConsumedThing implements Observable;  // for TD changes
+      [NoInterfaceObject]
+      interface Properties {
+        maplike<DOMString, ThingProperty>;
+      };
+      [NoInterfaceObject]
+      interface Actions {
+        maplike<DOMString, ThingAction>;
+      };
+      [NoInterfaceObject]
+      interface Events {
+        maplike<DOMString, ThingEvent>;
+      };
     
    
     
    
       ConsumedThing represents a local proxy object of the remote Thing.
@@ -509,10 +521,9 @@ 
    The ConsumedThing interface
    
     
    
       The events property represents a dictionary of ThingEvent items.
     
    
-    
  • 
+    
    
       The links property represents an array of WebLink objects.
-    
    • 
-
+    
    
     
    
       
    Examples
    
       
    
@@ -981,7 +992,7 @@ 
    The ThingProperty interface
    
           getter any(DOMString name);
           // get and set interface for the Property
           Promise<any> read();
-          Promise write(any value);
+          Promise<void> write(any value);
         };
         ThingProperty implements PropertyInit;
         ThingProperty implements Observable;
@@ -999,7 +1010,7 @@ 
    The ThingProperty interface
    
         The observable read-only property tells whether the Property supports subscribing to value change notifications. If it is false, then the subscribe() method SHOULD always fail.
       
    
       
    
-        The const read-only property - defined in DataSchema - tells whether the Property value is a constant. If true, the set() and subscribe() methods SHOULD always fail.
+        The constant read-only property - defined in DataSchema - tells whether the Property value is a constant. If true, the set() and subscribe() methods SHOULD always fail.
       
    
       
    
         The required read-only property  - defined in DataSchema - tells whether the Property should be always present on the ExposedThing object.
@@ -1122,9 +1133,9 @@ 
    The ThingAction interface
    
         
               dictionary DataSchema {
             required DataType type;
-            boolean required = "false";
+            boolean mandatory = false;
             DOMString description;
-            boolean const;
+            boolean constant;
           };
         
    
         
    
@@ -1134,13 +1145,13 @@ 
    The ThingAction interface
    
           The type property represents the value type enumerated in DataType.
         
    
         
    
-          The required property tells whether this value is required to be speficied.
+          The mandatory property tells whether this value is required to be speficied.
         
    
         
    
           The description property represents a textual description of the value.
         
    
         
    
-          The const property tells whether this value is constant.
+          The constant property tells whether this value is constant.
         
    
       
    
 
@@ -1166,7 +1177,7 @@ 
    The ThingAction interface
    
       
    The BooleanSchema dictionary
    
         
               dictionary BooleanSchema: DataSchema {
-            const type = "boolean";
+            DOMString type = "boolean";
           };
         
    
         
    
@@ -1177,24 +1188,28 @@ 
    The ThingAction interface
    
       
    The StringSchema dictionary
    
         
               dictionary StringSchema: DataSchema {
-            const type = "string";
-            sequence<DOMString>? enum;
+            DOMString type = "string";
+            sequence<DOMString>? enumeration;
           };
         
    
         
    
           The type property MUST have the value "string".
         
    
         
    
-          The enum property represents the list of allowed string values as a string array.
+          The enumeration property represents the list of allowed string values as a string array.
         
    
       
    
 
       
    The ObjectSchema dictionary
    
         
    +          [NoInterfaceObject]
+          interface SchemaProperties {
+            maplike<DOMString, DataSchema>;
+          };
           dictionary ObjectSchema: DataSchema {
-            const type = "object";
-            maplike<DOMString, DataSchema>? properties;
-            sequence<DOMString> required;
+            DOMString type = "object";
+            SchemaProperties? properties;
+            sequence<DOMString> mandatory;
           };
         
    
         
    
@@ -1204,14 +1219,14 @@ 
    The ThingAction interface
    
           The properties property is a dictionary that contains the names and types of each of the object properties. If not provided in the dictionary object, it SHOULD be initialized to undefined. The value null is accepted, as well as an empty object.
         
    
         
    
-          The required property is a string array that containes the names that are mandatory to be present from the object properties. If not provided, it SHOULD be initialized to undefined. An empty array is accepted.
+          The mandatory property is a string array that containes the names that are mandatory to be present from the object properties. If not provided, it SHOULD be initialized to undefined. An empty array is accepted.
         
    
       
    
 
       
    The ArraySchema dictionary
    
         
               dictionary ArraySchema: DataSchema {
-            const type = "array";
+            DOMString type = "array";
             DataSchema? items;
             unsigned long minItems;
             unsigned long maxItems;
@@ -1460,7 +1475,7 @@ 
     The SecurityScheme dictionary
    
       
     The BasicSecurityScheme dictionary
    
       
             dictionary BasicSecurityScheme: SecurityScheme {
-          const scheme = "basic";
+          DOMString scheme = "basic";
           DOMString in;
           DOMString pname;
         };
@@ -1480,7 +1495,7 @@ 
     The BasicSecurityScheme dictionary
    
       
     The DigestSecurityScheme dictionary
    
       
             dictionary DigestSecurityScheme: BasicSecurityScheme {
-          const scheme = "digest";
+          DOMString scheme = "digest";
           DOMString qop = "auth";
         };
       
    
@@ -1496,7 +1511,7 @@ 
     The DigestSecurityScheme dictionary
    
       
     The BearerSecurityScheme dictionary
    
       
             dictionary BearerSecurityScheme: BasicSecurityScheme {
-          const scheme = "bearer";
+          DOMString scheme = "bearer";
           USVString authorizationURL;
           DOMString alg = "ES256";
           DOMString format = "jwt";
@@ -1523,7 +1538,7 @@ 
     The PopSecurityScheme dictionary
    
       
    
       
             dictionary PopSecurityScheme: DigestSecurityScheme {
-          const scheme = "pop";
+          DOMString scheme = "pop";
         };
       
    
       
    
@@ -1538,7 +1553,7 @@ 
     The ApikeySecurityScheme dictionary
    
       
    
       
             dictionary ApikeySecurityScheme: BasicSecurityScheme {
-          const scheme = "apikey";
+          DOMString scheme = "apikey";
         };
       
    
       
    
@@ -1553,7 +1568,7 @@ 
     The OAuth2SecurityScheme dictionary
    
       
    
       
             dictionary OAuth2SecurityScheme: SecurityScheme {
-          const scheme = "oauth2";
+          DOMString scheme = "oauth2";
           USVString tokenURL;
           USVString authorizationURL;
           USVString refreshURL;

From cc8935e038b5896c01968e29bf3e6c2203b27d36 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Wed, 4 Jul 2018 08:36:48 +0300
Subject: [PATCH 232/464] Remove Promise from emitEvent()

Signed-off-by: Zoltan Kis 
---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index 9231d997..c9c8d5eb 100644
--- a/index.html
+++ b/index.html
@@ -580,7 +580,7 @@ 
    The ExposedThing interface
    
         ExposedThing removeAction(DOMString name);
         // define Events
         ExposedThing addEvent(DOMString name, EventInit event);
-        Promise<void> emitEvent(DOMString eventName, any payload);
+        void emitEvent(DOMString eventName, any payload);
         ExposedThing removeEvent(DOMString name);
       };
       callback PropertyReadHandler = Promise<any>();

From f3b137063baec773b25dffb1d6e56ae868cebf79 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Wed, 4 Jul 2018 21:06:59 +0300
Subject: [PATCH 233/464] Simplify the Observer subset used in WoT Scripting,
 as agreed on the Korea F2F.

Signed-off-by: Zoltan Kis 
---
 index.html | 43 +++++++++++++++++++------------------------
 1 file changed, 19 insertions(+), 24 deletions(-)

diff --git a/index.html b/index.html
index c9c8d5eb..772b75fd 100644
--- a/index.html
+++ b/index.html
@@ -1368,7 +1368,7 @@ 
    Observables
    
     
    
     
           interface Observable {
-        Subscription subscribe((Observer or OnNext) next,
+        Subscription subscribe(OnNext next,
                                optional OnError error,
                                optional OnComplete complete);
       };
@@ -1376,33 +1376,25 @@ 
    Observables
    
         void unsubscribe();
         readonly attribute boolean closed;
       };
-      interface Observer {
-        void next(any value);
-        void error(Error error);
-        void complete();
-      };
       callback OnNext = void (any value);
       callback OnError = void (Error error);
       callback OnComplete = void ();
     
    
 
-    
    
-      
    The Observer interface
    
-      
    
-        The Observer interface defines the callbacks needed to handle an Observable:
+    
    
+        The following callbacks can be provided when subscribing to an Observable:
+        
      
+          
    • 
+            The OnNext callback takes the next sample for the data in the value argument.
+          
      • 
+          
    • 
+            The OnError callback takes an error in the value argument. It is called when an error occured in producing the data the client should know about.
+          
      • 
+          
    • 
+            The OnComplete callback is called when the data source has finished sending values.
+          
      • 
+        
    
       
    
-      
      
-        
    • 
-          The next() function, as well as the OnNext callback takes the next sample for the data in the value argument.
-        
      • 
-        
    • 
-          The error() function, as well as the OnError callback takes an error in the value argument. It is called when an error occured in producing the data the client should know about.
-        
      • 
-        
    • 
-          The complete() function, as well as the OnComplete callback is called when the data source has finished sending values.
-        
      • 
-      
    
-    
    
 
     
    
       
    The Subscription interface
    
@@ -1421,10 +1413,13 @@ 
    The Observable interface
    
       
    
       
      
         
    • 
-          If the subscribe() method is called with an Observer object, initialize the data, error and completion handling callbacks from that object, or throw on error.
+          Initialize the data handler callback with the first function argument.
+        
      • 
+        
    • 
+          If the next argument is provided and is a function, initialize the error handling callback with that function, or throw on error.
         
      • 
         
    • 
-          Otherwise, if the subscribe() method is called with a function, initialize the data handler callback with that function. If the next argument is provided and is a function, initialize the error handling callback with that function, or throw on error. If the third argument is provided and is a function, initialize the completion handler with that function, or throw on error.
+          If the third argument is provided and is a function, initialize the completion handler with that function, or throw on error.
         
      • 
         
    • 
           After callback initializations, the implementation should request the underlying platform to provide data, error and completion notifications for the supported data source.

From 7a97c53db09aedbc607a038438df0df9574c9a2b Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Wed, 4 Jul 2018 21:43:07 +0300
Subject: [PATCH 234/464] Rename Observable callbacks to suit event handling
 better. Add onEvent() method to ConsumedThing. Add a third ActionHandler
 parameter to addAction() and remove setActionHandler().

Signed-off-by: Zoltan Kis 
---
 index.html | 46 ++++++++++++++++++++++++++--------------------
 1 file changed, 26 insertions(+), 20 deletions(-)

diff --git a/index.html b/index.html
index 772b75fd..d0c50e95 100644
--- a/index.html
+++ b/index.html
@@ -494,6 +494,8 @@ 
      The ConsumedThing interface
      
         readonly attribute FrozenArray<WebLink> links;
         // getter for ThingTemplate properties
         getter any(DOMString name);
+        // event subscription
+        Observable onEvent(DOMString eventName);
       };
       ConsumedThing implements Observable;  // for TD changes
       [NoInterfaceObject]
@@ -524,6 +526,14 @@ 
      The ConsumedThing interface
      
     
      
       The links property represents an array of WebLink objects.
     
      
+
+    
       
      The onEvent() method
      
+      
      
+        Returns an Observable in order to allow subscribing to an Event identified by the eventName parameter.
+      
      
+    
      
+
+
     
      
       
      Examples
      
       
      
@@ -575,8 +585,7 @@ 
      The ExposedThing interface
      
         ExposedThing setPropertyWriteHandler(DOMString name, PropertyWriteHandler writeHandler);
         ExposedThing removeProperty(DOMString name);
         // define Actions
-        ExposedThing addAction(DOMString name, ActionInit action);
-        ExposedThing setActionHandler(DOMString name, ActionHandler action);
+        ExposedThing addAction(DOMString name, ActionInit init, ActionHandler action);
         ExposedThing removeAction(DOMString name);
         // define Events
         ExposedThing addEvent(DOMString name, EventInit event);
@@ -620,7 +629,13 @@ 
      The ExposedThing interface
      
 
     
       
      The addAction() method
      
       
      
-        Adds an Action with name defined by the name argument and qualifiers and initialization value provided by the action argument of type ActionInitto the Thing object and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+        Adds to the actions property of a Thing object an Action with name defined by the name argument, defines input and output data format by the init argument of type ActionInit, and adds the function provided in the action argument as a handler, then updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+      
      
+      
      
+        The provided action callback function will implement invoking an Action and SHOULD be called by implementations when a request for invoking the Action is received from the underlying platform. The callback will receive a parameters dictionary argument according to the definition in the init.input argument and will return a value of type defined by the init.output argument according to the value-matching algorithm.
+      
      
+      
      
+        There SHOULD be exactly one handler for any given Action. If no handler is initialized for any given Action, implementations SHOULD throw a TypeError.
       
      
     
       
 
@@ -720,17 +735,6 @@ 
      The ActionHandler callback
      
         
       
      
     
      
-    
       
      The setActionHandler() method
      
-      
      
-        Takes name as string argument and action as argument of type ActionHandler. Sets the handler function for the specified Action matched by name. Throws on error. Returns a reference to the same object for supporting chaining.
-      
      
-      
      
-        If provided, this callback function will implement invoking an Action and SHOULD be called by implementations when a request for invoking a Action is received from the underlying platform. The callback will receive a parameters dictionary argument.
-      
      
-      
      
-        There SHOULD be exactly one handler for any given Action. If no handler is initialized for any given Action, implementations SHOULD return error if the action is invoked by any client.
-      
      
-    
      
 
     
      
       
      Examples
      
@@ -1023,7 +1027,9 @@ 
      The ThingProperty interface
      
       
      
 
       
      The PropertyInit dictionary
      
+      
      
         Defines the standardized part of the dictionary that initializes a ThingProperty object.
+      
      
         
                 dictionary PropertyInit: InteractionInit {
             boolean writable = false;
@@ -1368,16 +1374,16 @@ 
      Observables
      
     
      
     
             interface Observable {
-        Subscription subscribe(OnNext next,
-                               optional OnError error,
+        Subscription subscribe(EventHandler handler,
+                               optional ErrorHandler errorHandler,
                                optional OnComplete complete);
       };
       interface Subscription {
         void unsubscribe();
         readonly attribute boolean closed;
       };
-      callback OnNext = void (any value);
-      callback OnError = void (Error error);
+      callback EventHandler = void (any value);
+      callback ErrorHandler = void (Error error);
       callback OnComplete = void ();
     
      
 
@@ -1385,10 +1391,10 @@ 
      Observables
      
         The following callbacks can be provided when subscribing to an Observable:
         
        
           
      • 
-            The OnNext callback takes the next sample for the data in the value argument.
+            The EventHandler callback takes the next sample for the data in the value argument.
           
        • 
           
      • 
-            The OnError callback takes an error in the value argument. It is called when an error occured in producing the data the client should know about.
+            The ErrorHandler callback takes an error in the value argument. It is called when an error occured in producing the data the client should know about.
           
        • 
           
      • 
             The OnComplete callback is called when the data source has finished sending values.

From c02e93f14bb66aee9f51bc65d4c4dcaf79e93e1f Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Wed, 4 Jul 2018 21:57:04 +0300
Subject: [PATCH 235/464] Separate Property value initialization from its
 schema. Specify Observable type in prose for discover().

Signed-off-by: Zoltan Kis 
---
 index.html | 10 +++-------
 1 file changed, 3 insertions(+), 7 deletions(-)

diff --git a/index.html b/index.html
index d0c50e95..53e488b6 100644
--- a/index.html
+++ b/index.html
@@ -359,7 +359,7 @@ 
        The ThingTemplate dictionary
        
     
         
        The discover() method
        
       
        
         Starts the discovery process that will provide ThingDescriptions that match the optional argument ThingFilter. When the argument is not provided, uses all supported discovery methods.
-        Returns an [Observable](https://github.com/tc39/proposal-observable) object that can be subscribed to and unsubscribed from. Errors are also signaled at the subscription object.
+        Returns an [Observable](https://github.com/tc39/proposal-observable) object that can be subscribed to and unsubscribed from. Errors are also signaled at the subscription object. When subscribing, the handler function provided to the Observable will receive an argument of type USVString representing a ThingDescription.
       
        
       
        
         Note that canceling a discovery (via invoking unsubscribe()) may not be successful in all cases, for instance when discovery is based on open ended multicast requests. However, once unsubscribe() has been called,  implementations MUST suppress further event handling ( i.e. further discoveries and errors) on the Observable. Also, a discovery error may not mean the end of the discovery process. However, in order to respect Observable semantics (error always terminates processing), implementations MUST close or suppress further event handling on the Observable.
@@ -580,7 +580,7 @@ 
        The ExposedThing interface
        
         Promise<void> expose();
         Promise<void> destroy();
         // define Properties
-        ExposedThing addProperty(DOMString name, PropertyInit property);
+        ExposedThing addProperty(DOMString name, PropertyInit property, optional any initValue);
         ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
         ExposedThing setPropertyWriteHandler(DOMString name, PropertyWriteHandler writeHandler);
         ExposedThing removeProperty(DOMString name);
@@ -617,7 +617,7 @@ 
        The ExposedThing interface
        
 
     
         
        The addProperty() method
        
       
        
-        Adds a Property with name defined by the name argument and qualifiers and initialization value provided by the property argument of type PropertyInit. It updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+        Adds a Property with name defined by the name argument, the data schema provided by the property argument of type PropertyInit, and optionally an initial value provided in the argument initValue whose type should match the one defined in the type property according to the value-matching algorithm. If initValue is not provided, it SHOULD be initialized as undefined. Implementations SHOULD update the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
        
     
         
 
@@ -1034,7 +1034,6 @@ 
        The ThingProperty interface
        
           dictionary PropertyInit: InteractionInit {
             boolean writable = false;
             boolean observable = false;
-            any value;  // initialization value
           };
           PropertyInit implements DataSchema;
         
      
@@ -1044,9 +1043,6 @@ 
      The ThingProperty interface
      
       
      
         The observable property initializes observability access to the Property. The default value is false.
       
      
-        
      
-          The value property represents the initialization value of the property. Its type should match the one defined in the type property. If not provided in the dictionary object, it SHOULD be initialized as undefined.
-        
      
       
      
     
      
 

From 625c78715ed1b7570ce8ee280298f148ba966166 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Mon, 23 Jul 2018 12:11:22 +0300
Subject: [PATCH 236/464] Remove obsolete 'mandatory' property from DataSchema.
 Improve text on 'onEvent()'

Signed-off-by: Zoltan Kis 
---
 index.html | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/index.html b/index.html
index 53e488b6..ca1f96a0 100644
--- a/index.html
+++ b/index.html
@@ -529,7 +529,7 @@ 
      The ConsumedThing interface
      
 
     
       
      The onEvent() method
      
       
      
-        Returns an Observable in order to allow subscribing to an Event identified by the eventName parameter.
+        Returns an Observable in order to allow subscribing to an Event identified by the eventName parameter. When subscribing to the Observable, an event handler, and error handler and a completion handler can be specified and a Subscription object is returned that provides an unsubscribe() method.
       
      
     
      
 
@@ -1135,7 +1135,6 @@ 
      The ThingAction interface
      
         
                 dictionary DataSchema {
             required DataType type;
-            boolean mandatory = false;
             DOMString description;
             boolean constant;
           };
@@ -1146,9 +1145,6 @@ 
      The ThingAction interface
      
         
      
           The type property represents the value type enumerated in DataType.
         
      
-        
      
-          The mandatory property tells whether this value is required to be speficied.
-        
      
         
      
           The description property represents a textual description of the value.
         
      

From d47801a218df87741b10b18660d89fb3c652b8c0 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Mon, 23 Jul 2018 15:29:05 +0300
Subject: [PATCH 237/464] Change Event model from onEvent() and emitEvent() to
 emit() contained in the Event object and subscribe/unsubscribe through
 Observable

Signed-off-by: Zoltan Kis 
---
 index.html | 30 ++++++++++++------------------
 1 file changed, 12 insertions(+), 18 deletions(-)

diff --git a/index.html b/index.html
index ca1f96a0..b67fe9cc 100644
--- a/index.html
+++ b/index.html
@@ -494,8 +494,6 @@ 
      The ConsumedThing interface
      
         readonly attribute FrozenArray<WebLink> links;
         // getter for ThingTemplate properties
         getter any(DOMString name);
-        // event subscription
-        Observable onEvent(DOMString eventName);
       };
       ConsumedThing implements Observable;  // for TD changes
       [NoInterfaceObject]
@@ -527,13 +525,6 @@ 
      The ConsumedThing interface
      
       The links property represents an array of WebLink objects.
     
      
 
-    
       
      The onEvent() method
      
-      
      
-        Returns an Observable in order to allow subscribing to an Event identified by the eventName parameter. When subscribing to the Observable, an event handler, and error handler and a completion handler can be specified and a Subscription object is returned that provides an unsubscribe() method.
-      
      
-    
      
-
-
     
      
       
      Examples
      
       
      
@@ -589,7 +580,6 @@ 
      The ExposedThing interface
      
         ExposedThing removeAction(DOMString name);
         // define Events
         ExposedThing addEvent(DOMString name, EventInit event);
-        void emitEvent(DOMString eventName, any payload);
         ExposedThing removeEvent(DOMString name);
       };
       callback PropertyReadHandler = Promise<any>();
@@ -609,12 +599,6 @@ 
      The ExposedThing interface
      
       
      
     
      
 
-    
       
      The emitEvent() method
      
-      
      
-        Emits an the event initialized with the event name specified by the eventName argument and data specified by the payload argument.
-      
      
-    
      
-
     
       
      The addProperty() method
      
       
      
         Adds a Property with name defined by the name argument, the data schema provided by the property argument of type PropertyInit, and optionally an initial value provided in the argument initValue whose type should match the one defined in the type property according to the value-matching algorithm. If initValue is not provided, it SHOULD be initialized as undefined. Implementations SHOULD update the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
@@ -1089,16 +1073,26 @@ 
      The ThingAction interface
      
       
      
     
    
 
-    
    The ThingEvent interface
    
+    
    The ThingEvent interface
    
       
             interface ThingEvent {
+          void emit(any payload);
         };
         ThingEvent implements ThingProperty;
       
    
+      
     
    The emit() method
    
+        
    
+          Emits an event that carries data specified by the payload argument.
+        
    
+      
    
+
       
    
-        The data events are carrying is represented as a Property. ThingEvent SHOULD also implement the event mechanism of the underlying platform (such as a DOM Event or a Node.js Event).
+        Since ThingEvent implements Observable through the ThingProperty interface, event subscription is done by invoking the subscribe() method on the event object that returns a cancelable Subscription.
       
    
       
    The EventInit dictionary
    
+        
    
+          Event data is represented as a Property.
+        
    
         
               typedef PropertyInit EventInit;
         
    

From d14616325ffeabfe76e0f16b89cb359e20871b7c Mon Sep 17 00:00:00 2001
From: danielpeintner 
Date: Mon, 30 Jul 2018 14:28:35 +0200
Subject: [PATCH 238/464] docs: add information about available TypeScript
 definititions

---
 README.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/README.md b/README.md
index 32d026e9..8fa0aee0 100644
--- a/README.md
+++ b/README.md
@@ -14,3 +14,10 @@ See the [applications/script-manager](./applications/script-manager/README.md) o
 See the [applications/thing-directory](./applications/thing-directory/README.md) on the design of a Thing directory (reverse proxy) that would cache nearby Things, provide a single point of access and synchronize with the cached Things.
 
 To make contributions, please refer to [https://github.com/w3c/wotwg#contributing](https://github.com/w3c/wotwg#contributing).
+
+## TypeScript Definitions
+
+The specification uses WebIDL definitions. TypeScript definititions are also available (see https://github.com/thingweb/wot-typescript-definitions/blob/master/index.d.ts).
+
+Due to different implementation progress the definitions might be out of sync. However, there are regular sync points usually based on publication releases.
+Note: For future releases we plan to use TypeScript instead of WebIDL in the specification.

From c6f32a51e2a56fc5a956b68ace3b78ee260a1e50 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Mon, 6 Aug 2018 13:26:21 +0300
Subject: [PATCH 239/464] Change ThingTemplate to ThingFragment, updates to
 reflect changes in TypeScript definitions

Signed-off-by: Zoltan Kis 
---
 index.html | 188 ++++++++++++++++++++++++++---------------------------
 1 file changed, 94 insertions(+), 94 deletions(-)

diff --git a/index.html b/index.html
index b67fe9cc..c1116860 100644
--- a/index.html
+++ b/index.html
@@ -233,9 +233,9 @@ 
    The WoT object
    
         Promise<void> register(USVString directory, ExposedThing thing);
         Promise<void> unregister(USVString directory, ExposedThing thing);
       };
-      typedef object ThingTemplate;
+      typedef object ThingFragment;
       typedef USVString ThingDescription;
-      typedef (ThingTemplate or ThingDescription or ConsumedThing) ThingModel;
+      typedef (ThingFragment or ThingDescription) ThingModel;
     
    
 
     
    
@@ -243,67 +243,9 @@ 
    The WoT object
    
     
    
 
     
    
-      The ThingModel type represents either a ThingTemplate, or a ThingDescription or a ConsumedThing object.
+      The ThingModel type represents either a ThingFragment, or a ThingDescription.
     
    
 
-    
    
-    
    The ThingDescription type
    
-      
    
-        Serialized representation of the Thing Description (a JSON-LD document).
-      
    
-      
    
-        In this version of the API, Thing Descriptions are represented as an opaque USVString that can be transmitted between devices.
-      
    
-    
    
-
-    
    
-      
    The ThingTemplate dictionary
    
-      
    
-        ThingTemplate is a dictionary that contains properties representing semantic metadata and interactions (Properties, Actions and Events). It is used for initializing an internal representation of a Thing Description as defined in [[!WOT-TD]], and it is also used in ThingFilter. The set of core properties is defined below. In addition, ThingTemplate may contain other properties as well as defined in the Thing Description from which the Thing object is created.
-      
    
-      
      
-        
    • 
-          The name attribute represents the name of the Thing as DOMString. In the Thing Description this attribute is mandatory, but in ThingFilter it is optional.
-        
      • 
-        
    • 
-          The id optional attribute represents an application provided hint for the unique identifier of the Thing, typically a URI, IRI, or URN as USVString. Note that this is not the same as the JSON-LD @id attribute. Also note that the WoT Runtime may override this with a different value when exposing the Thing.
-        
      • 
-        
    • 
-          The description optional attribute of type DOMString represents a human readable description of the Thing.
-        
      • 
-        
    • 
-          The support optional attribute of type DOMString represents human readable information about the TD maintainer.
-        
      • 
-        
    • 
-          The security optional attribute represents security metadata defined by the SecurityScheme dictionary;
-        
      • 
-        
    • 
-          The properties optional attribute represents a dictionary with keys that correspond to Property names and values of type PropertyInit.
-        
      • 
-        
    • 
-          The actions optional attribute represents a dictionary with keys that correspond to Action names and values of type ActionInit.
-        
      • 
-        
    • 
-          The events optional attribute represents a dictionary with keys that correspond to Event names and values of type EventInit.
-        
      • 
-        
    • 
-          The links optional attribute represents an array of WebLink objects.
-        
      • 
-        
    • 
-          The @context optional attribute represents a semantic context as USVString.
-        
      • 
-        
    • 
-          The @type optional attribute represents a semantic type as USVString.
-        
      • 
-        
    • 
-          Apart from the core properties defined above, others may also be defined on a Thing, for instance "@id", "gms:COVParams" (with namespace definition), or "iotschema:unit" etc.
-        
      • 
-      
    
-      
    
-        Support for configuration and security metadata will be added later.
-      
    
-    
     
-
     
     
     The fetch() method
    
       
    
         Accepts an url argument of type USVString that represents a URL (e.g. "file://..." or "https://...") and returns a Promise that resolves with a ThingDescription (a serialized JSON-LD document of type USVString).
@@ -322,7 +264,7 @@ 
    The ThingTemplate dictionary
    
       
    
       
      
         
    1. 
-          from a ThingTemplate, then adding Properties, Actions, Events and request handlers;
+          from a ThingFragment, then adding Properties, Actions, Events and request handlers;
         
      2. 
         
    2. 
           from a Thing Description or a ConsumedThing object, then adding request handlers.
@@ -394,10 +336,10 @@ 
      The ThingFilter dictionary
      
         
      
         
                 dictionary ThingFilter {
-            DiscoveryMethod method = "any";
-            USVString url;
-            USVString query;
-            ThingTemplate template;
+            (DiscoveryMethod or DOMString) method = "any";
+            USVString? url;
+            USVString? query;
+            ThingFragment? fragment;
           };
         
      
         
      
@@ -410,10 +352,7 @@ 
      The ThingFilter dictionary
      
           The query property represents a query string accepted by the implementation, for instance a SPARQL or JSON query. Support may be implemented locally in the WoT Runtime or remotely as a service in a Thing Directory.
         
      
         
      
-          The template property represents a ThingTemplate dictionary used for matching against discovered Things.
-        
      
-        
      
-          Queries and templates are experimental features. Implementations are not required to support them. The template matching algorithm will be defined later, but there are two possibilities: either direct matching (property to property) or serializing the template and matching that against TDs.
+          The fragment property represents a ThingFragment dictionary used for matching property by property against discovered Things.
         
      
       
    
       
    
@@ -487,12 +426,12 @@ 
    The ConsumedThing interface
    
       The ConsumedThing interface is a client API for sending requests to servers in order to retrieve or update Properties, invoke Actions, and observe Properties and Events.
     
    
     
    -      interface ConsumedThing {
+      interface ConsumedThing: ThingFragment {
         readonly attribute Properties properties;
         readonly attribute Actions actions;
         readonly attribute Events events;
         readonly attribute FrozenArray<WebLink> links;
-        // getter for ThingTemplate properties
+        // getter for ThingFragment properties
         getter any(DOMString name);
       };
       ConsumedThing implements Observable;  // for TD changes
@@ -565,7 +504,7 @@ 
    The ExposedThing interface
    
     
           ExposedThing implements ConsumedThing;
       interface ExposedThing {
-        // setter for ThingTemplate properties
+        // setter for ThingFragment properties
         setter void(DOMString name, any value);
         // define how to expose and run the Thing
         Promise<void> expose();
@@ -886,9 +825,85 @@ 
    Examples
    
   
    
     
    Data types used in a Thing
    
     
    
-      Every Thing describes its metadata as defined in ThingTemplate, and basic interactions as defined in ConsumedThing: Properties, Actions and Events. The following data types are used for representing these interactions, as defined in [[!WOT-TD]].
+      Every Thing describes its metadata as defined in ThingFragment, and basic interactions defined as Properties, Actions and Events. The following data types are used for representing these interactions, as defined in [[!WOT-TD]].
     
    
 
+    
    
+    
    The ThingDescription type
    
+      
    
+        Serialized representation of the Thing Description (a JSON-LD document).
+      
    
+      
    
+        In this version of the API, Thing Descriptions are represented as an opaque USVString that can be transmitted between devices.
+      
    
+    
    
+
+    
    
+      
    The ThingFragment dictionary
    
+      
    
+        ThingFragment is a dictionary that contains properties representing semantic metadata and interactions (Properties, Actions and Events). It is used for initializing an internal representation of a Thing Description as defined in [[!WOT-TD]], and it is also used in ThingFilter. The set of core properties is defined below. In addition, ThingFragment may contain other properties as well as defined in the Thing Description from which the Thing object is created.
+      
    
+      
      
+        
    • 
+          The name attribute represents the name of the Thing as DOMString. In the Thing Description this attribute is mandatory, but in ThingFilter it is optional.
+        
      • 
+        
    • 
+          The id optional attribute represents an application provided hint for the unique identifier of the Thing, typically a URI, IRI, or URN as USVString. The WoT Runtime might override this with a different value when exposing the Thing.
+        
      • 
+        
    • 
+          The description optional attribute of type DOMString represents a human readable description of the Thing.
+        
      • 
+        
    • 
+          The support optional attribute of type DOMString represents human readable information about the TD maintainer.
+        
      • 
+        
    • 
+          The security optional attribute represents security metadata defined by the SecurityScheme dictionary;
+        
      • 
+        
    • 
+          The properties optional attribute represents a dictionary with keys that correspond to Property names and values of type PropertyInit.
+        
      • 
+        
    • 
+          The actions optional attribute represents a dictionary with keys that correspond to Action names and values of type ActionInit.
+        
      • 
+        
    • 
+          The events optional attribute represents a dictionary with keys that correspond to Event names and values of type EventInit.
+        
      • 
+        
    • 
+          The links optional attribute represents an array of WebLink objects.
+        
      • 
+        
    • 
+          The @context optional attribute represents a semantic context as USVString.
+        
      • 
+        
    • 
+          The @type optional attribute represents a semantic type as USVString.
+        
      • 
+        
    • 
+          Apart from the core properties defined above, others may also be defined on a Thing, for instance "@id", "gms:COVParams" (with namespace definition), or "iotschema:unit" etc.
+        
      • 
+      
    
+      
    
+        Support for configuration and security metadata will be added later.
+      
    
+    
     
+
+    
    
+      
    The InteractionInit dictionary
    
+      
    
+      
    
+      
    +        dictionary InteractionInit {
+          DOMString? label;
+          DOMString? description;
+        };
+      
    
+      
    
+        The label property initializes the text label for the interaction.
+      
    
+      
    
+        The description property initializes the description for the interaction.
+      
    
+    
     
+
     
    The Link dictionary
    
       
             dictionary Link {
@@ -936,34 +951,19 @@ 
    The Interaction interface
    
         The Interaction interface is an abstract class to represent Thing interactions: Properties, Actions and Events.
       
    
       
    
-        The InteractionInit dictionary holds the common properties of PropertyInit, ActionInit and EventInit dictionaries used for initializing ThingProperty, ThingAction and ThingEvent objects in a ThingTemplate dictionary used for creating an ExposedThing object.
+        The InteractionInit dictionary holds the common properties of PropertyInit, ActionInit and EventInit dictionaries used for initializing ThingProperty, ThingAction and ThingEvent objects in a ThingFragment dictionary used for creating an ExposedThing object.
       
    
 
       
             interface Interaction {
-          attribute DOMString label;
           readonly attribute FrozenArray<Form> forms;
         };
+        Interaction implements InteractionInit;
         Interaction implements Observable;
       
    
-      
    
-        The label property represents a text label for the interaction.
-      
    
       
    
         The forms read-only property represents the protocol bindings initialization data and is initialized by the WoT Runtime.
       
    
-
-      
    The InteractionInit dictionary
    
-        
    -          dictionary InteractionInit {
-            DOMString label;
-          };
-        
    
-        
    
-          The label property initializes the text label for the interaction.
-        
    
-      
    
-
     
    
 
     
    
@@ -972,7 +972,7 @@ 
    The ThingProperty interface
    
         The ThingProperty interface is used in ConsumedThing and ExposedThing objects to represent Thing Property interactions.
       
    
       
    
-        The PropertyInit dictionary is used for initializing Property objects in a ThingTemplate dictionary used for creating an ExposedThing object. It MUST implement one of the DataSchema dictionaries.
+        The PropertyInit dictionary is used for initializing Property objects in a ThingFragment dictionary used for creating an ExposedThing object. It MUST implement one of the DataSchema dictionaries.
       
    
       
             interface ThingProperty: Interaction {
@@ -1104,7 +1104,7 @@ 
    The ThingAction interface
    
 
     
    Value types
    
       
    
-        Value types are used in Property, Event and Action parameter definitions in a ThingTemplate. Basically correspond to a JSON object definition.
+        Value types are used in Property, Event and Action parameter definitions in a ThingFragment. Basically correspond to a JSON object definition.
       
    
 
       
    The DataType enumeration type
    
@@ -1713,7 +1713,7 @@ 
     The OAuth2SecurityScheme dictionary
    
     
    
       
      
         
    • 
-          Synchronized the Scripting API with the [Thing Description specification](https://w3c.github.io/wot-thing-description/). Defined ThingDescription, ThingTemplate, data type descriptions, etc. Refined discovery filtering.
+          Synchronized the Scripting API with the [Thing Description specification](https://w3c.github.io/wot-thing-description/). Defined ThingDescription, ThingFragment, data type descriptions, etc. Refined discovery filtering.
         
      • 
       
    
     
    

From ac32871a62a389aadf0f0e50a47cb21883543371 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Mon, 6 Aug 2018 16:29:31 +0300
Subject: [PATCH 240/464] Add ThingInstance, ExposedEvent, ExposedEvents.
 Update ConsumedThing, ExposedThing, ThingFragment. Change names to
 InteractionFragment, PropertyFragment, ActionFragment, EventFragment from
 xxxInit.

Signed-off-by: Zoltan Kis 
---
 index.html | 257 ++++++++++++++++++++++++++++++-----------------------
 1 file changed, 147 insertions(+), 110 deletions(-)

diff --git a/index.html b/index.html
index c1116860..a4f4e9ba 100644
--- a/index.html
+++ b/index.html
@@ -420,21 +420,22 @@ 
    The ThingFilter dictionary
    
     
     
   
     
 
-  
    
-    
    The ConsumedThing interface
    
+  
    
+    
    The ThingInstance interface
    
     
    
-      The ConsumedThing interface is a client API for sending requests to servers in order to retrieve or update Properties, invoke Actions, and observe Properties and Events.
+      Represents an object that extends a ThingFragment with methods for interactions (reading and writing Properties), invoking Actions, subscribe and unsubscribe for Property changes and Events.
     
    
     
    -      interface ConsumedThing: ThingFragment {
+      interface ThingInstance: ThingFragment {
+        readonly attribute DOMString id;
+        readonly attribute DOMString name;
+        readonly attribute DOMString? base;
         readonly attribute Properties properties;
         readonly attribute Actions actions;
         readonly attribute Events events;
-        readonly attribute FrozenArray<WebLink> links;
         // getter for ThingFragment properties
         getter any(DOMString name);
       };
-      ConsumedThing implements Observable;  // for TD changes
       [NoInterfaceObject]
       interface Properties {
         maplike<DOMString, ThingProperty>;
@@ -449,21 +450,40 @@ 
    The ConsumedThing interface
    
       };
     
    
     
    
-      ConsumedThing represents a local proxy object of the remote Thing.
+      The id attribute represents the unique identifier of the Thing instance, typically a URI, IRI, or URN as USVString.
     
    
     
    
-      The properties property represents a dictionary of ThingProperty items.
+      The name attribute represents the name of the Thing as DOMString.
     
    
     
    
-      The actions property represents a dictionary of ThingAction items.
+      The base attribute represents the base URI that is valid for all defined local interaction resources.
     
    
     
    
-      The events property represents a dictionary of ThingEvent items.
+      The properties attribute represents a dictionary of ThingProperty items.
     
    
     
    
-      The links property represents an array of WebLink objects.
+      The actions attribute represents a dictionary of ThingAction items.
     
    
+    
    
+      The events attribute represents a dictionary of ThingEvent items.
+    
    
+  
    
+
+  
    
 
+  
    
+    
    The ConsumedThing interface
    
+    
    
+      The ConsumedThing interface is a client API for sending requests to servers in order to retrieve or update Properties, invoke Actions, and observe Properties and Events.
+    
    
+    
    +      interface ConsumedThing: ThingInstance {
+      };
+      ConsumedThing implements Observable;  // for TD changes
+    
    
+    
    
+      ConsumedThing represents a local proxy object of the remote Thing.
+    
    
     
    
       
    Examples
    
       
    
@@ -499,33 +519,42 @@ 
    Examples
    
   
    
     
    The ExposedThing interface
    
     
    
-      The ExposedThing interface is the server API that allows defining request handlers, properties, Actions, and Events to a Thing. It also implements the ConsumedThing interface. An ExposedThing is created by the produce() method.
+      The ExposedThing interface is the server API that allows defining request handlers, properties, Actions, and Events to a Thing. It also implements the Observable interface. An ExposedThing is created by the produce() method.
     
    
     
    -      ExposedThing implements ConsumedThing;
-      interface ExposedThing {
-        // setter for ThingFragment properties
+      interface ExposedThing: ThingInstance {
+        readonly attribute ExposedEvents events;
+        // setter for ThingInstance properties
         setter void(DOMString name, any value);
         // define how to expose and run the Thing
         Promise<void> expose();
         Promise<void> destroy();
         // define Properties
-        ExposedThing addProperty(DOMString name, PropertyInit property, optional any initValue);
+        ExposedThing addProperty(DOMString name, PropertyFragment property, optional any initValue);
         ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
         ExposedThing setPropertyWriteHandler(DOMString name, PropertyWriteHandler writeHandler);
         ExposedThing removeProperty(DOMString name);
         // define Actions
-        ExposedThing addAction(DOMString name, ActionInit init, ActionHandler action);
+        ExposedThing addAction(DOMString name, ActionFragment init, ActionHandler action);
         ExposedThing removeAction(DOMString name);
         // define Events
-        ExposedThing addEvent(DOMString name, EventInit event);
+        ExposedThing addEvent(DOMString name, EventFragment event);
         ExposedThing removeEvent(DOMString name);
       };
+      [NoInterfaceObject]
+      interface ExposedEvents {
+        maplike<DOMString, ExposedEvent>;
+      };
       callback PropertyReadHandler = Promise<any>();
       callback PropertyWriteHandler = Promise<void>(any value);
       callback ActionHandler = Promise<any>(any parameters);
+      ExposedThing implements Observable;
     
    
 
+    
    
+      The events attribute represents a dictionary of ExposedEvent items that add the emit() method to the ThingEvent definition.
+    
    
+
     
     
    The expose() method
    
       
    
         Start serving external requests for the Thing, so that WoT interactions using Properties, Actions and Events will be possible.
@@ -540,7 +569,7 @@ 
    The ExposedThing interface
    
 
     
     
    The addProperty() method
    
       
    
-        Adds a Property with name defined by the name argument, the data schema provided by the property argument of type PropertyInit, and optionally an initial value provided in the argument initValue whose type should match the one defined in the type property according to the value-matching algorithm. If initValue is not provided, it SHOULD be initialized as undefined. Implementations SHOULD update the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+        Adds a Property with name defined by the name argument, the data schema provided by the property argument of type PropertyFragment, and optionally an initial value provided in the argument initValue whose type should match the one defined in the type property according to the value-matching algorithm. If initValue is not provided, it SHOULD be initialized as undefined. Implementations SHOULD update the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
    
     
     
 
@@ -552,7 +581,7 @@ 
    The ExposedThing interface
    
 
     
     
    The addAction() method
    
       
    
-        Adds to the actions property of a Thing object an Action with name defined by the name argument, defines input and output data format by the init argument of type ActionInit, and adds the function provided in the action argument as a handler, then updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+        Adds to the actions property of a Thing object an Action with name defined by the name argument, defines input and output data format by the init argument of type ActionFragment, and adds the function provided in the action argument as a handler, then updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
    
       
    
         The provided action callback function will implement invoking an Action and SHOULD be called by implementations when a request for invoking the Action is received from the underlying platform. The callback will receive a parameters dictionary argument according to the definition in the init.input argument and will return a value of type defined by the init.output argument according to the value-matching algorithm.
@@ -570,7 +599,7 @@ 
    The ExposedThing interface
    
 
     
     
    The addEvent() method
    
       
    
-        Adds an event with name defined by the name argument and qualifiers and initialization value provided by the event argument of type EventInitto the Thing object and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+        Adds an event with name defined by the name argument and qualifiers and initialization value provided by the event argument of type EventFragmentto the Thing object and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
    
     
    
 
@@ -845,10 +874,10 @@ 
    The ThingFragment dictionary
    
       
    
       
      
         
    • 
-          The name attribute represents the name of the Thing as DOMString. In the Thing Description this attribute is mandatory, but in ThingFilter it is optional.
+          The id optional attribute represents an application provided hint for the unique identifier of the Thing, typically a URI, IRI, or URN as USVString. The WoT Runtime might override this with a different value when exposing the Thing.
         
      • 
         
    • 
-          The id optional attribute represents an application provided hint for the unique identifier of the Thing, typically a URI, IRI, or URN as USVString. The WoT Runtime might override this with a different value when exposing the Thing.
+          The name attribute represents the name of the Thing as DOMString. In the Thing Description this attribute is mandatory, but in ThingFilter it is optional.
         
      • 
         
    • 
           The description optional attribute of type DOMString represents a human readable description of the Thing.
@@ -860,13 +889,13 @@ 
      The ThingFragment dictionary
      
           The security optional attribute represents security metadata defined by the SecurityScheme dictionary;
         
      • 
         
    • 
-          The properties optional attribute represents a dictionary with keys that correspond to Property names and values of type PropertyInit.
+          The properties optional attribute represents a dictionary with keys that correspond to Property names and values of type PropertyFragment.
         
      • 
         
    • 
-          The actions optional attribute represents a dictionary with keys that correspond to Action names and values of type ActionInit.
+          The actions optional attribute represents a dictionary with keys that correspond to Action names and values of type ActionFragment.
         
      • 
         
    • 
-          The events optional attribute represents a dictionary with keys that correspond to Event names and values of type EventInit.
+          The events optional attribute represents a dictionary with keys that correspond to Event names and values of type EventFragment.
         
      • 
         
    • 
           The links optional attribute represents an array of WebLink objects.
@@ -886,12 +915,12 @@ 
      The ThingFragment dictionary
      
       
      
     
     
 
-    
    
-      
    The InteractionInit dictionary
    
+    
    
+      
    The InteractionFragment dictionary
    
       
    
       
    
       
    -        dictionary InteractionInit {
+        dictionary InteractionFragment {
           DOMString? label;
           DOMString? description;
         };
@@ -902,46 +931,58 @@ 
    The InteractionInit dictionary
    
       
    
         The description property initializes the description for the interaction.
       
    
-    
     
+    
    
 
-    
    The Link dictionary
    
-      
    -        dictionary Link {
-          required USVString href;
-          USVString mediaType;
-          DOMString rel;
-        };
-      
    
+    
    
+      
    The PropertyFragment dictionary
    
       
    
-        The href property is a hypertext reference that defines the Link.
+        Defines the standardized part of the dictionary that initializes a ThingProperty object.
       
    
+        
    +          dictionary PropertyFragment: InteractionFragment {
+            boolean writable = false;
+            boolean observable = false;
+          };
+          PropertyFragment implements DataSchema;
+        
    
       
    
-        The mediaType property represents the IANA media type associated with the Link.
+        The writable property initializes access to the Property value. The default value is false.
       
    
       
    
-        The rel property represents a semantic label that specifies how to interact with the linked resource.
+        The observable property initializes observability access to the Property. The default value is false.
       
    
     
    
 
-    
    The WebLink dictionary
    
+    
    
+      
    The ActionFragment dictionary
    
       
    -        dictionary WebLink: Link {
-          USVString anchor;
+        dictionary ActionFragment: InteractionFragment {
+          DataSchema? input;
+          DataSchema? output;
+          DOMString description;
         };
       
    
       
    
-        The anchor property represents a URI that overrides the default context of a Link.
+        The input property initializes the input of type DataSchema to the ThingAction. Multiple arguments can be provided by applications as an array or as an object.
+      
    
+      
    
+        The output property initializes the output of type DataSchema of the ThingAction.
+      
    
+      
    
+        The description read-only property initializes a human-readable textual description of the Action interaction.
       
    
     
    
 
-    
    The Form dictionary
    
+    
    
+      
    The EventFragment dictionary
    
+      
    
+        Event data is represented as a Property.
+      
    
       
    -        dictionary Form: Link {
-          SecurityScheme security;
-        };
+        typedef PropertyFragment EventFragment;
       
    
       
    
-        The security property represents the security requirements for the linked resource.
+        The value an event is carrying is initialized as a Property value.
       
    
     
    
 
@@ -951,15 +992,14 @@ 
    The Interaction interface
    
         The Interaction interface is an abstract class to represent Thing interactions: Properties, Actions and Events.
       
    
       
    
-        The InteractionInit dictionary holds the common properties of PropertyInit, ActionInit and EventInit dictionaries used for initializing ThingProperty, ThingAction and ThingEvent objects in a ThingFragment dictionary used for creating an ExposedThing object.
+        The InteractionFragment dictionary holds the common properties of PropertyFragment, ActionFragment and EventFragment dictionaries used for initializing ThingProperty, ThingAction and ThingEvent objects in a ThingFragment dictionary used for creating an ExposedThing object.
       
    
 
       
             interface Interaction {
           readonly attribute FrozenArray<Form> forms;
         };
-        Interaction implements InteractionInit;
-        Interaction implements Observable;
+        Interaction implements InteractionFragment;
       
    
       
    
         The forms read-only property represents the protocol bindings initialization data and is initialized by the WoT Runtime.
@@ -972,21 +1012,21 @@ 
    The ThingProperty interface
    
         The ThingProperty interface is used in ConsumedThing and ExposedThing objects to represent Thing Property interactions.
       
    
       
    
-        The PropertyInit dictionary is used for initializing Property objects in a ThingFragment dictionary used for creating an ExposedThing object. It MUST implement one of the DataSchema dictionaries.
+        The PropertyFragment dictionary is used for initializing Property objects in a ThingFragment dictionary used for creating an ExposedThing object. It MUST implement one of the DataSchema dictionaries.
       
    
       
             interface ThingProperty: Interaction {
-          // getter for PropertyInit properties
+          // getter for PropertyFragment properties
           getter any(DOMString name);
           // get and set interface for the Property
           Promise<any> read();
           Promise<void> write(any value);
         };
-        ThingProperty implements PropertyInit;
+        ThingProperty implements PropertyFragment;
         ThingProperty implements Observable;
       
    
       
    
-        The ThingProperty interface contains all the properties defined on PropertyInit as read-only properties.
+        The ThingProperty interface contains all the properties defined on PropertyFragment as read-only properties.
       
    
       
    
         The type read-only property represents the type definition for the Property. If it matches a DataType, then it MUST implement the corresponding DataSchema dictionary.
@@ -1009,25 +1049,6 @@ 
    The ThingProperty interface
    
       
    
         The write() method will attempt to set the value of the Propertyspecified in the value argument whose type SHOULD match the o9ne specified by the type property. Returns a Promise that resolves on success, or rejects on an error.
       
    
-
-      
    The PropertyInit dictionary
    
-      
    
-        Defines the standardized part of the dictionary that initializes a ThingProperty object.
-      
    
-        
    -          dictionary PropertyInit: InteractionInit {
-            boolean writable = false;
-            boolean observable = false;
-          };
-          PropertyInit implements DataSchema;
-        
    
-      
    
-        The writable property initializes access to the Property value. The default value is false.
-      
    
-      
    
-        The observable property initializes observability access to the Property. The default value is false.
-      
    
-      
    
     
    
 
     
    
@@ -1052,54 +1073,70 @@ 
    The ThingAction interface
    
       
    
         The invoke() method when invoked, starts the Action interaction with the input value provided by the inputValue argument. If inputValue is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided. Otherwise the type of inputValue SHOULD match the DataSchema definition in the input property. Returns a Promise that will reject with an error or will resolve with a value of type defined by the output property.
       
    
-
-      
    The ActionInit dictionary
    
-        
    -          dictionary ActionInit: InteractionInit {
-            DataSchema? input;
-            DataSchema? output;
-            DOMString description;
-          };
-        
    
-        
    
-          The input property initializes the input of type DataSchema to the ThingAction. Multiple arguments can be provided by applications as an array or as an object.
-        
    
-        
    
-          The output property initializes the output of type DataSchema of the ThingAction.
-        
    
-        
    
-          The description read-only property initializes a human-readable textual description of the Action interaction.
-        
    
-      
    
     
    
 
     
    The ThingEvent interface
    
       
    -        interface ThingEvent {
+        interface ThingEvent: ThingProperty {
+        };
+      
    
+      
    
+        Since ThingEvent implements Observable through the ThingProperty interface, event subscription is done by invoking the subscribe() method on the event object that returns a cancelable Subscription.
+      
    
+    
    
+
+    
    The ExposedEvent interface
    
+      
    +        interface ExposedEvent: ThingEvent {
           void emit(any payload);
         };
-        ThingEvent implements ThingProperty;
       
    
       
     
    The emit() method
    
         
    
           Emits an event that carries data specified by the payload argument.
         
    
       
    
+    
    
+
+    
    The Link dictionary
    
+      
    +        dictionary Link {
+          required USVString href;
+          USVString mediaType;
+          DOMString rel;
+        };
+      
    
+      
    
+        The href property is a hypertext reference that defines the Link.
+      
    
+      
    
+        The mediaType property represents the IANA media type associated with the Link.
+      
    
+      
    
+        The rel property represents a semantic label that specifies how to interact with the linked resource.
+      
    
+    
    
 
+    
    The WebLink dictionary
    
+      
    +        dictionary WebLink: Link {
+          USVString anchor;
+        };
+      
    
       
    
-        Since ThingEvent implements Observable through the ThingProperty interface, event subscription is done by invoking the subscribe() method on the event object that returns a cancelable Subscription.
+        The anchor property represents a URI that overrides the default context of a Link.
+      
    
+    
    
+
+    
    The Form dictionary
    
+      
    +        dictionary Form: Link {
+          SecurityScheme security;
+        };
+      
    
+      
    
+        The security property represents the security requirements for the linked resource.
       
    
-      
    The EventInit dictionary
    
-        
    
-          Event data is represented as a Property.
-        
    
-        
    -          typedef PropertyInit EventInit;
-        
    
-        
    
-          The value an event is carrying is initialized as a Property value.
-        
    
-      
    
     
    
 
     
    Value types
    
@@ -1241,7 +1278,7 @@ 
    The ThingAction interface
    
 
     
    The value-matching algorithm
    
       
    
-        The value-matching algorithm is applied to a value input in relation to a valueType property of type DataSchema, for instance the value and type properties of a PropertyInit object, or the inputValue parameter to the invoke() method of a ThingAction object in relation to the same object. It executes the following steps:
+        The value-matching algorithm is applied to a value input in relation to a valueType property of type DataSchema, for instance the value and type properties of a PropertyFragment object, or the inputValue parameter to the invoke() method of a ThingAction object in relation to the same object. It executes the following steps:
         
      
           
    1. 
             If valueType.type is not defined, or does not fully match a string enumerated in DataType, return false.

From f69e63391e732392ec9940ee7a4cdb544269005b Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Tue, 7 Aug 2018 13:21:06 +0300
Subject: [PATCH 241/464] Editorial changes fixing review comments in
 https://github.com/w3c/wot-scripting-api/pull/128#issuecomment-410974898

Signed-off-by: Zoltan Kis 
---
 index.html | 164 ++++++++++++++++++++++-------------------------------
 1 file changed, 67 insertions(+), 97 deletions(-)

diff --git a/index.html b/index.html
index a4f4e9ba..7689ab17 100644
--- a/index.html
+++ b/index.html
@@ -97,7 +97,7 @@
 
   
      
     
      
-      The overall Web of Things (WoT) concepts are described in the [WoT Architecture](https://w3c.github.io/wot-architecture/) document. The Web of Things is made of entities (Things) that can describe their capabilities in a machine-interpretable format, the Thing Description (TD) and expose these capabilities through the WoT Interface, 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 overall Web of Things (WoT) concepts are described in the WoT Architecture document. The Web of Things is made of entities (Things) that can describe their capabilities in a machine-interpretable format, the Thing Description (TD) and expose these capabilities through the WoT Interface, 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.
     
      
     
      
       This specification describes a programming interface representing the WoT Interface that allows scripts run on a Thing to discover and consume (retrieve) other Thing Descriptions and to expose Things characterized by  WoT Interactions specified by a script.
@@ -109,7 +109,7 @@
 
   
      
     
      
-      Implementers need to be aware that this specification is considered unstable. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation phase should subscribe to the [repository](https://github.com/w3c/wot-scripting-api) and take part in the discussions.
+      Implementers need to be aware that this specification is considered unstable. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation phase should subscribe to the repository and take part in the discussions.
     
      
     
      
       Please contribute to this draft using the GitHub Issue feature of the WoT Scripting API repository.
@@ -134,7 +134,7 @@
       This specification does not make assumptions on how the WoT Runtime handles and runs scripts, including single or multiple tenancy, script deployment and lifecycle management. The API already supports the generic mechanisms that make it possible to implement script management, for instance by exposing a manager Thing whose Actions (action handlers) implement script lifecycle management operations.
     
      
     
      
-      For an introduction on how scripts could be used in Web of Things, check the [Primer](https://w3c.github.io/wot-scripting-api/primer) document. For some background on API design decisions check the [Rationale](https://w3c.github.io/wot-scripting-api/rationale) document.
+      For an introduction on how scripts could be used in Web of Things, check the Primer document. For some background on API design decisions check the Rationale document.
     
      
   
      
 
@@ -246,58 +246,6 @@ 
      The WoT object
      
       The ThingModel type represents either a ThingFragment, or a ThingDescription.
     
      
 
-    
       
       The fetch() method
      
-      
      
-        Accepts an url argument of type USVString that represents a URL (e.g. "file://..." or "https://...") and returns a Promise that resolves with a ThingDescription (a serialized JSON-LD document of type USVString).
-      
      
-    
      
-
-    
       
       The consume() method
      
-      
      
-        Accepts an td argument of type ThingDescription and returns a ConsumedThing object instantiated based on parsing that description.
-      
      
-    
      
-
-    
       
      The produce() method
      
-      
      
-        Accepts a model argument of type ThingModel and returns an ExposedThing object. An ExposedThing can be created in the following ways:
-      
      
-      
        
-        
      1. 
-          from a ThingFragment, then adding Properties, Actions, Events and request handlers;
-        
        2. 
-        
      2. 
-          from a Thing Description or a ConsumedThing object, then adding request handlers.
-        
        3. 
-      
      
-    
       
-
-    
       
      The register() method
      
-      
      
-        Takes two mandatory arguments:
-        
      
-      
      
-      
      
-        Generate the Thing Description as td, given the Properties, Actions and Events defined for this ExposedThing object. Then make a request to register td to the given WoT Thing Directory.
-      
      
-    
      
-
-    
       
      The unregister() method
      
-      
      
-        Takes two mandatory arguments:
-        
      
-      
      
-      
      
-        Makes a request to unregister the thing from the given WoT Thing Directory.
-      
      
-    
      
-
     
       
      The discover() method
      
       
      
         Starts the discovery process that will provide ThingDescriptions that match the optional argument ThingFilter. When the argument is not provided, uses all supported discovery methods.
@@ -360,6 +308,58 @@ 
      The ThingFilter dictionary
      
       
      
     
       
 
+    
       
       The fetch() method
      
+      
      
+        Accepts an url argument of type USVString that represents a URL (e.g. "file://..." or "https://...") and returns a Promise that resolves with a ThingDescription (a serialized JSON-LD document of type USVString).
+      
      
+    
      
+
+    
       
       The consume() method
      
+      
      
+        Accepts an td argument of type ThingDescription and returns a ConsumedThing object instantiated based on parsing that description.
+      
      
+    
      
+
+    
       
      The produce() method
      
+      
      
+        Accepts a model argument of type ThingModel and returns an ExposedThing object. An ExposedThing can be created in the following ways:
+      
      
+      
        
+        
      1. 
+          from a ThingFragment, then adding Properties, Actions, Events and request handlers;
+        
        2. 
+        
      2. 
+          from a Thing Description or a ConsumedThing object, then adding request handlers.
+        
        3. 
+      
      
+    
       
+
+    
       
      The register() method
      
+      
      
+        Takes two mandatory arguments:
+        
      
+      
      
+      
      
+        Generate the Thing Description as td, given the Properties, Actions and Events defined for this ExposedThing object. Then make a request to register td to the given WoT Thing Directory.
+      
      
+    
      
+
+    
       
      The unregister() method
      
+      
      
+        Takes two mandatory arguments:
+        
      
+      
      
+      
      
+        Makes a request to unregister the thing from the given WoT Thing Directory.
+      
      
+    
      
+
     
       
      Examples
      
       
               let discoveryFilter = {
@@ -395,28 +395,6 @@ 
      The ThingFilter dictionary
      
           complete: () => { console.log("Discovery finished successfully");}
         });
       
      
-      
      -        // Use a proprietary extension of "local" discovery via "constraints"
-        let bleSub = wot.discover({
-          method: "local",
-          constraints: [{ protocol: "BLE-4.2" }, { protocol: "NFC" }]
-        }).subscribe(
-          td => { console.log("Found nearby Thing " + td.name); },
-          error => { console.log("Discovery error: " + error.message); }
-        );
-      
      
-      
      -        let subscription = wot.discover({
-          method: "myOwnMethod", // not standardized
-          url: myDirectoryURL,
-          // includes non-standard, app-specific property "constraints"
-          constraints: [{ account: "XYZ123", key: "..."}]
-        }).subscribe(
-          td => { console.log("Found Thing " + td.name); },
-          error => { console.log("Discovery error: " + error.message); },
-          () => { console.log("Discovery finished successfully");}
-        );
-      
      
     
       
   
       
 
@@ -495,9 +473,8 @@ 
      Examples
      
             td => {
               let thing = wot.consume(td);
               console.log("Thing " + thing.name + " has been consumed.");
-              let subscription = thing.onPropertyChange("temperature")
-                .subscribe(function(value) {
-                  console.log("Temperature + " has changed to " + value);
+              let subscription = thing["temperature"].subscribe(function(value) {
+                  console.log("Temperature: " + value);
                 });
               thing.actions["startMeasurement"].invoke({ units: "Celsius" })
                 .then(() => { console.log("Temperature measurement started."); })
@@ -698,7 +675,6 @@ 
      Examples
      
         try {
           var temperatureValueDefinition = {
             type: "number",
-            value: 0.0,
             minimum: -50,
             maximum: 10000
           };
@@ -725,9 +701,8 @@ 
      Examples
      
             },
             links: []
           });
-          thing.expose().then(() => {
-              thing.register();
-          });
+          await thing.expose();
+          await wot.register("https://mydirectory.org", thing);
           // define Thing business logic
           setInterval( async () => {
             let mock = Math.random()*100;
@@ -772,7 +747,6 @@ 
      Examples
      
             properties: {
               brightness: {
                 type: "number",
-                value: 0.0,
                 minimum: 0.0,
                 maximum: 100.0,
                 required: true,
@@ -805,7 +779,7 @@ 
      Examples
      
       
               let thingDescription = '{ \
           "name": "mySensor", \
-          "@context": [ "https://w3c.github.io/wot/w3c-wot-td-context.jsonld",\
+          "@context": [ "http://www.w3.org/ns/td",\
              "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ],\
           "@type": [ "Thing", "Sensor" ], \
           "geo:location": "testspace", \
@@ -959,7 +933,6 @@ 
      The ActionFragment dictionary
      
         dictionary ActionFragment: InteractionFragment {
           DataSchema? input;
           DataSchema? output;
-          DOMString description;
         };
       
      
       
      
@@ -968,9 +941,6 @@ 
      The ActionFragment dictionary
      
       
      
         The output property initializes the output of type DataSchema of the ThingAction.
       
      
-      
      
-        The description read-only property initializes a human-readable textual description of the Action interaction.
-      
      
     
    
 
     
    
@@ -1055,11 +1025,9 @@ 
    The ThingProperty interface
    
       
    The ThingAction interface
    
       
             interface ThingAction: Interaction {
-          readonly attribute DataSchema? input;
-          readonly attribute DataSchema? output;
-          readonly attribute DOMString description;
           Promise<any> invoke(optional any inputValue);
         };
+        ThingAction implements ActionFragment;
       
    
       
    
         The input read-only property represents the input of type DataSchema to the ThingAction. Multiple arguments can be provided by applications as an array or as an object. If the value is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided.
@@ -1077,8 +1045,10 @@ 
    The ThingAction interface
    
 
     
    The ThingEvent interface
    
       
    -        interface ThingEvent: ThingProperty {
+        interface ThingEvent: Interaction {
         };
+        ThingEvent implements EventFragment;
+        ThingEvent implements ThingProperty;
       
    
       
    
         Since ThingEvent implements Observable through the ThingProperty interface, event subscription is done by invoking the subscribe() method on the event object that returns a cancelable Subscription.
@@ -1730,7 +1700,7 @@ 
     The OAuth2SecurityScheme dictionary
    
       This specification can be used for implementing the WoT Scripting API in multiple programming languages. The interface definitions are specified in [[!WEBIDL]].
     
    
     
    
-      The user agent (UA) may be implemented in the browser, or in a separate runtime environment, such as [Node.js](https://nodejs.org/en/) or small embedded runtimes.
+      The user agent (UA) may be implemented in the browser, or in a separate runtime environment, such as Node.js or small embedded runtimes.
     
    
     
    
       Implementations that use ECMAScript executed in a browser to implement the APIs defined in this document MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]].
@@ -1745,12 +1715,12 @@ 
     The OAuth2SecurityScheme dictionary
    
 
   
    Changes
    
     
    
-      The following is a list of major changes to the document. For a complete list of changes, see the [github change log](https://github.com/w3c/wot-scripting-api/commits/master). You can also view the [recently closed bugs](https://github.com/w3c/wot-scripting-api/issues?page=1&state=closed).
+      The following is a list of major changes to the document. For a complete list of changes, see the github change log. You can also view the recently closed issues.
     
    
     
    
       
      
         
    • 
-          Synchronized the Scripting API with the [Thing Description specification](https://w3c.github.io/wot-thing-description/). Defined ThingDescription, ThingFragment, data type descriptions, etc. Refined discovery filtering.
+          Synchronized the Scripting API with the Thing Description specification. Defined ThingDescription, ThingFragment, data type descriptions, etc. Refined discovery filtering.
         
      • 
       
    
     
    

From 5e14e47a1fba33efcbcbc972796993d412e260bb Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Tue, 7 Aug 2018 13:27:36 +0300
Subject: [PATCH 242/464] Fix SecurityScheme with description and proxyURI.

Signed-off-by: Zoltan Kis 
---
 index.html | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/index.html b/index.html
index 7689ab17..238dc4eb 100644
--- a/index.html
+++ b/index.html
@@ -1458,11 +1458,19 @@ 
     The SecurityScheme dictionary
    
       
             dictionary SecurityScheme {
           required SecuritySchemeType scheme;
+          DOMString? description;
+          USVString? proxyURI;
         };
       
    
       
    
         The scheme property represents the identification of the security scheme to be used for the Thing.
       
    
+      
    
+        The description property provides human readable information about the security scheme.
+      
    
+      
    
+        The proxyURI property represents the URI of the proxy server to which the security configuration containing the scheme provides access. If not provided, it means that the  security configuration refers directly to the endpoint.
+      
    
     
    
 
     
    

From 2f4fbee756ae60867b4b3c46dd713f0c174502ed Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Tue, 7 Aug 2018 14:06:07 +0300
Subject: [PATCH 243/464] Add missing textual definitions for maplike
 structures.

Signed-off-by: Zoltan Kis 
---
 index.html | 32 +++++++++++++-------------------
 1 file changed, 13 insertions(+), 19 deletions(-)

diff --git a/index.html b/index.html
index 238dc4eb..21a4865c 100644
--- a/index.html
+++ b/index.html
@@ -408,22 +408,22 @@ 
    The ThingInstance interface
    
         readonly attribute DOMString id;
         readonly attribute DOMString name;
         readonly attribute DOMString? base;
-        readonly attribute Properties properties;
-        readonly attribute Actions actions;
-        readonly attribute Events events;
+        readonly attribute PropertyMap properties;
+        readonly attribute ActionMap actions;
+        readonly attribute EventMap events;
         // getter for ThingFragment properties
         getter any(DOMString name);
       };
       [NoInterfaceObject]
-      interface Properties {
+      interface PropertyMap {
         maplike<DOMString, ThingProperty>;
       };
       [NoInterfaceObject]
-      interface Actions {
+      interface ActionMap {
         maplike<DOMString, ThingAction>;
       };
       [NoInterfaceObject]
-      interface Events {
+      interface EventMap {
         maplike<DOMString, ThingEvent>;
       };
     
    
@@ -437,13 +437,13 @@ 
    The ThingInstance interface
    
       The base attribute represents the base URI that is valid for all defined local interaction resources.
     
    
     
    
-      The properties attribute represents a dictionary of ThingProperty items.
+      The properties attribute represents a dictionary of ThingProperty items. The PropertyMap interface represents a maplike dictionary where all values are ThingProperty objects.
     
    
     
    
-      The actions attribute represents a dictionary of ThingAction items.
+      The actions attribute represents a dictionary of ThingAction items. The ActionMap interface represents a maplike dictionary where all values are ThingAction objects.
     
    
     
    
-      The events attribute represents a dictionary of ThingEvent items.
+      The events attribute represents a dictionary of ThingEvent items. The EventMap interface represents a maplike dictionary where all values are ThingEvent objects.
     
    
   
    
 
@@ -529,7 +529,7 @@ 
    The ExposedThing interface
    
     
    
 
     
    
-      The events attribute represents a dictionary of ExposedEvent items that add the emit() method to the ThingEvent definition.
+      The events attribute represents a dictionary of ExposedEvent items that add the emit() method to the ThingEvent definition. The ExposedEvents interface represents a maplike dictionary where all values are ExposedEvent objects.
     
    
 
     
     
    The expose() method
    
@@ -1029,15 +1029,6 @@ 
    The ThingAction interface
    
         };
         ThingAction implements ActionFragment;
       
    
-      
    
-        The input read-only property represents the input of type DataSchema to the ThingAction. Multiple arguments can be provided by applications as an array or as an object. If the value is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided.
-      
    
-      
    
-        The output read-only property represents the output of type DataSchema of the ThingAction. If the value is null or undefined, the action does not return any values.
-      
    
-      
    
-        The description read-only property represents a human-readable textual description of the Action interaction.
-      
    
       
    
         The invoke() method when invoked, starts the Action interaction with the input value provided by the inputValue argument. If inputValue is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided. Otherwise the type of inputValue SHOULD match the DataSchema definition in the input property. Returns a Promise that will reject with an error or will resolve with a value of type defined by the output property.
       
    
@@ -1214,6 +1205,9 @@ 
    The ThingAction interface
    
         
    
           The type property MUST have the value "object".
         
    
+        
    
+          The SchemaProperties interface represents a maplike dictionary where all values are DataSchema objects.
+        
    
         
    
           The properties property is a dictionary that contains the names and types of each of the object properties. If not provided in the dictionary object, it SHOULD be initialized to undefined. The value null is accepted, as well as an empty object.
         
    

From 69e56023a1ece4299397740d710090ab88a47087 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Tue, 21 Aug 2018 17:45:55 +0300
Subject: [PATCH 244/464] Add the fetch() and consume() algorithms

Signed-off-by: Zoltan Kis 
---
 index.html | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/index.html b/index.html
index 21a4865c..1b154713 100644
--- a/index.html
+++ b/index.html
@@ -312,12 +312,58 @@ 
    The ThingFilter dictionary
    
       
    
         Accepts an url argument of type USVString that represents a URL (e.g. "file://..." or "https://...") and returns a Promise that resolves with a ThingDescription (a serialized JSON-LD document of type USVString).
       
    
+      
    
+        The fetch(url) method must run the following steps:
+        
      
+          
    1. 
+            Return a Promise promise and execute the next steps asynchronously.
+          
      2. 
+          
    2. 
+            If invoking fetch() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
+          
      3. 
+          
    3. 
+            If the argument url is not a URL, reject promise with TypeError and terminate these steps.
+          
      4. 
+          
    4. 
+            Make a request to fetch the content of url as described by the Protocol Bindings and wait for the reply. Let td be the returned content.
+          
      5. 
+          
    5. 
+            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 terminate these steps.
+          
      6. 
+          
    6. 
+            Otherwise resolve promise with td and terminate these steps.
+          
      7. 
+        
    
+      
    
     
    
 
     
     
     The consume() method
    
       
    
         Accepts an td argument of type ThingDescription and returns a ConsumedThing object instantiated based on parsing that description.
       
    
+      
    
+        The consume(td) method must run the following steps:
+        
      
+          
    1. 
+            If invoking fetch() is not allowed for the current scripting context for security reasons, throw a SecurityError and terminate these steps.
+          
      2. 
+          
    2. 
+            If the argument td is not a string, throw a TypeError and terminate these steps.
+          
      3. 
+          
    3. 
+            Create a ConsumedThing object thing initialized with the default values described in ThingFragment.
+          
      4. 
+          
    4. 
+            Parse td according to the JSON-LD grammar description in order to produce a JSON object json. Update thing with the properties and values defined in json.
+          
      5. 
+          
    5. 
+            If there was an error during the parsing, throw that error and terminate these steps.
+          
      6. 
+          
    6. 
+            Otherwise return thing.
+          
      7. 
+        
    
+      
    
     
    
 
     
     
    The produce() method
    

From 4d84e5d368de277c489d2fdcec2e7999a77925fb Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Thu, 23 Aug 2018 11:36:01 +0300
Subject: [PATCH 245/464] Add the discovery algorithm

Signed-off-by: Zoltan Kis 
---
 index.html | 95 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 83 insertions(+), 12 deletions(-)

diff --git a/index.html b/index.html
index 1b154713..e57493d4 100644
--- a/index.html
+++ b/index.html
@@ -248,13 +248,8 @@ 
    The WoT object
    
 
     
     
    The discover() method
    
       
    
-        Starts the discovery process that will provide ThingDescriptions that match the optional argument ThingFilter. When the argument is not provided, uses all supported discovery methods.
-        Returns an [Observable](https://github.com/tc39/proposal-observable) object that can be subscribed to and unsubscribed from. Errors are also signaled at the subscription object. When subscribing, the handler function provided to the Observable will receive an argument of type USVString representing a ThingDescription.
+        Starts the discovery process that will provide ThingDescriptions that match the optional argument filter of type ThingFilter. Returns an [Observable](https://github.com/tc39/proposal-observable) object that can be subscribed to and unsubscribed from. The handler function provided to the Observable during subscription will receive an argument of type USVString representing a ThingDescription.
       
    
-      
    
-        Note that canceling a discovery (via invoking unsubscribe()) may not be successful in all cases, for instance when discovery is based on open ended multicast requests. However, once unsubscribe() has been called,  implementations MUST suppress further event handling ( i.e. further discoveries and errors) on the Observable. Also, a discovery error may not mean the end of the discovery process. However, in order to respect Observable semantics (error always terminates processing), implementations MUST close or suppress further event handling on the Observable.
-      
    
-
       
    
         
    The DiscoveryMethod enumeration
    
         
    @@ -304,7 +299,83 @@ 
    The ThingFilter dictionary
    
         
    
       
    
       
    
-        If queries are specified, but not supported, implementations should signal a NotSupportedError on the subscription objects. For security errors (e.g. authentication error) a SecurityError should be signaled. For query validation errors a TypeError should be signaled. For other errors an Error should be signaled.
+        The discover(filter) method MUST run the following steps:
+        
      
+          
    1. 
+            If invoking discover() is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
+          
      2. 
+          
    2. 
+            Return an Observable obs and execute the next steps in parallel.
+          
      3. 
+          
    3. 
+            If obs.subscribe(handler, errorHandler, complete) is called, execute the following sub-steps:
+            
        
+              
      1. 
+                If the first argument handler is not defined or it is not a function, throw TypeError and terminate the algorithm. Otherwise configure handler to be invoked when a discovery hit happens.
+              
        2. 
+              
      2. 
+                If the second argument errorHandler is defined, but it is not a function, throw TypeError and terminate these steps. Otherwise if defined, save it to be invoked in error conditions.
+              
        3. 
+              
      3. 
+                If the third argument onComplete is defined, but it is not a function, throw TypeError and terminate these steps. Otherwise if defined, save it to be invoked when the discovery process finished for other reasons than having been canceled.
+              
        4. 
+              
      4. 
+                If filter.query is defined, pass it as an opaque string to the underlying implementation to be matched against discovered items. The underlying implementation is responsible to parse it e.g. as a SPARQL or JSON query and match it against the Thing Descriptions found during the discovery process. If queries are not supported, implementations SHOULD throw a NotSupported error and terminate these steps.
+              
        5. 
+              
      5. 
+                If filter.fragment is defined, and if it contains other properties than the ones defined in ThingFragment, throw TypeError and terminate these steps. Otherwise save the object for matching the discovered items against it.
+              
        6. 
+              
      6. 
+                Request the underlying platform to start the discovery process, with the following parameters:
+                
          
+                  
        • 
+                    If filter.method is not defined or the value is "any", use the widest discovery method supported by the underlying platform.
+                  
          • 
+                  
        • 
+                    Otherwise if filter.method is "local", use the local Thing Directory for discovery. Usually that defines Things deployed in the same device, or connected to the device in slave mode (e.g. sensors connected via Bluetooth or a serial connection).
+                  
          • 
+                  
        • 
+                    Otherwise if filter.method is "directory", use the remote Thing Directory specified in filter.url.
+                  
          • 
+                  
        • 
+                    Otherwise if filter.method is "multicast", use all the multicast discovery protocols supported by the underlying platform.
+                  
          • 
+                
        
+              
        7. 
+            
      
+          
      4. 
+          
    4. 
+            Whenever a new item td is discovered by the underlying platform, run the following sub-steps:
+            
        
+              
      1. 
+                If filter.query is defined, check if td is a match for the query. The matching algorithm is encapsulated by implementations. If that returns false, discard td and continue the discovery process.
+              
        2. 
+              
      2. 
+                If filter.fragment is defined, for each property defined in it, check if that property exists in td and has the same value. If this is false in any checks, discard td and continue the discovery process.
+              
        3. 
+              
      3. 
+                Otherwise if td has not been discarded in the previous steps, invoke the handler function with td as parameter.
+              
        4. 
+            
      
+          
      5. 
+          
    5. 
+            Whenever an error occurs during the discovery process, and if errorHandler is defined, invoke it with an argument of type Error whose message property is set to UnknownError unless there was an error code provided by the Protocol Bindings, in which case set it to that value.
+          
      6. 
+          
    6. 
+            When the discovery process is finished, and if onComplete is defined, invoke it run the cancel discovery steps.
+          
      7. 
+          
    7. 
+            When the obs.unsubscribe() method is called, run the following cancel discovery steps:
+            
        
+              
      1. 
+                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.
+              
        2. 
+              
      2. 
+                 Set obs.closed to false.
+              
        3. 
+            
      
+          
      8. 
+        
    
       
    
     
     
 
@@ -313,10 +384,10 @@ 
    The ThingFilter dictionary
    
         Accepts an url argument of type USVString that represents a URL (e.g. "file://..." or "https://...") and returns a Promise that resolves with a ThingDescription (a serialized JSON-LD document of type USVString).
       
    
       
    
-        The fetch(url) method must run the following steps:
+        The fetch(url) method MUST run the following steps:
         
      
           
    1. 
-            Return a Promise promise and execute the next steps asynchronously.
+            Return a Promise promise and execute the next steps in parallel.
           
      2. 
           
    2. 
             If invoking fetch() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
@@ -670,7 +741,7 @@ 
      The ActionHandler callback
      
         When an external request for reading Property propertyName is received, the runtime SHOULD execute the following steps:
         
        
           
      1. 
-            Return a Promise promise and execute the next steps asynchronously.
+            Return a Promise promise and execute the next steps in parallel.
           
        2. 
           
      2. 
             If a Property with propertyName does not exist, reject promise with a ReferenceError and terminate these steps.
@@ -696,7 +767,7 @@ 
        The ActionHandler callback
        
         When an external request for writing a Property propertyName with a new value value is received, the runtime SHOULD execute the following steps:
         
          
           
        1. 
-            Return a Promise promise and execute the next steps asynchronously.
+            Return a Promise promise and execute the next steps in parallel.
           
          2. 
           
        2. 
             If a Property with propertyName does not exist, reject promise with a ReferenceError and terminate these steps.
@@ -1409,7 +1480,7 @@ 
          Observables
          
       interface Observable {
         Subscription subscribe(EventHandler handler,
                                optional ErrorHandler errorHandler,
-                               optional OnComplete complete);
+                               optional OnComplete onComplete);
       };
       interface Subscription {
         void unsubscribe();

From 358ebb5f718e100aee421c5e980d596c612f1294 Mon Sep 17 00:00:00 2001
From: danielpeintner 
Date: Mon, 27 Aug 2018 10:50:27 +0200
Subject: [PATCH 246/464] fix: issue-30, DataSchema type must not be required

see https://github.com/w3c/wot-scripting-api/issues/133
---
 index.html | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/index.html b/index.html
index 21a4865c..4621607b 100644
--- a/index.html
+++ b/index.html
@@ -1126,7 +1126,7 @@ 
          The ThingAction interface
          
       
          The DataSchema dictionary
          
         
                     dictionary DataSchema {
-            required DataType type;
+            DataType type;
             DOMString description;
             boolean constant;
           };
@@ -1148,7 +1148,7 @@ 
          The ThingAction interface
          
       
          The NumberSchema dictionary
          
         
                     dictionary NumberSchema: DataSchema {
-            required DOMString type;
+            DataType type = "number"; /* | "integer"*/
             Number minimum;
             Number maximum;
           };
@@ -1167,7 +1167,7 @@ 
          The ThingAction interface
          
       
          The BooleanSchema dictionary
          
         
                     dictionary BooleanSchema: DataSchema {
-            DOMString type = "boolean";
+            DataType type = "boolean";
           };
         
          
         
          
@@ -1178,7 +1178,7 @@ 
          The ThingAction interface
          
       
          The StringSchema dictionary
          
         
                     dictionary StringSchema: DataSchema {
-            DOMString type = "string";
+            DataType type = "string";
             sequence<DOMString>? enumeration;
           };
         
          
@@ -1197,7 +1197,7 @@ 
          The ThingAction interface
          
             maplike<DOMString, DataSchema>;
           };
           dictionary ObjectSchema: DataSchema {
-            DOMString type = "object";
+            DataType type = "object";
             SchemaProperties? properties;
             sequence<DOMString> mandatory;
           };
@@ -1219,7 +1219,7 @@ 
          The ThingAction interface
          
       
          The ArraySchema dictionary
          
         
                     dictionary ArraySchema: DataSchema {
-            DOMString type = "array";
+            DataType type = "array";
             DataSchema? items;
             unsigned long minItems;
             unsigned long maxItems;

From fc3d7bb2b0d13b15d89709fa7181ab20e6d9a649 Mon Sep 17 00:00:00 2001
From: danielpeintner 
Date: Tue, 28 Aug 2018 10:15:33 +0200
Subject: [PATCH 247/464] add IntegerSchema dictionary

* removes type "Number"
* adds IntegerSchema
* uses dedicated types for minimum/maximum
---
 index.html | 35 +++++++++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 8 deletions(-)

diff --git a/index.html b/index.html
index 4621607b..6a241ea9 100644
--- a/index.html
+++ b/index.html
@@ -1114,14 +1114,14 @@ 
          The ThingAction interface
          
         
          
       
          
 
-      
          The Number type
          
+      
 
       
          The DataSchema dictionary
          
         
          @@ -1148,19 +1148,38 @@ 
          The ThingAction interface
          
       
          The NumberSchema dictionary
          
         
                     dictionary NumberSchema: DataSchema {
-            DataType type = "number"; /* | "integer"*/
-            Number minimum;
-            Number maximum;
+            DataType type = "number";
+            unrestricted double minimum;
+            unrestricted double maximum;
+          };
+        
          
+        
          
+          The type property MUST have the value "number" (representing a floating point number) as defined by the underlying platform.
+        
          
+        
          
+          The minimum property defines the minimum value that can be used.
+        
          
+        
          
+          The maximum property defines the maximum value that can be used.
+        
          
+      
          
+	  
+      
          The IntegerSchema dictionary
          
+        
          +          dictionary IntegerSchema: DataSchema {
+            DataType type = "integer";
+            long minimum;
+            long maximum;
           };
         
          
         
          
-          The type property MUST have either the value "number" (representing a floating point number) or "integer" (representing an integer) as defined by the underlying platform.
+          The type property MUST have the value "integer" (representing an integer) as defined by the underlying platform.
         
          
         
          
-          The minimum property may be present when the value is of type "number" and if present, it defines the minimum value that can be used.
+          The minimum property defines the minimum value that can be used.
         
          
         
          
-          The maximum property may be present when the value is of type "number" and if present, it defines the maximum value that can be used.
+          The maximum property defines the maximum value that can be used.
         
          
       
          
 

From 9bc19253908af5b96640dd2b1e3f5b22a753468b Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Wed, 29 Aug 2018 15:44:05 +0300
Subject: [PATCH 248/464] Add algorithm for produce(), TD parsing, Thing
 instantiation

Signed-off-by: Zoltan Kis 
---
 index.html | 76 ++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 63 insertions(+), 13 deletions(-)

diff --git a/index.html b/index.html
index a319be4e..6deec5d7 100644
--- a/index.html
+++ b/index.html
@@ -422,16 +422,16 @@ 
          The ThingFilter dictionary
          
             If the argument td is not a string, throw a TypeError and terminate these steps.
           
          3. 
           
        3. 
-            Create a ConsumedThing object thing initialized with the default values described in ThingFragment.
+            Let model be the result of running the TD parsing algorithm with td as argument. If that throws an error, re-throw the error and terminate these steps.
           
          4. 
           
        4. 
-            Parse td according to the JSON-LD grammar description in order to produce a JSON object json. Update thing with the properties and values defined in json.
+            Let instance be the result of running the Thing instantiation algorithm with model as argument.
           
          5. 
           
        5. 
-            If there was an error during the parsing, throw that error and terminate these steps.
+            Create a ConsumedThing object thing initialized from instance.
           
          6. 
           
        6. 
-            Otherwise return thing.
+            Return thing.
           
          7. 
         
        
       
        
@@ -440,15 +440,65 @@ 
        The ThingFilter dictionary
        
     
         
        The produce() method
        
       
        
         Accepts a model argument of type ThingModel and returns an ExposedThing object. An ExposedThing can be created in the following ways:
+        
          
+          
        1. 
+            from a ThingFragment, then adding Properties, Actions, Events and request handlers;
+          
          2. 
+          
        2. 
+            from a Thing Description, then adding request handlers.
+          
          3. 
+        
        
+      
        
+      
        
+        The produce(url) method MUST run the following steps:
+        
          
+          
        1. 
+            If invoking produce() is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
+          
          2. 
+          
        2. 
+            If the argument model is a string, then run the TD parsing algorithm with model passed as parameter. If it throws an error, re-throw that error and terminate this algorithm. Otherwise let model be the returned value.
+          
          3. 
+          
        3. 
+            If model is not an object, throw TypeError and terminate these steps.
+          
          4. 
+          
        4. 
+            Let instance be the result of running the Thing instantiation algorithm with model passed as parameter.
+          
          5. 
+          
        5. 
+            Create an ExposedThing object thing initialized from instance.
+          
          6. 
+          
        6. 
+            Return thing.
+        
        
+      
        
+      
        
+        The TD parsing algorithm takes a string td as argument and runs the following steps:
+        
          
+          
        1. 
+            Parse td according to the WoT Thing Description in order to produce a JSON object json. Update thing with the properties and values defined in json.
+          
          2. 
+          
        2. 
+            If there was an error during the parsing, throw that error and terminate these steps.
+          
          3. 
+          
        3. 
+            Otherwise return json.
+          
          4. 
+        
        
+      
        
+      
        
+        The Thing instantiation algorithm takes an object model as argument and runs the following steps:
+        
          
+          
        1. 
+            If model does not have an own property that is defined in ThingFragment with a default value, add that property and value to model.
+          
          2. 
+          
        2. 
+            Let instance be a ThingInstance object initialized with model properties.
+          
          3. 
+          
        3. 
+            Return instance.
+          
          4. 
+        
        
       
        
-      
          
-        
        1. 
-          from a ThingFragment, then adding Properties, Actions, Events and request handlers;
-        
          2. 
-        
        2. 
-          from a Thing Description or a ConsumedThing object, then adding request handlers.
-        
          3. 
-      
        
     
         
 
     
         
        The register() method
        
@@ -1280,7 +1330,7 @@ 
        The ThingAction interface
        
           The maximum property defines the maximum value that can be used.
         
        
       
        
-	  
+
       
        The IntegerSchema dictionary
        
         
                   dictionary IntegerSchema: DataSchema {

From 7215a1dd0ec708215f2334770823e2bdfab0b026 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Mon, 3 Sep 2018 22:06:55 +0300
Subject: [PATCH 249/464] Merge ThingInstance into ConsumedThing and
 ExposedThing separately.

Signed-off-by: Zoltan Kis 
---
 index.html | 99 +++++++++++++++++++++++++++++-------------------------
 1 file changed, 54 insertions(+), 45 deletions(-)

diff --git a/index.html b/index.html
index 6deec5d7..56beefbb 100644
--- a/index.html
+++ b/index.html
@@ -378,7 +378,7 @@ 
        The ThingFilter dictionary
        
         
      
       
      
     
     
-
+<
     
     
     The fetch() method
    
       
    
         Accepts an url argument of type USVString that represents a URL (e.g. "file://..." or "https://...") and returns a Promise that resolves with a ThingDescription (a serialized JSON-LD document of type USVString).
@@ -425,10 +425,16 @@ 
    The ThingFilter dictionary
    
             Let model be the result of running the TD parsing algorithm with td as argument. If that throws an error, re-throw the error and terminate these steps.
           
    • 
           
  • 
-            Let instance be the result of running the Thing instantiation algorithm with model as argument.
+            If model does not have an own property that is defined in ThingFragment with a default value, add that property and value to model.
+          
    • 
+          
  • 
+            Create a ConsumedThing object thing initialized from model.
           
    • 
           
  • 
-            Create a ConsumedThing object thing initialized from instance.
+            Add the read() and write() methods to the ThingProperty elements so that they make requests to access the remote Things and wait for the reply, as defined by the Protocol Bindings.
+          
    • 
+          
  • 
+            Add the invoke() methods to the ThingAction elements so that they make requests to the remote Thing to invoke its actions, as defined by the Protocol Bindings.
           
    • 
           
  • 
             Return thing.
@@ -462,13 +468,36 @@ 
    The ThingFilter dictionary
    
             If model is not an object, throw TypeError and terminate these steps.
           
    • 
           
  • 
-            Let instance be the result of running the Thing instantiation algorithm with model passed as parameter.
+            If model does not have an own property that is defined in ThingFragment with a default value, add that property and value to model.
           
    • 
           
  • 
-            Create an ExposedThing object thing initialized from instance.
+            Create an ExposedThing object thing initialized from model.
+          
    • 
+          
  • 
+            For each ThingFragment property, initialize the property based on the provided initial or default values provided to the local WoT Runtime implementation, for instance initialize:
+            
      
+              
    1. 
+                 the id property to be the final unique identifier of the Thing,
+              
      2. 
+              
    2. 
+                the security object to represent the actual security scheme andits properties as set up by the implementation,
+              
      3. 
+              
    3. 
+                the properties property to be an array of ThingProperty objects in which the read() and write() methods are provided to define local methods to get and set the Property values,
+              
      4. 
+              
    4. 
+                the actions property to be an array of ThingAction objects in which the invoke() method is provided to define a local method to run the defined Actions,
+              
      5. 
+              
    5. 
+                the events property to be an array of ExposedEvent objects in which the emit() method is provided to define a local way to trigger sending notifications to all subscribed clients,
+              
      6. 
+              
    6. 
+                and initialize the other properties as initialized from model.
+              
      7. 
           
           
    7. 
             Return thing.
+          
      8. 
         
    
       
    
       
    
@@ -485,20 +514,6 @@ 
    The ThingFilter dictionary
    
           
    • 
         
       
    
-      
    
-        The Thing instantiation algorithm takes an object model as argument and runs the following steps:
-        
      
-          
    1. 
-            If model does not have an own property that is defined in ThingFragment with a default value, add that property and value to model.
-          
      2. 
-          
    2. 
-            Let instance be a ThingInstance object initialized with model properties.
-          
      3. 
-          
    3. 
-            Return instance.
-          
      4. 
-        
    
-      
    
     
     
 
     
     
    The register() method
    
@@ -565,13 +580,13 @@ 
    The ThingFilter dictionary
    
     
     
   
     
 
-  
    
-    
    The ThingInstance interface
    
+  
    
+    
    The ConsumedThing interface
    
     
    
-      Represents an object that extends a ThingFragment with methods for interactions (reading and writing Properties), invoking Actions, subscribe and unsubscribe for Property changes and Events.
+      Represents an object that extends a ThingFragment with methods for client interactions (send request for reading and writing Properties), invoke Actions, subscribe and unsubscribe for Property changes and Events.
     
    
     
    -      interface ThingInstance: ThingFragment {
+      interface ConsumedThing: ThingFragment {
         readonly attribute DOMString id;
         readonly attribute DOMString name;
         readonly attribute DOMString? base;
@@ -593,6 +608,7 @@ 
    The ThingInstance interface
    
       interface EventMap {
         maplike<DOMString, ThingEvent>;
       };
+      ConsumedThing implements Observable;  // for TD changes
     
    
     
    
       The id attribute represents the unique identifier of the Thing instance, typically a URI, IRI, or URN as USVString.
@@ -604,31 +620,15 @@ 
    The ThingInstance interface
    
       The base attribute represents the base URI that is valid for all defined local interaction resources.
     
    
     
    
-      The properties attribute represents a dictionary of ThingProperty items. The PropertyMap interface represents a maplike dictionary where all values are ThingProperty objects.
+      The properties attribute represents a dictionary of ThingProperty items. The PropertyMap interface represents a maplike dictionary where all values are ThingProperty objects. The read() and write() methods make a request to access the Properties on the remote Thing represented by this ConsumedThing proxy object.
     
    
     
    
-      The actions attribute represents a dictionary of ThingAction items. The ActionMap interface represents a maplike dictionary where all values are ThingAction objects.
+      The actions attribute represents a dictionary of ThingAction items. The ActionMap interface represents a maplike dictionary where all values are ThingAction objects. The invoke() method represents a request to invoke the Action on the remote Thing.
     
    
     
    
-      The events attribute represents a dictionary of ThingEvent items. The EventMap interface represents a maplike dictionary where all values are ThingEvent objects.
+      The events attribute represents a dictionary of ThingEvent items. The EventMap interface represents a maplike dictionary where all values are ThingEvent objects. Subscribing to the events involves setting up an observation (subscription) mechanism on the remote object.
     
    
-  
    
-
-  
    
 
-  
    
-    
    The ConsumedThing interface
    
-    
    
-      The ConsumedThing interface is a client API for sending requests to servers in order to retrieve or update Properties, invoke Actions, and observe Properties and Events.
-    
    
-    
    -      interface ConsumedThing: ThingInstance {
-      };
-      ConsumedThing implements Observable;  // for TD changes
-    
    
-    
    
-      ConsumedThing represents a local proxy object of the remote Thing.
-    
    
     
    
       
    Examples
    
       
    
@@ -666,9 +666,13 @@ 
    The ExposedThing interface
    
       The ExposedThing interface is the server API that allows defining request handlers, properties, Actions, and Events to a Thing. It also implements the Observable interface. An ExposedThing is created by the produce() method.
     
    
     
    -      interface ExposedThing: ThingInstance {
+      interface ExposedThing: ThingFragment {
+        readonly attribute PropertyMap properties;
+        readonly attribute ActionMap actions;
         readonly attribute ExposedEvents events;
-        // setter for ThingInstance properties
+        // getter for ThingFragment properties
+        getter any(DOMString name);
+        // setter for ThingFragment properties
         setter void(DOMString name, any value);
         // define how to expose and run the Thing
         Promise<void> expose();
@@ -692,9 +696,14 @@ 
    The ExposedThing interface
    
       callback PropertyReadHandler = Promise<any>();
       callback PropertyWriteHandler = Promise<void>(any value);
       callback ActionHandler = Promise<any>(any parameters);
-      ExposedThing implements Observable;
     
    
 
+    
    
+      The properties attribute represents a dictionary of ThingProperty items in which the read() and write() methods define local methods that access the physical representations of the Properties.
+    
    
+    
    
+      The actions attribute represents a dictionary of ThingAction items in which the invoke() method represents a local method to invoke the Action.
+    
    
     
    
       The events attribute represents a dictionary of ExposedEvent items that add the emit() method to the ThingEvent definition. The ExposedEvents interface represents a maplike dictionary where all values are ExposedEvent objects.
     
    

From c30ed7b4f2dac5941ee9b8a34e5ad58951abf4a3 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Mon, 3 Sep 2018 22:14:14 +0300
Subject: [PATCH 250/464] Add algorithms for expose() and destroy()

Signed-off-by: Zoltan Kis 
---
 index.html | 42 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/index.html b/index.html
index 56beefbb..82b43cb7 100644
--- a/index.html
+++ b/index.html
@@ -399,7 +399,7 @@ 
    The ThingFilter dictionary
    
             Make a request to fetch the content of url as described by the Protocol Bindings and wait for the reply. Let td be the returned content.
           
           
  • 
-            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 terminate these steps.
+            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 terminate these steps.
           
    • 
           
  • 
             Otherwise resolve promise with td and terminate these steps.
@@ -712,12 +712,52 @@ 
    The ExposedThing interface
    
       
    
         Start serving external requests for the Thing, so that WoT interactions using Properties, Actions and Events will be possible.
       
    
+      
    
+        The expose() method MUST run the following steps:
+        
      
+          
    1. 
+            Return a Promise promise and execute the next steps in parallel.
+          
      2. 
+          
    2. 
+            If invoking expose() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
+          
      3. 
+          
    3. 
+            Make a request to the underlying platform to create and configure serving external requests for WoT interactions, based on the Protocol Bindings.
+          
      4. 
+          
    4. 
+            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 terminate these steps.
+          
      5. 
+          
    5. 
+            Otherwise resolve promise with td and terminate these steps.
+          
      6. 
+        
    
+      
    
     
    • 
 
     
     
    The destroy() method
    
       
    
         Stop serving external requests for the Thing and destroy the object. Note that eventual unregistering should be done before invoking this method.
       
    
+      
    
+        The destroy() method MUST run the following steps:
+        
      
+          
    1. 
+            Return a Promise promise and execute the next steps in parallel.
+          
      2. 
+          
    2. 
+            If invoking destroy() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
+          
      3. 
+          
    3. 
+            Make a request to the underlying platform to stop serving external requests for WoT interactions, based on the Protocol Bindings.
+          
      4. 
+          
    4. 
+            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 terminate these steps.
+          
      5. 
+          
    5. 
+            Otherwise resolve promise with td and terminate these steps.
+          
      6. 
+        
    
+      
    
     
    
 
     
     
    The addProperty() method
    

From 288ea2c9426a95b48fb049de6eab82b5439bad30 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Tue, 4 Sep 2018 18:03:43 +0300
Subject: [PATCH 251/464] Fix #141, review comments

Signed-off-by: Zoltan Kis 
---
 index.html | 25 ++++++++-----------------
 1 file changed, 8 insertions(+), 17 deletions(-)

diff --git a/index.html b/index.html
index 82b43cb7..540467b5 100644
--- a/index.html
+++ b/index.html
@@ -480,7 +480,7 @@ 
    The ThingFilter dictionary
    
                  the id property to be the final unique identifier of the Thing,
               
               
  • 
-                the security object to represent the actual security scheme andits properties as set up by the implementation,
+                the security object to represent the actual security scheme and its properties as set up by the implementation,
               
    • 
               
  • 
                 the properties property to be an array of ThingProperty objects in which the read() and write() methods are provided to define local methods to get and set the Property values,
@@ -674,7 +674,7 @@ 
    The ExposedThing interface
    
         getter any(DOMString name);
         // setter for ThingFragment properties
         setter void(DOMString name, any value);
-        // define how to expose and run the Thing
+        // methods to expose and destroy the Thing
         Promise<void> expose();
         Promise<void> destroy();
         // define Properties
@@ -1233,7 +1233,7 @@ 
    The ThingProperty interface
    
         The read() method will fetch the value of the Property. Returns a Promise that resolves with the value, or rejects with an error.
       
    
       
    
-        The write() method will attempt to set the value of the Propertyspecified in the value argument whose type SHOULD match the o9ne specified by the type property. Returns a Promise that resolves on success, or rejects on an error.
+        The write() method will attempt to set the value of the Propertyspecified in the value argument whose type SHOULD match the one specified by the type property. Returns a Promise that resolves on success, or rejects on an error.
       
    
     
    • 
 
@@ -1330,15 +1330,6 @@ 
    The ThingAction interface
    
         
    
       
    
 
-      
-
       
    The DataSchema dictionary
    
         
               dictionary DataSchema {
@@ -1531,13 +1522,13 @@ 
    The ThingAction interface
    
             Otherwise, if valueType.type is "array", execute the following sub-steps:
             
      
               
    1. 
-                If valueType.minItems is defined, and value is not an array that contains at least valueType.minItems elements, return false.
+                If value is not an array, return false.
               
      2. 
               
    2. 
-                If valueType.maxItems is defined, and value is not an array that contains at maximum valueType.maxItems elements, return false.
+                If valueType.minItems is defined, and value does not contain at least valueType.minItems elements, return false.
               
      3. 
               
    3. 
-                Otherwise, if value is not an array, return false.
+                If valueType.maxItems is defined, and value contains more than valueType.maxItems elements, return false.
               
      4. 
               
    4. 
                 Otherwise, if valueType.items is undefined, return false.
@@ -1557,10 +1548,10 @@ 
      The ThingAction interface
      
             Otherwise, if type is "object", execute the following sub-steps:
             
        
               
      1. 
-                If value is not an Object or null, return false.
+                If value is not an Object, return false.
               
        2. 
               
      2. 
-                If valueType.properties is not defined or is not null or it is not an object, return false.
+                If valueType.properties is not defined, return false.
               
        3. 
               
      3. 
                 If valueType.properties is null, return true (i.e. accept any object value).

From d991daf488a2375a62d8f215752973cb811d4909 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Tue, 4 Sep 2018 18:34:01 +0300
Subject: [PATCH 252/464] Fix #139. Replace security dictionary definitions
 with link to the TD spec.

Signed-off-by: Zoltan Kis 
---
 index.html | 193 +++++++----------------------------------------------
 1 file changed, 23 insertions(+), 170 deletions(-)

diff --git a/index.html b/index.html
index 540467b5..b35b6a83 100644
--- a/index.html
+++ b/index.html
@@ -1076,7 +1076,7 @@ 
        The ThingFragment dictionary
        
           The support optional attribute of type DOMString represents human readable information about the TD maintainer.
         
        4. 
         
      4. 
-          The security optional attribute represents security metadata defined by the SecurityScheme dictionary;
+          The security optional attribute represents security metadata defined by a dictionary object whose properties are defined in the Thing Description specification;
         
        5. 
         
      5. 
           The properties optional attribute represents a dictionary with keys that correspond to Property names and values of type PropertyFragment.
@@ -1651,175 +1651,28 @@ 
        The Observable interface
        
     
        
      Please see the WoT Security and Privacy repository for work in progress regarding threat models, assets, risks, recommended mitigations, and best practices for security and privacy for systems using the Web of Things. Once complete, security and privacy considerations relevant to the Scripting API will be summarized in this section.
     
        
-
-    
        The SecuritySchemeType enumeration type
        
-      
        -        enum SecuritySchemeType { "basic", "digest", "bearer", "pop", "oauth2", "apikey" };
-      
        
-      
        
-        Defines the supported security schemes, i.e. "basic", "digest", "bearer", "pop", "oauth2" and "apikey".
-      
        
-    
        
-
-    
        The AuthenticationType enumeration type
        
-      
        -        enum AuthenticationType { "header", "body", "query", "cookie" };
-      
        
-      
        
-        Defines the  location of the authentication information, i.e. "header", "body", "query" and "cookie".
-      
        
-    
        
-
-    
        
-      
         The SecurityScheme dictionary
        
-      
        
-        Represents the base class for security related configuration. One of the subclasses (differentiated by scheme) SHOULD be used.
-      
        
-      
        -        dictionary SecurityScheme {
-          required SecuritySchemeType scheme;
-          DOMString? description;
-          USVString? proxyURI;
-        };
-      
        
-      
        
-        The scheme property represents the identification of the security scheme to be used for the Thing.
-      
        
-      
        
-        The description property provides human readable information about the security scheme.
-      
        
-      
        
-        The proxyURI property represents the URI of the proxy server to which the security configuration containing the scheme provides access. If not provided, it means that the  security configuration refers directly to the endpoint.
-      
        
-    
        
-
-    
        
-      
         The BasicSecurityScheme dictionary
        
-      
        -        dictionary BasicSecurityScheme: SecurityScheme {
-          DOMString scheme = "basic";
-          DOMString in;
-          DOMString pname;
-        };
-      
        
-      
        
-        The scheme property represents the identification of the security scheme to be used for the Thing.
-      
        
-      
        
-        The in property of type AuthenticationType represents represents the location of the authentication information.
-      
        
-      
        
-        The pname property represents the authentication parameter name.
-      
        
-    
        
-
-    
        
-      
         The DigestSecurityScheme dictionary
        
-      
        -        dictionary DigestSecurityScheme: BasicSecurityScheme {
-          DOMString scheme = "digest";
-          DOMString qop = "auth";
-        };
-      
        
-      
        
-        The scheme property represents the identification of the security scheme and MUST be "digest".
-      
        
-      
        
-        The qop property represents the quality of protection. The default value is "auth". The other accepted value is "auth-int".
-      
        
-    
        
-
-    
        
-      
         The BearerSecurityScheme dictionary
        
-      
        -        dictionary BearerSecurityScheme: BasicSecurityScheme {
-          DOMString scheme = "bearer";
-          USVString authorizationURL;
-          DOMString alg = "ES256";
-          DOMString format = "jwt";
-        };
-      
        
-      
        
-        The scheme property represents the identification of the security scheme and MUST be "bearer".
-      
        
-      
        
-        The authorizationURL property represents the authorization server URL.
-      
        
-      
        
-        The alg property represents the encoding, encryption or digest algorithm. Accepted values include "MD5", "ES256", "ES512-256". The default value is "ES256".
-      
        
-      
        
-        The format property represents the format of the authentication information. Accepted values are "jwt" (the default value), "jwe" and "jws".
-      
        
-    
        
-
-    
        
-      
         The PopSecurityScheme dictionary
        
-      
        
-        Represents the proof-of-possession token authentication security configuration.
-      
        
-      
        -        dictionary PopSecurityScheme: DigestSecurityScheme {
-          DOMString scheme = "pop";
-        };
-      
        
-      
        
-        The scheme property represents the identification of the security scheme and MUST be "pop".
-      
        
-    
        
-
-    
        
-      
         The ApikeySecurityScheme dictionary
        
-      
        
-        Represents the API key authentication security configuration, where the access token is opaque and is not using a standard token format.
-      
        
-      
        -        dictionary ApikeySecurityScheme: BasicSecurityScheme {
-          DOMString scheme = "apikey";
-        };
-      
        
-      
        
-        The scheme property represents the identification of the security scheme and MUST be "apikey".
-      
        
-    
        
-
-    
        
-      
         The OAuth2SecurityScheme dictionary
        
-      
        
-        Represents the OAuth2 authentication security configuration.
-      
        
-      
        -        dictionary OAuth2SecurityScheme: SecurityScheme {
-          DOMString scheme = "oauth2";
-          USVString tokenURL;
-          USVString authorizationURL;
-          USVString refreshURL;
-          sequence<DOMString> scopes;
-          DOMString flow = "implicit";
-        };
-      
        
-      
        
-        The scheme property represents the identification of the security scheme and MUST be "oauth2".
-      
        
-      
        
-        The tokenURL property represents the URL of the token server.
-      
        
-      
        
-        The authorizationURL property represents the URL of the authorization server.
-      
        
-      
        
-        The refreshURL property represents the URL of the refresh server.
-      
        
-      
        
-        The scopes property represents the authorization scope identifiers as an array of strings.
-      
        
-      
        
-        The flow property represents the authorization flow of type. Accepted values are: "implicit" (the default value), "password", "client", or "code".
-      
        
-      
        
-         For the "implicit" flow the authorizationURL and scopes properties are required. For the "password" and "client" flows the tokenURL and scopes properties are required. For the "code" flow the authorizationURL, tokenURL and scopes properties are required.
-      
        
-    
        
+    
        
+      In general, implementations SHOULD consider the following guidelines:
+      
          
+        
        1. 
+          Perform isolation of script instances (where applicable).
+        
          2. 
+        
        2. 
+          Perform security validation on all script inputs, including fuzzing.
+        
          3. 
+      
        
+    
        
+    
        
+      Script developers SHOULD consider the following guidelines:
+      
          
+        
        1. 
+          Minimize scripts functionality and complexity.
+        
          2. 
+        
        2. 
+          Avoid heavy functional processing in scripts without authentication.
+        
          3. 
+      
        
+    
        
   
    
 
   
     
    Terminology and conventions
    

From 2dc62086876f8828cf44de1f7737169b447a80ba Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Tue, 4 Sep 2018 20:57:26 +0300
Subject: [PATCH 253/464] Replace DataSchema section with link to the TD spec.
 Fix SecurityScheme.

Signed-off-by: Zoltan Kis 
---
 index.html | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/index.html b/index.html
index b35b6a83..ee26121b 100644
--- a/index.html
+++ b/index.html
@@ -480,7 +480,7 @@ 
    The ThingFilter dictionary
    
                  the id property to be the final unique identifier of the Thing,
               
               
  • 
-                the security object to represent the actual security scheme and its properties as set up by the implementation,
+                the security object of type SecurityScheme to represent the actual security scheme and its properties as set up by the implementation,
               
    • 
               
  • 
                 the properties property to be an array of ThingProperty objects in which the read() and write() methods are provided to define local methods to get and set the Property values,
@@ -1076,7 +1076,7 @@ 
    The ThingFragment dictionary
    
           The support optional attribute of type DOMString represents human readable information about the TD maintainer.
         
    • 
         
  • 
-          The security optional attribute represents security metadata defined by a dictionary object whose properties are defined in the Thing Description specification;
+          The security optional attribute represents security metadata defined by a dictionary object of type SecurityScheme;
         
    • 
         
  • 
           The properties optional attribute represents a dictionary with keys that correspond to Property names and values of type PropertyFragment.
@@ -1100,9 +1100,6 @@ 
    The ThingFragment dictionary
    
           Apart from the core properties defined above, others may also be defined on a Thing, for instance "@id", "gms:COVParams" (with namespace definition), or "iotschema:unit" etc.
         
    • 
       
-      
    
-        Support for configuration and security metadata will be added later.
-      
    
     
     
 
     
    
@@ -1215,7 +1212,7 @@ 
    The ThingProperty interface
    
         The ThingProperty interface contains all the properties defined on PropertyFragment as read-only properties.
       
    
       
    
-        The type read-only property represents the type definition for the Property. If it matches a DataType, then it MUST implement the corresponding DataSchema dictionary.
+        The type read-only property represents the type definition for the Property as a DataSchema dictionary object.
       
    
       
    
         The writable read-only property tells whether the Property value can be updated. If it is false, then the set(value) method SHOULD always reject.
@@ -1312,15 +1309,15 @@ 
    The ThingAction interface
    
         };

    - The security property represents the security requirements for the linked resource. + The security object property of type SecurityScheme represents the security requirements for the linked resource.

    Value types

    - Value types are used in Property, Event and Action parameter definitions in a ThingFragment. Basically correspond to a JSON object definition. + Value types are used in Property, Event and Action parameter definitions in a ThingFragment, and basically correspond to a JSON object definition. Value types are represented as DataSchema dictionary objects whose properties and possible sub-classes are defined in the Thing Description specification. One property of all DataSchema dictionaries is the type property whose value is from a set of enumerated strings that is referred in this specification as DataType.

    - +

    The value-matching algorithm

    @@ -1673,6 +1671,9 @@

    The Observable interface

    +

    + Security metadata is represented as dictionary objects of type SecurityScheme whose properties and sub-classes are defined in the Thing Description specification. +

    Terminology and conventions

    From 4250998e3c08d5d5469fc5bef7f65888e80c8af3 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 5 Sep 2018 17:48:13 +0300 Subject: [PATCH 254/464] Editorial changes for fixing review comments Signed-off-by: Zoltan Kis --- index.html | 40 ++++++++++++++++------------------------ 1 file changed, 16 insertions(+), 24 deletions(-) diff --git a/index.html b/index.html index ee26121b..5edcf5d5 100644 --- a/index.html +++ b/index.html @@ -378,7 +378,7 @@

    The ThingFilter dictionary

    -< +

    The fetch() method

    Accepts an url argument of type USVString that represents a URL (e.g. "file://..." or "https://...") and returns a Promise that resolves with a ThingDescription (a serialized JSON-LD document of type USVString). @@ -396,7 +396,7 @@

    The ThingFilter dictionary

    If the argument url is not a URL, reject promise with TypeError and terminate these steps.
  • - Make a request to fetch the content of url as described by the Protocol Bindings and wait for the reply. Let td be the returned content. + Make a request to fetch the content of url as described by the Protocol Bindings and wait for the reply. Implementations encapsulate the fetching process and the accepted media types (such as application/td+json), as far as a valid Thing Description can be obtained as defined in [[!WOT-TD]]. Let td be the Thing Description string-serialized from the returned content, as specified in the Thing Description serialization.
  • 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 terminate these steps. @@ -415,27 +415,27 @@

    The ThingFilter dictionary

    The consume(td) method must run the following steps:

      -
    1. - If invoking fetch() is not allowed for the current scripting context for security reasons, throw a SecurityError and terminate these steps. -
    2. If the argument td is not a string, throw a TypeError and terminate these steps.
    3. - Let model be the result of running the TD parsing algorithm with td as argument. If that throws an error, re-throw the error and terminate these steps. + Let stub be the result of running the TD parsing algorithm with td as argument. If that throws an error, re-throw the error and terminate these steps.
    4. - If model does not have an own property that is defined in ThingFragment with a default value, add that property and value to model. + If stub does not have an own property that is defined in ThingFragment with a default value, add that property and value to stub.
    5. - Create a ConsumedThing object thing initialized from model. + Create a ConsumedThing object thing initialized from stub that implements Observable.
    6. - Add the read() and write() methods to the ThingProperty elements so that they make requests to access the remote Things and wait for the reply, as defined by the Protocol Bindings. + Add the read() and write() methods to the ThingProperty elements so that they make requests to access the remote Things and wait for the reply, as defined by the Protocol Bindings. Also, all ThingProperty elements SHOULD implement Observable, i.e. define a subscribe() method that should make request to observe the given Properties as defined by the Protocol Bindings.
    7. Add the invoke() methods to the ThingAction elements so that they make requests to the remote Thing to invoke its actions, as defined by the Protocol Bindings.
      8. +
    8. + Add the subscribe() method to all ThingEvent elements so that they make requests to subscribe to the events defined by the remote Thing, as defined by the Protocol Bindings. +
    9. Return thing.
      10. @@ -445,18 +445,10 @@

      The ThingFilter dictionary

      The produce() method

      - Accepts a model argument of type ThingModel and returns an ExposedThing object. An ExposedThing can be created in the following ways: -

        -
      1. - from a ThingFragment, then adding Properties, Actions, Events and request handlers; -
        2. -
      2. - from a Thing Description, then adding request handlers. -
        3. -
      + Accepts a model argument of type ThingModel and returns an ExposedThing object.

      - The produce(url) method MUST run the following steps: + The produce(model) method MUST run the following steps:

      1. If invoking produce() is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps. @@ -474,7 +466,7 @@

        The ThingFilter dictionary

        Create an ExposedThing object thing initialized from model.
      2. - For each ThingFragment property, initialize the property based on the provided initial or default values provided to the local WoT Runtime implementation, for instance initialize: + For each property of ExposedThing defined in ThingFragment, initialize the property based on the provided initial or default values provided to the local WoT Runtime implementation, for instance initialize:
        1. the id property to be the final unique identifier of the Thing, @@ -483,13 +475,13 @@

          The ThingFilter dictionary

          the security object of type SecurityScheme to represent the actual security scheme and its properties as set up by the implementation,
        2. - the properties property to be an array of ThingProperty objects in which the read() and write() methods are provided to define local methods to get and set the Property values, + the properties property to be an object with all properties being ThingProperty objects in which the read() and write() methods are provided to define local methods to get and set the Property values,
        3. - the actions property to be an array of ThingAction objects in which the invoke() method is provided to define a local method to run the defined Actions, + the actions property to be an object with all properties being ThingAction objects in which the invoke() method is provided to define a local method to run the defined Actions,
        4. - the events property to be an array of ExposedEvent objects in which the emit() method is provided to define a local way to trigger sending notifications to all subscribed clients, + the events property to be an object with all properties being ExposedEvent objects in which the emit() method is provided to define a local way to trigger sending notifications to all subscribed clients,
        5. and initialize the other properties as initialized from model. @@ -722,7 +714,7 @@

          The ExposedThing interface

          If invoking expose() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
        6. - Make a request to the underlying platform to create and configure serving external requests for WoT interactions, based on the Protocol Bindings. + Make a request to the underlying platform to attach protocol handlers and start serving external requests for WoT interactions (read, write and observe Properties, invoke Actions and manage Event subscriptions), based on the Protocol Bindings.
        7. 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 terminate these steps. From 2ea50e981cfe86db4966e2f3468ed0dd9daca745 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 5 Sep 2018 21:35:28 +0300 Subject: [PATCH 255/464] Fix #143, #142: replace local dictionary definitions with references to the TD spec Signed-off-by: Zoltan Kis --- index.html | 363 +++++++++++------------------------------------------ 1 file changed, 73 insertions(+), 290 deletions(-) diff --git a/index.html b/index.html index 5edcf5d5..29d26bf9 100644 --- a/index.html +++ b/index.html @@ -128,7 +128,7 @@ Exposing a Thing requires defining a Thing Description (TD) and instantiating a software stack to serve requests for accessing the exposed Properties, Actions and Events. This specification describes how to expose and consume Things by a script.

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

          This specification does not make assumptions on how the WoT Runtime handles and runs scripts, including single or multiple tenancy, script deployment and lifecycle management. The API already supports the generic mechanisms that make it possible to implement script management, for instance by exposing a manager Thing whose Actions (action handlers) implement script lifecycle management operations. @@ -234,6 +234,13 @@

          The WoT object

          Promise<void> unregister(USVString directory, ExposedThing thing); }; typedef object ThingFragment; + typedef object PropertyFragment; + typedef object ActionFragment; + typedef object EventFragment; + typedef object DataSchema; + typedef object SecurityScheme; + typedef object Link; + typedef object Form; typedef USVString ThingDescription; typedef (ThingFragment or ThingDescription) ThingModel; @@ -702,7 +709,7 @@

          The ExposedThing interface

          The expose() method

          - Start serving external requests for the Thing, so that WoT interactions using Properties, Actions and Events will be possible. + Start serving external requests for the Thing, so that WoT Interactions using Properties, Actions and Events will be possible.

          The expose() method MUST run the following steps: @@ -714,7 +721,7 @@

          The ExposedThing interface

          If invoking expose() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
        8. - Make a request to the underlying platform to attach protocol handlers and start serving external requests for WoT interactions (read, write and observe Properties, invoke Actions and manage Event subscriptions), based on the Protocol Bindings. + Make a request to the underlying platform to attach protocol handlers and start serving external requests for WoT Interactions (read, write and observe Properties, invoke Actions and manage Event subscriptions), based on the Protocol Bindings.
        9. 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 terminate these steps. @@ -740,7 +747,7 @@

          The ExposedThing interface

          If invoking destroy() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
        10. - Make a request to the underlying platform to stop serving external requests for WoT interactions, based on the Protocol Bindings. + Make a request to the underlying platform to stop serving external requests for WoT Interactions, based on the Protocol Bindings.
        11. 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 terminate these steps. @@ -1033,133 +1040,104 @@

          Examples

    • -
    -

    Data types used in a Thing

    +
    +

    Data types and structures

    - Every Thing describes its metadata as defined in ThingFragment, and basic interactions defined as Properties, Actions and Events. The following data types are used for representing these interactions, as defined in [[!WOT-TD]]. + The [[!WOT-TD]] specification defines the WoT information model, i.e. the data types and data structures used in WoT Interactions. In this API these definitions translate to dictionary objects that are extended with methods by the interfaces defined in this specification.

    - -
    -

    The ThingDescription type

    +

    + In order to avoid duplication of definitions, references to these data types and structures is defined in this section, but for their full description please refer to the Thing Description specification. +

    +
    +

    The DataSchema dictionary and its subclasses

    - Serialized representation of the Thing Description (a JSON-LD document). + Value types basically represent types that may be used in JSON object definitions and are used in ThingFragment to define Properties, Events and Action parameters. Value types are represented as dictionary objects whose properties and possible sub-classes are defined in the DataSchema section of [[!WOT-TD]].

    -

    - In this version of the API, Thing Descriptions are represented as an opaque USVString that can be transmitted between devices. +

    + One property of all DataSchema dictionary is the type property whose value is from a set of enumerated strings defined in the DataSchema section of [[!WOT-TD]] and is referred as DataType in this specification. +

    +

    + Based on type, the following sub-classes of DataSchema are defined in [[!WOT-TD]]: BooleanSchema, NumberSchema, IntegerSchema, StringSchema, ObjectSchema, ArraySchema.

    -
    -

    The ThingFragment dictionary

    +
    +

    The SecurityScheme dictionary and its subclasses

    - ThingFragment is a dictionary that contains properties representing semantic metadata and interactions (Properties, Actions and Events). It is used for initializing an internal representation of a Thing Description as defined in [[!WOT-TD]], and it is also used in ThingFilter. The set of core properties is defined below. In addition, ThingFragment may contain other properties as well as defined in the Thing Description from which the Thing object is created. + Security metadata is represented as dictionary objects whose properties and sub-classes are defined in the SecurityScheme section of [[!WOT-TD]].

    -
      -
    • - The id optional attribute represents an application provided hint for the unique identifier of the Thing, typically a URI, IRI, or URN as USVString. The WoT Runtime might override this with a different value when exposing the Thing. -
      • -
    • - The name attribute represents the name of the Thing as DOMString. In the Thing Description this attribute is mandatory, but in ThingFilter it is optional. -
      • -
    • - The description optional attribute of type DOMString represents a human readable description of the Thing. -
      • -
    • - The support optional attribute of type DOMString represents human readable information about the TD maintainer. -
      • -
    • - The security optional attribute represents security metadata defined by a dictionary object of type SecurityScheme; -
      • -
    • - The properties optional attribute represents a dictionary with keys that correspond to Property names and values of type PropertyFragment. -
      • -
    • - The actions optional attribute represents a dictionary with keys that correspond to Action names and values of type ActionFragment. -
      • -
    • - The events optional attribute represents a dictionary with keys that correspond to Event names and values of type EventFragment. -
      • -
    • - The links optional attribute represents an array of WebLink objects. -
      • -
    • - The @context optional attribute represents a semantic context as USVString. -
      • -
    • - The @type optional attribute represents a semantic type as USVString. -
      • -
    • - Apart from the core properties defined above, others may also be defined on a Thing, for instance "@id", "gms:COVParams" (with namespace definition), or "iotschema:unit" etc. -
      • -
    -
    +

    + One property of the SecurityScheme dictionary is the scheme property whose value is from a set of enumerated strings defined in the SecurityScheme section of [[!WOT-TD]]. Based on type, multiple subclasses of SecurityScheme are defined. +

    -
    -

    The InteractionFragment dictionary

    +
    +

    The Link dictionary

    + Represents a Web Link with properties defined in the Link section of [[!WOT-TD]].

    - 
    -        dictionary InteractionFragment {
-          DOMString? label;
-          DOMString? description;
-        };
-
    +
    + +
    +

    The Form dictionary

    - The label property initializes the text label for the interaction. + Represents metadata describing service details, with properties defined in the Form section of [[!WOT-TD]].

    +
    + +
    +

    The InteractionFragment dictionary

    - The description property initializes the description for the interaction. + Represents the common properties of WoT Interactions, one of Property, Action or Event, as defined in the InteractionPattern section of [[!WOT-TD]]. Its subclasses are referred as PropertyFragment, ActionFragment and EventFragment.

    The PropertyFragment dictionary

    - Defines the standardized part of the dictionary that initializes a ThingProperty object. -

    - 
    -          dictionary PropertyFragment: InteractionFragment {
-            boolean writable = false;
-            boolean observable = false;
-          };
-          PropertyFragment implements DataSchema;
-
    -

    - The writable property initializes access to the Property value. The default value is false. -

    -

    - The observable property initializes observability access to the Property. The default value is false. + Represents the Property interaction data that initializes a ThingProperty object. Its properties are defined in the Property and InteractionPattern sections of [[!WOT-TD]].

    The ActionFragment dictionary

    - 
    -        dictionary ActionFragment: InteractionFragment {
-          DataSchema? input;
-          DataSchema? output;
-        };
-
    -

    - The input property initializes the input of type DataSchema to the ThingAction. Multiple arguments can be provided by applications as an array or as an object. -

    - The output property initializes the output of type DataSchema of the ThingAction. + Represents the Action interaction data that initializes a ThingAction object. Its properties are defined in the Action and InteractionPattern sections of [[!WOT-TD]].

    The EventFragment dictionary

    - Event data is represented as a Property. + Represents the Event interaction data that initializes a ThingEvent object. Its properties are defined in the Event section of [[!WOT-TD]].

    - 
    -        typedef PropertyFragment EventFragment;
-
    +
    + +
    +

    The ThingFragment dictionary

    +

    + The ThingFragment dictionary is defined as Thing in [[!WOT-TD]]. It is a dictionary that contains properties representing semantic metadata and interactions (Properties, Actions and Events). It is used for initializing an internal representation of a Thing Description and its properties may be used in ThingFilter. +

    +
    + +
    +

    The ThingDescription type

    - The value an event is carrying is initialized as a Property value. + Serialized representation of the Thing Description (a JSON-LD document). +

    +

    + In this version of the API, Thing Descriptions are represented as an opaque USVString that can be transmitted between devices.

    +
    + +
    +

    Interfaces for WoT Interactions

    +

    + The data types and structures imported from [[!WOT-TD]] are extended by this specification in order to provide the interfaces for WoT Interactions. +

    +

    + Every Thing describes its metadata as defined in ThingFragment, and basic interactions defined as Properties, Actions and Events. The following interfaces are used for representing these interactions. +

    The Interaction interface

    @@ -1172,7 +1150,7 @@

    The Interaction interface

             interface Interaction {
-          readonly attribute FrozenArray<Form> forms;
+          readonly attribute (Form or FrozenArray<Form>) forms;
         };
         Interaction implements InteractionFragment;
    @@ -1264,198 +1242,6 @@

    The ThingAction interface

    -

    The Link dictionary

    - 
    -        dictionary Link {
-          required USVString href;
-          USVString mediaType;
-          DOMString rel;
-        };
-
    -

    - The href property is a hypertext reference that defines the Link. -

    -

    - The mediaType property represents the IANA media type associated with the Link. -

    -

    - The rel property represents a semantic label that specifies how to interact with the linked resource. -

    -
    - -

    The WebLink dictionary

    - 
    -        dictionary WebLink: Link {
-          USVString anchor;
-        };
-
    -

    - The anchor property represents a URI that overrides the default context of a Link. -

    -
    - -

    The Form dictionary

    - 
    -        dictionary Form: Link {
-          SecurityScheme security;
-        };
-
    -

    - The security object property of type SecurityScheme represents the security requirements for the linked resource. -

    -
    - -

    Value types

    -

    - Value types are used in Property, Event and Action parameter definitions in a ThingFragment, and basically correspond to a JSON object definition. Value types are represented as DataSchema dictionary objects whose properties and possible sub-classes are defined in the Thing Description specification. One property of all DataSchema dictionaries is the type property whose value is from a set of enumerated strings that is referred in this specification as DataType. -

    - -
    -

    The value-matching algorithm

    The value-matching algorithm is applied to a value input in relation to a valueType property of type DataSchema, for instance the value and type properties of a PropertyFragment object, or the inputValue parameter to the invoke() method of a ThingAction object in relation to the same object. It executes the following steps: @@ -1663,9 +1449,6 @@

    The Observable interface

    -

    - Security metadata is represented as dictionary objects of type SecurityScheme whose properties and sub-classes are defined in the Thing Description specification. -

    Terminology and conventions

    From f31c297dd17c6e880f2828ca887e1449cc81c86e Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Fri, 7 Sep 2018 15:49:56 +0300 Subject: [PATCH 256/464] Editorial: change TD references to use data-cite Signed-off-by: Zoltan Kis --- index.html | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/index.html b/index.html index 29d26bf9..46c950ae 100644 --- a/index.html +++ b/index.html @@ -403,7 +403,7 @@

    The ThingFilter dictionary

    If the argument url is not a URL, reject promise with TypeError and terminate these steps.
  • - Make a request to fetch the content of url as described by the Protocol Bindings and wait for the reply. Implementations encapsulate the fetching process and the accepted media types (such as application/td+json), as far as a valid Thing Description can be obtained as defined in [[!WOT-TD]]. Let td be the Thing Description string-serialized from the returned content, as specified in the Thing Description serialization. + Make a request to fetch the content of url as described by the Protocol Bindings and wait for the reply. Implementations encapsulate the fetching process and the accepted media types (such as application/td+json), as far as a valid Thing Description can be obtained as defined in [[!WOT-TD]]. Let td be the Thing Description string-serialized from the returned content, as specified in the Thing Description serialization.
  • 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 terminate these steps. @@ -503,7 +503,7 @@

    The ThingFilter dictionary

    The TD parsing algorithm takes a string td as argument and runs the following steps:
    1. - Parse td according to the WoT Thing Description in order to produce a JSON object json. Update thing with the properties and values defined in json. + Parse td according to the WoT Thing Description in order to produce a JSON object json. Update thing with the properties and values defined in json.
    2. If there was an error during the parsing, throw that error and terminate these steps. @@ -1043,7 +1043,7 @@

      Examples

      Data types and structures

      - The [[!WOT-TD]] specification defines the WoT information model, i.e. the data types and data structures used in WoT Interactions. In this API these definitions translate to dictionary objects that are extended with methods by the interfaces defined in this specification. + The [[!WOT-TD]] specification defines the WoT information model, i.e. the data types and data structures used in WoT Interactions. In this API these definitions translate to dictionary objects that are extended with methods by the interfaces defined in this specification.

      In order to avoid duplication of definitions, references to these data types and structures is defined in this section, but for their full description please refer to the Thing Description specification. @@ -1051,71 +1051,71 @@

      Data types and structures

      The DataSchema dictionary and its subclasses

      - Value types basically represent types that may be used in JSON object definitions and are used in ThingFragment to define Properties, Events and Action parameters. Value types are represented as dictionary objects whose properties and possible sub-classes are defined in the DataSchema section of [[!WOT-TD]]. + Value types basically represent types that may be used in JSON object definitions and are used in ThingFragment to define Properties, Events and Action parameters. Value types are represented as dictionary objects whose properties and possible sub-classes are defined in the DataSchema section of [[!WOT-TD]].

      - One property of all DataSchema dictionary is the type property whose value is from a set of enumerated strings defined in the DataSchema section of [[!WOT-TD]] and is referred as DataType in this specification. + One property of all DataSchema dictionary is the type property whose value is from a set of enumerated strings defined in the DataSchema section of [[!WOT-TD]] and is referred as DataType in this specification.

      - Based on type, the following sub-classes of DataSchema are defined in [[!WOT-TD]]: BooleanSchema, NumberSchema, IntegerSchema, StringSchema, ObjectSchema, ArraySchema. + Based on type, the following sub-classes of DataSchema are defined in [[!WOT-TD]]: BooleanSchema, NumberSchema, IntegerSchema, StringSchema, ObjectSchema, ArraySchema.

      The SecurityScheme dictionary and its subclasses

      - Security metadata is represented as dictionary objects whose properties and sub-classes are defined in the SecurityScheme section of [[!WOT-TD]]. + Security metadata is represented as dictionary objects whose properties and sub-classes are defined in the SecurityScheme section of [[!WOT-TD]].

      - One property of the SecurityScheme dictionary is the scheme property whose value is from a set of enumerated strings defined in the SecurityScheme section of [[!WOT-TD]]. Based on type, multiple subclasses of SecurityScheme are defined. + One property of the SecurityScheme dictionary is the scheme property whose value is from a set of enumerated strings defined in the SecurityScheme section of [[!WOT-TD]]. Based on type, multiple subclasses of SecurityScheme are defined.

      The Link dictionary

      - Represents a Web Link with properties defined in the Link section of [[!WOT-TD]]. + Represents a Web Link with properties defined in the Link section of [[!WOT-TD]].

      The Form dictionary

      - Represents metadata describing service details, with properties defined in the Form section of [[!WOT-TD]]. + Represents metadata describing service details, with properties defined in the Form section of [[!WOT-TD]].

      The InteractionFragment dictionary

      - Represents the common properties of WoT Interactions, one of Property, Action or Event, as defined in the InteractionPattern section of [[!WOT-TD]]. Its subclasses are referred as PropertyFragment, ActionFragment and EventFragment. + Represents the common properties of WoT Interactions, one of Property, Action or Event, as defined in the InteractionPattern section of [[!WOT-TD]]. Its subclasses are referred as PropertyFragment, ActionFragment and EventFragment.

      The PropertyFragment dictionary

      - Represents the Property interaction data that initializes a ThingProperty object. Its properties are defined in the Property and InteractionPattern sections of [[!WOT-TD]]. + Represents the Property interaction data that initializes a ThingProperty object. Its properties are defined in the Property and InteractionPattern sections of [[!WOT-TD]].

      The ActionFragment dictionary

      - Represents the Action interaction data that initializes a ThingAction object. Its properties are defined in the Action and InteractionPattern sections of [[!WOT-TD]]. + Represents the Action interaction data that initializes a ThingAction object. Its properties are defined in the Action and InteractionPattern sections of [[!WOT-TD]].

      The EventFragment dictionary

      - Represents the Event interaction data that initializes a ThingEvent object. Its properties are defined in the Event section of [[!WOT-TD]]. + Represents the Event interaction data that initializes a ThingEvent object. Its properties are defined in the Event section of [[!WOT-TD]].

      The ThingFragment dictionary

      - The ThingFragment dictionary is defined as Thing in [[!WOT-TD]]. It is a dictionary that contains properties representing semantic metadata and interactions (Properties, Actions and Events). It is used for initializing an internal representation of a Thing Description and its properties may be used in ThingFilter. + The ThingFragment dictionary is defined as Thing in [[!WOT-TD]]. It is a dictionary that contains properties representing semantic metadata and interactions (Properties, Actions and Events). It is used for initializing an internal representation of a Thing Description and its properties may be used in ThingFilter.

      @@ -1577,7 +1577,7 @@

      The Observable interface

      From 1dde62c664cd1512bee36ce4a6e72d4522b9432d Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 24 Sep 2018 17:31:09 +0300 Subject: [PATCH 257/464] Fix #144: add setActionHandler() Signed-off-by: Zoltan Kis --- index.html | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/index.html b/index.html index 46c950ae..658f49c1 100644 --- a/index.html +++ b/index.html @@ -684,6 +684,7 @@

      The ExposedThing interface

      // define Actions ExposedThing addAction(DOMString name, ActionFragment init, ActionHandler action); ExposedThing removeAction(DOMString name); + ExposedThing setActionHandler(DOMString name, ActionHandler action); // define Events ExposedThing addEvent(DOMString name, EventFragment event); ExposedThing removeEvent(DOMString name); @@ -880,6 +881,35 @@

      The ActionHandler callback

      +

      The setActionHandler() method

      +

      + Takes name as string argument and action as argument of type ActionHandler. Sets the handler function for the specified Action matched by name. Throws on error. Returns a reference to the same 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 SHOULD be at most one handler for any given Action and newly added handlers replace the old handlers. +

      +

      + When an external request for invoking the Action identified by name is received, the runtime SHOULD execute the following steps: +

        +
      1. + Return a Promise promise and execute the next steps in parallel. +
        2. +
      2. + If an Action identified by name does not exist, reject promise with a ReferenceError and terminate these steps. +
        3. +
      3. + Otherwise, if no action handler has been defined for name, reject promise with a ReferenceError and terminate these steps. +
        4. +
      4. + Otherwise, invoke the Action handler associated with name. If it rejects with error, then reject promise with the same error, otherwise if it resolves with value, then resolve promise with the same value. +
        5. +
      +

      +
      +

      Examples

      From e3013020c99af658ddaa0d1861f5595228945ae3 Mon Sep 17 00:00:00 2001 From: plehegar Date: Wed, 26 Sep 2018 10:44:29 -0400 Subject: [PATCH 258/464] Code of Conduct --- CODE_OF_CONDUCT.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 CODE_OF_CONDUCT.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..04f41dc4 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,3 @@ +# Code of Conduct + +All documentation, code and communication under this repository are covered by the [W3C Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc/). From c7bf2321dcefe4a71151b325e053df7fc88a9e5b Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 3 Oct 2018 13:32:22 +0300 Subject: [PATCH 259/464] Fix PropertyWriteHandler text Signed-off-by: Zoltan Kis --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 658f49c1..80e8498b 100644 --- a/index.html +++ b/index.html @@ -812,7 +812,7 @@

      The PropertyReadHandler callback

      The PropertyWriteHandler callback

      - A function that is called when an external request for writing a Property is received. It is given the requested new value as argument and should return a Promise which is resolved when the value of the Property matching the name argument to the setPropertyReadHandler function is updated with value, or rejects with an error if the property is not found or the value cannot be updated. + A function that is called when an external request for writing a Property is received. It is given the requested new value as argument and should return a Promise which is resolved when the value of the Property that matches the name argument has been updated with value, or rejects with an error if the property is not found or the value cannot be updated.

      Note that this function is invoked by implementations before the property is updated and it actually defines what to do when a write request is received. The code in this callback function can invoke the read() method to find out the old value of the property, if needed. Therefore the old value is not provided to this function. From f4b79ea3733f7df2942f9fdedccfdc8d48c8763a Mon Sep 17 00:00:00 2001 From: Reshetova Date: Thu, 4 Oct 2018 14:58:43 +0300 Subject: [PATCH 260/464] Updating the content of security & privacy section --- index.html | 182 +++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 155 insertions(+), 27 deletions(-) diff --git a/index.html b/index.html index 658f49c1..10f93f6d 100644 --- a/index.html +++ b/index.html @@ -77,6 +77,24 @@ publisher: "W3C", date: "6 February 2017" }, + "WOT-SECURITY-CONSIDERATIONS" : { + href: "https://w3c.github.io/wot-security/", + title: "Web of Things Security and Privacy Considerations", + publisher: "W3C", + date: "28 August 2017" + }, + "WOT-SECURITY-BEST-PRACTICES" : { + href: "https://github.com/w3c/wot-security/blob/master/wot-security-best-practices.md", + title: "Web of Things Security and Privacy Best Practices (WIP)", + publisher: "W3C", + date: "WIP" + }, + "WOT-SECURITY-TESTING" : { + href: "https://github.com/w3c/wot-security/blob/master/wot-security-testing.md", + title: "Web of Things Security Testing and Validation", + publisher: "W3C", + date: "WIP" + }, "TYPESCRIPT": { href:"https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md", title: "TypeScript Language Specification", @@ -1453,33 +1471,143 @@

      The Observable interface

      -

      Security and Privacy

      -

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

      -

      - In general, implementations SHOULD consider the following guidelines: -

        -
      1. - Perform isolation of script instances (where applicable). -
        2. -
      2. - Perform security validation on all script inputs, including fuzzing. -
        3. -
      -

      -

      - Script developers SHOULD consider the following guidelines: -

        -
      1. - Minimize scripts functionality and complexity. -
        2. -
      2. - Avoid heavy functional processing in scripts without authentication. -
        3. -
      -

      -
      +

      Security and Privacy

      + +

      + In general the security measures taken to protect a WoT + system will depend on the threats and attackers that system + may face and the value of the assets needs to protect. + A detailed discussion of security and privacy considerations for the Web of Things, + including a threat model that can be adapted to various circumstances, is + presented in the informative document [[!WOT-SECURITY-CONSIDERATIONS]]. + This section includes only normative recommendations relevant to + the WoT Thing Description. +

      + +

      + When designing new devices and services for use with the WoT, + we have documented a set of best practices + in [[!WOT-SECURITY-BEST-PRACTICES]] that SHOULD be followed. + This best-practices document may be updated as security measures evolve. + Following these practices does not guarantee security, + but it at least will help to avoid common known vulnerabilities and pitfalls. +

      + + +

      Below are specific recommendations related to WoT runtime implementations: +

        +
      • In basic WoT setups, all scripts running inside the WoT runtime are considered trusted, and + therefore there is no strong need to perform strict isolation between each running script instance. + However, depending on device capabilities and deployment use case scenario risk level it might be + desirable to do so. +
          +
        • For example, if one script handles sensitive privacy-related data and well-audited, + it might be desirable to separate it from the rest of the script instances to minimize the risk of data + exposure in case some other script inside WoT gets compromised during the runtime. + + Therefore the WoT runtime SHOULD perform isolation of script instances and their data in cases + when scripts handle privacy-related or other critical security data. + +
          • +
        • + Another example is mutual co-existence of different tenants on a single WoT device. In this case each + WoT runtime instance will be hosting a different tenant, and isolation between them is required. + + Therefore the WoT runtime SHOULD perform isolation of WoT runtime instances and their data if + a WoT device has more than one tenant. + +
          • +
        + Such isolation can be performed within the WoT Runtime using platform security mechanisms + available on the device. For more information see Section "WoT Servient Single-Tenant" and + "WoT Servient Multi-Tenant" of [[!WOT-SECURITY-CONSIDERATIONS]]. +
        • + +
      • WoT scripts are using WoT Scripting API to implement the functionality and logic for WoT Things. + In addition to providing the isolation between script and runtime instances, the WoT runtime needs + to protect the underlying physical device from potentially misbehaving WoT scripts. + + Therefore the WoT Runtime SHOULD avoid directly exposing the native device interfaces + to the script developers. + + Instead a WoT Runtime should provide a hardware abstraction layer for accessing the native device + interfaces. Additionally, in order to reduce the damage to a physical WoT device in cases a WoT + script gets compromised, it is important to minimize the number of interfaces that are exposed or + accessible to a particular WoT script based on its functionality. + + Therefore the WoT Runtime SHOULD only expose a minimal set of interfaces to a WoT script based + on its intended functionality. + +
        • +
      • If the WoT runtime supports post-manufacturing provisioning or update of WoT scripts, WoT runtime + or any related data (including security credentials), it can be a major attack vector. An attacker + can try to modify any above described part during the update or provisioning process or simply + provision attacker's code and data directly. + + Therefore, if WoT Runtime supports post-manufacturing provisioning or update of WoT scripts, WoT + runtime or any related data, such operations SHOULD be done in a secure fashion. + + A set of recommendations for secure update and post-manufacturing provisioning can be found in + [[!WOT-SECURITY-BEST-PRACTICES]]. +
        • +
      • Typically the WoT runtime needs to store the security credentials that are provisioned to a WoT + device to operate in WoT network. The confidentiality or integrity of these credentials should not + be compromised. + + Therefore the WoT runtime SHOULD securely store the provisioned security credentials, + guaranteeing their integrity and confidentiality. + + + In case there are more than one tenant on a single WoT-enabled device, a WoT Runtime SHOULD + guarantee isolation of each tenant provisioned security credentials. + + Additionally, in order to minimize a risk that provisioned security credentials get compromised, + the WoT runtime should not have any way for WoT scripts to query these credentials. + + Therefore, the WoT Runtime SHOULD NOT expose any API for WoT scripts to query the provisioned + security credentials. + +
        • +
      +

      + +

      Some additional specific recommendations relevant for WoT script developers: +

        +
      • A typical way to compromise any process is to send it a corrupted input via one of the exposed + interfaces. + + Therefore developers SHOULD perform validation on all WoT script inputs, including + fuzzing. + + There are many tool and techniques in existence to do such validation. + More details can be found in [[!WOT-SECURITY-TESTING]]. + +
        • +
      • As any software, complex scripts with a lot of functionality presents a higher risk of + development mistakes. Such scripts are also hard to verify and test appropriately. + + Therefore developers SHOUD minimize the functionality and complexity of WoT scripts. + +
        • +
      • If a WoT script performs a heavy functional processing on received requests before the request + is authenticated, it presents a great risk for Denial-Of-Service (DOS) attacks. + + Therefore WoT scripts SHOULD avoid heavy functional processing without prior successful + authentication of requestor. + + The set of recommended authentication mechanisms can be found in [[!WOT-SECURITY-BEST-PRACTICES]]. +
        • +
      • WoT developers should remember that a content of a TD can change, including its identified, id, + which is not an immutable identifier. + + Therefore WoT scripts SHOULD use the provided WoT script API to subscribe for notifications + on TD changes. + +
        • +
      +

      +
      +

      Terminology and conventions

      From 67d0942c28dc72fc9e0d56a555ec9ad806c2537c Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 15 Oct 2018 17:21:00 +0300 Subject: [PATCH 261/464] Update WebIDL in this spec, following ReSpec update to support latest Web IDL specification Signed-off-by: Zoltan Kis --- index.html | 78 +++++++++++++++++++++++++++--------------------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/index.html b/index.html index ea538368..da5cbadd 100644 --- a/index.html +++ b/index.html @@ -79,19 +79,19 @@ }, "WOT-SECURITY-CONSIDERATIONS" : { href: "https://w3c.github.io/wot-security/", - title: "Web of Things Security and Privacy Considerations", + title: "Web of Things Security and Privacy Considerations", publisher: "W3C", date: "28 August 2017" - }, + }, "WOT-SECURITY-BEST-PRACTICES" : { href: "https://github.com/w3c/wot-security/blob/master/wot-security-best-practices.md", - title: "Web of Things Security and Privacy Best Practices (WIP)", + title: "Web of Things Security and Privacy Best Practices (WIP)", publisher: "W3C", date: "WIP" }, "WOT-SECURITY-TESTING" : { href: "https://github.com/w3c/wot-security/blob/master/wot-security-testing.md", - title: "Web of Things Security Testing and Validation", + title: "Web of Things Security Testing and Validation", publisher: "W3C", date: "WIP" }, @@ -615,17 +615,17 @@

      The ConsumedThing interface

      }; [NoInterfaceObject] interface PropertyMap { - maplike<DOMString, ThingProperty>; + readonly maplike<DOMString, ThingProperty>; }; [NoInterfaceObject] interface ActionMap { - maplike<DOMString, ThingAction>; + readonly maplike<DOMString, ThingAction>; }; [NoInterfaceObject] interface EventMap { - maplike<DOMString, ThingEvent>; + readonly maplike<DOMString, ThingEvent>; }; - ConsumedThing implements Observable; // for TD changes + ConsumedThing includes Observable; // for TD changes

      The id attribute represents the unique identifier of the Thing instance, typically a URI, IRI, or URN as USVString. @@ -1200,7 +1200,7 @@

      The Interaction interface

      interface Interaction { readonly attribute (Form or FrozenArray<Form>) forms; }; - Interaction implements InteractionFragment; + Interaction includes InteractionFragment;

      The forms read-only property represents the protocol bindings initialization data and is initialized by the WoT Runtime. @@ -1223,8 +1223,8 @@

      The ThingProperty interface

      Promise<any> read(); Promise<void> write(any value); }; - ThingProperty implements PropertyFragment; - ThingProperty implements Observable; + ThingProperty includes PropertyFragment; + ThingProperty includes Observable;

      The ThingProperty interface contains all the properties defined on PropertyFragment as read-only properties. @@ -1258,7 +1258,7 @@

      The ThingAction interface

      interface ThingAction: Interaction { Promise<any> invoke(optional any inputValue); }; - ThingAction implements ActionFragment; + ThingAction includes ActionFragment;

      The invoke() method when invoked, starts the Action interaction with the input value provided by the inputValue argument. If inputValue is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided. Otherwise the type of inputValue SHOULD match the DataSchema definition in the input property. Returns a Promise that will reject with an error or will resolve with a value of type defined by the output property. @@ -1269,8 +1269,8 @@

      The ThingAction interface

               interface ThingEvent: Interaction {
         };
-        ThingEvent implements EventFragment;
-        ThingEvent implements ThingProperty;
+        ThingEvent includes EventFragment;
+        ThingEvent includes ThingProperty;

      Since ThingEvent implements Observable through the ThingProperty interface, event subscription is done by invoking the subscribe() method on the event object that returns a cancelable Subscription. @@ -1472,14 +1472,14 @@

      The Observable interface

      Security and Privacy

      - +

      - In general the security measures taken to protect a WoT + In general the security measures taken to protect a WoT system will depend on the threats and attackers that system may face and the value of the assets needs to protect. A detailed discussion of security and privacy considerations for the Web of Things, including a threat model that can be adapted to various circumstances, is - presented in the informative document [[!WOT-SECURITY-CONSIDERATIONS]]. + presented in the informative document [[!WOT-SECURITY-CONSIDERATIONS]]. This section includes only normative recommendations relevant to the WoT Thing Description.

      @@ -1489,7 +1489,7 @@

      The Observable interface

      we have documented a set of best practices in [[!WOT-SECURITY-BEST-PRACTICES]] that SHOULD be followed. This best-practices document may be updated as security measures evolve. - Following these practices does not guarantee security, + Following these practices does not guarantee security, but it at least will help to avoid common known vulnerabilities and pitfalls.

      @@ -1499,11 +1499,11 @@

      The Observable interface

    3. In basic WoT setups, all scripts running inside the WoT runtime are considered trusted, and therefore there is no strong need to perform strict isolation between each running script instance. However, depending on device capabilities and deployment use case scenario risk level it might be - desirable to do so. + desirable to do so.
      • For example, if one script handles sensitive privacy-related data and well-audited, it might be desirable to separate it from the rest of the script instances to minimize the risk of data - exposure in case some other script inside WoT gets compromised during the runtime. + exposure in case some other script inside WoT gets compromised during the runtime. Therefore the WoT runtime SHOULD perform isolation of script instances and their data in cases when scripts handle privacy-related or other critical security data. @@ -1511,7 +1511,7 @@

        The Observable interface

      • Another example is mutual co-existence of different tenants on a single WoT device. In this case each - WoT runtime instance will be hosting a different tenant, and isolation between them is required. + WoT runtime instance will be hosting a different tenant, and isolation between them is required. Therefore the WoT runtime SHOULD perform isolation of WoT runtime instances and their data if a WoT device has more than one tenant. @@ -1525,7 +1525,7 @@

        The Observable interface

      • WoT scripts are using WoT Scripting API to implement the functionality and logic for WoT Things. In addition to providing the isolation between script and runtime instances, the WoT runtime needs - to protect the underlying physical device from potentially misbehaving WoT scripts. + to protect the underlying physical device from potentially misbehaving WoT scripts. Therefore the WoT Runtime SHOULD avoid directly exposing the native device interfaces to the script developers. @@ -1533,16 +1533,16 @@

        The Observable interface

        Instead a WoT Runtime should provide a hardware abstraction layer for accessing the native device interfaces. Additionally, in order to reduce the damage to a physical WoT device in cases a WoT script gets compromised, it is important to minimize the number of interfaces that are exposed or - accessible to a particular WoT script based on its functionality. + accessible to a particular WoT script based on its functionality. Therefore the WoT Runtime SHOULD only expose a minimal set of interfaces to a WoT script based on its intended functionality. - +
      • If the WoT runtime supports post-manufacturing provisioning or update of WoT scripts, WoT runtime or any related data (including security credentials), it can be a major attack vector. An attacker can try to modify any above described part during the update or provisioning process or simply - provision attacker's code and data directly. + provision attacker's code and data directly. Therefore, if WoT Runtime supports post-manufacturing provisioning or update of WoT scripts, WoT runtime or any related data, such operations SHOULD be done in a secure fashion. @@ -1551,21 +1551,21 @@

        The Observable interface

        [[!WOT-SECURITY-BEST-PRACTICES]].
      • Typically the WoT runtime needs to store the security credentials that are provisioned to a WoT - device to operate in WoT network. The confidentiality or integrity of these credentials should not - be compromised. + device to operate in WoT network. The confidentiality or integrity of these credentials should not + be compromised. Therefore the WoT runtime SHOULD securely store the provisioned security credentials, - guaranteeing their integrity and confidentiality. + guaranteeing their integrity and confidentiality. - In case there are more than one tenant on a single WoT-enabled device, a WoT Runtime SHOULD - guarantee isolation of each tenant provisioned security credentials. + In case there are more than one tenant on a single WoT-enabled device, a WoT Runtime SHOULD + guarantee isolation of each tenant provisioned security credentials. Additionally, in order to minimize a risk that provisioned security credentials get compromised, the WoT runtime should not have any way for WoT scripts to query these credentials. Therefore, the WoT Runtime SHOULD NOT expose any API for WoT scripts to query the provisioned - security credentials. + security credentials.
      @@ -1574,23 +1574,23 @@

      The Observable interface

      Some additional specific recommendations relevant for WoT script developers:

      • A typical way to compromise any process is to send it a corrupted input via one of the exposed - interfaces. + interfaces. - Therefore developers SHOULD perform validation on all WoT script inputs, including + Therefore developers SHOULD perform validation on all WoT script inputs, including fuzzing. - There are many tool and techniques in existence to do such validation. + There are many tool and techniques in existence to do such validation. More details can be found in [[!WOT-SECURITY-TESTING]].
      • As any software, complex scripts with a lot of functionality presents a higher risk of - development mistakes. Such scripts are also hard to verify and test appropriately. + development mistakes. Such scripts are also hard to verify and test appropriately. - Therefore developers SHOUD minimize the functionality and complexity of WoT scripts. + Therefore developers SHOUD minimize the functionality and complexity of WoT scripts.
      • If a WoT script performs a heavy functional processing on received requests before the request - is authenticated, it presents a great risk for Denial-Of-Service (DOS) attacks. + is authenticated, it presents a great risk for Denial-Of-Service (DOS) attacks. Therefore WoT scripts SHOULD avoid heavy functional processing without prior successful authentication of requestor. @@ -1598,10 +1598,10 @@

        The Observable interface

        The set of recommended authentication mechanisms can be found in [[!WOT-SECURITY-BEST-PRACTICES]].
      • WoT developers should remember that a content of a TD can change, including its identified, id, - which is not an immutable identifier. + which is not an immutable identifier. Therefore WoT scripts SHOULD use the provided WoT script API to subscribe for notifications - on TD changes. + on TD changes.
      From c368fd9740f909d24fb710cb4018e71f9ffd2ac4 Mon Sep 17 00:00:00 2001 From: plehegar Date: Wed, 17 Oct 2018 20:46:13 -0400 Subject: [PATCH 262/464] Config --- w3c.json | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/w3c.json b/w3c.json index d6f8b345..2420b7e8 100644 --- a/w3c.json +++ b/w3c.json @@ -1,5 +1,10 @@ - { - "group": ["95969"] -, "contacts": ["ashimura"] -, "shortName": "wot-scripting-api" +{ + "group": [ + "95969" + ], + "contacts": [ + "ashimura" + ], + "shortName": "wot-scripting-api", + "repo-type": "rec-track" } \ No newline at end of file From b6792e1568456018d884c8824640185f83b13ecd Mon Sep 17 00:00:00 2001 From: ashimura Date: Mon, 22 Oct 2018 00:21:54 +0900 Subject: [PATCH 263/464] publication preparation --- Overview.html | 5724 +++++++++++ diff.html | 19177 +++++++++++++++++++++++++++++++++++ releases/wd3/Overview.html | 5724 +++++++++++ releases/wd3/diff.html | 19177 +++++++++++++++++++++++++++++++++++ releases/wd3/manifest.txt | 2 + 5 files changed, 49804 insertions(+) create mode 100644 Overview.html create mode 100644 diff.html create mode 100644 releases/wd3/Overview.html create mode 100644 releases/wd3/diff.html create mode 100644 releases/wd3/manifest.txt diff --git a/Overview.html b/Overview.html new file mode 100644 index 00000000..2f6915b6 --- /dev/null +++ b/Overview.html @@ -0,0 +1,5724 @@ + + + + + + + + + + + Web of Things (WoT) Scripting API + + + + + + + + +
      + +

      Web of Things (WoT) + Scripting API

      +

      W3C Working + Draft

      +
      +
      This version:
      +
      + + https://www.w3.org/TR/2018/WD-wot-scripting-api-20181021/ +
      +
      Latest published version:
      +
      + https://www.w3.org/TR/wot-scripting-api/ +
      +
      Latest editor's draft:
      +
      + https://w3c.github.io/wot-scripting-api/ +
      +
      Previous version:
      +
      + + https://www.w3.org/TR/2018/WD-wot-scripting-api-20180405/ +
      +
      Editors:
      +
      + Zoltan Kis (Intel) +
      +
      + Kazuaki Nimura (Fujitsu Ltd.) +
      +
      + Daniel Peintner (Siemens AG) +
      +
      Johannes Hund (Former Editor, when at + Siemens AG)
      +
      Contributors:
      +
      + + In the GitHub repository +
      +
      Repository:
      +
      + We are + on GitHub +
      +
      + File a + bug +
      +
      +

      Copyright + © 2017-2018 W3C® + (MIT, + ERCIM, + Keio, Beihang). W3C + liability, + trademark and + permissive document license rules apply.

      +
      +
      +
      +

      Abstract

      +

      The overall Web of Things (WoT) concepts are + described in the WoT Architecture + document. The Web of Things is made of entities (Things) that can describe their capabilities in a + machine-interpretable format, the Thing Description (TD) and expose these capabilities + through the WoT Interface, 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.

      +

      This specification describes a programming interface + representing the WoT Interface that + allows scripts run on a Thing to discover and + consume (retrieve) other Thing Descriptions + and to expose Things characterized by WoT Interactions specified by a script.

      +

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

      +
      +
      +

      Status of This Document

      +

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

      +

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

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

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

      +
      +

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

      +

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

      +

      Changes from the previous publication can be found in + Appendix B. A diff-marked version of this document is also + available for comparison purposes.

      +

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

      +

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

      +

      This document is governed by the 1 February 2018 + W3C Process + Document.

      +
      + +
      + +

      1. + Introduction

      +

      WoT provides layered interoperability based on how Things are modeled: as being "consumed" and + "exposed".

      +

      By consuming a TD, a client Thing creates a runtime resource model that allows + accessing the Properties, Actions and + Events exposed by the server Thing exposed on a + remote device.

      +

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

      +
      +
      + Note +
      +

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

      +
      +
      +
      + Note +
      +

      This specification does not make assumptions on + how the WoT Runtime handles and runs + scripts, including single or multiple tenancy, script + deployment and lifecycle management. The API already supports + the generic mechanisms that make it possible to implement + script management, for instance by exposing a manager + Thing whose Actions (action + handlers) implement script lifecycle management + operations.

      +
      +

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

      +
      +
      + +

      2. Use + Cases

      +

      This section is non-normative.

      +

      The following scripting use cases are supported in this + specification:

      +
      +

      2.1 + Discovery

      +
        +
      • Discover all Things in the WoT network by + sending a broadcast request. +
        • +
      • Discover Things running in the local + WoT Runtime. +
        • +
      • Discover nearby Things, for instance + connected by NFC or Bluetooth. +
        • +
      • Discover Things by sending a discovery + request to a given registry. +
        • +
      • Discover Things by filters defined on + Thing Descriptions +
        • +
      • Discover Things by semantic queries. +
        • +
      • Stop or suppress an ongoing discovery process.
        • +
      • Optionally specify a timeout to the discovery process + after which it is stopped/suppressed.
        • +
      +
      +
      +

      2.2 Consuming a Thing

      + +
      +
      +

      2.3 + Exposing a Thing

      +
        +
      • Exposing the Thing includes generating the + protocol bindings in order to access lower level + functionality. +
        • +
      • Create a local ExposedThing to be exposed, based on + a Thing Description provided in + string serialized format, or out of a template or an + existing ConsumedThing object. +
        • +
      • Add a Property definition to the + Thing. +
        • +
      • Add an Action definition to the + Thing. +
        • +
      • Add an Event definition to the Thing. +
        • +
      • Attach semantic information to the Thing. +
        • +
      • Attach semantic information to a + Property. +
        • +
      • Attach semantic information to an Action. +
        • +
      • Attach semantic information to an Event. +
        • +
      • Emit an Event, i.e. notify all listeners + subscribed to that Event. +
        • +
      • Provide notifications for TD changes to + clients subscribed to that. +
        • +
      • Mark/unmark the Thing to be discoverable.
        • +
      • Mark/unmark the Thing to be consumable.
        • +
      • Start the exposed Thing in order to + process external requests. +
        • +
      • Stop the exposed Thing. +
        • +
      • Register handlers for external requests: +
          +
        • to retrieve a Property value; +
          • +
        • to update a Property value; +
          • +
        • to run an Action: take the + parameters from the request, execute the defined + action, and return the result; +
          • +
        +
        • +
      +
      +
      +
      + +

      3. The + WoT + object

      +

      The WoT object is the API entry point and it is exposed by + an implementation of the WoT Runtime. The + WoT object + does not expose properties, only methods for discovering, + consuming and exposing a Thing.

      +
      +
      + Note +
      +

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

      +
      +
      + 
      // [SecureContext]
+// [NamespaceObject]
+interface WoT {
+  Observable discover(optional ThingFilter filter);
+  Promise<ThingDescription> fetch(USVString url);
+  ConsumedThing consume(ThingDescription td);
+  ExposedThing produce(ThingModel model);
+  Promise<void> register(USVString directory, ExposedThing thing);
+  Promise<void> unregister(USVString directory, ExposedThing thing);
+};
+typedef object ThingFragment;
+typedef object PropertyFragment;
+typedef object ActionFragment;
+typedef object EventFragment;
+typedef object DataSchema;
+typedef object SecurityScheme;
+typedef object Link;
+typedef object Form;
+typedef USVString ThingDescription;
+typedef (ThingFragment or ThingDescription) ThingModel;
      +
      +
      +
      + Editor's note +
      +

      The algorithms for the WoT methods will be + specified later, including error handling and security + considerations.

      +
      +

      The ThingModel type represents + either a ThingFragment, or a + ThingDescription.

      +
      +

      3.1 The discover() + method

      +

      Starts the discovery process that will provide ThingDescriptions that match the + optional argument filter of type ThingFilter. Returns an + [Observable](https://github.com/tc39/proposal-observable) + object that can be subscribed to and unsubscribed from. The + handler function provided to the Observable during + subscription will receive an argument of type + USVString representing a ThingDescription.

      +
      +

      + 3.1.1 The DiscoveryMethod + enumeration

      +
      + 
      typedef DOMString DiscoveryMethod;
      +
      +

      DiscoveryMethod + represents the discovery type to be used:

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

      3.1.2 The ThingFilter + dictionary

      +

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

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

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

      +

      The url property + represents additional information for the discovery method, + such as the URL of the target entity serving the discovery + request, for instance a Thing + Directory (if method is + "directory") or a Thing (otherwise).

      +

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

      +

      The fragment property + represents a ThingFragment dictionary used for + matching property by property against discovered Things.

      +
      +

      The discover(filter) method MUST run the following steps:

      +
        +
      1. If invoking discover() is not allowed for + the current scripting context for security reasons, throw + SecurityError and terminate these steps.
        2. +
      2. Return an Observable obs and + execute the next steps in parallel. +
        3. +
      3. If obs.subscribe(handler, errorHandler, + complete) is called, execute the following + sub-steps: +
          +
        1. If the first argument handler is not + defined or it is not a function, throw + TypeError and terminate the algorithm. + Otherwise configure handler to be invoked + when a discovery hit happens.
          2. +
        2. If the second argument errorHandler is + defined, but it is not a function, throw + TypeError and terminate these steps. + Otherwise if defined, save it to be invoked in error + conditions.
          3. +
        3. If the third argument onComplete is + defined, but it is not a function, throw + TypeError and terminate these steps. + Otherwise if defined, save it to be invoked when the + discovery process finished for other reasons than + having been canceled.
          4. +
        4. If filter.query is defined, pass it as + an opaque string to the underlying implementation to be + matched against discovered items. The underlying + implementation is responsible to parse it e.g. as a + SPARQL or JSON query and match it against the + Thing Descriptions found + during the discovery process. If queries are not + supported, implementations SHOULD throw a + NotSupported error and terminate these + steps. +
          5. +
        5. If filter.fragment is defined, and if it + contains other properties than the ones defined in + ThingFragment, + throw TypeError and terminate these steps. + Otherwise save the object for matching the discovered + items against it. +
          6. +
        6. Request the underlying platform to start the + discovery process, with the following parameters: +
            +
          • If filter.method is not defined or + the value is "any", use the widest + discovery method supported by the underlying + platform.
            • +
          • Otherwise if filter.method is + "local", use the local Thing Directory for + discovery. Usually that defines Things deployed in the same device, or + connected to the device in slave mode (e.g. + sensors connected via Bluetooth or a serial + connection). +
            • +
          • Otherwise if filter.method is + "directory", use the remote Thing Directory + specified in filter.url. +
            • +
          • Otherwise if filter.method is + "multicast", use all the multicast + discovery protocols supported by the underlying + platform.
            • +
          +
          7. +
        +
        4. +
      4. Whenever a new item td is discovered by the + underlying platform, run the following sub-steps: +
          +
        1. If filter.query is defined, check if + td is a match for the query. The matching + algorithm is encapsulated by implementations. If that + returns false, discard td and + continue the discovery process.
          2. +
        2. If filter.fragment is defined, for each + property defined in it, check if that property exists + in td and has the same value. If this is + false in any checks, discard td + and continue the discovery process.
          3. +
        3. Otherwise if td has not been discarded + in the previous steps, invoke the handler + function with td as parameter.
          4. +
        +
        5. +
      5. Whenever an error occurs during the discovery process, + and if errorHandler is defined, invoke it with + an argument of type Error whose + message property is set to + UnknownError unless there was an error code + provided by the Protocol Bindings, + in which case set it to that value. +
        6. +
      6. When the discovery process is finished, and if + onComplete is defined, invoke it run the + cancel discovery steps. +
        7. +
      7. When the obs.unsubscribe() method is + called, run the following cancel discovery steps: +
          +
        1. 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.
          2. +
        2. Set obs.closed to + false.
          3. +
        +
        8. +
      +
      +
      +

      3.2 + The fetch() + method

      +

      Accepts an url argument of type + USVString that represents a URL (e.g. + "file://..." or "https://...") and + returns a Promise that resolves with a + ThingDescription (a + serialized JSON-LD document of type + USVString).

      +

      The fetch(url) method MUST run the following steps:

      +
        +
      1. Return a Promise promise and + execute the next steps in parallel. +
        2. +
      2. If invoking fetch() is not allowed for the + current scripting context for security reasons, reject + promise with SecurityError and + terminate these steps.
        3. +
      3. If the argument url is not a URL, reject + promise with TypeError and + terminate these steps.
        4. +
      4. Make a request to fetch the content of url + as described by the Protocol + Bindings and wait for the reply. Implementations + encapsulate the fetching process and the accepted media + types (such as application/td+json), as far + as a valid Thing Description + can be obtained as defined in [WOT-TD]. Let td + be the Thing Description + string-serialized from the returned content, as specified + in the + Thing Description serialization. +
        5. +
      5. 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 terminate + these steps. +
        6. +
      6. Otherwise resolve promise with td + and terminate these steps.
        7. +
      +
      +
      +

      3.3 The consume() + method

      +

      Accepts an td argument of type ThingDescription and returns a + ConsumedThing object + instantiated based on parsing that description.

      +

      The consume(td) method must run the following + steps:

      +
        +
      1. If the argument td is not a string, throw a + TypeError and terminate these steps.
        2. +
      2. Let stub be the result of running the + TD parsing algorithm with + td as argument. If that throws an error, + re-throw the error and terminate these steps. +
        3. +
      3. If stub does not have an own property that + is defined in ThingFragment with a default value, + add that property and value to stub. +
        4. +
      4. Create a ConsumedThing object + thing initialized from stub that + implements Observable. +
        5. +
      5. Add the read() and write() + methods to the ThingProperty elements so that they + make requests to access the remote Things and + wait for the reply, as defined by the Protocol Bindings. Also, all + ThingProperty + elements SHOULD + implement Observable, i.e. + define a subscribe() method that should make + request to observe the given Properties + as defined by the Protocol Bindings. +
        6. +
      6. Add the invoke() methods to the ThingAction elements so that they + make requests to the remote Thing to invoke its + actions, as defined by the Protocol + Bindings. +
        7. +
      7. Add the subscribe() method to all + ThingEvent elements + so that they make requests to subscribe to the events + defined by the remote Thing, as defined + by the Protocol Bindings. +
        8. +
      8. Return thing.
        9. +
      +
      +
      +

      3.4 The produce() + method

      +

      Accepts a model argument of type + ThingModel and + returns an ExposedThing + object.

      +

      The produce(model) method MUST run the following steps:

      +
        +
      1. If invoking produce() is not allowed for + the current scripting context for security reasons, throw + SecurityError and terminate these steps.
        2. +
      2. If the argument model is a string, then run + the TD parsing algorithm with model + passed as parameter. If it throws an error, re-throw that + error and terminate this algorithm. Otherwise let + model be the returned value.
        3. +
      3. If model is not an object, throw + TypeError and terminate these steps.
        4. +
      4. If model does not have an own property that + is defined in ThingFragment with a default value, + add that property and value to model. +
        5. +
      5. Create an ExposedThing object thing + initialized from model. +
        6. +
      6. For each property of ExposedThing defined in ThingFragment, initialize the + property based on the provided initial or default values + provided to the local WoT Runtime + implementation, for instance initialize: +
          +
        1. the id property to be the final unique + identifier of the Thing, +
          2. +
        2. the security object of type SecurityScheme to + represent the actual security scheme and its properties + as set up by the implementation, +
          3. +
        3. the properties property to be an + object with all properties being ThingProperty + objects in which the read() and + write() methods are provided to define + local methods to get and set the Property values, +
          4. +
        4. the actions property to be an object + with all properties being ThingAction objects in which the + invoke() method is provided to define a + local method to run the defined Actions, +
          5. +
        5. the events property to be an object + with all properties being ExposedEvent objects in which + the emit() method is provided to define a + local way to trigger sending notifications to all + subscribed clients, +
          6. +
        6. and initialize the other properties as initialized + from model.
          7. +
        7. Return thing.
          8. +
        +

        The TD parsing algorithm + takes a string td as argument and runs the + following steps:

        +
          +
        1. Parse td according to the + WoT Thing Description in order to produce a + JSON + object json. Update thing + with the properties and values defined in + json. +
          2. +
        2. If there was an error during the parsing, throw + that error and terminate these steps.
          3. +
        3. Otherwise return json.
          4. +
        +
        7. +
      +
      +
      +

      3.5 The register() + method

      +

      Takes two mandatory arguments:

      + +

      Generate the Thing Description as + td, given the Properties, Actions and Events defined for + this ExposedThing object. + Then make a request to register td to the given + WoT Thing Directory.

      +
      +
      +

      3.6 The + unregister() method

      +

      Takes two mandatory arguments:

      + +

      Makes a request to unregister the thing from + the given WoT Thing Directory.

      +
      +
      +

      3.7 + Examples

      +
      +
      + Example + 1: Discover Things via + directory +
      + 
      let discoveryFilter = {
+  method: "directory",
+  url: "http://directory.wotservice.org"
+};
+let subscription = wot.discover(discoveryFilter).subscribe(
+  td => {
+    console.log("Found Thing " + td.name);
+    // fetch the TD and create a ConsumedThing
+    let thing = wot.consume(td);
+  },
+  error => { console.log("Discovery finished because an error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);
+setTimeout( () => {
+    subscription.unsubscribe();
+    console.log("Discovery timeout");
+  },
+  5000);
      +
      +
      +
      + Example + 2: Discover Things + exposed by local hardware +
      + 
      let subscription = wot.discover({ method: "local" }).subscribe(
+  td => { console.log("Found local Thing " + td.name); },
+  error => { console.log("Discovery error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);
      +
      +
      +
      + + Example 3: Same as above + but with different Observable syntax +
      + 
      let subscription = wot.discover({ method: "local" }).subscribe({
+  td => { console.log("Found local Thing " + td.name); },
+  error: err => { console.log("Discovery error: " + err.message); },
+  complete: () => { console.log("Discovery finished successfully");}
+});
      +
      +
      +
      +
      + +

      4. The ConsumedThing + interface

      +

      Represents an object that extends a ThingFragment with methods for client + interactions (send request for reading and writing Properties), invoke Actions, subscribe and + unsubscribe for Property changes and Events.

      +
      + 
      interface ConsumedThing : ThingFragment {
+  readonly attribute DOMString id;
+  readonly attribute DOMString name;
+  readonly attribute DOMString? base;
+  readonly attribute PropertyMap properties;
+  readonly attribute ActionMap actions;
+  readonly attribute EventMap events;
+  // getter for ThingFragment properties
+  getter any (DOMString name);
+};
+[NoInterfaceObject]
+interface PropertyMap {
+  readonly maplike<DOMString, ThingProperty>;
+};
+[NoInterfaceObject]
+interface ActionMap {
+  readonly maplike<DOMString, ThingAction>;
+};
+[NoInterfaceObject]
+interface EventMap {
+  readonly maplike<DOMString, ThingEvent>;
+};
+ConsumedThing includes Observable;  // for TD changes
      +
      +

      The id attribute + represents the unique identifier of the Thing instance, + typically a URI, IRI, or URN as USVString.

      +

      The name attribute + represents the name of the Thing as + DOMString.

      +

      The base attribute + represents the base URI that is valid for all defined local + interaction resources.

      +

      The properties + attribute represents a dictionary of ThingProperty items. The + PropertyMap interface + represents a maplike dictionary where all values are ThingProperty objects. The + read() and write() methods make a + request to access the Properties on the remote + Thing represented by this ConsumedThing proxy object.

      +

      The actions + attribute represents a dictionary of ThingAction items. The + ActionMap interface represents a + maplike dictionary where all values are ThingAction objects. The + invoke() method represents a request to invoke the + Action on the remote Thing.

      +

      The events + attribute represents a dictionary of ThingEvent items. The EventMap interface + represents a maplike dictionary where all values are ThingEvent objects. Subscribing to the + events involves setting up an observation (subscription) + mechanism on the remote object.

      +
      +

      4.1 + Examples

      +

      Below a ConsumedThing interface example + is given.

      +
      +
      + Example + 4: Consume a Thing +
      + 
      try {
+  let subscription = wot.discover({ method: "local" }).subscribe(
+    td => {
+      let thing = wot.consume(td);
+      console.log("Thing " + thing.name + " has been consumed.");
+      let subscription = thing["temperature"].subscribe(function(value) {
+          console.log("Temperature: " + value);
+        });
+      thing.actions["startMeasurement"].invoke({ units: "Celsius" })
+        .then(() => { console.log("Temperature measurement started."); })
+        .catch(e => {
+           console.log("Error starting measurement.");
+           subscription.unsubscribe();
+         })
+    },
+    error => { console.log("Discovery error: " + error.message); },
+    () => { console.log("Discovery finished successfully");}
+  );
+} catch(error) {
+  console.log("Error: " + error.message);
+};
      +
      +
      +
      +
      + +

      5. The ExposedThing + interface

      +

      The ExposedThing interface is + the server API that allows defining request handlers, + properties, Actions, and Events to a + Thing. It also implements the Observable interface. An ExposedThing is created by the produce() method.

      +
      + 
      interface ExposedThing : ThingFragment {
+  readonly attribute PropertyMap properties;
+  readonly attribute ActionMap actions;
+  readonly attribute ExposedEvents events;
+  // getter for ThingFragment properties
+  getter any (DOMString name);
+  // setter for ThingFragment properties
+  setter void (DOMString name, any value);
+  // methods to expose and destroy the Thing
+  Promise<void> expose();
+  Promise<void> destroy();
+  // define Properties
+  ExposedThing addProperty(DOMString name, PropertyFragment property, optional any initValue);
+  ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
+  ExposedThing setPropertyWriteHandler(DOMString name, PropertyWriteHandler writeHandler);
+  ExposedThing removeProperty(DOMString name);
+  // define Actions
+  ExposedThing addAction(DOMString name, ActionFragment init, ActionHandler action);
+  ExposedThing removeAction(DOMString name);
+  ExposedThing setActionHandler(DOMString name, ActionHandler action);
+  // define Events
+  ExposedThing addEvent(DOMString name, EventFragment event);
+  ExposedThing removeEvent(DOMString name);
+};
+[NoInterfaceObject]
+interface ExposedEvents {
+  maplike<DOMString, ExposedEvent>;
+};
+callback PropertyReadHandler = Promise<any> ();
+callback PropertyWriteHandler = Promise<void> (any value);
+callback ActionHandler = Promise<any> (any parameters);
      +
      +

      The properties + attribute represents a dictionary of ThingProperty items in which the + read() and write() methods define + local methods that access the physical representations of the + Properties.

      +

      The actions + attribute represents a dictionary of ThingAction items in which the + invoke() method represents a local method to + invoke the Action.

      +

      The events + attribute represents a dictionary of ExposedEvent items that add the + emit() method to the ThingEvent definition. The + ExposedEvents interface + represents a maplike dictionary where all values are ExposedEvent objects.

      +
      +

      5.1 The + expose() method

      +

      Start serving external requests for the Thing, so that WoT Interactions + using Properties, Actions and + Events will be possible.

      +

      The expose() method MUST run the following steps:

      +
        +
      1. Return a Promise promise and + execute the next steps in parallel. +
        2. +
      2. If invoking expose() is not allowed for + the current scripting context for security reasons, reject + promise with SecurityError and + terminate these steps.
        3. +
      3. Make a request to the underlying platform to attach + protocol handlers and start serving external requests for + WoT Interactions (read, write and + observe Properties, invoke Actions and manage Event + subscriptions), based on the Protocol Bindings. +
        4. +
      4. 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 terminate + these steps. +
        5. +
      5. Otherwise resolve promise with td + and terminate these steps.
        6. +
      +
      +
      +

      5.2 The + destroy() method

      +

      Stop serving external requests for the Thing and destroy the object. Note that eventual + unregistering should be done before invoking this method.

      +

      The destroy() method MUST run the following steps:

      +
        +
      1. Return a Promise promise and + execute the next steps in parallel. +
        2. +
      2. If invoking destroy() is not allowed for + the current scripting context for security reasons, reject + promise with SecurityError and + terminate these steps.
        3. +
      3. Make a request to the underlying platform to stop + serving external requests for WoT Interactions, based on the + Protocol Bindings. +
        4. +
      4. 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 terminate + these steps. +
        5. +
      5. Otherwise resolve promise with td + and terminate these steps.
        6. +
      +
      +
      +

      5.3 The + addProperty() method

      +

      Adds a Property with name defined by the + name argument, the data schema provided by the + property argument of type PropertyFragment, and optionally an + initial value provided in the argument initValue + whose type should match the one defined in the + type property according to the value-matching algorithm. If + initValue is not provided, it SHOULD be initialized as + undefined. Implementations SHOULD update the Thing Description. Throws on error. Returns a + reference to the same object for supporting chaining.

      +
      +
      +

      5.4 The + removeProperty() method

      +

      Removes the Property specified by the + name argument and updates the Thing Description. Throws on error. Returns a + reference to the same object for supporting chaining.

      +
      +
      +

      5.5 The + addAction() method

      +

      Adds to the actions property of a Thing object an Action with name + defined by the name argument, defines input and + output data format by the init argument of type + ActionFragment, and + adds the function provided in the action argument + as a handler, then updates the Thing Description. Throws on error. Returns a + reference to the same object for supporting chaining.

      +

      The provided action callback function will + implement invoking an Action and SHOULD be called by + implementations when a request for invoking the Action is received from the underlying platform. + The callback will receive a parameters + dictionary argument according to the definition in the + init.input argument and will return a value of + type defined by the init.output argument according + to the value-matching + algorithm.

      +

      There SHOULD be + exactly one handler for any given Action. If no + handler is initialized for any given Action, + implementations SHOULD throw a TypeError.

      +
      +
      +

      5.6 The + removeAction() method

      +

      Removes the Action specified by the + name argument and updates the Thing Description. Throws on error. Returns a + reference to the same object for supporting chaining.

      +
      +
      +

      5.7 The + addEvent() method

      +

      Adds an event with name defined by the name + argument and qualifiers and initialization value provided by + the event argument of type EventFragmentto the Thing object and updates the Thing Description. Throws on error. Returns a + reference to the same object for supporting chaining.

      +
      +
      +

      5.8 The + removeEvent() method

      +

      Removes the event specified by the name + argument and updates the Thing + Description. Returns a reference to the same object for + supporting chaining.

      +
      +
      +

      5.9 The PropertyReadHandler + callback

      +

      A function that is called when an external request for + reading a Property is received. It should + return a Promise and resolves it with the value of the + Property matching the name argument to + the setPropertyReadHandler function, or rejects + with an error if the property is not found or the value + cannot be retrieved.

      +
      +
      +

      5.10 The PropertyWriteHandler + callback

      +

      A function that is called when an external request for + writing a Property is received. It is given + the requested new value as argument and should + return a Promise which is resolved when the value of the + Property that matches the name + argument has been updated with value, or rejects + with an error if the property is not found or the value + cannot be updated.

      +
      +
      + Editor's note +
      +

      Note that this function is invoked by + implementations before the property is updated and it + actually defines what to do when a write request is + received. The code in this callback function can invoke the + read() method to find out the old value of the + property, if needed. Therefore the old value is not + provided to this function.

      +
      +
      +
      +

      5.11 The ActionHandler + callback

      +

      A function called with a parameters + dictionary argument assembled by the WoT runtime based on the Thing Description and the external client request. + It returns a Promise that rejects with an error or resolves + if the action is successful or ongoing (may also resolve with + a control object such as an Observable for actions that need + progress notifications or that can be canceled).

      +
      +
      +

      5.12 The + setPropertyReadHandler() method

      +

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

      +

      The readHandler callback function will + implement reading a Property and + SHOULD be called by + implementations when a request for reading a Property is received from the underlying + platform.

      +

      There SHOULD be at + most one handler for any given Property and + newly added handlers replace the old handlers. If no handler + is initialized for any given Property, + implementations SHOULD implement a default property read + handler.

      +

      When an external request for reading Property propertyName is received, the + runtime SHOULD + execute the following steps:

      +
        +
      1. Return a Promise promise and + execute the next steps in parallel. +
        2. +
      2. If a Property with + propertyName does not exist, reject promise with a ReferenceError and + terminate these steps. +
        3. +
      3. Otherwise, if no read handler has been defined for + propertyName, resolve promise with + the value of the Property named + propertyName provided by the runtime implementation + and terminate these steps. +
        4. +
      4. Otherwise, invoke the read handler associated with + propertyName. If it rejects, then reject + promise with the same error, and resolve + promise with the same value. +
        5. +
      +
      +
      +

      + 5.13 The + setPropertyWriteHandler() method

      +

      Takes name as string argument and + writeHandler as argument of type PropertyWriteHandler. + Sets the handler function for writing the specified Property matched by name. Throws on + error. Returns a reference to the same object for supporting + chaining.

      +

      There SHOULD be at + most one write handler for any given Property and newly added handlers replace the old + handlers. If no write handler is initialized for any given + Property, implementations SHOULD implement default property update + and notifying observers on change.

      +

      When an external request for writing a Property propertyName with a new value + value is received, the runtime SHOULD execute the following steps:

      +
        +
      1. Return a Promise promise and + execute the next steps in parallel. +
        2. +
      2. If a Property with + propertyName does not exist, reject promise with a ReferenceError and + terminate these steps. +
        3. +
      3. Otherwise, if no write handler has been defined for + propertyName, the runtime implementation + SHOULD update the + Property value with + value, resolve promise and terminate + these steps. +
        4. +
      4. Otherwise, invoke the write handler associated with + propertyName providing value as + argument. If it rejects, then reject promise + with the same error, and resolve promise with + the same value. +
        5. +
      +
      +
      +

      5.14 The + setActionHandler() method

      +

      Takes name as string argument and + action as argument of type ActionHandler. Sets the handler + function for the specified Action matched by + name. Throws on error. Returns a reference to + the same 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 SHOULD be at + most one handler for any given Action and newly added + handlers replace the old handlers.

      +

      When an external request for invoking the Action identified by name is received, + the runtime SHOULD + execute the following steps:

      +
        +
      1. Return a Promise promise and + execute the next steps in parallel. +
        2. +
      2. If an Action identified by + name does not exist, reject promise with a ReferenceError and + terminate these steps. +
        3. +
      3. Otherwise, if no action handler has been defined for + name, reject promise with a + ReferenceError and terminate these steps. +
        4. +
      4. Otherwise, invoke the Action handler + associated with name. If it rejects with + error, then reject promise with the + same error, otherwise if it resolves with + value, then resolve promise with the + same value. +
        5. +
      +
      +
      +

      5.15 + Examples

      +

      Below some ExposedThing interface examples + are given.

      +
      +
      + + Example 5: Create a new + exposed Thing with a simple property +
      + 
      +        try {
+  var temperatureValueDefinition = {
+    type: "number",
+    minimum: -50,
+    maximum: 10000
+  };
+  var temperaturePropertyDefinition = temperatureValueDefinition;
+  // add the 'forms' property
+  temperaturePropertyDefinition.forms = [ ... ];
+  var thing = WoT.produce({
+    name: "tempSensor",
+    properties: {
+      temperature: temperaturePropertyDefinition
+    },
+    actions: {
+      reset: {
+        description: "Reset the temperature sensor",
+        input: {
+          temperature: temperatureValueDefinition
+        },
+        output: null,
+        forms: []
+      },
+    },
+    events: {
+      onchange: temperatureValueDefinition
+    },
+    links: []
+  });
+  await thing.expose();
+  await wot.register("https://mydirectory.org", thing);
+  // define Thing business logic
+  setInterval( async () => {
+    let mock = Math.random()*100;
+    let old = await thing["temperature"].read();
+    if (old < mock) {
+      await thing["temperature"].write(mock);
+      thing.emitEvent("onchange", mock);
+    }
+  }, 1000);
+} catch (err) {
+   console.log("Error creating ExposedThing: " + err);
+}
      +
      +
      +
      + Example + 6: Create a new exposed + Thing with object property +
      + 
      +        try {
+  var 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
+        }
+      }
+  };
+  var statusPropertyDefinition = statusValueDefinition;
+  // add the 'forms' property
+  statusPropertyDefinition["forms"] = [];
+  var thing = WoT.produce({
+    name: "mySensor",
+    properties: {
+      brightness: {
+        type: "number",
+        minimum: 0.0,
+        maximum: 100.0,
+        required: true,
+      },
+      status: statusPropertyDefinition
+    },
+    actions: {
+      status: {
+        description: "Get status object",
+        input: null,
+        output: {
+          status : statusValueDefinition;
+        },
+        forms: []
+      },
+    },
+    events: {
+      onstatuschange: statusValueDefinition;
+    },
+    links: []
+  });
+  thing.expose().then(() => {
+      thing.register();
+  });
+} catch (err) {
+   console.log("Error creating ExposedThing: " + err);
+}
      +
      +
      +
      + + Example 7: Create a new + exposed Thing from a Thing Description +
      + 
      +        let thingDescription = '{ \
+  "name": "mySensor", \
+  "@context": [ "http://www.w3.org/ns/td",\
+     "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ],\
+  "@type": [ "Thing", "Sensor" ], \
+  "geo:location": "testspace", \
+  "properties": { \
+    "prop1": { \
+      "type": "number",\
+      "@type": [ "Property", "Temperature" ], \
+      "saref:TemperatureUnit": "degree_Celsius" \
+  } } }';
+try {
+  // note that produce() fails if thingDescription contains error
+  let thing = WoT.produce(thingDescription);
+  // Interactions were added from TD
+  // WoT adds generic handler for reading any property
+  // define a specific handler for one property
+  let name = "examplePropertyName";
+  thing.setPropertyReadHandler(name, () => {
+    console.log("Handling read request for " + name);
+    return new Promise((resolve, reject) => {
+        let examplePropertyValue = 5;
+        resolve(examplePropertyValue);
+      },
+      e => {
+        console.log("Error");
+      });
+  });
+  thing.expose();
+} catch(err) {
+   console.log("Error creating ExposedThing: " + err);
+}
      +
      +
      +
      + Example + 8: Create a new exposed + Thing from a TD URI +
      + 
      +        // fetch an external TD, e.g., to set up a proxy for that Thing
+WoT.fetch("http://myservice.org/mySensor/description").then(td => {
+  // WoT.produce() ignores instance-specific metadata (security, form)
+  let thing = WoT.produce(td);
+  // Interactions were added from TD
+  // add server functionality
+  // ...
+});
      +
      +
      +
      +
      + +

      6. Data types and structures

      +

      The [WOT-TD] specification defines the + + WoT information model, i.e. the data types and data + structures used in WoT Interactions. In + this API these definitions translate to dictionary objects that + are extended with methods by the interfaces defined in this + specification.

      +

      In order to avoid duplication of definitions, references to + these data types and structures is defined in this section, but + for their full description please refer to the Thing + Description specification.

      +
      +

      + 6.1 The DataSchema + dictionary and its subclasses

      +

      Value types basically represent types that may be used in + JSON object definitions and are used in ThingFragment to define Properties, Events and Action parameters. Value types are represented as + dictionary objects whose properties and possible sub-classes + are defined in the + DataSchema section of [WOT-TD].

      +

      One property of all DataSchema dictionary is the + type property whose value is from a set of + enumerated strings defined in the DataSchema + section of [WOT-TD] and is referred as + DataType in + this specification.

      +

      Based on type, the following sub-classes of + DataSchema are defined in + [WOT-TD]: BooleanSchema, NumberSchema, IntegerSchema, StringSchema, ObjectSchema, ArraySchema.

      +
      +
      +

      + 6.2 The SecurityScheme dictionary + and its subclasses

      +

      Security metadata is represented as dictionary objects + whose properties and sub-classes are defined in the + SecurityScheme section of [WOT-TD].

      +

      One property of the SecurityScheme dictionary is the + scheme property whose value is from a set of + enumerated strings defined in the + SecurityScheme section of [WOT-TD]. Based on type, + multiple subclasses of SecurityScheme are defined.

      +
      + +
      +

      6.4 The Form dictionary

      +

      Represents metadata describing service details, with + properties defined in the Form + section of [WOT-TD].

      +
      +
      +

      6.5 The InteractionFragment + dictionary

      +

      Represents the common properties of WoT Interactions, one of Property, + Action or Event, as defined in the + InteractionPattern section of [WOT-TD]. Its subclasses are + referred as PropertyFragment, ActionFragment and EventFragment.

      +
      +
      +

      6.6 The PropertyFragment + dictionary

      +

      Represents the Property interaction + data that initializes a ThingProperty object. Its properties + are defined in the Property + and + InteractionPattern sections of [WOT-TD].

      +
      +
      +

      6.7 The ActionFragment + dictionary

      +

      Represents the Action interaction data that + initializes a ThingAction object. Its + properties are defined in the Action + and + InteractionPattern sections of [WOT-TD].

      +
      +
      +

      6.8 The EventFragment + dictionary

      +

      Represents the Event interaction data that + initializes a ThingEvent object. Its + properties are defined in the Event + section of [WOT-TD].

      +
      +
      +

      6.9 The ThingFragment + dictionary

      +

      The ThingFragment + dictionary is defined as Thing + in [WOT-TD]. It is a dictionary that + contains properties representing semantic metadata and + interactions (Properties, Actions and + Events). It is used for initializing an internal + representation of a Thing Description and + its properties may be used in ThingFilter.

      +
      +
      +

      6.10 The ThingDescription + type

      +

      Serialized representation of the Thing Description (a JSON-LD document).

      +
      +
      + Note +
      +

      In this version of the API, Thing Descriptions are represented + as an opaque USVString that can be transmitted + between devices.

      +
      +
      +
      +
      + +

      7. Interfaces for WoT Interactions

      +

      The data types and structures imported from [WOT-TD] are extended by + this specification in order to provide the interfaces for + WoT Interactions.

      +

      Every Thing describes its metadata as + defined in ThingFragment, and basic + interactions defined as Properties, Actions and Events. The following interfaces are + used for representing these interactions.

      +
      +

      7.1 The Interaction + interface

      +

      The Interaction interface + is an abstract class to represent Thing + interactions: Properties, Actions and + Events.

      +

      The InteractionFragment + dictionary holds the common properties of PropertyFragment, ActionFragment and EventFragment dictionaries used for + initializing ThingProperty, ThingAction and ThingEvent objects in a ThingFragment dictionary used for + creating an ExposedThing + object.

      +
      + 
      interface Interaction {
+  readonly attribute (Form or FrozenArray<Form>) forms;
+};
+Interaction includes InteractionFragment;
      +
      +

      The forms read-only + property represents the protocol bindings initialization data + and is initialized by the WoT Runtime.

      +
      +
      +

      7.2 The ThingProperty + interface

      +

      The ThingProperty interface + is used in ConsumedThing and + ExposedThing objects to + represent Thing Property + interactions.

      +

      The PropertyFragment + dictionary is used for initializing Property objects + in a ThingFragment + dictionary used for creating an ExposedThing object. It MUST implement one of the + DataSchema dictionaries.

      +
      + 
      interface ThingProperty : Interaction {
+  // getter for PropertyFragment properties
+  getter any (DOMString name);
+  // get and set interface for the Property
+  Promise<any> read();
+  Promise<void> write(any value);
+};
+ThingProperty includes PropertyFragment;
+ThingProperty includes Observable;
      +
      +

      The ThingProperty interface + contains all the properties defined on PropertyFragment as read-only + properties.

      +

      The type + read-only property represents the type definition for the + Property as a DataSchema dictionary object.

      +

      The writable read-only property tells + whether the Property value can be updated. If it + is false, then the set(value) + method SHOULD always + reject.

      +

      The observable read-only + property tells whether the Property supports + subscribing to value change notifications. If it is + false, then the subscribe() method + SHOULD always + fail.

      +

      The constant read-only property + - defined in DataSchema - tells + whether the Property value is a constant. If + true, the set() and + subscribe() methods SHOULD always fail.

      +

      The required read-only property + - defined in DataSchema - tells + whether the Property should be always present on + the ExposedThing + object.

      +

      The read() + method will fetch the value of the Property. + Returns a Promise that resolves with the + value, or rejects with an error.

      +

      The + write() method will attempt to set the value of + the Propertyspecified in the + value argument whose type SHOULD match the one specified by the + type property. Returns a Promise that + resolves on success, or rejects on an error.

      +
      +
      +

      7.3 The ThingAction + interface

      +
      + 
      interface ThingAction : Interaction {
+  Promise<any> invoke(optional any inputValue);
+};
+ThingAction includes ActionFragment;
      +
      +

      The + invoke() method when invoked, starts the + Action interaction with the input value provided by + the inputValue argument. If inputValue + is null, the action does not take any arguments + and rejects if any arguments are provided. If the value is + undefined, the action will ignore any arguments + provided. Otherwise the type of inputValue + SHOULD match the + DataSchema definition in the + input property. Returns a Promise that + will reject with an error or will resolve with a value of + type defined by the output property.

      +
      +
      +

      7.4 The ThingEvent interface

      +
      + 
      interface ThingEvent : Interaction {
+};
+ThingEvent includes EventFragment;
+ThingEvent includes ThingProperty;
      +
      +

      Since ThingEvent implements + Observable through the ThingProperty interface, event + subscription is done by invoking the subscribe() + method on the event object that returns a cancelable Subscription.

      +
      +
      +

      7.5 The ExposedEvent + interface

      +
      + 
      interface ExposedEvent : ThingEvent {
+  void emit(any payload);
+};
      +
      +
      +

      7.5.1 The emit() + method

      +

      Emits an event that carries data specified by the + payload argument.

      +
      +
      +
      +

      7.6 The value-matching + algorithm

      +

      The value-matching algorithm is applied to a + value input in relation to a valueType + property of type DataSchema, for instance the + value and type properties of a + PropertyFragment + object, or the inputValue parameter to the + invoke() method of a ThingAction object in relation to the + same object. It executes the following steps:

      +
        +
      1. If valueType.type is not defined, or does + not fully match a string enumerated in DataType, return false. +
        2. +
      2. Otherwise, if valueType.type is + "null": if value is + null, return true, otherwise + return false.
        3. +
      3. Otherwise, if valueType.type is + "boolean": if value is either + true or false, then return + true, otherwise return + false.
        4. +
      4. Otherwise, if valueType.type is + "integer": if value is not an + integer type defined by the underlying platform (such as + long or long long), then return + false, otherwise execute the following + sub-steps: +
          +
        1. If valueType.minimum is defined and + value is not greater or equal than that + value, return false.
          2. +
        2. If valueType.maximum is defined and + value is not less or equal than that value, + return false.
          3. +
        3. Return true.
          4. +
        +
        5. +
      5. Otherwise, if valueType.type is + "number", if value is not an + integer or floating point type defined by the underlying + platform (such as long or long + long or double), then return + false, otherwise otherwise execute the + following sub-steps: +
          +
        1. If valueType.minimum is defined and + value is not greater or equal than that + value, return false.
          2. +
        2. If valueType.maximum is defined and + value is not less or equal than that value, + return false.
          3. +
        3. Return true.
          4. +
        +
        6. +
      6. Otherwise, if valueType.type is + "string": if value is not a string + type defined by the underlying platform, then return + false, otherwise return true. In this + case the algorithm expects a third parameter + valueType.enum and runs the following + sub-steps: +
          +
        • If valueType.enum is an array of + strings, then if value fully matches one of + the strings defined in the array, return + true.
          • +
        • Otherwise, return false.
          • +
        +
        7. +
      7. Otherwise, if valueType.type is + "array", execute the following sub-steps: +
          +
        1. If value is not an array, return + false.
          2. +
        2. If valueType.minItems is defined, and + value does not contain at least + valueType.minItems elements, return + false.
          3. +
        3. If valueType.maxItems is defined, and + value contains more than + valueType.maxItems elements, return + false.
          4. +
        4. Otherwise, if valueType.items is + undefined, return false.
          5. +
        5. Otherwise, if valueType.items is + null, return true (i.e. any + type is accepted as array element, including + heterogenous arrays).
          6. +
        6. Otherwise, for each element of the array + value run the value-matching algorithm + against the valueType.items object. If any + of these runs returns false, then return + false. +
          7. +
        7. Otherwise, return true.
          8. +
        +
        8. +
      8. Otherwise, if type is "object", + execute the following sub-steps: +
          +
        1. If value is not an Object, + return false.
          2. +
        2. If valueType.properties is not defined, + return false.
          3. +
        3. If valueType.properties is + null, return true (i.e. + accept any object value).
          4. +
        4. For each string in the + valueType.required array, if it does not + match a property name in the + value.properties object or in the + value object, then return + false.
          5. +
        5. For each property with name propName and + value propDataSchema found in + valueType.properties, run the following + sub-steps: +
            +
          1. If the result of applying the value-matching algorithm + on the value value[propName] and + propDataSchema is false, + then return false. +
            2. +
          +
          6. +
        6. Return true.
          7. +
        +
        9. +
      +
      +
      +
      + +

      8. + Observables

      +

      This section is non-normative.

      +

      Observables are proposed to + be included in ECMAScript and are used for handling pushed data + associated with various possible sources, for instance events, + timers, streams, etc. A minimal required implementation is + described here.

      +
      +
      + Editor's note +
      +

      This section is informal and contains rather + laconic information for implementations on what to support + for interoperability.

      +
      +
      + 
      interface Observable {
+  Subscription subscribe(EventHandler handler,
+                         optional ErrorHandler errorHandler,
+                         optional OnComplete onComplete);
+};
+interface Subscription {
+  void unsubscribe();
+  readonly attribute boolean closed;
+};
+callback EventHandler = void (any value);
+callback ErrorHandler = void (Error error);
+callback OnComplete = void ();
      +
      +

      The following callbacks can be provided when subscribing to + an Observable:

      +
        +
      • The EventHandler callback takes + the next sample for the data in the value + argument.
        • +
      • The ErrorHandler callback takes + an error in the value argument. It is called + when an error occured in producing the data the client should + know about.
        • +
      • The OnComplete callback is called + when the data source has finished sending values.
        • +
      +
      +

      8.1 The Subscription + interface

      +

      Contains the closed + property of type boolean that tells if the + subscription is closed or active.

      +

      Also, contains the unsubscribe() + method that cancels the subscription, i.e. makes a request to + the underlying platform to stop receiving data from the + source, and sets the closed property to + false.

      +
      +
      +

      8.2 The Observable interface

      +

      The Observable interface + enabled subscribing to pushed data notifications by the + subscribe() + method:

      +
        +
      • Initialize the data handler callback with the first + function argument.
        • +
      • If the next argument is provided and is a function, + initialize the error handling callback with that function, + or throw on error.
        • +
      • If the third argument is provided and is a function, + initialize the completion handler with that function, or + throw on error.
        • +
      • After callback initializations, the implementation + should request the underlying platform to provide data, + error and completion notifications for the supported data + source.
        • +
      +
      +
      +
      + +

      9. Security and + Privacy

      +

      In general the security measures taken to protect a WoT + system will depend on the threats and attackers that system may + face and the value of the assets needs to protect. A detailed + discussion of security and privacy considerations for the Web + of Things, including a threat model that can be adapted to + various circumstances, is presented in the informative document + [WOT-SECURITY-CONSIDERATIONS]. + This section includes only normative recommendations relevant + to the WoT Thing Description.

      +

      When designing new devices and services + for use with the WoT, we have documented a set of best + practices in [WOT-SECURITY-BEST-PRACTICES] + that SHOULD be + followed. This best-practices document may be updated as + security measures evolve. Following these practices does not + guarantee security, but it at least will help to avoid common + known vulnerabilities and pitfalls.

      +

      Below are specific recommendations related to WoT runtime + implementations:

      +
        +
      • In basic WoT setups, all scripts running inside the WoT + runtime are considered trusted, and therefore there is no + strong need to perform strict isolation between each running + script instance. However, depending on device capabilities + and deployment use case scenario risk level it might be + desirable to do so. +
          +
        • For example, if one script handles sensitive + privacy-related data and well-audited, it might be + desirable to separate it from the rest of the script + instances to minimize the risk of data exposure in case + some other script inside WoT gets compromised during the + runtime. Therefore the WoT + runtime SHOULD + perform isolation of script instances and their data in + cases when scripts handle privacy-related or other + critical security data.
          • +
        • Another example is mutual co-existence of different + tenants on a single WoT device. In this case each WoT + runtime instance will be hosting a different tenant, and + isolation between them is required. Therefore the WoT + runtime SHOULD + perform isolation of WoT runtime instances and their data + if a WoT device has more than one tenant.
          • +
        Such isolation can be performed within the WoT Runtime + using platform security mechanisms available on the device. + For more information see Section "WoT Servient + Single-Tenant" and "WoT Servient Multi-Tenant" of + [WOT-SECURITY-CONSIDERATIONS]. +
        • +
      • WoT scripts are using WoT Scripting API to implement the + functionality and logic for WoT Things. In addition to + providing the isolation between script and runtime instances, + the WoT runtime needs to protect the underlying physical + device from potentially misbehaving WoT scripts. Therefore the + WoT Runtime SHOULD + avoid directly exposing the native device interfaces to the + script developers. Instead a WoT Runtime should + provide a hardware abstraction layer for accessing the native + device interfaces. Additionally, in order to reduce the + damage to a physical WoT device in cases a WoT script gets + compromised, it is important to minimize the number of + interfaces that are exposed or accessible to a particular WoT + script based on its functionality. Therefore the WoT Runtime + SHOULD only expose a + minimal set of interfaces to a WoT script based on its + intended functionality.
        • +
      • If the WoT runtime supports post-manufacturing + provisioning or update of WoT scripts, WoT runtime or any + related data (including security credentials), it can be a + major attack vector. An attacker can try to modify any above + described part during the update or provisioning process or + simply provision attacker's code and data directly. + Therefore, if WoT Runtime supports + post-manufacturing provisioning or update of WoT scripts, WoT + runtime or any related data, such operations SHOULD be done in a secure + fashion. A set of recommendations for secure update + and post-manufacturing provisioning can be found in + [WOT-SECURITY-BEST-PRACTICES].
        • +
      • Typically the WoT runtime needs to store the security + credentials that are provisioned to a WoT device to operate + in WoT network. The confidentiality or integrity of these + credentials should not be compromised. Therefore the + WoT runtime SHOULD + securely store the provisioned security credentials, + guaranteeing their integrity and confidentiality. + In + case there are more than one tenant on a single WoT-enabled + device, a WoT Runtime SHOULD guarantee isolation of each tenant + provisioned security credentials. Additionally, in + order to minimize a risk that provisioned security + credentials get compromised, the WoT runtime should not have + any way for WoT scripts to query these credentials. + Therefore, the WoT Runtime SHOULD NOT expose any API + for WoT scripts to query the provisioned security + credentials.
        • +
      +

      Some additional specific recommendations relevant for WoT + script developers:

      +
        +
      • A typical way to compromise any process is to send it a + corrupted input via one of the exposed interfaces. + Therefore developers SHOULD perform validation on + all WoT script inputs, including fuzzing. + There are many tool and techniques in existence to do such + validation. More details can be found in [WOT-SECURITY-TESTING].
        • +
      • As any software, complex scripts with a lot of + functionality presents a higher risk of development mistakes. + Such scripts are also hard to verify and test appropriately. + Therefore developers SHOUD + minimize the functionality and complexity of WoT + scripts.
        • +
      • If a WoT script performs a heavy functional processing on + received requests before the request is authenticated, it + presents a great risk for Denial-Of-Service (DOS) attacks. + Therefore WoT scripts SHOULD avoid heavy functional processing + without prior successful authentication of requestor. + The set of recommended authentication mechanisms can be found + in [WOT-SECURITY-BEST-PRACTICES].
        • +
      • WoT developers should remember that a content of a TD can + change, including its identified, id, which is not an + immutable identifier. Therefore WoT scripts SHOULD use the provided WoT script API to + subscribe for notifications on TD changes.
        • +
      +
      +
      + +

      10. Terminology and conventions

      +

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

      +

      JSON-LD is + defined in [JSON-LD] as a JSON document that is + augmented with support for Linked Data.

      +

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

      +

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

      +

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

      +

      The term + secure + context is defined in [WEBAPPSEC].

      +

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

      +

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

      +

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

      +

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

      +

      The terms hyperlink reference and + relation + type are defined in [HTML5] and RFC8288.

      +
      +
      + +

      11. + Conformance

      +

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

      +

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

      +

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

      +

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

      +

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

      +

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

      +

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

      +

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

      +
      +
      + +

      A. + Changes

      +

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

      + +
      +
      + +

      B. Open issues

      +

      The following problems are being discussed and need most + attention:

      +
        +
      • Security related metadata + (https://github.com/w3c/wot-scripting-api/issues/91).
        • +
      • Providing Protocol Binding for + ExposedThing + (https://github.com/w3c/wot-scripting-api/issues/45). +
        • +
      • Script management and runtime related issues + (https://github.com/w3c/wot-scripting-api/issues/)
        • +
      +
      +
      + +

      C. + Acknowledgements

      +

      Special thanks to former editor Johannes Hund (until August + 2017, when at Siemens AG) for developing this specification. + Also, the editors would like to thank Dave Raggett, Matthias + Kovatsch, Michael Koster and Michael McCool for their comments + and guidance.

      +
      +
      + +

      D. + References

      +
      +

      D.1 Normative references

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

      D.2 Informative references

      +
      +
      [HTML]
      +
      + HTML + Standard. Anne van Kesteren; Domenic Denicola; + Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. + Living Standard. URL: https://html.spec.whatwg.org/multipage/ +
      +
      +
      +
      + + + + diff --git a/diff.html b/diff.html new file mode 100644 index 00000000..2cde3a44 --- /dev/null +++ b/diff.html @@ -0,0 +1,19177 @@ + + + + + + + + + + + + +Web of Things (WoT) Scripting API + + + + + + + + + + + +
      + +

      +Web +of +Things +(WoT) +Scripting +API +

      +

      + +W3C + +Working +Draft +5 +April + + +

      +
      +
      +This +version: +
      +
      +https://www.w3.org/TR/2018/WD-wot-scripting-api-20180405/ + + +https://www.w3.org/TR/2018/WD-wot-scripting-api-20181021/ + + +
      +
      +Latest +published +version: +
      +
      + +https://www.w3.org/TR/wot-scripting-api/ + +
      +
      +Latest +editor's +draft: +
      +
      + +https://w3c.github.io/wot-scripting-api/ + +
      +
      +Previous +version: +
      +
      +https://www.w3.org/TR/2017/WD-wot-scripting-api-20170914/ + + +https://www.w3.org/TR/2018/WD-wot-scripting-api-20180405/ + + +
      +
      +Editors: +
      +
      + +Zoltan +Kis + +( + +Intel + +) +
      +
      + +Kazuaki +Nimura + +( + +Fujitsu +Ltd. + +) +
      +
      + +Daniel +Peintner + +( + +Siemens +AG + +) +
      +
      + +Johannes +Hund + +(Former +Editor, +when +at +Siemens +AG) +
      +
      +Contributors: +
      +
      + +In +the +GitHub +repository + +
      +
      +Repository: +
      +
      + +We +are +on +GitHub + +
      +
      + +File +a +bug + +
      +
      +

      + +Copyright + +© +2017-2018 + + +W3C + + + +® + +( + + +MIT + +, + + +ERCIM + +, + +Keio +, + +Beihang + +). + +W3C + + +liability +, + +trademark + +and + +permissive +document +license + +rules +apply. +

      +
      +
      +
      +

      +Abstract +

      +

      +The +overall + + +Web +of +Things + +(WoT) +provides +layered +interoperability +between + +concepts +are +described +in +the + +WoT +Architecture + +document. +The +Web +of + +Things +is +made +of +entities +( + +Thing + + +by +using + +s) +that +can +describe +their +capabilities +in +a +machine-interpretable +format, +the + +Thing +Description + +(TD) +and +expose +these +capabilities +through + +the + +WoT +Interface +, +that +is, +network +interactions +modeled +as + +Properties + + +s. + +for +reading +and +writing +values, + +Action + +s +to +execute +remote +procedures +with +or +without +return +values +and + +Event + +s +for +signaling +notifications. + +

      +

      +This +specification +describes +a +programming +interface +representing +the + +WoT +Interface + +that +allows +scripts +run +on +a + +Thing + +to +discover +and +consume +(retrieve) +other + +Thing +Description + + +s +and +to +expose + +Things + +characterized +by + +WoT +Interactions +, +i.e. +Properties +, +Actions + + +and +Events +. + +specified +by +a +script. + +

      +

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

      +
      +
      +

      +Status +of +This +Document +

      +

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

      +

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

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

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

      +
      +

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

      +

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

      +

      +Changes +from +the +previous +publication +can +be +found +in + +Appendix +A + +B + +. +A + +diff-marked +version + +of +this +document +is +also +available +for +comparison +purposes. +

      +

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

      +

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

      +

      +This +document +is +governed +by +the + +1 +February +2018 + +W3C + +Process +Document +. +

      +
      + +
      +

      + +1. + +Introduction + + +

      +

      +The +overall + +WoT +concepts +are +described +in +the +WoT +Architecture +document. +The +Web +of +Things +is +made +of +entities +( +Thing +s) +that +can +describe +their +capabilities +in +a +machine-interpretable +format, +the + +provides +layered +interoperability +based +on +how + +Thing +Description + + +(TD) + +s +are +modeled: +as +being +"consumed" + +and +expose +these +capabilities +through +the +WoT +Interface +. +Support +for +scripting +is +optional +for +WoT +devices. + +"exposed". + +

      +

      +By + +consuming +a +TD +, +a +client + +Thing + +creates +a +runtime +resource +model +that +allows +accessing +the + +Properties +, + +Actions + +and + +Events + +exposed +by +the +server + +Thing +. + + +exposed +on +a +remote +device. + +

      +

      +Exposing +a + +Thing + +requires +defining +a + +Thing +Description + +(TD) +and +instantiating +a +software +stack +needed + +to +serve +requests +for +accessing +the +exposed + +Properties +, + +Actions + +and + +Events +. +This +specification +describes +how +to +expose +and +consume + +Thing + +s +by +a +script. +

      +
      +
      + +Note + +
      +

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

      +
      +
      +
      + +Note + +
      +

      +This +specification +does +not +make +assumptions +on +how +the + +WoT +Runtime + +handles +and +runs +scripts, +including +single +or +multiple +tenancy, +script +deployment +and +lifecycle +management. +The +API +already +supports +the +generic +mechanisms +that +make +it +possible +to +implement +script +management, +for +instance +by +exposing +a +manager + +Thing + +whose + +Actions + +(action +handlers) +implement +script +lifecycle +management +operations. +

      +
      +

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

      +
      +
      +

      + +2. + +Use +Cases + + +

      +

      + +This +section +is +non-normative. + +

      +

      +The +following +scripting +use +cases +are +supported +in +this +specification: +

      +
      +

      + +2.1 + +Discovery + + +

      +
        +
      • +Discover +all + +Thing + +s +in +the +WoT +network +by +sending +a +broadcast +request. +
        • +
      • +Discover + +Thing + +s +running +in +the +local + +WoT +Runtime +. +
        • +
      • +Discover +nearby + +Thing + +s, +for +instance +connected + +by +NFC +or +Bluetooth. +
        • +
      • +Discover + +Thing + +s +by +sending +a +discovery +request +to +a +given +registry. +
        • +
      • +Discover + +Thing + +s +by +filters +defined +on + +Thing +Description + +s +
        • +
      • +Discover + +Thing + +s +by +semantic +filters. + +queries. + +
        • +
      • +Stop +or +suppress +an +ongoing +discovery +process. +
        • +
      • +Optionally +specify +a +timeout +to +the +discovery +process +after +which +it +is +stopped/suppressed. +
        • +
      +
      +
      +

      + +2.2 + +Consuming +a +Thing + + +

      + +
      +
      +

      + +2.3 + +Exposing +a +Thing + + +

      +
        +
      • +Exposing +the + +Thing + +includes +generating +the +protocol +bindings +in +order +to +access +lower +level +functionality. +
        • +
      • +Create +a +local + + +ExposedThing + + +to +be +exposed, +based +on +a + +Thing +Description + +provided +in +string +serialized +format, +or +out +of +a +template +or +an +existing + + +ConsumedThing + + +object. +
        • +
      • +Add +a + +Property + +definition +to +the + +Thing +. +
        • +
      • +Add +an + +Action + +definition +to +the + +Thing +. +
        • +
      • +Add +an + +Event + +definition +to +the + +Thing +. +
        • +
      • +Attach +semantic +information +to +the + +Thing +. +
        • +
      • +Attach +semantic +information +to +a + +Property +. +
        • +
      • +Attach +semantic +information +to +an + +Action +. +
        • +
      • +Attach +semantic +information +to +an + +Event +. +
        • +
      • +Emit +an + +Event +, +i.e. +notify +all +listeners +subscribed +to +that + +Event +. +
        • +
      • +Provide +notifications +for + +TD + +changes +to +clients +subscribed +to +that. +
        • +
      • +Mark/unmark +the +Thing +to +be +discoverable. +
        • +
      • +Mark/unmark +the +Thing +to +be +consumable. +
        • +
      • +Start +the +exposed + +Thing + +in +order +to +process +external +requests. +
        • +
      • +Stop +the +exposed + +Thing +. +
        • +
      • +Register +handlers +for +external +requests: +
          +
        • +to +retrieve +a + +Property + +value; +
          • +
        • +to +update +a + +Property + +value; +
          • +
        • +to +run +an + +Action +: +take +the +parameters +from +the +request, +execute +the +defined +action, +and +return +the +result; +
          • +
        +
        • +
      +
      +
      +
      +

      + +3. + +The + + +WoT + + +object + + +

      +

      +The +WoT +object +is +the +API +entry +point +and +it +is +exposed +by +an +implementation +of +the + +WoT +Runtime +. +The + +WoT +object + +does +not +expose +properties, +only +methods +for +discovering, +consuming +and +exposing +a + +Thing +. +

      +
      +
      + +Note + +
      +

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

      +
      +
      +
      data-idl="" data-title="WoT">interface <span class=
+"idlInterfaceID"><a data-no-default="" data-link-for="" data-lt=""
+href="#dom-wot" class="internalDFN" data-link-type=
+"dfn"> {
+<span class="idlMethod" id="idl-def-wot-discover-filter" data-idl=
+"" data-title="discover" data-dfn-for="wot">    <span class=
+"idlMethType"><a href="#dom-observable" class="internalDFN"
+data-link-type="dfn"><<a href=
+"#dom-consumedthing" class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlMethName"><a data-no-default="" data-link-for="wot" data-lt=
+"discover()|discover" href="#dom-wot-discover" class="internalDFN"
+data-link-type="dfn">discover(<span class=
+"idlParam">optional <a href=
+"#dom-thingfilter" class="internalDFN" data-link-type=
+
+data-idl="" data-title="WoT">// [SecureContext]
+// [NamespaceObject]
+interface 
+data-link-for="" data-lt="" href="#dom-wot" class="internalDFN"
+data-link-type="dfn">WoT {
+  
+data-link-type=
+"dfn">Observable discover(optional 
+"dfn">ThingFilter "idlParamName">filter
+<span class="idlMethod" id="idl-def-wot-fetch-url" data-idl=""
+data-title="fetch" data-dfn-for="wot">    <span class=
+"idlMethType"><a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<<a href="#dom-thingdescription"
+class="internalDFN" data-link-type=
+
+"idlParamName">filter);
+  
+"https://heycam.github.io/webidl/#idl-promise">Promise<
+"dfn">ThingDescription> "fetch()|fetch" href="#dom-wot-fetch" class="internalDFN"
+data-link-type="dfn">fetch(<span class=
+
+"wot.fetch()|wot.fetch|fetch()|fetch" href="#dom-wot-fetch" class=
+"internalDFN" data-link-type=
+"dfn">fetch(
+"idlParam">"https://heycam.github.io/webidl/#idl-USVString">USVString
+<span class="idlMethod" id="idl-def-wot-consume-td" data-idl=""
+data-title="consume" data-dfn-for="wot">    <span class=
+"idlMethType"><a href="#dom-consumedthing" class="internalDFN"
+
+"https://heycam.github.io/webidl/#idl-USVString">USVString url);
+  "dfn"><a data-no-default=""
+data-link-for="wot" data-lt="consume()|consume" href=
+
+"dfn">ConsumedThing 
+"#dom-wot-consume" class="internalDFN" data-link-type=
+"dfn">consume<span class=
+"idlParamType"><a href="#dom-thingdescription" class="internalDFN"
+data-link-type=
+
+"dfn">consume(
+"dfn">ThingDescription "idlParamName">td
+<span class="idlMethod" id="idl-def-wot-produce-model" data-idl=""
+data-title="produce" data-dfn-for="wot">    <span class=
+"idlMethType"><a href="#dom-exposedthing" class="internalDFN"
+
+"idlParamName">td);
+  "dfn"><a data-no-default=""
+data-link-for="wot" data-lt="produce()|produce" href=
+"#dom-wot-produce" class="internalDFN" data-link-type=
+"dfn">produce<span class=
+"idlParamType"><a href="#dom-thingmodel" class="internalDFN"
+
+"dfn">ExposedThing produce(ThingModel model);
+  
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> register(USVString directory, ExposedThing thing);
+  
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> unregister(USVString directory, ExposedThing thing);
+};
+typedef object ThingFragment;
+typedef object PropertyFragment;
+typedef object ActionFragment;
+typedef object EventFragment;
+typedef object DataSchema;
+typedef object SecurityScheme;
+typedef object 
+data-link-type=
+"dfn">
+};
+<span class="idlTypedef" id="idl-def-thingdescription" data-idl=""
+data-title="ThingDescription">typedef <span class=
+"idlTypedefType"><a href=
+
+"dfn">Link;
+typedef object Form;
+typedef 
+"https://heycam.github.io/webidl/#idl-USVString">USVString "dfn">
+<span class="idlTypedef" id="idl-def-thingmodel" data-idl=""
+data-title="ThingModel">typedef <span class=
+"idlTypedefType">(<a href="#dom-thingtemplate" class="internalDFN"
+data-link-type="dfn"> or <a href=
+
+"dfn">ThingDescription;
+typedef (ThingFragment or 
+"#dom-thingdescription" class="internalDFN" data-link-type=
+"dfn">ThingDescription) 
+
+ThingModel
+
+
+
+;
+
+
      +
      +
      +
      + +Editor's +note + +
      +

      +The +algorithms +for +the +WoT +methods +will +be +specified +later, +including +error +handling +and +security +considerations. +

      +
      +

      +The + +ThingModel + +type +represents +either +a + +ThingFragment +, +or +a + +ThingDescription +.

      +
      +

      + +3.1 + +The + + +discover() + + +method + + +

      +

      +Starts +the +discovery +process +that +will +provide + + +ConsumedThing + +ThingDescription + + + +objects + +s + +that +match +the +optional +argument + +filter + +of +type + + + + +ThingFilter + + +. +When +the +argument +is +not +provided, +starts +the +widest +discovery +the +Thing +Description +and +Protocol +Bindings +allow +and +support. + +Returns +an +[ + + +Observable + +](https://github.com/tc39/proposal-observable) + +object +that +can +be +subscribed +to +and +unsubscribed +from. +The +handler +function +provided +to +the +Observable +during +subscription +will +receive +an +argument +of +type + +USVString + +representing +a + +ThingDescription +. +

      +
      +

      + +3.1.1 + +The + + +DiscoveryMethod + + +enumeration + + +

      +
      +
      "DiscoveryMethod">typedef <a href=
+
+"DiscoveryMethod">typedef 
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString 
+
+DiscoveryMethod
+
+
+
+;
+
+
      +
      +

      + + +DiscoveryMethod + + +represents +the +discovery +type +to +be +used: +

      + +
      +
      +

      + +3.1.2 + +The + + +ThingFilter + + +dictionary + + +

      +

      +The + + +ThingFilter + + +dictionary +that +represents +the +constraints +for +discovering + +Thing + +s +as +key-value +pairs. +

      +
      +
      dictionary "dfn"> {
+<span class="idlMember" id="idl-def-thingfilter-method" data-idl=""
+data-title="method" data-dfn-for="thingfilter">    <span class=
+"idlMemberType"><a href="#dom-discoverymethod" class="internalDFN"
+data-link-type=
+"dfn">      <span class=
+"idlMemberName"><a data-no-default="" data-link-for="thingfilter"
+data-lt="" href="#dom-thingfilter-method" class="internalDFN"
+data-link-type="dfn"> = <span class=
+"idlMemberValue">"any"
+<span class="idlMember" id="idl-def-thingfilter-url" data-idl=""
+data-title="url" data-dfn-for="thingfilter">    <span class=
+"idlMemberType"><a href=
+"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default=""
+
+"dfn">ThingFilter {
+  (DiscoveryMethod or DOMString) method = "any";
+  
+"https://heycam.github.io/webidl/#idl-USVString">USVString? 
+data-link-for="thingfilter" data-lt="" href="#dom-thingfilter-url"
+class="internalDFN" data-link-type=
+"dfn">
+<span class="idlMember" id="idl-def-thingfilter-query" data-idl=""
+data-title="query" data-dfn-for="thingfilter">    <span class=
+"idlMemberType"><a href=
+"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default=""
+
+"dfn">url;
+  
+"https://heycam.github.io/webidl/#idl-USVString">USVString? 
+data-link-for="thingfilter" data-lt="" href=
+"#dom-thingfilter-query" class="internalDFN" data-link-type=
+"dfn">
+<span class="idlMember" id="idl-def-thingfilter-constraints"
+data-idl="" data-title="constraints" data-dfn-for=
+"thingfilter">    <a href=
+"https://heycam.github.io/webidl/#idl-sequence">sequence<a data-no-default=""
+data-link-for="thingfilter" data-lt="" href=
+"#dom-thingfilter-constraints" class="internalDFN" data-link-type=
+"dfn">
+
+"dfn">query;
+  
+data-link-type=
+"dfn">ThingFragment? fragment;
+
+};
+
+
      +
      +

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

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

      +The + + +url + + +property +represents +additional +information +for +the +discovery +method, +such +as +the +URL +of +the +target +entity +serving +the +discovery +request, +such +as + +for +instance + +a + +Thing +Directory + +(if + +method + +is + +"directory" + +) + +or +a +Thing. + +Thing +(otherwise). + +

      +

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

      +

      +The + + +constraints + +fragment + + + +property +represents +additional +information + +a + +ThingFragment + +dictionary +used + +for +the +discovery + +matching +property +by +property +against +discovered + +Thing + +s. +

      +The + +discover(filter) + +method +in + + +MUST + +run + +the +form +of +a +list +of +sets +of +property-value +pairs +(dictionaries). +The +list +elements +(dictionaries) +are +in +OR +relationship, + +following +steps: +

      1. +If +invoking + +discover() + +is +not +allowed +for +the +current +scripting +context +for +security +reasons, +throw + +SecurityError + +and +within +a +constraint +dictionary + +terminate +these +steps. +
      2. +Return +an + +Observable + +obs + +and +execute + +the +key-value +pairs +are + +next +steps + +in +AND +relationship. +Implementations +SHOULD +make + +parallel +.
      3. +If + +obs.subscribe(handler, +errorHandler, +complete) + +is +called, +execute + +the +following +mapping +from + +sub-steps: +
        1. +If + +the +constraint +dictionaries + +first +argument + +handler + +is +not +defined +or +it +is +not +a +function, +throw + +TypeError + +and +terminate +the +algorithm. +Otherwise +configure + +handler + +to +be +invoked +when +a +discovery +hit +happens. +
        2. +If +the +second +argument + +errorHandler + +is +defined, +but +it +is +not +a +function, +throw + + +SemanticAnnotations + +TypeError + + +: +for +each +property-value +pair + +and +terminate +these +steps. +Otherwise +if +defined, +save +it +to +be +invoked + +in +error +conditions. +
        3. +If +the +third +argument + +onComplete + +is +defined, +but +it +is +not + +a +constraint +dictionary, + +function, +throw + +TypeError + +and +terminate +these +steps. +Otherwise +if +defined, +save +it +to +be +invoked +when +the +discovery +process +finished +for +other +reasons +than +having +been +canceled. +
          4. +
        4. +Each +property +name +in + +If + +filter.query + +is +defined, +pass +it +as +an +opaque +string +to + +the +constraint +dictionary +SHOULD + +underlying +implementation +to +be +matched +against +discovered +items. +The +underlying +implementation +is +responsible +to +parse +it +e.g. +as +a +SPARQL +or +JSON +query +and + +match +it +against + +the +either + + +Thing +Description + +s +found +during + +the +discovery +process. +If +queries +are +not +supported, +implementations + +SHOULD + +throw +a + + +name + +NotSupported + + +property +of +a + +error +and +terminate +these +steps. +
        5. +If + +filter.fragment + +is +defined, +and +if +it +contains +other +properties +than +the +ones + +defined +in + + +SemanticType + +ThingFragment + + +on + +, +throw + +TypeError + +and +terminate +these +steps. +Otherwise +save + +the +target + +object +for +matching +the +discovered +items +against +it. +
        6. +Request +the +underlying +platform +to +start +the +discovery +process, +with +the +following +parameters: +
          • +If + +filter.method + +is +not +defined +or +the +value +is + +"any" +, +use +the +widest +discovery +method +supported +by +the +underlying +platform. +
          • +Otherwise +if + +filter.method + +is + +"local" +, +use +the +local + +Thing +Directory + + +object, + +for +discovery. +Usually +that +defines + +Thing + +s +deployed +in +the +same +device, + +or +connected +to + +the +name +of + +device +in +slave +mode +(e.g. +sensors +connected +via +Bluetooth +or + +a +Property +on + +serial +connection). +
          • +Otherwise +if + +filter.method + +is + +"directory" +, +use + +the +target + +remote + +Thing +. + +Directory + +specified +in + +filter.url +. +
            • +
          • +When + +Otherwise +if + +filter.method + +is + +"multicast" +, +use +all + +the +name +matches, + +multicast +discovery +protocols +supported +by + +the +values +are +compared. + +underlying +platform. +
      4. +Whenever +a +new +item + +td + +is +discovered +by +the +underlying +platform, +run +the +following +sub-steps: +
        1. +If + +filter.query + +is +defined, +check +if + +td + +is +a +match +for + +the +values +match, + +query. +The +matching +algorithm +is +encapsulated +by +implementations. +If +that +returns + +false +, +discard + +td + +and +continue + +the +constraint + +discovery +process. +
        2. +If + +filter.fragment + +is +matched. + +defined, +for +each +property +defined +in +it, +check +if +that +property +exists +in + +td + +and +has +the +same +value. +If +this +is + +false + +in +any +checks, +discard + +td + +and +continue +the +discovery +process. + +
          3. +Editor's +note +Constraints +are +experimental +feature, +implementations +are + +
        3. +Otherwise +if + +td + +has + +not +required +to +support +them. +Editor's +note +Semantic +annotations +need +revisiting + +been +discarded + +in +order +to +simplify +their +representation. +In + +the +[ +WOT-TD +] +specification +they +represent + +previous +steps, +invoke + +the + +handler + +function +with + +td + +as +parameter. +
      5. +Whenever +an +error +occurs +during +the +discovery +process, +and +if + +errorHandler + +is +defined, +invoke +it +with +an +argument +of +type + + +@type + +Error + + +construct. +At +the +moment +only + +whose + + +@context +, + +message + +property +is +set +to + + +@type + +UnknownError + + +unless +there +was +an +error +code +provided +by +the + +Protocol +Bindings +, +in +which +case +set +it +to +that +value. +
      6. +When +the +discovery +process +is +finished, + +and +if + +onComplete + +is +defined, +invoke +it +run +the + +cancel +discovery + +steps. +
      7. +When +the + + +@id + +obs.unsubscribe() + + +constructs +are +used +in + +method +is +called, +run + +the +TD +. + +following + +cancel +discovery + +steps: +
        1. +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. +
        2. +Set + +obs.closed + +to + +false +.
      +
      +
      +

      + +3.2 + +The + + +fetch() + + +method + + +

      +

      +Accepts +an + +url + +argument +of +type + +USVString + +that +represents +a +URL +(e.g. + +"file://..." + +or + +"https://..." + +) + +and +returns +a + + +Promise + + +that +resolves +with +a + + +ThingDescription + +. + + +(a +serialized + +JSON-LD + +document +of +type + +USVString + +). + +

      +3.3 + +

      +The + +ThingDescription + +fetch(url) + + +type +Representation +of + +method + +MUST + +run + +the +Thing +Description +, +standardized + +following +steps: +

      1. +Return +a + +Promise + +promise + +and +execute +the +next +steps + +in +parallel +.
      2. +If +invoking + +fetch() + +is +not +allowed +for + +the +Wot +Things + +current +scripting +context +for +security +reasons, +reject + +promise + +with + +SecurityError + +and +terminate +these +steps. +
      3. +If +the +argument + +url + +is +not +a +URL, +reject + +promise + +with + +TypeError + +and +terminate +these +steps. +
      4. +Make +a +request +to +fetch +the +content +of + +url + +as +described +by +the + +Protocol +Bindings + +and +wait +for +the +reply. +Implementations +encapsulate +the +fetching +process +and +the +accepted +media +types +(such +as + +application/td+json + +), +as +far +as +a +valid + +Thing + +Description + +specification. + +can +be +obtained +as +defined +in +[ + +Note + + +WOT-TD + +In +this +version +of + + +]. +Let + +td + +be + +the +API, + + +Thing +Description + +s +are +represented + +string-serialized +from +the +returned +content, + +as +opaque +strings, +denoting +a +serialized +form, +for +instance +JSON +or +JSON-LD. +See +Issue +38 + +specified +in +the + +Thing +Description +serialization +.
      5. +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 +Issue +45 +. + +terminate +these +steps. +
      6. +Otherwise +resolve + +promise + +with + +td + +and +terminate +these +steps. +
      +
      +
      +

      + +3.4 + +3.3 + + +The + + +consume() + + +method + + +

      +

      +Accepts +an + +td + +argument +of +type + + + +ThingDescription + + + +and +returns +a + + +ConsumedThing + + +object +instantiated +based +on +parsing + +that +description. +

      +

      +The + +consume(td) + +method +must +run +the +following +steps: +

      1. +If +the +argument + +td + +is +not +a +string, +throw +a + +TypeError + +and +terminate +these +steps. +
      2. +Let + +stub + +be +the +result +of +running +the + +TD +parsing +algorithm + +with + +td + +as +argument. +If +that +throws +an +error, +re-throw +the +error +and +terminate +these +steps. +
      3. +If + +stub + +does +not +have +an +own +property +that +is +defined +in + +ThingFragment + +with +a +default +value, +add +that +property +and +value +to + +stub +.
      4. +Create +a + +ConsumedThing + +object + +thing + +initialized +from + +stub + +that +implements + +Observable +.
      5. +Add +the + +read() + +and + +write() + +methods +to +the + +ThingProperty + +elements +so +that +they +make +requests +to +access +the +remote + +Thing + +s +and +wait +for +the +reply, +as +defined +by +the + +Protocol +Bindings +. +Also, +all + +ThingProperty + +elements + +SHOULD + +implement + +Observable +, +i.e. +define +a + +subscribe() + +method +that +should +make +request +to +observe +the +given + +Properties + +as +defined +by +the + +Protocol +Bindings +.
      6. +Add +the + +invoke() + +methods +to +the + +ThingAction + +elements +so +that +they +make +requests +to +the +remote + +Thing + +to +invoke +its +actions, +as +defined +by +the + +Protocol +Bindings +.
      7. +Add +the + +subscribe() + +method +to +all + +ThingEvent + +elements +so +that +they +make +requests +to +subscribe +to +the +events +defined +by +the +remote + +Thing +, +as +defined +by +the + +Protocol +Bindings +.
      8. +Return + +thing +.
      +
      +
      +

      + +3.5 + +3.4 + + +The + + +produce() + + +method + + +

      +

      +Accepts +a + +model + +argument +of +type + + + +ThingModel + + + +and +returns +an + + +ExposedThing + + +object, +locally +created +based +on +the +provided +initialization +parameters. +An + +object. +

      +The + + +ExposedThing + +produce(model) + + +can +be +created +in + +method + +MUST + +run + +the +following +ways: + +steps: + +

      +
        +
      1. +from +an +initial + +If +invoking + +produce() + +is +not +allowed +for +the +current +scripting +context +for +security +reasons, +throw + +SecurityError + +and +terminate +these +steps. +
      2. +If +the +argument + +model +(including + + +is + +a +user +given +name +and +semantic +annotations +), + +string, + +then +adding +properties, +actions, +events + +run +the + +TD +parsing +algorithm + +with + +model + +passed +as +parameter. +If +it +throws +an +error, +re-throw +that +error + +and +request +handlers; + +terminate +this +algorithm. +Otherwise +let + +model + +be +the +returned +value. + +
        3. +
      3. +from +a +Thing +Description +(possibly +of +a + +If + +model + +is +not +an +object, +throw + +TypeError + +and +terminate +these +steps. +
      4. +If + +model + +does +not +have +an +own +property +that +is +defined +in + + +ConsumedThing + +ThingFragment + + + +object), +then +adding +request +handlers. + +with +a +default +value, +add +that +property +and +value +to + +model +. +
        5. +3.6 +The + +
      5. +Create +an + + +ThingModel + +ExposedThing + + +type +A +Thing + + +object + +thing + +initialized +from + +model +is +used +for +producing +a +new + +. +
        6. +
      6. +For +each +property +of + + +ExposedThing + + +and +can +be +either +a + +defined +in + + +ThingTemplate + +ThingFragment + + +, +initialize +the +property +based +on +the +provided +initial + +or +a + +default +values +provided +to +the +local + +WoT +Runtime + +implementation, +for +instance +initialize: +
        1. +the + + +ThingDescription + +id + + +. +3.7 +The + +property +to +be +the +final +unique +identifier +of +the + +Thing +,
        2. +the + +security + +object +of +type + + +SemanticAnnotations + +SecurityScheme + + +dictionary +A +dictionary +that +provides + + +to +represent + +the +semantic +types + +actual +security +scheme + +and +semantic +metadata. +<span class="idlDictionary" id= +"idl-def-semanticannotations" data-idl="" data-title= +"SemanticAnnotations">dictionary <span class= +"idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-semanticannotations" class="internalDFN" data-link-type= +"dfn"> { +<span class="idlMember" id= +"idl-def-semanticannotations-semantictype" data-idl="" data-title= +"semanticType" data-dfn-for="semanticannotations"> <span class= +"idlMemberType"><a href= +"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-semantictype" +class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-no-default="" data-link-for= +"semanticannotations" data-lt="" href= +"#dom-semanticannotations-semantictype" class="internalDFN" +data-link-type="dfn"> +<span class="idlMember" id="idl-def-semanticannotations-metadata" +data-idl="" data-title="metadata" data-dfn-for= +"semanticannotations"> <a href= +"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-semanticmetadata" +class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-no-default="" data-link-for= +"semanticannotations" data-lt="" href= +"#dom-semanticannotations-metadata" class="internalDFN" +data-link-type="dfn"> +}; +The + +its +properties +as +set +up +by +the +implementation, +
        3. +the + + +semanticType + +properties + + +property +denotes +a +list +of + +to +be +an +object +with +all +properties +being + + +SemanticType + +ThingProperty + + + +objects +that + +in +which +the + +read() + +and + +write() + +methods +are +provided +to + +define +local +methods +to +get +and +set +the + +Property + +values, +
        4. +the +semantic +types +that +can +be +used +in +semantic +metadata +type-value +pairs. +The + + +metadata + +actions + + +property +denotes +a +list +of + +to +be +an +object +with +all +properties +being + + +SemanticMetadata + +ThingAction + + + +objects +(type-value +pairs). +3.8 +The + +in +which +the + + +SemanticType + +invoke() + + +dictionary +<span class="idlDictionary" id= +"idl-def-semantictype" data-idl="" data-title= +"SemanticType">dictionary <span class= +"idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-semantictype" class="internalDFN" data-link-type= +"dfn"> { +<span class="idlMember" id="idl-def-semantictype-name" data-idl="" +data-title="name" data-dfn-for= +"semantictype"> required <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" +data-link-for="semantictype" data-lt="" href= +"#dom-semantictype-name" class="internalDFN" data-link-type= +"dfn"> +<span class="idlMember" id="idl-def-semantictype-context" data-idl= +"" data-title="context" data-dfn-for= +"semantictype"> required <a href= +"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default="" +data-link-for="semantictype" data-lt="" href= +"#dom-semantictype-context" class="internalDFN" data-link-type= +"dfn"> +<span class="idlMember" id="idl-def-semantictype-prefix" data-idl= +"" data-title="prefix" data-dfn-for= +"semantictype"> <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" +data-link-for="semantictype" data-lt="" href= +"#dom-semantictype-prefix" class="internalDFN" data-link-type= +"dfn"> +}; +Represents +a +semantic +type +annotation, +containing +a +name, +a +context +and + +method +is +provided +to +define + +a +prefix. + +local +method +to +run +the +defined + +Action + +s, +
          5. +
        5. +The + +the + +events + +property +to +be +an +object +with +all +properties +being + + +name + +ExposedEvent + + +attribute +represents +the +name +of +the +semantic +type + + +objects + +in +which + +the +given +context. +The + + +context + +emit() + + +attribute +represents +an +URL +link + +method +is +provided + +to +define +a +local +way +to +trigger +sending +notifications +to +all +subscribed +clients, +
        6. +and +initialize + +the +context +of +the +semantic +classification. + +other +properties +as +initialized +from + +model +. +
          7. +
        7. +Return + +thing +.

        +The +prefix + + +TD +parsing +algorithm + + +attribute +represents + +takes + +a +short +prefix +associated +with + +string + +td + +as +argument +and +runs +the +following +steps: +

        1. +Parse + +td + +according +to +the + +WoT +Thing +Description + +in +order +to +produce + +a +context. + + +JSON +object + +json +. +Update + +thing + +with +the +properties +and +values +defined +in + +json +. +
          2. +Editor's +note +Semantic +type +examples +to +be +added. + +
        2. +If +there +was +an +error +during +the +parsing, +throw +that +error +and +terminate +these +steps. +
        3. +Otherwise +return + +json +.
      +
      +
      +

      +3.9 + + +3.5 + + +The + + +SemanticMetadata + +register() + + + +dictionary +<span class="idlDictionary" id= +"idl-def-semanticmetadata" data-idl="" data-title= +"SemanticMetadata">dictionary <span class= +"idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-semanticmetadata" class="internalDFN" data-link-type= +"dfn"> { +<span class="idlMember" id="idl-def-semanticmetadata-type" +data-idl="" data-title="type" data-dfn-for= +"semanticmetadata"> <a href= +"#dom-semantictype" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-no-default="" data-link-for= +"semanticmetadata" data-lt="" href="#dom-semanticmetadata-type" +class="internalDFN" data-link-type= +"dfn"> +<span class="idlMember" id="idl-def-semanticmetadata-value" +data-idl="" data-title="value" data-dfn-for= +"semanticmetadata"> <a href= +"https://heycam.github.io/webidl/#idl-any">any<a data-no-default="" +data-link-for="semanticmetadata" data-lt="" href= +"#dom-semanticmetadata-value" class="internalDFN" data-link-type= +"dfn"> +}; + +method + + +

      +

      +The + +Takes +two +mandatory +arguments: +

      • + +SemanticMetadata + +directory + + +dictionary +describes + +denoting + +a +pair +of +semantic +type + + +Thing +Directory +, +and +value: + +
        • +
      • +The + + +type + +thing + + +attribute +represents +the +semantic +type +name +defined +by +a + +denoting +an + + +SemanticType + +ExposedThing + + + +object. +
        • +The +value +attribute +represents +the +metadata +value. + +
      +3.10 +The +ThingTemplate +dictionary + +

      +A + +Generate +the + +Thing +Template +is +a +dictionary +that +provides +a +user + +Description + +as + +td +, +given +name, +and + +the +semantic +types + + +Properties +, +Action + +s + +and +semantic +metadata +attached +to +the + + +Event + +s +defined +for +this + + + +ExposedThing + + +object. +Then +make +a +request +to +register + +td + +to +the +given +WoT + +Thing +Description +'s +root +level. + +Directory +. +

      +<span class="idlDictionary" id= +"idl-def-thingtemplate" data-idl="" data-title= +"ThingTemplate">dictionary <span class= +"idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-thingtemplate" class="internalDFN" data-link-type= +"dfn"> : <span class= +"idlSuperclass"><a href="#dom-semanticannotations" class= +"internalDFN" data-link-type= +"dfn"> { +<span class="idlMember" id="idl-def-thingtemplate-name" data-idl="" +data-title="name" data-dfn-for= +"thingtemplate"> required <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" +data-link-for="thingtemplate" data-lt="" href= +"#dom-thingtemplate-name" class="internalDFN" data-link-type= +"dfn"> +}; + +
      +
      +

      + +3.6 + +The + + +ThingTemplate + +unregister() + + + +method + + +dictionary +extends + +

      +

      +Takes +two +mandatory +arguments: +

      +Makes +a +request +to +unregister + +the +user +given +name +of + + +thing + +from + +the +given +WoT + +Thing +Directory + +. +Editor's +note +Support +for +configuration +and +security +data +might +be +added +later. + +

      +
      +
      +

      + +3.11 + +3.7 + + +Examples + + +

      +
      +
      + +Example +1 + +: + +: +Discover +Things +via +directory + +
      +
      let discoveryFilter = {
+  method: "directory",
+  url: "http://directory.wotservice.org"
+};
+let subscription = wot.discover(discoveryFilter).subscribe(
+  "hljs-params">thing { <span class=
+"hljs-built_in">console.log(<span class=
+"hljs-string">"Found Thing " + thing.name); },
+
+"hljs-params">td => {
+    console.log(
+"hljs-string">"Found Thing " + td.name);
+    
+"hljs-comment">// fetch the TD and create a ConsumedThing
+    let thing = wot.consume(td);
+  },
+
+  error => { console.log("Discovery finished because an error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);
+setTimeout( () => {
+    subscription.unsubscribe();
+    console.log("Discovery timeout");
+  },
+
+5000
+
+);
+
      +
      +Note +Note +that +canceling +a +discovery +(through +unsubscribe() +) +may +not +be +successful +in +all +cases, +for +instance +when +discovery +is +based +on +open +ended +broadcast +requests. +However, +once +unsubscribe() +has +been +called, +implementations +MUST +suppress +further +event +handling +( +i.e. +further +discoveries +and +errors) +on +the +Observable. +Also, +a +discovery +error +may +not +mean +the +end +of +the +discovery +process. +However, +in +order +to +respect +Observable +semantics +(error +always +terminates +processing), +implementations +MUST +close +or +suppress +further +event +handling +on +the +Observable. + +
      +
      + +Example +2 + +: + +: +Discover +Things +exposed +by +local +hardware + +
      +
      let subscription = wot.discover({ method: "local" }).subscribe(
+  "hljs-params">thing { <span class=
+
+"hljs-params">td => { 
+"hljs-built_in">console.log("hljs-string">"Found local Thing " + thing.name); },
+
+"hljs-string">"Found local Thing " + td.name); },
+
+  error => { console.log("Discovery error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);
+
      +
      +
      +
      + +Example +3 + +: + +: +Same +as +above +but +with +different +Observable +syntax + +
      +
      let subscription = wot.discover({ method: "local" }).subscribe({
+  thing => { <span class=
+
+  td => { 
+"hljs-built_in">console.log("hljs-string">"Found local Thing " + thing.name); },
+
+"hljs-string">"Found local Thing " + td.name); },
+
+  error: err => { console.log("Discovery error: " + err.message); },
+  complete: () => { console.log("Discovery finished successfully");}
+});
+
      +
      +Example +4 +: +Discover +Things +exposed +nearby, +via +Bluetooth +or +NFC +<span class= +"hljs-keyword">let subscription = wot.discover({ + : <span class= +"hljs-string">"nearby", + : [{ <span class= +"hljs-attr">protocol: <span class= +"hljs-string">"BLE-4.2" }, { <span class= +"hljs-attr">protocol: <span class= +"hljs-string">"NFC"}] +}).subscribe( + <span class= +"hljs-params">thing { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Found nearby Thing " + thing.name); }, + error => { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Discovery error: " + error.message); }, + () => { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Discovery finished successfully");} +); +Example +5 +: +Discover +Things +exposed +in +a +proprietary +way +<span class= +"hljs-keyword">let subscription = wot.discover({ + : <span class= +"hljs-string">"other", + : [{ <span class= +"hljs-attr">solution: <span class= +"hljs-string">"XYZ123", <span class= +"hljs-attr">key}] +}).subscribe( + <span class= +"hljs-params">thing { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Found Thing " + thing.name); }, + error => { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Discovery error: " + error.message); }, + () => { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Discovery finished successfully");} +); + +
      +
      +
      +

      + +4. + +The + + +ConsumedThing + + +interface + + +

      +

      +The + +Represents +an +object +that +extends +a + + +ConsumedThing + +ThingFragment + + + +interface +is +a + +with +methods +for + +client +API + +interactions +(send +request + +for +sending +requests +to +servers +in +order +to +retrieve +or +update + +reading +and +writing + +Properties +, + + +), + +invoke +Actions +, + + +Action + +s, +subscribe + +and +observe +Properties + +unsubscribe +for + +Property + + +changes + +and + +Events +. + +Event + +s. + +

      +
      +
      interface "dfn"> {
+<span class="idlAttribute" id="idl-def-consumedthing-name"
+data-idl="" data-title="name" data-dfn-for=
+"consumedthing">    readonly attribute <span class=
+"idlAttrType"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default=""
+data-link-for="consumedthing" data-lt="" href=
+"#dom-consumedthing-name" class="internalDFN" data-link-type=
+"dfn">
+<span class="idlMethod" id=
+"idl-def-consumedthing-getthingdescription" data-idl="" data-title=
+"getThingDescription" data-dfn-for="consumedthing">    <span class=
+"idlMethType"><a href="#dom-thingdescription" class="internalDFN"
+
+"dfn">ConsumedThing : 
+data-link-type=
+"dfn"> <span class=
+"idlMethName"><a data-no-default="" data-link-for="consumedthing"
+data-lt="getthingdescription()|getThingDescription" href=
+"#dom-consumedthing-getthingdescription" class="internalDFN"
+data-link-type="dfn">getThingDescription
+<span class="idlMethod" id=
+"idl-def-consumedthing-readproperty-name" data-idl="" data-title=
+"readProperty" data-dfn-for="consumedthing">    <span class=
+"idlMethType"><a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default=""
+data-link-for="consumedthing" data-lt="readproperty()|readProperty"
+href="#dom-consumedthing-readproperty" class="internalDFN"
+data-link-type="dfn">readProperty(<span class=
+"idlParam"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class="idlMethod" id=
+"idl-def-consumedthing-writeproperty-name-value" data-idl=""
+data-title="writeProperty" data-dfn-for=
+"consumedthing">    <a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default=""
+data-link-for="consumedthing" data-lt=
+"writeproperty()|writeProperty" href=
+"#dom-consumedthing-writeproperty" class="internalDFN"
+data-link-type="dfn">writeProperty(<span class=
+"idlParam"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class="idlMethod" id=
+"idl-def-consumedthing-invokeaction-name-parameters" data-idl=""
+data-title="invokeAction" data-dfn-for=
+"consumedthing">    <a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default=""
+data-link-for="consumedthing" data-lt="invokeaction()|invokeAction"
+href="#dom-consumedthing-invokeaction" class="internalDFN"
+data-link-type="dfn">invokeAction(<span class=
+"idlParam"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class="idlMethod" id=
+"idl-def-consumedthing-onpropertychange-name" data-idl=""
+data-title="onPropertyChange" data-dfn-for=
+"consumedthing">    <a href=
+"#dom-observable" class="internalDFN" data-link-type=
+"dfn">       <span class=
+"idlMethName"><a data-no-default="" data-link-for="consumedthing"
+data-lt="onpropertychange()|onPropertyChange" href=
+"#dom-consumedthing-onpropertychange" class="internalDFN"
+data-link-type="dfn">onPropertyChange(<span class=
+"idlParam"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class="idlMethod" id="idl-def-consumedthing-onevent-name"
+data-idl="" data-title="onEvent" data-dfn-for=
+"consumedthing">    <a href=
+"#dom-observable" class="internalDFN" data-link-type=
+"dfn">       <span class=
+"idlMethName"><a data-no-default="" data-link-for="consumedthing"
+data-lt="onevent()|onEvent" href="#dom-consumedthing-onevent"
+class="internalDFN" data-link-type=
+"dfn">onEvent<span class=
+"idlParamType"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class="idlMethod" id="idl-def-consumedthing-ontdchange"
+data-idl="" data-title="onTDChange" data-dfn-for=
+"consumedthing">    <a href=
+
+"dfn">ThingFragment {
+  readonly attribute DOMString id;
+  readonly attribute DOMString name;
+  readonly attribute DOMString? base;
+  readonly attribute PropertyMap properties;
+  readonly attribute ActionMap actions;
+  readonly attribute EventMap events;
+  // getter for ThingFragment properties
+  getter 
+"https://heycam.github.io/webidl/#idl-any">any (DOMString name);
+};
+[NoInterfaceObject]
+interface PropertyMap {
+  readonly maplike<DOMString, ThingProperty>;
+};
+[NoInterfaceObject]
+interface ActionMap {
+  readonly maplike<DOMString, ThingAction>;
+};
+[NoInterfaceObject]
+interface EventMap {
+  readonly maplike<DOMString, ThingEvent>;
+};
+
+"dfn">ConsumedThing includes 
+"#dom-observable" class="internalDFN" data-link-type=
+"dfn">       <span class=
+"idlMethName"><a data-no-default="" data-link-for="consumedthing"
+data-lt="ontdchange()|onTDChange" href=
+"#dom-consumedthing-ontdchange" class="internalDFN" data-link-type=
+"dfn">onTDChange
+};
+
+"dfn">Observable;
+//
+for
+TD
+changes
+
+
+
      +
      +

      +The + + +ConsumedThing + +id + + + +attribute + +represents +a +local +proxy +object + +the +unique +identifier + +of +the +remote + + +Thing +. + + +instance, +typically +a +URI, +IRI, +or +URN +as + +USVString +. +

      +4.1 + +

      +The + + +name + + +property +The +name +property + +attribute + +represents +the +name +of +the + +Thing + +as +specified +in +the +TD +. +In +this +version +it +is +read +only. + + +DOMString +. +

      +4.2 + +

      +The + + +getThingDescription() + +base + + + +method +Returns +the +Thing +Description +of + +attribute +represents + +the +Thing +. +Editor's +note +In +this +version, +introspection +based +on +TD +is +out +of +scope. +Parsing +and +exposing +Thing +Description +s + +base +URI +that + +is +discussed +in +Issue +38 +. + +valid +for +all +defined +local +interaction +resources. + +

      +4.3 + +

      +The + + +readProperty() + +properties + + + +method +Takes +the +Property +name +as +the +name +argument, +then +requests +from +the +underlying +platform +and +the +Protocol +Bindings +to +retrieve +the +Property +on +the +remote +Thing +and +return +the +result. +Returns + +attribute +represents + +a +dictionary +of + + +ThingProperty + +Promise + + +items. +The + + +PropertyMap + + +that +resolves +with +the +Property +value +or +rejects +with +an +Error +. + +4.4 +The + + +interface +represents +a +maplike +dictionary +where +all +values +are + + +writeProperty() + +ThingProperty + + +method +Takes +the +Property + + +name +as +the +name +argument +and +the +new +value +as +the +value +argument, +then +requests +from +the +underlying +platform + +objects. +The + +read() + +and +the +Protocol +Bindings + + +write() + +methods +make +a +request + +to +update + +access + +the + +Property + +Properties + + +on +the +remote + +Thing + +and +return +the +result. +Returns +a + +represented +by +this + + +ConsumedThing + +Promise + + +that +resolves +on +success +or +rejects +with +an +Error +. + +proxy +object. + +

      +4.5 + +

      +The + + +invokeAction() + +actions + + + +method +Takes +the +Action +name +from +the +name +argument +and +the +list +of +parameters, +then +requests +from +the +underlying +platform +and +the +Protocol +Bindings +to +invoke +the +Action +on +the +remote +Thing +and +return +the +result. +Returns + +attribute +represents + +a +Promise + +dictionary +of + + +ThingAction + + +that +resolves +with +the +return +value +or +rejects +with +an +Error +. + +4.6 + + +items. + +The + + +onPropertyChange() + +ActionMap + + + +method +Returns +an + +interface +represents +a +maplike +dictionary +where +all +values +are + + +Observable + +ThingAction + + + +for +the +Property +specified +in +the +name +argument, +allowing +subscribing +to +and +unsubscribing +from +notifications. + +objects. + +The +callback +function +passed +to +the + + +subscribe() + +invoke() + + +method +when +invoked +on + +represents +a +request +to +invoke + +the +returned +observer +will +receive + + +Action + +on + +the +new +property +value +each +time +it +is +changed. + +remote + +Thing +. +

      +4.7 + +

      +The + + +onEvent() + +events + + + +method +Returns +an + +attribute +represents +a +dictionary +of + + +Observable + +ThingEvent + + + +for +the +Event +specified +in +the +name +argument, +allowing +subscribing +to +and +unsubscribing +from +notifications. +The +callback +function +passed +to +the +subscribe() +method +when +invoked +on +the +returned +observer +will +receive +the +event +data +each +time +the +event +is +fired. +4.8 + +items. + +The + + +onTDChange() + +EventMap + + + +method +Returns +an + +interface +represents +a +maplike +dictionary +where +all +values +are + + +Observable + +ThingEvent + + +, +allowing +subscribing +to +and +unsubscribing +from +notifications +to +the +Thing +Description +. +The +callback +function +passed + + +objects. +Subscribing + +to +the +subscribe() +method +when +invoked + +events +involves +setting +up +an +observation +(subscription) +mechanism + +on +the +returned +observer +will +receive +the +new +Thing +Description +each +time +it +is +changed. + +remote +object. + +

      +
      +

      + +4.9 + +4.1 + + +Examples + + +

      +

      +Below +a + + + +ConsumedThing + + + +interface +example +is +given. +

      +
      +
      + +Example +6 + +4 + +: + +: +Consume +a +Thing + +
      +try { + let td = await wot.fetch("http://mmyservice.org/mySensor"); + let thing = wot.consume(td); + console.log("Thing " + thing.name + " has been consumed."); + let subscription = thing.onPropertyChange("temperature") + .subscribe(function(value) { + console.log("Temperature + " has changed to " + value); + }); + thing.invokeAction("startMeasurement", { units: "Celsius" }) + .then(() => { console.log("Temperature measurement started."); }) + .catch(e => { + console.log("Error starting measurement."); + subscription.unsubscribe(); + }) +} catch(error) { + console.log("Error during fetch or consume: " + error.message); + +
      "hljs-keyword">try {
+  
+"hljs-keyword">let subscription = wot.discover({ method: "local" }).subscribe(
+    
+"hljs-params">td => {
+      
+"hljs-keyword">let thing = wot.consume(td);
+      console.log(
+"hljs-string">"Thing " + thing.name + " has been consumed.");
+      
+"hljs-keyword">let subscription = thing["temperature"].subscribe(function(value) {
+          
+"hljs-built_in">console.log("Temperature: " + value);
+        });
+      thing.actions["startMeasurement"].invoke({ units: "Celsius" })
+        .then(() => { console.log("Temperature measurement started."); })
+        .catch(e => {
+           
+"hljs-built_in">console.log("Error starting measurement.");
+           subscription.unsubscribe();
+         })
+    },
+    error => { console.log("Discovery error: " + error.message); },
+    () => { console.log("Discovery finished successfully");}
+  );
+} catch(error) {
+  console.log(
+"hljs-string">"Error: " + error.message);
+
+};
+
      +
      +
      +
      +
      +

      + +5. + +The + + +ExposedThing + + +interface + + +

      +

      +The + + +ExposedThing + + +interface +is +the +server +API +that +allows +defining +request +handlers, +properties, + +Actions +, +and + +Events + +to +a + +Thing +. +It +also +implements +the + + +ConsumedThing + +Observable + + + +interface. +An + + +ExposedThing + + +is +created +by +the + +produce() + +method. +

      +Editor's +note +It +is +under +consideration +to +use +a +constructor +for +ExposedThing +instead +of +a +factory +method. + +
      +<a href= +"#dom-exposedthing" class="internalDFN" data-link-type= +"dfn"> implements <a href= +"#dom-consumedthing" class="internalDFN" data-link-type= +"dfn"> +<span class="idlInterface" id="idl-def-exposedthing" data-idl="" +data-title="ExposedThing">interface <span class= + +
      "idl-def-exposedthing" data-idl="" data-title=
+"ExposedThing">interface 
+"idlInterfaceID">"dfn"> {
+<span class=
+"idlSectionComment">    // define how to expose and run the Thing
+<span class="idlMethod" id="idl-def-exposedthing-start" data-idl=""
+data-title="start" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default=""
+data-link-for="exposedthing" data-lt="start()|start" href=
+"#dom-exposedthing-start" class="internalDFN" data-link-type=
+"dfn">start
+<span class="idlMethod" id="idl-def-exposedthing-stop" data-idl=""
+data-title="stop" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default=""
+data-link-for="exposedthing" data-lt="stop()|stop" href=
+"#dom-exposedthing-stop" class="internalDFN" data-link-type=
+"dfn">stop
+<span class="idlMethod" id=
+"idl-def-exposedthing-register-directory" data-idl="" data-title=
+"register" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default=""
+data-link-for="exposedthing" data-lt="register()|register" href=
+"#dom-exposedthing-register" class="internalDFN" data-link-type=
+"dfn">register(<span class=
+"idlParam">optional <a href=
+"https://heycam.github.io/webidl/#idl-USVString">USVString
+<span class="idlMethod" id=
+"idl-def-exposedthing-unregister-directory" data-idl="" data-title=
+"unregister" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href=
+
+"dfn">ExposedThing : ThingFragment {
+  readonly attribute PropertyMap properties;
+  readonly attribute ActionMap actions;
+  readonly attribute ExposedEvents events;
+  // getter for ThingFragment properties
+  getter 
+"https://heycam.github.io/webidl/#idl-any">any (DOMString name);
+  // setter for ThingFragment properties
+  setter void (
+"idlParam">DOMString name, any value);
+  // methods to expose and destroy the Thing
+  Promise<void> data-link-for="exposedthing" data-lt="unregister()|unregister"
+href="#dom-exposedthing-unregister" class="internalDFN"
+data-link-type="dfn">unregister(<span class=
+"idlParam">optional <a href=
+"https://heycam.github.io/webidl/#idl-USVString">USVString
+<span class="idlMethod" id=
+"idl-def-exposedthing-emitevent-eventname-payload" data-idl=""
+data-title="emitEvent" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href=
+
+data-link-for="exposedthing" data-lt=
+"exposedthing.expose()|exposedthing.expose|expose()|expose" href=
+"#dom-exposedthing-expose" class="internalDFN" data-link-type=
+"dfn">expose();
+  Promise<void> data-link-for="exposedthing" data-lt="emitevent()|emitEvent" href=
+"#dom-exposedthing-emitevent" class="internalDFN" data-link-type=
+"dfn">emitEvent<span class=
+"idlParamType"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class=
+"idlSectionComment">    // define Thing Description modifiers
+<span class="idlMethod" id=
+"idl-def-exposedthing-addproperty-property" data-idl="" data-title=
+"addProperty" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href="#dom-exposedthing" class="internalDFN"
+data-link-type=
+"dfn">  <span class=
+
+data-link-for="exposedthing" data-lt=
+"exposedthing.destroy()|exposedthing.destroy|destroy()|destroy"
+href="#dom-exposedthing-destroy" class="internalDFN"
+data-link-type="dfn">destroy();
+  // define Properties
+  
+"internalDFN" data-link-type=
+"dfn">ExposedThing 
+"idlMethName">data-lt="addproperty()|addProperty" href=
+"#dom-exposedthing-addproperty" class="internalDFN" data-link-type=
+"dfn">addProperty<span class=
+"idlParamType"><a href="#dom-thingproperty" class="internalDFN"
+
+data-lt=
+"exposedthing.addproperty()|exposedthing.addproperty|addproperty()|addproperty"
+href="#dom-exposedthing-addproperty" class="internalDFN"
+
+data-link-type=
+"dfn"> <span class=
+"idlParamName">property
+<span class="idlMethod" id=
+"idl-def-exposedthing-removeproperty-name" data-idl="" data-title=
+"removeProperty" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href="#dom-exposedthing" class="internalDFN"
+
+"dfn">addProperty(DOMString name, PropertyFragment property, optional any initValue);
+  "dfn">  <span class=
+
+"dfn">ExposedThing 
+"idlMethName">data-lt="removeproperty()|removeProperty" href=
+"#dom-exposedthing-removeproperty" class="internalDFN"
+data-link-type="dfn">removeProperty(<span class=
+
+data-lt=
+"exposedthing.setpropertyreadhandler()|exposedthing.setpropertyreadhandler|setpropertyreadhandler()|setpropertyreadhandler"
+href="#dom-exposedthing-setpropertyreadhandler" class="internalDFN"
+data-link-type=
+"dfn">setPropertyReadHandler(
+"idlParam">"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class="idlMethod" id="idl-def-exposedthing-addaction-action"
+data-idl="" data-title="addAction" data-dfn-for=
+"exposedthing">    <a href=
+"#dom-exposedthing" class="internalDFN" data-link-type=
+"dfn">  <span class=
+"idlMethName"><a data-no-default="" data-link-for="exposedthing"
+data-lt="addaction()|addAction" href="#dom-exposedthing-addaction"
+class="internalDFN" data-link-type=
+"dfn">addAction<span class=
+"idlParamType"><a href="#dom-thingaction" class="internalDFN"
+
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name, PropertyReadHandler readHandler);
+  "dfn"> <span class=
+"idlParamName">action
+<span class="idlMethod" id="idl-def-exposedthing-removeaction-name"
+data-idl="" data-title="removeAction" data-dfn-for=
+"exposedthing">    <a href=
+"#dom-exposedthing" class="internalDFN" data-link-type=
+"dfn">  <span class=
+
+"dfn">ExposedThing 
+"idlMethName">data-lt="removeaction()|removeAction" href=
+"#dom-exposedthing-removeaction" class="internalDFN"
+data-link-type="dfn">removeAction(<span class=
+
+data-lt=
+"exposedthing.setpropertywritehandler()|exposedthing.setpropertywritehandler|setpropertywritehandler()|setpropertywritehandler"
+href="#dom-exposedthing-setpropertywritehandler" class=
+"internalDFN" data-link-type=
+"dfn">setPropertyWriteHandler(
+"idlParam">"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class="idlMethod" id="idl-def-exposedthing-addevent-event"
+data-idl="" data-title="addEvent" data-dfn-for=
+"exposedthing">    <a href=
+"#dom-exposedthing" class="internalDFN" data-link-type=
+"dfn">  <span class=
+"idlMethName"><a data-no-default="" data-link-for="exposedthing"
+data-lt="addevent()|addEvent" href="#dom-exposedthing-addevent"
+class="internalDFN" data-link-type=
+"dfn">addEvent<span class=
+"idlParamType"><a href="#dom-thingevent" class="internalDFN"
+
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name, PropertyWriteHandler writeHandler);
+  "dfn">
+<span class="idlMethod" id="idl-def-exposedthing-removeevent-name"
+data-idl="" data-title="removeEvent" data-dfn-for=
+"exposedthing">    <a href=
+"#dom-exposedthing" class="internalDFN" data-link-type=
+"dfn">  <span class=
+"idlMethName"><a data-no-default="" data-link-for="exposedthing"
+data-lt="removeevent()|removeEvent" href=
+"#dom-exposedthing-removeevent" class="internalDFN" data-link-type=
+"dfn">removeEvent<span class=
+"idlParamType"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class=
+"idlSectionComment">    // define request handlers
+<span class="idlMethod" id=
+"idl-def-exposedthing-setpropertyreadhandler-name-readhandler"
+data-idl="" data-title="setPropertyReadHandler" data-dfn-for=
+"exposedthing">    <a href=
+"#dom-exposedthing" class="internalDFN" data-link-type=
+"dfn">  <span class=
+
+"dfn">ExposedThing 
+"idlMethName">data-lt="setpropertyreadhandler()|setPropertyReadHandler" href=
+"#dom-exposedthing-setpropertyreadhandler" class="internalDFN"
+data-link-type="dfn">setPropertyReadHandler(<span class=
+
+data-lt=
+"exposedthing.removeproperty()|exposedthing.removeproperty|removeproperty()|removeproperty"
+href="#dom-exposedthing-removeproperty" class="internalDFN"
+data-link-type=
+"dfn">removeProperty(
+"idlParam">"https://heycam.github.io/webidl/#idl-DOMString">DOMString,
+                                         <span class=
+
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name);
+  // define Actions
+  
+"internalDFN" data-link-type=
+"dfn">ExposedThing addAction(
+"idlParam">"#dom-propertyreadhandler" class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">readHandler
+<span class="idlMethod" id=
+"idl-def-exposedthing-setpropertywritehandler-name-writehandler"
+data-idl="" data-title="setPropertyWriteHandler" data-dfn-for=
+"exposedthing">    <a href=
+"#dom-exposedthing" class="internalDFN" data-link-type=
+"dfn">  <span class=
+
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name, ActionFragment init, ActionHandler action);
+  
+data-link-type=
+"dfn">ExposedThing 
+"idlMethName">data-lt="setpropertywritehandler()|setPropertyWriteHandler" href=
+"#dom-exposedthing-setpropertywritehandler" class="internalDFN"
+
+data-lt=
+"exposedthing.removeaction()|exposedthing.removeaction|removeaction()|removeaction"
+href="#dom-exposedthing-removeaction" class="internalDFN"
+
+data-link-type=
+"dfn">setPropertyWriteHandler,
+                                          <span class=
+
+"dfn">removeAction(
+"idlParam">"#dom-propertywritehandler" class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">writeHandler
+<span class="idlMethod" id=
+"idl-def-exposedthing-setactionhandler-name-action" data-idl=""
+
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name);
+data-title="setActionHandler" data-dfn-for=
+"exposedthing">    <a href=
+"#dom-exposedthing" class="internalDFN" data-link-type=
+"dfn">  <span class=
+
+"exposedthing">
+  
+data-link-type=
+"dfn">ExposedThing 
+"idlMethName">data-lt="setactionhandler()|setActionHandler" href=
+"#dom-exposedthing-setactionhandler" class="internalDFN"
+data-link-type="dfn">setActionHandler(<span class=
+
+data-lt=
+"exposedthing.setactionhandler()|exposedthing.setactionhandler|setactionhandler()|setactionhandler"
+href="#dom-exposedthing-setactionhandler" class="internalDFN"
+data-link-type=
+"dfn">setActionHandler(
+"idlParam">"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a href="#dom-actionhandler"
+class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">action
+};
+<span class="idlCallback" id="idl-def-propertyreadhandler"
+data-idl="" data-title="PropertyReadHandler">callback <span class=
+"idlCallbackID"><a data-no-default="" data-link-for="" data-lt=""
+href="#dom-propertyreadhandler" class="internalDFN" data-link-type=
+"dfn"> = <span class=
+"idlCallbackType"><a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise
+<span class="idlCallback" id="idl-def-propertywritehandler"
+data-idl="" data-title="PropertyWriteHandler">callback <span class=
+"idlCallbackID"><a data-no-default="" data-link-for="" data-lt=""
+href="#dom-propertywritehandler" class="internalDFN"
+data-link-type="dfn">
+<span class="idlCallback" id="idl-def-actionhandler" data-idl=""
+data-title="ActionHandler">callback <span class=
+"idlCallbackID"><a data-no-default="" data-link-for="" data-lt=""
+
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name, 
+href="#dom-actionhandler" class="internalDFN" data-link-type=
+"dfn"> = <span class=
+"idlCallbackType"><a href=
+
+"dfn">ActionHandler action);
+  // define Events
+  
+"internalDFN" data-link-type=
+"dfn">ExposedThing addEvent(DOMString name, EventFragment event);
+  
+data-link-type=
+"dfn">ExposedThing removeEvent(DOMString name);
+};
+[NoInterfaceObject]
+interface ExposedEvents {
+  maplike<DOMString, ExposedEvent>;
+};
+callback PropertyReadHandler = Promise<any> ();
+callback PropertyWriteHandler = Promise<void> (any value);
+callback ActionHandler = 
+"https://heycam.github.io/webidl/#idl-promise">
+Promise
+
+<
+
+any
+
+>
+
+(
+
+
+
+any
+
+
+
+parameters
+
+
+);
+
+
      +
      +5.1 +The +start() +method + +

      +Start +serving +external +requests +for +the +Thing +. +5.2 + +The + + +stop() + +properties + + + +method +Stop +serving +external +requests +for +the +Thing +. +5.3 +The + +attribute +represents +a +dictionary +of + + +register() + +ThingProperty + + +method +Generates +the +Thing +Description + + +given + +items +in +which + +the +properties, +Actions + + +read() + +and +Event +defined +for +this +object. +If +a + + +directory + +write() + + +argument +is +given, +make +a +request +to +register + +methods +define +local +methods +that +access + +the +Thing +Description +with + +physical +representations +of + +the +given +WoT +repository +by +invoking +its +register +Action + + +Properties + +. +

      +5.4 + +

      +The + + +unregister() + +actions + + + +method +If + +attribute +represents + +a +dictionary +of + + +directory + +ThingAction + + +argument +is +given, +make +a +request +to +unregister +the +Thing +Description + + +with + +items +in +which + +the +given +WoT +repository +by +invoking +its + + +unregister + +invoke() + + +Action +. +Then, +and +in +the +case +no +arguments +were +provided + +method +represents +a +local +method + +to +this +function, +stop +the +Thing +and +remove + +invoke + +the +Thing +Description + + +Action + +. +

      +5.5 + +

      +The + + +emitEvent() + +events + + + +method +Emits +an +the +event +initialized +with +the +event +name +specified +by + +attribute +represents +a +dictionary +of + +ExposedEvent + +items +that +add + +the + +eventName + +emit() + + +argument +and +data +specified +by + +method +to + +the + + +payload + +ThingEvent + + +argument. + +5.6 + + +definition. + +The + + +DataSchema + +ExposedEvents + + + +type +<span class="idlTypedef" id= +"idl-def-dataschema" data-idl="" data-title= +"DataSchema">typedef <a href= +"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default="" +data-link-for="" data-lt="" href="#dom-dataschema" class= +"internalDFN" data-link-type= +"dfn"> + +interface +represents +a +maplike +dictionary +where +all +values +are + + +DataSchema + +ExposedEvent + + + +objects. +

      + +5.1 + + +; + +The + + +DataSchema + +expose() + + + +method + + +type +represents +a +data +type +specified +in + +

      +

      +Start +serving +external +requests +for + +the + +Thing +Description + +, +so +that + +WoT +Interactions + + +in +a +serialized +form. + +using + +Properties +, +Action + +s +and + +Event + +s +will +be +possible. + +

      +Editor's +note + +

      +The + + +DataSchema + +expose() + + +is +under +development, +currently +it +can +denote +any +type +supported +by + +method + +MUST + +run + +the +Thing +Description + +following +steps: +

      1. +Return +a + +Promise + +promise + +and +execute + +the +WoT +Runtime + +next +steps + +in +parallel + +. +5.7 +The + +
        2. +
      2. +If +invoking + + +addProperty() + +expose() + + +method +Adds + +is +not +allowed +for +the +current +scripting +context +for +security +reasons, +reject + +promise + +with + +SecurityError + +and +terminate +these +steps. +
      3. +Make + +a +Property +defined +by + +request +to + +the +argument + +underlying +platform +to +attach +protocol +handlers + +and +updates + +start +serving +external +requests +for + +WoT +Interactions + +(read, +write +and +observe + +Properties +, +invoke + +Action + +s +and +manage + +Event + +subscriptions), +based +on + +the +Thing +Description + + +Protocol +Bindings + +. +Throws +on +error. +Returns +a +reference +to + +
        4. +
      4. +If +there +was +an +error +during + +the +same + +request, +reject + +promise + +with +an + +Error + +object +for +supporting +chaining. + + +error + +with + +error.message + +set +to +the +error +code +seen +by +the + +Protocol +Bindings + +and +terminate +these +steps. +
      5. +Otherwise +resolve + +promise + +with + +td + +and +terminate +these +steps. +

      +5.7.1 + + +5.2 + + +The + + +ThingProperty + +destroy() + + + +dictionary +<span class="idlDictionary" id= +"idl-def-thingproperty" data-idl="" data-title= +"ThingProperty">dictionary <span class= +"idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-thingproperty" class="internalDFN" data-link-type= +"dfn"> : <span class= +"idlSuperclass"><a href="#dom-semanticannotations" class= +"internalDFN" data-link-type= +"dfn"> { +<span class="idlMember" id="idl-def-thingproperty-name" data-idl="" +data-title="name" data-dfn-for= +"thingproperty"> required <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" +data-link-for="thingproperty" data-lt="" href= +"#dom-thingproperty-name" class="internalDFN" data-link-type= +"dfn"> +<span class="idlMember" id="idl-def-thingproperty-schema" data-idl= +"" data-title="schema" data-dfn-for= +"thingproperty"> required <a href= +"#dom-dataschema" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-no-default="" data-link-for="thingproperty" +data-lt="" href="#dom-thingproperty-schema" class="internalDFN" +data-link-type="dfn"> +<span class="idlMember" id="idl-def-thingproperty-value" data-idl= +"" data-title="value" data-dfn-for= +"thingproperty"> <a href= +"https://heycam.github.io/webidl/#idl-any">any<a data-no-default="" +data-link-for="thingproperty" data-lt="" href= +"#dom-thingproperty-value" class="internalDFN" data-link-type= +"dfn"> +<span class="idlMember" id="idl-def-thingproperty-writable" +data-idl="" data-title="writable" data-dfn-for= +"thingproperty"> <a href= +"https://heycam.github.io/webidl/#idl-boolean">boolean<a data-no-default="" +data-link-for="thingproperty" data-lt="" href= +"#dom-thingproperty-writable" class="internalDFN" data-link-type= +"dfn"> = <span class= +"idlMemberValue">false +<span class="idlMember" id="idl-def-thingproperty-observable" +data-idl="" data-title="observable" data-dfn-for= +"thingproperty"> <a href= +"https://heycam.github.io/webidl/#idl-boolean">boolean<a data-no-default="" +data-link-for="thingproperty" data-lt="" href= +"#dom-thingproperty-observable" class="internalDFN" data-link-type= +"dfn"> = <span class= +"idlMemberValue">false +}; + +method + + +

      +

      +Represents + +Stop +serving +external +requests +for + +the + +Thing + +Property +description. + +and +destroy +the +object. +Note +that +eventual +unregistering +should +be +done +before +invoking +this +method. + +

      +

      +The + +name + +destroy() + + +attribute +represents + +method + +MUST + +run + +the +name +of + +following +steps: +

      1. +Return +a + +Promise + +promise + +and +execute + +the +Property + +next +steps + +in +parallel + +. +
        2. +
      2. +The + +If +invoking + + +schema + +destroy() + + +attribute +represents +the +data +type + +is +not +allowed + +for +the +Property +described +by + +current +scripting +context +for +security +reasons, +reject + +promise + +with + + +DataSchema + +SecurityError + + +. + +and +terminate +these +steps. + +
        3. +
      3. +The +value +attribute +represents + +Make +a +request +to + +the +value +of + +underlying +platform +to +stop +serving +external +requests +for + +WoT +Interactions +, +based +on + +the +Property + + +Protocol +Bindings + +. +
        4. +
      4. +The + +If +there +was +an +error +during +the +request, +reject + +promise + +with +an + + +writable + +Error + + +attribute +defines +whether + +object + +error + +with + +error.message + +set +to + +the +Property + +error +code +seen +by +the + +Protocol +Bindings + + +can +be +updated. +The +default +value +is +false +. + +and +terminate +these +steps. + +
        5. +
      5. +The + +Otherwise +resolve + +promise + +with + +td + +and +terminate +these +steps. +

      + +5.3 + +The + + +observable + +addProperty() + + + +attribute +defines +whether +the + +method +

      +Adds +a + + +Property + +changes +can +be +observed + +with +name +defined +by +the + +name + +argument, +the +data +schema +provided + +by +the + +property + +argument +of +type + +PropertyFragment +, +and +optionally + +an +external +client. +The +default + +initial + +value +provided +in +the +argument + +initValue + +whose +type +should +match +the +one +defined +in +the + +type + +property +according +to +the + +value-matching +algorithm +. +If + +initValue + +is +not +provided, +it + +SHOULD + +be +initialized +as + + +false + +undefined + +. +Implementations + +SHOULD + +update +the + +Thing +Description +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +

      +
      +
      +

      + +5.8 + +5.4 + + +The + + +removeProperty() + + +method + + +

      +

      +Removes +the + +Property + +specified +by +the + +name + +argument +and +updates +the + +Thing +Description +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +

      +
      +
      +

      + +5.9 + +5.5 + + +The + + +addAction() + + +method + + +

      +

      +Adds +an +Action + +to +the + +actions + +property +of +a + +Thing + +object +as + +an + +Action + +with +name + +defined +by +the +action + + +name + +argument, +defines +input +and +output +data +format +by +the + +init + +argument +of +type + + +ThingAction + +ActionFragment + + +, +and +adds +the +function +provided +in +the + +action + +argument +as +a +handler, +then + +updates +the + +Thing +Description +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +

      +5.9.1 +The +ThingAction +dictionary +<span class="idlDictionary" id= +"idl-def-thingaction" data-idl="" data-title= +"ThingAction">dictionary <span class= +"idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-thingaction" class="internalDFN" data-link-type= +"dfn"> : <span class= +"idlSuperclass"><a href="#dom-semanticannotations" class= +"internalDFN" data-link-type= +"dfn"> { +<span class="idlMember" id="idl-def-thingaction-name" data-idl="" +data-title="name" data-dfn-for= +"thingaction"> required <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" +data-link-for="thingaction" data-lt="" href="#dom-thingaction-name" +class="internalDFN" data-link-type= +"dfn"> +<span class="idlMember" id="idl-def-thingaction-inputschema" +data-idl="" data-title="inputSchema" data-dfn-for= +"thingaction"> <a href= +"#dom-dataschema" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-no-default="" data-link-for="thingaction" +data-lt="" href="#dom-thingaction-inputschema" class="internalDFN" +data-link-type="dfn"> +<span class="idlMember" id="idl-def-thingaction-outputschema" +data-idl="" data-title="outputSchema" data-dfn-for= +"thingaction"> <a href= +"#dom-dataschema" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-no-default="" data-link-for="thingaction" +data-lt="" href="#dom-thingaction-outputschema" class="internalDFN" +data-link-type="dfn"> +}; + +

      +The +ThingAction + +provided + +action + +callback +function +will +implement +invoking +an + +Action + + +dictionary +describes +the +arguments + +and + +SHOULD + +be +called +by +implementations +when +a +request +for +invoking + +the +return +value. +The +name +attribute +provides +the + + +Action + +name. +The +inputSchema +attribute +provides +the +description +of +the +input +arguments +(argument +list + +is +represented +by +an +object). +If +missing, +it +means + +received +from + +the +action +does +not +accept +arguments. + +underlying +platform. + +The +callback +will +receive +a + + +outputSchema + +parameters + + +attribute +provides + +dictionary +argument +according +to + +the +description + +definition +in +the + +init.input + +argument +and +will +return +a +value + +of +type +defined +by + +the +returned +data. +If +missing, +it +means + + +init.output + +argument +according +to + +the +action +does +not +return +data. + + +value-matching +algorithm +.

      +There + +SHOULD + +be +exactly +one +handler +for +any +given + +Action +. +If +no +handler +is +initialized +for +any +given + +Action +, +implementations + +SHOULD + +throw +a + +TypeError +.

      +
      +
      +

      + +5.10 + +5.6 + + +The + + +removeAction() + + +method + + +

      +

      +Removes +the + +Action + +specified +by +the + +name + +argument +and +updates +the + +Thing +Description +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +

      +
      +
      +

      + +5.11 + +5.7 + + +The + + +addEvent() + + +method + + +

      +

      +Adds +an +event +to +the +Thing +object +as + +with +name + +defined +by +the + +name + +argument +and +qualifiers +and +initialization +value +provided +by +the + +event + +argument +of +type + + +ThingEvent + +EventFragment + + + +to +the + +Thing + +object + +and +updates +the + +Thing +Description +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +

      +5.11.1 +The +ThingEvent +dictionary +<span class="idlDictionary" id= +"idl-def-thingevent" data-idl="" data-title= +"ThingEvent">dictionary <span class= +"idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-thingevent" class="internalDFN" data-link-type= +"dfn"> : <span class= +"idlSuperclass"><a href="#dom-semanticannotations" class= +"internalDFN" data-link-type= +"dfn"> { +<span class="idlMember" id="idl-def-thingevent-name" data-idl="" +data-title="name" data-dfn-for= +"thingevent"> required <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" +data-link-for="thingevent" data-lt="" href="#dom-thingevent-name" +class="internalDFN" data-link-type= +"dfn"> +<span class="idlMember" id="idl-def-thingevent-schema" data-idl="" +data-title="schema" data-dfn-for= +"thingevent"> <a href= +"#dom-dataschema" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-no-default="" data-link-for="thingevent" +data-lt="" href="#dom-thingevent-schema" class="internalDFN" +data-link-type="dfn"> +}; +The +name +attribute +represents +the +event +name. +The +schema +attribute +represents +the +type +of +the +data +that +is +attached +to +the +event. +If +missing, +it +means +the +event +does +not +carry +data. + +
      +
      +

      +5.12 + + +5.8 + + +The + + +removeEvent() + + +method + + +

      +

      +Removes +the +event +specified +by +the + +name + +argument +and +updates +the + +Thing +Description +. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +

      +
      +
      +

      + +5.13 + +5.9 + + +The + + +PropertyReadHandler + + +callback + + +

      +

      +A +function +that +returns + +is +called +when +an +external +request +for +reading +a + +Property + +is +received. +It +should +return + +a +Promise +and +resolves +it +with +the +value +of +the + +Property + +matching +the + +name + +argument +to +the + +setPropertyReadHandler + +function, +or +rejects +with +an +error +if +the +property +is +not +found +or +the +value +cannot +be +retrieved. +

      +
      +
      +

      + +5.14 + +5.10 + + +The + + +PropertyWriteHandler + + +callback + + +

      +

      +A +function +that +is + +called +with + +when +an +external +request +for +writing +a + +Property + +is +received. +It +is +given +the +requested +new + + +value + +as +argument +that +returns + +and +should +return + +a +Promise +which +is +resolved +when +the +value +of +the + +Property + +matching + +that +matches + +the + +name + +argument +to +the +setPropertyReadHandler +function +is + +has +been + +updated +with + +value +, +or +rejects +with +an +error +if +the +property +is +not +found +or +the +value +cannot +be +updated. +

      +
      +
      + +Editor's +note + +
      +

      +Note +that +this +function +is +invoked +by +implementations +before +the +property +is +updated, +so +the + +updated +and +it +actually +defines +what +to +do +when +a +write +request +is +received. +The + +code +in +this +callback +function +can +invoke +the + +readProperty() + +read() + + +method +to +find +out +the +old +value +of +the +property, +if +needed. +Therefore +the +old +value +is +not +provided +to +this +method. + +function. + +

      +
      +
      +
      +

      + +5.15 + +5.11 + + +The + + +ActionHandler + + +callback + + +

      +

      +A +function +called +with +a + +parameters + +dictionary +argument +assembled +by +the + +WoT +runtime + +based +on +the + +Thing +Description + +and +the +external +client +request. +It +returns +a +Promise +that +rejects +with +an +error +or +resolves +if +the +action +is +successful +or +ongoing +(may +also +resolve +with +a +control +object +such +as +an + + +Observable + + +for +actions +that +need +progress +notifications +or +that +can +be +canceled). +

      +
      +
      +

      + +5.16 + +5.12 + + +The + + +setPropertyReadHandler() + + +method + + +

      +

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

      +

      +The + +readHandler + +callback +function +will +implement +reading +a + +Property + +and + +SHOULD + +be +called +by +implementations +when +a +request +for +reading +a + +Property + +is +received +from +the +underlying +platform. +

      +

      +There + +SHOULD + +be +at +most +one +handler +for +any +given + +Property + +and +newly +added +handlers +replace +the +old +handlers. +If +no +handler +is +initialized +for +any +given + +Property +, +implementations + +SHOULD + +implement +a +default +property +read +handler. +

      +

      +When +an +external +request +for +reading + +Property + +propertyName + +is +received, +the +runtime + +SHOULD + +execute +the +following +steps: +

      1. +Return +a + +Promise + +promise + +and +execute +the +next +steps + +in +parallel +.
      2. +If +a + +Property + +with + +propertyName + +does +not +exist, +reject + +promise + +with +a + +ReferenceError + +and +terminate +these +steps. +
      3. +Otherwise, +if +no +read +handler +has +been +defined +for + +propertyName +, +resolve + +promise + +with +the +value +of +the + +Property + +named + +propertyName + +provided +by +the +runtime +implementation +and +terminate +these +steps. +
      4. +Otherwise, +invoke +the +read +handler +associated +with + +propertyName +. +If +it +rejects, +then +reject + +promise + +with +the +same +error, +and +resolve + +promise + +with +the +same +value. +
      +
      +
      +

      + +5.17 + +5.13 + + +The + + +setPropertyWriteHandler() + + +method + + +

      +

      +Takes + +name + +as +string +argument +and + +writeHandler + +as +argument +of +type + + +PropertyWriteHandler + +. +Sets +the +handler +function +for +writing +the +specified + +Property + +matched +by + +name +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +

      +

      +There + +SHOULD + +be +at +most +one +write +handler +for +any +given + +Property + +and +newly +added +handlers +replace +the +old +handlers. +If +no +write +handler +is +initialized +for +any +given + +Property +, +implementations + +SHOULD + +implement +default +property +update +and +notifying +observers +on +change. +

      +

      +When +an +external +request +for +writing +a + +Property + +propertyName + +with +a +new +value + +value + +is +received, +the +runtime + +SHOULD + +execute +the +following +steps: +

      1. +Return +a + +Promise + +promise + +and +execute +the +next +steps + +in +parallel +.
      2. +If +a + +Property + +with + +propertyName + +does +not +exist, +reject + +promise + +with +a + +ReferenceError + +and +terminate +these +steps. +
      3. +Otherwise, +if +no +write +handler +has +been +defined +for + +propertyName +, +the +runtime +implementation + +SHOULD + +update +the + +Property + +value +with + +value +, +resolve + +promise + +and +terminate +these +steps. +
      4. +Otherwise, +invoke +the +write +handler +associated +with + +propertyName + +providing + +value + +as +argument. +If +it +rejects, +then +reject + +promise + +with +the +same +error, +and +resolve + +promise + +with +the +same +value. +
      +
      +
      +

      + +5.18 + +5.14 + + +The + + +setActionHandler() + + +method + + +

      +

      +Takes + +name + +as +string +argument +and + +action + +as +argument +of +type + + +ActionHandler + +. +Sets +the +handler +function +for +the +specified + +Action + +matched +by + +name +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +

      +

      +If +provided, +this + +The + +action + +callback +function +will +implement +invoking + +an + +Action + +and + +SHOULD + +be +called +by +implementations +when +a +request +for +invoking +a + +the + +Action + +is +received +from +the +underlying +platform. +The +callback +will +receive +a +parameters +dictionary +argument. + +

      +

      +There + +SHOULD + +be +exactly + +at +most + +one +handler +for +any +given + +Action + +and +newly +added +handlers +replace +the +old +handlers. +

      +When +an +external +request +for +invoking +the + +Action + +identified +by + +name + +is +received, +the +runtime + +SHOULD + +execute +the +following +steps: +

      1. +Return +a + +Promise + +promise + +and +execute +the +next +steps + +in +parallel + +. +
        2. +
      2. +If +an + +Action + +identified +by + +name + +does +not +exist, +reject + +promise + +with +a + +ReferenceError + +and +terminate +these +steps. +
      3. +Otherwise, +if + +no +action + +handler +is +initialized + +has +been +defined + +for +any +given + + +name +, +reject + +promise + +with +a + +ReferenceError + +and +terminate +these +steps. +
      4. +Otherwise, +invoke +the + + +Action +, +implementations +SHOULD +return + + +handler +associated +with + +name +. +If +it +rejects +with + +error +, +then +reject + +promise + +with +the +same + +error +, +otherwise + +if +it +resolves +with + +value +, +then +resolve + +promise + +with + +the +action +is +invoked +by +any +client. + +same + +value +.
      +
      +
      +

      + +5.19 + +5.15 + + +Examples + + +

      +

      +Below +some + + + +ExposedThing + + + +interface +examples +are +given. +

      +
      +
      + +Example +7 + +5 + +: + +: +Create +a +new +blank + +exposed +Thing +with +a +simple +property + + +
      +
      +        try {
+  "hljs-keyword">var thing = WoT.produce({ <span class=
+"hljs-attr">name: <span class=
+"hljs-string">"tempSensor" });
+  
+  thing.addProperty({
+    : <span class=
+"hljs-string">"temperature",
+    : <span class=
+"hljs-number">0.0,
+    : <span class=
+"hljs-string">'{ "type": "number" }'
+    <span class=
+"hljs-comment">// use default values for the rest
+  }).addProperty({
+    : <span class=
+"hljs-string">"max",
+    : <span class=
+"hljs-number">0.0,
+    : <span class=
+"hljs-string">'{ "type": "number" }'
+    <span class=
+"hljs-comment">// use default values for the rest
+  }).addAction({
+    : <span class=
+"hljs-string">"reset",
+    
+  }).addEvent({
+
+"hljs-keyword">var temperatureValueDefinition = {
+    type: 
+"hljs-string">"number",
+    minimum: 
+"hljs-number">-50,
+    maximum: 
+"hljs-number">10000
+  };
+  
+"hljs-keyword">var temperaturePropertyDefinition = temperatureValueDefinition;
+  // add the 'forms' property
+  temperaturePropertyDefinition.forms = [ ... ];
+  var thing = WoT.produce({
+    name: "hljs-string">"onchange",
+    : <span class=
+"hljs-string">'{ "type": "number" }'
+  });
+  
+  thing.setActionHandler(<span class=
+"hljs-string">"reset", () => {
+    .log(<span class=
+"hljs-string">"Resetting maximum");
+    thing.writeProperty(<span class=
+"hljs-string">"max");
+  });
+  thing.start().then(<span class=
+"hljs-params">() {
+      thing.register();
+
+"hljs-string">"tempSensor",
+    properties: {      
+"hljs-attr">temperature: temperaturePropertyDefinition
+    },
+    actions: {      reset: {        description: 
+"hljs-string">"Reset the temperature sensor",
+        input: {          
+"hljs-attr">temperature: temperatureValueDefinition
+        },
+        output: 
+"hljs-literal">null,
+        forms: []
+      },
+    },
+    events: {      
+"hljs-attr">onchange: temperatureValueDefinition
+    },
+    links: []
+  });
+  await thing.expose();
+  await wot.register("hljs-string">"https://mydirectory.org", thing);
+
+  // define Thing business logic
+  setInterval( async () => {
+    let mock = Math.random()*100;
+    thing.writeProperty(<span class=
+"hljs-string">"temperature", mock);
+
+    let old = "hljs-keyword">await thing.readProperty(<span class=
+"hljs-string">"max");
+
+"hljs-keyword">await thing["temperature"].read();
+
+    if (old < mock) {
+      thing.writeProperty(<span class=
+"hljs-string">"max", mock);
+      thing.emitEvent();
+
+      await thing["hljs-string">"temperature"].write(mock);
+      thing.emitEvent("onchange", mock);
+
+    }
+  }, 1000);
+} catch (err) {
+   console.log("Error creating ExposedThing: " + err);
+}
+
      +
      +
      +
      + +Example +8 + +6 +: +Create +a +new +exposed +Thing +with +object +property + + +: + +
      +
      +        try {
+  var statusValueDefinition = {
+    type: "hljs-string">"object",
+    properties: {      brightness: {        type: 
+"hljs-string">"number",
+        minimum: 
+"hljs-number">0.0,
+        maximum: 
+"hljs-number">100.0,
+        required: 
+"hljs-literal">true
+      },
+      rgb: {        type: 
+"hljs-string">"array",
+        "minItems": 
+"hljs-number">3,
+        "maxItems": 
+"hljs-number">3,
+        items : {            "type" : 
+"hljs-string">"number",
+            
+"hljs-string">"minimum": 0,
+            
+"hljs-string">"maximum": 255
+        }
+      }
+  };
+  
+"hljs-keyword">var statusPropertyDefinition = statusValueDefinition;
+  // add the 'forms' property
+  statusPropertyDefinition["forms"] = [];
+  var thing = WoT.produce({    name: 
+"hljs-string">"mySensor",
+    properties: {      brightness: {        type: 
+"hljs-string">"number",
+        minimum: 
+"hljs-number">0.0,
+        maximum: 
+"hljs-number">100.0,
+        required: 
+"hljs-literal">true,
+      },
+      
+"hljs-attr">status: statusPropertyDefinition
+    },
+    actions: {      status: {        description: 
+"hljs-string">"Get status object",
+        input: 
+"hljs-literal">null,
+        output: {          
+"hljs-attr">status : statusValueDefinition;
+        },
+        forms: []
+      },
+    },
+    events: {      
+"hljs-attr">onstatuschange: statusValueDefinition;
+    },
+    links: []
+  });
+  thing.expose().then(() => {
+      thing.register();
+  });
+} catch (err) {
+   console.log(
+"hljs-string">"Error creating ExposedThing: " + err);
+}
+
      +Example +7 +: +Create +a +new +exposed +Thing +from +a +Thing +Description + +
      +
      +        let thingDescription = "hljs-string">'{ "@context": [ "https://w3c.github.io/wot/w3c-wot-td-context.jsonld", "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ], "@type": [ "Thing", "Sensor" ], "name": "mySensor", "geo:location": "testspace", "interaction": [ { "@type": [ "Property", "Temperature" ], "name": "prop1", "schema": { "type": "number" }, "saref:TemperatureUnit": "degree_Celsius" } ] }';
+
+"hljs-string">'{ \
+  "name": "mySensor", \
+  "@context": [ "http://www.w3.org/ns/td",\
+     "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ],\
+  "@type": [ "Thing", "Sensor" ], \
+  "geo:location": "testspace", \
+  "properties": { \
+    "prop1": { \
+      "type": "number",\
+      "@type": [ "Property", "Temperature" ], \
+      "saref:TemperatureUnit": "degree_Celsius" \
+  } } }';
+
+try {
+  // note that produce() fails if thingDescription contains error
+  let thing = WoT.produce(thingDescription);
+  // Interactions were added from TD
+  // WoT adds generic handler for reading any property
+  // define a specific handler for one property
+  let name = "examplePropertyName";
+  thing.setPropertyReadHandler(name, () => {
+    console.log("Handling read request for " + name);
+    return new Promise((resolve, reject) => {
+        let examplePropertyValue = 5;
+        resolve(examplePropertyValue);
+      },
+      e => {
+        console.log("Error");
+      });
+  });
+  thing.start();
+
+  thing.expose();
+
+} catch(err) {
+   console.log("Error creating ExposedThing: " + err);
+}
+
      +
      +
      +
      + +Example +9 + +8 + +: + +: +Create +a +new +exposed +Thing +from +a +TD +URI + +
      +
      +        // fetch an external TD, e.g., to set up a proxy for that Thing
+WoT.fetch("http://myservice.org/mySensor/description").then(td => {
+  // WoT.produce() ignores instance-specific metadata (security, form)
+  let thing = WoT.produce(td);
+  // Interactions were added from TD
+  // add server functionality
+  // ...
+});
+
      +
      +
      +
      +
      +

      + +6. + +Experimental +extensions +to +the +ConsumedThing +interface + +Data +types +and +structures + +

      +

      +The +[ + +This +section +is +non-normative. + + +WOT-TD + + +] +specification +defines +the + +WoT +information +model +, +i.e. +the +data +types +and +data +structures +used +in + +WoT +Interactions +. +In +this +API +these +definitions +translate +to +dictionary +objects +that +are +extended +with +methods +by +the +interfaces +defined +in +this +specification. + +

      +

      +In +order +to +avoid +duplication +of +definitions, +references +to +these +data +types +and +structures +is +defined +in +this +section, +but +for +their +full +description +please +refer +to +the + +Thing +Description +specification +.

      +6.1 + +The + + +ThingDescription + +DataSchema + + + +dictionary +and +its +subclasses + + +related +functionality, +such +as +enumerating + +

      +

      +Value +types +basically +represent +types +that +may +be +used +in + +JSON + +object +definitions +and +are +used +in + +ThingFragment + +to +define + +Properties +, +Action +s, + + +Event + +s +and +links +(introspection) + + +Action + +parameters. +Value +types +are +represented +as +dictionary +objects +whose +properties +and +possible +sub-classes +are +defined +in +the + +DataSchema + +section +of +[ + +WOT-TD + +]. +

      +One +property +of +all + +DataSchema + +dictionary + +is +an +API +extension +that + +the + +type + +property +whose +value + +is +out + +from +a +set + +of +scope +for + +enumerated +strings +defined +in +the + +DataSchema + +section +of +[ + +WOT-TD + +] +and +is +referred +as + +DataType + +in + +this +specification. +However, + +

      +

      +Based +on + +type +, +the +draft +interfaces + +following +sub-classes +of + +DataSchema + +are +defined +here +for +informative +purposes. +<span class="idlInterface" id= +"idl-def-consumedthing-partial-1" data-idl="" data-title= +"ConsumedThing">partial interface <span class= +"idlInterfaceID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-consumedthing" class="internalDFN" data-link-type= +"dfn"> { +<span class="idlMethod" id="idl-def-consumedthing-getproperties" +data-idl="" data-title="getProperties" data-dfn-for= +"consumedthing"> <a href= +"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-thingproperty" +class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="consumedthing" +data-lt="getproperties()|getProperties" href= +"#dom-consumedthing-getproperties" class="internalDFN" +data-link-type="dfn">getProperties +<span class="idlMethod" id="idl-def-consumedthing-getactions" +data-idl="" data-title="getActions" data-dfn-for= +"consumedthing"> <a href= +"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-thingaction" +class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="consumedthing" +data-lt="getactions()|getActions" href= +"#dom-consumedthing-getactions" class="internalDFN" data-link-type= +"dfn">getActions +<span class="idlMethod" id="idl-def-consumedthing-getevents" +data-idl="" data-title="getEvents" data-dfn-for= +"consumedthing"> <a href= +"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-thingevent" +class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="consumedthing" +data-lt="getevents()|getEvents" href="#dom-consumedthing-getevents" +class="internalDFN" data-link-type= +"dfn">getEvents +<span class="idlMethod" id="idl-def-consumedthing-getlinks" +data-idl="" data-title="getLinks" data-dfn-for= +"consumedthing"> <a href= +"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-tdlink" +class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="consumedthing" +data-lt="getlinks()|getLinks" href="#dom-consumedthing-getlinks" +class="internalDFN" data-link-type= +"dfn">getLinks +}; + +in +[ + + +WOT-TD + + +]: + +6.1 + + +BooleanSchema +, +NumberSchema +, +IntegerSchema +, +StringSchema +, +ObjectSchema +, +ArraySchema +.

      +6.2 + + +The + + +getProperties() + +SecurityScheme + + + +method + +dictionary +and +its +subclasses + +

      +

      +Returns +the +list +of +Properties + +Security +metadata +is +represented +as +dictionary +objects +whose +properties +and +sub-classes +are + +defined +in +the +Thing +Description + + +SecurityScheme + + +section +of +[ + +WOT-TD + +]. +

      +One +property + +of +the +Thing + + + +SecurityScheme + + +dictionary +is +the + +scheme + +property +whose +value +is +from +a +set +of +enumerated +strings +defined + +in +the +form + + +SecurityScheme + +section + +of +a +list + +[ + +WOT-TD + +]. +Based +on + +type +, +multiple +subclasses + +of + + +ThingProperty + +SecurityScheme + + + +objects. + +are +defined. + +

      +
      +

      +6.4 + +The + +Form + +dictionary +

      +Represents +metadata +describing +service +details, +with +properties + +defined +in +the +Thing +Description + + +Form + + +section + +of +[ + +WOT-TD + +]. +

      +6.5 + +The + +InteractionFragment + +dictionary +

      +Represents + +the +Thing + +common +properties +of + +WoT +Interactions +, +one +of + +Property +, +Action + + +or + +Event +, +as +defined + +in +the +form + + +InteractionPattern + +section + +of +[ + +WOT-TD + +]. +Its +subclasses +are +referred +as + +PropertyFragment +, +ActionFragment + +and + +EventFragment +.

      +6.6 + +The + +PropertyFragment + +dictionary +

      +Represents +the + +Property + +interaction +data +that +initializes + +a +list + + + +ThingProperty + +object. +Its +properties +are +defined +in +the + +Property + +and + +InteractionPattern + +sections + +of +[ + +WOT-TD + +]. +

      +6.7 + +The + +ActionFragment + +dictionary +

      +Represents +the + +Action + +interaction +data +that +initializes +a + + + +ThingAction + + +objects. + +object. +Its +properties +are +defined +in +the + +Action + +and + +InteractionPattern + +sections +of +[ + +WOT-TD + +]. + +

      +
      +
      +

      +6.3 + + +6.8 + + +The + + +getEvents() + +EventFragment + + + +method + +dictionary + +

      +

      +Returns + +Represents + +the +list +of + + +Event + +s + +interaction +data +that +initializes +a + +ThingEvent + +object. +Its +properties +are + +defined +in +the +Thing +Description + + +Event + + +section + +of +the + +[ + +WOT-TD + +]. +

      +6.9 + +The + +ThingFragment + +dictionary +

      +The + +ThingFragment + +dictionary +is +defined +as + +Thing + + +in +the +form +of + +[ + +WOT-TD + +]. +It +is + +a +list + +dictionary +that +contains +properties +representing +semantic +metadata +and +interactions +( + +Properties +, +Action + +s +and + +Event + +s). +It +is +used +for +initializing +an +internal +representation + +of +a + +Thing +Description + +and +its +properties +may +be +used +in + + +ThingEvent + +ThingFilter + + +objects. + +. +

      +
      +
      +

      +6.4 + + +6.10 + + +The + + +getLinks() + +ThingDescription + + + +method + +type + +

      +

      +Returns +the +list + +Serialized +representation + +of +linked +resources +in + +the + + +Thing +Description + +(a + +JSON-LD + +document). +

      +Note +

      +In +this +version + +of +the +API, + +Thing +Description + +s +are +represented +as +an +opaque + +USVString + +that +can +be +transmitted +between +devices. +

      +7. + +Interfaces +for + +WoT +Interactions +

      +The +data +types +and +structures +imported +from +[ + +WOT-TD + + + +] +are +extended +by +this +specification + +in +order +to +provide + +the +form +of +a +list +of + +interfaces +for + +WoT +Interactions +.

      +Every + +Thing + +describes +its +metadata +as +defined +in + + +TDLink + +ThingFragment + + +, +and +basic +interactions +defined +as + +Properties +, +Action + + +objects. + +s +and + +Event + +s. +The +following +interfaces +are +used +for +representing +these +interactions. + +

      +
      +

      + +6.4.1 + +7.1 + + +The + + +TDLink + +Interaction + + + +dictionary + +interface +

      +

      +Contains +a +hyperlink +reference, +a +relation +type + +The + +Interaction + +interface +is +an +abstract +class +to +represent + +Thing + +interactions: + +Properties +, +Actions + +and + +Events +.

      +The + +InteractionFragment + +dictionary +holds +the +common +properties +of + +PropertyFragment +, +ActionFragment + +and + + +EventFragment + +dictionaries +used +for +initializing + +ThingProperty +, +ThingAction + +and + +ThingEvent + +objects +in + +a +media +type. + + + +ThingFragment + +dictionary +used +for +creating +an + +ExposedThing + +object. + +

      +
      +<span class="idlDictionary" id= +"idl-def-tdlink" data-idl="" data-title= +"TDLink">dictionary <span class= +"idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-tdlink" class="internalDFN" data-link-type= +"dfn"> { +<span class="idlMember" id="idl-def-tdlink-href" data-idl="" +data-title="href" data-dfn-for="tdlink"> required <span class= +"idlMemberType"><a href= +"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default="" +data-link-for="tdlink" data-lt="" href="#dom-tdlink-href" class= +"internalDFN" data-link-type= +"dfn"> +<span class="idlMember" id="idl-def-tdlink-mediatype" data-idl="" +data-title="mediaType" data-dfn-for= +"tdlink"> <a href= +"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default="" +data-link-for="tdlink" data-lt="" href="#dom-tdlink-mediatype" + +
      "idl-def-interaction" data-idl="" data-title=
+"Interaction">interface Interaction {
+  readonly attribute (Form or FrozenArray<Form>) 
+class="internalDFN" data-link-type=
+"dfn">
+<span class="idlMember" id="idl-def-tdlink-rel" data-idl=""
+data-title="rel" data-dfn-for="tdlink">             <span class=
+"idlMemberType"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default=""
+data-link-for="tdlink" data-lt="" href="#dom-tdlink-rel" class=
+"internalDFN" data-link-type=
+"dfn">
+};
+
+"dfn">forms;
+};
+
+"dfn">Interaction includes 
+
+InteractionFragment
+
+;
+
+
+
      +
      +

      +The + + +TDLink + +forms + +read-only +property +represents +the +protocol +bindings +initialization +data +and +is +initialized +by +the + +WoT +Runtime +.

      +7.2 + +The + +ThingProperty + +interface +

      +The + +ThingProperty + +interface +is +used +in + +ConsumedThing + +and + +ExposedThing + +objects +to +represent + +Thing + +Property + +interactions. +

      +The + +PropertyFragment + + + +dictionary +contains + +is +used +for +initializing + +Property + +objects +in +a + +ThingFragment + +dictionary +used +for +creating +an + +ExposedThing + +object. +It + +MUST + +implement +one +of + +the +following +properties: + + + +DataSchema + +dictionaries. + +

      +
      +
      "idl-def-thingproperty" data-idl="" data-title=
+"ThingProperty">interface ThingProperty : Interaction {
+  // getter for PropertyFragment properties
+  getter 
+"https://heycam.github.io/webidl/#idl-any">any (DOMString name);
+  // get and set interface for the Property
+  
+"https://heycam.github.io/webidl/#idl-promise">Promise<any> read();
+  
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> write(any value);
+};
+
+"dfn">ThingProperty includes PropertyFragment;
+
+"dfn">ThingProperty includes 
+
+Observable
+
+;
+

      +The + + +href + +ThingProperty + +interface +contains +all +the +properties +defined +on + +PropertyFragment + + + +as +read-only +properties. +

      +The + +type + + +attribute + +read-only +property + +represents +the +type +definition +for +the + +Property + +as + +a +hyperlink +reference + + + +DataSchema + +dictionary +object. +

      +The + +writable + +read-only +property +tells +whether +the + +Property + +value +can +be +updated. +If +it +is + +false +, +then +the + +set(value) + +method + +SHOULD + +always +reject. +

      +The + +observable + +read-only +property +tells +whether +the + +Property + +supports +subscribing +to +value +change +notifications. +If +it +is + +false +, +then +the + +subscribe() + +method + +SHOULD + +always +fail. +

      +The + +constant + +read-only +property +- +defined +in + +DataSchema + +- +tells +whether +the + +Property + +value +is +a +constant. +If + +true +, +the + +set() + +and + +subscribe() + +methods + +SHOULD + +always +fail. +

      +The + +required + +read-only +property +- +defined +in + +DataSchema + +- +tells +whether +the + +Property + +should +be +always +present +on +the + +ExposedThing + +object. +

      +The + +read() + +method +will +fetch +the +value +of +the + +Property + +. +Returns +a + +Promise + +that +resolves +with +the +value, +or +rejects +with +an +error. +

      +The + + +rel + +write() + + + +attribute +represents + +method +will +attempt +to +set +the +value +of +the + +Property + +specified +in +the + +value + +argument +whose +type + +SHOULD + +match +the +one +specified +by +the + +type + +property. +Returns + +a +relation + + +Promise + +that +resolves +on +success, +or +rejects +on +an +error. +

      +7.3 + +The + +ThingAction + +interface +

      
+"idl-def-thingaction" data-idl="" data-title=
+"ThingAction">interface ThingAction : Interaction {
+  
+"https://heycam.github.io/webidl/#idl-promise">Promise<any> invoke(optional any inputValue);
+};
+
+"dfn">ThingAction includes 
+
+ActionFragment
+
+;
+

      +The + +invoke() + +method +when +invoked, +starts +the + +Action + +interaction +with +the +input +value +provided +by +the + +inputValue + +argument. +If + +inputValue + +is + +null +, +the +action +does +not +take +any +arguments +and +rejects +if +any +arguments +are +provided. +If +the +value +is + +undefined +, +the +action +will +ignore +any +arguments +provided. +Otherwise +the + +type +of + +inputValue + +SHOULD + +match +the + +DataSchema + +definition +in +the + +input + +property. +Returns +a + +Promise + +that +will +reject +with +an +error +or +will +resolve +with +a +value +of +type +defined +by +the + +output + +property. +

      +7.4 + +The + +ThingEvent + +interface +

      
+"idl-def-thingevent" data-idl="" data-title=
+"ThingEvent">interface ThingEvent : Interaction {
+};
+
+"dfn">ThingEvent includes EventFragment;
+
+"dfn">ThingEvent includes 
+
+ThingProperty
+
+;
+

      +Since + +ThingEvent + +implements + +Observable + +through +the + +ThingProperty + +interface, +event +subscription +is +done +by +invoking +the + +subscribe() + +method +on +the +event +object +that +returns +a +cancelable + +Subscription + +. +

      +
      +
      +

      + +7.5 + +The + + +mediaType + +ExposedEvent + + + +attribute +represents + +interface +

      
+"idl-def-exposedevent" data-idl="" data-title=
+"ExposedEvent">interface ExposedEvent : ThingEvent {
+  void emit(any payload);
+};
+

      +7.5.1 + +The + +emit() + +method +

      +Emits +an +event +that +carries +data +specified +by +the + +payload + +argument. +

      +7.6 + +The + +value-matching +algorithm +

      +The +value-matching +algorithm +is +applied +to + +a +IANA +media + + +value + +input +in +relation +to +a + +valueType + +property +of + +type +. +For +TD + + + +DataSchema +, +for +instance +the + +value + +and + +type + +properties +of +a + +PropertyFragment + + +s +there +will +be +registered +media +types, +so +applications +will +be +able + +object, +or +the + +inputValue + +parameter + +to +check +whether +an + +the + + +href + +invoke() + + +link +points + +method +of +a + +ThingAction + +object +in +relation + +to +the +same +object. +It +executes +the +following +steps: +

      1. +If + +valueType.type + +is +not +defined, +or +does +not +fully +match + +a +TD + +string +enumerated +in + +DataType + +, +i.e. +whether + +return + +false +.
      2. +Otherwise, +if + +valueType.type + +is + +"null" +: +if + +value + +is + +null +, +return + +true +, +otherwise +return + +false +.
      3. +Otherwise, +if + +valueType.type + +is + +"boolean" +: +if + +value + +is +either + +true + +or + +false +, +then +return + +true +, +otherwise +return + +false +.
      4. +Otherwise, +if + +valueType.type + +is + +"integer" +: +if + +value + +is +not +an +integer +type +defined +by + +the +link + +underlying +platform +(such +as + +long + +or + +long +long + +), +then +return + +false +, +otherwise +execute +the +following +sub-steps: +
        1. +If + +valueType.minimum + +is +fetcheable +with + +defined +and + +value + +is +not +greater +or +equal +than +that +value, +return + +false +.
        2. +If + +valueType.maximum + +is +defined +and + +value + +is +not +less +or +equal +than +that +value, +return + +false +.
        3. +Return + +true +.
      5. +Otherwise, +if + +valueType.type + +is + +"number" +, +if + +value + +is +not +an +integer +or +floating +point +type +defined +by +the +underlying +platform +(such +as + +long + +or + +long +long + +or + +double + +), +then +return + +false +, +otherwise +otherwise +execute +the +following +sub-steps: +
        1. +If + +valueType.minimum + +is +defined +and + +value + +is +not +greater +or +equal +than +that +value, +return + +false +.
        2. +If + +valueType.maximum + +is +defined +and + +value + +is +not +less +or +equal +than +that +value, +return + +false +.
        3. +Return + +true +.
      6. +Otherwise, +if + +valueType.type + +is + +"string" +: +if + +value + +is +not +a +string +type +defined +by +the +underlying +platform, +then +return + +false +, +otherwise +return + +true +. +In + +this +API. + +case +the +algorithm +expects +a +third +parameter + +valueType.enum + +and +runs +the +following +sub-steps: +
        • +If + +valueType.enum + +is +an +array +of +strings, +then +if + +value + +fully +matches +one +of +the +strings +defined +in +the +array, +return + +true +.
        • +Otherwise, +return + +false +. +
          • +
        +
        7. +
      7. +Otherwise, +if + +valueType.type + +is + +"array" +, +execute +the +following +sub-steps: +
        1. +If + +value + +is +not +an +array, +return + +false +.
        2. +If + +valueType.minItems + +is +defined, +and + +value + +does +not +contain +at +least + +valueType.minItems + +elements, +return + +false +.
        3. +If + +valueType.maxItems + +is +defined, +and + +value + +contains +more +than + +valueType.maxItems + +elements, +return + +false +.
        4. +Otherwise, +if + +valueType.items + +is + +undefined +, +return + +false +.
        5. +Otherwise, +if + +valueType.items + +is + +null +, +return + +true + +(i.e. +any +type +is +accepted +as +array +element, +including +heterogenous +arrays). +
        6. +Otherwise, +for +each +element +of +the +array + +value + +run +the + +value-matching +algorithm + +against +the + +valueType.items + +object. +If +any +of +these +runs +returns + +false +, +then +return + +false +.
        7. +Otherwise, +return + +true +.
      8. +Otherwise, +if + +type + +is + +"object" +, +execute +the +following +sub-steps: +
        1. +If + +value + +is +not +an + +Object +, +return + +false +.
        2. +If + +valueType.properties + +is +not +defined, +return + +false +.
        3. +If + +valueType.properties + +is + +null +, +return + +true + +(i.e. +accept +any +object +value). +
        4. +For +each +string +in +the + +valueType.required + +array, +if +it +does +not +match +a +property +name +in +the + +value.properties + +object +or +in +the + +value + +object, +then +return + +false +.
        5. +For +each +property +with +name + +propName + +and +value + +propDataSchema + +found +in + +valueType.properties +, +run +the +following +sub-steps: +
          1. +If +the +result +of +applying +the + +value-matching +algorithm + +on +the +value + +value[propName] + +and + +propDataSchema + +is + +false +, +then +return + +false +.
        6. +Return + +true +.
      +
      +
      +
      +

      + +7. + +8. + + +Observables + + +

      +

      + +This +section +is +non-normative. + +

      +

      + +Observables + +are + +proposed + +to +be +included +in +ECMAScript +and +are +used +for +handling +pushed +data +associated +with +various +possible +sources, +for +instance +events, +timers, +streams, +etc. +A +minimal +required +implementation +is +described +here. +

      +
      +
      + +Editor's +note + +
      +

      +This +section +is +informal +and +contains +rather +laconic +information +for +implementations +on +what +to +support +for +interoperability. +

      +
      +
      +
      interface "dfn"> {
+<span class="idlMethod" id=
+"idl-def-observable-subscribe-next-error-complete" data-idl=""
+data-title="subscribe" data-dfn-for="observable">    <span class=
+"idlMethType"><a href="#dom-subscription" class="internalDFN"
+
+"dfn">Observable {
+  Subscription subscribe("idlParam">(<a href="#dom-observer"
+class="internalDFN" data-link-type=
+"dfn"> or <a href="#dom-onnext" class=
+
+"idlParam">EventHandler handler,
+                         optional ErrorHandler errorHandler,
+                         optional 
+"internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">next,
+                           <span class=
+"idlParam">optional <a href=
+"#dom-onerror" class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">error,
+                           <span class=
+"idlParam">optional <a href=
+"#dom-oncomplete" class="internalDFN" data-link-type=
+
+"dfn">OnComplete "idlParamName">complete
+};
+<span class="idlInterface" id="idl-def-subscription" data-idl=""
+data-title="Subscription">interface <span class=
+"idlInterfaceID"><a data-no-default="" data-link-for="" data-lt=""
+href="#dom-subscription" class="internalDFN" data-link-type=
+"dfn"> {
+<span class="idlMethod" id="idl-def-subscription-unsubscribe"
+data-idl="" data-title="unsubscribe" data-dfn-for=
+"subscription">    <span class=
+"idlMethType">void <span class=
+"idlMethName"><a data-no-default="" data-link-for="subscription"
+data-lt="unsubscribe|unsubscribe()" href=
+"#dom-subscription-unsubscribe" class="internalDFN" data-link-type=
+"dfn">
+<span class="idlAttribute" id="idl-def-subscription-closed"
+data-idl="" data-title="closed" data-dfn-for=
+"subscription">    readonly attribute <span class=
+"idlAttrType"><a href=
+
+"idlParamName">onComplete);
+};
+interface Subscription {
+  void unsubscribe();
+  readonly attribute 
+"https://heycam.github.io/webidl/#idl-boolean">boolean data-link-for="subscription" data-lt="" href=
+"#dom-subscription-closed" class="internalDFN" data-link-type=
+
+data-link-for="subscription" data-lt="subscription.closed|closed"
+href="#dom-subscription-closed" class="internalDFN" data-link-type=
+
+"dfn">closed;
+};
+<span class="idlInterface" id="idl-def-observer" data-idl=""
+data-title="Observer">interface <span class=
+"idlInterfaceID"><a data-no-default="" data-link-for="" data-lt=""
+href="#dom-observer" class="internalDFN" data-link-type=
+"dfn"> {
+<span class="idlMethod" id="idl-def-observer-next-value" data-idl=
+"" data-title="next" data-dfn-for="observer">    <span class=
+"idlMethType">void <span class=
+"idlMethName"><a data-no-default="" data-link-for="observer"
+data-lt="next()|next" href="#dom-observer-next" class="internalDFN"
+data-link-type="dfn">next(<span class=
+"idlParam"><a href=
+"https://heycam.github.io/webidl/#idl-any">any
+<span class="idlMethod" id="idl-def-observer-error-error" data-idl=
+"" data-title="error" data-dfn-for="observer">    <span class=
+"idlMethType">void <span class=
+"idlMethName"><a data-no-default="" data-link-for="observer"
+data-lt="error()|error" href="#dom-observer-error" class=
+"internalDFN" data-link-type="dfn">error(<span class=
+"idlParam"><a href=
+"https://heycam.github.io/webidl/#idl-Error">Error
+<span class="idlMethod" id="idl-def-observer-complete" data-idl=""
+data-title="complete" data-dfn-for="observer">    <span class=
+"idlMethType">void <span class=
+"idlMethName"><a data-no-default="" data-link-for="observer"
+data-lt="complete()|complete" href="#dom-observer-complete" class=
+"internalDFN" data-link-type="dfn">complete
+};
+<span class="idlCallback" id="idl-def-onnext" data-idl=""
+data-title="OnNext">callback <span class=
+"idlCallbackID"><a data-no-default="" data-link-for="" data-lt=""
+href="#dom-onnext" class="internalDFN" data-link-type=
+"dfn"> = <span class=
+"idlCallbackType">void<span class=
+
+};
+callback EventHandler = void (
+"idlParamType">"https://heycam.github.io/webidl/#idl-any">any
+<span class="idlCallback" id="idl-def-onerror" data-idl=""
+data-title="OnError">callback <span class=
+"idlCallbackID"><a data-no-default="" data-link-for="" data-lt=""
+href="#dom-onerror" class="internalDFN" data-link-type=
+"dfn"> = <span class=
+"idlCallbackType">void<span class=
+
+"https://heycam.github.io/webidl/#idl-any">any value);
+callback ErrorHandler = void (
+"idlParamType">"https://heycam.github.io/webidl/#idl-Error">Error
+<span class="idlCallback" id="idl-def-oncomplete" data-idl=""
+data-title="OnComplete">callback <span class=
+"idlCallbackID"><a data-no-default="" data-link-for="" data-lt=""
+href="#dom-oncomplete" class="internalDFN" data-link-type=
+"dfn"> = <span class=
+
+"https://heycam.github.io/webidl/#idl-Error">Error error);
+callback OnComplete =
+"idlCallbackType">
+void
+
+();
+
+
      +
      +7.1 +The +Observer +interface + +

      +The +Observer +interface +defines +the + +following + +callbacks +needed + +can +be +provided +when +subscribing + +to +handle + +an + + +Observable + +: +

      +
        +
      • +The +next() +function, +as +well +as +the + + + +OnNext + +EventHandler + + + +callback +takes +the +next +sample +for +the +data +in +the + +value + +argument. +
        • +
      • +The +error() +function, +as +well +as +the + + + +OnError + +ErrorHandler + + + +callback +takes +an +error +in +the + +value + +argument. +It +is +called +when +an +error +occured +in +producing +the +data +the +client +should +know +about. +
        • +
      • +The +complete() +function, +as +well +as +the + + + +OnComplete + + +callback +is +called +when +the +data +source +has +finished +sending +values. +
        • +
      +
      +

      + +7.2 + +8.1 + + +The + + +Subscription + + +interface + + +

      +

      +Contains +the + + +closed + + +property +of +type + +boolean + +that +tells +if +the +subscription +is +closed +or +active. +

      +

      +Also, +contains +the + + +unsubscribe + + +() +method +that +cancels +the +subscription, +i.e. +makes +a +request +to +the +underlying +platform +to +stop +receiving +data +from +the +source, +and +sets +the + +closed + +property +to + +false +. +

      +
      +
      +

      + +7.3 + +8.2 + + +The + + +Observable + + +interface + + +

      +

      +The + + +Observable + + +interface +enabled +subscribing +to +pushed +data +notifications +by +the + + +subscribe + + +() +method: +

      +
        +
      • +If +the +subscribe() +method +is +called +with +an +Observer +object, +initialize +the +data, +error +and +completion +handling +callbacks +from +that +object, +or +throw +on +error. +Otherwise, +if +the +subscribe() +method +is +called +with +a +function, +initialize + +Initialize + +the +data +handler +callback +with +that +function. + +the +first +function +argument. +
      • +If +the +next +argument +is +provided +and +is +a +function, +initialize +the +error +handling +callback +with +that +function, +or +throw +on +error. +
        • +
      • +If +the +third +argument +is +provided +and +is +a +function, +initialize +the +completion +handler +with +that +function, +or +throw +on +error. +
        • +
      • +After +callback +initializations, +the +implementation +should +request +the +underlying +platform +to +provide +data, +error +and +completion +notifications +for +the +supported +data +source. +
        • +
      +
      +
      +
      +

      + +8. + +9. + + +Security +and +Privacy + +Editor's +note + + +Please +see + +

      +

      +In +general + +the +security +measures +taken +to +protect +a + +WoT +Security + +system +will +depend +on +the +threats + +and +Privacy +repository + +attackers +that +system +may +face +and +the +value +of +the +assets +needs +to +protect. +A +detailed +discussion +of +security +and +privacy +considerations + +for +work +in +progress +regarding + +the +Web +of +Things, +including +a + +threat +models, +assets, +risks, +recommended +mitigations, + +model +that +can +be +adapted +to +various +circumstances, +is +presented +in +the +informative +document +[ + +WOT-SECURITY-CONSIDERATIONS + +]. +This +section +includes +only +normative +recommendations +relevant +to +the +WoT +Thing +Description. +

      +When +designing +new +devices + +and +services +for +use +with +the +WoT, +we +have +documented +a +set +of + +best +practices +for + +in +[ + +WOT-SECURITY-BEST-PRACTICES + +] +that + +SHOULD + +be +followed. + +This +best-practices +document +may +be +updated +as + +security +measures +evolve. +Following +these +practices +does +not +guarantee +security, +but +it +at +least +will +help +to +avoid +common +known +vulnerabilities + +and +privacy +for +systems + +pitfalls. +

      +Below +are +specific +recommendations +related +to +WoT +runtime +implementations: +

      • +In +basic +WoT +setups, +all +scripts +running +inside +the +WoT +runtime +are +considered +trusted, +and +therefore +there +is +no +strong +need +to +perform +strict +isolation +between +each +running +script +instance. +However, +depending +on +device +capabilities +and +deployment +use +case +scenario +risk +level +it +might +be +desirable +to +do +so. +
        • +For +example, +if +one +script +handles +sensitive +privacy-related +data +and +well-audited, +it +might +be +desirable +to +separate +it +from +the +rest +of +the +script +instances +to +minimize +the +risk +of +data +exposure +in +case +some +other +script +inside +WoT +gets +compromised +during +the +runtime. + +Therefore +the +WoT +runtime + +SHOULD + +perform +isolation +of +script +instances +and +their +data +in +cases +when +scripts +handle +privacy-related +or +other +critical +security +data. +
        • +Another +example +is +mutual +co-existence +of +different +tenants +on +a +single +WoT +device. +In +this +case +each +WoT +runtime +instance +will +be +hosting +a +different +tenant, +and +isolation +between +them +is +required. + +Therefore +the +WoT +runtime + +SHOULD + +perform +isolation +of +WoT +runtime +instances +and +their +data +if +a +WoT +device +has +more +than +one +tenant. +
        +Such +isolation +can +be +performed +within +the +WoT +Runtime + +using +platform +security +mechanisms +available +on + +the +Web + +device. +For +more +information +see +Section +"WoT +Servient +Single-Tenant" +and +"WoT +Servient +Multi-Tenant" + +of +[ + +WOT-SECURITY-CONSIDERATIONS + +]. +
      • +WoT +scripts +are +using +WoT +Scripting +API +to +implement +the +functionality +and +logic +for +WoT + +Things. +Once +complete, + +In +addition +to +providing +the +isolation +between +script +and +runtime +instances, +the +WoT +runtime +needs +to +protect +the +underlying +physical +device +from +potentially +misbehaving +WoT +scripts. + +Therefore +the +WoT +Runtime + +SHOULD + +avoid +directly +exposing +the +native +device +interfaces +to +the +script +developers. + +Instead +a +WoT +Runtime +should +provide +a +hardware +abstraction +layer +for +accessing +the +native +device +interfaces. +Additionally, +in +order +to +reduce +the +damage +to +a +physical +WoT +device +in +cases +a +WoT +script +gets +compromised, +it +is +important +to +minimize +the +number +of +interfaces +that +are +exposed +or +accessible +to +a +particular +WoT +script +based +on +its +functionality. + +Therefore +the +WoT +Runtime + +SHOULD + +only +expose +a +minimal +set +of +interfaces +to +a +WoT +script +based +on +its +intended +functionality. +
      • +If +the +WoT +runtime +supports +post-manufacturing +provisioning +or +update +of +WoT +scripts, +WoT +runtime +or +any +related +data +(including + +security +credentials), +it +can +be +a +major +attack +vector. +An +attacker +can +try +to +modify +any +above +described +part +during +the +update +or +provisioning +process +or +simply +provision +attacker's +code + +and +privacy +considerations +relevant + +data +directly. + +Therefore, +if +WoT +Runtime +supports +post-manufacturing +provisioning +or +update +of +WoT +scripts, +WoT +runtime +or +any +related +data, +such +operations + +SHOULD + +be +done +in +a +secure +fashion. + +A +set +of +recommendations +for +secure +update +and +post-manufacturing +provisioning +can +be +found +in +[ + +WOT-SECURITY-BEST-PRACTICES + +]. +
      • +Typically +the +WoT +runtime +needs + +to +store + +the +Scripting +API +will + +security +credentials +that +are +provisioned +to +a +WoT +device +to +operate +in +WoT +network. +The +confidentiality +or +integrity +of +these +credentials +should +not + +be +summarized + +compromised. + +Therefore +the +WoT +runtime + +SHOULD + +securely +store +the +provisioned +security +credentials, +guaranteeing +their +integrity +and +confidentiality. + +In +case +there +are +more +than +one +tenant +on +a +single +WoT-enabled +device, +a +WoT +Runtime + +SHOULD + +guarantee +isolation +of +each +tenant +provisioned +security +credentials. + +Additionally, + +in +this +section. + +order +to +minimize +a +risk +that +provisioned +security +credentials +get +compromised, +the +WoT +runtime +should +not +have +any +way +for +WoT +scripts +to +query +these +credentials. + +Therefore, +the +WoT +Runtime + +SHOULD +NOT + +expose +any +API +for +WoT +scripts +to +query +the +provisioned +security +credentials. +

      +Some +additional +specific +recommendations +relevant +for +WoT +script +developers: + +

      +
        +
      • +A +typical +way +to +compromise +any +process +is +to +send +it +a +corrupted +input +via +one +of +the +exposed +interfaces. + +Therefore +developers + +SHOULD + +perform +validation +on +all +WoT +script +inputs, +including + +fuzzing +. +There +are +many +tool +and +techniques +in +existence +to +do +such +validation. +More +details +can +be +found +in +[ + +WOT-SECURITY-TESTING + +]. +
      • +As +any +software, +complex +scripts +with +a +lot +of +functionality +presents +a +higher +risk +of +development +mistakes. +Such +scripts +are +also +hard +to +verify +and +test +appropriately. + +Therefore +developers +SHOUD +minimize +the +functionality +and +complexity +of +WoT +scripts. +
      • +If +a +WoT +script +performs +a +heavy +functional +processing +on +received +requests +before +the +request +is +authenticated, +it +presents +a +great +risk +for +Denial-Of-Service +(DOS) +attacks. + +Therefore +WoT +scripts + +SHOULD + +avoid +heavy +functional +processing +without +prior +successful +authentication +of +requestor. + +The +set +of +recommended +authentication +mechanisms +can +be +found +in +[ + +WOT-SECURITY-BEST-PRACTICES + +]. +
      • +WoT +developers +should +remember +that +a +content +of +a +TD +can +change, +including +its +identified, +id, +which +is +not +an +immutable +identifier. + +Therefore +WoT +scripts + +SHOULD + +use +the +provided +WoT +script +API +to +subscribe +for +notifications +on +TD +changes. +
      +
      +
      +

      + +9. + +10. + + +Terminology +and +conventions + + +

      +

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

      +

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

      +

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

      +

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

      +

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

      +

      +The +term + + +secure +context + + +is +defined +in +[ + + +WEBAPPSEC + + +]. +

      +

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

      +

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

      +

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

      +

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

      +

      +The +terms + +hyperlink +reference + +and + +relation +type + +are +defined +in +[ + +HTML52 + + +HTML5 + + + +] +and + +RFC8288 +. +

      +
      +
      +

      + +10. + +11. + + +Conformance + + +

      +

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

      +

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

      +

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

      +

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

      +

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

      +

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

      +

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

      +

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

      +
      +
      +

      + +A. + +Changes + + +

      +

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

      +
        +
      • +Synchronized + +Make + +the +Scripting +API +with + +refer +to +(rather +then +locally +re-define) + +the +data +structures +defined +in +the + +Thing +Description +specification +. +Defined +ThingDescription +, +ThingTemplate +, +SemanticAnnotations +, +SemanticType +, +SemanticMetadata +, +input +and +output +data +descriptions, +etc. +Separated +consume() +to +fetch() +and +consume() +. +Changed +expose() +to +accept +a +Thing +Template +. +Instead +of +addListener() +, +removeListener() +introduced +onEvent() +, +onPropertyChange() +, +onTDChange() +. +Revised +ExposedThing +handlers +for +Property, +Action +and +Event. +Added +an +informal +section +on +TD +introspection. +Added +informal +section +for +Observable +. + +
        • +
      +
      +
      +

      + +B. + +Open +issues + + +

      +

      +The +following +problems +are +being +discussed +and +need +most +attention: +

      +
        +
      • +Revised +API +for +tracking +the +TD +better +( +https://github.com/w3c/wot-scripting-api/issues/96) +. + +Security +related +metadata +( +https://github.com/w3c/wot-scripting-api/issues/91) +. +Defining +DataSchema +better +( +https://github.com/w3c/wot-scripting-api/issues/89) +. + +(https://github.com/w3c/wot-scripting-api/issues/91). + +
        • +
      • +Providing +Protocol +Binding +for + + +ExposedThing + + +( +https://github.com/w3c/wot-scripting-api/issues/45) +. +Retrieving +information +from +Thing +Description +( +https://github.com/w3c/wot-scripting-api/issues/38 +) + +(https://github.com/w3c/wot-scripting-api/issues/45). + +
        • +
      • +Script +management +and +runtime +related +issues +( +https://github.com/w3c/wot-scripting-api/issues/ +) + +(https://github.com/w3c/wot-scripting-api/issues/) + +
        • +
      +
      +
      +

      + +C. + +Acknowledgements + + +

      +

      +Special +thanks +to +former +editor +Johannes +Hund +(until +August +2017, +when +at +Siemens +AG) +for +developing +this +specification. +Also, +the +editors +would +like +to +thank +Dave +Raggett, +Matthias +Kovatsch, +Michael +Koster +and +Michael +McCool +for +their +comments +and +guidance. +

      +
      +
      +

      + +D. + +References + + +

      +
      +

      + +D.1 + +Normative +references + + +

      +
      +
      +[ECMASCRIPT] +
      +
      + + +ECMAScript +Language +Specification + +. +Ecma +International. +URL: + +https://tc39.github.io/ecma262/ + +
      +
      +[ENCODING] +
      +
      + + +Encoding + +. +Anne +van +Kesteren; +Joshua +Bell; +Addison +Phillips. +W3C. +15 +December +2016. +W3C +Candidate +Recommendation. +URL: + +https://www.w3.org/TR/encoding/ + +
      +[HTML52] + +
      +[HTML5] + +
      +
      + + +HTML +5.2 + +HTML5 + + +. +Ian +Hickson; +Robin +Berjon; + +Steve +Faulkner; +Arron +Eicholz; + +Travis +Leithead; +Alex +Danilo; +Sangwhan +Moon; + +Erika +Doyle +Navara; +Theresa +O'Connor; +Robin +Berjon. + +Silvia +Pfeiffer. + +W3C. +14 +December +2017. + +27 +March +2018. + +W3C +Recommendation. +URL: +https://www.w3.org/TR/html52/ + + +https://www.w3.org/TR/html5/ + + +
      +
      +[JSON-LD] +
      +
      + + +JSON-LD +1.0 + +. +Manu +Sporny; +Gregg +Kellogg; +Markus +Lanthaler. +W3C. +16 +January +2014. +W3C +Recommendation. +URL: + +https://www.w3.org/TR/json-ld/ + +
      +
      +[RFC2119] +
      +
      + + +Key +words +for +use +in +RFCs +to +Indicate +Requirement +Levels + +. +S. +Bradner. +IETF. +March +1997. +Best +Current +Practice. +URL: + +https://tools.ietf.org/html/rfc2119 + +
      +
      +[TYPESCRIPT] +
      +
      + + +TypeScript +Language +Specification + +. +Microsoft. +1 +October +2012. +URL: + +https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md + +
      +
      +[URL] +
      +
      + + +URL +Standard + +. +Anne +van +Kesteren. +WHATWG. +Living +Standard. +URL: + +https://url.spec.whatwg.org/ + +
      +
      +[WEBAPPSEC] +
      +
      + + +Secure +Contexts + +. +W3C. +17 +July +2015. +URL: +https://w3c.github.io/webappsec/specs/powerfulfeatures/ + + +https://w3c.github.io/webappsec/specs/powerfulfeatures + + +
      +
      +[WEBIDL] +
      +
      + + +Web +IDL + +. +Cameron +McCormack; +Boris +Zbarsky; +Tobie +Langel. +W3C. +15 +December +2016. +W3C +Editor's +Draft. +URL: + +https://heycam.github.io/webidl/ + +
      +
      +[WOT-ARCHITECTURE] +
      +
      + + +Web +of +Things +Architecture + +. +W3C. +14 +September + +20 +August + +2017. +URL: +https://www.w3.org/TR/2017/WD-wot-architecture-20170914/ + + +https://w3c.github.io/wot-architecture/ +
      +[WOT-SECURITY-BEST-PRACTICES] +
      +Web +of +Things +Security +and +Privacy +Best +Practices +(WIP) +. +W3C. +WIP. +URL: + +https://github.com/w3c/wot-security/blob/master/wot-security-best-practices.md +
      +[WOT-SECURITY-CONSIDERATIONS] +
      +Web +of +Things +Security +and +Privacy +Considerations +. +W3C. +28 +August +2017. +URL: + +https://w3c.github.io/wot-security/ +
      +[WOT-SECURITY-TESTING] +
      +Web +of +Things +Security +Testing +and +Validation +. +W3C. +WIP. +URL: + +https://github.com/w3c/wot-security/blob/master/wot-security-testing.md +
      +[WOT-TD] +
      +WoT +Thing +Description + +. +W3C. +20 +August +2017. +URL: + +https://w3c.github.io/wot-thing-description/ + + +
      +
      +
      +
      +

      + +D.2 + +Informative +references + + +

      +
      +[WOT-TD] + +
      +[HTML] + +
      +
      + + +WoT +Thing +Description + +HTML +Standard + + +. +W3C. +20 +August +2017. + +. +Anne +van +Kesteren; +Domenic +Denicola; +Ian +Hickson; +Philip +Jägenstedt; +Simon +Pieters. +WHATWG. +Living +Standard. + +URL: +https://www.w3.org/TR/2018/WD-wot-thing-description-20180405/ + + +https://html.spec.whatwg.org/multipage/ + + +
      +
      +
      +
      + + + + diff --git a/releases/wd3/Overview.html b/releases/wd3/Overview.html new file mode 100644 index 00000000..2f6915b6 --- /dev/null +++ b/releases/wd3/Overview.html @@ -0,0 +1,5724 @@ + + + + + + + + + + + Web of Things (WoT) Scripting API + + + + + + + + +
      + +

      Web of Things (WoT) + Scripting API

      +

      W3C Working + Draft

      +
      +
      This version:
      +
      + + https://www.w3.org/TR/2018/WD-wot-scripting-api-20181021/ +
      +
      Latest published version:
      +
      + https://www.w3.org/TR/wot-scripting-api/ +
      +
      Latest editor's draft:
      +
      + https://w3c.github.io/wot-scripting-api/ +
      +
      Previous version:
      +
      + + https://www.w3.org/TR/2018/WD-wot-scripting-api-20180405/ +
      +
      Editors:
      +
      + Zoltan Kis (Intel) +
      +
      + Kazuaki Nimura (Fujitsu Ltd.) +
      +
      + Daniel Peintner (Siemens AG) +
      +
      Johannes Hund (Former Editor, when at + Siemens AG)
      +
      Contributors:
      +
      + + In the GitHub repository +
      +
      Repository:
      +
      + We are + on GitHub +
      +
      + File a + bug +
      +
      +

      Copyright + © 2017-2018 W3C® + (MIT, + ERCIM, + Keio, Beihang). W3C + liability, + trademark and + permissive document license rules apply.

      +
      +
      +
      +

      Abstract

      +

      The overall Web of Things (WoT) concepts are + described in the WoT Architecture + document. The Web of Things is made of entities (Things) that can describe their capabilities in a + machine-interpretable format, the Thing Description (TD) and expose these capabilities + through the WoT Interface, 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.

      +

      This specification describes a programming interface + representing the WoT Interface that + allows scripts run on a Thing to discover and + consume (retrieve) other Thing Descriptions + and to expose Things characterized by WoT Interactions specified by a script.

      +

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

      +
      +
      +

      Status of This Document

      +

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

      +

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

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

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

      +
      +

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

      +

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

      +

      Changes from the previous publication can be found in + Appendix B. A diff-marked version of this document is also + available for comparison purposes.

      +

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

      +

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

      +

      This document is governed by the 1 February 2018 + W3C Process + Document.

      +
      + +
      + +

      1. + Introduction

      +

      WoT provides layered interoperability based on how Things are modeled: as being "consumed" and + "exposed".

      +

      By consuming a TD, a client Thing creates a runtime resource model that allows + accessing the Properties, Actions and + Events exposed by the server Thing exposed on a + remote device.

      +

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

      +
      +
      + Note +
      +

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

      +
      +
      +
      + Note +
      +

      This specification does not make assumptions on + how the WoT Runtime handles and runs + scripts, including single or multiple tenancy, script + deployment and lifecycle management. The API already supports + the generic mechanisms that make it possible to implement + script management, for instance by exposing a manager + Thing whose Actions (action + handlers) implement script lifecycle management + operations.

      +
      +

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

      +
      +
      + +

      2. Use + Cases

      +

      This section is non-normative.

      +

      The following scripting use cases are supported in this + specification:

      +
      +

      2.1 + Discovery

      +
        +
      • Discover all Things in the WoT network by + sending a broadcast request. +
        • +
      • Discover Things running in the local + WoT Runtime. +
        • +
      • Discover nearby Things, for instance + connected by NFC or Bluetooth. +
        • +
      • Discover Things by sending a discovery + request to a given registry. +
        • +
      • Discover Things by filters defined on + Thing Descriptions +
        • +
      • Discover Things by semantic queries. +
        • +
      • Stop or suppress an ongoing discovery process.
        • +
      • Optionally specify a timeout to the discovery process + after which it is stopped/suppressed.
        • +
      +
      +
      +

      2.2 Consuming a Thing

      + +
      +
      +

      2.3 + Exposing a Thing

      +
        +
      • Exposing the Thing includes generating the + protocol bindings in order to access lower level + functionality. +
        • +
      • Create a local ExposedThing to be exposed, based on + a Thing Description provided in + string serialized format, or out of a template or an + existing ConsumedThing object. +
        • +
      • Add a Property definition to the + Thing. +
        • +
      • Add an Action definition to the + Thing. +
        • +
      • Add an Event definition to the Thing. +
        • +
      • Attach semantic information to the Thing. +
        • +
      • Attach semantic information to a + Property. +
        • +
      • Attach semantic information to an Action. +
        • +
      • Attach semantic information to an Event. +
        • +
      • Emit an Event, i.e. notify all listeners + subscribed to that Event. +
        • +
      • Provide notifications for TD changes to + clients subscribed to that. +
        • +
      • Mark/unmark the Thing to be discoverable.
        • +
      • Mark/unmark the Thing to be consumable.
        • +
      • Start the exposed Thing in order to + process external requests. +
        • +
      • Stop the exposed Thing. +
        • +
      • Register handlers for external requests: +
          +
        • to retrieve a Property value; +
          • +
        • to update a Property value; +
          • +
        • to run an Action: take the + parameters from the request, execute the defined + action, and return the result; +
          • +
        +
        • +
      +
      +
      +
      + +

      3. The + WoT + object

      +

      The WoT object is the API entry point and it is exposed by + an implementation of the WoT Runtime. The + WoT object + does not expose properties, only methods for discovering, + consuming and exposing a Thing.

      +
      +
      + Note +
      +

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

      +
      +
      + 
      // [SecureContext]
+// [NamespaceObject]
+interface WoT {
+  Observable discover(optional ThingFilter filter);
+  Promise<ThingDescription> fetch(USVString url);
+  ConsumedThing consume(ThingDescription td);
+  ExposedThing produce(ThingModel model);
+  Promise<void> register(USVString directory, ExposedThing thing);
+  Promise<void> unregister(USVString directory, ExposedThing thing);
+};
+typedef object ThingFragment;
+typedef object PropertyFragment;
+typedef object ActionFragment;
+typedef object EventFragment;
+typedef object DataSchema;
+typedef object SecurityScheme;
+typedef object Link;
+typedef object Form;
+typedef USVString ThingDescription;
+typedef (ThingFragment or ThingDescription) ThingModel;
      +
      +
      +
      + Editor's note +
      +

      The algorithms for the WoT methods will be + specified later, including error handling and security + considerations.

      +
      +

      The ThingModel type represents + either a ThingFragment, or a + ThingDescription.

      +
      +

      3.1 The discover() + method

      +

      Starts the discovery process that will provide ThingDescriptions that match the + optional argument filter of type ThingFilter. Returns an + [Observable](https://github.com/tc39/proposal-observable) + object that can be subscribed to and unsubscribed from. The + handler function provided to the Observable during + subscription will receive an argument of type + USVString representing a ThingDescription.

      +
      +

      + 3.1.1 The DiscoveryMethod + enumeration

      +
      + 
      typedef DOMString DiscoveryMethod;
      +
      +

      DiscoveryMethod + represents the discovery type to be used:

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

      3.1.2 The ThingFilter + dictionary

      +

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

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

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

      +

      The url property + represents additional information for the discovery method, + such as the URL of the target entity serving the discovery + request, for instance a Thing + Directory (if method is + "directory") or a Thing (otherwise).

      +

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

      +

      The fragment property + represents a ThingFragment dictionary used for + matching property by property against discovered Things.

      +
      +

      The discover(filter) method MUST run the following steps:

      +
        +
      1. If invoking discover() is not allowed for + the current scripting context for security reasons, throw + SecurityError and terminate these steps.
        2. +
      2. Return an Observable obs and + execute the next steps in parallel. +
        3. +
      3. If obs.subscribe(handler, errorHandler, + complete) is called, execute the following + sub-steps: +
          +
        1. If the first argument handler is not + defined or it is not a function, throw + TypeError and terminate the algorithm. + Otherwise configure handler to be invoked + when a discovery hit happens.
          2. +
        2. If the second argument errorHandler is + defined, but it is not a function, throw + TypeError and terminate these steps. + Otherwise if defined, save it to be invoked in error + conditions.
          3. +
        3. If the third argument onComplete is + defined, but it is not a function, throw + TypeError and terminate these steps. + Otherwise if defined, save it to be invoked when the + discovery process finished for other reasons than + having been canceled.
          4. +
        4. If filter.query is defined, pass it as + an opaque string to the underlying implementation to be + matched against discovered items. The underlying + implementation is responsible to parse it e.g. as a + SPARQL or JSON query and match it against the + Thing Descriptions found + during the discovery process. If queries are not + supported, implementations SHOULD throw a + NotSupported error and terminate these + steps. +
          5. +
        5. If filter.fragment is defined, and if it + contains other properties than the ones defined in + ThingFragment, + throw TypeError and terminate these steps. + Otherwise save the object for matching the discovered + items against it. +
          6. +
        6. Request the underlying platform to start the + discovery process, with the following parameters: +
            +
          • If filter.method is not defined or + the value is "any", use the widest + discovery method supported by the underlying + platform.
            • +
          • Otherwise if filter.method is + "local", use the local Thing Directory for + discovery. Usually that defines Things deployed in the same device, or + connected to the device in slave mode (e.g. + sensors connected via Bluetooth or a serial + connection). +
            • +
          • Otherwise if filter.method is + "directory", use the remote Thing Directory + specified in filter.url. +
            • +
          • Otherwise if filter.method is + "multicast", use all the multicast + discovery protocols supported by the underlying + platform.
            • +
          +
          7. +
        +
        4. +
      4. Whenever a new item td is discovered by the + underlying platform, run the following sub-steps: +
          +
        1. If filter.query is defined, check if + td is a match for the query. The matching + algorithm is encapsulated by implementations. If that + returns false, discard td and + continue the discovery process.
          2. +
        2. If filter.fragment is defined, for each + property defined in it, check if that property exists + in td and has the same value. If this is + false in any checks, discard td + and continue the discovery process.
          3. +
        3. Otherwise if td has not been discarded + in the previous steps, invoke the handler + function with td as parameter.
          4. +
        +
        5. +
      5. Whenever an error occurs during the discovery process, + and if errorHandler is defined, invoke it with + an argument of type Error whose + message property is set to + UnknownError unless there was an error code + provided by the Protocol Bindings, + in which case set it to that value. +
        6. +
      6. When the discovery process is finished, and if + onComplete is defined, invoke it run the + cancel discovery steps. +
        7. +
      7. When the obs.unsubscribe() method is + called, run the following cancel discovery steps: +
          +
        1. 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.
          2. +
        2. Set obs.closed to + false.
          3. +
        +
        8. +
      +
      +
      +

      3.2 + The fetch() + method

      +

      Accepts an url argument of type + USVString that represents a URL (e.g. + "file://..." or "https://...") and + returns a Promise that resolves with a + ThingDescription (a + serialized JSON-LD document of type + USVString).

      +

      The fetch(url) method MUST run the following steps:

      +
        +
      1. Return a Promise promise and + execute the next steps in parallel. +
        2. +
      2. If invoking fetch() is not allowed for the + current scripting context for security reasons, reject + promise with SecurityError and + terminate these steps.
        3. +
      3. If the argument url is not a URL, reject + promise with TypeError and + terminate these steps.
        4. +
      4. Make a request to fetch the content of url + as described by the Protocol + Bindings and wait for the reply. Implementations + encapsulate the fetching process and the accepted media + types (such as application/td+json), as far + as a valid Thing Description + can be obtained as defined in [WOT-TD]. Let td + be the Thing Description + string-serialized from the returned content, as specified + in the + Thing Description serialization. +
        5. +
      5. 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 terminate + these steps. +
        6. +
      6. Otherwise resolve promise with td + and terminate these steps.
        7. +
      +
      +
      +

      3.3 The consume() + method

      +

      Accepts an td argument of type ThingDescription and returns a + ConsumedThing object + instantiated based on parsing that description.

      +

      The consume(td) method must run the following + steps:

      +
        +
      1. If the argument td is not a string, throw a + TypeError and terminate these steps.
        2. +
      2. Let stub be the result of running the + TD parsing algorithm with + td as argument. If that throws an error, + re-throw the error and terminate these steps. +
        3. +
      3. If stub does not have an own property that + is defined in ThingFragment with a default value, + add that property and value to stub. +
        4. +
      4. Create a ConsumedThing object + thing initialized from stub that + implements Observable. +
        5. +
      5. Add the read() and write() + methods to the ThingProperty elements so that they + make requests to access the remote Things and + wait for the reply, as defined by the Protocol Bindings. Also, all + ThingProperty + elements SHOULD + implement Observable, i.e. + define a subscribe() method that should make + request to observe the given Properties + as defined by the Protocol Bindings. +
        6. +
      6. Add the invoke() methods to the ThingAction elements so that they + make requests to the remote Thing to invoke its + actions, as defined by the Protocol + Bindings. +
        7. +
      7. Add the subscribe() method to all + ThingEvent elements + so that they make requests to subscribe to the events + defined by the remote Thing, as defined + by the Protocol Bindings. +
        8. +
      8. Return thing.
        9. +
      +
      +
      +

      3.4 The produce() + method

      +

      Accepts a model argument of type + ThingModel and + returns an ExposedThing + object.

      +

      The produce(model) method MUST run the following steps:

      +
        +
      1. If invoking produce() is not allowed for + the current scripting context for security reasons, throw + SecurityError and terminate these steps.
        2. +
      2. If the argument model is a string, then run + the TD parsing algorithm with model + passed as parameter. If it throws an error, re-throw that + error and terminate this algorithm. Otherwise let + model be the returned value.
        3. +
      3. If model is not an object, throw + TypeError and terminate these steps.
        4. +
      4. If model does not have an own property that + is defined in ThingFragment with a default value, + add that property and value to model. +
        5. +
      5. Create an ExposedThing object thing + initialized from model. +
        6. +
      6. For each property of ExposedThing defined in ThingFragment, initialize the + property based on the provided initial or default values + provided to the local WoT Runtime + implementation, for instance initialize: +
          +
        1. the id property to be the final unique + identifier of the Thing, +
          2. +
        2. the security object of type SecurityScheme to + represent the actual security scheme and its properties + as set up by the implementation, +
          3. +
        3. the properties property to be an + object with all properties being ThingProperty + objects in which the read() and + write() methods are provided to define + local methods to get and set the Property values, +
          4. +
        4. the actions property to be an object + with all properties being ThingAction objects in which the + invoke() method is provided to define a + local method to run the defined Actions, +
          5. +
        5. the events property to be an object + with all properties being ExposedEvent objects in which + the emit() method is provided to define a + local way to trigger sending notifications to all + subscribed clients, +
          6. +
        6. and initialize the other properties as initialized + from model.
          7. +
        7. Return thing.
          8. +
        +

        The TD parsing algorithm + takes a string td as argument and runs the + following steps:

        +
          +
        1. Parse td according to the + WoT Thing Description in order to produce a + JSON + object json. Update thing + with the properties and values defined in + json. +
          2. +
        2. If there was an error during the parsing, throw + that error and terminate these steps.
          3. +
        3. Otherwise return json.
          4. +
        +
        7. +
      +
      +
      +

      3.5 The register() + method

      +

      Takes two mandatory arguments:

      + +

      Generate the Thing Description as + td, given the Properties, Actions and Events defined for + this ExposedThing object. + Then make a request to register td to the given + WoT Thing Directory.

      +
      +
      +

      3.6 The + unregister() method

      +

      Takes two mandatory arguments:

      + +

      Makes a request to unregister the thing from + the given WoT Thing Directory.

      +
      +
      +

      3.7 + Examples

      +
      +
      + Example + 1: Discover Things via + directory +
      + 
      let discoveryFilter = {
+  method: "directory",
+  url: "http://directory.wotservice.org"
+};
+let subscription = wot.discover(discoveryFilter).subscribe(
+  td => {
+    console.log("Found Thing " + td.name);
+    // fetch the TD and create a ConsumedThing
+    let thing = wot.consume(td);
+  },
+  error => { console.log("Discovery finished because an error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);
+setTimeout( () => {
+    subscription.unsubscribe();
+    console.log("Discovery timeout");
+  },
+  5000);
      +
      +
      +
      + Example + 2: Discover Things + exposed by local hardware +
      + 
      let subscription = wot.discover({ method: "local" }).subscribe(
+  td => { console.log("Found local Thing " + td.name); },
+  error => { console.log("Discovery error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);
      +
      +
      +
      + + Example 3: Same as above + but with different Observable syntax +
      + 
      let subscription = wot.discover({ method: "local" }).subscribe({
+  td => { console.log("Found local Thing " + td.name); },
+  error: err => { console.log("Discovery error: " + err.message); },
+  complete: () => { console.log("Discovery finished successfully");}
+});
      +
      +
      +
      +
      + +

      4. The ConsumedThing + interface

      +

      Represents an object that extends a ThingFragment with methods for client + interactions (send request for reading and writing Properties), invoke Actions, subscribe and + unsubscribe for Property changes and Events.

      +
      + 
      interface ConsumedThing : ThingFragment {
+  readonly attribute DOMString id;
+  readonly attribute DOMString name;
+  readonly attribute DOMString? base;
+  readonly attribute PropertyMap properties;
+  readonly attribute ActionMap actions;
+  readonly attribute EventMap events;
+  // getter for ThingFragment properties
+  getter any (DOMString name);
+};
+[NoInterfaceObject]
+interface PropertyMap {
+  readonly maplike<DOMString, ThingProperty>;
+};
+[NoInterfaceObject]
+interface ActionMap {
+  readonly maplike<DOMString, ThingAction>;
+};
+[NoInterfaceObject]
+interface EventMap {
+  readonly maplike<DOMString, ThingEvent>;
+};
+ConsumedThing includes Observable;  // for TD changes
      +
      +

      The id attribute + represents the unique identifier of the Thing instance, + typically a URI, IRI, or URN as USVString.

      +

      The name attribute + represents the name of the Thing as + DOMString.

      +

      The base attribute + represents the base URI that is valid for all defined local + interaction resources.

      +

      The properties + attribute represents a dictionary of ThingProperty items. The + PropertyMap interface + represents a maplike dictionary where all values are ThingProperty objects. The + read() and write() methods make a + request to access the Properties on the remote + Thing represented by this ConsumedThing proxy object.

      +

      The actions + attribute represents a dictionary of ThingAction items. The + ActionMap interface represents a + maplike dictionary where all values are ThingAction objects. The + invoke() method represents a request to invoke the + Action on the remote Thing.

      +

      The events + attribute represents a dictionary of ThingEvent items. The EventMap interface + represents a maplike dictionary where all values are ThingEvent objects. Subscribing to the + events involves setting up an observation (subscription) + mechanism on the remote object.

      +
      +

      4.1 + Examples

      +

      Below a ConsumedThing interface example + is given.

      +
      +
      + Example + 4: Consume a Thing +
      + 
      try {
+  let subscription = wot.discover({ method: "local" }).subscribe(
+    td => {
+      let thing = wot.consume(td);
+      console.log("Thing " + thing.name + " has been consumed.");
+      let subscription = thing["temperature"].subscribe(function(value) {
+          console.log("Temperature: " + value);
+        });
+      thing.actions["startMeasurement"].invoke({ units: "Celsius" })
+        .then(() => { console.log("Temperature measurement started."); })
+        .catch(e => {
+           console.log("Error starting measurement.");
+           subscription.unsubscribe();
+         })
+    },
+    error => { console.log("Discovery error: " + error.message); },
+    () => { console.log("Discovery finished successfully");}
+  );
+} catch(error) {
+  console.log("Error: " + error.message);
+};
      +
      +
      +
      +
      + +

      5. The ExposedThing + interface

      +

      The ExposedThing interface is + the server API that allows defining request handlers, + properties, Actions, and Events to a + Thing. It also implements the Observable interface. An ExposedThing is created by the produce() method.

      +
      + 
      interface ExposedThing : ThingFragment {
+  readonly attribute PropertyMap properties;
+  readonly attribute ActionMap actions;
+  readonly attribute ExposedEvents events;
+  // getter for ThingFragment properties
+  getter any (DOMString name);
+  // setter for ThingFragment properties
+  setter void (DOMString name, any value);
+  // methods to expose and destroy the Thing
+  Promise<void> expose();
+  Promise<void> destroy();
+  // define Properties
+  ExposedThing addProperty(DOMString name, PropertyFragment property, optional any initValue);
+  ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
+  ExposedThing setPropertyWriteHandler(DOMString name, PropertyWriteHandler writeHandler);
+  ExposedThing removeProperty(DOMString name);
+  // define Actions
+  ExposedThing addAction(DOMString name, ActionFragment init, ActionHandler action);
+  ExposedThing removeAction(DOMString name);
+  ExposedThing setActionHandler(DOMString name, ActionHandler action);
+  // define Events
+  ExposedThing addEvent(DOMString name, EventFragment event);
+  ExposedThing removeEvent(DOMString name);
+};
+[NoInterfaceObject]
+interface ExposedEvents {
+  maplike<DOMString, ExposedEvent>;
+};
+callback PropertyReadHandler = Promise<any> ();
+callback PropertyWriteHandler = Promise<void> (any value);
+callback ActionHandler = Promise<any> (any parameters);
      +
      +

      The properties + attribute represents a dictionary of ThingProperty items in which the + read() and write() methods define + local methods that access the physical representations of the + Properties.

      +

      The actions + attribute represents a dictionary of ThingAction items in which the + invoke() method represents a local method to + invoke the Action.

      +

      The events + attribute represents a dictionary of ExposedEvent items that add the + emit() method to the ThingEvent definition. The + ExposedEvents interface + represents a maplike dictionary where all values are ExposedEvent objects.

      +
      +

      5.1 The + expose() method

      +

      Start serving external requests for the Thing, so that WoT Interactions + using Properties, Actions and + Events will be possible.

      +

      The expose() method MUST run the following steps:

      +
        +
      1. Return a Promise promise and + execute the next steps in parallel. +
        2. +
      2. If invoking expose() is not allowed for + the current scripting context for security reasons, reject + promise with SecurityError and + terminate these steps.
        3. +
      3. Make a request to the underlying platform to attach + protocol handlers and start serving external requests for + WoT Interactions (read, write and + observe Properties, invoke Actions and manage Event + subscriptions), based on the Protocol Bindings. +
        4. +
      4. 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 terminate + these steps. +
        5. +
      5. Otherwise resolve promise with td + and terminate these steps.
        6. +
      +
      +
      +

      5.2 The + destroy() method

      +

      Stop serving external requests for the Thing and destroy the object. Note that eventual + unregistering should be done before invoking this method.

      +

      The destroy() method MUST run the following steps:

      +
        +
      1. Return a Promise promise and + execute the next steps in parallel. +
        2. +
      2. If invoking destroy() is not allowed for + the current scripting context for security reasons, reject + promise with SecurityError and + terminate these steps.
        3. +
      3. Make a request to the underlying platform to stop + serving external requests for WoT Interactions, based on the + Protocol Bindings. +
        4. +
      4. 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 terminate + these steps. +
        5. +
      5. Otherwise resolve promise with td + and terminate these steps.
        6. +
      +
      +
      +

      5.3 The + addProperty() method

      +

      Adds a Property with name defined by the + name argument, the data schema provided by the + property argument of type PropertyFragment, and optionally an + initial value provided in the argument initValue + whose type should match the one defined in the + type property according to the value-matching algorithm. If + initValue is not provided, it SHOULD be initialized as + undefined. Implementations SHOULD update the Thing Description. Throws on error. Returns a + reference to the same object for supporting chaining.

      +
      +
      +

      5.4 The + removeProperty() method

      +

      Removes the Property specified by the + name argument and updates the Thing Description. Throws on error. Returns a + reference to the same object for supporting chaining.

      +
      +
      +

      5.5 The + addAction() method

      +

      Adds to the actions property of a Thing object an Action with name + defined by the name argument, defines input and + output data format by the init argument of type + ActionFragment, and + adds the function provided in the action argument + as a handler, then updates the Thing Description. Throws on error. Returns a + reference to the same object for supporting chaining.

      +

      The provided action callback function will + implement invoking an Action and SHOULD be called by + implementations when a request for invoking the Action is received from the underlying platform. + The callback will receive a parameters + dictionary argument according to the definition in the + init.input argument and will return a value of + type defined by the init.output argument according + to the value-matching + algorithm.

      +

      There SHOULD be + exactly one handler for any given Action. If no + handler is initialized for any given Action, + implementations SHOULD throw a TypeError.

      +
      +
      +

      5.6 The + removeAction() method

      +

      Removes the Action specified by the + name argument and updates the Thing Description. Throws on error. Returns a + reference to the same object for supporting chaining.

      +
      +
      +

      5.7 The + addEvent() method

      +

      Adds an event with name defined by the name + argument and qualifiers and initialization value provided by + the event argument of type EventFragmentto the Thing object and updates the Thing Description. Throws on error. Returns a + reference to the same object for supporting chaining.

      +
      +
      +

      5.8 The + removeEvent() method

      +

      Removes the event specified by the name + argument and updates the Thing + Description. Returns a reference to the same object for + supporting chaining.

      +
      +
      +

      5.9 The PropertyReadHandler + callback

      +

      A function that is called when an external request for + reading a Property is received. It should + return a Promise and resolves it with the value of the + Property matching the name argument to + the setPropertyReadHandler function, or rejects + with an error if the property is not found or the value + cannot be retrieved.

      +
      +
      +

      5.10 The PropertyWriteHandler + callback

      +

      A function that is called when an external request for + writing a Property is received. It is given + the requested new value as argument and should + return a Promise which is resolved when the value of the + Property that matches the name + argument has been updated with value, or rejects + with an error if the property is not found or the value + cannot be updated.

      +
      +
      + Editor's note +
      +

      Note that this function is invoked by + implementations before the property is updated and it + actually defines what to do when a write request is + received. The code in this callback function can invoke the + read() method to find out the old value of the + property, if needed. Therefore the old value is not + provided to this function.

      +
      +
      +
      +

      5.11 The ActionHandler + callback

      +

      A function called with a parameters + dictionary argument assembled by the WoT runtime based on the Thing Description and the external client request. + It returns a Promise that rejects with an error or resolves + if the action is successful or ongoing (may also resolve with + a control object such as an Observable for actions that need + progress notifications or that can be canceled).

      +
      +
      +

      5.12 The + setPropertyReadHandler() method

      +

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

      +

      The readHandler callback function will + implement reading a Property and + SHOULD be called by + implementations when a request for reading a Property is received from the underlying + platform.

      +

      There SHOULD be at + most one handler for any given Property and + newly added handlers replace the old handlers. If no handler + is initialized for any given Property, + implementations SHOULD implement a default property read + handler.

      +

      When an external request for reading Property propertyName is received, the + runtime SHOULD + execute the following steps:

      +
        +
      1. Return a Promise promise and + execute the next steps in parallel. +
        2. +
      2. If a Property with + propertyName does not exist, reject promise with a ReferenceError and + terminate these steps. +
        3. +
      3. Otherwise, if no read handler has been defined for + propertyName, resolve promise with + the value of the Property named + propertyName provided by the runtime implementation + and terminate these steps. +
        4. +
      4. Otherwise, invoke the read handler associated with + propertyName. If it rejects, then reject + promise with the same error, and resolve + promise with the same value. +
        5. +
      +
      +
      +

      + 5.13 The + setPropertyWriteHandler() method

      +

      Takes name as string argument and + writeHandler as argument of type PropertyWriteHandler. + Sets the handler function for writing the specified Property matched by name. Throws on + error. Returns a reference to the same object for supporting + chaining.

      +

      There SHOULD be at + most one write handler for any given Property and newly added handlers replace the old + handlers. If no write handler is initialized for any given + Property, implementations SHOULD implement default property update + and notifying observers on change.

      +

      When an external request for writing a Property propertyName with a new value + value is received, the runtime SHOULD execute the following steps:

      +
        +
      1. Return a Promise promise and + execute the next steps in parallel. +
        2. +
      2. If a Property with + propertyName does not exist, reject promise with a ReferenceError and + terminate these steps. +
        3. +
      3. Otherwise, if no write handler has been defined for + propertyName, the runtime implementation + SHOULD update the + Property value with + value, resolve promise and terminate + these steps. +
        4. +
      4. Otherwise, invoke the write handler associated with + propertyName providing value as + argument. If it rejects, then reject promise + with the same error, and resolve promise with + the same value. +
        5. +
      +
      +
      +

      5.14 The + setActionHandler() method

      +

      Takes name as string argument and + action as argument of type ActionHandler. Sets the handler + function for the specified Action matched by + name. Throws on error. Returns a reference to + the same 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 SHOULD be at + most one handler for any given Action and newly added + handlers replace the old handlers.

      +

      When an external request for invoking the Action identified by name is received, + the runtime SHOULD + execute the following steps:

      +
        +
      1. Return a Promise promise and + execute the next steps in parallel. +
        2. +
      2. If an Action identified by + name does not exist, reject promise with a ReferenceError and + terminate these steps. +
        3. +
      3. Otherwise, if no action handler has been defined for + name, reject promise with a + ReferenceError and terminate these steps. +
        4. +
      4. Otherwise, invoke the Action handler + associated with name. If it rejects with + error, then reject promise with the + same error, otherwise if it resolves with + value, then resolve promise with the + same value. +
        5. +
      +
      +
      +

      5.15 + Examples

      +

      Below some ExposedThing interface examples + are given.

      +
      +
      + + Example 5: Create a new + exposed Thing with a simple property +
      + 
      +        try {
+  var temperatureValueDefinition = {
+    type: "number",
+    minimum: -50,
+    maximum: 10000
+  };
+  var temperaturePropertyDefinition = temperatureValueDefinition;
+  // add the 'forms' property
+  temperaturePropertyDefinition.forms = [ ... ];
+  var thing = WoT.produce({
+    name: "tempSensor",
+    properties: {
+      temperature: temperaturePropertyDefinition
+    },
+    actions: {
+      reset: {
+        description: "Reset the temperature sensor",
+        input: {
+          temperature: temperatureValueDefinition
+        },
+        output: null,
+        forms: []
+      },
+    },
+    events: {
+      onchange: temperatureValueDefinition
+    },
+    links: []
+  });
+  await thing.expose();
+  await wot.register("https://mydirectory.org", thing);
+  // define Thing business logic
+  setInterval( async () => {
+    let mock = Math.random()*100;
+    let old = await thing["temperature"].read();
+    if (old < mock) {
+      await thing["temperature"].write(mock);
+      thing.emitEvent("onchange", mock);
+    }
+  }, 1000);
+} catch (err) {
+   console.log("Error creating ExposedThing: " + err);
+}
      +
      +
      +
      + Example + 6: Create a new exposed + Thing with object property +
      + 
      +        try {
+  var 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
+        }
+      }
+  };
+  var statusPropertyDefinition = statusValueDefinition;
+  // add the 'forms' property
+  statusPropertyDefinition["forms"] = [];
+  var thing = WoT.produce({
+    name: "mySensor",
+    properties: {
+      brightness: {
+        type: "number",
+        minimum: 0.0,
+        maximum: 100.0,
+        required: true,
+      },
+      status: statusPropertyDefinition
+    },
+    actions: {
+      status: {
+        description: "Get status object",
+        input: null,
+        output: {
+          status : statusValueDefinition;
+        },
+        forms: []
+      },
+    },
+    events: {
+      onstatuschange: statusValueDefinition;
+    },
+    links: []
+  });
+  thing.expose().then(() => {
+      thing.register();
+  });
+} catch (err) {
+   console.log("Error creating ExposedThing: " + err);
+}
      +
      +
      +
      + + Example 7: Create a new + exposed Thing from a Thing Description +
      + 
      +        let thingDescription = '{ \
+  "name": "mySensor", \
+  "@context": [ "http://www.w3.org/ns/td",\
+     "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ],\
+  "@type": [ "Thing", "Sensor" ], \
+  "geo:location": "testspace", \
+  "properties": { \
+    "prop1": { \
+      "type": "number",\
+      "@type": [ "Property", "Temperature" ], \
+      "saref:TemperatureUnit": "degree_Celsius" \
+  } } }';
+try {
+  // note that produce() fails if thingDescription contains error
+  let thing = WoT.produce(thingDescription);
+  // Interactions were added from TD
+  // WoT adds generic handler for reading any property
+  // define a specific handler for one property
+  let name = "examplePropertyName";
+  thing.setPropertyReadHandler(name, () => {
+    console.log("Handling read request for " + name);
+    return new Promise((resolve, reject) => {
+        let examplePropertyValue = 5;
+        resolve(examplePropertyValue);
+      },
+      e => {
+        console.log("Error");
+      });
+  });
+  thing.expose();
+} catch(err) {
+   console.log("Error creating ExposedThing: " + err);
+}
      +
      +
      +
      + Example + 8: Create a new exposed + Thing from a TD URI +
      + 
      +        // fetch an external TD, e.g., to set up a proxy for that Thing
+WoT.fetch("http://myservice.org/mySensor/description").then(td => {
+  // WoT.produce() ignores instance-specific metadata (security, form)
+  let thing = WoT.produce(td);
+  // Interactions were added from TD
+  // add server functionality
+  // ...
+});
      +
      +
      +
      +
      + +

      6. Data types and structures

      +

      The [WOT-TD] specification defines the + + WoT information model, i.e. the data types and data + structures used in WoT Interactions. In + this API these definitions translate to dictionary objects that + are extended with methods by the interfaces defined in this + specification.

      +

      In order to avoid duplication of definitions, references to + these data types and structures is defined in this section, but + for their full description please refer to the Thing + Description specification.

      +
      +

      + 6.1 The DataSchema + dictionary and its subclasses

      +

      Value types basically represent types that may be used in + JSON object definitions and are used in ThingFragment to define Properties, Events and Action parameters. Value types are represented as + dictionary objects whose properties and possible sub-classes + are defined in the + DataSchema section of [WOT-TD].

      +

      One property of all DataSchema dictionary is the + type property whose value is from a set of + enumerated strings defined in the DataSchema + section of [WOT-TD] and is referred as + DataType in + this specification.

      +

      Based on type, the following sub-classes of + DataSchema are defined in + [WOT-TD]: BooleanSchema, NumberSchema, IntegerSchema, StringSchema, ObjectSchema, ArraySchema.

      +
      +
      +

      + 6.2 The SecurityScheme dictionary + and its subclasses

      +

      Security metadata is represented as dictionary objects + whose properties and sub-classes are defined in the + SecurityScheme section of [WOT-TD].

      +

      One property of the SecurityScheme dictionary is the + scheme property whose value is from a set of + enumerated strings defined in the + SecurityScheme section of [WOT-TD]. Based on type, + multiple subclasses of SecurityScheme are defined.

      +
      + +
      +

      6.4 The Form dictionary

      +

      Represents metadata describing service details, with + properties defined in the Form + section of [WOT-TD].

      +
      +
      +

      6.5 The InteractionFragment + dictionary

      +

      Represents the common properties of WoT Interactions, one of Property, + Action or Event, as defined in the + InteractionPattern section of [WOT-TD]. Its subclasses are + referred as PropertyFragment, ActionFragment and EventFragment.

      +
      +
      +

      6.6 The PropertyFragment + dictionary

      +

      Represents the Property interaction + data that initializes a ThingProperty object. Its properties + are defined in the Property + and + InteractionPattern sections of [WOT-TD].

      +
      +
      +

      6.7 The ActionFragment + dictionary

      +

      Represents the Action interaction data that + initializes a ThingAction object. Its + properties are defined in the Action + and + InteractionPattern sections of [WOT-TD].

      +
      +
      +

      6.8 The EventFragment + dictionary

      +

      Represents the Event interaction data that + initializes a ThingEvent object. Its + properties are defined in the Event + section of [WOT-TD].

      +
      +
      +

      6.9 The ThingFragment + dictionary

      +

      The ThingFragment + dictionary is defined as Thing + in [WOT-TD]. It is a dictionary that + contains properties representing semantic metadata and + interactions (Properties, Actions and + Events). It is used for initializing an internal + representation of a Thing Description and + its properties may be used in ThingFilter.

      +
      +
      +

      6.10 The ThingDescription + type

      +

      Serialized representation of the Thing Description (a JSON-LD document).

      +
      +
      + Note +
      +

      In this version of the API, Thing Descriptions are represented + as an opaque USVString that can be transmitted + between devices.

      +
      +
      +
      +
      + +

      7. Interfaces for WoT Interactions

      +

      The data types and structures imported from [WOT-TD] are extended by + this specification in order to provide the interfaces for + WoT Interactions.

      +

      Every Thing describes its metadata as + defined in ThingFragment, and basic + interactions defined as Properties, Actions and Events. The following interfaces are + used for representing these interactions.

      +
      +

      7.1 The Interaction + interface

      +

      The Interaction interface + is an abstract class to represent Thing + interactions: Properties, Actions and + Events.

      +

      The InteractionFragment + dictionary holds the common properties of PropertyFragment, ActionFragment and EventFragment dictionaries used for + initializing ThingProperty, ThingAction and ThingEvent objects in a ThingFragment dictionary used for + creating an ExposedThing + object.

      +
      + 
      interface Interaction {
+  readonly attribute (Form or FrozenArray<Form>) forms;
+};
+Interaction includes InteractionFragment;
      +
      +

      The forms read-only + property represents the protocol bindings initialization data + and is initialized by the WoT Runtime.

      +
      +
      +

      7.2 The ThingProperty + interface

      +

      The ThingProperty interface + is used in ConsumedThing and + ExposedThing objects to + represent Thing Property + interactions.

      +

      The PropertyFragment + dictionary is used for initializing Property objects + in a ThingFragment + dictionary used for creating an ExposedThing object. It MUST implement one of the + DataSchema dictionaries.

      +
      + 
      interface ThingProperty : Interaction {
+  // getter for PropertyFragment properties
+  getter any (DOMString name);
+  // get and set interface for the Property
+  Promise<any> read();
+  Promise<void> write(any value);
+};
+ThingProperty includes PropertyFragment;
+ThingProperty includes Observable;
      +
      +

      The ThingProperty interface + contains all the properties defined on PropertyFragment as read-only + properties.

      +

      The type + read-only property represents the type definition for the + Property as a DataSchema dictionary object.

      +

      The writable read-only property tells + whether the Property value can be updated. If it + is false, then the set(value) + method SHOULD always + reject.

      +

      The observable read-only + property tells whether the Property supports + subscribing to value change notifications. If it is + false, then the subscribe() method + SHOULD always + fail.

      +

      The constant read-only property + - defined in DataSchema - tells + whether the Property value is a constant. If + true, the set() and + subscribe() methods SHOULD always fail.

      +

      The required read-only property + - defined in DataSchema - tells + whether the Property should be always present on + the ExposedThing + object.

      +

      The read() + method will fetch the value of the Property. + Returns a Promise that resolves with the + value, or rejects with an error.

      +

      The + write() method will attempt to set the value of + the Propertyspecified in the + value argument whose type SHOULD match the one specified by the + type property. Returns a Promise that + resolves on success, or rejects on an error.

      +
      +
      +

      7.3 The ThingAction + interface

      +
      + 
      interface ThingAction : Interaction {
+  Promise<any> invoke(optional any inputValue);
+};
+ThingAction includes ActionFragment;
      +
      +

      The + invoke() method when invoked, starts the + Action interaction with the input value provided by + the inputValue argument. If inputValue + is null, the action does not take any arguments + and rejects if any arguments are provided. If the value is + undefined, the action will ignore any arguments + provided. Otherwise the type of inputValue + SHOULD match the + DataSchema definition in the + input property. Returns a Promise that + will reject with an error or will resolve with a value of + type defined by the output property.

      +
      +
      +

      7.4 The ThingEvent interface

      +
      + 
      interface ThingEvent : Interaction {
+};
+ThingEvent includes EventFragment;
+ThingEvent includes ThingProperty;
      +
      +

      Since ThingEvent implements + Observable through the ThingProperty interface, event + subscription is done by invoking the subscribe() + method on the event object that returns a cancelable Subscription.

      +
      +
      +

      7.5 The ExposedEvent + interface

      +
      + 
      interface ExposedEvent : ThingEvent {
+  void emit(any payload);
+};
      +
      +
      +

      7.5.1 The emit() + method

      +

      Emits an event that carries data specified by the + payload argument.

      +
      +
      +
      +

      7.6 The value-matching + algorithm

      +

      The value-matching algorithm is applied to a + value input in relation to a valueType + property of type DataSchema, for instance the + value and type properties of a + PropertyFragment + object, or the inputValue parameter to the + invoke() method of a ThingAction object in relation to the + same object. It executes the following steps:

      +
        +
      1. If valueType.type is not defined, or does + not fully match a string enumerated in DataType, return false. +
        2. +
      2. Otherwise, if valueType.type is + "null": if value is + null, return true, otherwise + return false.
        3. +
      3. Otherwise, if valueType.type is + "boolean": if value is either + true or false, then return + true, otherwise return + false.
        4. +
      4. Otherwise, if valueType.type is + "integer": if value is not an + integer type defined by the underlying platform (such as + long or long long), then return + false, otherwise execute the following + sub-steps: +
          +
        1. If valueType.minimum is defined and + value is not greater or equal than that + value, return false.
          2. +
        2. If valueType.maximum is defined and + value is not less or equal than that value, + return false.
          3. +
        3. Return true.
          4. +
        +
        5. +
      5. Otherwise, if valueType.type is + "number", if value is not an + integer or floating point type defined by the underlying + platform (such as long or long + long or double), then return + false, otherwise otherwise execute the + following sub-steps: +
          +
        1. If valueType.minimum is defined and + value is not greater or equal than that + value, return false.
          2. +
        2. If valueType.maximum is defined and + value is not less or equal than that value, + return false.
          3. +
        3. Return true.
          4. +
        +
        6. +
      6. Otherwise, if valueType.type is + "string": if value is not a string + type defined by the underlying platform, then return + false, otherwise return true. In this + case the algorithm expects a third parameter + valueType.enum and runs the following + sub-steps: +
          +
        • If valueType.enum is an array of + strings, then if value fully matches one of + the strings defined in the array, return + true.
          • +
        • Otherwise, return false.
          • +
        +
        7. +
      7. Otherwise, if valueType.type is + "array", execute the following sub-steps: +
          +
        1. If value is not an array, return + false.
          2. +
        2. If valueType.minItems is defined, and + value does not contain at least + valueType.minItems elements, return + false.
          3. +
        3. If valueType.maxItems is defined, and + value contains more than + valueType.maxItems elements, return + false.
          4. +
        4. Otherwise, if valueType.items is + undefined, return false.
          5. +
        5. Otherwise, if valueType.items is + null, return true (i.e. any + type is accepted as array element, including + heterogenous arrays).
          6. +
        6. Otherwise, for each element of the array + value run the value-matching algorithm + against the valueType.items object. If any + of these runs returns false, then return + false. +
          7. +
        7. Otherwise, return true.
          8. +
        +
        8. +
      8. Otherwise, if type is "object", + execute the following sub-steps: +
          +
        1. If value is not an Object, + return false.
          2. +
        2. If valueType.properties is not defined, + return false.
          3. +
        3. If valueType.properties is + null, return true (i.e. + accept any object value).
          4. +
        4. For each string in the + valueType.required array, if it does not + match a property name in the + value.properties object or in the + value object, then return + false.
          5. +
        5. For each property with name propName and + value propDataSchema found in + valueType.properties, run the following + sub-steps: +
            +
          1. If the result of applying the value-matching algorithm + on the value value[propName] and + propDataSchema is false, + then return false. +
            2. +
          +
          6. +
        6. Return true.
          7. +
        +
        9. +
      +
      +
      +
      + +

      8. + Observables

      +

      This section is non-normative.

      +

      Observables are proposed to + be included in ECMAScript and are used for handling pushed data + associated with various possible sources, for instance events, + timers, streams, etc. A minimal required implementation is + described here.

      +
      +
      + Editor's note +
      +

      This section is informal and contains rather + laconic information for implementations on what to support + for interoperability.

      +
      +
      + 
      interface Observable {
+  Subscription subscribe(EventHandler handler,
+                         optional ErrorHandler errorHandler,
+                         optional OnComplete onComplete);
+};
+interface Subscription {
+  void unsubscribe();
+  readonly attribute boolean closed;
+};
+callback EventHandler = void (any value);
+callback ErrorHandler = void (Error error);
+callback OnComplete = void ();
      +
      +

      The following callbacks can be provided when subscribing to + an Observable:

      +
        +
      • The EventHandler callback takes + the next sample for the data in the value + argument.
        • +
      • The ErrorHandler callback takes + an error in the value argument. It is called + when an error occured in producing the data the client should + know about.
        • +
      • The OnComplete callback is called + when the data source has finished sending values.
        • +
      +
      +

      8.1 The Subscription + interface

      +

      Contains the closed + property of type boolean that tells if the + subscription is closed or active.

      +

      Also, contains the unsubscribe() + method that cancels the subscription, i.e. makes a request to + the underlying platform to stop receiving data from the + source, and sets the closed property to + false.

      +
      +
      +

      8.2 The Observable interface

      +

      The Observable interface + enabled subscribing to pushed data notifications by the + subscribe() + method:

      +
        +
      • Initialize the data handler callback with the first + function argument.
        • +
      • If the next argument is provided and is a function, + initialize the error handling callback with that function, + or throw on error.
        • +
      • If the third argument is provided and is a function, + initialize the completion handler with that function, or + throw on error.
        • +
      • After callback initializations, the implementation + should request the underlying platform to provide data, + error and completion notifications for the supported data + source.
        • +
      +
      +
      +
      + +

      9. Security and + Privacy

      +

      In general the security measures taken to protect a WoT + system will depend on the threats and attackers that system may + face and the value of the assets needs to protect. A detailed + discussion of security and privacy considerations for the Web + of Things, including a threat model that can be adapted to + various circumstances, is presented in the informative document + [WOT-SECURITY-CONSIDERATIONS]. + This section includes only normative recommendations relevant + to the WoT Thing Description.

      +

      When designing new devices and services + for use with the WoT, we have documented a set of best + practices in [WOT-SECURITY-BEST-PRACTICES] + that SHOULD be + followed. This best-practices document may be updated as + security measures evolve. Following these practices does not + guarantee security, but it at least will help to avoid common + known vulnerabilities and pitfalls.

      +

      Below are specific recommendations related to WoT runtime + implementations:

      +
        +
      • In basic WoT setups, all scripts running inside the WoT + runtime are considered trusted, and therefore there is no + strong need to perform strict isolation between each running + script instance. However, depending on device capabilities + and deployment use case scenario risk level it might be + desirable to do so. +
          +
        • For example, if one script handles sensitive + privacy-related data and well-audited, it might be + desirable to separate it from the rest of the script + instances to minimize the risk of data exposure in case + some other script inside WoT gets compromised during the + runtime. Therefore the WoT + runtime SHOULD + perform isolation of script instances and their data in + cases when scripts handle privacy-related or other + critical security data.
          • +
        • Another example is mutual co-existence of different + tenants on a single WoT device. In this case each WoT + runtime instance will be hosting a different tenant, and + isolation between them is required. Therefore the WoT + runtime SHOULD + perform isolation of WoT runtime instances and their data + if a WoT device has more than one tenant.
          • +
        Such isolation can be performed within the WoT Runtime + using platform security mechanisms available on the device. + For more information see Section "WoT Servient + Single-Tenant" and "WoT Servient Multi-Tenant" of + [WOT-SECURITY-CONSIDERATIONS]. +
        • +
      • WoT scripts are using WoT Scripting API to implement the + functionality and logic for WoT Things. In addition to + providing the isolation between script and runtime instances, + the WoT runtime needs to protect the underlying physical + device from potentially misbehaving WoT scripts. Therefore the + WoT Runtime SHOULD + avoid directly exposing the native device interfaces to the + script developers. Instead a WoT Runtime should + provide a hardware abstraction layer for accessing the native + device interfaces. Additionally, in order to reduce the + damage to a physical WoT device in cases a WoT script gets + compromised, it is important to minimize the number of + interfaces that are exposed or accessible to a particular WoT + script based on its functionality. Therefore the WoT Runtime + SHOULD only expose a + minimal set of interfaces to a WoT script based on its + intended functionality.
        • +
      • If the WoT runtime supports post-manufacturing + provisioning or update of WoT scripts, WoT runtime or any + related data (including security credentials), it can be a + major attack vector. An attacker can try to modify any above + described part during the update or provisioning process or + simply provision attacker's code and data directly. + Therefore, if WoT Runtime supports + post-manufacturing provisioning or update of WoT scripts, WoT + runtime or any related data, such operations SHOULD be done in a secure + fashion. A set of recommendations for secure update + and post-manufacturing provisioning can be found in + [WOT-SECURITY-BEST-PRACTICES].
        • +
      • Typically the WoT runtime needs to store the security + credentials that are provisioned to a WoT device to operate + in WoT network. The confidentiality or integrity of these + credentials should not be compromised. Therefore the + WoT runtime SHOULD + securely store the provisioned security credentials, + guaranteeing their integrity and confidentiality. + In + case there are more than one tenant on a single WoT-enabled + device, a WoT Runtime SHOULD guarantee isolation of each tenant + provisioned security credentials. Additionally, in + order to minimize a risk that provisioned security + credentials get compromised, the WoT runtime should not have + any way for WoT scripts to query these credentials. + Therefore, the WoT Runtime SHOULD NOT expose any API + for WoT scripts to query the provisioned security + credentials.
        • +
      +

      Some additional specific recommendations relevant for WoT + script developers:

      +
        +
      • A typical way to compromise any process is to send it a + corrupted input via one of the exposed interfaces. + Therefore developers SHOULD perform validation on + all WoT script inputs, including fuzzing. + There are many tool and techniques in existence to do such + validation. More details can be found in [WOT-SECURITY-TESTING].
        • +
      • As any software, complex scripts with a lot of + functionality presents a higher risk of development mistakes. + Such scripts are also hard to verify and test appropriately. + Therefore developers SHOUD + minimize the functionality and complexity of WoT + scripts.
        • +
      • If a WoT script performs a heavy functional processing on + received requests before the request is authenticated, it + presents a great risk for Denial-Of-Service (DOS) attacks. + Therefore WoT scripts SHOULD avoid heavy functional processing + without prior successful authentication of requestor. + The set of recommended authentication mechanisms can be found + in [WOT-SECURITY-BEST-PRACTICES].
        • +
      • WoT developers should remember that a content of a TD can + change, including its identified, id, which is not an + immutable identifier. Therefore WoT scripts SHOULD use the provided WoT script API to + subscribe for notifications on TD changes.
        • +
      +
      +
      + +

      10. Terminology and conventions

      +

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

      +

      JSON-LD is + defined in [JSON-LD] as a JSON document that is + augmented with support for Linked Data.

      +

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

      +

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

      +

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

      +

      The term + secure + context is defined in [WEBAPPSEC].

      +

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

      +

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

      +

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

      +

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

      +

      The terms hyperlink reference and + relation + type are defined in [HTML5] and RFC8288.

      +
      +
      + +

      11. + Conformance

      +

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

      +

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

      +

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

      +

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

      +

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

      +

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

      +

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

      +

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

      +
      +
      + +

      A. + Changes

      +

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

      + +
      +
      + +

      B. Open issues

      +

      The following problems are being discussed and need most + attention:

      +
        +
      • Security related metadata + (https://github.com/w3c/wot-scripting-api/issues/91).
        • +
      • Providing Protocol Binding for + ExposedThing + (https://github.com/w3c/wot-scripting-api/issues/45). +
        • +
      • Script management and runtime related issues + (https://github.com/w3c/wot-scripting-api/issues/)
        • +
      +
      +
      + +

      C. + Acknowledgements

      +

      Special thanks to former editor Johannes Hund (until August + 2017, when at Siemens AG) for developing this specification. + Also, the editors would like to thank Dave Raggett, Matthias + Kovatsch, Michael Koster and Michael McCool for their comments + and guidance.

      +
      +
      + +

      D. + References

      +
      +

      D.1 Normative references

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

      D.2 Informative references

      +
      +
      [HTML]
      +
      + HTML + Standard. Anne van Kesteren; Domenic Denicola; + Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. + Living Standard. URL: https://html.spec.whatwg.org/multipage/ +
      +
      +
      +
      + + + + diff --git a/releases/wd3/diff.html b/releases/wd3/diff.html new file mode 100644 index 00000000..2cde3a44 --- /dev/null +++ b/releases/wd3/diff.html @@ -0,0 +1,19177 @@ + + + + + + + + + + + + +Web of Things (WoT) Scripting API + + + + + + + + + + + +
      + +

      +Web +of +Things +(WoT) +Scripting +API +

      +

      + +W3C + +Working +Draft +5 +April + + +

      +
      +
      +This +version: +
      +
      +https://www.w3.org/TR/2018/WD-wot-scripting-api-20180405/ + + +https://www.w3.org/TR/2018/WD-wot-scripting-api-20181021/ + + +
      +
      +Latest +published +version: +
      +
      + +https://www.w3.org/TR/wot-scripting-api/ + +
      +
      +Latest +editor's +draft: +
      +
      + +https://w3c.github.io/wot-scripting-api/ + +
      +
      +Previous +version: +
      +
      +https://www.w3.org/TR/2017/WD-wot-scripting-api-20170914/ + + +https://www.w3.org/TR/2018/WD-wot-scripting-api-20180405/ + + +
      +
      +Editors: +
      +
      + +Zoltan +Kis + +( + +Intel + +) +
      +
      + +Kazuaki +Nimura + +( + +Fujitsu +Ltd. + +) +
      +
      + +Daniel +Peintner + +( + +Siemens +AG + +) +
      +
      + +Johannes +Hund + +(Former +Editor, +when +at +Siemens +AG) +
      +
      +Contributors: +
      +
      + +In +the +GitHub +repository + +
      +
      +Repository: +
      +
      + +We +are +on +GitHub + +
      +
      + +File +a +bug + +
      +
      +

      + +Copyright + +© +2017-2018 + + +W3C + + + +® + +( + + +MIT + +, + + +ERCIM + +, + +Keio +, + +Beihang + +). + +W3C + + +liability +, + +trademark + +and + +permissive +document +license + +rules +apply. +

      +
      +
      +
      +

      +Abstract +

      +

      +The +overall + + +Web +of +Things + +(WoT) +provides +layered +interoperability +between + +concepts +are +described +in +the + +WoT +Architecture + +document. +The +Web +of + +Things +is +made +of +entities +( + +Thing + + +by +using + +s) +that +can +describe +their +capabilities +in +a +machine-interpretable +format, +the + +Thing +Description + +(TD) +and +expose +these +capabilities +through + +the + +WoT +Interface +, +that +is, +network +interactions +modeled +as + +Properties + + +s. + +for +reading +and +writing +values, + +Action + +s +to +execute +remote +procedures +with +or +without +return +values +and + +Event + +s +for +signaling +notifications. + +

      +

      +This +specification +describes +a +programming +interface +representing +the + +WoT +Interface + +that +allows +scripts +run +on +a + +Thing + +to +discover +and +consume +(retrieve) +other + +Thing +Description + + +s +and +to +expose + +Things + +characterized +by + +WoT +Interactions +, +i.e. +Properties +, +Actions + + +and +Events +. + +specified +by +a +script. + +

      +

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

      +
      +
      +

      +Status +of +This +Document +

      +

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

      +

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

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

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

      +
      +

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

      +

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

      +

      +Changes +from +the +previous +publication +can +be +found +in + +Appendix +A + +B + +. +A + +diff-marked +version + +of +this +document +is +also +available +for +comparison +purposes. +

      +

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

      +

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

      +

      +This +document +is +governed +by +the + +1 +February +2018 + +W3C + +Process +Document +. +

      +
      + +
      +

      + +1. + +Introduction + + +

      +

      +The +overall + +WoT +concepts +are +described +in +the +WoT +Architecture +document. +The +Web +of +Things +is +made +of +entities +( +Thing +s) +that +can +describe +their +capabilities +in +a +machine-interpretable +format, +the + +provides +layered +interoperability +based +on +how + +Thing +Description + + +(TD) + +s +are +modeled: +as +being +"consumed" + +and +expose +these +capabilities +through +the +WoT +Interface +. +Support +for +scripting +is +optional +for +WoT +devices. + +"exposed". + +

      +

      +By + +consuming +a +TD +, +a +client + +Thing + +creates +a +runtime +resource +model +that +allows +accessing +the + +Properties +, + +Actions + +and + +Events + +exposed +by +the +server + +Thing +. + + +exposed +on +a +remote +device. + +

      +

      +Exposing +a + +Thing + +requires +defining +a + +Thing +Description + +(TD) +and +instantiating +a +software +stack +needed + +to +serve +requests +for +accessing +the +exposed + +Properties +, + +Actions + +and + +Events +. +This +specification +describes +how +to +expose +and +consume + +Thing + +s +by +a +script. +

      +
      +
      + +Note + +
      +

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

      +
      +
      +
      + +Note + +
      +

      +This +specification +does +not +make +assumptions +on +how +the + +WoT +Runtime + +handles +and +runs +scripts, +including +single +or +multiple +tenancy, +script +deployment +and +lifecycle +management. +The +API +already +supports +the +generic +mechanisms +that +make +it +possible +to +implement +script +management, +for +instance +by +exposing +a +manager + +Thing + +whose + +Actions + +(action +handlers) +implement +script +lifecycle +management +operations. +

      +
      +

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

      +
      +
      +

      + +2. + +Use +Cases + + +

      +

      + +This +section +is +non-normative. + +

      +

      +The +following +scripting +use +cases +are +supported +in +this +specification: +

      +
      +

      + +2.1 + +Discovery + + +

      +
        +
      • +Discover +all + +Thing + +s +in +the +WoT +network +by +sending +a +broadcast +request. +
        • +
      • +Discover + +Thing + +s +running +in +the +local + +WoT +Runtime +. +
        • +
      • +Discover +nearby + +Thing + +s, +for +instance +connected + +by +NFC +or +Bluetooth. +
        • +
      • +Discover + +Thing + +s +by +sending +a +discovery +request +to +a +given +registry. +
        • +
      • +Discover + +Thing + +s +by +filters +defined +on + +Thing +Description + +s +
        • +
      • +Discover + +Thing + +s +by +semantic +filters. + +queries. + +
        • +
      • +Stop +or +suppress +an +ongoing +discovery +process. +
        • +
      • +Optionally +specify +a +timeout +to +the +discovery +process +after +which +it +is +stopped/suppressed. +
        • +
      +
      +
      +

      + +2.2 + +Consuming +a +Thing + + +

      + +
      +
      +

      + +2.3 + +Exposing +a +Thing + + +

      +
        +
      • +Exposing +the + +Thing + +includes +generating +the +protocol +bindings +in +order +to +access +lower +level +functionality. +
        • +
      • +Create +a +local + + +ExposedThing + + +to +be +exposed, +based +on +a + +Thing +Description + +provided +in +string +serialized +format, +or +out +of +a +template +or +an +existing + + +ConsumedThing + + +object. +
        • +
      • +Add +a + +Property + +definition +to +the + +Thing +. +
        • +
      • +Add +an + +Action + +definition +to +the + +Thing +. +
        • +
      • +Add +an + +Event + +definition +to +the + +Thing +. +
        • +
      • +Attach +semantic +information +to +the + +Thing +. +
        • +
      • +Attach +semantic +information +to +a + +Property +. +
        • +
      • +Attach +semantic +information +to +an + +Action +. +
        • +
      • +Attach +semantic +information +to +an + +Event +. +
        • +
      • +Emit +an + +Event +, +i.e. +notify +all +listeners +subscribed +to +that + +Event +. +
        • +
      • +Provide +notifications +for + +TD + +changes +to +clients +subscribed +to +that. +
        • +
      • +Mark/unmark +the +Thing +to +be +discoverable. +
        • +
      • +Mark/unmark +the +Thing +to +be +consumable. +
        • +
      • +Start +the +exposed + +Thing + +in +order +to +process +external +requests. +
        • +
      • +Stop +the +exposed + +Thing +. +
        • +
      • +Register +handlers +for +external +requests: +
          +
        • +to +retrieve +a + +Property + +value; +
          • +
        • +to +update +a + +Property + +value; +
          • +
        • +to +run +an + +Action +: +take +the +parameters +from +the +request, +execute +the +defined +action, +and +return +the +result; +
          • +
        +
        • +
      +
      +
      +
      +

      + +3. + +The + + +WoT + + +object + + +

      +

      +The +WoT +object +is +the +API +entry +point +and +it +is +exposed +by +an +implementation +of +the + +WoT +Runtime +. +The + +WoT +object + +does +not +expose +properties, +only +methods +for +discovering, +consuming +and +exposing +a + +Thing +. +

      +
      +
      + +Note + +
      +

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

      +
      +
      +
      data-idl="" data-title="WoT">interface <span class=
+"idlInterfaceID"><a data-no-default="" data-link-for="" data-lt=""
+href="#dom-wot" class="internalDFN" data-link-type=
+"dfn"> {
+<span class="idlMethod" id="idl-def-wot-discover-filter" data-idl=
+"" data-title="discover" data-dfn-for="wot">    <span class=
+"idlMethType"><a href="#dom-observable" class="internalDFN"
+data-link-type="dfn"><<a href=
+"#dom-consumedthing" class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlMethName"><a data-no-default="" data-link-for="wot" data-lt=
+"discover()|discover" href="#dom-wot-discover" class="internalDFN"
+data-link-type="dfn">discover(<span class=
+"idlParam">optional <a href=
+"#dom-thingfilter" class="internalDFN" data-link-type=
+
+data-idl="" data-title="WoT">// [SecureContext]
+// [NamespaceObject]
+interface 
+data-link-for="" data-lt="" href="#dom-wot" class="internalDFN"
+data-link-type="dfn">WoT {
+  
+data-link-type=
+"dfn">Observable discover(optional 
+"dfn">ThingFilter "idlParamName">filter
+<span class="idlMethod" id="idl-def-wot-fetch-url" data-idl=""
+data-title="fetch" data-dfn-for="wot">    <span class=
+"idlMethType"><a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<<a href="#dom-thingdescription"
+class="internalDFN" data-link-type=
+
+"idlParamName">filter);
+  
+"https://heycam.github.io/webidl/#idl-promise">Promise<
+"dfn">ThingDescription> "fetch()|fetch" href="#dom-wot-fetch" class="internalDFN"
+data-link-type="dfn">fetch(<span class=
+
+"wot.fetch()|wot.fetch|fetch()|fetch" href="#dom-wot-fetch" class=
+"internalDFN" data-link-type=
+"dfn">fetch(
+"idlParam">"https://heycam.github.io/webidl/#idl-USVString">USVString
+<span class="idlMethod" id="idl-def-wot-consume-td" data-idl=""
+data-title="consume" data-dfn-for="wot">    <span class=
+"idlMethType"><a href="#dom-consumedthing" class="internalDFN"
+
+"https://heycam.github.io/webidl/#idl-USVString">USVString url);
+  "dfn"><a data-no-default=""
+data-link-for="wot" data-lt="consume()|consume" href=
+
+"dfn">ConsumedThing 
+"#dom-wot-consume" class="internalDFN" data-link-type=
+"dfn">consume<span class=
+"idlParamType"><a href="#dom-thingdescription" class="internalDFN"
+data-link-type=
+
+"dfn">consume(
+"dfn">ThingDescription "idlParamName">td
+<span class="idlMethod" id="idl-def-wot-produce-model" data-idl=""
+data-title="produce" data-dfn-for="wot">    <span class=
+"idlMethType"><a href="#dom-exposedthing" class="internalDFN"
+
+"idlParamName">td);
+  "dfn"><a data-no-default=""
+data-link-for="wot" data-lt="produce()|produce" href=
+"#dom-wot-produce" class="internalDFN" data-link-type=
+"dfn">produce<span class=
+"idlParamType"><a href="#dom-thingmodel" class="internalDFN"
+
+"dfn">ExposedThing produce(ThingModel model);
+  
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> register(USVString directory, ExposedThing thing);
+  
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> unregister(USVString directory, ExposedThing thing);
+};
+typedef object ThingFragment;
+typedef object PropertyFragment;
+typedef object ActionFragment;
+typedef object EventFragment;
+typedef object DataSchema;
+typedef object SecurityScheme;
+typedef object 
+data-link-type=
+"dfn">
+};
+<span class="idlTypedef" id="idl-def-thingdescription" data-idl=""
+data-title="ThingDescription">typedef <span class=
+"idlTypedefType"><a href=
+
+"dfn">Link;
+typedef object Form;
+typedef 
+"https://heycam.github.io/webidl/#idl-USVString">USVString "dfn">
+<span class="idlTypedef" id="idl-def-thingmodel" data-idl=""
+data-title="ThingModel">typedef <span class=
+"idlTypedefType">(<a href="#dom-thingtemplate" class="internalDFN"
+data-link-type="dfn"> or <a href=
+
+"dfn">ThingDescription;
+typedef (ThingFragment or 
+"#dom-thingdescription" class="internalDFN" data-link-type=
+"dfn">ThingDescription) 
+
+ThingModel
+
+
+
+;
+
+
      +
      +
      +
      + +Editor's +note + +
      +

      +The +algorithms +for +the +WoT +methods +will +be +specified +later, +including +error +handling +and +security +considerations. +

      +
      +

      +The + +ThingModel + +type +represents +either +a + +ThingFragment +, +or +a + +ThingDescription +.

      +
      +

      + +3.1 + +The + + +discover() + + +method + + +

      +

      +Starts +the +discovery +process +that +will +provide + + +ConsumedThing + +ThingDescription + + + +objects + +s + +that +match +the +optional +argument + +filter + +of +type + + + + +ThingFilter + + +. +When +the +argument +is +not +provided, +starts +the +widest +discovery +the +Thing +Description +and +Protocol +Bindings +allow +and +support. + +Returns +an +[ + + +Observable + +](https://github.com/tc39/proposal-observable) + +object +that +can +be +subscribed +to +and +unsubscribed +from. +The +handler +function +provided +to +the +Observable +during +subscription +will +receive +an +argument +of +type + +USVString + +representing +a + +ThingDescription +. +

      +
      +

      + +3.1.1 + +The + + +DiscoveryMethod + + +enumeration + + +

      +
      +
      "DiscoveryMethod">typedef <a href=
+
+"DiscoveryMethod">typedef 
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString 
+
+DiscoveryMethod
+
+
+
+;
+
+
      +
      +

      + + +DiscoveryMethod + + +represents +the +discovery +type +to +be +used: +

      + +
      +
      +

      + +3.1.2 + +The + + +ThingFilter + + +dictionary + + +

      +

      +The + + +ThingFilter + + +dictionary +that +represents +the +constraints +for +discovering + +Thing + +s +as +key-value +pairs. +

      +
      +
      dictionary "dfn"> {
+<span class="idlMember" id="idl-def-thingfilter-method" data-idl=""
+data-title="method" data-dfn-for="thingfilter">    <span class=
+"idlMemberType"><a href="#dom-discoverymethod" class="internalDFN"
+data-link-type=
+"dfn">      <span class=
+"idlMemberName"><a data-no-default="" data-link-for="thingfilter"
+data-lt="" href="#dom-thingfilter-method" class="internalDFN"
+data-link-type="dfn"> = <span class=
+"idlMemberValue">"any"
+<span class="idlMember" id="idl-def-thingfilter-url" data-idl=""
+data-title="url" data-dfn-for="thingfilter">    <span class=
+"idlMemberType"><a href=
+"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default=""
+
+"dfn">ThingFilter {
+  (DiscoveryMethod or DOMString) method = "any";
+  
+"https://heycam.github.io/webidl/#idl-USVString">USVString? 
+data-link-for="thingfilter" data-lt="" href="#dom-thingfilter-url"
+class="internalDFN" data-link-type=
+"dfn">
+<span class="idlMember" id="idl-def-thingfilter-query" data-idl=""
+data-title="query" data-dfn-for="thingfilter">    <span class=
+"idlMemberType"><a href=
+"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default=""
+
+"dfn">url;
+  
+"https://heycam.github.io/webidl/#idl-USVString">USVString? 
+data-link-for="thingfilter" data-lt="" href=
+"#dom-thingfilter-query" class="internalDFN" data-link-type=
+"dfn">
+<span class="idlMember" id="idl-def-thingfilter-constraints"
+data-idl="" data-title="constraints" data-dfn-for=
+"thingfilter">    <a href=
+"https://heycam.github.io/webidl/#idl-sequence">sequence<a data-no-default=""
+data-link-for="thingfilter" data-lt="" href=
+"#dom-thingfilter-constraints" class="internalDFN" data-link-type=
+"dfn">
+
+"dfn">query;
+  
+data-link-type=
+"dfn">ThingFragment? fragment;
+
+};
+
+
      +
      +

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

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

      +The + + +url + + +property +represents +additional +information +for +the +discovery +method, +such +as +the +URL +of +the +target +entity +serving +the +discovery +request, +such +as + +for +instance + +a + +Thing +Directory + +(if + +method + +is + +"directory" + +) + +or +a +Thing. + +Thing +(otherwise). + +

      +

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

      +

      +The + + +constraints + +fragment + + + +property +represents +additional +information + +a + +ThingFragment + +dictionary +used + +for +the +discovery + +matching +property +by +property +against +discovered + +Thing + +s. +

      +The + +discover(filter) + +method +in + + +MUST + +run + +the +form +of +a +list +of +sets +of +property-value +pairs +(dictionaries). +The +list +elements +(dictionaries) +are +in +OR +relationship, + +following +steps: +

      1. +If +invoking + +discover() + +is +not +allowed +for +the +current +scripting +context +for +security +reasons, +throw + +SecurityError + +and +within +a +constraint +dictionary + +terminate +these +steps. +
      2. +Return +an + +Observable + +obs + +and +execute + +the +key-value +pairs +are + +next +steps + +in +AND +relationship. +Implementations +SHOULD +make + +parallel +.
      3. +If + +obs.subscribe(handler, +errorHandler, +complete) + +is +called, +execute + +the +following +mapping +from + +sub-steps: +
        1. +If + +the +constraint +dictionaries + +first +argument + +handler + +is +not +defined +or +it +is +not +a +function, +throw + +TypeError + +and +terminate +the +algorithm. +Otherwise +configure + +handler + +to +be +invoked +when +a +discovery +hit +happens. +
        2. +If +the +second +argument + +errorHandler + +is +defined, +but +it +is +not +a +function, +throw + + +SemanticAnnotations + +TypeError + + +: +for +each +property-value +pair + +and +terminate +these +steps. +Otherwise +if +defined, +save +it +to +be +invoked + +in +error +conditions. +
        3. +If +the +third +argument + +onComplete + +is +defined, +but +it +is +not + +a +constraint +dictionary, + +function, +throw + +TypeError + +and +terminate +these +steps. +Otherwise +if +defined, +save +it +to +be +invoked +when +the +discovery +process +finished +for +other +reasons +than +having +been +canceled. +
          4. +
        4. +Each +property +name +in + +If + +filter.query + +is +defined, +pass +it +as +an +opaque +string +to + +the +constraint +dictionary +SHOULD + +underlying +implementation +to +be +matched +against +discovered +items. +The +underlying +implementation +is +responsible +to +parse +it +e.g. +as +a +SPARQL +or +JSON +query +and + +match +it +against + +the +either + + +Thing +Description + +s +found +during + +the +discovery +process. +If +queries +are +not +supported, +implementations + +SHOULD + +throw +a + + +name + +NotSupported + + +property +of +a + +error +and +terminate +these +steps. +
        5. +If + +filter.fragment + +is +defined, +and +if +it +contains +other +properties +than +the +ones + +defined +in + + +SemanticType + +ThingFragment + + +on + +, +throw + +TypeError + +and +terminate +these +steps. +Otherwise +save + +the +target + +object +for +matching +the +discovered +items +against +it. +
        6. +Request +the +underlying +platform +to +start +the +discovery +process, +with +the +following +parameters: +
          • +If + +filter.method + +is +not +defined +or +the +value +is + +"any" +, +use +the +widest +discovery +method +supported +by +the +underlying +platform. +
          • +Otherwise +if + +filter.method + +is + +"local" +, +use +the +local + +Thing +Directory + + +object, + +for +discovery. +Usually +that +defines + +Thing + +s +deployed +in +the +same +device, + +or +connected +to + +the +name +of + +device +in +slave +mode +(e.g. +sensors +connected +via +Bluetooth +or + +a +Property +on + +serial +connection). +
          • +Otherwise +if + +filter.method + +is + +"directory" +, +use + +the +target + +remote + +Thing +. + +Directory + +specified +in + +filter.url +. +
            • +
          • +When + +Otherwise +if + +filter.method + +is + +"multicast" +, +use +all + +the +name +matches, + +multicast +discovery +protocols +supported +by + +the +values +are +compared. + +underlying +platform. +
      4. +Whenever +a +new +item + +td + +is +discovered +by +the +underlying +platform, +run +the +following +sub-steps: +
        1. +If + +filter.query + +is +defined, +check +if + +td + +is +a +match +for + +the +values +match, + +query. +The +matching +algorithm +is +encapsulated +by +implementations. +If +that +returns + +false +, +discard + +td + +and +continue + +the +constraint + +discovery +process. +
        2. +If + +filter.fragment + +is +matched. + +defined, +for +each +property +defined +in +it, +check +if +that +property +exists +in + +td + +and +has +the +same +value. +If +this +is + +false + +in +any +checks, +discard + +td + +and +continue +the +discovery +process. + +
          3. +Editor's +note +Constraints +are +experimental +feature, +implementations +are + +
        3. +Otherwise +if + +td + +has + +not +required +to +support +them. +Editor's +note +Semantic +annotations +need +revisiting + +been +discarded + +in +order +to +simplify +their +representation. +In + +the +[ +WOT-TD +] +specification +they +represent + +previous +steps, +invoke + +the + +handler + +function +with + +td + +as +parameter. +
      5. +Whenever +an +error +occurs +during +the +discovery +process, +and +if + +errorHandler + +is +defined, +invoke +it +with +an +argument +of +type + + +@type + +Error + + +construct. +At +the +moment +only + +whose + + +@context +, + +message + +property +is +set +to + + +@type + +UnknownError + + +unless +there +was +an +error +code +provided +by +the + +Protocol +Bindings +, +in +which +case +set +it +to +that +value. +
      6. +When +the +discovery +process +is +finished, + +and +if + +onComplete + +is +defined, +invoke +it +run +the + +cancel +discovery + +steps. +
      7. +When +the + + +@id + +obs.unsubscribe() + + +constructs +are +used +in + +method +is +called, +run + +the +TD +. + +following + +cancel +discovery + +steps: +
        1. +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. +
        2. +Set + +obs.closed + +to + +false +.
      +
      +
      +

      + +3.2 + +The + + +fetch() + + +method + + +

      +

      +Accepts +an + +url + +argument +of +type + +USVString + +that +represents +a +URL +(e.g. + +"file://..." + +or + +"https://..." + +) + +and +returns +a + + +Promise + + +that +resolves +with +a + + +ThingDescription + +. + + +(a +serialized + +JSON-LD + +document +of +type + +USVString + +). + +

      +3.3 + +

      +The + +ThingDescription + +fetch(url) + + +type +Representation +of + +method + +MUST + +run + +the +Thing +Description +, +standardized + +following +steps: +

      1. +Return +a + +Promise + +promise + +and +execute +the +next +steps + +in +parallel +.
      2. +If +invoking + +fetch() + +is +not +allowed +for + +the +Wot +Things + +current +scripting +context +for +security +reasons, +reject + +promise + +with + +SecurityError + +and +terminate +these +steps. +
      3. +If +the +argument + +url + +is +not +a +URL, +reject + +promise + +with + +TypeError + +and +terminate +these +steps. +
      4. +Make +a +request +to +fetch +the +content +of + +url + +as +described +by +the + +Protocol +Bindings + +and +wait +for +the +reply. +Implementations +encapsulate +the +fetching +process +and +the +accepted +media +types +(such +as + +application/td+json + +), +as +far +as +a +valid + +Thing + +Description + +specification. + +can +be +obtained +as +defined +in +[ + +Note + + +WOT-TD + +In +this +version +of + + +]. +Let + +td + +be + +the +API, + + +Thing +Description + +s +are +represented + +string-serialized +from +the +returned +content, + +as +opaque +strings, +denoting +a +serialized +form, +for +instance +JSON +or +JSON-LD. +See +Issue +38 + +specified +in +the + +Thing +Description +serialization +.
      5. +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 +Issue +45 +. + +terminate +these +steps. +
      6. +Otherwise +resolve + +promise + +with + +td + +and +terminate +these +steps. +
      +
      +
      +

      + +3.4 + +3.3 + + +The + + +consume() + + +method + + +

      +

      +Accepts +an + +td + +argument +of +type + + + +ThingDescription + + + +and +returns +a + + +ConsumedThing + + +object +instantiated +based +on +parsing + +that +description. +

      +

      +The + +consume(td) + +method +must +run +the +following +steps: +

      1. +If +the +argument + +td + +is +not +a +string, +throw +a + +TypeError + +and +terminate +these +steps. +
      2. +Let + +stub + +be +the +result +of +running +the + +TD +parsing +algorithm + +with + +td + +as +argument. +If +that +throws +an +error, +re-throw +the +error +and +terminate +these +steps. +
      3. +If + +stub + +does +not +have +an +own +property +that +is +defined +in + +ThingFragment + +with +a +default +value, +add +that +property +and +value +to + +stub +.
      4. +Create +a + +ConsumedThing + +object + +thing + +initialized +from + +stub + +that +implements + +Observable +.
      5. +Add +the + +read() + +and + +write() + +methods +to +the + +ThingProperty + +elements +so +that +they +make +requests +to +access +the +remote + +Thing + +s +and +wait +for +the +reply, +as +defined +by +the + +Protocol +Bindings +. +Also, +all + +ThingProperty + +elements + +SHOULD + +implement + +Observable +, +i.e. +define +a + +subscribe() + +method +that +should +make +request +to +observe +the +given + +Properties + +as +defined +by +the + +Protocol +Bindings +.
      6. +Add +the + +invoke() + +methods +to +the + +ThingAction + +elements +so +that +they +make +requests +to +the +remote + +Thing + +to +invoke +its +actions, +as +defined +by +the + +Protocol +Bindings +.
      7. +Add +the + +subscribe() + +method +to +all + +ThingEvent + +elements +so +that +they +make +requests +to +subscribe +to +the +events +defined +by +the +remote + +Thing +, +as +defined +by +the + +Protocol +Bindings +.
      8. +Return + +thing +.
      +
      +
      +

      + +3.5 + +3.4 + + +The + + +produce() + + +method + + +

      +

      +Accepts +a + +model + +argument +of +type + + + +ThingModel + + + +and +returns +an + + +ExposedThing + + +object, +locally +created +based +on +the +provided +initialization +parameters. +An + +object. +

      +The + + +ExposedThing + +produce(model) + + +can +be +created +in + +method + +MUST + +run + +the +following +ways: + +steps: + +

      +
        +
      1. +from +an +initial + +If +invoking + +produce() + +is +not +allowed +for +the +current +scripting +context +for +security +reasons, +throw + +SecurityError + +and +terminate +these +steps. +
      2. +If +the +argument + +model +(including + + +is + +a +user +given +name +and +semantic +annotations +), + +string, + +then +adding +properties, +actions, +events + +run +the + +TD +parsing +algorithm + +with + +model + +passed +as +parameter. +If +it +throws +an +error, +re-throw +that +error + +and +request +handlers; + +terminate +this +algorithm. +Otherwise +let + +model + +be +the +returned +value. + +
        3. +
      3. +from +a +Thing +Description +(possibly +of +a + +If + +model + +is +not +an +object, +throw + +TypeError + +and +terminate +these +steps. +
      4. +If + +model + +does +not +have +an +own +property +that +is +defined +in + + +ConsumedThing + +ThingFragment + + + +object), +then +adding +request +handlers. + +with +a +default +value, +add +that +property +and +value +to + +model +. +
        5. +3.6 +The + +
      5. +Create +an + + +ThingModel + +ExposedThing + + +type +A +Thing + + +object + +thing + +initialized +from + +model +is +used +for +producing +a +new + +. +
        6. +
      6. +For +each +property +of + + +ExposedThing + + +and +can +be +either +a + +defined +in + + +ThingTemplate + +ThingFragment + + +, +initialize +the +property +based +on +the +provided +initial + +or +a + +default +values +provided +to +the +local + +WoT +Runtime + +implementation, +for +instance +initialize: +
        1. +the + + +ThingDescription + +id + + +. +3.7 +The + +property +to +be +the +final +unique +identifier +of +the + +Thing +,
        2. +the + +security + +object +of +type + + +SemanticAnnotations + +SecurityScheme + + +dictionary +A +dictionary +that +provides + + +to +represent + +the +semantic +types + +actual +security +scheme + +and +semantic +metadata. +<span class="idlDictionary" id= +"idl-def-semanticannotations" data-idl="" data-title= +"SemanticAnnotations">dictionary <span class= +"idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-semanticannotations" class="internalDFN" data-link-type= +"dfn"> { +<span class="idlMember" id= +"idl-def-semanticannotations-semantictype" data-idl="" data-title= +"semanticType" data-dfn-for="semanticannotations"> <span class= +"idlMemberType"><a href= +"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-semantictype" +class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-no-default="" data-link-for= +"semanticannotations" data-lt="" href= +"#dom-semanticannotations-semantictype" class="internalDFN" +data-link-type="dfn"> +<span class="idlMember" id="idl-def-semanticannotations-metadata" +data-idl="" data-title="metadata" data-dfn-for= +"semanticannotations"> <a href= +"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-semanticmetadata" +class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-no-default="" data-link-for= +"semanticannotations" data-lt="" href= +"#dom-semanticannotations-metadata" class="internalDFN" +data-link-type="dfn"> +}; +The + +its +properties +as +set +up +by +the +implementation, +
        3. +the + + +semanticType + +properties + + +property +denotes +a +list +of + +to +be +an +object +with +all +properties +being + + +SemanticType + +ThingProperty + + + +objects +that + +in +which +the + +read() + +and + +write() + +methods +are +provided +to + +define +local +methods +to +get +and +set +the + +Property + +values, +
        4. +the +semantic +types +that +can +be +used +in +semantic +metadata +type-value +pairs. +The + + +metadata + +actions + + +property +denotes +a +list +of + +to +be +an +object +with +all +properties +being + + +SemanticMetadata + +ThingAction + + + +objects +(type-value +pairs). +3.8 +The + +in +which +the + + +SemanticType + +invoke() + + +dictionary +<span class="idlDictionary" id= +"idl-def-semantictype" data-idl="" data-title= +"SemanticType">dictionary <span class= +"idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-semantictype" class="internalDFN" data-link-type= +"dfn"> { +<span class="idlMember" id="idl-def-semantictype-name" data-idl="" +data-title="name" data-dfn-for= +"semantictype"> required <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" +data-link-for="semantictype" data-lt="" href= +"#dom-semantictype-name" class="internalDFN" data-link-type= +"dfn"> +<span class="idlMember" id="idl-def-semantictype-context" data-idl= +"" data-title="context" data-dfn-for= +"semantictype"> required <a href= +"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default="" +data-link-for="semantictype" data-lt="" href= +"#dom-semantictype-context" class="internalDFN" data-link-type= +"dfn"> +<span class="idlMember" id="idl-def-semantictype-prefix" data-idl= +"" data-title="prefix" data-dfn-for= +"semantictype"> <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" +data-link-for="semantictype" data-lt="" href= +"#dom-semantictype-prefix" class="internalDFN" data-link-type= +"dfn"> +}; +Represents +a +semantic +type +annotation, +containing +a +name, +a +context +and + +method +is +provided +to +define + +a +prefix. + +local +method +to +run +the +defined + +Action + +s, +
          5. +
        5. +The + +the + +events + +property +to +be +an +object +with +all +properties +being + + +name + +ExposedEvent + + +attribute +represents +the +name +of +the +semantic +type + + +objects + +in +which + +the +given +context. +The + + +context + +emit() + + +attribute +represents +an +URL +link + +method +is +provided + +to +define +a +local +way +to +trigger +sending +notifications +to +all +subscribed +clients, +
        6. +and +initialize + +the +context +of +the +semantic +classification. + +other +properties +as +initialized +from + +model +. +
          7. +
        7. +Return + +thing +.

        +The +prefix + + +TD +parsing +algorithm + + +attribute +represents + +takes + +a +short +prefix +associated +with + +string + +td + +as +argument +and +runs +the +following +steps: +

        1. +Parse + +td + +according +to +the + +WoT +Thing +Description + +in +order +to +produce + +a +context. + + +JSON +object + +json +. +Update + +thing + +with +the +properties +and +values +defined +in + +json +. +
          2. +Editor's +note +Semantic +type +examples +to +be +added. + +
        2. +If +there +was +an +error +during +the +parsing, +throw +that +error +and +terminate +these +steps. +
        3. +Otherwise +return + +json +.
      +
      +
      +

      +3.9 + + +3.5 + + +The + + +SemanticMetadata + +register() + + + +dictionary +<span class="idlDictionary" id= +"idl-def-semanticmetadata" data-idl="" data-title= +"SemanticMetadata">dictionary <span class= +"idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-semanticmetadata" class="internalDFN" data-link-type= +"dfn"> { +<span class="idlMember" id="idl-def-semanticmetadata-type" +data-idl="" data-title="type" data-dfn-for= +"semanticmetadata"> <a href= +"#dom-semantictype" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-no-default="" data-link-for= +"semanticmetadata" data-lt="" href="#dom-semanticmetadata-type" +class="internalDFN" data-link-type= +"dfn"> +<span class="idlMember" id="idl-def-semanticmetadata-value" +data-idl="" data-title="value" data-dfn-for= +"semanticmetadata"> <a href= +"https://heycam.github.io/webidl/#idl-any">any<a data-no-default="" +data-link-for="semanticmetadata" data-lt="" href= +"#dom-semanticmetadata-value" class="internalDFN" data-link-type= +"dfn"> +}; + +method + + +

      +

      +The + +Takes +two +mandatory +arguments: +

      • + +SemanticMetadata + +directory + + +dictionary +describes + +denoting + +a +pair +of +semantic +type + + +Thing +Directory +, +and +value: + +
        • +
      • +The + + +type + +thing + + +attribute +represents +the +semantic +type +name +defined +by +a + +denoting +an + + +SemanticType + +ExposedThing + + + +object. +
        • +The +value +attribute +represents +the +metadata +value. + +
      +3.10 +The +ThingTemplate +dictionary + +

      +A + +Generate +the + +Thing +Template +is +a +dictionary +that +provides +a +user + +Description + +as + +td +, +given +name, +and + +the +semantic +types + + +Properties +, +Action + +s + +and +semantic +metadata +attached +to +the + + +Event + +s +defined +for +this + + + +ExposedThing + + +object. +Then +make +a +request +to +register + +td + +to +the +given +WoT + +Thing +Description +'s +root +level. + +Directory +. +

      +<span class="idlDictionary" id= +"idl-def-thingtemplate" data-idl="" data-title= +"ThingTemplate">dictionary <span class= +"idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-thingtemplate" class="internalDFN" data-link-type= +"dfn"> : <span class= +"idlSuperclass"><a href="#dom-semanticannotations" class= +"internalDFN" data-link-type= +"dfn"> { +<span class="idlMember" id="idl-def-thingtemplate-name" data-idl="" +data-title="name" data-dfn-for= +"thingtemplate"> required <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" +data-link-for="thingtemplate" data-lt="" href= +"#dom-thingtemplate-name" class="internalDFN" data-link-type= +"dfn"> +}; + +
      +
      +

      + +3.6 + +The + + +ThingTemplate + +unregister() + + + +method + + +dictionary +extends + +

      +

      +Takes +two +mandatory +arguments: +

      +Makes +a +request +to +unregister + +the +user +given +name +of + + +thing + +from + +the +given +WoT + +Thing +Directory + +. +Editor's +note +Support +for +configuration +and +security +data +might +be +added +later. + +

      +
      +
      +

      + +3.11 + +3.7 + + +Examples + + +

      +
      +
      + +Example +1 + +: + +: +Discover +Things +via +directory + +
      +
      let discoveryFilter = {
+  method: "directory",
+  url: "http://directory.wotservice.org"
+};
+let subscription = wot.discover(discoveryFilter).subscribe(
+  "hljs-params">thing { <span class=
+"hljs-built_in">console.log(<span class=
+"hljs-string">"Found Thing " + thing.name); },
+
+"hljs-params">td => {
+    console.log(
+"hljs-string">"Found Thing " + td.name);
+    
+"hljs-comment">// fetch the TD and create a ConsumedThing
+    let thing = wot.consume(td);
+  },
+
+  error => { console.log("Discovery finished because an error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);
+setTimeout( () => {
+    subscription.unsubscribe();
+    console.log("Discovery timeout");
+  },
+
+5000
+
+);
+
      +
      +Note +Note +that +canceling +a +discovery +(through +unsubscribe() +) +may +not +be +successful +in +all +cases, +for +instance +when +discovery +is +based +on +open +ended +broadcast +requests. +However, +once +unsubscribe() +has +been +called, +implementations +MUST +suppress +further +event +handling +( +i.e. +further +discoveries +and +errors) +on +the +Observable. +Also, +a +discovery +error +may +not +mean +the +end +of +the +discovery +process. +However, +in +order +to +respect +Observable +semantics +(error +always +terminates +processing), +implementations +MUST +close +or +suppress +further +event +handling +on +the +Observable. + +
      +
      + +Example +2 + +: + +: +Discover +Things +exposed +by +local +hardware + +
      +
      let subscription = wot.discover({ method: "local" }).subscribe(
+  "hljs-params">thing { <span class=
+
+"hljs-params">td => { 
+"hljs-built_in">console.log("hljs-string">"Found local Thing " + thing.name); },
+
+"hljs-string">"Found local Thing " + td.name); },
+
+  error => { console.log("Discovery error: " + error.message); },
+  () => { console.log("Discovery finished successfully");}
+);
+
      +
      +
      +
      + +Example +3 + +: + +: +Same +as +above +but +with +different +Observable +syntax + +
      +
      let subscription = wot.discover({ method: "local" }).subscribe({
+  thing => { <span class=
+
+  td => { 
+"hljs-built_in">console.log("hljs-string">"Found local Thing " + thing.name); },
+
+"hljs-string">"Found local Thing " + td.name); },
+
+  error: err => { console.log("Discovery error: " + err.message); },
+  complete: () => { console.log("Discovery finished successfully");}
+});
+
      +
      +Example +4 +: +Discover +Things +exposed +nearby, +via +Bluetooth +or +NFC +<span class= +"hljs-keyword">let subscription = wot.discover({ + : <span class= +"hljs-string">"nearby", + : [{ <span class= +"hljs-attr">protocol: <span class= +"hljs-string">"BLE-4.2" }, { <span class= +"hljs-attr">protocol: <span class= +"hljs-string">"NFC"}] +}).subscribe( + <span class= +"hljs-params">thing { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Found nearby Thing " + thing.name); }, + error => { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Discovery error: " + error.message); }, + () => { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Discovery finished successfully");} +); +Example +5 +: +Discover +Things +exposed +in +a +proprietary +way +<span class= +"hljs-keyword">let subscription = wot.discover({ + : <span class= +"hljs-string">"other", + : [{ <span class= +"hljs-attr">solution: <span class= +"hljs-string">"XYZ123", <span class= +"hljs-attr">key}] +}).subscribe( + <span class= +"hljs-params">thing { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Found Thing " + thing.name); }, + error => { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Discovery error: " + error.message); }, + () => { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Discovery finished successfully");} +); + +
      +
      +
      +

      + +4. + +The + + +ConsumedThing + + +interface + + +

      +

      +The + +Represents +an +object +that +extends +a + + +ConsumedThing + +ThingFragment + + + +interface +is +a + +with +methods +for + +client +API + +interactions +(send +request + +for +sending +requests +to +servers +in +order +to +retrieve +or +update + +reading +and +writing + +Properties +, + + +), + +invoke +Actions +, + + +Action + +s, +subscribe + +and +observe +Properties + +unsubscribe +for + +Property + + +changes + +and + +Events +. + +Event + +s. + +

      +
      +
      interface "dfn"> {
+<span class="idlAttribute" id="idl-def-consumedthing-name"
+data-idl="" data-title="name" data-dfn-for=
+"consumedthing">    readonly attribute <span class=
+"idlAttrType"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default=""
+data-link-for="consumedthing" data-lt="" href=
+"#dom-consumedthing-name" class="internalDFN" data-link-type=
+"dfn">
+<span class="idlMethod" id=
+"idl-def-consumedthing-getthingdescription" data-idl="" data-title=
+"getThingDescription" data-dfn-for="consumedthing">    <span class=
+"idlMethType"><a href="#dom-thingdescription" class="internalDFN"
+
+"dfn">ConsumedThing : 
+data-link-type=
+"dfn"> <span class=
+"idlMethName"><a data-no-default="" data-link-for="consumedthing"
+data-lt="getthingdescription()|getThingDescription" href=
+"#dom-consumedthing-getthingdescription" class="internalDFN"
+data-link-type="dfn">getThingDescription
+<span class="idlMethod" id=
+"idl-def-consumedthing-readproperty-name" data-idl="" data-title=
+"readProperty" data-dfn-for="consumedthing">    <span class=
+"idlMethType"><a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default=""
+data-link-for="consumedthing" data-lt="readproperty()|readProperty"
+href="#dom-consumedthing-readproperty" class="internalDFN"
+data-link-type="dfn">readProperty(<span class=
+"idlParam"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class="idlMethod" id=
+"idl-def-consumedthing-writeproperty-name-value" data-idl=""
+data-title="writeProperty" data-dfn-for=
+"consumedthing">    <a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default=""
+data-link-for="consumedthing" data-lt=
+"writeproperty()|writeProperty" href=
+"#dom-consumedthing-writeproperty" class="internalDFN"
+data-link-type="dfn">writeProperty(<span class=
+"idlParam"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class="idlMethod" id=
+"idl-def-consumedthing-invokeaction-name-parameters" data-idl=""
+data-title="invokeAction" data-dfn-for=
+"consumedthing">    <a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default=""
+data-link-for="consumedthing" data-lt="invokeaction()|invokeAction"
+href="#dom-consumedthing-invokeaction" class="internalDFN"
+data-link-type="dfn">invokeAction(<span class=
+"idlParam"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class="idlMethod" id=
+"idl-def-consumedthing-onpropertychange-name" data-idl=""
+data-title="onPropertyChange" data-dfn-for=
+"consumedthing">    <a href=
+"#dom-observable" class="internalDFN" data-link-type=
+"dfn">       <span class=
+"idlMethName"><a data-no-default="" data-link-for="consumedthing"
+data-lt="onpropertychange()|onPropertyChange" href=
+"#dom-consumedthing-onpropertychange" class="internalDFN"
+data-link-type="dfn">onPropertyChange(<span class=
+"idlParam"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class="idlMethod" id="idl-def-consumedthing-onevent-name"
+data-idl="" data-title="onEvent" data-dfn-for=
+"consumedthing">    <a href=
+"#dom-observable" class="internalDFN" data-link-type=
+"dfn">       <span class=
+"idlMethName"><a data-no-default="" data-link-for="consumedthing"
+data-lt="onevent()|onEvent" href="#dom-consumedthing-onevent"
+class="internalDFN" data-link-type=
+"dfn">onEvent<span class=
+"idlParamType"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class="idlMethod" id="idl-def-consumedthing-ontdchange"
+data-idl="" data-title="onTDChange" data-dfn-for=
+"consumedthing">    <a href=
+
+"dfn">ThingFragment {
+  readonly attribute DOMString id;
+  readonly attribute DOMString name;
+  readonly attribute DOMString? base;
+  readonly attribute PropertyMap properties;
+  readonly attribute ActionMap actions;
+  readonly attribute EventMap events;
+  // getter for ThingFragment properties
+  getter 
+"https://heycam.github.io/webidl/#idl-any">any (DOMString name);
+};
+[NoInterfaceObject]
+interface PropertyMap {
+  readonly maplike<DOMString, ThingProperty>;
+};
+[NoInterfaceObject]
+interface ActionMap {
+  readonly maplike<DOMString, ThingAction>;
+};
+[NoInterfaceObject]
+interface EventMap {
+  readonly maplike<DOMString, ThingEvent>;
+};
+
+"dfn">ConsumedThing includes 
+"#dom-observable" class="internalDFN" data-link-type=
+"dfn">       <span class=
+"idlMethName"><a data-no-default="" data-link-for="consumedthing"
+data-lt="ontdchange()|onTDChange" href=
+"#dom-consumedthing-ontdchange" class="internalDFN" data-link-type=
+"dfn">onTDChange
+};
+
+"dfn">Observable;
+//
+for
+TD
+changes
+
+
+
      +
      +

      +The + + +ConsumedThing + +id + + + +attribute + +represents +a +local +proxy +object + +the +unique +identifier + +of +the +remote + + +Thing +. + + +instance, +typically +a +URI, +IRI, +or +URN +as + +USVString +. +

      +4.1 + +

      +The + + +name + + +property +The +name +property + +attribute + +represents +the +name +of +the + +Thing + +as +specified +in +the +TD +. +In +this +version +it +is +read +only. + + +DOMString +. +

      +4.2 + +

      +The + + +getThingDescription() + +base + + + +method +Returns +the +Thing +Description +of + +attribute +represents + +the +Thing +. +Editor's +note +In +this +version, +introspection +based +on +TD +is +out +of +scope. +Parsing +and +exposing +Thing +Description +s + +base +URI +that + +is +discussed +in +Issue +38 +. + +valid +for +all +defined +local +interaction +resources. + +

      +4.3 + +

      +The + + +readProperty() + +properties + + + +method +Takes +the +Property +name +as +the +name +argument, +then +requests +from +the +underlying +platform +and +the +Protocol +Bindings +to +retrieve +the +Property +on +the +remote +Thing +and +return +the +result. +Returns + +attribute +represents + +a +dictionary +of + + +ThingProperty + +Promise + + +items. +The + + +PropertyMap + + +that +resolves +with +the +Property +value +or +rejects +with +an +Error +. + +4.4 +The + + +interface +represents +a +maplike +dictionary +where +all +values +are + + +writeProperty() + +ThingProperty + + +method +Takes +the +Property + + +name +as +the +name +argument +and +the +new +value +as +the +value +argument, +then +requests +from +the +underlying +platform + +objects. +The + +read() + +and +the +Protocol +Bindings + + +write() + +methods +make +a +request + +to +update + +access + +the + +Property + +Properties + + +on +the +remote + +Thing + +and +return +the +result. +Returns +a + +represented +by +this + + +ConsumedThing + +Promise + + +that +resolves +on +success +or +rejects +with +an +Error +. + +proxy +object. + +

      +4.5 + +

      +The + + +invokeAction() + +actions + + + +method +Takes +the +Action +name +from +the +name +argument +and +the +list +of +parameters, +then +requests +from +the +underlying +platform +and +the +Protocol +Bindings +to +invoke +the +Action +on +the +remote +Thing +and +return +the +result. +Returns + +attribute +represents + +a +Promise + +dictionary +of + + +ThingAction + + +that +resolves +with +the +return +value +or +rejects +with +an +Error +. + +4.6 + + +items. + +The + + +onPropertyChange() + +ActionMap + + + +method +Returns +an + +interface +represents +a +maplike +dictionary +where +all +values +are + + +Observable + +ThingAction + + + +for +the +Property +specified +in +the +name +argument, +allowing +subscribing +to +and +unsubscribing +from +notifications. + +objects. + +The +callback +function +passed +to +the + + +subscribe() + +invoke() + + +method +when +invoked +on + +represents +a +request +to +invoke + +the +returned +observer +will +receive + + +Action + +on + +the +new +property +value +each +time +it +is +changed. + +remote + +Thing +. +

      +4.7 + +

      +The + + +onEvent() + +events + + + +method +Returns +an + +attribute +represents +a +dictionary +of + + +Observable + +ThingEvent + + + +for +the +Event +specified +in +the +name +argument, +allowing +subscribing +to +and +unsubscribing +from +notifications. +The +callback +function +passed +to +the +subscribe() +method +when +invoked +on +the +returned +observer +will +receive +the +event +data +each +time +the +event +is +fired. +4.8 + +items. + +The + + +onTDChange() + +EventMap + + + +method +Returns +an + +interface +represents +a +maplike +dictionary +where +all +values +are + + +Observable + +ThingEvent + + +, +allowing +subscribing +to +and +unsubscribing +from +notifications +to +the +Thing +Description +. +The +callback +function +passed + + +objects. +Subscribing + +to +the +subscribe() +method +when +invoked + +events +involves +setting +up +an +observation +(subscription) +mechanism + +on +the +returned +observer +will +receive +the +new +Thing +Description +each +time +it +is +changed. + +remote +object. + +

      +
      +

      + +4.9 + +4.1 + + +Examples + + +

      +

      +Below +a + + + +ConsumedThing + + + +interface +example +is +given. +

      +
      +
      + +Example +6 + +4 + +: + +: +Consume +a +Thing + +
      +try { + let td = await wot.fetch("http://mmyservice.org/mySensor"); + let thing = wot.consume(td); + console.log("Thing " + thing.name + " has been consumed."); + let subscription = thing.onPropertyChange("temperature") + .subscribe(function(value) { + console.log("Temperature + " has changed to " + value); + }); + thing.invokeAction("startMeasurement", { units: "Celsius" }) + .then(() => { console.log("Temperature measurement started."); }) + .catch(e => { + console.log("Error starting measurement."); + subscription.unsubscribe(); + }) +} catch(error) { + console.log("Error during fetch or consume: " + error.message); + +
      "hljs-keyword">try {
+  
+"hljs-keyword">let subscription = wot.discover({ method: "local" }).subscribe(
+    
+"hljs-params">td => {
+      
+"hljs-keyword">let thing = wot.consume(td);
+      console.log(
+"hljs-string">"Thing " + thing.name + " has been consumed.");
+      
+"hljs-keyword">let subscription = thing["temperature"].subscribe(function(value) {
+          
+"hljs-built_in">console.log("Temperature: " + value);
+        });
+      thing.actions["startMeasurement"].invoke({ units: "Celsius" })
+        .then(() => { console.log("Temperature measurement started."); })
+        .catch(e => {
+           
+"hljs-built_in">console.log("Error starting measurement.");
+           subscription.unsubscribe();
+         })
+    },
+    error => { console.log("Discovery error: " + error.message); },
+    () => { console.log("Discovery finished successfully");}
+  );
+} catch(error) {
+  console.log(
+"hljs-string">"Error: " + error.message);
+
+};
+
      +
      +
      +
      +
      +

      + +5. + +The + + +ExposedThing + + +interface + + +

      +

      +The + + +ExposedThing + + +interface +is +the +server +API +that +allows +defining +request +handlers, +properties, + +Actions +, +and + +Events + +to +a + +Thing +. +It +also +implements +the + + +ConsumedThing + +Observable + + + +interface. +An + + +ExposedThing + + +is +created +by +the + +produce() + +method. +

      +Editor's +note +It +is +under +consideration +to +use +a +constructor +for +ExposedThing +instead +of +a +factory +method. + +
      +<a href= +"#dom-exposedthing" class="internalDFN" data-link-type= +"dfn"> implements <a href= +"#dom-consumedthing" class="internalDFN" data-link-type= +"dfn"> +<span class="idlInterface" id="idl-def-exposedthing" data-idl="" +data-title="ExposedThing">interface <span class= + +
      "idl-def-exposedthing" data-idl="" data-title=
+"ExposedThing">interface 
+"idlInterfaceID">"dfn"> {
+<span class=
+"idlSectionComment">    // define how to expose and run the Thing
+<span class="idlMethod" id="idl-def-exposedthing-start" data-idl=""
+data-title="start" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default=""
+data-link-for="exposedthing" data-lt="start()|start" href=
+"#dom-exposedthing-start" class="internalDFN" data-link-type=
+"dfn">start
+<span class="idlMethod" id="idl-def-exposedthing-stop" data-idl=""
+data-title="stop" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default=""
+data-link-for="exposedthing" data-lt="stop()|stop" href=
+"#dom-exposedthing-stop" class="internalDFN" data-link-type=
+"dfn">stop
+<span class="idlMethod" id=
+"idl-def-exposedthing-register-directory" data-idl="" data-title=
+"register" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default=""
+data-link-for="exposedthing" data-lt="register()|register" href=
+"#dom-exposedthing-register" class="internalDFN" data-link-type=
+"dfn">register(<span class=
+"idlParam">optional <a href=
+"https://heycam.github.io/webidl/#idl-USVString">USVString
+<span class="idlMethod" id=
+"idl-def-exposedthing-unregister-directory" data-idl="" data-title=
+"unregister" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href=
+
+"dfn">ExposedThing : ThingFragment {
+  readonly attribute PropertyMap properties;
+  readonly attribute ActionMap actions;
+  readonly attribute ExposedEvents events;
+  // getter for ThingFragment properties
+  getter 
+"https://heycam.github.io/webidl/#idl-any">any (DOMString name);
+  // setter for ThingFragment properties
+  setter void (
+"idlParam">DOMString name, any value);
+  // methods to expose and destroy the Thing
+  Promise<void> data-link-for="exposedthing" data-lt="unregister()|unregister"
+href="#dom-exposedthing-unregister" class="internalDFN"
+data-link-type="dfn">unregister(<span class=
+"idlParam">optional <a href=
+"https://heycam.github.io/webidl/#idl-USVString">USVString
+<span class="idlMethod" id=
+"idl-def-exposedthing-emitevent-eventname-payload" data-idl=""
+data-title="emitEvent" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href=
+
+data-link-for="exposedthing" data-lt=
+"exposedthing.expose()|exposedthing.expose|expose()|expose" href=
+"#dom-exposedthing-expose" class="internalDFN" data-link-type=
+"dfn">expose();
+  Promise<void> data-link-for="exposedthing" data-lt="emitevent()|emitEvent" href=
+"#dom-exposedthing-emitevent" class="internalDFN" data-link-type=
+"dfn">emitEvent<span class=
+"idlParamType"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class=
+"idlSectionComment">    // define Thing Description modifiers
+<span class="idlMethod" id=
+"idl-def-exposedthing-addproperty-property" data-idl="" data-title=
+"addProperty" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href="#dom-exposedthing" class="internalDFN"
+data-link-type=
+"dfn">  <span class=
+
+data-link-for="exposedthing" data-lt=
+"exposedthing.destroy()|exposedthing.destroy|destroy()|destroy"
+href="#dom-exposedthing-destroy" class="internalDFN"
+data-link-type="dfn">destroy();
+  // define Properties
+  
+"internalDFN" data-link-type=
+"dfn">ExposedThing 
+"idlMethName">data-lt="addproperty()|addProperty" href=
+"#dom-exposedthing-addproperty" class="internalDFN" data-link-type=
+"dfn">addProperty<span class=
+"idlParamType"><a href="#dom-thingproperty" class="internalDFN"
+
+data-lt=
+"exposedthing.addproperty()|exposedthing.addproperty|addproperty()|addproperty"
+href="#dom-exposedthing-addproperty" class="internalDFN"
+
+data-link-type=
+"dfn"> <span class=
+"idlParamName">property
+<span class="idlMethod" id=
+"idl-def-exposedthing-removeproperty-name" data-idl="" data-title=
+"removeProperty" data-dfn-for="exposedthing">    <span class=
+"idlMethType"><a href="#dom-exposedthing" class="internalDFN"
+
+"dfn">addProperty(DOMString name, PropertyFragment property, optional any initValue);
+  "dfn">  <span class=
+
+"dfn">ExposedThing 
+"idlMethName">data-lt="removeproperty()|removeProperty" href=
+"#dom-exposedthing-removeproperty" class="internalDFN"
+data-link-type="dfn">removeProperty(<span class=
+
+data-lt=
+"exposedthing.setpropertyreadhandler()|exposedthing.setpropertyreadhandler|setpropertyreadhandler()|setpropertyreadhandler"
+href="#dom-exposedthing-setpropertyreadhandler" class="internalDFN"
+data-link-type=
+"dfn">setPropertyReadHandler(
+"idlParam">"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class="idlMethod" id="idl-def-exposedthing-addaction-action"
+data-idl="" data-title="addAction" data-dfn-for=
+"exposedthing">    <a href=
+"#dom-exposedthing" class="internalDFN" data-link-type=
+"dfn">  <span class=
+"idlMethName"><a data-no-default="" data-link-for="exposedthing"
+data-lt="addaction()|addAction" href="#dom-exposedthing-addaction"
+class="internalDFN" data-link-type=
+"dfn">addAction<span class=
+"idlParamType"><a href="#dom-thingaction" class="internalDFN"
+
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name, PropertyReadHandler readHandler);
+  "dfn"> <span class=
+"idlParamName">action
+<span class="idlMethod" id="idl-def-exposedthing-removeaction-name"
+data-idl="" data-title="removeAction" data-dfn-for=
+"exposedthing">    <a href=
+"#dom-exposedthing" class="internalDFN" data-link-type=
+"dfn">  <span class=
+
+"dfn">ExposedThing 
+"idlMethName">data-lt="removeaction()|removeAction" href=
+"#dom-exposedthing-removeaction" class="internalDFN"
+data-link-type="dfn">removeAction(<span class=
+
+data-lt=
+"exposedthing.setpropertywritehandler()|exposedthing.setpropertywritehandler|setpropertywritehandler()|setpropertywritehandler"
+href="#dom-exposedthing-setpropertywritehandler" class=
+"internalDFN" data-link-type=
+"dfn">setPropertyWriteHandler(
+"idlParam">"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class="idlMethod" id="idl-def-exposedthing-addevent-event"
+data-idl="" data-title="addEvent" data-dfn-for=
+"exposedthing">    <a href=
+"#dom-exposedthing" class="internalDFN" data-link-type=
+"dfn">  <span class=
+"idlMethName"><a data-no-default="" data-link-for="exposedthing"
+data-lt="addevent()|addEvent" href="#dom-exposedthing-addevent"
+class="internalDFN" data-link-type=
+"dfn">addEvent<span class=
+"idlParamType"><a href="#dom-thingevent" class="internalDFN"
+
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name, PropertyWriteHandler writeHandler);
+  "dfn">
+<span class="idlMethod" id="idl-def-exposedthing-removeevent-name"
+data-idl="" data-title="removeEvent" data-dfn-for=
+"exposedthing">    <a href=
+"#dom-exposedthing" class="internalDFN" data-link-type=
+"dfn">  <span class=
+"idlMethName"><a data-no-default="" data-link-for="exposedthing"
+data-lt="removeevent()|removeEvent" href=
+"#dom-exposedthing-removeevent" class="internalDFN" data-link-type=
+"dfn">removeEvent<span class=
+"idlParamType"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString
+<span class=
+"idlSectionComment">    // define request handlers
+<span class="idlMethod" id=
+"idl-def-exposedthing-setpropertyreadhandler-name-readhandler"
+data-idl="" data-title="setPropertyReadHandler" data-dfn-for=
+"exposedthing">    <a href=
+"#dom-exposedthing" class="internalDFN" data-link-type=
+"dfn">  <span class=
+
+"dfn">ExposedThing 
+"idlMethName">data-lt="setpropertyreadhandler()|setPropertyReadHandler" href=
+"#dom-exposedthing-setpropertyreadhandler" class="internalDFN"
+data-link-type="dfn">setPropertyReadHandler(<span class=
+
+data-lt=
+"exposedthing.removeproperty()|exposedthing.removeproperty|removeproperty()|removeproperty"
+href="#dom-exposedthing-removeproperty" class="internalDFN"
+data-link-type=
+"dfn">removeProperty(
+"idlParam">"https://heycam.github.io/webidl/#idl-DOMString">DOMString,
+                                         <span class=
+
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name);
+  // define Actions
+  
+"internalDFN" data-link-type=
+"dfn">ExposedThing addAction(
+"idlParam">"#dom-propertyreadhandler" class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">readHandler
+<span class="idlMethod" id=
+"idl-def-exposedthing-setpropertywritehandler-name-writehandler"
+data-idl="" data-title="setPropertyWriteHandler" data-dfn-for=
+"exposedthing">    <a href=
+"#dom-exposedthing" class="internalDFN" data-link-type=
+"dfn">  <span class=
+
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name, ActionFragment init, ActionHandler action);
+  
+data-link-type=
+"dfn">ExposedThing 
+"idlMethName">data-lt="setpropertywritehandler()|setPropertyWriteHandler" href=
+"#dom-exposedthing-setpropertywritehandler" class="internalDFN"
+
+data-lt=
+"exposedthing.removeaction()|exposedthing.removeaction|removeaction()|removeaction"
+href="#dom-exposedthing-removeaction" class="internalDFN"
+
+data-link-type=
+"dfn">setPropertyWriteHandler,
+                                          <span class=
+
+"dfn">removeAction(
+"idlParam">"#dom-propertywritehandler" class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">writeHandler
+<span class="idlMethod" id=
+"idl-def-exposedthing-setactionhandler-name-action" data-idl=""
+
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name);
+data-title="setActionHandler" data-dfn-for=
+"exposedthing">    <a href=
+"#dom-exposedthing" class="internalDFN" data-link-type=
+"dfn">  <span class=
+
+"exposedthing">
+  
+data-link-type=
+"dfn">ExposedThing 
+"idlMethName">data-lt="setactionhandler()|setActionHandler" href=
+"#dom-exposedthing-setactionhandler" class="internalDFN"
+data-link-type="dfn">setActionHandler(<span class=
+
+data-lt=
+"exposedthing.setactionhandler()|exposedthing.setactionhandler|setactionhandler()|setactionhandler"
+href="#dom-exposedthing-setactionhandler" class="internalDFN"
+data-link-type=
+"dfn">setActionHandler(
+"idlParam">"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a href="#dom-actionhandler"
+class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">action
+};
+<span class="idlCallback" id="idl-def-propertyreadhandler"
+data-idl="" data-title="PropertyReadHandler">callback <span class=
+"idlCallbackID"><a data-no-default="" data-link-for="" data-lt=""
+href="#dom-propertyreadhandler" class="internalDFN" data-link-type=
+"dfn"> = <span class=
+"idlCallbackType"><a href=
+"https://heycam.github.io/webidl/#idl-promise">Promise
+<span class="idlCallback" id="idl-def-propertywritehandler"
+data-idl="" data-title="PropertyWriteHandler">callback <span class=
+"idlCallbackID"><a data-no-default="" data-link-for="" data-lt=""
+href="#dom-propertywritehandler" class="internalDFN"
+data-link-type="dfn">
+<span class="idlCallback" id="idl-def-actionhandler" data-idl=""
+data-title="ActionHandler">callback <span class=
+"idlCallbackID"><a data-no-default="" data-link-for="" data-lt=""
+
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString name, 
+href="#dom-actionhandler" class="internalDFN" data-link-type=
+"dfn"> = <span class=
+"idlCallbackType"><a href=
+
+"dfn">ActionHandler action);
+  // define Events
+  
+"internalDFN" data-link-type=
+"dfn">ExposedThing addEvent(DOMString name, EventFragment event);
+  
+data-link-type=
+"dfn">ExposedThing removeEvent(DOMString name);
+};
+[NoInterfaceObject]
+interface ExposedEvents {
+  maplike<DOMString, ExposedEvent>;
+};
+callback PropertyReadHandler = Promise<any> ();
+callback PropertyWriteHandler = Promise<void> (any value);
+callback ActionHandler = 
+"https://heycam.github.io/webidl/#idl-promise">
+Promise
+
+<
+
+any
+
+>
+
+(
+
+
+
+any
+
+
+
+parameters
+
+
+);
+
+
      +
      +5.1 +The +start() +method + +

      +Start +serving +external +requests +for +the +Thing +. +5.2 + +The + + +stop() + +properties + + + +method +Stop +serving +external +requests +for +the +Thing +. +5.3 +The + +attribute +represents +a +dictionary +of + + +register() + +ThingProperty + + +method +Generates +the +Thing +Description + + +given + +items +in +which + +the +properties, +Actions + + +read() + +and +Event +defined +for +this +object. +If +a + + +directory + +write() + + +argument +is +given, +make +a +request +to +register + +methods +define +local +methods +that +access + +the +Thing +Description +with + +physical +representations +of + +the +given +WoT +repository +by +invoking +its +register +Action + + +Properties + +. +

      +5.4 + +

      +The + + +unregister() + +actions + + + +method +If + +attribute +represents + +a +dictionary +of + + +directory + +ThingAction + + +argument +is +given, +make +a +request +to +unregister +the +Thing +Description + + +with + +items +in +which + +the +given +WoT +repository +by +invoking +its + + +unregister + +invoke() + + +Action +. +Then, +and +in +the +case +no +arguments +were +provided + +method +represents +a +local +method + +to +this +function, +stop +the +Thing +and +remove + +invoke + +the +Thing +Description + + +Action + +. +

      +5.5 + +

      +The + + +emitEvent() + +events + + + +method +Emits +an +the +event +initialized +with +the +event +name +specified +by + +attribute +represents +a +dictionary +of + +ExposedEvent + +items +that +add + +the + +eventName + +emit() + + +argument +and +data +specified +by + +method +to + +the + + +payload + +ThingEvent + + +argument. + +5.6 + + +definition. + +The + + +DataSchema + +ExposedEvents + + + +type +<span class="idlTypedef" id= +"idl-def-dataschema" data-idl="" data-title= +"DataSchema">typedef <a href= +"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default="" +data-link-for="" data-lt="" href="#dom-dataschema" class= +"internalDFN" data-link-type= +"dfn"> + +interface +represents +a +maplike +dictionary +where +all +values +are + + +DataSchema + +ExposedEvent + + + +objects. +

      + +5.1 + + +; + +The + + +DataSchema + +expose() + + + +method + + +type +represents +a +data +type +specified +in + +

      +

      +Start +serving +external +requests +for + +the + +Thing +Description + +, +so +that + +WoT +Interactions + + +in +a +serialized +form. + +using + +Properties +, +Action + +s +and + +Event + +s +will +be +possible. + +

      +Editor's +note + +

      +The + + +DataSchema + +expose() + + +is +under +development, +currently +it +can +denote +any +type +supported +by + +method + +MUST + +run + +the +Thing +Description + +following +steps: +

      1. +Return +a + +Promise + +promise + +and +execute + +the +WoT +Runtime + +next +steps + +in +parallel + +. +5.7 +The + +
        2. +
      2. +If +invoking + + +addProperty() + +expose() + + +method +Adds + +is +not +allowed +for +the +current +scripting +context +for +security +reasons, +reject + +promise + +with + +SecurityError + +and +terminate +these +steps. +
      3. +Make + +a +Property +defined +by + +request +to + +the +argument + +underlying +platform +to +attach +protocol +handlers + +and +updates + +start +serving +external +requests +for + +WoT +Interactions + +(read, +write +and +observe + +Properties +, +invoke + +Action + +s +and +manage + +Event + +subscriptions), +based +on + +the +Thing +Description + + +Protocol +Bindings + +. +Throws +on +error. +Returns +a +reference +to + +
        4. +
      4. +If +there +was +an +error +during + +the +same + +request, +reject + +promise + +with +an + +Error + +object +for +supporting +chaining. + + +error + +with + +error.message + +set +to +the +error +code +seen +by +the + +Protocol +Bindings + +and +terminate +these +steps. +
      5. +Otherwise +resolve + +promise + +with + +td + +and +terminate +these +steps. +

      +5.7.1 + + +5.2 + + +The + + +ThingProperty + +destroy() + + + +dictionary +<span class="idlDictionary" id= +"idl-def-thingproperty" data-idl="" data-title= +"ThingProperty">dictionary <span class= +"idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-thingproperty" class="internalDFN" data-link-type= +"dfn"> : <span class= +"idlSuperclass"><a href="#dom-semanticannotations" class= +"internalDFN" data-link-type= +"dfn"> { +<span class="idlMember" id="idl-def-thingproperty-name" data-idl="" +data-title="name" data-dfn-for= +"thingproperty"> required <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" +data-link-for="thingproperty" data-lt="" href= +"#dom-thingproperty-name" class="internalDFN" data-link-type= +"dfn"> +<span class="idlMember" id="idl-def-thingproperty-schema" data-idl= +"" data-title="schema" data-dfn-for= +"thingproperty"> required <a href= +"#dom-dataschema" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-no-default="" data-link-for="thingproperty" +data-lt="" href="#dom-thingproperty-schema" class="internalDFN" +data-link-type="dfn"> +<span class="idlMember" id="idl-def-thingproperty-value" data-idl= +"" data-title="value" data-dfn-for= +"thingproperty"> <a href= +"https://heycam.github.io/webidl/#idl-any">any<a data-no-default="" +data-link-for="thingproperty" data-lt="" href= +"#dom-thingproperty-value" class="internalDFN" data-link-type= +"dfn"> +<span class="idlMember" id="idl-def-thingproperty-writable" +data-idl="" data-title="writable" data-dfn-for= +"thingproperty"> <a href= +"https://heycam.github.io/webidl/#idl-boolean">boolean<a data-no-default="" +data-link-for="thingproperty" data-lt="" href= +"#dom-thingproperty-writable" class="internalDFN" data-link-type= +"dfn"> = <span class= +"idlMemberValue">false +<span class="idlMember" id="idl-def-thingproperty-observable" +data-idl="" data-title="observable" data-dfn-for= +"thingproperty"> <a href= +"https://heycam.github.io/webidl/#idl-boolean">boolean<a data-no-default="" +data-link-for="thingproperty" data-lt="" href= +"#dom-thingproperty-observable" class="internalDFN" data-link-type= +"dfn"> = <span class= +"idlMemberValue">false +}; + +method + + +

      +

      +Represents + +Stop +serving +external +requests +for + +the + +Thing + +Property +description. + +and +destroy +the +object. +Note +that +eventual +unregistering +should +be +done +before +invoking +this +method. + +

      +

      +The + +name + +destroy() + + +attribute +represents + +method + +MUST + +run + +the +name +of + +following +steps: +

      1. +Return +a + +Promise + +promise + +and +execute + +the +Property + +next +steps + +in +parallel + +. +
        2. +
      2. +The + +If +invoking + + +schema + +destroy() + + +attribute +represents +the +data +type + +is +not +allowed + +for +the +Property +described +by + +current +scripting +context +for +security +reasons, +reject + +promise + +with + + +DataSchema + +SecurityError + + +. + +and +terminate +these +steps. + +
        3. +
      3. +The +value +attribute +represents + +Make +a +request +to + +the +value +of + +underlying +platform +to +stop +serving +external +requests +for + +WoT +Interactions +, +based +on + +the +Property + + +Protocol +Bindings + +. +
        4. +
      4. +The + +If +there +was +an +error +during +the +request, +reject + +promise + +with +an + + +writable + +Error + + +attribute +defines +whether + +object + +error + +with + +error.message + +set +to + +the +Property + +error +code +seen +by +the + +Protocol +Bindings + + +can +be +updated. +The +default +value +is +false +. + +and +terminate +these +steps. + +
        5. +
      5. +The + +Otherwise +resolve + +promise + +with + +td + +and +terminate +these +steps. +

      + +5.3 + +The + + +observable + +addProperty() + + + +attribute +defines +whether +the + +method +

      +Adds +a + + +Property + +changes +can +be +observed + +with +name +defined +by +the + +name + +argument, +the +data +schema +provided + +by +the + +property + +argument +of +type + +PropertyFragment +, +and +optionally + +an +external +client. +The +default + +initial + +value +provided +in +the +argument + +initValue + +whose +type +should +match +the +one +defined +in +the + +type + +property +according +to +the + +value-matching +algorithm +. +If + +initValue + +is +not +provided, +it + +SHOULD + +be +initialized +as + + +false + +undefined + +. +Implementations + +SHOULD + +update +the + +Thing +Description +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +

      +
      +
      +

      + +5.8 + +5.4 + + +The + + +removeProperty() + + +method + + +

      +

      +Removes +the + +Property + +specified +by +the + +name + +argument +and +updates +the + +Thing +Description +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +

      +
      +
      +

      + +5.9 + +5.5 + + +The + + +addAction() + + +method + + +

      +

      +Adds +an +Action + +to +the + +actions + +property +of +a + +Thing + +object +as + +an + +Action + +with +name + +defined +by +the +action + + +name + +argument, +defines +input +and +output +data +format +by +the + +init + +argument +of +type + + +ThingAction + +ActionFragment + + +, +and +adds +the +function +provided +in +the + +action + +argument +as +a +handler, +then + +updates +the + +Thing +Description +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +

      +5.9.1 +The +ThingAction +dictionary +<span class="idlDictionary" id= +"idl-def-thingaction" data-idl="" data-title= +"ThingAction">dictionary <span class= +"idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-thingaction" class="internalDFN" data-link-type= +"dfn"> : <span class= +"idlSuperclass"><a href="#dom-semanticannotations" class= +"internalDFN" data-link-type= +"dfn"> { +<span class="idlMember" id="idl-def-thingaction-name" data-idl="" +data-title="name" data-dfn-for= +"thingaction"> required <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" +data-link-for="thingaction" data-lt="" href="#dom-thingaction-name" +class="internalDFN" data-link-type= +"dfn"> +<span class="idlMember" id="idl-def-thingaction-inputschema" +data-idl="" data-title="inputSchema" data-dfn-for= +"thingaction"> <a href= +"#dom-dataschema" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-no-default="" data-link-for="thingaction" +data-lt="" href="#dom-thingaction-inputschema" class="internalDFN" +data-link-type="dfn"> +<span class="idlMember" id="idl-def-thingaction-outputschema" +data-idl="" data-title="outputSchema" data-dfn-for= +"thingaction"> <a href= +"#dom-dataschema" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-no-default="" data-link-for="thingaction" +data-lt="" href="#dom-thingaction-outputschema" class="internalDFN" +data-link-type="dfn"> +}; + +

      +The +ThingAction + +provided + +action + +callback +function +will +implement +invoking +an + +Action + + +dictionary +describes +the +arguments + +and + +SHOULD + +be +called +by +implementations +when +a +request +for +invoking + +the +return +value. +The +name +attribute +provides +the + + +Action + +name. +The +inputSchema +attribute +provides +the +description +of +the +input +arguments +(argument +list + +is +represented +by +an +object). +If +missing, +it +means + +received +from + +the +action +does +not +accept +arguments. + +underlying +platform. + +The +callback +will +receive +a + + +outputSchema + +parameters + + +attribute +provides + +dictionary +argument +according +to + +the +description + +definition +in +the + +init.input + +argument +and +will +return +a +value + +of +type +defined +by + +the +returned +data. +If +missing, +it +means + + +init.output + +argument +according +to + +the +action +does +not +return +data. + + +value-matching +algorithm +.

      +There + +SHOULD + +be +exactly +one +handler +for +any +given + +Action +. +If +no +handler +is +initialized +for +any +given + +Action +, +implementations + +SHOULD + +throw +a + +TypeError +.

      +
      +
      +

      + +5.10 + +5.6 + + +The + + +removeAction() + + +method + + +

      +

      +Removes +the + +Action + +specified +by +the + +name + +argument +and +updates +the + +Thing +Description +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +

      +
      +
      +

      + +5.11 + +5.7 + + +The + + +addEvent() + + +method + + +

      +

      +Adds +an +event +to +the +Thing +object +as + +with +name + +defined +by +the + +name + +argument +and +qualifiers +and +initialization +value +provided +by +the + +event + +argument +of +type + + +ThingEvent + +EventFragment + + + +to +the + +Thing + +object + +and +updates +the + +Thing +Description +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +

      +5.11.1 +The +ThingEvent +dictionary +<span class="idlDictionary" id= +"idl-def-thingevent" data-idl="" data-title= +"ThingEvent">dictionary <span class= +"idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-thingevent" class="internalDFN" data-link-type= +"dfn"> : <span class= +"idlSuperclass"><a href="#dom-semanticannotations" class= +"internalDFN" data-link-type= +"dfn"> { +<span class="idlMember" id="idl-def-thingevent-name" data-idl="" +data-title="name" data-dfn-for= +"thingevent"> required <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" +data-link-for="thingevent" data-lt="" href="#dom-thingevent-name" +class="internalDFN" data-link-type= +"dfn"> +<span class="idlMember" id="idl-def-thingevent-schema" data-idl="" +data-title="schema" data-dfn-for= +"thingevent"> <a href= +"#dom-dataschema" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMemberName"><a data-no-default="" data-link-for="thingevent" +data-lt="" href="#dom-thingevent-schema" class="internalDFN" +data-link-type="dfn"> +}; +The +name +attribute +represents +the +event +name. +The +schema +attribute +represents +the +type +of +the +data +that +is +attached +to +the +event. +If +missing, +it +means +the +event +does +not +carry +data. + +
      +
      +

      +5.12 + + +5.8 + + +The + + +removeEvent() + + +method + + +

      +

      +Removes +the +event +specified +by +the + +name + +argument +and +updates +the + +Thing +Description +. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +

      +
      +
      +

      + +5.13 + +5.9 + + +The + + +PropertyReadHandler + + +callback + + +

      +

      +A +function +that +returns + +is +called +when +an +external +request +for +reading +a + +Property + +is +received. +It +should +return + +a +Promise +and +resolves +it +with +the +value +of +the + +Property + +matching +the + +name + +argument +to +the + +setPropertyReadHandler + +function, +or +rejects +with +an +error +if +the +property +is +not +found +or +the +value +cannot +be +retrieved. +

      +
      +
      +

      + +5.14 + +5.10 + + +The + + +PropertyWriteHandler + + +callback + + +

      +

      +A +function +that +is + +called +with + +when +an +external +request +for +writing +a + +Property + +is +received. +It +is +given +the +requested +new + + +value + +as +argument +that +returns + +and +should +return + +a +Promise +which +is +resolved +when +the +value +of +the + +Property + +matching + +that +matches + +the + +name + +argument +to +the +setPropertyReadHandler +function +is + +has +been + +updated +with + +value +, +or +rejects +with +an +error +if +the +property +is +not +found +or +the +value +cannot +be +updated. +

      +
      +
      + +Editor's +note + +
      +

      +Note +that +this +function +is +invoked +by +implementations +before +the +property +is +updated, +so +the + +updated +and +it +actually +defines +what +to +do +when +a +write +request +is +received. +The + +code +in +this +callback +function +can +invoke +the + +readProperty() + +read() + + +method +to +find +out +the +old +value +of +the +property, +if +needed. +Therefore +the +old +value +is +not +provided +to +this +method. + +function. + +

      +
      +
      +
      +

      + +5.15 + +5.11 + + +The + + +ActionHandler + + +callback + + +

      +

      +A +function +called +with +a + +parameters + +dictionary +argument +assembled +by +the + +WoT +runtime + +based +on +the + +Thing +Description + +and +the +external +client +request. +It +returns +a +Promise +that +rejects +with +an +error +or +resolves +if +the +action +is +successful +or +ongoing +(may +also +resolve +with +a +control +object +such +as +an + + +Observable + + +for +actions +that +need +progress +notifications +or +that +can +be +canceled). +

      +
      +
      +

      + +5.16 + +5.12 + + +The + + +setPropertyReadHandler() + + +method + + +

      +

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

      +

      +The + +readHandler + +callback +function +will +implement +reading +a + +Property + +and + +SHOULD + +be +called +by +implementations +when +a +request +for +reading +a + +Property + +is +received +from +the +underlying +platform. +

      +

      +There + +SHOULD + +be +at +most +one +handler +for +any +given + +Property + +and +newly +added +handlers +replace +the +old +handlers. +If +no +handler +is +initialized +for +any +given + +Property +, +implementations + +SHOULD + +implement +a +default +property +read +handler. +

      +

      +When +an +external +request +for +reading + +Property + +propertyName + +is +received, +the +runtime + +SHOULD + +execute +the +following +steps: +

      1. +Return +a + +Promise + +promise + +and +execute +the +next +steps + +in +parallel +.
      2. +If +a + +Property + +with + +propertyName + +does +not +exist, +reject + +promise + +with +a + +ReferenceError + +and +terminate +these +steps. +
      3. +Otherwise, +if +no +read +handler +has +been +defined +for + +propertyName +, +resolve + +promise + +with +the +value +of +the + +Property + +named + +propertyName + +provided +by +the +runtime +implementation +and +terminate +these +steps. +
      4. +Otherwise, +invoke +the +read +handler +associated +with + +propertyName +. +If +it +rejects, +then +reject + +promise + +with +the +same +error, +and +resolve + +promise + +with +the +same +value. +
      +
      +
      +

      + +5.17 + +5.13 + + +The + + +setPropertyWriteHandler() + + +method + + +

      +

      +Takes + +name + +as +string +argument +and + +writeHandler + +as +argument +of +type + + +PropertyWriteHandler + +. +Sets +the +handler +function +for +writing +the +specified + +Property + +matched +by + +name +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +

      +

      +There + +SHOULD + +be +at +most +one +write +handler +for +any +given + +Property + +and +newly +added +handlers +replace +the +old +handlers. +If +no +write +handler +is +initialized +for +any +given + +Property +, +implementations + +SHOULD + +implement +default +property +update +and +notifying +observers +on +change. +

      +

      +When +an +external +request +for +writing +a + +Property + +propertyName + +with +a +new +value + +value + +is +received, +the +runtime + +SHOULD + +execute +the +following +steps: +

      1. +Return +a + +Promise + +promise + +and +execute +the +next +steps + +in +parallel +.
      2. +If +a + +Property + +with + +propertyName + +does +not +exist, +reject + +promise + +with +a + +ReferenceError + +and +terminate +these +steps. +
      3. +Otherwise, +if +no +write +handler +has +been +defined +for + +propertyName +, +the +runtime +implementation + +SHOULD + +update +the + +Property + +value +with + +value +, +resolve + +promise + +and +terminate +these +steps. +
      4. +Otherwise, +invoke +the +write +handler +associated +with + +propertyName + +providing + +value + +as +argument. +If +it +rejects, +then +reject + +promise + +with +the +same +error, +and +resolve + +promise + +with +the +same +value. +
      +
      +
      +

      + +5.18 + +5.14 + + +The + + +setActionHandler() + + +method + + +

      +

      +Takes + +name + +as +string +argument +and + +action + +as +argument +of +type + + +ActionHandler + +. +Sets +the +handler +function +for +the +specified + +Action + +matched +by + +name +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +

      +

      +If +provided, +this + +The + +action + +callback +function +will +implement +invoking + +an + +Action + +and + +SHOULD + +be +called +by +implementations +when +a +request +for +invoking +a + +the + +Action + +is +received +from +the +underlying +platform. +The +callback +will +receive +a +parameters +dictionary +argument. + +

      +

      +There + +SHOULD + +be +exactly + +at +most + +one +handler +for +any +given + +Action + +and +newly +added +handlers +replace +the +old +handlers. +

      +When +an +external +request +for +invoking +the + +Action + +identified +by + +name + +is +received, +the +runtime + +SHOULD + +execute +the +following +steps: +

      1. +Return +a + +Promise + +promise + +and +execute +the +next +steps + +in +parallel + +. +
        2. +
      2. +If +an + +Action + +identified +by + +name + +does +not +exist, +reject + +promise + +with +a + +ReferenceError + +and +terminate +these +steps. +
      3. +Otherwise, +if + +no +action + +handler +is +initialized + +has +been +defined + +for +any +given + + +name +, +reject + +promise + +with +a + +ReferenceError + +and +terminate +these +steps. +
      4. +Otherwise, +invoke +the + + +Action +, +implementations +SHOULD +return + + +handler +associated +with + +name +. +If +it +rejects +with + +error +, +then +reject + +promise + +with +the +same + +error +, +otherwise + +if +it +resolves +with + +value +, +then +resolve + +promise + +with + +the +action +is +invoked +by +any +client. + +same + +value +.
      +
      +
      +

      + +5.19 + +5.15 + + +Examples + + +

      +

      +Below +some + + + +ExposedThing + + + +interface +examples +are +given. +

      +
      +
      + +Example +7 + +5 + +: + +: +Create +a +new +blank + +exposed +Thing +with +a +simple +property + + +
      +
      +        try {
+  "hljs-keyword">var thing = WoT.produce({ <span class=
+"hljs-attr">name: <span class=
+"hljs-string">"tempSensor" });
+  
+  thing.addProperty({
+    : <span class=
+"hljs-string">"temperature",
+    : <span class=
+"hljs-number">0.0,
+    : <span class=
+"hljs-string">'{ "type": "number" }'
+    <span class=
+"hljs-comment">// use default values for the rest
+  }).addProperty({
+    : <span class=
+"hljs-string">"max",
+    : <span class=
+"hljs-number">0.0,
+    : <span class=
+"hljs-string">'{ "type": "number" }'
+    <span class=
+"hljs-comment">// use default values for the rest
+  }).addAction({
+    : <span class=
+"hljs-string">"reset",
+    
+  }).addEvent({
+
+"hljs-keyword">var temperatureValueDefinition = {
+    type: 
+"hljs-string">"number",
+    minimum: 
+"hljs-number">-50,
+    maximum: 
+"hljs-number">10000
+  };
+  
+"hljs-keyword">var temperaturePropertyDefinition = temperatureValueDefinition;
+  // add the 'forms' property
+  temperaturePropertyDefinition.forms = [ ... ];
+  var thing = WoT.produce({
+    name: "hljs-string">"onchange",
+    : <span class=
+"hljs-string">'{ "type": "number" }'
+  });
+  
+  thing.setActionHandler(<span class=
+"hljs-string">"reset", () => {
+    .log(<span class=
+"hljs-string">"Resetting maximum");
+    thing.writeProperty(<span class=
+"hljs-string">"max");
+  });
+  thing.start().then(<span class=
+"hljs-params">() {
+      thing.register();
+
+"hljs-string">"tempSensor",
+    properties: {      
+"hljs-attr">temperature: temperaturePropertyDefinition
+    },
+    actions: {      reset: {        description: 
+"hljs-string">"Reset the temperature sensor",
+        input: {          
+"hljs-attr">temperature: temperatureValueDefinition
+        },
+        output: 
+"hljs-literal">null,
+        forms: []
+      },
+    },
+    events: {      
+"hljs-attr">onchange: temperatureValueDefinition
+    },
+    links: []
+  });
+  await thing.expose();
+  await wot.register("hljs-string">"https://mydirectory.org", thing);
+
+  // define Thing business logic
+  setInterval( async () => {
+    let mock = Math.random()*100;
+    thing.writeProperty(<span class=
+"hljs-string">"temperature", mock);
+
+    let old = "hljs-keyword">await thing.readProperty(<span class=
+"hljs-string">"max");
+
+"hljs-keyword">await thing["temperature"].read();
+
+    if (old < mock) {
+      thing.writeProperty(<span class=
+"hljs-string">"max", mock);
+      thing.emitEvent();
+
+      await thing["hljs-string">"temperature"].write(mock);
+      thing.emitEvent("onchange", mock);
+
+    }
+  }, 1000);
+} catch (err) {
+   console.log("Error creating ExposedThing: " + err);
+}
+
      +
      +
      +
      + +Example +8 + +6 +: +Create +a +new +exposed +Thing +with +object +property + + +: + +
      +
      +        try {
+  var statusValueDefinition = {
+    type: "hljs-string">"object",
+    properties: {      brightness: {        type: 
+"hljs-string">"number",
+        minimum: 
+"hljs-number">0.0,
+        maximum: 
+"hljs-number">100.0,
+        required: 
+"hljs-literal">true
+      },
+      rgb: {        type: 
+"hljs-string">"array",
+        "minItems": 
+"hljs-number">3,
+        "maxItems": 
+"hljs-number">3,
+        items : {            "type" : 
+"hljs-string">"number",
+            
+"hljs-string">"minimum": 0,
+            
+"hljs-string">"maximum": 255
+        }
+      }
+  };
+  
+"hljs-keyword">var statusPropertyDefinition = statusValueDefinition;
+  // add the 'forms' property
+  statusPropertyDefinition["forms"] = [];
+  var thing = WoT.produce({    name: 
+"hljs-string">"mySensor",
+    properties: {      brightness: {        type: 
+"hljs-string">"number",
+        minimum: 
+"hljs-number">0.0,
+        maximum: 
+"hljs-number">100.0,
+        required: 
+"hljs-literal">true,
+      },
+      
+"hljs-attr">status: statusPropertyDefinition
+    },
+    actions: {      status: {        description: 
+"hljs-string">"Get status object",
+        input: 
+"hljs-literal">null,
+        output: {          
+"hljs-attr">status : statusValueDefinition;
+        },
+        forms: []
+      },
+    },
+    events: {      
+"hljs-attr">onstatuschange: statusValueDefinition;
+    },
+    links: []
+  });
+  thing.expose().then(() => {
+      thing.register();
+  });
+} catch (err) {
+   console.log(
+"hljs-string">"Error creating ExposedThing: " + err);
+}
+
      +Example +7 +: +Create +a +new +exposed +Thing +from +a +Thing +Description + +
      +
      +        let thingDescription = "hljs-string">'{ "@context": [ "https://w3c.github.io/wot/w3c-wot-td-context.jsonld", "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ], "@type": [ "Thing", "Sensor" ], "name": "mySensor", "geo:location": "testspace", "interaction": [ { "@type": [ "Property", "Temperature" ], "name": "prop1", "schema": { "type": "number" }, "saref:TemperatureUnit": "degree_Celsius" } ] }';
+
+"hljs-string">'{ \
+  "name": "mySensor", \
+  "@context": [ "http://www.w3.org/ns/td",\
+     "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ],\
+  "@type": [ "Thing", "Sensor" ], \
+  "geo:location": "testspace", \
+  "properties": { \
+    "prop1": { \
+      "type": "number",\
+      "@type": [ "Property", "Temperature" ], \
+      "saref:TemperatureUnit": "degree_Celsius" \
+  } } }';
+
+try {
+  // note that produce() fails if thingDescription contains error
+  let thing = WoT.produce(thingDescription);
+  // Interactions were added from TD
+  // WoT adds generic handler for reading any property
+  // define a specific handler for one property
+  let name = "examplePropertyName";
+  thing.setPropertyReadHandler(name, () => {
+    console.log("Handling read request for " + name);
+    return new Promise((resolve, reject) => {
+        let examplePropertyValue = 5;
+        resolve(examplePropertyValue);
+      },
+      e => {
+        console.log("Error");
+      });
+  });
+  thing.start();
+
+  thing.expose();
+
+} catch(err) {
+   console.log("Error creating ExposedThing: " + err);
+}
+
      +
      +
      +
      + +Example +9 + +8 + +: + +: +Create +a +new +exposed +Thing +from +a +TD +URI + +
      +
      +        // fetch an external TD, e.g., to set up a proxy for that Thing
+WoT.fetch("http://myservice.org/mySensor/description").then(td => {
+  // WoT.produce() ignores instance-specific metadata (security, form)
+  let thing = WoT.produce(td);
+  // Interactions were added from TD
+  // add server functionality
+  // ...
+});
+
      +
      +
      +
      +
      +

      + +6. + +Experimental +extensions +to +the +ConsumedThing +interface + +Data +types +and +structures + +

      +

      +The +[ + +This +section +is +non-normative. + + +WOT-TD + + +] +specification +defines +the + +WoT +information +model +, +i.e. +the +data +types +and +data +structures +used +in + +WoT +Interactions +. +In +this +API +these +definitions +translate +to +dictionary +objects +that +are +extended +with +methods +by +the +interfaces +defined +in +this +specification. + +

      +

      +In +order +to +avoid +duplication +of +definitions, +references +to +these +data +types +and +structures +is +defined +in +this +section, +but +for +their +full +description +please +refer +to +the + +Thing +Description +specification +.

      +6.1 + +The + + +ThingDescription + +DataSchema + + + +dictionary +and +its +subclasses + + +related +functionality, +such +as +enumerating + +

      +

      +Value +types +basically +represent +types +that +may +be +used +in + +JSON + +object +definitions +and +are +used +in + +ThingFragment + +to +define + +Properties +, +Action +s, + + +Event + +s +and +links +(introspection) + + +Action + +parameters. +Value +types +are +represented +as +dictionary +objects +whose +properties +and +possible +sub-classes +are +defined +in +the + +DataSchema + +section +of +[ + +WOT-TD + +]. +

      +One +property +of +all + +DataSchema + +dictionary + +is +an +API +extension +that + +the + +type + +property +whose +value + +is +out + +from +a +set + +of +scope +for + +enumerated +strings +defined +in +the + +DataSchema + +section +of +[ + +WOT-TD + +] +and +is +referred +as + +DataType + +in + +this +specification. +However, + +

      +

      +Based +on + +type +, +the +draft +interfaces + +following +sub-classes +of + +DataSchema + +are +defined +here +for +informative +purposes. +<span class="idlInterface" id= +"idl-def-consumedthing-partial-1" data-idl="" data-title= +"ConsumedThing">partial interface <span class= +"idlInterfaceID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-consumedthing" class="internalDFN" data-link-type= +"dfn"> { +<span class="idlMethod" id="idl-def-consumedthing-getproperties" +data-idl="" data-title="getProperties" data-dfn-for= +"consumedthing"> <a href= +"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-thingproperty" +class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="consumedthing" +data-lt="getproperties()|getProperties" href= +"#dom-consumedthing-getproperties" class="internalDFN" +data-link-type="dfn">getProperties +<span class="idlMethod" id="idl-def-consumedthing-getactions" +data-idl="" data-title="getActions" data-dfn-for= +"consumedthing"> <a href= +"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-thingaction" +class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="consumedthing" +data-lt="getactions()|getActions" href= +"#dom-consumedthing-getactions" class="internalDFN" data-link-type= +"dfn">getActions +<span class="idlMethod" id="idl-def-consumedthing-getevents" +data-idl="" data-title="getEvents" data-dfn-for= +"consumedthing"> <a href= +"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-thingevent" +class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="consumedthing" +data-lt="getevents()|getEvents" href="#dom-consumedthing-getevents" +class="internalDFN" data-link-type= +"dfn">getEvents +<span class="idlMethod" id="idl-def-consumedthing-getlinks" +data-idl="" data-title="getLinks" data-dfn-for= +"consumedthing"> <a href= +"https://heycam.github.io/webidl/#idl-sequence">sequence<<a href="#dom-tdlink" +class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="consumedthing" +data-lt="getlinks()|getLinks" href="#dom-consumedthing-getlinks" +class="internalDFN" data-link-type= +"dfn">getLinks +}; + +in +[ + + +WOT-TD + + +]: + +6.1 + + +BooleanSchema +, +NumberSchema +, +IntegerSchema +, +StringSchema +, +ObjectSchema +, +ArraySchema +.

      +6.2 + + +The + + +getProperties() + +SecurityScheme + + + +method + +dictionary +and +its +subclasses + +

      +

      +Returns +the +list +of +Properties + +Security +metadata +is +represented +as +dictionary +objects +whose +properties +and +sub-classes +are + +defined +in +the +Thing +Description + + +SecurityScheme + + +section +of +[ + +WOT-TD + +]. +

      +One +property + +of +the +Thing + + + +SecurityScheme + + +dictionary +is +the + +scheme + +property +whose +value +is +from +a +set +of +enumerated +strings +defined + +in +the +form + + +SecurityScheme + +section + +of +a +list + +[ + +WOT-TD + +]. +Based +on + +type +, +multiple +subclasses + +of + + +ThingProperty + +SecurityScheme + + + +objects. + +are +defined. + +

      +
      +

      +6.4 + +The + +Form + +dictionary +

      +Represents +metadata +describing +service +details, +with +properties + +defined +in +the +Thing +Description + + +Form + + +section + +of +[ + +WOT-TD + +]. +

      +6.5 + +The + +InteractionFragment + +dictionary +

      +Represents + +the +Thing + +common +properties +of + +WoT +Interactions +, +one +of + +Property +, +Action + + +or + +Event +, +as +defined + +in +the +form + + +InteractionPattern + +section + +of +[ + +WOT-TD + +]. +Its +subclasses +are +referred +as + +PropertyFragment +, +ActionFragment + +and + +EventFragment +.

      +6.6 + +The + +PropertyFragment + +dictionary +

      +Represents +the + +Property + +interaction +data +that +initializes + +a +list + + + +ThingProperty + +object. +Its +properties +are +defined +in +the + +Property + +and + +InteractionPattern + +sections + +of +[ + +WOT-TD + +]. +

      +6.7 + +The + +ActionFragment + +dictionary +

      +Represents +the + +Action + +interaction +data +that +initializes +a + + + +ThingAction + + +objects. + +object. +Its +properties +are +defined +in +the + +Action + +and + +InteractionPattern + +sections +of +[ + +WOT-TD + +]. + +

      +
      +
      +

      +6.3 + + +6.8 + + +The + + +getEvents() + +EventFragment + + + +method + +dictionary + +

      +

      +Returns + +Represents + +the +list +of + + +Event + +s + +interaction +data +that +initializes +a + +ThingEvent + +object. +Its +properties +are + +defined +in +the +Thing +Description + + +Event + + +section + +of +the + +[ + +WOT-TD + +]. +

      +6.9 + +The + +ThingFragment + +dictionary +

      +The + +ThingFragment + +dictionary +is +defined +as + +Thing + + +in +the +form +of + +[ + +WOT-TD + +]. +It +is + +a +list + +dictionary +that +contains +properties +representing +semantic +metadata +and +interactions +( + +Properties +, +Action + +s +and + +Event + +s). +It +is +used +for +initializing +an +internal +representation + +of +a + +Thing +Description + +and +its +properties +may +be +used +in + + +ThingEvent + +ThingFilter + + +objects. + +. +

      +
      +
      +

      +6.4 + + +6.10 + + +The + + +getLinks() + +ThingDescription + + + +method + +type + +

      +

      +Returns +the +list + +Serialized +representation + +of +linked +resources +in + +the + + +Thing +Description + +(a + +JSON-LD + +document). +

      +Note +

      +In +this +version + +of +the +API, + +Thing +Description + +s +are +represented +as +an +opaque + +USVString + +that +can +be +transmitted +between +devices. +

      +7. + +Interfaces +for + +WoT +Interactions +

      +The +data +types +and +structures +imported +from +[ + +WOT-TD + + + +] +are +extended +by +this +specification + +in +order +to +provide + +the +form +of +a +list +of + +interfaces +for + +WoT +Interactions +.

      +Every + +Thing + +describes +its +metadata +as +defined +in + + +TDLink + +ThingFragment + + +, +and +basic +interactions +defined +as + +Properties +, +Action + + +objects. + +s +and + +Event + +s. +The +following +interfaces +are +used +for +representing +these +interactions. + +

      +
      +

      + +6.4.1 + +7.1 + + +The + + +TDLink + +Interaction + + + +dictionary + +interface +

      +

      +Contains +a +hyperlink +reference, +a +relation +type + +The + +Interaction + +interface +is +an +abstract +class +to +represent + +Thing + +interactions: + +Properties +, +Actions + +and + +Events +.

      +The + +InteractionFragment + +dictionary +holds +the +common +properties +of + +PropertyFragment +, +ActionFragment + +and + + +EventFragment + +dictionaries +used +for +initializing + +ThingProperty +, +ThingAction + +and + +ThingEvent + +objects +in + +a +media +type. + + + +ThingFragment + +dictionary +used +for +creating +an + +ExposedThing + +object. + +

      +
      +<span class="idlDictionary" id= +"idl-def-tdlink" data-idl="" data-title= +"TDLink">dictionary <span class= +"idlDictionaryID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-tdlink" class="internalDFN" data-link-type= +"dfn"> { +<span class="idlMember" id="idl-def-tdlink-href" data-idl="" +data-title="href" data-dfn-for="tdlink"> required <span class= +"idlMemberType"><a href= +"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default="" +data-link-for="tdlink" data-lt="" href="#dom-tdlink-href" class= +"internalDFN" data-link-type= +"dfn"> +<span class="idlMember" id="idl-def-tdlink-mediatype" data-idl="" +data-title="mediaType" data-dfn-for= +"tdlink"> <a href= +"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default="" +data-link-for="tdlink" data-lt="" href="#dom-tdlink-mediatype" + +
      "idl-def-interaction" data-idl="" data-title=
+"Interaction">interface Interaction {
+  readonly attribute (Form or FrozenArray<Form>) 
+class="internalDFN" data-link-type=
+"dfn">
+<span class="idlMember" id="idl-def-tdlink-rel" data-idl=""
+data-title="rel" data-dfn-for="tdlink">             <span class=
+"idlMemberType"><a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default=""
+data-link-for="tdlink" data-lt="" href="#dom-tdlink-rel" class=
+"internalDFN" data-link-type=
+"dfn">
+};
+
+"dfn">forms;
+};
+
+"dfn">Interaction includes 
+
+InteractionFragment
+
+;
+
+
+
      +
      +

      +The + + +TDLink + +forms + +read-only +property +represents +the +protocol +bindings +initialization +data +and +is +initialized +by +the + +WoT +Runtime +.

      +7.2 + +The + +ThingProperty + +interface +

      +The + +ThingProperty + +interface +is +used +in + +ConsumedThing + +and + +ExposedThing + +objects +to +represent + +Thing + +Property + +interactions. +

      +The + +PropertyFragment + + + +dictionary +contains + +is +used +for +initializing + +Property + +objects +in +a + +ThingFragment + +dictionary +used +for +creating +an + +ExposedThing + +object. +It + +MUST + +implement +one +of + +the +following +properties: + + + +DataSchema + +dictionaries. + +

      +
      +
      "idl-def-thingproperty" data-idl="" data-title=
+"ThingProperty">interface ThingProperty : Interaction {
+  // getter for PropertyFragment properties
+  getter 
+"https://heycam.github.io/webidl/#idl-any">any (DOMString name);
+  // get and set interface for the Property
+  
+"https://heycam.github.io/webidl/#idl-promise">Promise<any> read();
+  
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> write(any value);
+};
+
+"dfn">ThingProperty includes PropertyFragment;
+
+"dfn">ThingProperty includes 
+
+Observable
+
+;
+

      +The + + +href + +ThingProperty + +interface +contains +all +the +properties +defined +on + +PropertyFragment + + + +as +read-only +properties. +

      +The + +type + + +attribute + +read-only +property + +represents +the +type +definition +for +the + +Property + +as + +a +hyperlink +reference + + + +DataSchema + +dictionary +object. +

      +The + +writable + +read-only +property +tells +whether +the + +Property + +value +can +be +updated. +If +it +is + +false +, +then +the + +set(value) + +method + +SHOULD + +always +reject. +

      +The + +observable + +read-only +property +tells +whether +the + +Property + +supports +subscribing +to +value +change +notifications. +If +it +is + +false +, +then +the + +subscribe() + +method + +SHOULD + +always +fail. +

      +The + +constant + +read-only +property +- +defined +in + +DataSchema + +- +tells +whether +the + +Property + +value +is +a +constant. +If + +true +, +the + +set() + +and + +subscribe() + +methods + +SHOULD + +always +fail. +

      +The + +required + +read-only +property +- +defined +in + +DataSchema + +- +tells +whether +the + +Property + +should +be +always +present +on +the + +ExposedThing + +object. +

      +The + +read() + +method +will +fetch +the +value +of +the + +Property + +. +Returns +a + +Promise + +that +resolves +with +the +value, +or +rejects +with +an +error. +

      +The + + +rel + +write() + + + +attribute +represents + +method +will +attempt +to +set +the +value +of +the + +Property + +specified +in +the + +value + +argument +whose +type + +SHOULD + +match +the +one +specified +by +the + +type + +property. +Returns + +a +relation + + +Promise + +that +resolves +on +success, +or +rejects +on +an +error. +

      +7.3 + +The + +ThingAction + +interface +

      
+"idl-def-thingaction" data-idl="" data-title=
+"ThingAction">interface ThingAction : Interaction {
+  
+"https://heycam.github.io/webidl/#idl-promise">Promise<any> invoke(optional any inputValue);
+};
+
+"dfn">ThingAction includes 
+
+ActionFragment
+
+;
+

      +The + +invoke() + +method +when +invoked, +starts +the + +Action + +interaction +with +the +input +value +provided +by +the + +inputValue + +argument. +If + +inputValue + +is + +null +, +the +action +does +not +take +any +arguments +and +rejects +if +any +arguments +are +provided. +If +the +value +is + +undefined +, +the +action +will +ignore +any +arguments +provided. +Otherwise +the + +type +of + +inputValue + +SHOULD + +match +the + +DataSchema + +definition +in +the + +input + +property. +Returns +a + +Promise + +that +will +reject +with +an +error +or +will +resolve +with +a +value +of +type +defined +by +the + +output + +property. +

      +7.4 + +The + +ThingEvent + +interface +

      
+"idl-def-thingevent" data-idl="" data-title=
+"ThingEvent">interface ThingEvent : Interaction {
+};
+
+"dfn">ThingEvent includes EventFragment;
+
+"dfn">ThingEvent includes 
+
+ThingProperty
+
+;
+

      +Since + +ThingEvent + +implements + +Observable + +through +the + +ThingProperty + +interface, +event +subscription +is +done +by +invoking +the + +subscribe() + +method +on +the +event +object +that +returns +a +cancelable + +Subscription + +. +

      +
      +
      +

      + +7.5 + +The + + +mediaType + +ExposedEvent + + + +attribute +represents + +interface +

      
+"idl-def-exposedevent" data-idl="" data-title=
+"ExposedEvent">interface ExposedEvent : ThingEvent {
+  void emit(any payload);
+};
+

      +7.5.1 + +The + +emit() + +method +

      +Emits +an +event +that +carries +data +specified +by +the + +payload + +argument. +

      +7.6 + +The + +value-matching +algorithm +

      +The +value-matching +algorithm +is +applied +to + +a +IANA +media + + +value + +input +in +relation +to +a + +valueType + +property +of + +type +. +For +TD + + + +DataSchema +, +for +instance +the + +value + +and + +type + +properties +of +a + +PropertyFragment + + +s +there +will +be +registered +media +types, +so +applications +will +be +able + +object, +or +the + +inputValue + +parameter + +to +check +whether +an + +the + + +href + +invoke() + + +link +points + +method +of +a + +ThingAction + +object +in +relation + +to +the +same +object. +It +executes +the +following +steps: +

      1. +If + +valueType.type + +is +not +defined, +or +does +not +fully +match + +a +TD + +string +enumerated +in + +DataType + +, +i.e. +whether + +return + +false +.
      2. +Otherwise, +if + +valueType.type + +is + +"null" +: +if + +value + +is + +null +, +return + +true +, +otherwise +return + +false +.
      3. +Otherwise, +if + +valueType.type + +is + +"boolean" +: +if + +value + +is +either + +true + +or + +false +, +then +return + +true +, +otherwise +return + +false +.
      4. +Otherwise, +if + +valueType.type + +is + +"integer" +: +if + +value + +is +not +an +integer +type +defined +by + +the +link + +underlying +platform +(such +as + +long + +or + +long +long + +), +then +return + +false +, +otherwise +execute +the +following +sub-steps: +
        1. +If + +valueType.minimum + +is +fetcheable +with + +defined +and + +value + +is +not +greater +or +equal +than +that +value, +return + +false +.
        2. +If + +valueType.maximum + +is +defined +and + +value + +is +not +less +or +equal +than +that +value, +return + +false +.
        3. +Return + +true +.
      5. +Otherwise, +if + +valueType.type + +is + +"number" +, +if + +value + +is +not +an +integer +or +floating +point +type +defined +by +the +underlying +platform +(such +as + +long + +or + +long +long + +or + +double + +), +then +return + +false +, +otherwise +otherwise +execute +the +following +sub-steps: +
        1. +If + +valueType.minimum + +is +defined +and + +value + +is +not +greater +or +equal +than +that +value, +return + +false +.
        2. +If + +valueType.maximum + +is +defined +and + +value + +is +not +less +or +equal +than +that +value, +return + +false +.
        3. +Return + +true +.
      6. +Otherwise, +if + +valueType.type + +is + +"string" +: +if + +value + +is +not +a +string +type +defined +by +the +underlying +platform, +then +return + +false +, +otherwise +return + +true +. +In + +this +API. + +case +the +algorithm +expects +a +third +parameter + +valueType.enum + +and +runs +the +following +sub-steps: +
        • +If + +valueType.enum + +is +an +array +of +strings, +then +if + +value + +fully +matches +one +of +the +strings +defined +in +the +array, +return + +true +.
        • +Otherwise, +return + +false +. +
          • +
        +
        7. +
      7. +Otherwise, +if + +valueType.type + +is + +"array" +, +execute +the +following +sub-steps: +
        1. +If + +value + +is +not +an +array, +return + +false +.
        2. +If + +valueType.minItems + +is +defined, +and + +value + +does +not +contain +at +least + +valueType.minItems + +elements, +return + +false +.
        3. +If + +valueType.maxItems + +is +defined, +and + +value + +contains +more +than + +valueType.maxItems + +elements, +return + +false +.
        4. +Otherwise, +if + +valueType.items + +is + +undefined +, +return + +false +.
        5. +Otherwise, +if + +valueType.items + +is + +null +, +return + +true + +(i.e. +any +type +is +accepted +as +array +element, +including +heterogenous +arrays). +
        6. +Otherwise, +for +each +element +of +the +array + +value + +run +the + +value-matching +algorithm + +against +the + +valueType.items + +object. +If +any +of +these +runs +returns + +false +, +then +return + +false +.
        7. +Otherwise, +return + +true +.
      8. +Otherwise, +if + +type + +is + +"object" +, +execute +the +following +sub-steps: +
        1. +If + +value + +is +not +an + +Object +, +return + +false +.
        2. +If + +valueType.properties + +is +not +defined, +return + +false +.
        3. +If + +valueType.properties + +is + +null +, +return + +true + +(i.e. +accept +any +object +value). +
        4. +For +each +string +in +the + +valueType.required + +array, +if +it +does +not +match +a +property +name +in +the + +value.properties + +object +or +in +the + +value + +object, +then +return + +false +.
        5. +For +each +property +with +name + +propName + +and +value + +propDataSchema + +found +in + +valueType.properties +, +run +the +following +sub-steps: +
          1. +If +the +result +of +applying +the + +value-matching +algorithm + +on +the +value + +value[propName] + +and + +propDataSchema + +is + +false +, +then +return + +false +.
        6. +Return + +true +.
      +
      +
      +
      +

      + +7. + +8. + + +Observables + + +

      +

      + +This +section +is +non-normative. + +

      +

      + +Observables + +are + +proposed + +to +be +included +in +ECMAScript +and +are +used +for +handling +pushed +data +associated +with +various +possible +sources, +for +instance +events, +timers, +streams, +etc. +A +minimal +required +implementation +is +described +here. +

      +
      +
      + +Editor's +note + +
      +

      +This +section +is +informal +and +contains +rather +laconic +information +for +implementations +on +what +to +support +for +interoperability. +

      +
      +
      +
      interface "dfn"> {
+<span class="idlMethod" id=
+"idl-def-observable-subscribe-next-error-complete" data-idl=""
+data-title="subscribe" data-dfn-for="observable">    <span class=
+"idlMethType"><a href="#dom-subscription" class="internalDFN"
+
+"dfn">Observable {
+  Subscription subscribe("idlParam">(<a href="#dom-observer"
+class="internalDFN" data-link-type=
+"dfn"> or <a href="#dom-onnext" class=
+
+"idlParam">EventHandler handler,
+                         optional ErrorHandler errorHandler,
+                         optional 
+"internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">next,
+                           <span class=
+"idlParam">optional <a href=
+"#dom-onerror" class="internalDFN" data-link-type=
+"dfn"> <span class=
+"idlParamName">error,
+                           <span class=
+"idlParam">optional <a href=
+"#dom-oncomplete" class="internalDFN" data-link-type=
+
+"dfn">OnComplete "idlParamName">complete
+};
+<span class="idlInterface" id="idl-def-subscription" data-idl=""
+data-title="Subscription">interface <span class=
+"idlInterfaceID"><a data-no-default="" data-link-for="" data-lt=""
+href="#dom-subscription" class="internalDFN" data-link-type=
+"dfn"> {
+<span class="idlMethod" id="idl-def-subscription-unsubscribe"
+data-idl="" data-title="unsubscribe" data-dfn-for=
+"subscription">    <span class=
+"idlMethType">void <span class=
+"idlMethName"><a data-no-default="" data-link-for="subscription"
+data-lt="unsubscribe|unsubscribe()" href=
+"#dom-subscription-unsubscribe" class="internalDFN" data-link-type=
+"dfn">
+<span class="idlAttribute" id="idl-def-subscription-closed"
+data-idl="" data-title="closed" data-dfn-for=
+"subscription">    readonly attribute <span class=
+"idlAttrType"><a href=
+
+"idlParamName">onComplete);
+};
+interface Subscription {
+  void unsubscribe();
+  readonly attribute 
+"https://heycam.github.io/webidl/#idl-boolean">boolean data-link-for="subscription" data-lt="" href=
+"#dom-subscription-closed" class="internalDFN" data-link-type=
+
+data-link-for="subscription" data-lt="subscription.closed|closed"
+href="#dom-subscription-closed" class="internalDFN" data-link-type=
+
+"dfn">closed;
+};
+<span class="idlInterface" id="idl-def-observer" data-idl=""
+data-title="Observer">interface <span class=
+"idlInterfaceID"><a data-no-default="" data-link-for="" data-lt=""
+href="#dom-observer" class="internalDFN" data-link-type=
+"dfn"> {
+<span class="idlMethod" id="idl-def-observer-next-value" data-idl=
+"" data-title="next" data-dfn-for="observer">    <span class=
+"idlMethType">void <span class=
+"idlMethName"><a data-no-default="" data-link-for="observer"
+data-lt="next()|next" href="#dom-observer-next" class="internalDFN"
+data-link-type="dfn">next(<span class=
+"idlParam"><a href=
+"https://heycam.github.io/webidl/#idl-any">any
+<span class="idlMethod" id="idl-def-observer-error-error" data-idl=
+"" data-title="error" data-dfn-for="observer">    <span class=
+"idlMethType">void <span class=
+"idlMethName"><a data-no-default="" data-link-for="observer"
+data-lt="error()|error" href="#dom-observer-error" class=
+"internalDFN" data-link-type="dfn">error(<span class=
+"idlParam"><a href=
+"https://heycam.github.io/webidl/#idl-Error">Error
+<span class="idlMethod" id="idl-def-observer-complete" data-idl=""
+data-title="complete" data-dfn-for="observer">    <span class=
+"idlMethType">void <span class=
+"idlMethName"><a data-no-default="" data-link-for="observer"
+data-lt="complete()|complete" href="#dom-observer-complete" class=
+"internalDFN" data-link-type="dfn">complete
+};
+<span class="idlCallback" id="idl-def-onnext" data-idl=""
+data-title="OnNext">callback <span class=
+"idlCallbackID"><a data-no-default="" data-link-for="" data-lt=""
+href="#dom-onnext" class="internalDFN" data-link-type=
+"dfn"> = <span class=
+"idlCallbackType">void<span class=
+
+};
+callback EventHandler = void (
+"idlParamType">"https://heycam.github.io/webidl/#idl-any">any
+<span class="idlCallback" id="idl-def-onerror" data-idl=""
+data-title="OnError">callback <span class=
+"idlCallbackID"><a data-no-default="" data-link-for="" data-lt=""
+href="#dom-onerror" class="internalDFN" data-link-type=
+"dfn"> = <span class=
+"idlCallbackType">void<span class=
+
+"https://heycam.github.io/webidl/#idl-any">any value);
+callback ErrorHandler = void (
+"idlParamType">"https://heycam.github.io/webidl/#idl-Error">Error
+<span class="idlCallback" id="idl-def-oncomplete" data-idl=""
+data-title="OnComplete">callback <span class=
+"idlCallbackID"><a data-no-default="" data-link-for="" data-lt=""
+href="#dom-oncomplete" class="internalDFN" data-link-type=
+"dfn"> = <span class=
+
+"https://heycam.github.io/webidl/#idl-Error">Error error);
+callback OnComplete =
+"idlCallbackType">
+void
+
+();
+
+
      +
      +7.1 +The +Observer +interface + +

      +The +Observer +interface +defines +the + +following + +callbacks +needed + +can +be +provided +when +subscribing + +to +handle + +an + + +Observable + +: +

      +
        +
      • +The +next() +function, +as +well +as +the + + + +OnNext + +EventHandler + + + +callback +takes +the +next +sample +for +the +data +in +the + +value + +argument. +
        • +
      • +The +error() +function, +as +well +as +the + + + +OnError + +ErrorHandler + + + +callback +takes +an +error +in +the + +value + +argument. +It +is +called +when +an +error +occured +in +producing +the +data +the +client +should +know +about. +
        • +
      • +The +complete() +function, +as +well +as +the + + + +OnComplete + + +callback +is +called +when +the +data +source +has +finished +sending +values. +
        • +
      +
      +

      + +7.2 + +8.1 + + +The + + +Subscription + + +interface + + +

      +

      +Contains +the + + +closed + + +property +of +type + +boolean + +that +tells +if +the +subscription +is +closed +or +active. +

      +

      +Also, +contains +the + + +unsubscribe + + +() +method +that +cancels +the +subscription, +i.e. +makes +a +request +to +the +underlying +platform +to +stop +receiving +data +from +the +source, +and +sets +the + +closed + +property +to + +false +. +

      +
      +
      +

      + +7.3 + +8.2 + + +The + + +Observable + + +interface + + +

      +

      +The + + +Observable + + +interface +enabled +subscribing +to +pushed +data +notifications +by +the + + +subscribe + + +() +method: +

      +
        +
      • +If +the +subscribe() +method +is +called +with +an +Observer +object, +initialize +the +data, +error +and +completion +handling +callbacks +from +that +object, +or +throw +on +error. +Otherwise, +if +the +subscribe() +method +is +called +with +a +function, +initialize + +Initialize + +the +data +handler +callback +with +that +function. + +the +first +function +argument. +
      • +If +the +next +argument +is +provided +and +is +a +function, +initialize +the +error +handling +callback +with +that +function, +or +throw +on +error. +
        • +
      • +If +the +third +argument +is +provided +and +is +a +function, +initialize +the +completion +handler +with +that +function, +or +throw +on +error. +
        • +
      • +After +callback +initializations, +the +implementation +should +request +the +underlying +platform +to +provide +data, +error +and +completion +notifications +for +the +supported +data +source. +
        • +
      +
      +
      +
      +

      + +8. + +9. + + +Security +and +Privacy + +Editor's +note + + +Please +see + +

      +

      +In +general + +the +security +measures +taken +to +protect +a + +WoT +Security + +system +will +depend +on +the +threats + +and +Privacy +repository + +attackers +that +system +may +face +and +the +value +of +the +assets +needs +to +protect. +A +detailed +discussion +of +security +and +privacy +considerations + +for +work +in +progress +regarding + +the +Web +of +Things, +including +a + +threat +models, +assets, +risks, +recommended +mitigations, + +model +that +can +be +adapted +to +various +circumstances, +is +presented +in +the +informative +document +[ + +WOT-SECURITY-CONSIDERATIONS + +]. +This +section +includes +only +normative +recommendations +relevant +to +the +WoT +Thing +Description. +

      +When +designing +new +devices + +and +services +for +use +with +the +WoT, +we +have +documented +a +set +of + +best +practices +for + +in +[ + +WOT-SECURITY-BEST-PRACTICES + +] +that + +SHOULD + +be +followed. + +This +best-practices +document +may +be +updated +as + +security +measures +evolve. +Following +these +practices +does +not +guarantee +security, +but +it +at +least +will +help +to +avoid +common +known +vulnerabilities + +and +privacy +for +systems + +pitfalls. +

      +Below +are +specific +recommendations +related +to +WoT +runtime +implementations: +

      • +In +basic +WoT +setups, +all +scripts +running +inside +the +WoT +runtime +are +considered +trusted, +and +therefore +there +is +no +strong +need +to +perform +strict +isolation +between +each +running +script +instance. +However, +depending +on +device +capabilities +and +deployment +use +case +scenario +risk +level +it +might +be +desirable +to +do +so. +
        • +For +example, +if +one +script +handles +sensitive +privacy-related +data +and +well-audited, +it +might +be +desirable +to +separate +it +from +the +rest +of +the +script +instances +to +minimize +the +risk +of +data +exposure +in +case +some +other +script +inside +WoT +gets +compromised +during +the +runtime. + +Therefore +the +WoT +runtime + +SHOULD + +perform +isolation +of +script +instances +and +their +data +in +cases +when +scripts +handle +privacy-related +or +other +critical +security +data. +
        • +Another +example +is +mutual +co-existence +of +different +tenants +on +a +single +WoT +device. +In +this +case +each +WoT +runtime +instance +will +be +hosting +a +different +tenant, +and +isolation +between +them +is +required. + +Therefore +the +WoT +runtime + +SHOULD + +perform +isolation +of +WoT +runtime +instances +and +their +data +if +a +WoT +device +has +more +than +one +tenant. +
        +Such +isolation +can +be +performed +within +the +WoT +Runtime + +using +platform +security +mechanisms +available +on + +the +Web + +device. +For +more +information +see +Section +"WoT +Servient +Single-Tenant" +and +"WoT +Servient +Multi-Tenant" + +of +[ + +WOT-SECURITY-CONSIDERATIONS + +]. +
      • +WoT +scripts +are +using +WoT +Scripting +API +to +implement +the +functionality +and +logic +for +WoT + +Things. +Once +complete, + +In +addition +to +providing +the +isolation +between +script +and +runtime +instances, +the +WoT +runtime +needs +to +protect +the +underlying +physical +device +from +potentially +misbehaving +WoT +scripts. + +Therefore +the +WoT +Runtime + +SHOULD + +avoid +directly +exposing +the +native +device +interfaces +to +the +script +developers. + +Instead +a +WoT +Runtime +should +provide +a +hardware +abstraction +layer +for +accessing +the +native +device +interfaces. +Additionally, +in +order +to +reduce +the +damage +to +a +physical +WoT +device +in +cases +a +WoT +script +gets +compromised, +it +is +important +to +minimize +the +number +of +interfaces +that +are +exposed +or +accessible +to +a +particular +WoT +script +based +on +its +functionality. + +Therefore +the +WoT +Runtime + +SHOULD + +only +expose +a +minimal +set +of +interfaces +to +a +WoT +script +based +on +its +intended +functionality. +
      • +If +the +WoT +runtime +supports +post-manufacturing +provisioning +or +update +of +WoT +scripts, +WoT +runtime +or +any +related +data +(including + +security +credentials), +it +can +be +a +major +attack +vector. +An +attacker +can +try +to +modify +any +above +described +part +during +the +update +or +provisioning +process +or +simply +provision +attacker's +code + +and +privacy +considerations +relevant + +data +directly. + +Therefore, +if +WoT +Runtime +supports +post-manufacturing +provisioning +or +update +of +WoT +scripts, +WoT +runtime +or +any +related +data, +such +operations + +SHOULD + +be +done +in +a +secure +fashion. + +A +set +of +recommendations +for +secure +update +and +post-manufacturing +provisioning +can +be +found +in +[ + +WOT-SECURITY-BEST-PRACTICES + +]. +
      • +Typically +the +WoT +runtime +needs + +to +store + +the +Scripting +API +will + +security +credentials +that +are +provisioned +to +a +WoT +device +to +operate +in +WoT +network. +The +confidentiality +or +integrity +of +these +credentials +should +not + +be +summarized + +compromised. + +Therefore +the +WoT +runtime + +SHOULD + +securely +store +the +provisioned +security +credentials, +guaranteeing +their +integrity +and +confidentiality. + +In +case +there +are +more +than +one +tenant +on +a +single +WoT-enabled +device, +a +WoT +Runtime + +SHOULD + +guarantee +isolation +of +each +tenant +provisioned +security +credentials. + +Additionally, + +in +this +section. + +order +to +minimize +a +risk +that +provisioned +security +credentials +get +compromised, +the +WoT +runtime +should +not +have +any +way +for +WoT +scripts +to +query +these +credentials. + +Therefore, +the +WoT +Runtime + +SHOULD +NOT + +expose +any +API +for +WoT +scripts +to +query +the +provisioned +security +credentials. +

      +Some +additional +specific +recommendations +relevant +for +WoT +script +developers: + +

      +
        +
      • +A +typical +way +to +compromise +any +process +is +to +send +it +a +corrupted +input +via +one +of +the +exposed +interfaces. + +Therefore +developers + +SHOULD + +perform +validation +on +all +WoT +script +inputs, +including + +fuzzing +. +There +are +many +tool +and +techniques +in +existence +to +do +such +validation. +More +details +can +be +found +in +[ + +WOT-SECURITY-TESTING + +]. +
      • +As +any +software, +complex +scripts +with +a +lot +of +functionality +presents +a +higher +risk +of +development +mistakes. +Such +scripts +are +also +hard +to +verify +and +test +appropriately. + +Therefore +developers +SHOUD +minimize +the +functionality +and +complexity +of +WoT +scripts. +
      • +If +a +WoT +script +performs +a +heavy +functional +processing +on +received +requests +before +the +request +is +authenticated, +it +presents +a +great +risk +for +Denial-Of-Service +(DOS) +attacks. + +Therefore +WoT +scripts + +SHOULD + +avoid +heavy +functional +processing +without +prior +successful +authentication +of +requestor. + +The +set +of +recommended +authentication +mechanisms +can +be +found +in +[ + +WOT-SECURITY-BEST-PRACTICES + +]. +
      • +WoT +developers +should +remember +that +a +content +of +a +TD +can +change, +including +its +identified, +id, +which +is +not +an +immutable +identifier. + +Therefore +WoT +scripts + +SHOULD + +use +the +provided +WoT +script +API +to +subscribe +for +notifications +on +TD +changes. +
      +
      +
      +

      + +9. + +10. + + +Terminology +and +conventions + + +

      +

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

      +

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

      +

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

      +

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

      +

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

      +

      +The +term + + +secure +context + + +is +defined +in +[ + + +WEBAPPSEC + + +]. +

      +

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

      +

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

      +

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

      +

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

      +

      +The +terms + +hyperlink +reference + +and + +relation +type + +are +defined +in +[ + +HTML52 + + +HTML5 + + + +] +and + +RFC8288 +. +

      +
      +
      +

      + +10. + +11. + + +Conformance + + +

      +

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

      +

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

      +

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

      +

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

      +

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

      +

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

      +

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

      +

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

      +
      +
      +

      + +A. + +Changes + + +

      +

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

      +
        +
      • +Synchronized + +Make + +the +Scripting +API +with + +refer +to +(rather +then +locally +re-define) + +the +data +structures +defined +in +the + +Thing +Description +specification +. +Defined +ThingDescription +, +ThingTemplate +, +SemanticAnnotations +, +SemanticType +, +SemanticMetadata +, +input +and +output +data +descriptions, +etc. +Separated +consume() +to +fetch() +and +consume() +. +Changed +expose() +to +accept +a +Thing +Template +. +Instead +of +addListener() +, +removeListener() +introduced +onEvent() +, +onPropertyChange() +, +onTDChange() +. +Revised +ExposedThing +handlers +for +Property, +Action +and +Event. +Added +an +informal +section +on +TD +introspection. +Added +informal +section +for +Observable +. + +
        • +
      +
      +
      +

      + +B. + +Open +issues + + +

      +

      +The +following +problems +are +being +discussed +and +need +most +attention: +

      +
        +
      • +Revised +API +for +tracking +the +TD +better +( +https://github.com/w3c/wot-scripting-api/issues/96) +. + +Security +related +metadata +( +https://github.com/w3c/wot-scripting-api/issues/91) +. +Defining +DataSchema +better +( +https://github.com/w3c/wot-scripting-api/issues/89) +. + +(https://github.com/w3c/wot-scripting-api/issues/91). + +
        • +
      • +Providing +Protocol +Binding +for + + +ExposedThing + + +( +https://github.com/w3c/wot-scripting-api/issues/45) +. +Retrieving +information +from +Thing +Description +( +https://github.com/w3c/wot-scripting-api/issues/38 +) + +(https://github.com/w3c/wot-scripting-api/issues/45). + +
        • +
      • +Script +management +and +runtime +related +issues +( +https://github.com/w3c/wot-scripting-api/issues/ +) + +(https://github.com/w3c/wot-scripting-api/issues/) + +
        • +
      +
      +
      +

      + +C. + +Acknowledgements + + +

      +

      +Special +thanks +to +former +editor +Johannes +Hund +(until +August +2017, +when +at +Siemens +AG) +for +developing +this +specification. +Also, +the +editors +would +like +to +thank +Dave +Raggett, +Matthias +Kovatsch, +Michael +Koster +and +Michael +McCool +for +their +comments +and +guidance. +

      +
      +
      +

      + +D. + +References + + +

      +
      +

      + +D.1 + +Normative +references + + +

      +
      +
      +[ECMASCRIPT] +
      +
      + + +ECMAScript +Language +Specification + +. +Ecma +International. +URL: + +https://tc39.github.io/ecma262/ + +
      +
      +[ENCODING] +
      +
      + + +Encoding + +. +Anne +van +Kesteren; +Joshua +Bell; +Addison +Phillips. +W3C. +15 +December +2016. +W3C +Candidate +Recommendation. +URL: + +https://www.w3.org/TR/encoding/ + +
      +[HTML52] + +
      +[HTML5] + +
      +
      + + +HTML +5.2 + +HTML5 + + +. +Ian +Hickson; +Robin +Berjon; + +Steve +Faulkner; +Arron +Eicholz; + +Travis +Leithead; +Alex +Danilo; +Sangwhan +Moon; + +Erika +Doyle +Navara; +Theresa +O'Connor; +Robin +Berjon. + +Silvia +Pfeiffer. + +W3C. +14 +December +2017. + +27 +March +2018. + +W3C +Recommendation. +URL: +https://www.w3.org/TR/html52/ + + +https://www.w3.org/TR/html5/ + + +
      +
      +[JSON-LD] +
      +
      + + +JSON-LD +1.0 + +. +Manu +Sporny; +Gregg +Kellogg; +Markus +Lanthaler. +W3C. +16 +January +2014. +W3C +Recommendation. +URL: + +https://www.w3.org/TR/json-ld/ + +
      +
      +[RFC2119] +
      +
      + + +Key +words +for +use +in +RFCs +to +Indicate +Requirement +Levels + +. +S. +Bradner. +IETF. +March +1997. +Best +Current +Practice. +URL: + +https://tools.ietf.org/html/rfc2119 + +
      +
      +[TYPESCRIPT] +
      +
      + + +TypeScript +Language +Specification + +. +Microsoft. +1 +October +2012. +URL: + +https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md + +
      +
      +[URL] +
      +
      + + +URL +Standard + +. +Anne +van +Kesteren. +WHATWG. +Living +Standard. +URL: + +https://url.spec.whatwg.org/ + +
      +
      +[WEBAPPSEC] +
      +
      + + +Secure +Contexts + +. +W3C. +17 +July +2015. +URL: +https://w3c.github.io/webappsec/specs/powerfulfeatures/ + + +https://w3c.github.io/webappsec/specs/powerfulfeatures + + +
      +
      +[WEBIDL] +
      +
      + + +Web +IDL + +. +Cameron +McCormack; +Boris +Zbarsky; +Tobie +Langel. +W3C. +15 +December +2016. +W3C +Editor's +Draft. +URL: + +https://heycam.github.io/webidl/ + +
      +
      +[WOT-ARCHITECTURE] +
      +
      + + +Web +of +Things +Architecture + +. +W3C. +14 +September + +20 +August + +2017. +URL: +https://www.w3.org/TR/2017/WD-wot-architecture-20170914/ + + +https://w3c.github.io/wot-architecture/ +
      +[WOT-SECURITY-BEST-PRACTICES] +
      +Web +of +Things +Security +and +Privacy +Best +Practices +(WIP) +. +W3C. +WIP. +URL: + +https://github.com/w3c/wot-security/blob/master/wot-security-best-practices.md +
      +[WOT-SECURITY-CONSIDERATIONS] +
      +Web +of +Things +Security +and +Privacy +Considerations +. +W3C. +28 +August +2017. +URL: + +https://w3c.github.io/wot-security/ +
      +[WOT-SECURITY-TESTING] +
      +Web +of +Things +Security +Testing +and +Validation +. +W3C. +WIP. +URL: + +https://github.com/w3c/wot-security/blob/master/wot-security-testing.md +
      +[WOT-TD] +
      +WoT +Thing +Description + +. +W3C. +20 +August +2017. +URL: + +https://w3c.github.io/wot-thing-description/ + + +
      +
      +
      +
      +

      + +D.2 + +Informative +references + + +

      +
      +[WOT-TD] + +
      +[HTML] + +
      +
      + + +WoT +Thing +Description + +HTML +Standard + + +. +W3C. +20 +August +2017. + +. +Anne +van +Kesteren; +Domenic +Denicola; +Ian +Hickson; +Philip +Jägenstedt; +Simon +Pieters. +WHATWG. +Living +Standard. + +URL: +https://www.w3.org/TR/2018/WD-wot-thing-description-20180405/ + + +https://html.spec.whatwg.org/multipage/ + + +
      +
      +
      +
      + + + + diff --git a/releases/wd3/manifest.txt b/releases/wd3/manifest.txt new file mode 100644 index 00000000..578b5801 --- /dev/null +++ b/releases/wd3/manifest.txt @@ -0,0 +1,2 @@ +Overview.html +diff.html From e87a8d937f82f8a5cdd0cb14fb058344b1dd76e5 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Tue, 30 Oct 2018 09:14:49 +0100 Subject: [PATCH 264/464] move https://github.com/thingweb/wot-typescript-definitions to scripting api repository --- typescript/README.md | 16 ++ typescript/index.d.ts | 412 +++++++++++++++++++++++++++++++++++++++ typescript/package.json | 28 +++ typescript/tsconfig.json | 18 ++ 4 files changed, 474 insertions(+) create mode 100644 typescript/README.md create mode 100644 typescript/index.d.ts create mode 100644 typescript/package.json create mode 100644 typescript/tsconfig.json diff --git a/typescript/README.md b/typescript/README.md new file mode 100644 index 00000000..e3f37430 --- /dev/null +++ b/typescript/README.md @@ -0,0 +1,16 @@ +# wot-typescript-definitions + +A typescript definition file for the WoT scripting API as used in thingweb node-wot. + +## WARNING + +The current definitions and work are still done on https://github.com/thingweb/wot-typescript-definitions and will be moved to this repository in the near future. + +## Notes on usage + +These definitions are imported using npm. Once we reach conclusion on the API in the W3C Web of Things task force, we will add this to definatelytyped. + +## ES5 targets + +As consumers are using typescript we target ES6. +When implementing for ES5 targets, be sure to provide a polyfill for ES6 Promises, either ``es6-promise`` from npm or add the lib ``es2015.promise`` to your tsc command when transpiling typescript. \ No newline at end of file diff --git a/typescript/index.d.ts b/typescript/index.d.ts new file mode 100644 index 00000000..0a60a875 --- /dev/null +++ b/typescript/index.d.ts @@ -0,0 +1,412 @@ +import { Observable } from 'rxjs/Observable'; +import { Subscription } from 'rxjs/Subscription'; + +export as namespace WoT; + +/** + * The WoTFactory (usually instantiated as "WoT" object) is the main API entry point + * and it is exposed by an implementation of the WoT Runtime. + */ +export interface WoTFactory { + /** + * Starts the discovery process that will provide ConsumedThing + * + * @param filter represents the constraints for discovering Things as key-value pairs + */ + discover(filter?: ThingFilter): Observable; + + /** + * Accepts an url argument and returns a Promise of a ThingDescription + * @param url URL of a thing description + */ + fetch(url: USVString): Promise; + + /** + * Accepts a ThingDescription and returns a ConsumedThing + * @param url URL of a thing description + */ + consume(td: ThingDescription): ConsumedThing; + + /** + * Accepts a model argument of type ThingModel and returns an ExposedThing object + * + * @param model can be either a ThingTemplate, or a ThingDescription. + */ + produce(model: ThingModel): ExposedThing; + + /** + * Make a request to register td to the given WoT Thing Directory.. + */ + register(directory: USVString, thing: ExposedThing): Promise; + + /** + * Makes a request to unregister the thing from the given WoT Thing Directory. */ + unregister(directory: USVString, thing: ExposedThing): Promise; +} + +/** + * Dictionary that represents the constraints for discovering Things as key-value pairs. + */ +export interface ThingFilter { + /** + * The method field represents the discovery type that should be used in the discovery process. The possible values are defined by the DiscoveryMethod enumeration that can be extended by string values defined by solutions (with no guarantee of interoperability). + */ + method?: DiscoveryMethod | string; // default value "any", DOMString + /** + * The url field represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, such as a Thing Directory or a Thing. + */ + url?: USVString; + /** + * The query field represents a query string accepted by the implementation, for instance a SPARQL query. + */ + query?: USVString; + /** + * The fragment field represents a ThingFragment dictionary used for matching against discovered Things. + */ + fragment?: ThingFragment; +} + +/** The DiscoveryMethod enumeration represents the discovery type to be used */ +export declare enum DiscoveryMethod { + /** does not restrict */ + "any", + /** for discovering Things defined in the same Servient */ + "local", + /** for discovery based on a service provided by a Thing Directory */ + "directory", + /** for discovering Things in the same/reachable network by using a supported multicast protocol */ + "multicast" +} + +/** + * WoT provides a unified representation for data exchange between Things, standardized in the Wot Things Description specification. + * In this version of the API, Thing Descriptions are represented as opaque strings, denoting a serialized form, for instance JSON or JSON-LD + */ +export declare type ThingDescription = USVString; + +/** + * The ThingFragment dictionary contains fields to initialize a Thing or to match during discovery + */ +export interface ThingFragment { + /** A hint to gernerate the identifier for the Thing */ + id?: string; + /** The name attribute represents the user given name of the Thing */ + name?: string; + /** A human-readable description of the Thing */ + description?: string; + /** Information about the Thing maintainer, e.g., author or contact URI */ + support?: string; + + /** A list of security schemas used by the Thing */ + security?: Array; + + /** A map of PropertyFragments with decriptions only */ + properties?: { [key: string]: PropertyFragment } + /** A map of ActionFragments with decriptions only */ + actions?: { [key: string]: ActionFragment } + /** A map of EventFragments with decriptions only */ + events?: { [key: string]: EventFragment } + /** A list of Web links to other Things or metadata */ + links?: Array; + /** + * A collection of predicate terms that reference values of any type, + * e.g., @context, @type, or other terms from the vocabulary defined in @context. + */ + [key: string]: any; +} + +/** A Thing model is used for producing a new ExposedThing and can be either a ThingTemplate, or a ThingDescription. */ +export declare type ThingModel = (ThingDescription | ThingFragment); + +/** Base for representing Thing Interaction descriptions */ +export interface InteractionFragment { + /** A human-readable title for the Interaction, e.g., for UIs */ + title?: string; + /** A human-readable description of the Interaction */ + description?: string; + /** + * A collection of predicate terms that reference values of any type, + * e.g., @type, or other terms from the vocabulary defined in @context. + */ + [key: string]: any; +} + +/** Represents a Thing Property description */ +export interface PropertyFragment extends InteractionFragment { + writable?: boolean; + observable?: boolean; +} +/** Represents a Thing Action description */ +export interface ActionFragment extends InteractionFragment { + input?: DataSchema; + output?: DataSchema; +} +/** Represents a Thing Event description */ +export interface EventFragment extends InteractionFragment { + subscription?: DataSchema; + data?: DataSchema; + cancellation?: DataSchema; +} + +/** + * A Thing instance must have an id and a name and its Interactions do have forms and + * functions to interact (read/write/invoke/subscribe/emit). + */ +export interface ThingInstance extends ThingFragment { + /** id becomes mandatory for Thing instances */ + id: string; + /** name becomes mandatory for Thing instances */ + name: string; + /** base becomes available for Thing instances (part of binding metadata) */ + base?: string; + + /** A map of ThingProperties (PropertyFragment plus mandatory binding metadata (forms)) */ + properties: { [key: string]: ThingProperty }; + /** A map of ThingActions (ActionFragment plus mandatory binding metadata (forms)) */ + actions: { [key: string]: ThingAction }; + /** A map of ThingEvents (EventFragment plus mandatory binding metadata (forms)) */ + events: { [key: string]: ThingEvent }; +} + +/** + * The Interaction interface is an abstract class to represent Thing interactions: Properties, Actions and Events. + */ +export interface ThingInteraction extends InteractionFragment { + forms: Array
      ; +} + +/** Represents an interactable Thing Property */ +export interface ThingProperty extends ThingInteraction, PropertyFragment //, Observable +{ + read(): Promise; + write(value: any): Promise; + subscribe(next?: (value: any) => void, error?: (error: any) => void, complete?: () => void): Subscription; +} +/** Represents an interactable Thing Action */ +export interface ThingAction extends ThingInteraction, ActionFragment { + invoke(parameter?: any): Promise; +} + +/** Represents an interactable Thing Event */ +// FIXME: Events are different on ConsumendThing and ExposedThing +export interface ThingEvent extends ThingInteraction, EventFragment { + subscribe(next?: (data: any) => void, error?: (error: any) => void, complete?: () => void): Subscription; + // FIXME emit should be only on ExposedThings' ThingEvents - therefore move emit() to ExposedThing? + emit?(data?: any): void; +} + +/** Represents a client API object to consume Things and their Properties, Actions, and Events */ +export interface ConsumedThing extends ThingInstance { + // no additional functions defined +} + +/** Represents a server API object to expose Things and their Properties, Actions, and Events */ +export interface ExposedThing extends ThingInstance { + + // define how to expose and run the Thing + + /** + * Start serving external requests for the Thing, so that WoT Interactions using Properties, Actions and Events will be possible. + */ + expose(): Promise; + + /** + * Stop serving external requests for the Thing and destroy the object. Note that eventual unregistering should be done before invoking this method. + */ + destroy(): Promise; + + // define Thing Description modifiers + + /** + * Adds a Property with name defined by the name argument, the data schema provided by the property argument of type PropertyFragment, and optionally an initial value provided in the argument initValue whose type should match the one defined in the type property. + */ + addProperty(name: string, property: PropertyFragment, init?: any): ExposedThing; + + /** + * Removes the Property specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining. + */ + removeProperty(name: string): ExposedThing; + + /** + * Adds to the actions property of a Thing object an Action with name defined by the name argument, defines input and output data format by the action argument of type ActionFragment, and adds the function provided in the handler argument as a handler, then updates the Thing Description. + * Throws on error. + * Returns a reference to the same object for supporting chaining. + */ + addAction(name: string, action: ActionFragment, handler: ActionHandler): ExposedThing; + + /** + * Removes the Action specified by the name argument and updates the Thing Description. + * Throws on error. + * Returns a reference to the same object for supporting chaining. + */ + removeAction(name: string): ExposedThing; + + /** + * Adds an event with name defined by the name argument and qualifiers and initialization value provided by the event argument of type EventFragmentto the Thing object and updates the Thing Description. + * Throws on error. + * Returns a reference to the same object for supporting chaining. + */ + addEvent(name: string, event: EventFragment): ExposedThing; + + /** + * Removes the event specified by the name argument and updates the Thing Description. + * Returns a reference to the same object for supporting chaining. + */ + removeEvent(name: string): ExposedThing; + + // define request handlers + + /** + * Takes name as string argument and handler as argument of type PropertyReadHandler. + * Sets the handler function for reading the specified Property matched by name. + * Throws on error. + * Returns a reference to the same object for supporting chaining. + */ + setPropertyReadHandler(name: string, handler: PropertyReadHandler): ExposedThing; + + /** + * Takes name as string argument and handler as argument of type PropertyWriteHandler. + * Sets the handler function for writing the specified Property matched by name. + * Throws on error. + * Returns a reference to the same object for supporting chaining. + */ + setPropertyWriteHandler(name: string, handler: PropertyWriteHandler): ExposedThing; + + /** + * Takes name as string argument and handler as argument of type ActionHandler. + * Sets the handler function for the specified Action matched by name. + * Throws on error. + * Returns a reference to the same object for supporting chaining. + */ + setActionHandler(name: string, handler: ActionHandler): ExposedThing; +} + +// TODO: Decide if decorator (with 'internal') or replacement (without 'internal') for get() +// For now decorator in node-wot +export declare type PropertyReadHandler = (internal?: any) => Promise; + +// TODO: Decide if decorator (return any) or replacement (return void) for set() +// For now decorator in node-wot +export declare type PropertyWriteHandler = (value: any) => Promise; + +export declare type ActionHandler = (parameters: any) => Promise; + +export interface Link { + href: USVString; + rel?: USVString | Array; + type?: USVString; // media type hint, no media type parameters + anchor?: USVString; +} + +export interface Form { + href: USVString; + subprotocol?: USVString; + op?: USVString | Array; + contenttype?: USVString; // media type + parameter(s), e.g., text/plain;charset=utf8 + security?: Security; +} + +export type DataSchema = BooleanSchema | IntegerSchema | NumberSchema | StringSchema | ObjectSchema | ArraySchema | NullSchema; + +export interface BaseSchema { + type?: string; + const?: any; + enum?: Array; +} + +export interface BooleanSchema extends BaseSchema { + type: "boolean"; +} + +export interface IntegerSchema extends BaseSchema { + type: "integer"; + minimum?: number; + maximum?: number; +} + +export interface NumberSchema extends BaseSchema { + type: "number"; + minimum?: number; + maximum?: number; +} + +export interface StringSchema extends BaseSchema { + type: "string"; +} + +export interface ObjectSchema extends BaseSchema { + type: "object"; + properties: { [key:string]: DataSchema }; + required?: Array; +} + +export interface ArraySchema extends BaseSchema { + type: "array"; + items: DataSchema; + minItems?: number; + maxItems?: number; +} + +export interface NullSchema extends BaseSchema { + type: "null"; +} + +export type Security = NoSecurityScheme | BasicSecurityScheme | DigestSecurityScheme | BearerSecurityScheme | PopSecurityScheme | ApikeySecurityScheme | OAuth2SecurityScheme | PskScheme; + + +export interface SecurityScheme { + scheme: string; + description?: string; + proxyURI?: any; +} + +export interface NoSecurityScheme extends SecurityScheme { + scheme: "nosec"; +} + +export interface BasicSecurityScheme extends SecurityScheme { + scheme: "basic"; + in: string; + pname?: string; +} + +export interface DigestSecurityScheme extends SecurityScheme { + scheme: "digest"; + in: string; + qop: string; + pname?: string; +} + +export interface BearerSecurityScheme extends SecurityScheme { + scheme: "bearer"; + alg: string; + format: string; + in: string; + pname?: string; +} + +export interface PopSecurityScheme extends SecurityScheme { + scheme: "pop"; + alg: string; + format: string; + in: string; + pname?: string; +} + +export interface ApikeySecurityScheme extends SecurityScheme { + scheme: "apikey"; + in: string; + pname?: string; +} + +export interface OAuth2SecurityScheme extends SecurityScheme { + scheme: "oauth2"; + authorizationUrl: string; + scopes?: Array; + // one of implicit, password, client, or code + flow: string; +} + +export interface PskScheme extends SecurityScheme { + scheme: "psk"; +} diff --git a/typescript/package.json b/typescript/package.json new file mode 100644 index 00000000..dbb07784 --- /dev/null +++ b/typescript/package.json @@ -0,0 +1,28 @@ +{ + "name": "wot-typescript-definitions", + "version": "0.6.0-SNAPSHOT.0", + "description": "TypeScript definitions for the W3C WoT Scripting API", + "author": "W3C WoT Working Group", + "license": "W3C-20150513", + "repository": "https://github.com/w3c/wot-scripting-api/TypeScript", + "keywords": [ + "Web", + "W3C", + "WoT", + "IoT", + "things", + "scripting", + "typescript", + "types" + ], + "publishConfig": { + "access": "public" + }, + "types": "index.d.ts", + "dependencies": { + "rxjs": "5.4.3" + }, + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + } +} diff --git a/typescript/tsconfig.json b/typescript/tsconfig.json new file mode 100644 index 00000000..7a28ba25 --- /dev/null +++ b/typescript/tsconfig.json @@ -0,0 +1,18 @@ +{ + "compilerOptions": { + "target": "es5", + "lib" : ["es2015","dom"], + "module": "commonjs", + "outDir": "dist", + "sourceMap": true, + "noImplicitAny": true, + "removeComments": true, + "noLib": false, + "preserveConstEnums": true, + "experimentalDecorators": true, + "declaration": true + }, + "include": [ + "src/**/*" + ] +} \ No newline at end of file From 1863bd160a58032a428daf173a932a1b80061b4d Mon Sep 17 00:00:00 2001 From: Matthias Kovatsch Date: Sun, 4 Nov 2018 11:51:59 +0100 Subject: [PATCH 265/464] typescript: update security pname to name --- typescript/index.d.ts | 28 ++++++++++++++-------------- typescript/package.json | 6 +++--- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index 0a60a875..575c7a49 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -366,37 +366,37 @@ export interface NoSecurityScheme extends SecurityScheme { export interface BasicSecurityScheme extends SecurityScheme { scheme: "basic"; - in: string; - pname?: string; + in?: string; + name?: string; } export interface DigestSecurityScheme extends SecurityScheme { scheme: "digest"; - in: string; - qop: string; - pname?: string; + qop?: string; + in?: string; + name?: string; } export interface BearerSecurityScheme extends SecurityScheme { scheme: "bearer"; - alg: string; - format: string; - in: string; - pname?: string; + alg?: string; + format?: string; + in?: string; + name?: string; } export interface PopSecurityScheme extends SecurityScheme { scheme: "pop"; - alg: string; - format: string; - in: string; - pname?: string; + alg?: string; + format?: string; + in?: string; + name?: string; } export interface ApikeySecurityScheme extends SecurityScheme { scheme: "apikey"; in: string; - pname?: string; + name?: string; } export interface OAuth2SecurityScheme extends SecurityScheme { diff --git a/typescript/package.json b/typescript/package.json index dbb07784..ec1bec9b 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,10 +1,10 @@ { "name": "wot-typescript-definitions", - "version": "0.6.0-SNAPSHOT.0", + "version": "0.6.0-SNAPSHOT.1", "description": "TypeScript definitions for the W3C WoT Scripting API", - "author": "W3C WoT Working Group", + "author": "W3C Web of Things Working Group", "license": "W3C-20150513", - "repository": "https://github.com/w3c/wot-scripting-api/TypeScript", + "repository": "https://github.com/w3c/wot-scripting-api/tree/master/typescript", "keywords": [ "Web", "W3C", From e1a345d7ed616444b58eb0481e74a1aedf31c222 Mon Sep 17 00:00:00 2001 From: Matthias Kovatsch Date: Sun, 4 Nov 2018 11:52:45 +0100 Subject: [PATCH 266/464] typescript: update contenttype to contentType --- typescript/index.d.ts | 2 +- typescript/package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index 575c7a49..fd1ac128 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -302,7 +302,7 @@ export interface Form { href: USVString; subprotocol?: USVString; op?: USVString | Array; - contenttype?: USVString; // media type + parameter(s), e.g., text/plain;charset=utf8 + contentType?: USVString; // media type + parameter(s), e.g., text/plain;charset=utf8 security?: Security; } diff --git a/typescript/package.json b/typescript/package.json index ec1bec9b..163fc541 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.6.0-SNAPSHOT.1", + "version": "0.6.0-SNAPSHOT.2", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From d8d545295b589afd7c45a80b08768ad1a91efe29 Mon Sep 17 00:00:00 2001 From: Matthias Kovatsch Date: Sun, 4 Nov 2018 12:09:32 +0100 Subject: [PATCH 267/464] typescript: update README --- typescript/README.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/typescript/README.md b/typescript/README.md index e3f37430..5232751c 100644 --- a/typescript/README.md +++ b/typescript/README.md @@ -1,16 +1,13 @@ # wot-typescript-definitions -A typescript definition file for the WoT scripting API as used in thingweb node-wot. - -## WARNING - -The current definitions and work are still done on https://github.com/thingweb/wot-typescript-definitions and will be moved to this repository in the near future. +A TypeScript definition file for the WoT Scripting API to be used by implementations such as [Eclipse Thingweb](https://projects.eclipse.org/projects/iot.thingweb). ## Notes on usage -These definitions are imported using npm. Once we reach conclusion on the API in the W3C Web of Things task force, we will add this to definatelytyped. +These definitions are imported using npm. +Once we reach conclusion on the API in the W3C Web of Things Working Group, it is planned to add them to DefinitelyTyped. ## ES5 targets -As consumers are using typescript we target ES6. -When implementing for ES5 targets, be sure to provide a polyfill for ES6 Promises, either ``es6-promise`` from npm or add the lib ``es2015.promise`` to your tsc command when transpiling typescript. \ No newline at end of file +As consumers are using TypeScript we target ES6. +When implementing for ES5 targets, be sure to provide a polyfill for ES6 Promises, either ``es6-promise`` from npm or add the lib ``es2015.promise`` to your tsc command when transpiling TypeScript. From 4469f65d5ac6b40285d9e9c49f9188847c6c69f5 Mon Sep 17 00:00:00 2001 From: ashimura Date: Mon, 12 Nov 2018 20:43:10 +0900 Subject: [PATCH 268/464] update for publication on nov 12 --- Overview.html | 14 +++++++------- diff.html | 16 ++++++++-------- releases/wd3/Overview.html | 14 +++++++------- releases/wd3/diff.html | 16 ++++++++-------- 4 files changed, 30 insertions(+), 30 deletions(-) diff --git a/Overview.html b/Overview.html index 2f6915b6..6b3b83f5 100644 --- a/Overview.html +++ b/Overview.html @@ -884,7 +884,7 @@ "shortName": "wot-scripting-api", "copyrightStart": 2017, "noLegacyStyle": true, - "publishDate": "2018-10-21", + "publishDate": "2018-11-12", "previousPublishDate": "2018-04-05", "previousMaturity": "", "edDraftURI": "https://w3c.github.io/wot-scripting-api/", @@ -1005,8 +1005,8 @@ "id": "webappsec" } }, - "publishISODate": "2018-10-21T00:00:00.000Z", - "generatedSubtitle": "Workign Draft 21 October 2018" + "publishISODate": "2018-11-12T00:00:00.000Z", + "generatedSubtitle": "Workign Draft 12 November 2018" } Web of Things (WoT) Scripting API

    • W3C Working - Draft

    + Draft

    This version:
    - https://www.w3.org/TR/2018/WD-wot-scripting-api-20181021/ + "https://www.w3.org/TR/2018/WD-wot-scripting-api-20181112/"> + https://www.w3.org/TR/2018/WD-wot-scripting-api-20181112/
    Latest published version:
    diff --git a/diff.html b/diff.html index 2cde3a44..74d28852 100644 --- a/diff.html +++ b/diff.html @@ -899,7 +899,7 @@ "shortName": "wot-scripting-api", "copyrightStart": 2017, "noLegacyStyle": true, - "publishDate": "2018-10-21", + "publishDate": "2018-11-12", "previousPublishDate": "2018-04-05", "previousMaturity": "", "edDraftURI": "https://w3c.github.io/wot-scripting-api/", @@ -1020,8 +1020,8 @@ "id": "webappsec" } }, - "publishISODate": "2018-10-21T00:00:00.000Z", - "generatedSubtitle": "Workign Draft 21 October 2018" + "publishISODate": "2018-11-12T00:00:00.000Z", + "generatedSubtitle": "Workign Draft 12 November 2018" } ]]> @@ -1069,9 +1069,9 @@

    5 April -

    This version:
    - https://www.w3.org/TR/2018/WD-wot-scripting-api-20181021/ + "https://www.w3.org/TR/2018/WD-wot-scripting-api-20181112/"> + https://www.w3.org/TR/2018/WD-wot-scripting-api-20181112/
    Latest published version:
    diff --git a/releases/wd3/diff.html b/releases/wd3/diff.html index 2cde3a44..74d28852 100644 --- a/releases/wd3/diff.html +++ b/releases/wd3/diff.html @@ -899,7 +899,7 @@ "shortName": "wot-scripting-api", "copyrightStart": 2017, "noLegacyStyle": true, - "publishDate": "2018-10-21", + "publishDate": "2018-11-12", "previousPublishDate": "2018-04-05", "previousMaturity": "", "edDraftURI": "https://w3c.github.io/wot-scripting-api/", @@ -1020,8 +1020,8 @@ "id": "webappsec" } }, - "publishISODate": "2018-10-21T00:00:00.000Z", - "generatedSubtitle": "Workign Draft 21 October 2018" + "publishISODate": "2018-11-12T00:00:00.000Z", + "generatedSubtitle": "Workign Draft 12 November 2018" } ]]> @@ -1069,9 +1069,9 @@

    5 April -

    [WOT-TD] -
    +
    WoT Thing Description . W3C. -20 -August -2017. +21 +October +2018. URL: - -https://w3c.github.io/wot-thing-description/ + +https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/
    From 283510ea35d9298772a457142c43edaeb5232328 Mon Sep 17 00:00:00 2001 From: ashimura Date: Mon, 19 Nov 2018 18:29:14 +0900 Subject: [PATCH 271/464] pubdate nov 19 --- Overview.html | 58 +++++++++++----------- releases/wd3/Overview.html | 58 +++++++++++----------- releases/wd3/diff.html | 99 ++++++++++++++++++-------------------- 3 files changed, 106 insertions(+), 109 deletions(-) diff --git a/Overview.html b/Overview.html index 0a91c2d5..89ade4d4 100644 --- a/Overview.html +++ b/Overview.html @@ -884,7 +884,7 @@ "shortName": "wot-scripting-api", "copyrightStart": 2017, "noLegacyStyle": true, - "publishDate": "2018-11-13", + "publishDate": "2018-11-19", "previousPublishDate": "2018-04-05", "previousMaturity": "", "edDraftURI": "https://w3c.github.io/wot-scripting-api/", @@ -1005,8 +1005,8 @@ "id": "webappsec" } }, - "publishISODate": "2018-11-13T00:00:00.000Z", - "generatedSubtitle": "Workign Draft 13 November 2018" + "publishISODate": "2018-11-19T00:00:00.000Z", + "generatedSubtitle": "Workign Draft 19 November 2018" } Web of Things (WoT) Scripting API

    W3C Working - Draft

    This version:
    - https://www.w3.org/TR/2018/WD-wot-scripting-api-20181113/ + "https://www.w3.org/TR/2018/WD-wot-scripting-api-20181119/"> + https://www.w3.org/TR/2018/WD-wot-scripting-api-20181119/
    Latest published version:
    @@ -2506,7 +2506,7 @@

    3.2 "internalDFN" data-link-type="dfn">Thing Description string-serialized from the returned content, as specified in the + "https://w3c.github.io/wot-thing-description/#sec-td-serialization"> Thing Description serialization.
  • If there was an error during the request, reject @@ -2694,7 +2694,7 @@

    1. Parse td according to the + "https://w3c.github.io/wot-thing-description/#sec-td-serialization"> WoT Thing Description in order to produce a JSON @@ -4215,7 +4215,7 @@

      The [WOT-TD] specification defines the + "https://w3c.github.io/wot-thing-description/#sec-vocabulary-definition"> WoT information model, i.e. the data types and data structures used in WoT Interactions. In @@ -4247,7 +4247,7 @@

      "dfn">Action parameters. Value types are represented as dictionary objects whose properties and possible sub-classes are defined in the + "https://w3c.github.io/wot-thing-description/#sec-data-schema-vocabulary-definition"> DataSchema section of [WOT-TD].

      One property of all "dfn">DataSchema dictionary is the type property whose value is from a set of enumerated strings defined in the DataSchema + "https://w3c.github.io/wot-thing-description/#dataschema">DataSchema section of [WOT-TD] and is referred as DataType in @@ -4265,17 +4265,17 @@

      "dfn">DataSchema are defined in [WOT-TD]: BooleanSchema, NumberSchema, IntegerSchema, StringSchema, ObjectSchema, ArraySchema.

      "#the-securityscheme-dictionary-and-its-subclasses">

      Security metadata is represented as dictionary objects whose properties and sub-classes are defined in the + "https://w3c.github.io/wot-thing-description/#sec-security-vocabulary-definition"> SecurityScheme section of [WOT-TD].

      One property of the "dfn">SecurityScheme dictionary is the scheme property whose value is from a set of enumerated strings defined in the + "https://w3c.github.io/wot-thing-description/#securityscheme"> SecurityScheme section of [WOT-TD]. Based on type, multiple subclasses of Represents a Web Link with properties defined in the Link + "https://w3c.github.io/wot-thing-description/#link">Link section of [WOT-TD].

      @@ -4326,7 +4326,7 @@

      Represents metadata describing service details, with properties defined in the Form + "https://w3c.github.io/wot-thing-description/#form">Form section of [WOT-TD].

      @@ -4344,7 +4344,7 @@

      Action or Event, as defined in the + "https://w3c.github.io/wot-thing-description/#interactionpattern"> InteractionPattern section of [WOT-TD]. Its subclasses are referred as ThingProperty object. Its properties are defined in the Property + "https://w3c.github.io/wot-thing-description/#property">Property and + "https://w3c.github.io/wot-thing-description/#interactionpattern"> InteractionPattern sections of [WOT-TD].

      @@ -4388,9 +4388,9 @@

      ThingAction object. Its properties are defined in the Action + "https://w3c.github.io/wot-thing-description/#action">Action and + "https://w3c.github.io/wot-thing-description/#interactionpattern"> InteractionPattern sections of [WOT-TD].

      @@ -4407,7 +4407,7 @@

      ThingEvent object. Its properties are defined in the Event + "https://w3c.github.io/wot-thing-description/#event">Event section of [WOT-TD].

      @@ -4422,7 +4422,7 @@

      The ThingFragment dictionary is defined as Thing + "https://w3c.github.io/wot-thing-description/#thing">Thing in [WOT-TD]. It is a dictionary that contains properties representing semantic metadata and @@ -5534,7 +5534,7 @@

      A. diff --git a/releases/wd3/Overview.html b/releases/wd3/Overview.html index 0a91c2d5..89ade4d4 100644 --- a/releases/wd3/Overview.html +++ b/releases/wd3/Overview.html @@ -884,7 +884,7 @@ "shortName": "wot-scripting-api", "copyrightStart": 2017, "noLegacyStyle": true, - "publishDate": "2018-11-13", + "publishDate": "2018-11-19", "previousPublishDate": "2018-04-05", "previousMaturity": "", "edDraftURI": "https://w3c.github.io/wot-scripting-api/", @@ -1005,8 +1005,8 @@ "id": "webappsec" } }, - "publishISODate": "2018-11-13T00:00:00.000Z", - "generatedSubtitle": "Workign Draft 13 November 2018" + "publishISODate": "2018-11-19T00:00:00.000Z", + "generatedSubtitle": "Workign Draft 19 November 2018" } Web of Things (WoT) Scripting API

      W3C Working - Draft

      This version:
      - https://www.w3.org/TR/2018/WD-wot-scripting-api-20181113/ + "https://www.w3.org/TR/2018/WD-wot-scripting-api-20181119/"> + https://www.w3.org/TR/2018/WD-wot-scripting-api-20181119/
      Latest published version:
      @@ -2506,7 +2506,7 @@

      3.2 "internalDFN" data-link-type="dfn">Thing Description string-serialized from the returned content, as specified in the + "https://w3c.github.io/wot-thing-description/#sec-td-serialization"> Thing Description serialization.

    2. If there was an error during the request, reject @@ -2694,7 +2694,7 @@

      1. Parse td according to the + "https://w3c.github.io/wot-thing-description/#sec-td-serialization"> WoT Thing Description in order to produce a JSON @@ -4215,7 +4215,7 @@

        The [WOT-TD] specification defines the + "https://w3c.github.io/wot-thing-description/#sec-vocabulary-definition"> WoT information model, i.e. the data types and data structures used in WoT Interactions. In @@ -4247,7 +4247,7 @@

        "dfn">Action parameters. Value types are represented as dictionary objects whose properties and possible sub-classes are defined in the + "https://w3c.github.io/wot-thing-description/#sec-data-schema-vocabulary-definition"> DataSchema section of [WOT-TD].

        One property of all "dfn">DataSchema dictionary is the type property whose value is from a set of enumerated strings defined in the DataSchema + "https://w3c.github.io/wot-thing-description/#dataschema">DataSchema section of [WOT-TD] and is referred as DataType in @@ -4265,17 +4265,17 @@

        "dfn">DataSchema are defined in [WOT-TD]: BooleanSchema, NumberSchema, IntegerSchema, StringSchema, ObjectSchema, ArraySchema.

        "#the-securityscheme-dictionary-and-its-subclasses">

        Security metadata is represented as dictionary objects whose properties and sub-classes are defined in the + "https://w3c.github.io/wot-thing-description/#sec-security-vocabulary-definition"> SecurityScheme section of [WOT-TD].

        One property of the "dfn">SecurityScheme dictionary is the scheme property whose value is from a set of enumerated strings defined in the + "https://w3c.github.io/wot-thing-description/#securityscheme"> SecurityScheme section of [WOT-TD]. Based on type, multiple subclasses of Represents a Web Link with properties defined in the Link + "https://w3c.github.io/wot-thing-description/#link">Link section of [WOT-TD].

        @@ -4326,7 +4326,7 @@

        Represents metadata describing service details, with properties defined in the Form + "https://w3c.github.io/wot-thing-description/#form">Form section of [WOT-TD].

        @@ -4344,7 +4344,7 @@

        Action or Event, as defined in the + "https://w3c.github.io/wot-thing-description/#interactionpattern"> InteractionPattern section of [WOT-TD]. Its subclasses are referred as ThingProperty object. Its properties are defined in the Property + "https://w3c.github.io/wot-thing-description/#property">Property and + "https://w3c.github.io/wot-thing-description/#interactionpattern"> InteractionPattern sections of [WOT-TD].

        @@ -4388,9 +4388,9 @@

        ThingAction object. Its properties are defined in the Action + "https://w3c.github.io/wot-thing-description/#action">Action and + "https://w3c.github.io/wot-thing-description/#interactionpattern"> InteractionPattern sections of [WOT-TD].

        @@ -4407,7 +4407,7 @@

        ThingEvent object. Its properties are defined in the Event + "https://w3c.github.io/wot-thing-description/#event">Event section of [WOT-TD].

        @@ -4422,7 +4422,7 @@

        The ThingFragment dictionary is defined as Thing + "https://w3c.github.io/wot-thing-description/#thing">Thing in [WOT-TD]. It is a dictionary that contains properties representing semantic metadata and @@ -5534,7 +5534,7 @@

        A. diff --git a/releases/wd3/diff.html b/releases/wd3/diff.html index ad8e3a20..ac74dbd6 100644 --- a/releases/wd3/diff.html +++ b/releases/wd3/diff.html @@ -899,7 +899,7 @@ "shortName": "wot-scripting-api", "copyrightStart": 2017, "noLegacyStyle": true, - "publishDate": "2018-11-13", + "publishDate": "2018-11-19", "previousPublishDate": "2018-04-05", "previousMaturity": "", "edDraftURI": "https://w3c.github.io/wot-scripting-api/", @@ -1020,8 +1020,8 @@ "id": "webappsec" } }, - "publishISODate": "2018-11-13T00:00:00.000Z", - "generatedSubtitle": "Workign Draft 13 November 2018" + "publishISODate": "2018-11-19T00:00:00.000Z", + "generatedSubtitle": "Workign Draft 19 November 2018" } ]]> @@ -1069,8 +1069,8 @@

        5 April -

        2. -
      2. 6. Experimental extensions @@ -2823,6 +2822,7 @@

        ConsumedThing interface +
      3. 6.1 @@ -2909,9 +2909,9 @@

        The +TDLink -TDLink -dictionary +dictionary

        4. @@ -6231,7 +6231,7 @@

        specified in the - + Thing Description serialization @@ -7372,7 +7372,7 @@

        according to the - + WoT Thing Description @@ -13164,7 +13164,7 @@

        specification defines the - + WoT information model @@ -13322,7 +13322,7 @@

        defined in the - + DataSchema section @@ -13372,7 +13372,7 @@

        defined in the - + DataSchema section @@ -13474,22 +13474,20 @@

        ]: - -BooleanSchema - + 6.1 -, - - -NumberSchema -, + +BooleanSchema +, +NumberSchema +, IntegerSchema -, +, StringSchema -, +, ObjectSchema -, +, ArraySchema .

        6.2 @@ -13538,18 +13536,17 @@

        Thing Description - + SecurityScheme - -section + + +section of [ - + WOT-TD - - - -]. + +].

        One property @@ -13585,7 +13582,7 @@

        the form - + SecurityScheme section @@ -13662,7 +13659,7 @@

      4. If there was an error during the request, reject @@ -2694,7 +2694,7 @@

        1. Parse td according to the + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#sec-td-serialization"> WoT Thing Description in order to produce a JSON @@ -4215,7 +4215,7 @@

          The [WOT-TD] specification defines the + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#sec-vocabulary-definition"> WoT information model, i.e. the data types and data structures used in WoT Interactions. In @@ -4247,7 +4247,7 @@

          "dfn">Action parameters. Value types are represented as dictionary objects whose properties and possible sub-classes are defined in the + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#sec-data-schema-vocabulary-definition"> DataSchema section of [WOT-TD].

          One property of all "dfn">DataSchema dictionary is the type property whose value is from a set of enumerated strings defined in the DataSchema + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#dataschema">DataSchema section of [WOT-TD] and is referred as DataType in @@ -4265,17 +4265,17 @@

          "dfn">DataSchema are defined in [WOT-TD]: BooleanSchema, NumberSchema, IntegerSchema, StringSchema, ObjectSchema, ArraySchema.

          "#the-securityscheme-dictionary-and-its-subclasses">

          Security metadata is represented as dictionary objects whose properties and sub-classes are defined in the + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#sec-security-vocabulary-definition"> SecurityScheme section of [WOT-TD].

          One property of the "dfn">SecurityScheme dictionary is the scheme property whose value is from a set of enumerated strings defined in the + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#securityscheme"> SecurityScheme section of [WOT-TD]. Based on type, multiple subclasses of Represents a Web Link with properties defined in the Link + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#link">Link section of [WOT-TD].

          @@ -4326,7 +4326,7 @@

          Represents metadata describing service details, with properties defined in the Form + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#form">Form section of [WOT-TD].

          @@ -4344,7 +4344,7 @@

          Action or Event, as defined in the + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#interactionpattern"> InteractionPattern section of [WOT-TD]. Its subclasses are referred as ThingProperty object. Its properties are defined in the Property + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#property">Property and + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#interactionpattern"> InteractionPattern sections of [WOT-TD].

          @@ -4388,9 +4388,9 @@

          ThingAction object. Its properties are defined in the Action + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#action">Action and + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#interactionpattern"> InteractionPattern sections of [WOT-TD].

          @@ -4407,7 +4407,7 @@

          ThingEvent object. Its properties are defined in the Event + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#event">Event section of [WOT-TD].

          @@ -4422,7 +4422,7 @@

          The ThingFragment dictionary is defined as Thing + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#thing">Thing in [WOT-TD]. It is a dictionary that contains properties representing semantic metadata and @@ -5534,7 +5534,7 @@

          A. diff --git a/releases/wd3/Overview.html b/releases/wd3/Overview.html index 89ade4d4..ada00521 100644 --- a/releases/wd3/Overview.html +++ b/releases/wd3/Overview.html @@ -2506,7 +2506,7 @@

          3.2 "internalDFN" data-link-type="dfn">Thing Description string-serialized from the returned content, as specified in the + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#sec-td-serialization"> Thing Description serialization.

        2. If there was an error during the request, reject @@ -2694,7 +2694,7 @@

          1. Parse td according to the + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#sec-td-serialization"> WoT Thing Description in order to produce a JSON @@ -4215,7 +4215,7 @@

            The [WOT-TD] specification defines the + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#sec-vocabulary-definition"> WoT information model, i.e. the data types and data structures used in WoT Interactions. In @@ -4247,7 +4247,7 @@

            "dfn">Action parameters. Value types are represented as dictionary objects whose properties and possible sub-classes are defined in the + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#sec-data-schema-vocabulary-definition"> DataSchema section of [WOT-TD].

            One property of all "dfn">DataSchema dictionary is the type property whose value is from a set of enumerated strings defined in the DataSchema + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#dataschema">DataSchema section of [WOT-TD] and is referred as DataType in @@ -4265,17 +4265,17 @@

            "dfn">DataSchema are defined in [WOT-TD]: BooleanSchema, NumberSchema, IntegerSchema, StringSchema, ObjectSchema, ArraySchema.

            "#the-securityscheme-dictionary-and-its-subclasses">

            Security metadata is represented as dictionary objects whose properties and sub-classes are defined in the + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#sec-security-vocabulary-definition"> SecurityScheme section of [WOT-TD].

            One property of the "dfn">SecurityScheme dictionary is the scheme property whose value is from a set of enumerated strings defined in the + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#securityscheme"> SecurityScheme section of [WOT-TD]. Based on type, multiple subclasses of Represents a Web Link with properties defined in the Link + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#link">Link section of [WOT-TD].

            @@ -4326,7 +4326,7 @@

            Represents metadata describing service details, with properties defined in the Form + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#form">Form section of [WOT-TD].

            @@ -4344,7 +4344,7 @@

            Action or Event, as defined in the + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#interactionpattern"> InteractionPattern section of [WOT-TD]. Its subclasses are referred as ThingProperty object. Its properties are defined in the Property + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#property">Property and + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#interactionpattern"> InteractionPattern sections of [WOT-TD].

            @@ -4388,9 +4388,9 @@

            ThingAction object. Its properties are defined in the Action + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#action">Action and + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#interactionpattern"> InteractionPattern sections of [WOT-TD].

            @@ -4407,7 +4407,7 @@

            ThingEvent object. Its properties are defined in the Event + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#event">Event section of [WOT-TD].

            @@ -4422,7 +4422,7 @@

            The ThingFragment dictionary is defined as Thing + "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#thing">Thing in [WOT-TD]. It is a dictionary that contains properties representing semantic metadata and @@ -5534,7 +5534,7 @@

            A. diff --git a/releases/wd3/diff.html b/releases/wd3/diff.html index ac74dbd6..7193dcc6 100644 --- a/releases/wd3/diff.html +++ b/releases/wd3/diff.html @@ -2814,6 +2814,7 @@

            2. +
          2. 6. Experimental extensions @@ -2822,7 +2823,6 @@

            ConsumedThing interface -
          3. 6.1 @@ -2909,9 +2909,9 @@

            The -TDLink -dictionary +TDLink +dictionary

            4. @@ -6231,7 +6231,7 @@

            specified in the - + Thing Description serialization @@ -7372,7 +7372,7 @@

            according to the - + WoT Thing Description @@ -13164,7 +13164,7 @@

            specification defines the - + WoT information model @@ -13322,7 +13322,7 @@

            defined in the - + DataSchema section @@ -13372,7 +13372,7 @@

            defined in the - + DataSchema section @@ -13474,20 +13474,22 @@

            ]: - + +BooleanSchema + 6.1 - -BooleanSchema -, -NumberSchema -, +, + + +NumberSchema +, IntegerSchema -, +, StringSchema -, +, ObjectSchema -, +, ArraySchema .

            6.2 @@ -13536,17 +13538,18 @@

            Thing Description - + SecurityScheme - - -section + +section of [ - + WOT-TD - -]. + + + +].

            One property @@ -13582,7 +13585,7 @@

            the form - + SecurityScheme section @@ -13659,7 +13662,7 @@

          4. C. Acknowledgements + "secno">C. Acknowledgments
          5. 8. "dom-errorhandler" data-idl="callback" data-title= "ErrorHandler">ErrorHandler callback takes an error in the value argument. It is called - when an error occured in producing the data the client should + when an error occurred in producing the data the client should know about.
          6. The

            C. - Acknowledgements

            Special thanks to former editor Johannes Hund (until August 2017, when at Siemens AG) for developing this specification. diff --git a/releases/wd3/Overview.html b/releases/wd3/Overview.html index ada00521..8594aac3 100644 --- a/releases/wd3/Overview.html +++ b/releases/wd3/Overview.html @@ -1676,7 +1676,7 @@

            Table of

          7. C. Acknowledgements + "secno">C. Acknowledgments
          8. 8. "dom-errorhandler" data-idl="callback" data-title= "ErrorHandler">ErrorHandler callback takes an error in the value argument. It is called - when an error occured in producing the data the client should + when an error occurred in producing the data the client should know about.
          9. The

            C. - Acknowledgements

            Special thanks to former editor Johannes Hund (until August 2017, when at Siemens AG) for developing this specification. diff --git a/releases/wd3/diff.html b/releases/wd3/diff.html index 7193dcc6..f533d2dd 100644 --- a/releases/wd3/diff.html +++ b/releases/wd3/diff.html @@ -2814,7 +2814,6 @@

            10. -
          10. 6. Experimental extensions @@ -2823,6 +2822,7 @@

            ConsumedThing interface +
          11. 6.1 @@ -2909,9 +2909,9 @@

            The +TDLink -TDLink -dictionary +dictionary

            12. @@ -3028,7 +3028,10 @@

            C. -Acknowledgements +Acknowledgements + +Acknowledgments +

          12. @@ -14276,24 +14279,24 @@

            PropertyFragment , ActionFragment - + and - - -EventFragment - + +EventFragment + dictionaries used for initializing - + ThingProperty -, +, ThingAction - + and - -ThingEvent + + +ThingEvent objects in @@ -16261,7 +16264,10 @@

            when an error -occured +occured + +occurred + in producing the @@ -18685,9 +18691,10 @@

            C. -Acknowledgements - - +Acknowledgements + +Acknowledgments +

            Special From 5fe72f05524963d45fdab812dc8de4a5e32c849e Mon Sep 17 00:00:00 2001 From: ashimura Date: Mon, 19 Nov 2018 21:45:05 +0900 Subject: [PATCH 274/464] HTML52 instead of HTML5 --- Overview.html | 23 +-- diff.html | 279 +++++++++++++++++-------------------- releases/wd3/Overview.html | 23 +-- releases/wd3/diff.html | 159 +++++++++------------ 4 files changed, 219 insertions(+), 265 deletions(-) diff --git a/Overview.html b/Overview.html index 8594aac3..3cbfd680 100644 --- a/Overview.html +++ b/Overview.html @@ -5360,7 +5360,7 @@

            URL path are defined in [URL].

            The following terms are defined in [HTML5] and are used in the context + href="#bib-html52">HTML52] and are used in the context of browser implementations: browsing @@ -5475,7 +5475,7 @@

            hyperlink reference and relation type are defined in [HTML5] and HTML52] and RFC8288.

            @@ -5595,15 +5595,20 @@

            https://www.w3.org/TR/encoding/

    • -
    [HTML5]
    +
    [HTML52]
    HTML5. - Ian Hickson; Robin Berjon; Steve Faulkner; Travis - Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia - Pfeiffer. W3C. 27 March 2018. W3C Recommendation. URL: - https://www.w3.org/TR/html5/ + "https://www.w3.org/TR/html52/">HTML 5.2. + Steve Faulkner; + Arron Eicholz; + Travis Leithead; + Alex Danilo; + Sangwhan Moon; + Erika Doyle Navara; + Theresa O'Connor; + Robin Berjon. + W3C. 14 December 2017. W3C Recommendation. URL: + https://www.w3.org/TR/html52/
    [JSON-LD]
    diff --git a/diff.html b/diff.html index d7ba7edf..cea49001 100644 --- a/diff.html +++ b/diff.html @@ -899,7 +899,7 @@ "shortName": "wot-scripting-api", "copyrightStart": 2017, "noLegacyStyle": true, - "publishDate": "2018-11-13", + "publishDate": "2018-11-19", "previousPublishDate": "2018-04-05", "previousMaturity": "", "edDraftURI": "https://w3c.github.io/wot-scripting-api/", @@ -966,10 +966,10 @@ "id": "wot-architecture" }, "WOT-TD": { - "href": "https://w3c.github.io/wot-thing-description/", + "href": "https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/", "title": "WoT Thing Description ", "publisher": "W3C", - "date": "20 August 2017", + "date": "21 October 2018", "id": "wot-td" }, "WOT-PROTOCOL-BINDINGS": { @@ -1020,8 +1020,8 @@ "id": "webappsec" } }, - "publishISODate": "2018-11-13T00:00:00.000Z", - "generatedSubtitle": "Workign Draft 13 November 2018" + "publishISODate": "2018-11-19T00:00:00.000Z", + "generatedSubtitle": "Workign Draft 19 November 2018" } ]]> @@ -1069,8 +1069,8 @@

    5 April -

    method -5.19 -Examples interface -6. +
  • +5.19 +Examples +6. Experimental extensions to @@ -2822,7 +2823,6 @@

    ConsumedThing interface -
  • 6.1 @@ -2909,9 +2909,9 @@

    The -TDLink -dictionary +TDLink +dictionary

    • @@ -3028,7 +3028,10 @@

    C. -Acknowledgements +Acknowledgements + +Acknowledgments +

  • @@ -6231,7 +6234,7 @@

    specified in the - + Thing Description serialization @@ -7372,7 +7375,7 @@

    according to the - + WoT Thing Description @@ -10748,19 +10751,19 @@

    with name defined + by -the - +the + name - + argument, the data schema provided - by -the +the property @@ -12712,21 +12715,21 @@

    it rejects with - + error -, -then +, +then reject - + promise - + with the same - + error -, -otherwise +, +otherwise if it @@ -13164,7 +13167,7 @@

    specification defines the - + WoT information model @@ -13322,7 +13325,7 @@

    defined in the - + DataSchema section @@ -13372,7 +13375,7 @@

    defined in the - + DataSchema section @@ -13474,20 +13477,22 @@

    ]: - + +BooleanSchema + 6.1 - -BooleanSchema -, -NumberSchema -, +, + + +NumberSchema +, IntegerSchema -, +, StringSchema -, +, ObjectSchema -, +, ArraySchema .

    6.2 @@ -13536,7 +13541,7 @@

    Thing Description - + SecurityScheme @@ -13582,7 +13587,7 @@

    the form - + SecurityScheme section @@ -13659,7 +13664,7 @@

    • -[HTML52] - -
    -[HTML5] - +
    +[HTML52]
    - + -HTML +HTML 5.2 - -HTML5 - . -Ian -Hickson; -Robin -Berjon; - Steve Faulkner; -Arron +Arron Eicholz; - Travis Leithead; -Alex +Alex Danilo; Sangwhan Moon; - Erika Doyle Navara; Theresa O'Connor; -Robin +Robin Berjon. - -Silvia -Pfeiffer. - W3C. -14 +14 December 2017. - -27 -March -2018. - W3C Recommendation. URL: -https://www.w3.org/TR/html52/ - - -https://www.w3.org/TR/html5/ - + +https://www.w3.org/TR/html52/
    @@ -19085,19 +19062,19 @@

    https://github.com/w3c/wot-security/blob/master/wot-security-testing.md
    [WOT-TD] -
    +

    WoT Thing Description . W3C. -20 -August -2017. +21 +October +2018. URL: - -https://w3c.github.io/wot-thing-description/ + +https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/
    diff --git a/releases/wd3/Overview.html b/releases/wd3/Overview.html index 8594aac3..3cbfd680 100644 --- a/releases/wd3/Overview.html +++ b/releases/wd3/Overview.html @@ -5360,7 +5360,7 @@

    URL path are defined in [URL].

    The following terms are defined in [HTML5] and are used in the context + href="#bib-html52">HTML52] and are used in the context of browser implementations: browsing @@ -5475,7 +5475,7 @@

    hyperlink reference and relation type are defined in [HTML5] and HTML52] and RFC8288.

    @@ -5595,15 +5595,20 @@

    https://www.w3.org/TR/encoding/ -
    [HTML5]
    +
    [HTML52]
    HTML5. - Ian Hickson; Robin Berjon; Steve Faulkner; Travis - Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia - Pfeiffer. W3C. 27 March 2018. W3C Recommendation. URL: - https://www.w3.org/TR/html5/ + "https://www.w3.org/TR/html52/">HTML 5.2. + Steve Faulkner; + Arron Eicholz; + Travis Leithead; + Alex Danilo; + Sangwhan Moon; + Erika Doyle Navara; + Theresa O'Connor; + Robin Berjon. + W3C. 14 December 2017. W3C Recommendation. URL: + https://www.w3.org/TR/html52/
    [JSON-LD]
    diff --git a/releases/wd3/diff.html b/releases/wd3/diff.html index f533d2dd..cea49001 100644 --- a/releases/wd3/diff.html +++ b/releases/wd3/diff.html @@ -2807,14 +2807,15 @@

    method -5.19 -Examples interface -6. +
  • +5.19 +Examples +6. Experimental extensions to @@ -2822,7 +2823,6 @@

    ConsumedThing interface -
  • 6.1 @@ -2909,9 +2909,9 @@

    The -TDLink -dictionary +TDLink +dictionary

    • @@ -10751,19 +10751,19 @@

    with name defined + by -the - +the + name - + argument, the data schema provided - by -the +the property @@ -12715,21 +12715,21 @@

    it rejects with - + error -, -then +, +then reject - + promise - + with the same - + error -, -otherwise +, +otherwise if it @@ -13543,16 +13543,15 @@

    SecurityScheme - -section + + +section of [ - + WOT-TD - - - -]. + +].

    One property @@ -14100,8 +14099,9 @@

    Thing Description - -s + + +s are represented as @@ -14135,10 +14135,8 @@

    [ WOT-TD - - - -] + +] are extended by @@ -14546,20 +14544,20 @@

    href ThingProperty - -interface + + + +interface contains all the properties defined on - + PropertyFragment - - - -as + +as read-only properties.

    @@ -14930,31 +14928,30 @@

    provided. Otherwise the - type -of - +of + inputValue - + SHOULD - + match the - + DataSchema - + definition in the - + input - + property. Returns a - + Promise - + that will reject @@ -14968,8 +14965,9 @@

    a value of + type -defined +defined by the @@ -17772,11 +17770,8 @@

    in [ -HTML52 - - -HTML5 - + +HTML52 ] @@ -18163,11 +18158,8 @@

    in [ -HTML52 - - -HTML5 - + +HTML52 ] @@ -18804,67 +18796,42 @@

    https://www.w3.org/TR/encoding/

    • -[HTML52] - -
    -[HTML5] - +
    +[HTML52]
    - + -HTML +HTML 5.2 - -HTML5 - . -Ian -Hickson; -Robin -Berjon; - Steve Faulkner; -Arron +Arron Eicholz; - Travis Leithead; -Alex +Alex Danilo; Sangwhan Moon; - Erika Doyle Navara; Theresa O'Connor; -Robin +Robin Berjon. - -Silvia -Pfeiffer. - W3C. -14 +14 December 2017. - -27 -March -2018. - W3C Recommendation. URL: -https://www.w3.org/TR/html52/ - - -https://www.w3.org/TR/html5/ - + +https://www.w3.org/TR/html52/
    From f9238eda6d7593491b03c8295c2697e0cf1982dc Mon Sep 17 00:00:00 2001 From: ashimura Date: Thu, 29 Nov 2018 13:33:10 +0900 Subject: [PATCH 275/464] pubdate nov 29 --- Overview.html | 93 ++++++++++++++++++++++---------------- releases/wd3/Overview.html | 93 ++++++++++++++++++++++---------------- releases/wd3/diff.html | 12 ++--- 3 files changed, 116 insertions(+), 82 deletions(-) diff --git a/Overview.html b/Overview.html index 3cbfd680..50470a78 100644 --- a/Overview.html +++ b/Overview.html @@ -1005,8 +1005,8 @@ "id": "webappsec" } }, - "publishISODate": "2018-11-19T00:00:00.000Z", - "generatedSubtitle": "Workign Draft 19 November 2018" + "publishISODate": "2018-11-29T00:00:00.000Z", + "generatedSubtitle": "Workign Draft 29 November 2018" } Web of Things (WoT) Scripting API

    W3C Working - Draft

    This version:
    - https://www.w3.org/TR/2018/WD-wot-scripting-api-20181119/ + "https://www.w3.org/TR/2018/WD-wot-scripting-api-20181129/"> + https://www.w3.org/TR/2018/WD-wot-scripting-api-20181129/
    Latest published version:
    @@ -5361,44 +5361,61 @@

    URL].

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

    + serialized origin, + + executing algorithms + + + in parallel, + + + queue a task, + + + task source, + + + iframe, + + + valid MIME type.

    +

    A browsing context refers to the environment in which Web of Things (WoT) Scripting API

    W3C Working - Draft

    This version:
    - https://www.w3.org/TR/2018/WD-wot-scripting-api-20181119/ + "https://www.w3.org/TR/2018/WD-wot-scripting-api-20181129/"> + https://www.w3.org/TR/2018/WD-wot-scripting-api-20181129/
    Latest published version:
    @@ -5361,44 +5361,61 @@

    URL].

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

    + serialized origin, + + executing algorithms + + + in parallel, + + + queue a task, + + + task source, + + + iframe, + + + valid MIME type.

    +

    A browsing context refers to the environment in which @@ -1069,8 +1069,8 @@

    5 April -

    https://www.w3.org/TR/2018/WD-wot-scripting-api-20180405/ - -https://www.w3.org/TR/2018/WD-wot-scripting-api-20181119/ + +https://www.w3.org/TR/2018/WD-wot-scripting-api-20181129/
    From 962ca6f5f6d48c478d5762bd925f072e9e4d3dd3 Mon Sep 17 00:00:00 2001 From: ashimura Date: Thu, 29 Nov 2018 13:54:55 +0900 Subject: [PATCH 276/464] use HTML5.2 instead of whatwg living standard --- Overview.html | 32 +++---- releases/wd3/Overview.html | 32 +++---- releases/wd3/diff.html | 181 ++++++++++++++++++------------------- 3 files changed, 122 insertions(+), 123 deletions(-) diff --git a/Overview.html b/Overview.html index 50470a78..3c5bbaf5 100644 --- a/Overview.html +++ b/Overview.html @@ -5028,7 +5028,7 @@

    8. class="internalDFN" data-link-type= "dfn">subscribe(EventHandler handler, +"https://www.w3.org/TR/html52/single-page.html#typedefdef-eventhandler">EventHandler handler, optional HTML52] and are used in the context of browser implementations: - + browsing context, - + top-level browsing context, - + global object, - + incumbent settings object, - + Document, - + document base URL, - + Window, - + WindowProxy, - + origin, - + ASCII serialized origin, executing algorithms - + in parallel, - + queue a task, - + task source, - + iframe, - + valid MIME type.

    A 8. class="internalDFN" data-link-type= "dfn">subscribe(EventHandler handler, +"https://www.w3.org/TR/html52/single-page.html#typedefdef-eventhandler">EventHandler handler, optional HTML52] and are used in the context of browser implementations: - + browsing context, - + top-level browsing context, - + global object, - + incumbent settings object, - + Document, - + document base URL, - + Window, - + WindowProxy, - + origin, - + ASCII serialized origin, executing algorithms - + in parallel, - + queue a task, - + task source, - + iframe, - + valid MIME type.

    A method +5.19 +Examples interface -

  • -5.19 -Examples -6. +6. Experimental extensions to @@ -2823,6 +2822,7 @@

    ConsumedThing interface +
  • 6.1 @@ -2900,17 +2900,17 @@

    The getLinks() -method -6.4.1 value-matching algorithm -The +method -TDLink +6.4.1 +The +TDLink dictionary @@ -5752,26 +5752,26 @@

    previous steps, invoke - the - -handler - + +handler + function with - + td - + as parameter. -

  • +
  • Whenever an error occurs during + the -discovery +discovery process, and if @@ -10751,19 +10751,19 @@

    with name defined - by -the - +the + name - + argument, the data schema provided + by -the +the property @@ -12715,21 +12715,21 @@

    it rejects with - + error -, -then +, +then reject - + promise - + with the same - + error -, -otherwise +, +otherwise if it @@ -13250,24 +13250,13 @@

    ThingDescription DataSchema - - - -dictionary + +dictionary and its subclasses - - -related -functionality, -such -as -enumerating - -

    -

    -Value +

    +Value types basically represent @@ -13288,8 +13277,16 @@

    in ThingFragment - -to + + + +related +functionality, +such +as +enumerating + +to define Properties @@ -13543,15 +13540,16 @@

    SecurityScheme - - -section + +section of [ - + WOT-TD - -]. + + + +].

    One property @@ -14099,9 +14097,8 @@

    Thing Description - - -s + +s are represented as @@ -14135,8 +14132,10 @@

    [ WOT-TD - -] + + + +] are extended by @@ -14277,24 +14276,24 @@

    PropertyFragment , ActionFragment - + and - -EventFragment - + + +EventFragment + dictionaries used for initializing - + ThingProperty -, +, ThingAction - + and - - -ThingEvent + +ThingEvent objects in @@ -16011,7 +16010,7 @@

    "dfn"> or <a href="#dom-onnext" class= "idlParam">EventHandler handler, +"https://www.w3.org/TR/html52/single-page.html#typedefdef-eventhandler">EventHandler handler, optional of browser implementations: - + browsing context , - - + + top-level browsing context , - + global object , - + incumbent settings object , - + Document , - + document base URL , - - + + Window , - - + + WindowProxy , - - + + origin , - + ASCII serialized @@ -17846,32 +17845,32 @@

    , executing algorithms - - + + in parallel , - - + + queue a task , - - + + task source , - + iframe , - - + + valid MIME type From 8349c1eed01a9abae821634ddd207debc0ca3e7c Mon Sep 17 00:00:00 2001 From: ashimura Date: Thu, 29 Nov 2018 13:58:44 +0900 Subject: [PATCH 277/464] use HTML5.2 instead of whatwg living standard --- Overview.html | 4 +-- releases/wd3/Overview.html | 4 +-- releases/wd3/diff.html | 54 +++++++++++++++++++------------------- 3 files changed, 31 insertions(+), 31 deletions(-) diff --git a/Overview.html b/Overview.html index 3c5bbaf5..fbf7c457 100644 --- a/Overview.html +++ b/Overview.html @@ -5360,7 +5360,7 @@

    URL path are defined in [URL].

    The following terms are defined in [HTML52] and are used in the context + href="#bib-HTML52">HTML52] and are used in the context of browser implementations: @@ -5492,7 +5492,7 @@

    hyperlink reference and relation type are defined in [HTML52] and HTML52] and RFC8288.

    • diff --git a/releases/wd3/Overview.html b/releases/wd3/Overview.html index 3c5bbaf5..fbf7c457 100644 --- a/releases/wd3/Overview.html +++ b/releases/wd3/Overview.html @@ -5360,7 +5360,7 @@

    URL path are defined in [URL].

    The following terms are defined in [HTML52] and are used in the context + href="#bib-HTML52">HTML52] and are used in the context of browser implementations: @@ -5492,7 +5492,7 @@

    hyperlink reference and relation type are defined in [HTML52] and HTML52] and RFC8288.

    diff --git a/releases/wd3/diff.html b/releases/wd3/diff.html index 4644ff50..5ac85b93 100644 --- a/releases/wd3/diff.html +++ b/releases/wd3/diff.html @@ -13540,16 +13540,15 @@

    SecurityScheme - -section + + +section of [ - + WOT-TD - - - -]. + +].

    One property @@ -14121,8 +14120,11 @@

    WoT Interactions -

    -The + + +

    +

    +The data types and @@ -14132,10 +14134,8 @@

    [ WOT-TD - - - -] + +] are extended by @@ -14927,30 +14927,31 @@

    provided. Otherwise the + type -of - +of + inputValue - + SHOULD - + match the - + DataSchema - + definition in the - + input - + property. Returns a - + Promise - + that will reject @@ -14964,9 +14965,8 @@

    a value of - type -defined +defined by the @@ -17769,7 +17769,7 @@

    in [ - + HTML52 @@ -18157,7 +18157,7 @@

    in [ - + HTML52 From b75d6288cc53aaa42100d0ecf479d2131331866b Mon Sep 17 00:00:00 2001 From: ashimura Date: Thu, 29 Nov 2018 14:01:37 +0900 Subject: [PATCH 278/464] Changes at Appendix A --- Overview.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Overview.html b/Overview.html index fbf7c457..10558477 100644 --- a/Overview.html +++ b/Overview.html @@ -1184,7 +1184,7 @@

    Status of This Document

    "mailto:public-wot-wg@w3.org">public-wot-wg@w3.org (archives).

    Changes from the previous publication can be found in - Appendix B. A Appendix A. A diff-marked version of this document is also available for comparison purposes.

    Publication as a Working Draft does not imply endorsement by From b27f0ef37a4fb852fde9d972355481bbac223748 Mon Sep 17 00:00:00 2001 From: ashimura Date: Thu, 29 Nov 2018 14:03:56 +0900 Subject: [PATCH 279/464] Changes at Appendix A --- releases/wd3/Overview.html | 2 +- releases/wd3/diff.html | 43 ++++++++++++++++++-------------------- 2 files changed, 21 insertions(+), 24 deletions(-) diff --git a/releases/wd3/Overview.html b/releases/wd3/Overview.html index fbf7c457..10558477 100644 --- a/releases/wd3/Overview.html +++ b/releases/wd3/Overview.html @@ -1184,7 +1184,7 @@

    Status of This Document

    "mailto:public-wot-wg@w3.org">public-wot-wg@w3.org (archives).

    Changes from the previous publication can be found in - Appendix B. A Appendix A. A diff-marked version of this document is also available for comparison purposes.

    Publication as a Working Draft does not imply endorsement by diff --git a/releases/wd3/diff.html b/releases/wd3/diff.html index 5ac85b93..bc8cd453 100644 --- a/releases/wd3/diff.html +++ b/releases/wd3/diff.html @@ -1704,12 +1704,9 @@

    be found in - + Appendix -A - -B - +A . A @@ -2814,6 +2811,7 @@

    +
  • 6. Experimental extensions @@ -2822,7 +2820,6 @@

    ConsumedThing interface -
  • 6.1 @@ -2900,17 +2897,17 @@

    The getLinks() +method +6.4.1 value-matching algorithm -method +The -6.4.1 -The -TDLink +TDLink dictionary @@ -13540,15 +13537,16 @@

    SecurityScheme - - -section + +section of [ - + WOT-TD - -]. + + + +].

    One property @@ -14120,11 +14118,8 @@

    WoT Interactions - - -

    -

    -The +

    • +The data types and @@ -14134,8 +14129,10 @@

    [ WOT-TD - -] + + + +] are extended by From ef5c52d11329705f46609b48933f2de419e5fa9a Mon Sep 17 00:00:00 2001 From: ashimura Date: Thu, 29 Nov 2018 14:06:57 +0900 Subject: [PATCH 280/464] add how to subscribe the group list --- Overview.html | 3 ++- releases/wd3/Overview.html | 3 ++- releases/wd3/diff.html | 16 ++++++++-------- 3 files changed, 12 insertions(+), 10 deletions(-) diff --git a/Overview.html b/Overview.html index 10558477..82d39d42 100644 --- a/Overview.html +++ b/Overview.html @@ -1182,7 +1182,8 @@

    Status of This Document

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

    + (subscribe, + archives).

    Changes from the previous publication can be found in Appendix A. A diff-marked version of this document is also diff --git a/releases/wd3/Overview.html b/releases/wd3/Overview.html index 10558477..82d39d42 100644 --- a/releases/wd3/Overview.html +++ b/releases/wd3/Overview.html @@ -1182,7 +1182,8 @@

    Status of This Document

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

    + (subscribe, + archives).

    Changes from the previous publication can be found in Appendix A. A diff-marked version of this document is also diff --git a/releases/wd3/diff.html b/releases/wd3/diff.html index bc8cd453..5c109772 100644 --- a/releases/wd3/diff.html +++ b/releases/wd3/diff.html @@ -1686,9 +1686,9 @@

    public-wot-wg@w3.org ( -subscribe -, - + +subscribe +, archives @@ -10748,19 +10748,19 @@

    with name defined + by -the - +the + name - + argument, the data schema provided - by -the +the property From 99f741a37d225f5b20d675da7758cf46ba14b098 Mon Sep 17 00:00:00 2001 From: ashimura Date: Thu, 29 Nov 2018 15:38:52 +0900 Subject: [PATCH 281/464] update diff.html --- diff.html | 214 +++++++++++++++++++++++++++--------------------------- 1 file changed, 105 insertions(+), 109 deletions(-) diff --git a/diff.html b/diff.html index cea49001..5c109772 100644 --- a/diff.html +++ b/diff.html @@ -1020,8 +1020,8 @@ "id": "webappsec" } }, - "publishISODate": "2018-11-19T00:00:00.000Z", - "generatedSubtitle": "Workign Draft 19 November 2018" + "publishISODate": "2018-11-29T00:00:00.000Z", + "generatedSubtitle": "Workign Draft 29 November 2018" } ]]> @@ -1069,8 +1069,8 @@

    5 April -

    be found in - + Appendix -A - -B - +A . A @@ -2807,15 +2804,15 @@

    method +5.19 +Examples interface

  • -5.19 -Examples -6. +6. Experimental extensions to @@ -5752,26 +5749,26 @@

    previous steps, invoke - the - -handler - + +handler + function with - + td - + as parameter. -

  • +
  • Whenever an error occurs during + the -discovery +discovery process, and if @@ -12715,21 +12712,21 @@

    it rejects with - + error -, -then +, +then reject - + promise - + with the same - + error -, -otherwise +, +otherwise if it @@ -13250,24 +13247,13 @@

    ThingDescription DataSchema - - - -dictionary + +dictionary and its subclasses - - -related -functionality, -such -as -enumerating - -

    -

    -Value +

    +Value types basically represent @@ -13288,8 +13274,16 @@

    in ThingFragment - -to + + + +related +functionality, +such +as +enumerating + +to define Properties @@ -13543,15 +13537,16 @@

    SecurityScheme - - -section + +section of [ - + WOT-TD - -]. + + + +].

    One property @@ -14099,9 +14094,8 @@

    Thing Description - - -s + +s are represented as @@ -14135,8 +14129,10 @@

    [ WOT-TD - -] + + + +] are extended by @@ -14277,24 +14273,24 @@

    PropertyFragment , ActionFragment - + and - -EventFragment - + + +EventFragment + dictionaries used for initializing - + ThingProperty -, +, ThingAction - + and - - -ThingEvent + +ThingEvent objects in @@ -14928,30 +14924,31 @@

    provided. Otherwise the + type -of - +of + inputValue - + SHOULD - + match the - + DataSchema - + definition in the - + input - + property. Returns a - + Promise - + that will reject @@ -14965,9 +14962,8 @@

    a value of - type -defined +defined by the @@ -16011,7 +16007,7 @@

    "dfn"> or <a href="#dom-onnext" class= "idlParam">EventHandler handler, +"https://www.w3.org/TR/html52/single-page.html#typedefdef-eventhandler">EventHandler handler, optional in [ - + HTML52 @@ -17784,60 +17780,60 @@

    of browser implementations: - + browsing context , - - + + top-level browsing context , - + global object , - + incumbent settings object , - + Document , - + document base URL , - - + + Window , - - + + WindowProxy , - - + + origin , - + ASCII serialized @@ -17846,32 +17842,32 @@

    , executing algorithms - - + + in parallel , - - + + queue a task , - - + + task source , - + iframe , - - + + valid MIME type @@ -18158,7 +18154,7 @@

    in [ - + HTML52 From cb0b365b83230f3a4477cbc04e7c6f5b26983045 Mon Sep 17 00:00:00 2001 From: ashimura Date: Thu, 29 Nov 2018 16:06:02 +0900 Subject: [PATCH 282/464] add data-editor-id --- Overview.html | 8 +-- diff.html | 138 +++++++++++++++++++------------------ releases/wd3/Overview.html | 8 +-- releases/wd3/diff.html | 138 +++++++++++++++++++------------------ 4 files changed, 150 insertions(+), 142 deletions(-) diff --git a/Overview.html b/Overview.html index 82d39d42..60d57b03 100644 --- a/Overview.html +++ b/Overview.html @@ -1046,22 +1046,22 @@

    W3C Working https://www.w3.org/TR/2018/WD-wot-scripting-api-20180405/
    Editors:
    -
    +
    Zoltan Kis (Intel)
    -
    +
    Kazuaki Nimura (Fujitsu Ltd.)
    -
    +
    Daniel Peintner (Siemens AG)
    -
    Johannes Hund (Former Editor, when at Siemens AG)
    Contributors:
    diff --git a/diff.html b/diff.html index 5c109772..dd07b8ae 100644 --- a/diff.html +++ b/diff.html @@ -1124,42 +1124,42 @@

    Editors:
    -
    +
    Zoltan Kis ( - + Intel )
    -
    +
    Kazuaki Nimura ( - + Fujitsu Ltd. )
    -
    +
    Daniel Peintner ( - + Siemens AG )
    -
    +
    Johannes Hund @@ -5749,26 +5749,26 @@

    previous steps, invoke + the - -handler - + +handler + function with - + td - + as parameter. -

  • +
  • Whenever an error occurs during - the -discovery +discovery process, and if @@ -10748,19 +10748,19 @@

    with name defined - by -the - +the + name - + argument, the data schema provided + by -the +the property @@ -12712,21 +12712,21 @@

    it rejects with - + error -, -then +, +then reject - + promise - + with the same - + error -, -otherwise +, +otherwise if it @@ -13247,13 +13247,24 @@

    ThingDescription DataSchema - -dictionary + + + +dictionary and its subclasses -

    -Value + + +related +functionality, +such +as +enumerating + +

    +

    +Value types basically represent @@ -13274,16 +13285,8 @@

    in ThingFragment - - - -related -functionality, -such -as -enumerating - -to + +to define Properties @@ -13537,16 +13540,15 @@

    SecurityScheme - -section + + +section of [ - + WOT-TD - - - -]. + +].

    One property @@ -14118,8 +14120,13 @@

    WoT Interactions -

    -The + + + + +

    +

    +The data types and @@ -14129,10 +14136,8 @@

    [ WOT-TD - - - -] + +] are extended by @@ -14254,30 +14259,29 @@

    Properties , Actions - + and - -Events -.

    + +Events +.

    The - + InteractionFragment - + dictionary holds the common properties of - + PropertyFragment -, +, ActionFragment - + and - - -EventFragment + +EventFragment dictionaries used diff --git a/releases/wd3/Overview.html b/releases/wd3/Overview.html index 82d39d42..60d57b03 100644 --- a/releases/wd3/Overview.html +++ b/releases/wd3/Overview.html @@ -1046,22 +1046,22 @@

    W3C Working https://www.w3.org/TR/2018/WD-wot-scripting-api-20180405/
    Editors:
    -
    +
    Zoltan Kis (Intel)
    -
    +
    Kazuaki Nimura (Fujitsu Ltd.)
    -
    +
    Daniel Peintner (Siemens AG)
    -
    Johannes Hund (Former Editor, when at Siemens AG)
    Contributors:
    diff --git a/releases/wd3/diff.html b/releases/wd3/diff.html index 5c109772..dd07b8ae 100644 --- a/releases/wd3/diff.html +++ b/releases/wd3/diff.html @@ -1124,42 +1124,42 @@

    Editors:
    -
    +
    Zoltan Kis ( - + Intel )
    -
    +
    Kazuaki Nimura ( - + Fujitsu Ltd. )
    -
    +
    Daniel Peintner ( - + Siemens AG )
    -
    +
    Johannes Hund @@ -5749,26 +5749,26 @@

    previous steps, invoke + the - -handler - + +handler + function with - + td - + as parameter. -

  • +
  • Whenever an error occurs during - the -discovery +discovery process, and if @@ -10748,19 +10748,19 @@

    with name defined - by -the - +the + name - + argument, the data schema provided + by -the +the property @@ -12712,21 +12712,21 @@

    it rejects with - + error -, -then +, +then reject - + promise - + with the same - + error -, -otherwise +, +otherwise if it @@ -13247,13 +13247,24 @@

    ThingDescription DataSchema - -dictionary + + + +dictionary and its subclasses -

    -Value + + +related +functionality, +such +as +enumerating + +

    +

    +Value types basically represent @@ -13274,16 +13285,8 @@

    in ThingFragment - - - -related -functionality, -such -as -enumerating - -to + +to define Properties @@ -13537,16 +13540,15 @@

    SecurityScheme - -section + + +section of [ - + WOT-TD - - - -]. + +].

    One property @@ -14118,8 +14120,13 @@

    WoT Interactions -

    -The + + + + +

    +

    +The data types and @@ -14129,10 +14136,8 @@

    [ WOT-TD - - - -] + +] are extended by @@ -14254,30 +14259,29 @@

    Properties , Actions - + and - -Events -.

    + +Events +.

    The - + InteractionFragment - + dictionary holds the common properties of - + PropertyFragment -, +, ActionFragment - + and - - -EventFragment + +EventFragment dictionaries used From b60c9c6d1421c569ec706f861c9d354a5b88617f Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Tue, 8 Jan 2019 08:47:17 +0100 Subject: [PATCH 283/464] fix TS issue "Cannot find name 'USVString'" by replacing USVString with string --- typescript/index.d.ts | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index fd1ac128..b40905ff 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -19,7 +19,7 @@ export interface WoTFactory { * Accepts an url argument and returns a Promise of a ThingDescription * @param url URL of a thing description */ - fetch(url: USVString): Promise; + fetch(url: string): Promise; /** * Accepts a ThingDescription and returns a ConsumedThing @@ -37,11 +37,11 @@ export interface WoTFactory { /** * Make a request to register td to the given WoT Thing Directory.. */ - register(directory: USVString, thing: ExposedThing): Promise; + register(directory: string, thing: ExposedThing): Promise; /** * Makes a request to unregister the thing from the given WoT Thing Directory. */ - unregister(directory: USVString, thing: ExposedThing): Promise; + unregister(directory: string, thing: ExposedThing): Promise; } /** @@ -55,11 +55,11 @@ export interface ThingFilter { /** * The url field represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, such as a Thing Directory or a Thing. */ - url?: USVString; + url?: string; /** * The query field represents a query string accepted by the implementation, for instance a SPARQL query. */ - query?: USVString; + query?: string; /** * The fragment field represents a ThingFragment dictionary used for matching against discovered Things. */ @@ -82,7 +82,7 @@ export declare enum DiscoveryMethod { * WoT provides a unified representation for data exchange between Things, standardized in the Wot Things Description specification. * In this version of the API, Thing Descriptions are represented as opaque strings, denoting a serialized form, for instance JSON or JSON-LD */ -export declare type ThingDescription = USVString; +export declare type ThingDescription = string; /** * The ThingFragment dictionary contains fields to initialize a Thing or to match during discovery @@ -292,17 +292,17 @@ export declare type PropertyWriteHandler = (value: any) => Promise; export declare type ActionHandler = (parameters: any) => Promise; export interface Link { - href: USVString; - rel?: USVString | Array; - type?: USVString; // media type hint, no media type parameters - anchor?: USVString; + href: string; + rel?: string | Array; + type?: string; // media type hint, no media type parameters + anchor?: string; } export interface Form { - href: USVString; - subprotocol?: USVString; - op?: USVString | Array; - contentType?: USVString; // media type + parameter(s), e.g., text/plain;charset=utf8 + href: string; + subprotocol?: string; + op?: string | Array; + contentType?: string; // media type + parameter(s), e.g., text/plain;charset=utf8 security?: Security; } From f039e55b71778fc05ab52d71383d8c3d15bef355 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Tue, 8 Jan 2019 09:04:58 +0100 Subject: [PATCH 284/464] align with TD Security changes * SecurityScheme: rename proxyURI to proxy * Rename APIKeySecurityScheme to ApikeySecurityScheme * BearerSecurityScheme: add attribute authorization * CertSecurityScheme: missing * Rename PskScheme to PSKSecurityScheme and add attribute identity * PublicSecurityScheme: missing * Rename PopSecurityScheme to PoPSecurityScheme * OAuth2SecurityScheme: add attributes token and refresh --- typescript/index.d.ts | 51 ++++++++++++++++++++++++++--------------- typescript/package.json | 2 +- 2 files changed, 34 insertions(+), 19 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index b40905ff..3a3c88c1 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -351,13 +351,13 @@ export interface NullSchema extends BaseSchema { type: "null"; } -export type Security = NoSecurityScheme | BasicSecurityScheme | DigestSecurityScheme | BearerSecurityScheme | PopSecurityScheme | ApikeySecurityScheme | OAuth2SecurityScheme | PskScheme; +export type Security = NoSecurityScheme | BasicSecurityScheme | DigestSecurityScheme | BearerSecurityScheme | CertSecurityScheme | PoPSecurityScheme | APIKeySecurityScheme | OAuth2SecurityScheme | PSKSecurityScheme | PublicSecurityScheme; export interface SecurityScheme { scheme: string; description?: string; - proxyURI?: any; + proxy?: string; } export interface NoSecurityScheme extends SecurityScheme { @@ -372,41 +372,56 @@ export interface BasicSecurityScheme extends SecurityScheme { export interface DigestSecurityScheme extends SecurityScheme { scheme: "digest"; + name?: string; + in?: string; qop?: string; +} + +export interface APIKeySecurityScheme extends SecurityScheme { + scheme: "apikey"; in?: string; name?: string; } export interface BearerSecurityScheme extends SecurityScheme { scheme: "bearer"; + in?: string; alg?: string; format?: string; - in?: string; name?: string; + authorization?: string; } -export interface PopSecurityScheme extends SecurityScheme { - scheme: "pop"; - alg?: string; - format?: string; - in?: string; - name?: string; +export interface CertSecurityScheme extends SecurityScheme { + scheme: "cert"; + identity?: string; } -export interface ApikeySecurityScheme extends SecurityScheme { - scheme: "apikey"; - in: string; +export interface PSKSecurityScheme extends SecurityScheme { + scheme: "psk"; + identity?: string; +} + +export interface PublicSecurityScheme extends SecurityScheme { + scheme: "public"; + identity?: string; +} + +export interface PoPSecurityScheme extends SecurityScheme { + scheme: "pop"; + format?: string; + authorization?: string; + alg?: string; name?: string; + in?: string; } export interface OAuth2SecurityScheme extends SecurityScheme { scheme: "oauth2"; - authorizationUrl: string; + authorization?: string; + flow?: string; // one of implicit, password, client, or code + token?: string; + refresh?: string; scopes?: Array; - // one of implicit, password, client, or code - flow: string; } -export interface PskScheme extends SecurityScheme { - scheme: "psk"; -} diff --git a/typescript/package.json b/typescript/package.json index 163fc541..cfa03373 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.6.0-SNAPSHOT.2", + "version": "0.6.0-SNAPSHOT.3", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From ddddc2443382087c3d7e9da3f3f45a267b16c78e Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Tue, 8 Jan 2019 15:29:41 +0100 Subject: [PATCH 285/464] further TD spec alignments change writable to readOnly and writeOnly add MultiLanguage term for titles and descriptions add safe and idempotent to Action --- typescript/index.d.ts | 25 +++++++++++++++++++++---- typescript/package.json | 2 +- 2 files changed, 22 insertions(+), 5 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index 3a3c88c1..611e2929 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -94,6 +94,8 @@ export interface ThingFragment { name?: string; /** A human-readable description of the Thing */ description?: string; + /** Human-readable descriptions in different languages */ + descriptions?: MultiLanguage; /** Information about the Thing maintainer, e.g., author or contact URI */ support?: string; @@ -122,8 +124,12 @@ export declare type ThingModel = (ThingDescription | ThingFragment); export interface InteractionFragment { /** A human-readable title for the Interaction, e.g., for UIs */ title?: string; + /** Human-readable titles for the Interaction, in different languages */ + titles?: MultiLanguage; /** A human-readable description of the Interaction */ description?: string; + /** Human-readable descriptions in different languages */ + descriptions?: MultiLanguage; /** * A collection of predicate terms that reference values of any type, * e.g., @type, or other terms from the vocabulary defined in @context. @@ -132,14 +138,15 @@ export interface InteractionFragment { } /** Represents a Thing Property description */ -export interface PropertyFragment extends InteractionFragment { - writable?: boolean; +export interface PropertyFragment extends InteractionFragment, BaseSchema { observable?: boolean; } /** Represents a Thing Action description */ export interface ActionFragment extends InteractionFragment { input?: DataSchema; output?: DataSchema; + safe?: boolean; + idempotent?: boolean; } /** Represents a Thing Event description */ export interface EventFragment extends InteractionFragment { @@ -306,10 +313,20 @@ export interface Form { security?: Security; } +export declare type MultiLanguage = any; // object? + export type DataSchema = BooleanSchema | IntegerSchema | NumberSchema | StringSchema | ObjectSchema | ArraySchema | NullSchema; export interface BaseSchema { type?: string; + title?: string; + titles?: MultiLanguage; + description?: string; + descriptions?: MultiLanguage; + writeOnly?: boolean; + readOnly?: boolean; + oneOf?: Array; + unit?: string; const?: any; enum?: Array; } @@ -336,7 +353,7 @@ export interface StringSchema extends BaseSchema { export interface ObjectSchema extends BaseSchema { type: "object"; - properties: { [key:string]: DataSchema }; + properties: { [key: string]: DataSchema }; required?: Array; } @@ -351,7 +368,7 @@ export interface NullSchema extends BaseSchema { type: "null"; } -export type Security = NoSecurityScheme | BasicSecurityScheme | DigestSecurityScheme | BearerSecurityScheme | CertSecurityScheme | PoPSecurityScheme | APIKeySecurityScheme | OAuth2SecurityScheme | PSKSecurityScheme | PublicSecurityScheme; +export type Security = NoSecurityScheme | BasicSecurityScheme | DigestSecurityScheme | BearerSecurityScheme | CertSecurityScheme | PoPSecurityScheme | APIKeySecurityScheme | OAuth2SecurityScheme | PSKSecurityScheme | PublicSecurityScheme; export interface SecurityScheme { diff --git a/typescript/package.json b/typescript/package.json index cfa03373..580be491 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.6.0-SNAPSHOT.3", + "version": "0.6.0-SNAPSHOT.4", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From 0302f38dc2a5eedab7d8af33db42ba68b0565e51 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Mon, 14 Jan 2019 11:17:24 +0100 Subject: [PATCH 286/464] fix: add missing TypeScript terms (scopes,response) and fix terms (security) in Form Interface add required ExpectedResponse interface --- typescript/index.d.ts | 8 +++++++- typescript/package.json | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index 611e2929..9f2f0dea 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -305,12 +305,18 @@ export interface Link { anchor?: string; } +export interface ExpectedResponse { + contentType?: string; +} + export interface Form { href: string; subprotocol?: string; op?: string | Array; contentType?: string; // media type + parameter(s), e.g., text/plain;charset=utf8 - security?: Security; + security?: Array; // Set of security definition names, chosen from those defined in securityDefinitions // Security; + scopes?: Array; + response?: ExpectedResponse; } export declare type MultiLanguage = any; // object? diff --git a/typescript/package.json b/typescript/package.json index 580be491..7fe2479a 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.6.0-SNAPSHOT.4", + "version": "0.6.0-SNAPSHOT.5", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From cd6023c8cb3cc6211cf443696e2e5396174e86bf Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Thu, 17 Jan 2019 10:19:17 +0100 Subject: [PATCH 287/464] update definitions: add forms to top-level, fix security definitions, add base, lastModified, .. --- typescript/index.d.ts | 23 ++++++++++++++++++++--- typescript/package.json | 2 +- 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index 9f2f0dea..0c43e378 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -84,6 +84,11 @@ export declare enum DiscoveryMethod { */ export declare type ThingDescription = string; +/** Carries version information about the TD instance. If required, additional version information such as firmware and hardware version (term definitions outside of the TD namespace) can be extended here. */ +export interface Versioning { + instance?: string; +} + /** * The ThingFragment dictionary contains fields to initialize a Thing or to match during discovery */ @@ -92,15 +97,25 @@ export interface ThingFragment { id?: string; /** The name attribute represents the user given name of the Thing */ name?: string; + /** Define the base URI that is valid for all defined local interaction resources */ + base?: string; /** A human-readable description of the Thing */ description?: string; /** Human-readable descriptions in different languages */ descriptions?: MultiLanguage; /** Information about the Thing maintainer, e.g., author or contact URI */ support?: string; - - /** A list of security schemas used by the Thing */ - security?: Array; + /** Provides information when the TD instance was last modified */ + lastModified?: string; + /** Provides information when the TD instance was created */ + created?: string; + /** Provides version information */ + version?: Versioning; + + /** Set of named security configurations (definitions only). Not actually applied unless names are used in a security section */ + securityDefinitions?: { [key: string]: Security } + /** Set of security definition names, chosen from those defined in securityDefinitions. */ + security?: Array; /** A map of PropertyFragments with decriptions only */ properties?: { [key: string]: PropertyFragment } @@ -110,6 +125,8 @@ export interface ThingFragment { events?: { [key: string]: EventFragment } /** A list of Web links to other Things or metadata */ links?: Array; + /** Indicates one or more endpoints at which operation(s) on this resource are accessible */ + forms?: Array; /** * A collection of predicate terms that reference values of any type, * e.g., @context, @type, or other terms from the vocabulary defined in @context. diff --git a/typescript/package.json b/typescript/package.json index 7fe2479a..1a6dbd26 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.6.0-SNAPSHOT.5", + "version": "0.6.0-SNAPSHOT.6", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From 252bc55a7f1e96333843e6fbc41d167ac37bf2d0 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Thu, 17 Jan 2019 14:47:48 +0200 Subject: [PATCH 288/464] Add appendix for WebIDL index Signed-off-by: Zoltan Kis --- index.html | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/index.html b/index.html index da5cbadd..7b490e1c 100644 --- a/index.html +++ b/index.html @@ -1756,6 +1756,10 @@

    The Observable interface

    +
    + +
    +

    Acknowledgements

    Special thanks to former editor Johannes Hund (until August 2017, when at Siemens AG) for developing this specification. Also, the editors would like to thank Dave Raggett, Matthias Kovatsch, Michael Koster and Michael McCool for their comments and guidance. From 3957b6ae9f6ddb702d09f22bce7436660cd9c353 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 23 Jan 2019 14:00:12 +0100 Subject: [PATCH 289/464] fix: add scopes, uriVariables, and security terms to InteractionFragment (TypeScript definitions) --- typescript/index.d.ts | 7 +++++++ typescript/package.json | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index 0c43e378..7957355a 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -147,6 +147,13 @@ export interface InteractionFragment { description?: string; /** Human-readable descriptions in different languages */ descriptions?: MultiLanguage; + /** Set of authorization scope identifiers */ + scopes?: Array; + /** URI template variables */ + uriVariables?: DataSchema; + /** Set of security definition names */ + security?: Array; + /** * A collection of predicate terms that reference values of any type, * e.g., @type, or other terms from the vocabulary defined in @context. diff --git a/typescript/package.json b/typescript/package.json index 1a6dbd26..e6c3524e 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.6.0-SNAPSHOT.6", + "version": "0.6.0-SNAPSHOT.7", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From aa46bf14d17174a11894cc89d901d1430192672a Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Tue, 29 Jan 2019 13:39:14 +0100 Subject: [PATCH 290/464] feat: add (experimental) support for passing options to property.read()/write() and action.invoke() (e.g., for uriVariables) --- typescript/index.d.ts | 6 +++--- typescript/package.json | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index 7957355a..d4ece93d 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -209,13 +209,13 @@ export interface ThingInteraction extends InteractionFragment { /** Represents an interactable Thing Property */ export interface ThingProperty extends ThingInteraction, PropertyFragment //, Observable { - read(): Promise; - write(value: any): Promise; + read(options?: any): Promise; + write(value: any, options?: any): Promise; subscribe(next?: (value: any) => void, error?: (error: any) => void, complete?: () => void): Subscription; } /** Represents an interactable Thing Action */ export interface ThingAction extends ThingInteraction, ActionFragment { - invoke(parameter?: any): Promise; + invoke(parameter?: any, options?: any): Promise; } /** Represents an interactable Thing Event */ diff --git a/typescript/package.json b/typescript/package.json index e6c3524e..16436d3b 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.6.0-SNAPSHOT.7", + "version": "0.6.0-SNAPSHOT.8", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From 21e2e3a9caa53585cc6f0330e73186bf6c042c59 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Tue, 29 Jan 2019 15:22:38 +0100 Subject: [PATCH 291/464] feat: add options to handlers also --- typescript/index.d.ts | 6 +++--- typescript/package.json | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index d4ece93d..efb4ab56 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -314,13 +314,13 @@ export interface ExposedThing extends ThingInstance { // TODO: Decide if decorator (with 'internal') or replacement (without 'internal') for get() // For now decorator in node-wot -export declare type PropertyReadHandler = (internal?: any) => Promise; +export declare type PropertyReadHandler = (internal?: any, options?: any) => Promise; // TODO: Decide if decorator (return any) or replacement (return void) for set() // For now decorator in node-wot -export declare type PropertyWriteHandler = (value: any) => Promise; +export declare type PropertyWriteHandler = (value: any, options?: any) => Promise; -export declare type ActionHandler = (parameters: any) => Promise; +export declare type ActionHandler = (parameters: any, options?: any) => Promise; export interface Link { href: string; diff --git a/typescript/package.json b/typescript/package.json index 16436d3b..92b371df 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.6.0-SNAPSHOT.8", + "version": "0.6.0-SNAPSHOT.9", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From 4296f81403c1e6ac01a31783ea3c48fca59c1a22 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Tue, 29 Jan 2019 16:07:31 +0100 Subject: [PATCH 292/464] fix: uriVariables is not of type DataSchema. Instead it is of map of DataSchema --- typescript/index.d.ts | 2 +- typescript/package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index efb4ab56..bf3d1a33 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -150,7 +150,7 @@ export interface InteractionFragment { /** Set of authorization scope identifiers */ scopes?: Array; /** URI template variables */ - uriVariables?: DataSchema; + uriVariables?: { [key: string]: DataSchema }; /** Set of security definition names */ security?: Array; diff --git a/typescript/package.json b/typescript/package.json index 92b371df..a27d980c 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.6.0-SNAPSHOT.9", + "version": "0.6.0-SNAPSHOT.10", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From efa4c6221a75467b66b948c254dd4ff70fb5fa00 Mon Sep 17 00:00:00 2001 From: Reshetova Date: Mon, 12 Nov 2018 09:17:20 +0200 Subject: [PATCH 293/464] Rewriting S&P section without normative statements --- index.html | 272 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 157 insertions(+), 115 deletions(-) diff --git a/index.html b/index.html index da5cbadd..4ae57dc8 100644 --- a/index.html +++ b/index.html @@ -1480,133 +1480,175 @@

    The Observable interface

    A detailed discussion of security and privacy considerations for the Web of Things, including a threat model that can be adapted to various circumstances, is presented in the informative document [[!WOT-SECURITY-CONSIDERATIONS]]. - This section includes only normative recommendations relevant to - the WoT Thing Description. -

    + This section discusses only security and privacy risks and possible mitigations + directly relevant to the scripts and WoT Scripting API. +

    -

    +

    When designing new devices and services for use with the WoT, - we have documented a set of best practices - in [[!WOT-SECURITY-BEST-PRACTICES]] that SHOULD be followed. + we have documented a suggested set of best practices + in [[!WOT-SECURITY-BEST-PRACTICES]] to improve security. This best-practices document may be updated as security measures evolve. Following these practices does not guarantee security, but it at least will help to avoid common known vulnerabilities and pitfalls.

    +

    + In addition to describing security and privacy risks relevant for + script developers in + Scripts Security and Privacy Risks, + WoT Scripting Runtime Security and Privacy Risks also presets the risks relevant + for the WoT Scripting Runtime itself, since both are important to take into + consideration while building an overall WoT software stack. + A suggested mitigation for each risk is also proposed. +

    -

    Below are specific recommendations related to WoT runtime implementations: -

      -
    • In basic WoT setups, all scripts running inside the WoT runtime are considered trusted, and - therefore there is no strong need to perform strict isolation between each running script instance. - However, depending on device capabilities and deployment use case scenario risk level it might be - desirable to do so. -
        -
      • For example, if one script handles sensitive privacy-related data and well-audited, - it might be desirable to separate it from the rest of the script instances to minimize the risk of data - exposure in case some other script inside WoT gets compromised during the runtime. - - Therefore the WoT runtime SHOULD perform isolation of script instances and their data in cases - when scripts handle privacy-related or other critical security data. - -
        • -
      • - Another example is mutual co-existence of different tenants on a single WoT device. In this case each - WoT runtime instance will be hosting a different tenant, and isolation between them is required. - - Therefore the WoT runtime SHOULD perform isolation of WoT runtime instances and their data if - a WoT device has more than one tenant. - -
        • -
      - Such isolation can be performed within the WoT Runtime using platform security mechanisms - available on the device. For more information see Section "WoT Servient Single-Tenant" and - "WoT Servient Multi-Tenant" of [[!WOT-SECURITY-CONSIDERATIONS]]. -
      • - -
    • WoT scripts are using WoT Scripting API to implement the functionality and logic for WoT Things. - In addition to providing the isolation between script and runtime instances, the WoT runtime needs - to protect the underlying physical device from potentially misbehaving WoT scripts. - - Therefore the WoT Runtime SHOULD avoid directly exposing the native device interfaces - to the script developers. - - Instead a WoT Runtime should provide a hardware abstraction layer for accessing the native device - interfaces. Additionally, in order to reduce the damage to a physical WoT device in cases a WoT - script gets compromised, it is important to minimize the number of interfaces that are exposed or - accessible to a particular WoT script based on its functionality. - - Therefore the WoT Runtime SHOULD only expose a minimal set of interfaces to a WoT script based - on its intended functionality. - -
      • -
    • If the WoT runtime supports post-manufacturing provisioning or update of WoT scripts, WoT runtime - or any related data (including security credentials), it can be a major attack vector. An attacker - can try to modify any above described part during the update or provisioning process or simply - provision attacker's code and data directly. - - Therefore, if WoT Runtime supports post-manufacturing provisioning or update of WoT scripts, WoT - runtime or any related data, such operations SHOULD be done in a secure fashion. - - A set of recommendations for secure update and post-manufacturing provisioning can be found in - [[!WOT-SECURITY-BEST-PRACTICES]]. -
      • -
    • Typically the WoT runtime needs to store the security credentials that are provisioned to a WoT - device to operate in WoT network. The confidentiality or integrity of these credentials should not - be compromised. - - Therefore the WoT runtime SHOULD securely store the provisioned security credentials, - guaranteeing their integrity and confidentiality. - - - In case there are more than one tenant on a single WoT-enabled device, a WoT Runtime SHOULD - guarantee isolation of each tenant provisioned security credentials. - - Additionally, in order to minimize a risk that provisioned security credentials get compromised, - the WoT runtime should not have any way for WoT scripts to query these credentials. - - Therefore, the WoT Runtime SHOULD NOT expose any API for WoT scripts to query the provisioned - security credentials. - -
      • -
    +

    Scripts Security and Privacy Risks

    +

    This section contains specific risks relevant for script developers.

    -

    Some additional specific recommendations relevant for WoT script developers: -

      -
    • A typical way to compromise any process is to send it a corrupted input via one of the exposed - interfaces. - - Therefore developers SHOULD perform validation on all WoT script inputs, including - fuzzing. - - There are many tool and techniques in existence to do such validation. - More details can be found in [[!WOT-SECURITY-TESTING]]. +
      +
      Corrupted Input Security and Privacy Risk
      +

      + A typical way to compromise any process is to send it a corrupted input via one of the exposed + interfaces. This can be done to a script instance using WoT interface it exposes. +

      +
      Mitigation:
      + Developers should perform validation on all script inputs. + In addition to input validation, + fuzzing should be used + to verify that the input processing is done correctly. + There are many tools and techniques in existence to do such validation. + More details can be found in [[!WOT-SECURITY-TESTING]]. +
      +
      -
      • -
    • As any software, complex scripts with a lot of functionality presents a higher risk of - development mistakes. Such scripts are also hard to verify and test appropriately. - - Therefore developers SHOUD minimize the functionality and complexity of WoT scripts. - -
      • -
    • If a WoT script performs a heavy functional processing on received requests before the request - is authenticated, it presents a great risk for Denial-Of-Service (DOS) attacks. - - Therefore WoT scripts SHOULD avoid heavy functional processing without prior successful - authentication of requestor. - - The set of recommended authentication mechanisms can be found in [[!WOT-SECURITY-BEST-PRACTICES]]. -
      • -
    • WoT developers should remember that a content of a TD can change, including its identified, id, - which is not an immutable identifier. - - Therefore WoT scripts SHOULD use the provided WoT script API to subscribe for notifications - on TD changes. - -
      • -
    +
    +
    Denial Of Service Security Risk
    +

    + If a script performs a heavy functional processing on received requests before the request + is authenticated, it presents a great risk for Denial-Of-Service (DOS) attacks. +

    +
    Mitigation:
    + Scripts should avoid heavy functional processing without prior successful + authentication of requestor. The set of recommended authentication mechanisms + can be found in [[!WOT-SECURITY-BEST-PRACTICES]]. +
    +
    + +
    +
    Stale TD Security Risk
    +

    + During the lifetime of a WoT network, a content of a TD can change. + This includes its identifier, + id, which may not be an immutable one and updated periodically. +

    +
    Mitigation:
    + Scripts should use the provided script API to subscribe for notifications + on TD changes and do not rely on TD values to remain persistent. +
    +

    + While stale TDs can present a potential problem for WoT network operation, + it might not be a security risk. +

    +
    +
    + +

    WoT Scripting Runtime Security and Privacy Risks

    +

    This section contains specific risks relevant for the WoT Scripting Runtime itself. + While the following risks are strictly speaking out of the scope + for the WoT Scripting API, a script needs a secure runtime to + execute and therefore we present these risks and recommended mitigations here.

    -
    + +
    +
    Cross-Script Security and Privacy Risk
    +

    + In basic WoT setups, all scripts running inside the WoT Scripting Runtime + are considered trusted, and therefore there is no strong need to + perform strict isolation between each running script instance. + However, depending on device capabilities and deployment use case + scenario risk level it might be desirable to do so. + For example, if one script handles sensitive privacy-related + data and well-audited, it might be desirable to separate it + from the rest of the script instances to minimize the risk of data + exposure in case some other script inside WoT gets compromised during runtime. + Another example is mutual co-existence of different tenants on a + single WoT device. In this case each WoT Scripting Runtime instance will + be hosting a different tenant, and isolation between them is required. +

    +
    Mitigation:
    + The WoT Scripting Runtime should perform isolation of script instances and + their data in cases when scripts handle privacy-related or other + critical security data. Similarly, the WoT Scripting Runtime + should perform isolation of WoT Scripting Runtime instances and their data + if a WoT device has more than one tenant. + Such isolation can be performed within the WoT Scripting Runtime using + platform security mechanisms available on the device. For more + information see Sections "WoT Servient Single-Tenant" and + "WoT Servient Multi-Tenant" of [[!WOT-SECURITY-CONSIDERATIONS]]. +
    +
    + +
    +
    Physical Device Direct Access Security and Privacy Risk
    +

    + In case a script is compromised or misbehaving, the underlying physical device + (and potentially surrounded environment) can be damaged if a script can use directly exposed + native device interfaces. If such interfaces lack safety checks on their inputs, they might + bring the underlying physical device (or environment) to an unsafe state + (i.e. device overheats and explodes). +

    +
    Mitigation:
    + The WoT Scripting Runtime should avoid directly exposing the native device interfaces + to the script developers. Instead a WoT Scripting Runtime should provide a hardware abstraction + layer for accessing the native device interfaces. Such hardware abstraction layer should + refuse to execute commands that might put the device (or environment) to an unsafe state. + Additionally, in order to reduce the damage to a physical WoT device in cases a script + gets compromised, it is important to minimize the number of interfaces that are exposed + or accessible to a particular script based on its functionality. +
    +
    + +
    +
    Provisioning and Update Security Risk
    +

    + If the WoT Scripting Runtime supports post-manufacturing provisioning + or updates of scripts, WoT Scripting Runtime or any related data + (including security credentials), it can be a major attack vector. + An attacker can try to modify any above described element + during the update or provisioning process or simply + provision attacker's code and data directly. +

    +
    Mitigation:
    + Post-manufacturing provisioning or update of scripts, + WoT Scripting Runtime or any related data should be done in a secure fashion. + A set of recommendations for secure update and post-manufacturing + provisioning can be found in [[!WOT-SECURITY-CONSIDERATIONS]]. +
    +
    + +
    +
    Security Credentials Storage Security and Privacy Risk
    +

    + Typically the WoT Scripting Runtime needs to store the security credentials that are provisioned to a WoT + device to operate in WoT network. If an attacker can compromise the confidentiality or integrity + of these credentials, then it can obtain access to the WoT assets, impersonate WoT things or devices + or create Denial-Of-Service (DoS) attacks. +

    +
    Mitigation:
    + The WoT Scripting Runtime should securely store the provisioned security credentials, + guaranteeing their integrity and confidentiality. + In case there are more than one tenant on a single WoT-enabled device, a WoT Scripting Runtime should + guarantee isolation of each tenant provisioned security credentials. + Additionally, in order to minimize a risk that provisioned security credentials get compromised, + the WoT Scripting Runtime should not expose any API for scripts to query the provisioned + security credentials. +
    +
    +
    + +

    Terminology and conventions

    From e3978d3eb3b901c6d0817867aa27e50fca15bb99 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Thu, 14 Feb 2019 09:41:52 +0100 Subject: [PATCH 294/464] refactor: get ready for node-wot release 0.6.0 --- typescript/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/typescript/package.json b/typescript/package.json index a27d980c..0a4a2ae9 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.6.0-SNAPSHOT.10", + "version": "0.6.0", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From 004be7d8cbb32db604b7188f40166cd8768bb14a Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Thu, 14 Feb 2019 10:29:04 +0100 Subject: [PATCH 295/464] refactor: update to node-wot 0.7.0-SNAPSHOT.1 --- typescript/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/typescript/package.json b/typescript/package.json index 0a4a2ae9..6cca2fc6 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.6.0", + "version": "0.7.0-SNAPSHOT.1", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From f28b22124bcda13729f1334d5bd4a099f8e66db4 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Thu, 14 Feb 2019 22:18:51 +0200 Subject: [PATCH 296/464] Reorganize the Security section Signed-off-by: Zoltan Kis --- index.html | 291 +++++++++++++++++++++++++---------------------------- 1 file changed, 135 insertions(+), 156 deletions(-) diff --git a/index.html b/index.html index 6a66822e..2a53f1a9 100644 --- a/index.html +++ b/index.html @@ -1393,12 +1393,12 @@

    The ThingAction interface

  • Return true. +

    • -
    @@ -1473,182 +1473,161 @@

    The Observable interface

    Security and Privacy

    -

    - In general the security measures taken to protect a WoT - system will depend on the threats and attackers that system - may face and the value of the assets needs to protect. - A detailed discussion of security and privacy considerations for the Web of Things, - including a threat model that can be adapted to various circumstances, is - presented in the informative document [[!WOT-SECURITY-CONSIDERATIONS]]. - This section discusses only security and privacy risks and possible mitigations - directly relevant to the scripts and WoT Scripting API. -

    -

    - When designing new devices and services for use with the WoT, - we have documented a suggested set of best practices - in [[!WOT-SECURITY-BEST-PRACTICES]] to improve security. - This best-practices document may be updated as security measures evolve. - Following these practices does not guarantee security, - but it at least will help to avoid common known vulnerabilities and pitfalls. + A detailed discussion of security and privacy considerations for the Web of Things, including a threat model that can be adapted to various circumstances, is + presented in the informative document [[!WOT-SECURITY-CONSIDERATIONS]]. + This section discusses only security and privacy risks and possible mitigations + directly relevant to the scripts and WoT Scripting API.

    - In addition to describing security and privacy risks relevant for - script developers in - Scripts Security and Privacy Risks, - WoT Scripting Runtime Security and Privacy Risks also presets the risks relevant - for the WoT Scripting Runtime itself, since both are important to take into - consideration while building an overall WoT software stack. - A suggested mitigation for each risk is also proposed. + A suggested set of best practices to improve security for WoT devices and + services has been documented in [[!WOT-SECURITY-BEST-PRACTICES]]. + That document may be updated as security measures evolve. + Following these practices does not guarantee security, + but it might help avoid common known vulnerabilities.

    -

    Scripts Security and Privacy Risks

    -

    This section contains specific risks relevant for script developers. +

    + The WoT security risks and possible mitigations are concerning the following groups: +

      +
    • + Implementors of WoT Runtimes that do not implement a Scripting Runtime. + The [[!WOT-ARCHITECTURE]] document provides generic security guidelines + for this group. +
      • +
    • + Implementors of the WoT Scripting API in a WoT Scripting Runtime. This is the main scope and is covered in the + + Scripting Runtime Security and Privacy Risks sub-section that + contains normative text regarding security. +
      • +
    • + WoT script developers, covered in the + + Script Security and Privacy Risks sub-section that contains + informative recommendations concerning security. +
      • +

    -
    -
    Corrupted Input Security and Privacy Risk
    -

    - A typical way to compromise any process is to send it a corrupted input via one of the exposed - interfaces. This can be done to a script instance using WoT interface it exposes. +

    +

    Scripting Runtime Security and Privacy Risks

    +

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

    -
    Mitigation:
    - Developers should perform validation on all script inputs. - In addition to input validation, - fuzzing should be used - to verify that the input processing is done correctly. - There are many tools and techniques in existence to do such validation. - More details can be found in [[!WOT-SECURITY-TESTING]]. -
    -
    -
    -
    Denial Of Service Security Risk
    -

    - If a script performs a heavy functional processing on received requests before the request - is authenticated, it presents a great risk for Denial-Of-Service (DOS) attacks. -

    -
    Mitigation:
    - Scripts should avoid heavy functional processing without prior successful - authentication of requestor. The set of recommended authentication mechanisms - can be found in [[!WOT-SECURITY-BEST-PRACTICES]]. -
    -
    +
    +

    Corrupted Input Security and Privacy Risk

    +

    + A typical way to compromise any process is to send it a corrupted input + via one of the exposed interfaces. This can be done to a script instance + using WoT interface it exposes. +

    +
    Mitigation:
    + Implementors of this API SHOULD perform validation on all script inputs. + In addition to input validation, + fuzzing should be used + to verify that the input processing is done correctly. + There are many tools and techniques in existence to do such validation. + More details can be found in [[!WOT-SECURITY-TESTING]]. +
    +
    -
    -
    Stale TD Security Risk
    -

    - During the lifetime of a WoT network, a content of a TD can change. - This includes its identifier, - id, which may not be an immutable one and updated periodically. -

    -
    Mitigation:
    - Scripts should use the provided script API to subscribe for notifications - on TD changes and do not rely on TD values to remain persistent. -
    -

    - While stale TDs can present a potential problem for WoT network operation, - it might not be a security risk. -

    -
    -
    -

    WoT Scripting Runtime Security and Privacy Risks

    -

    This section contains specific risks relevant for the WoT Scripting Runtime itself. - While the following risks are strictly speaking out of the scope - for the WoT Scripting API, a script needs a secure runtime to - execute and therefore we present these risks and recommended mitigations here. -

    +
    +

    Physical Device Direct Access Security and Privacy Risk

    +

    + In case a script is compromised or misbehaving, the underlying physical device + (and potentially surrounded environment) can be damaged if a script can use directly exposed native device interfaces. If such interfaces lack safety checks on their inputs, they might bring the underlying physical device (or environment) to an unsafe state (i.e. device overheats and explodes). +

    +
    Mitigation:
    + The WoT Scripting Runtime SHOULD avoid directly exposing the native device interfaces to the script developers. Instead, a WoT Scripting Runtime should provide a hardware abstraction layer for accessing the native device interfaces. Such hardware abstraction layer should refuse to execute commands that might put the device (or environment) to an unsafe state. + Additionally, in order to reduce the damage to a physical WoT device in cases a script gets compromised, it is important to minimize the number of interfaces that are exposed or accessible to a particular script based on its functionality. +
    +
    -
    -
    Cross-Script Security and Privacy Risk
    -

    - In basic WoT setups, all scripts running inside the WoT Scripting Runtime - are considered trusted, and therefore there is no strong need to - perform strict isolation between each running script instance. - However, depending on device capabilities and deployment use case - scenario risk level it might be desirable to do so. - For example, if one script handles sensitive privacy-related - data and well-audited, it might be desirable to separate it - from the rest of the script instances to minimize the risk of data - exposure in case some other script inside WoT gets compromised during runtime. - Another example is mutual co-existence of different tenants on a - single WoT device. In this case each WoT Scripting Runtime instance will - be hosting a different tenant, and isolation between them is required. -

    -
    Mitigation:
    - The WoT Scripting Runtime should perform isolation of script instances and - their data in cases when scripts handle privacy-related or other - critical security data. Similarly, the WoT Scripting Runtime - should perform isolation of WoT Scripting Runtime instances and their data - if a WoT device has more than one tenant. - Such isolation can be performed within the WoT Scripting Runtime using - platform security mechanisms available on the device. For more - information see Sections "WoT Servient Single-Tenant" and - "WoT Servient Multi-Tenant" of [[!WOT-SECURITY-CONSIDERATIONS]]. -
    -
    +
    +

    Provisioning and Update Security Risk

    +

    + If the WoT Scripting Runtime supports post-manufacturing provisioning + or updates of scripts, WoT Scripting Runtime or any related data + (including security credentials), it can be a major attack vector. + An attacker can try to modify any above described element + during the update or provisioning process or simply + provision attacker's code and data directly. +

    +
    Mitigation:
    + Post-manufacturing provisioning or update of scripts, + WoT Scripting Runtime or any related data should be done in a secure fashion. + A set of recommendations for secure update and post-manufacturing + provisioning can be found in [[!WOT-SECURITY-CONSIDERATIONS]]. +
    +
    -
    -
    Physical Device Direct Access Security and Privacy Risk
    -

    - In case a script is compromised or misbehaving, the underlying physical device - (and potentially surrounded environment) can be damaged if a script can use directly exposed - native device interfaces. If such interfaces lack safety checks on their inputs, they might - bring the underlying physical device (or environment) to an unsafe state - (i.e. device overheats and explodes). -

    -
    Mitigation:
    - The WoT Scripting Runtime should avoid directly exposing the native device interfaces - to the script developers. Instead a WoT Scripting Runtime should provide a hardware abstraction - layer for accessing the native device interfaces. Such hardware abstraction layer should - refuse to execute commands that might put the device (or environment) to an unsafe state. - Additionally, in order to reduce the damage to a physical WoT device in cases a script - gets compromised, it is important to minimize the number of interfaces that are exposed - or accessible to a particular script based on its functionality. -
    +
    +

    Security Credentials Storage Security and Privacy Risk

    +

    + Typically the WoT Scripting Runtime needs to store the security credentials that are provisioned to a WoT device to operate in WoT network. If an attacker can compromise the confidentiality or integrity of these credentials, then it can obtain access to the WoT assets, impersonate WoT things or devices or create Denial-Of-Service (DoS) attacks. +

    +
    Mitigation:
    + The WoT Scripting Runtime should securely store the provisioned security credentials, guaranteeing their integrity and confidentiality. + In case there are more than one tenant on a single WoT-enabled device, a WoT Scripting Runtime should guarantee isolation of each tenant provisioned security credentials. + Additionally, in order to minimize a risk that provisioned security credentials get compromised, the WoT Scripting Runtime should not expose any API for scripts to query the provisioned security credentials. +
    +
    -
    -
    Provisioning and Update Security Risk
    -

    - If the WoT Scripting Runtime supports post-manufacturing provisioning - or updates of scripts, WoT Scripting Runtime or any related data - (including security credentials), it can be a major attack vector. - An attacker can try to modify any above described element - during the update or provisioning process or simply - provision attacker's code and data directly. +

    +

    Script Security and Privacy Risks

    +

    + This section describes specific risks relevant for script developers.

    -
    Mitigation:
    - Post-manufacturing provisioning or update of scripts, - WoT Scripting Runtime or any related data should be done in a secure fashion. - A set of recommendations for secure update and post-manufacturing - provisioning can be found in [[!WOT-SECURITY-CONSIDERATIONS]]. + +
    +

    Corrupted Script Input Security and Privacy Risk

    +

    + A script instance may receive data formats defined by the TD, or data formats defined by the applications. While the WoT Scripting Runtime SHOULD perform validation on all input fields defined by the TD, scripts may be still exploited by input data. +

    +
    Mitigation:
    + Script developers should perform validation on all application defined script inputs. In addition to input validation, + fuzzing could be used + to verify that the input processing is done correctly. + There are many tools and techniques in existence to do such validation. + More details can be found in [[!WOT-SECURITY-TESTING]]. +
    +
    + +
    +

    Denial Of Service Security Risk

    +

    + If a script performs a heavy functional processing on received requests before the request is authenticated, it presents a great risk for Denial-Of-Service (DOS) attacks. +

    +
    Mitigation:
    + Scripts should avoid heavy functional processing without prior successful + authentication of requestor. The set of recommended authentication mechanisms + can be found in [[!WOT-SECURITY-BEST-PRACTICES]]. +
    +
    + +
    +

    Stale TD Security Risk

    +

    + During the lifetime of a WoT network, a content of a TD can change. + This includes its identifier, which might not be an immutable one and might be updated periodically. +

    +
    Mitigation:
    + Scripts should use this API to subscribe for notifications + on TD changes and do not rely on TD values to remain persistent.
    +

    + While stale TDs can present a potential problem for WoT network operation, + it might not be a security risk. +

    +
    -
    -
    Security Credentials Storage Security and Privacy Risk
    -

    - Typically the WoT Scripting Runtime needs to store the security credentials that are provisioned to a WoT - device to operate in WoT network. If an attacker can compromise the confidentiality or integrity - of these credentials, then it can obtain access to the WoT assets, impersonate WoT things or devices - or create Denial-Of-Service (DoS) attacks. -

    -
    Mitigation:
    - The WoT Scripting Runtime should securely store the provisioned security credentials, - guaranteeing their integrity and confidentiality. - In case there are more than one tenant on a single WoT-enabled device, a WoT Scripting Runtime should - guarantee isolation of each tenant provisioned security credentials. - Additionally, in order to minimize a risk that provisioned security credentials get compromised, - the WoT Scripting Runtime should not expose any API for scripts to query the provisioned - security credentials. -
    -
    -
    -

    Terminology and conventions

    From adbda349606dabc385b424a829b4afcef10a1561 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Thu, 21 Feb 2019 11:32:02 +0200 Subject: [PATCH 297/464] Revise scripting use cases and terminology. Signed-off-by: Zoltan Kis --- index.html | 258 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 161 insertions(+), 97 deletions(-) diff --git a/index.html b/index.html index 2a53f1a9..885514c6 100644 --- a/index.html +++ b/index.html @@ -178,17 +178,18 @@
    • Fetch a Thing Description of a Thing given its URL. +

      + This use case can be fulfilled using a HTTP library or polyfill or the Fetch API available on the platform. +

    • - Consume a TD of a Thing, including parsing the TD and generating the protocol bindings in order to access lower level functionality. -
      • -
    • On a consumed Thing, + Consume a TD, i.e. create a programmatic object from a Thing Description that exposes WoT Interactions:
        -
      • Read the value of a Property or set of properties.
        • +
      • Read the value of a Property or a set of properties.
      • Set the value of a Property or a set of properties.
      • Observe value changes of a Property.
      • Invoke an Action.
        • -
      • Observe Events emitted by the Thing.
        • +
      • Observe WoT Events emitted by the Thing.
      • Observe changes to the Thing Description of the Thing.
      • Get the Thing Description.
      • Get the list of linked resources based on the Thing Description.
        • @@ -202,30 +203,52 @@ Exposing the Thing includes generating the protocol bindings in order to access lower level functionality.
      • - Create a local ExposedThing to be exposed, based on a Thing Description provided in string serialized format, or out of a template or an existing ConsumedThing object.
        • + Create a local Thing to be exposed, based on a Thing Description provided in string serialized format, or out of an existing Thing object. + +
      • Add a Property definition to the Thing.
        • +
      • Remove a Property definition from the Thing.
      • Add an Action definition to the Thing.
        • -
      • Add an Event definition to the Thing.
        • -
      • Attach semantic information to the Thing.
        • -
      • Attach semantic information to a Property.
        • -
      • Attach semantic information to an Action.
        • -
      • Attach semantic information to an Event.
        • +
      • Remove an Action definition from the Thing.
        • +
      • Add a WoT Event definition to the Thing.
        • +
      • Remove a WoT Event definition from the Thing.
        • +
      • - Emit an Event, i.e. notify all listeners subscribed to that Event. + Emit a WoT Event, i.e. notify all subscribed listeners.
      • Provide notifications for TD changes to clients subscribed to that. +

        + This use case could be fulfilled by the TD specifying an event for TD change. +

        • -
      • Mark/unmark the Thing to be discoverable.
        • -
      • Mark/unmark the Thing to be consumable.
        • -
      • Start the exposed Thing in order to process external requests.
        • -
      • Stop the exposed Thing.
        • -
      • Register handlers for external requests: + +
      • Register service handlers for external requests:
        • to retrieve a Property value;
        • to update a Property value;
        • - to run an Action: take the parameters from the request, execute the defined action, and return the result; + to invoke an Action: take the parameters from the request, execute the defined action, and return the result;
        • @@ -412,7 +435,7 @@

        The ThingFilter dictionary

        The fetch(url) method MUST run the following steps:
        1. - Return a Promise promise and execute the next steps in parallel. + Return a Promise promise and execute the next steps in parallel.
        2. If invoking fetch() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps. @@ -734,7 +757,7 @@

          The ExposedThing interface

          The expose() method MUST run the following steps:
          1. - Return a Promise promise and execute the next steps in parallel. + Return a Promise promise and execute the next steps in parallel.
          2. If invoking expose() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps. @@ -760,7 +783,7 @@

            The ExposedThing interface

            The destroy() method MUST run the following steps:
            1. - Return a Promise promise and execute the next steps in parallel. + Return a Promise promise and execute the next steps in parallel.
            2. If invoking destroy() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps. @@ -823,14 +846,14 @@

              The ExposedThing interface

              The PropertyReadHandler callback

              - A function that is called when an external request for reading a Property is received. It should return a Promise and resolves it with the value of the Property matching the name argument to the setPropertyReadHandler function, or rejects with an error if the property is not found or the value cannot be retrieved. + A function that is called when an external request for reading a Property is received. It should return a Promise and resolves it with the value of the Property matching the name argument to the setPropertyReadHandler function, or rejects with an error if the property is not found or the value cannot be retrieved.

              The PropertyWriteHandler callback

              - A function that is called when an external request for writing a Property is received. It is given the requested new value as argument and should return a Promise which is resolved when the value of the Property that matches the name argument has been updated with value, or rejects with an error if the property is not found or the value cannot be updated. + A function that is called when an external request for writing a Property is received. It is given the requested new value as argument and should return a Promise which is resolved when the value of the Property that matches the name argument has been updated with value, or rejects with an error if the property is not found or the value cannot be updated.

              Note that this function is invoked by implementations before the property is updated and it actually defines what to do when a write request is received. The code in this callback function can invoke the read() method to find out the old value of the property, if needed. Therefore the old value is not provided to this function. @@ -840,7 +863,7 @@

              The PropertyWriteHandler callback

              The ActionHandler callback

              - A function called with a parameters dictionary argument assembled by the WoT runtime based on the Thing Description and the external client request. It returns a Promise that rejects with an error or resolves if the action is successful or ongoing (may also resolve with a control object such as an Observable for actions that need progress notifications or that can be canceled). + A function called with a parameters dictionary argument assembled by the WoT runtime based on the Thing Description and the external client request. It returns a Promise that rejects with an error or resolves if the action is successful or ongoing (may also resolve with a control object such as an Observable for actions that need progress notifications or that can be canceled).

              @@ -858,7 +881,7 @@

              The ActionHandler callback

              When an external request for reading Property propertyName is received, the runtime SHOULD execute the following steps:
              1. - Return a Promise promise and execute the next steps in parallel. + Return a Promise promise and execute the next steps in parallel.
              2. If a Property with propertyName does not exist, reject promise with a ReferenceError and terminate these steps. @@ -884,7 +907,7 @@

                The ActionHandler callback

                When an external request for writing a Property propertyName with a new value value is received, the runtime SHOULD execute the following steps:
                1. - Return a Promise promise and execute the next steps in parallel. + Return a Promise promise and execute the next steps in parallel.
                2. If a Property with propertyName does not exist, reject promise with a ReferenceError and terminate these steps. @@ -913,7 +936,7 @@

                  The ActionHandler callback

                  When an external request for invoking the Action identified by name is received, the runtime SHOULD execute the following steps:
                  1. - Return a Promise promise and execute the next steps in parallel. + Return a Promise promise and execute the next steps in parallel.
                  2. If an Action identified by name does not exist, reject promise with a ReferenceError and terminate these steps. @@ -1411,7 +1434,7 @@

                    Observables

                           interface Observable {
-        Subscription subscribe(EventHandler handler,
+        Subscription subscribe(ObserverHandler handler,
                                optional ErrorHandler errorHandler,
                                optional OnComplete onComplete);
       };
@@ -1419,7 +1442,7 @@ 
                    Observables
                    
         void unsubscribe();
         readonly attribute boolean closed;
       };
-      callback EventHandler = void (any value);
+      callback ObserverHandler = void (any value);
       callback ErrorHandler = void (Error error);
       callback OnComplete = void ();
                    @@ -1428,7 +1451,7 @@

                    Observables

                    The following callbacks can be provided when subscribing to an Observable:
                    • - The EventHandler callback takes the next sample for the data in the value argument. + The ObserverHandler callback takes the next sample for the data in the value argument.
                    • The ErrorHandler callback takes an error in the value argument. It is called when an error occured in producing the data the client should know about. @@ -1638,86 +1661,127 @@

                      Stale TD Security Risk

                      JSON-LD is defined in [[!JSON-LD]] as a JSON document that is augmented with support for Linked Data.

                      - The terms URL and - - URL path are defined in [[!URL]]. + The terms + URL, + URL scheme, + URL host, + URL path, + URL record, + parse a URL, + absolute-URL string, + path-absolute-URL string, + basic URL parser + are defined in [[!URL]].

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

                      - A browsing context refers to the environment in which - Document objects are presented to the user. A given - browsing context has a single WindowProxy object, - but it can have many Document objects, with their associated - Window objects. The script execution context - associated with the browsing context identifies the entity which - invokes this API, which can be a web app, a web page, or an - iframe. + The terms + UTF-8 encoding, + UTF-8 decode, + encode, + decode + are defined in [[!ENCODING]].

                      - The term - - secure context is defined in [[!WEBAPPSEC]]. + ASCII decode, + ASCII lowercase, + string, + byte, + byte sequence, + set, + exists, + list, + for each, + continue, + is empty, + is not empty, + append, + contains, + parse JSON from bytes and + serialize JSON to bytes, + are defined in [[!INFRA]]. +

                      +

                      + The terms + throw, + creating, + DOMString, + Dictionary, + ArrayBuffer, + BufferSource, + any, + not present, + DOMException, + AbortError, + SyntaxError, + NotSupportedError, + NetworkError, + TypeError, + NotReadableError, + TimeoutError, + NoModificationAllowedError, + SecurityError, + are defined in [[!WEBIDL]].

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

                      - DOMString, - USVString, - ArrayBuffer, - BufferSource and - any are defined in [[!WEBIDL]]. + The terms + browsing context, + top-level browsing context, + global object, + current settings object, + Document, + document base URL, + Window, + WindowProxy, + origin, + serialized origin, + executing algorithms in parallel, + queue a task, + task source, + iframe, + relevant settings object, + active document, + environment settings object, + EventHandler, + are defined in [[!HTML5]] and are used in the context of browser implementations. +

                      +

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

                      +

                      + The term + + secure context is defined in [[!WEBAPPSEC]].

                      - The algorithms - utf-8 encode, and - - utf-8 decode are defined in [[!ENCODING]]. + fire an event, + AbortSignal, + aborted flag, and + add the following abort steps + are defined in [[!DOM]].

                      IANA media types (formerly known as MIME types) are defined in From d7403a1100b9c4995fb9b2f8a1c67f62a56f4662 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Thu, 7 Mar 2019 10:07:29 +0100 Subject: [PATCH 298/464] feat: start adapting new API reading properties for consumed thing for now --- typescript/index.d.ts | 6 +++++- typescript/package.json | 2 +- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index bf3d1a33..83ed1a3c 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -228,7 +228,11 @@ export interface ThingEvent extends ThingInteraction, EventFragment { /** Represents a client API object to consume Things and their Properties, Actions, and Events */ export interface ConsumedThing extends ThingInstance { - // no additional functions defined + // TODO add additional 'options' field to allow for uriVariables et cetera + readProperty(propertyName: string): Promise; + readAllProperties(): Promise; + readMultipleProperties(propertyNames: [string]): Promise; + // XXX add more } /** Represents a server API object to expose Things and their Properties, Actions, and Events */ diff --git a/typescript/package.json b/typescript/package.json index 6cca2fc6..86600e46 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.7.0-SNAPSHOT.1", + "version": "0.7.0-NEXT-SNAPSHOT.1", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From 990d2d08f808d09691d05019f67bd6aff08fe553 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Thu, 7 Mar 2019 14:20:44 +0100 Subject: [PATCH 299/464] feat: move new API calls to thingInstance --- typescript/index.d.ts | 12 +++++++----- typescript/package.json | 2 +- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index 83ed1a3c..43d657fd 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -197,6 +197,13 @@ export interface ThingInstance extends ThingFragment { actions: { [key: string]: ThingAction }; /** A map of ThingEvents (EventFragment plus mandatory binding metadata (forms)) */ events: { [key: string]: ThingEvent }; + + // next API + // XXX add additional 'options' field to allow for uriVariables et cetera + readProperty(propertyName: string): Promise; + readAllProperties(): Promise; + readMultipleProperties(propertyNames: [string]): Promise; + // XXX add more } /** @@ -228,11 +235,6 @@ export interface ThingEvent extends ThingInteraction, EventFragment { /** Represents a client API object to consume Things and their Properties, Actions, and Events */ export interface ConsumedThing extends ThingInstance { - // TODO add additional 'options' field to allow for uriVariables et cetera - readProperty(propertyName: string): Promise; - readAllProperties(): Promise; - readMultipleProperties(propertyNames: [string]): Promise; - // XXX add more } /** Represents a server API object to expose Things and their Properties, Actions, and Events */ diff --git a/typescript/package.json b/typescript/package.json index 86600e46..934159a5 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.7.0-NEXT-SNAPSHOT.1", + "version": "0.7.0-NEXT-SNAPSHOT.2", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From cd224cc982e584dfb43a921618b21e05ef3f306f Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Thu, 7 Mar 2019 15:45:28 +0100 Subject: [PATCH 300/464] fix: string array issue --- typescript/index.d.ts | 2 +- typescript/package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index 43d657fd..ec179e77 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -202,7 +202,7 @@ export interface ThingInstance extends ThingFragment { // XXX add additional 'options' field to allow for uriVariables et cetera readProperty(propertyName: string): Promise; readAllProperties(): Promise; - readMultipleProperties(propertyNames: [string]): Promise; + readMultipleProperties(propertyNames: string[]): Promise; // XXX add more } diff --git a/typescript/package.json b/typescript/package.json index 934159a5..e4e5d8b5 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.7.0-NEXT-SNAPSHOT.2", + "version": "0.7.0-NEXT-SNAPSHOT.3", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From bfa35cfddc602afed3248f6f5db492f21dcceec7 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Tue, 12 Mar 2019 14:01:35 +0100 Subject: [PATCH 301/464] feat: add writing properties for new API --- typescript/index.d.ts | 2 ++ typescript/package.json | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index ec179e77..0cd8e2f5 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -203,6 +203,8 @@ export interface ThingInstance extends ThingFragment { readProperty(propertyName: string): Promise; readAllProperties(): Promise; readMultipleProperties(propertyNames: string[]): Promise; + writeProperty(propertyName: string, value: any): Promise; + writeMultipleProperties(valueMap: { [key: string]: any }): Promise; // XXX add more } diff --git a/typescript/package.json b/typescript/package.json index e4e5d8b5..a6cb7e17 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.7.0-NEXT-SNAPSHOT.3", + "version": "0.7.0-NEXT-SNAPSHOT.4", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From 672ea3b52f4b3cf9f77f1e91e02dbdb5cb22e660 Mon Sep 17 00:00:00 2001 From: hasbel Date: Fri, 15 Mar 2019 15:52:35 +0100 Subject: [PATCH 302/464] Fix #163 Change to the typescript definitions to make "items" in ArraySchema and "properties" in ObjectSchema non mandatory (as described by the TD spec). --- typescript/index.d.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index bf3d1a33..6e50dc7a 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -383,13 +383,13 @@ export interface StringSchema extends BaseSchema { export interface ObjectSchema extends BaseSchema { type: "object"; - properties: { [key: string]: DataSchema }; + properties?: { [key: string]: DataSchema }; required?: Array; } export interface ArraySchema extends BaseSchema { type: "array"; - items: DataSchema; + items?: DataSchema; minItems?: number; maxItems?: number; } From 13ca9266f38410682fd2fc264f69dfb09602deb5 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Mon, 18 Mar 2019 15:33:43 +0100 Subject: [PATCH 303/464] fix: add invokeAction for next API --- typescript/index.d.ts | 2 ++ typescript/package.json | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index 0cd8e2f5..2e567a0e 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -205,6 +205,8 @@ export interface ThingInstance extends ThingFragment { readMultipleProperties(propertyNames: string[]): Promise; writeProperty(propertyName: string, value: any): Promise; writeMultipleProperties(valueMap: { [key: string]: any }): Promise; + + invokeAction(actionName: string, parameter?: any): Promise; // XXX add more } diff --git a/typescript/package.json b/typescript/package.json index a6cb7e17..c92dc13b 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.7.0-NEXT-SNAPSHOT.4", + "version": "0.7.0-NEXT-SNAPSHOT.5", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From c211947e7f0049c2537647e5e1bc76d2d81a92a3 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Mon, 1 Apr 2019 13:45:13 +0200 Subject: [PATCH 304/464] fix: TypeScript definitions links --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8fa0aee0..3e2a25e7 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ To make contributions, please refer to [https://github.com/w3c/wotwg#contributin ## TypeScript Definitions -The specification uses WebIDL definitions. TypeScript definititions are also available (see https://github.com/thingweb/wot-typescript-definitions/blob/master/index.d.ts). +The specification uses WebIDL definitions. TypeScript definititions are also available (see https://github.com/w3c/wot-scripting-api/blob/master/typescript/index.d.ts). Due to different implementation progress the definitions might be out of sync. However, there are regular sync points usually based on publication releases. Note: For future releases we plan to use TypeScript instead of WebIDL in the specification. From d7119d0a14c6274b6eaaf747c3eec7e169383677 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Thu, 4 Apr 2019 21:57:14 +0300 Subject: [PATCH 305/464] Update editors list, header, abstract and use cases Signed-off-by: Zoltan Kis --- index.html | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/index.html b/index.html index 885514c6..247531fb 100644 --- a/index.html +++ b/index.html @@ -21,9 +21,9 @@ format: 'markdown', editors: [ { name: "Zoltan Kis", company: "Intel", companyURL: "https://www.intel.com/" }, - { name: "Kazuaki Nimura", company: "Fujitsu Ltd.", companyURL: "https://www.fujitsu.com/" }, { name: "Daniel Peintner", company: "Siemens AG", companyURL: "https://www.siemens.com/" }, { name: "Johannes Hund", note: "Former Editor, when at Siemens AG" }, + { name: "Kazuaki Nimura", note: "Former Editor, at Fujitsu Ltd." }, ], wg: "Web of Things Working Group", wgURI: "https://www.w3.org/WoT/WG/", @@ -31,19 +31,10 @@ issueBase: "https://www.github.com/w3c/wot-scripting-api/issues/", githubAPI: "https://api.github.com/repos/w3c/wot-scripting-api", otherLinks: [ - { - key: "Contributors", - data: [ - { - value: "In the GitHub repository", - href: "https://github.com/w3c/wot-scripting-api/graphs/contributors" - } - ] - }, { key: "Repository", data: [{ - value: "We are on GitHub", + value: "On GitHub", href: "https://github.com/w3c/wot-scripting-api" }, { value: "File a bug", @@ -51,6 +42,15 @@ }, ] }, + { + key: "Contributors", + data: [ + { + value: "Contributors on GitHub", + href: "https://github.com/w3c/wot-scripting-api/graphs/contributors" + } + ] + }, ], localBiblio: { "WOT-ARCHITECTURE" : { @@ -115,13 +115,16 @@

                      - The overall Web of Things (WoT) concepts are described in the WoT Architecture document. The Web of Things is made of entities (Things) that can describe their capabilities in a machine-interpretable format, the Thing Description (TD) and expose these capabilities through the WoT Interface, 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 key Web of Things (WoT) concepts are described in the WoT Architecture document. The Web of Things is made of entities (Things) that can describe their capabilities in a machine-interpretable format, the Thing Description (TD) and expose these capabilities through the WoT Interface, 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.

                      - This specification describes a programming interface representing the WoT Interface that allows scripts run on a Thing to discover and consume (retrieve) other Thing Descriptions and to expose Things characterized by WoT Interactions specified by a script. + Scripting is an optional "convenience" building block in WoT and it is typically used in gateways that are able to run a WoT Runtime and script management, providing a convenient way to extend WoT support to new types of endpoints and implement WoT applications like Thing Directory.

                      - Scripting is an optional "convenience" building block in WoT and it is typically used in gateways that are able to run a WoT Runtime and script management, providing a convenient way to extend WoT support to new types of endpoints and implement WoT applications like Thing Directory. + This specification describes a programming interface representing the WoT Interface that allows scripts run on a Thing to discover and consume (retrieve) other Thing Descriptions and to expose Things characterized by WoT Interactions specified by a script. It deliberately follows the [[!WOT-TD]] specification closely. It is possible to implement simpler APIs on top of this API, or inspired directly by [[!WOT-TD]] and implementing the WoT network facing interface (i.e. the WoT Interface). +

                      +

                      + This specification is implemented at least by the ThingWeb project, which is considered the reference open source implementation at the moment. Check the source code, including examples. Other, currently closed source implementations have been made by some of the WG member companies and tested against node-wot in plug-fests.

                      @@ -179,7 +182,7 @@
                    • Fetch a Thing Description of a Thing given its URL.

                      - This use case can be fulfilled using a HTTP library or polyfill or the Fetch API available on the platform. + This use case has been "outsourced" to be fulfilled using a HTTP library or polyfill or the Fetch API available on the platform. We provide example code, but don't any more support a WoT-specific fetch() API.

                    • From 4145db5dc17288bdc492c7ef98317211d00bdd6d Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Sat, 6 Apr 2019 16:23:26 +0300 Subject: [PATCH 306/464] Update the WOT object, fetching, parsing, instantiating a TD, consume(), produce(), discover(), examples. Signed-off-by: Zoltan Kis --- index.html | 576 +++++++++++++++++++++++++---------------------------- 1 file changed, 274 insertions(+), 302 deletions(-) diff --git a/index.html b/index.html index 247531fb..dbbf69f2 100644 --- a/index.html +++ b/index.html @@ -121,7 +121,7 @@ Scripting is an optional "convenience" building block in WoT and it is typically used in gateways that are able to run a WoT Runtime and script management, providing a convenient way to extend WoT support to new types of endpoints and implement WoT applications like Thing Directory.

                      - This specification describes a programming interface representing the WoT Interface that allows scripts run on a Thing to discover and consume (retrieve) other Thing Descriptions and to expose Things characterized by WoT Interactions specified by a script. It deliberately follows the [[!WOT-TD]] specification closely. It is possible to implement simpler APIs on top of this API, or inspired directly by [[!WOT-TD]] and implementing the WoT network facing interface (i.e. the WoT Interface). + This specification describes a programming interface representing the WoT Interface that allows scripts run on a Thing to discover and consume (retrieve) other Thing Descriptions and to expose Things characterized by WoT Interactions specified by a script. It deliberately follows the WoT Thing Description specification closely. It is possible to implement simpler APIs on top of this API, or implementing directly the WoT network facing interface (i.e. the WoT Interface).

                      This specification is implemented at least by the ThingWeb project, which is considered the reference open source implementation at the moment. Check the source code, including examples. Other, currently closed source implementations have been made by some of the WG member companies and tested against node-wot in plug-fests. @@ -179,12 +179,6 @@

                      Consuming a Thing

                        -
                      • - Fetch a Thing Description of a Thing given its URL. -

                        - This use case has been "outsourced" to be fulfilled using a HTTP library or polyfill or the Fetch API available on the platform. We provide example code, but don't any more support a WoT-specific fetch() API. -

                        -
                      • Consume a TD, i.e. create a programmatic object from a Thing Description that exposes WoT Interactions:
                          @@ -219,13 +213,6 @@
                        • Remove an Action definition from the Thing.
                        • Add a WoT Event definition to the Thing.
                        • Remove a WoT Event definition from the Thing.
                          • -
                        • Emit a WoT Event, i.e. notify all subscribed listeners.
                          • @@ -235,17 +222,6 @@ This use case could be fulfilled by the TD specifying an event for TD change.

                          -
                        • Register service handlers for external requests:
                          • to retrieve a Property value;
                            • @@ -259,201 +235,94 @@
                      -
                      -

                      The WoT object

                      -

                      The WoT object is the API entry point and it is exposed by an implementation of the WoT Runtime. The WoT object does not expose properties, only methods for discovering, consuming and exposing a Thing. +

                      +

                      The WOT object

                      +

                      + The WOT object is the API entry point and it is exposed by an implementation of the WoT Runtime as a singleton. The WOT object contains the API methods for discovering, consuming and exposing a Thing.

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

                      -      // [SecureContext]
-      // [NamespaceObject]
-      interface WoT {
-        Observable discover(optional ThingFilter filter);
-        Promise<ThingDescription> fetch(USVString url);
+      typedef (USVString or object) ThingDescription;
+      typedef object ThingInstance;
+      [Constructor(), SecureContext, Exposed=(Window,Worker)]
+      interface WOT {
         ConsumedThing consume(ThingDescription td);
-        ExposedThing produce(ThingModel model);
-        Promise<void> register(USVString directory, ExposedThing thing);
-        Promise<void> unregister(USVString directory, ExposedThing thing);
+        ExposedThing produce(ThingDescription td);
+        void discover(ThingDiscovery discovery);
       };
-      typedef object ThingFragment;
-      typedef object PropertyFragment;
-      typedef object ActionFragment;
-      typedef object EventFragment;
-      typedef object DataSchema;
-      typedef object SecurityScheme;
-      typedef object Link;
-      typedef object Form;
-      typedef USVString ThingDescription;
-      typedef (ThingFragment or ThingDescription) ThingModel;
                      -

                      - The algorithms for the WoT methods will be specified later, including error handling and security considerations. -

                      - -

                      - The ThingModel type represents either a ThingFragment, or a ThingDescription. -

                      - -

                      The discover() method

                      +

                      Fetching a Thing Description

                      - Starts the discovery process that will provide ThingDescriptions that match the optional argument filter of type ThingFilter. Returns an [Observable](https://github.com/tc39/proposal-observable) object that can be subscribed to and unsubscribed from. The handler function provided to the Observable during subscription will receive an argument of type USVString representing a ThingDescription. + The fetch() method has been part of this API in earlier versions. However, now fetching a TD should be done with an external method, such as the Fetch API or a HTTP client library.

                      -
                      -

                      The DiscoveryMethod enumeration

                      - 
                      -          typedef DOMString DiscoveryMethod;
-
                      -

                      - DiscoveryMethod represents the discovery type to be used: -

                      -
                        -
                      • "any" does not provide any restriction
                        • -
                      • - "local" for discovering Things defined in the same device or connected to the device by wired or wireless means. -
                        • -
                      • - "directory" for discovery based on a service provided by a Thing Directory. -
                        • -
                      • - "multicast" for discovering Things in the device's network by using a supported multicast protocol. -
                        • -
                      -
                      + 
                      +        try {
+          let res = await fetch('https://tds.mythings.biz/sensor11');
+          // ... additional checks possible on res.headers
+          let td = await res.json();  // could also be res.text()
+          let thing = WOT.consume(td);
+          console.log("Thing name: " + thing.instance.name);
+        } catch (err) {
+          console.log("Fetching TD failed", err.message);
+        }
+
                      +
                      -
                      -

                      The ThingFilter dictionary

                      -

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

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

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

                      -

                      - The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, for instance a Thing Directory (if method is "directory") or a Thing (otherwise). -

                      -

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

                      -

                      - The fragment property represents a ThingFragment dictionary used for matching property by property against discovered Things. -

                      -
                      +

                      Instantiating a Thing Description

                      +

                      + A ThingDescription is expected to be either a string representing a JSON-serialized object as described in the TD specification, or a JSON object representing a valid TD. +

                      - The discover(filter) method MUST run the following steps: + To parse a TD given td, run the following steps:

                      1. - If invoking discover() is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps. -
                        2. -
                      2. - Return an Observable obs and execute the next steps in parallel. -
                        3. -
                      3. - If obs.subscribe(handler, errorHandler, complete) is called, execute the following sub-steps: -
                          -
                        1. - If the first argument handler is not defined or it is not a function, throw TypeError and terminate the algorithm. Otherwise configure handler to be invoked when a discovery hit happens. -
                          2. -
                        2. - If the second argument errorHandler is defined, but it is not a function, throw TypeError and terminate these steps. Otherwise if defined, save it to be invoked in error conditions. -
                          3. -
                        3. - If the third argument onComplete is defined, but it is not a function, throw TypeError and terminate these steps. Otherwise if defined, save it to be invoked when the discovery process finished for other reasons than having been canceled. -
                          4. -
                        4. - If filter.query is defined, pass it as an opaque string to the underlying implementation to be matched against discovered items. The underlying implementation is responsible to parse it e.g. as a SPARQL or JSON query and match it against the Thing Descriptions found during the discovery process. If queries are not supported, implementations SHOULD throw a NotSupported error and terminate these steps. -
                          5. -
                        5. - If filter.fragment is defined, and if it contains other properties than the ones defined in ThingFragment, throw TypeError and terminate these steps. Otherwise save the object for matching the discovered items against it. -
                          6. -
                        6. - Request the underlying platform to start the discovery process, with the following parameters: -
                            -
                          • - If filter.method is not defined or the value is "any", use the widest discovery method supported by the underlying platform. -
                            • -
                          • - Otherwise if filter.method is "local", use the local Thing Directory for discovery. Usually that defines Things deployed in the same device, or connected to the device in slave mode (e.g. sensors connected via Bluetooth or a serial connection). -
                            • -
                          • - Otherwise if filter.method is "directory", use the remote Thing Directory specified in filter.url. -
                            • -
                          • - Otherwise if filter.method is "multicast", use all the multicast discovery protocols supported by the underlying platform. -
                            • -
                          -
                          7. -
                        -
                        4. -
                      4. - Whenever a new item td is discovered by the underlying platform, run the following sub-steps: -
                          -
                        1. - If filter.query is defined, check if td is a match for the query. The matching algorithm is encapsulated by implementations. If that returns false, discard td and continue the discovery process. -
                          2. -
                        2. - If filter.fragment is defined, for each property defined in it, check if that property exists in td and has the same value. If this is false in any checks, discard td and continue the discovery process. -
                          3. -
                        3. - Otherwise if td has not been discarded in the previous steps, invoke the handler function with td as parameter. -
                          4. -
                        + If the argument td is not a string, throw a TypeError and terminate these steps.
                      5. - Whenever an error occurs during the discovery process, and if errorHandler is defined, invoke it with an argument of type Error whose message property is set to UnknownError unless there was an error code provided by the Protocol Bindings, in which case set it to that value. + Let json be the result of invoking JSON.parse() on td. If that fails, throw TypeError and terminate these steps.
                      6. - When the discovery process is finished, and if onComplete is defined, invoke it run the cancel discovery steps. -
                        7. -
                      7. - When the obs.unsubscribe() method is called, run the following cancel discovery steps: -
                          -
                        1. - 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. -
                          2. -
                        2. - Set obs.closed to false. -
                          3. -
                        + Return json.

                      -
                      - -

                      The fetch() method

                      - Accepts an url argument of type USVString that represents a URL (e.g. "file://..." or "https://...") and returns a Promise that resolves with a ThingDescription (a serialized JSON-LD document of type USVString). + A ThingInstance is an object that represents a Thing Description in the local WoT Runtime.

                      - The fetch(url) method MUST run the following steps: + To instantiate a TD td, run the following steps:

                      1. - Return a Promise promise and execute the next steps in parallel. + If the argument td is not a string or an object, throw a TypeError and terminate these steps.
                      2. - If invoking fetch() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps. + If td is an object, let instance be td.
                      3. - If the argument url is not a URL, reject promise with TypeError and terminate these steps. + Otherwise, if td is a string, let instance be the result of running the parse a TD steps on td. If that fails, re-throw the error and terminate these steps.
                      4. - Make a request to fetch the content of url as described by the Protocol Bindings and wait for the reply. Implementations encapsulate the fetching process and the accepted media types (such as application/td+json), as far as a valid Thing Description can be obtained as defined in [[!WOT-TD]]. Let td be the Thing Description string-serialized from the returned content, as specified in the Thing Description serialization. + Validate instance according to the TD instance validation. If that fails, throw TypeError and terminate these steps.
                      5. - 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 terminate these steps. + Update instance with the WoT Runtime local settings. +
                          +
                        1. + Initialize instance.id to be the final unique identifier of the Thing instance. +
                          2. +
                        2. + Initialize instance.security to the actual security scheme used by the WoT Runtime. +
                          3. +
                        3. + Update instance.forms with local settings (IP address, ports etc). +
                          4. +
                      6. - Otherwise resolve promise with td and terminate these steps. + Return instance.

                      @@ -461,31 +330,13 @@

                      The ThingFilter dictionary

                      The consume() method

                      - Accepts an td argument of type ThingDescription and returns a ConsumedThing object instantiated based on parsing that description. -

                      -

                      - The consume(td) method must run the following steps: + Accepts an td argument and returns a ConsumedThing object that represents a client interface to operate with the Thing. It MUST run the following steps:

                      1. - If the argument td is not a string, throw a TypeError and terminate these steps. -
                        2. -
                      2. - Let stub be the result of running the TD parsing algorithm with td as argument. If that throws an error, re-throw the error and terminate these steps. -
                        3. -
                      3. - If stub does not have an own property that is defined in ThingFragment with a default value, add that property and value to stub. -
                        4. -
                      4. - Create a ConsumedThing object thing initialized from stub that implements Observable. -
                        5. -
                      5. - Add the read() and write() methods to the ThingProperty elements so that they make requests to access the remote Things and wait for the reply, as defined by the Protocol Bindings. Also, all ThingProperty elements SHOULD implement Observable, i.e. define a subscribe() method that should make request to observe the given Properties as defined by the Protocol Bindings. + Let instance be the result of running the instantiate a TD steps on td. If that throws, re-throw the error and terminate these steps.
                      6. - Add the invoke() methods to the ThingAction elements so that they make requests to the remote Thing to invoke its actions, as defined by the Protocol Bindings. -
                        7. -
                      7. - Add the subscribe() method to all ThingEvent elements so that they make requests to subscribe to the events defined by the remote Thing, as defined by the Protocol Bindings. + Let thing be a new ConsumedThing object with thing.instance initialized with instance.
                      8. Return thing. @@ -496,94 +347,213 @@

                        The ThingFilter dictionary

                        The produce() method

                        - Accepts a model argument of type ThingModel and returns an ExposedThing object. -

                        -

                        - The produce(model) method MUST run the following steps: + Accepts a td argument and returns an ExposedThing object that extends ConsumedThing with a server interface, i.e. the ability to define request handlers. It MUST run the following steps:

                        1. If invoking produce() is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
                        2. - If the argument model is a string, then run the TD parsing algorithm with model passed as parameter. If it throws an error, re-throw that error and terminate this algorithm. Otherwise let model be the returned value. + Let instance be the result of running the instantiate a TD steps on td. If that throws, re-throw the error and terminate these steps.
                        3. - If model is not an object, throw TypeError and terminate these steps. -
                          4. -
                        4. - If model does not have an own property that is defined in ThingFragment with a default value, add that property and value to model. -
                          5. -
                        5. - Create an ExposedThing object thing initialized from model. -
                          6. -
                        6. - For each property of ExposedThing defined in ThingFragment, initialize the property based on the provided initial or default values provided to the local WoT Runtime implementation, for instance initialize: -
                            -
                          1. - the id property to be the final unique identifier of the Thing, -
                            2. -
                          2. - the security object of type SecurityScheme to represent the actual security scheme and its properties as set up by the implementation, -
                            3. -
                          3. - the properties property to be an object with all properties being ThingProperty objects in which the read() and write() methods are provided to define local methods to get and set the Property values, -
                            4. -
                          4. - the actions property to be an object with all properties being ThingAction objects in which the invoke() method is provided to define a local method to run the defined Actions, -
                            5. -
                          5. - the events property to be an object with all properties being ExposedEvent objects in which the emit() method is provided to define a local way to trigger sending notifications to all subscribed clients, -
                            6. -
                          6. - and initialize the other properties as initialized from model. -
                            7. + Let thing be a new ExposedThing object with thing.instance initialized with instance.
                          7. Return thing.

                          +
                        + +

                        The discover() method

                        - The TD parsing algorithm takes a string td as argument and runs the following steps: + Starts the discovery process that will look for Thing Descriptions that match an optional filter which can specify the discovery method and match a specific source URL, a query and a template object. Check the example code. Fires an event with a fetchable Thing Description URL whenever a matching Thing Description is found. It MUST run the following steps:

                        1. - Parse td according to the WoT Thing Description in order to produce a JSON object json. Update thing with the properties and values defined in json. + If invoking discover() is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
                        2. - If there was an error during the parsing, throw that error and terminate these steps. + If the argument discovery is not defined or it is not an instance of ThingDiscovery, throw TypeError and terminate these steps.
                        3. - Otherwise return json. + Invoke the discovery.start() method.

                        -
                        -

                        The register() method

                        -

                        - Takes two mandatory arguments: +

                        +

                        The DiscoveryMethod enumeration

                        + 
                        +          typedef DOMString DiscoveryMethod;
+
                        +

                        + DiscoveryMethod represents the discovery type to be used: +

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

                        -

                        - Generate the Thing Description as td, given the Properties, Actions and Events defined for this ExposedThing object. Then make a request to register td to the given WoT Thing Directory. -

                        -
                        +
                        -

                        The unregister() method

                        -

                        - Takes two mandatory arguments: -

                        -

                        -

                        - Makes a request to unregister the thing from the given WoT Thing Directory. -

                        -
                        +
                        +

                        The ThingFilter dictionary

                        +

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

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

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

                        +

                        + The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, for instance a Thing Directory (if method is "directory") or a Thing (otherwise). +

                        +

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

                        +

                        + The fragment property represents a ThingFragment dictionary used for matching property by property against discovered Things. +

                        +
                        + +
                        +

                        The ThingDiscovery interface

                        +

                        + Constructed given a filter and provides the events and methods controlling the discovery process. +

                        + 
                        +          [Constructor(optional ThingFilter filter), SecureContext, Exposed=(Window,Worker)]
+          interface ThingDiscovery: EventTarget {
+            readonly attribute ThingFilter? filter;
+            readonly attribute boolean active;
+            void start();
+            void stop();
+            attribute EventHandler onfound;
+            attribute EventHandler onerror;
+            attribute EventHandler oncomplete;
+          };
+          interface ThingDescriptionEvent: Event {
+            readonly attribute object json-td;
+          };
+
                        +

                        + The filter property represents the discovery filter of type ThingFilter specified for the discovery. +

                        +

                        + The active property represents whether the discovery is actively ongoing or not (i.e. it has either been completed or stopped). +

                        +

                        + The start() method starts the discovery process, or if the discovery is already active, does nothing. +

                        +

                        + The stop() method 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 inactive. +

                        +

                        + The onfound event of type ThingDescriptionEvent is fired when a Thing Description has been discovered. It contains a JSON object json-td representing a parsed, but not yet instantiated Thing Description. +

                        +

                        + The onerror is of type ErrorEvent and is fired when the discovery process reports an error. It might not be supported by all discovery methods and endpoints. +

                        +

                        + The oncomplete simple event is fired when the discovery process is completed, i.e. there are no more Thing Descriptions to discover. It might not be supported by all discovery methods (e.g. multicast discovery) and endpoints. +

                        + +

                        + The start() method runs the following steps: +

                          +
                        1. + If this.filter is defined, +
                            +
                          • + Let filter denote this.filter. +
                            • +
                          • + If filter.query is defined, pass it as an opaque string to the underlying implementation to be matched against discovered items. The underlying implementation is responsible to parse it e.g. as a SPARQL or JSON query and match it against the Thing Descriptions found during the discovery process. If queries are not supported, implementations SHOULD throw a NotSupported error and terminate these steps. +
                            • +
                          • + If filter.fragment is defined, and if it contains other properties than the ones defined in ThingFragment, throw TypeError and terminate these steps. Otherwise save the object for matching the discovered items against it. +
                            • +
                          +
                          2. +
                        2. + Request the underlying platform to start the discovery process, with the following parameters: +
                            +
                          • + If filter.method is not defined or the value is "any", use the widest discovery method supported by the underlying platform. +
                            • +
                          • + Otherwise if filter.method is "local", use the local Thing Directory for discovery. Usually that defines Things deployed in the same device, or connected to the device in slave mode (e.g. sensors connected via Bluetooth or a serial connection). +
                            • +
                          • + Otherwise if filter.method is "directory", use the remote Thing Directory specified in filter.url. +
                            • +
                          • + Otherwise if filter.method is "multicast", use all the multicast discovery protocols supported by the underlying platform. +
                            • +
                          +
                          3. +
                        3. + When the underlying platform has started the discovery process, set the active property to true. +
                          4. +
                        4. + Whenever a new Thing Description td is discovered by the underlying platform, run the following sub-steps: +
                            +
                          1. + Fetch the td. +
                            2. +
                          2. + Let json be the result of running the parse a TD steps on td. If that fails, fire an onerror event with that error, discard td and continue the discovery process. +
                            3. +
                          3. + If filter.query is defined, check if json is a match for the query. The matching algorithm is encapsulated by implementations. If that returns false, discard td and continue the discovery process. +
                            4. +
                          4. + If filter.fragment is defined, for each property defined in it, check if that property exists in json.properties and has the same value. If this is false in any checks, discard td and continue the discovery process. +
                            5. +
                          5. + Otherwise if td has not been discarded in the previous steps, fire an onfound event with its td property set to json. +
                            6. +
                          +
                          5. +
                        5. + Whenever an error occurs during the discovery process, fire an onerror event, whose message property is set to DiscoveryError unless there was an error code provided by the Protocol Bindings, in which case set it to that value. +
                          6. +
                        6. + When the discovery process is completed, fire the oncomplete event, remove all event listeners and set the this.active property to false. +
                          7. +
                        +

                        + +

                        + The stop() runs the following steps: +

                          +
                        1. + 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. +
                          2. +
                        2. + Remove all event listeners. +
                          3. +
                        3. + Set the this.active property to false. +
                          4. +
                        +

                        +
                        +

                      Examples

                      @@ -591,34 +561,37 @@ 
                      The ThingFilter dictionary
                      
           method: "directory",
           url: "http://directory.wotservice.org"
         };
-        let subscription = wot.discover(discoveryFilter).subscribe(
-          td => {
-            console.log("Found Thing " + td.name);
-            // fetch the TD and create a ConsumedThing
-            let thing = wot.consume(td);
-          },
-          error => { console.log("Discovery finished because an error: " + error.message); },
-          () => { console.log("Discovery finished successfully");}
-        );
+        let discovery = new ThingDiscovery(discoveryFilter);
+        discovery.addEventListener("found", event => {
+          console.log("Found Thing Description for " + event.td.name);
+          let thing = WOT.consume(td);
+          console.log("Thing name: " + thing.instance.name);
+        });
+        discovery.onerror = error => {
+          console.log("Discovery error" + error.message);
+        });
+        discovery.oncomplete = event => {
+          console.log("Discovery finished successfully";
+        });
+        discovery.start();
         setTimeout( () => {
-            subscription.unsubscribe();
+            discovery.stop();
             console.log("Discovery timeout");
           },
           5000);
       
                      -        let subscription = wot.discover({ method: "local" }).subscribe(
-          td => { console.log("Found local Thing " + td.name); },
-          error => { console.log("Discovery error: " + error.message); },
-          () => { console.log("Discovery finished successfully");}
-        );
-
                      - 
                      -        let subscription = wot.discover({ method: "local" }).subscribe({
-          td => { console.log("Found local Thing " + td.name); },
-          error: err => { console.log("Discovery error: " + err.message); },
-          complete: () => { console.log("Discovery finished successfully");}
-        });
+        let discovery = new ThingDiscovery({ method: "local" });
+        discovery.onfound = event => {
+          console.log("Found Thing Description for " + event.td.name);
+          let thing = WOT.consume(td);
+          console.log("Thing name: " + thing.instance.name);
+        };
+        discovery.onerror = error =>
+          console.log("Discovery error" + error.message);
+        discovery.oncomplete = event =>
+          console.log("Discovery finished successfully";
+        discovery.start();
                      @@ -740,6 +713,14 @@

                      The ExposedThing interface

                      callback PropertyReadHandler = Promise<any>(); callback PropertyWriteHandler = Promise<void>(any value); callback ActionHandler = Promise<any>(any parameters); + typedef object ThingFragment; + typedef object PropertyFragment; + typedef object ActionFragment; + typedef object EventFragment; + typedef object DataSchema; + typedef object SecurityScheme; + typedef object Link; + typedef object Form;

                      @@ -970,7 +951,7 @@

                      Examples

                      var temperaturePropertyDefinition = temperatureValueDefinition; // add the 'forms' property temperaturePropertyDefinition.forms = [ ... ]; - var thing = WoT.produce({ + var thing = WOT.produce({ name: "tempSensor", properties: { temperature: temperaturePropertyDefinition @@ -1031,7 +1012,7 @@

                      Examples

                      var statusPropertyDefinition = statusValueDefinition; // add the 'forms' property statusPropertyDefinition["forms"] = []; - var thing = WoT.produce({ + var thing = WOT.produce({ name: "mySensor", properties: { brightness: { @@ -1080,7 +1061,7 @@

                      Examples

                      } } }'; try { // note that produce() fails if thingDescription contains error - let thing = WoT.produce(thingDescription); + let thing = WOT.produce(thingDescription); // Interactions were added from TD // WoT adds generic handler for reading any property // define a specific handler for one property @@ -1103,9 +1084,9 @@

                      Examples

                               // fetch an external TD, e.g., to set up a proxy for that Thing
-        WoT.fetch("http://myservice.org/mySensor/description").then(td => {
-          // WoT.produce() ignores instance-specific metadata (security, form)
-          let thing = WoT.produce(td);
+        WOT.fetch("http://myservice.org/mySensor/description").then(td => {
+          // WOT.produce() ignores instance-specific metadata (security, form)
+          let thing = WOT.produce(td);
           // Interactions were added from TD
           // add server functionality
           // ...
@@ -1193,15 +1174,6 @@ 
                      The ThingFragment dictionary
                      -
                      -

                      The ThingDescription type

                      -

                      - Serialized representation of the Thing Description (a JSON-LD document). -

                      -

                      - In this version of the API, Thing Descriptions are represented as an opaque USVString that can be transmitted between devices. -

                      -
                      From cf7f9555af61a0ee775db61df5e7849bb926658a Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Sat, 6 Apr 2019 21:13:06 +0300 Subject: [PATCH 307/464] Update ConsumeThing, ExposedThing, remove unnecessary sections, start writing some of the algorithms. Signed-off-by: Zoltan Kis --- index.html | 837 ++++++++++++++++++----------------------------------- 1 file changed, 285 insertions(+), 552 deletions(-) diff --git a/index.html b/index.html index dbbf69f2..247f4310 100644 --- a/index.html +++ b/index.html @@ -246,7 +246,7 @@

                      The WOT object

                             typedef (USVString or object) ThingDescription;
       typedef object ThingInstance;
-      [Constructor(), SecureContext, Exposed=(Window,Worker)]
+      [SecureContext, Exposed=(Window,Worker)]
       interface WOT {
         ConsumedThing consume(ThingDescription td);
         ExposedThing produce(ThingDescription td);
@@ -276,13 +276,13 @@ 
                      The WOT object
                      
         A ThingDescription is expected to be either a string representing a JSON-serialized object as described in the TD specification, or a JSON object representing a valid TD.
       
                      
       
                      
-        To parse a TD given td, run the following steps:
+        To parse a TD denoted as td, run the following steps:
         
                        
           
                      1. 
-            If the argument td is not a string, throw a TypeError and terminate these steps.
+            If td is not a string, throw TypeError and terminate these steps.
           
                        2. 
           
                      2. 
-            Let json be the result of invoking JSON.parse() on td. If that fails, throw TypeError and terminate these steps.
+            Let json be the result of invoking JSON.parse() on td. If that fails, throw SyntaxError and terminate these steps.
           
                        3. 
           
                      3. 
             Return json.
@@ -290,22 +290,22 @@ 
                        The WOT object
                        
         
                      
       
                      
       
                      
-        A ThingInstance is an object that represents a Thing Description in the local WoT Runtime.
+        A ThingInstance denotes an object that represents a Thing Description in the local WoT Runtime.
       
                      
       
                      
-        To instantiate a TD td, run the following steps:
+        To instantiate a TD denoted as td, run the following steps:
         
                        
           
                      1. 
-            If the argument td is not a string or an object, throw a TypeError and terminate these steps.
+            If the td is not a string or an object, throw TypeError and terminate these steps.
           
                        2. 
           
                      2. 
             If td is an object, let instance be td.
           
                        3. 
           
                      3. 
-            Otherwise, if td is a string, let instance be the result of running the parse a TD steps on td. If that fails, re-throw the error and terminate these steps.
+            Otherwise, if td is a string, let instance be the result of running the parse a TD steps on td. If that fails by throwing an error, re-throw the error and terminate these steps.
           
                        4. 
           
                      4. 
-            Validate instance according to the TD instance validation. If that fails, throw TypeError and terminate these steps.
+            Validate instance according to the TD instance validation. If that fails, throw SyntaxError and terminate these steps.
           
                        5. 
           
                      5. 
             Update instance with the WoT Runtime local settings.
@@ -317,7 +317,7 @@ 
                        The WOT object
                        
                 Initialize instance.security to the actual security scheme used by the WoT Runtime.
               
                        6. 
               
                      6. 
-                Update instance.forms with local settings (IP address, ports etc).
+                Update instance.forms with local settings specific to the WoT Runtime.
               
                        7.
                      • @@ -338,6 +338,12 @@

                      The WOT object

                    • Let thing be a new ConsumedThing object with thing.instance initialized with instance.
                      • +
                    • + Make a request to the underlying platform to subscribe to TD change notifications. +

                      + This mechanism needs to be defined more exactly in the Thing Description specification. +

                      +
                    • Return thing.
                      • @@ -413,7 +419,7 @@

                      The ThingFilter dictionary

                      (DiscoveryMethod or DOMString) method = "any"; USVString? url; USVString? query; - ThingFragment? fragment; + object? fragment; };

                      @@ -426,7 +432,7 @@

                      The ThingFilter dictionary

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

                      - The fragment property represents a ThingFragment dictionary used for matching property by property against discovered Things. + The fragment property represents a template object used for matching property by property against discovered Things.

                      @@ -447,7 +453,7 @@

                      The ThingDiscovery interface

                      attribute EventHandler oncomplete; }; interface ThingDescriptionEvent: Event { - readonly attribute object json-td; + readonly attribute object jsonTD; };

                      @@ -463,7 +469,7 @@

                      The ThingDiscovery interface

                      The stop() method 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 inactive.

                      - The onfound event of type ThingDescriptionEvent is fired when a Thing Description has been discovered. It contains a JSON object json-td representing a parsed, but not yet instantiated Thing Description. + The onfound event of type ThingDescriptionEvent is fired when a Thing Description has been discovered. It contains a JSON object jsonTD representing a parsed, but not yet instantiated Thing Description.

                      The onerror is of type ErrorEvent and is fired when the discovery process reports an error. It might not be supported by all discovery methods and endpoints. @@ -484,9 +490,6 @@

                      The ThingDiscovery interface

                    • If filter.query is defined, pass it as an opaque string to the underlying implementation to be matched against discovered items. The underlying implementation is responsible to parse it e.g. as a SPARQL or JSON query and match it against the Thing Descriptions found during the discovery process. If queries are not supported, implementations SHOULD throw a NotSupported error and terminate these steps.
                      • -
                    • - If filter.fragment is defined, and if it contains other properties than the ones defined in ThingFragment, throw TypeError and terminate these steps. Otherwise save the object for matching the discovered items against it. -
                    • @@ -563,7 +566,8 @@

                      The ThingDiscovery interface

                      }; let discovery = new ThingDiscovery(discoveryFilter); discovery.addEventListener("found", event => { - console.log("Found Thing Description for " + event.td.name); + let td = event.jsonTD; + console.log("Found Thing Description for " + td.name); let thing = WOT.consume(td); console.log("Thing name: " + thing.instance.name); }); @@ -583,7 +587,8 @@

                      The ThingDiscovery interface

                               let discovery = new ThingDiscovery({ method: "local" });
         discovery.onfound = event => {
-          console.log("Found Thing Description for " + event.td.name);
+          let td = event.jsonTD;
+          console.log("Found Thing Description for " + td.name);
           let thing = WOT.consume(td);
           console.log("Thing name: " + thing.instance.name);
         };
@@ -599,231 +604,276 @@ 
                      The ThingDiscovery interface
                      
   
                      
     
                      The ConsumedThing interface
                      
     
                      
-      Represents an object that extends a ThingFragment with methods for client interactions (send request for reading and writing Properties), invoke Actions, subscribe and unsubscribe for Property changes and Events.
+      Represents a client API to operate a Thing.
     
                      
     
                      -      interface ConsumedThing: ThingFragment {
-        readonly attribute DOMString id;
-        readonly attribute DOMString name;
-        readonly attribute DOMString? base;
-        readonly attribute PropertyMap properties;
-        readonly attribute ActionMap actions;
-        readonly attribute EventMap events;
-        // getter for ThingFragment properties
-        getter any(DOMString name);
+      [Constructor(ThingInstance instance), SecureContext, Exposed=(Window,Worker)]
+      interface ConsumedThing: EventTarget {
+        Promise<any> readProperty(DOMString propertyName, optional InteractionOptions options);
+        Promise<object> readAllProperties(optional InteractionOptions options);
+        Promise<object> readMultipleProperties(sequence<DOMString> propertyNames, optional InteractionOptions options);
+        Promise<void> writeProperty(DOMString propertyName, any value, optional InteractionOptions options);
+        Promise<void> writeMultipleProperties(object valueMap, optional InteractionOptions options);
+        Promise<any> invokeAction(DOMString actionName, optional any params, optional InteractionOptions options);
+        Promise<void> subscribeProperty(DOMString name, WotListener listener);
+        Promise<void> unsubscribeProperty(DOMString name);
+        Promise<void> subscribeEvent(DOMString name, WotListener listener);
+        Promise<void> unsubscribeEvent(DOMString name);
+        readonly attribute ThingInstance instance;
+        attribute EventHandler onchange;
       };
-      [NoInterfaceObject]
-      interface PropertyMap {
-        readonly maplike<DOMString, ThingProperty>;
+      callback WotListener = void(any data);
+      dictionary InteractionOptions {
+        object uriVariables;
       };
-      [NoInterfaceObject]
-      interface ActionMap {
-        readonly maplike<DOMString, ThingAction>;
-      };
-      [NoInterfaceObject]
-      interface EventMap {
-        readonly maplike<DOMString, ThingEvent>;
-      };
-      ConsumedThing includes Observable;  // for TD changes
     
                      
-    
                      
-      The id attribute represents the unique identifier of the Thing instance, typically a URI, IRI, or URN as USVString.
-    
                      
-    
                      
-      The name attribute represents the name of the Thing as DOMString.
-    
                      
-    
                      
-      The base attribute represents the base URI that is valid for all defined local interaction resources.
-    
                      
-    
                      
-      The properties attribute represents a dictionary of ThingProperty items. The PropertyMap interface represents a maplike dictionary where all values are ThingProperty objects. The read() and write() methods make a request to access the Properties on the remote Thing represented by this ConsumedThing proxy object.
-    
                      
-    
                      
-      The actions attribute represents a dictionary of ThingAction items. The ActionMap interface represents a maplike dictionary where all values are ThingAction objects. The invoke() method represents a request to invoke the Action on the remote Thing.
-    
                      
-    
                      
-      The events attribute represents a dictionary of ThingEvent items. The EventMap interface represents a maplike dictionary where all values are ThingEvent objects. Subscribing to the events involves setting up an observation (subscription) mechanism on the remote object.
-    
                      
 
     
                      
-      
                      Examples
                      
+      
                      Constructing ConsumedThing
                      
       
                      
-        Below a ConsumedThing interface example is given.
+        The instance read-only property is a JSON object that represents the Thing instance, i.e. the result of the instantiate a TD steps given the Thing Description of the Thing.
       
                      
-      
                      -        try {
-          let subscription = wot.discover({ method: "local" }).subscribe(
-            td => {
-              let thing = wot.consume(td);
-              console.log("Thing " + thing.name + " has been consumed.");
-              let subscription = thing["temperature"].subscribe(function(value) {
-                  console.log("Temperature: " + value);
-                });
-              thing.actions["startMeasurement"].invoke({ units: "Celsius" })
-                .then(() => { console.log("Temperature measurement started."); })
-                .catch(e => {
-                   console.log("Error starting measurement.");
-                   subscription.unsubscribe();
-                 })
-            },
-            error => { console.log("Discovery error: " + error.message); },
-            () => { console.log("Discovery finished successfully");}
-          );
-        } catch(error) {
-          console.log("Error: " + error.message);
-        };
-      
                      
-    
                       
-  
                       
+      
                      
+        The ConsumedThing objects SHOULD only be created by the consume() method which internally uses the ConsumedThing constructor by providing a ThingInstance. This specification currently does not provide an API to expose a standalone ThingInstance produced by the instantiate a TD steps. A ThingInstance is exposed only on ConsumedThing and ExposedThing objects. However, an existing ThingInstance can be used for constructing another ConsumedThing object that will basically be a deep clone and will represent the same remote Thing. A ThingInstance object can also be modified before feeding to the constructor, but then an inconsistent ConsumedThing would be created whose interactions may fail. A modified ThingInstance can be used in turn to create a new ExposedThing where the necessary request handlers can be added.
+      
                      
+    
 
-  
                      
-    
                      The ExposedThing interface
                      
-    
                      
-      The ExposedThing interface is the server API that allows defining request handlers, properties, Actions, and Events to a Thing. It also implements the Observable interface. An ExposedThing is created by the produce() method.
-    
                      
-    
                      -      interface ExposedThing: ThingFragment {
-        readonly attribute PropertyMap properties;
-        readonly attribute ActionMap actions;
-        readonly attribute ExposedEvents events;
-        // getter for ThingFragment properties
-        getter any(DOMString name);
-        // setter for ThingFragment properties
-        setter void(DOMString name, any value);
-        // methods to expose and destroy the Thing
-        Promise<void> expose();
-        Promise<void> destroy();
-        // define Properties
-        ExposedThing addProperty(DOMString name, PropertyFragment property, optional any initValue);
-        ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
-        ExposedThing setPropertyWriteHandler(DOMString name, PropertyWriteHandler writeHandler);
-        ExposedThing removeProperty(DOMString name);
-        // define Actions
-        ExposedThing addAction(DOMString name, ActionFragment init, ActionHandler action);
-        ExposedThing removeAction(DOMString name);
-        ExposedThing setActionHandler(DOMString name, ActionHandler action);
-        // define Events
-        ExposedThing addEvent(DOMString name, EventFragment event);
-        ExposedThing removeEvent(DOMString name);
-      };
-      [NoInterfaceObject]
-      interface ExposedEvents {
-        maplike<DOMString, ExposedEvent>;
-      };
-      callback PropertyReadHandler = Promise<any>();
-      callback PropertyWriteHandler = Promise<void>(any value);
-      callback ActionHandler = Promise<any>(any parameters);
-      typedef object ThingFragment;
-      typedef object PropertyFragment;
-      typedef object ActionFragment;
-      typedef object EventFragment;
-      typedef object DataSchema;
-      typedef object SecurityScheme;
-      typedef object Link;
-      typedef object Form;
-    
                      
+    
                      
+      
                      The TD change steps
                      
+      
                      
+        The onchange event is fired when the Thing Description has been changed by the source from where it was consumed.
+      
                      
+      
                      
+        When the Thing Description is changed by the source and the underlying platform gets a change notification, run the following steps:
+        
                        
+          
                      1. 
+            Fetch the new Thing Description and let td be the result of running the parse a TD steps on it. If that throws an error, terminate these steps.
+          
                        2. 
+          
                      2. 
+            Let instance be the result of running the instantiate a TD steps on td. If that throws an error, terminate these steps.
+          
                        3. 
+          
                      3. 
+            Replace this.instance with instance.
+          
                        4. 
+          
                      4. 
+            Fire an onchange event.
+          
                        5. 
+        
                      
+      
                      
+    
                      
 
-    
                      
-      The properties attribute represents a dictionary of ThingProperty items in which the read() and write() methods define local methods that access the physical representations of the Properties.
-    
                      
-    
                      
-      The actions attribute represents a dictionary of ThingAction items in which the invoke() method represents a local method to invoke the Action.
-    
                      
-    
                      
-      The events attribute represents a dictionary of ExposedEvent items that add the emit() method to the ThingEvent definition. The ExposedEvents interface represents a maplike dictionary where all values are ExposedEvent objects.
-    
                      
+    
                      
+      
                      The InteractionOptions dictionary
                      
+      
                      
+        Contains properties that define specific overrideable options on WoT interactions defined in the TD InteractionAffordance section. At the moment this includes only uriVariables.
+      
                      
+      
                      
+        The uriVariables property is a JSON object that defines URI template variables as in RFC-6570. An example of URI templates is given in the TD specification.
+      
                      
+    
                      
 
-    
                       
                      The expose() method
                      
+    
                      
+      
                      The WotListener callback
                      
       
                      
-        Start serving external requests for the Thing, so that WoT Interactions using Properties, Actions and Events will be possible.
+        User provided callback that takes any argument and is used for Property change and Event subscriptions. As subscriptions are WoT interactions, they are not modelled with software events.
       
                      
+    
                      
+
+    
                      
+      
                      The readProperty() method
                      
       
                      
-        The expose() method MUST run the following steps:
+        Reads a Property value. Takes the following arguments: a string propertyName and an optional InteractionOptions options argument. It returns a Property value represented as any type. It runs the following steps:
         
                        
           
                      1. 
             Return a Promise promise and execute the next steps in parallel.
           
                        2. 
           
                      2. 
-            If invoking expose() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
+            If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
           
                        3. 
           
                      3. 
-            Make a request to the underlying platform to attach protocol handlers and start serving external requests for WoT Interactions (read, write and observe Properties, invoke Actions and manage Event subscriptions), based on the Protocol Bindings.
+            Make a request to the underlying platform (via the Protocol Bindings) to retrieve the value of the Property given by propertyName with optional URI templates given in options.uriVariables.
           
                        4. 
           
                      4. 
-            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 terminate these steps.
+            If the request fails, return the error received from the Protocol Bindings and terminate these steps.
           
                        5. 
           
                      5. 
-            Otherwise resolve promise with td and terminate these steps.
+            Let value be the result of the request.
+          
                        6. 
+          
                      6. 
+            Run the validate Property value sub-steps on value:
+            
                          
+              
                        1. 
+                Based on the DataSchema definition, value MUST be a JSON value and comply to the data schema defined for the Property that is found in this.instance.properties[propertyName].
+              
                          2. 
+              
                        2. 
+                If this fails, return SyntaxError and terminate these steps.
+              
                          3. 
+              
                        3. 
+                Return value.
+            
                          4. 
+          
                        
+          
                      7. 
+            If these steps returned an error, reject promise with that error and terminate these steps.
+          
                        8. 
+          
                      8. 
+            Otherwise resolve promise with value.
           
                        9. 
         
                      
       
                      
     
                      
 
-    
                       
                      The destroy() method
                      
-      
                      
-        Stop serving external requests for the Thing and destroy the object. Note that eventual unregistering should be done before invoking this method.
-      
                      
+    
                      
+      
                      The readMultipleProperties() method
                      
       
                      
-        The destroy() method MUST run the following steps:
+        Reads multiple Property values with one or multiple requests. Takes the following arguments: a sequence of strings propertyNames and an optional InteractionOptions options argument. It returns an object with keys from propertyNames and values returned by this algorithm. The method runs the following steps:
         
                        
           
                      1. 
             Return a Promise promise and execute the next steps in parallel.
           
                        2. 
           
                      2. 
-            If invoking destroy() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
+            If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
           
                        3. 
           
                      3. 
-            Make a request to the underlying platform to stop serving external requests for WoT Interactions, based on the Protocol Bindings.
+            Let result be an object and for each string name in propertyNames add a property with key name and the value null.
           
                        4. 
           
                      4. 
-            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 terminate these steps.
+            Make a request to the underlying platform (via the Protocol Bindings) to retrieve the Property values given by propertyNames with optional URI templates given in options.uriVariables. If the Protocol Bindings support this using one request, use that, otherwise run the readProperty() steps on each property name in propertyNames and options and store the resulting values in result for each name in propertyNames.
           
                        5. 
           
                      5. 
-            Otherwise resolve promise with td and terminate these steps.
+            If the above step fails at any point, reject promise with SyntaxError and terminate these steps.
+          
                        6. 
+          
                      6. 
+            Resolve promise with result.
+          
                        7. 
+        
                      
+      
                      
+    
                      
+
+    
                      
+      
                      The readAllProperties() method
                      
+      
                      
+        Reads all properties of the Thing with one or multiple requests. Takes an optional InteractionOptions options argument. It returns an object with keys from Property names and values returned by this algorithm. The method runs the following steps:
+        
                        
+          
                      1. 
+            Let propertyNames be a sequence created from all the Property names of this Thing as found in this.instance.properties.
+          
                        2. 
+          
                      2. 
+            Let result be the result of running the readMultipleProperties() steps on propertyNames and options. If that fails, reject promise with that error and terminate these steps.
+          
                        3. 
+          
                      3. 
+            Resolve promise with result.
           
                        4. 
         
                      
       
                      
     
                      
 
-    
                       
                      The addProperty() method
                      
+    
                      
+      
                      The writeProperty() method
                      
       
                      
-        Adds a Property with name defined by the name argument, the data schema provided by the property argument of type PropertyFragment, and optionally an initial value provided in the argument initValue whose type should match the one defined in the type property according to the value-matching algorithm. If initValue is not provided, it SHOULD be initialized as undefined. Implementations SHOULD update the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
                      
-    
                       
+    
                      
 
-    
                       
                      The removeProperty() method
                      
+    
                      
+      
                      The writeMultipleProperties() method
                      
       
                      
-        Removes the Property specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
                      
     
                      
 
-    
                       
                      The addAction() method
                      
+    
                      
+      
                      The invokeAction() method
                      
       
                      
-        Adds to the actions property of a Thing object an Action with name defined by the name argument, defines input and output data format by the init argument of type ActionFragment, and adds the function provided in the action argument as a handler, then updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
                      
+    
                      
+
+    
                      
+      
                      The subscribeProperty() method
                      
       
                      
-        The provided action callback function will implement invoking an Action and SHOULD be called by implementations when a request for invoking the Action is received from the underlying platform. The callback will receive a parameters dictionary argument according to the definition in the init.input argument and will return a value of type defined by the init.output argument according to the value-matching algorithm.
       
                      
+    
                      
+
+    
                      
+      
                      The unsubscribeProperty() method
                      
       
                      
-        There SHOULD be exactly one handler for any given Action. If no handler is initialized for any given Action, implementations SHOULD throw a TypeError.
       
                      
-    
                       
+    
                      
 
-    
                       
                      The removeAction() method
                      
+    
                      
+      
                      The subscribeEvent() method
                      
       
                      
-        Removes the Action specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
                      
     
                      
 
-    
                       
                      The addEvent() method
                      
+    
                      
+      
                      The unsubscribeEvent() method
                      
       
                      
-        Adds an event with name defined by the name argument and qualifiers and initialization value provided by the event argument of type EventFragmentto the Thing object and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
       
                      
     
                      
 
-    
                       
                      The removeEvent() method
                      
+    
                      
+      
                      Examples
                      
+      
                      
+        This example illustrates how to fetch a TD by URL, create a ConsumedThing, read metadata (name), read property value, subscribe to property change, subscribe to a WoT event, unsubscribe.
+      
                      
+      
                      +        try {
+          let res = await fetch("https://tds.mythings.org/sensor11");
+          let td = res.json();
+          let thing = new ConsumedThing(td);
+          console.log("Thing " + thing.instance.name + " consumed.");
+        } catch(e) {
+          console.log("TD fetch error: " + e.message); },
+        };
+        try {
+          // subscribe to property change for “temperature”
+          await thing.subscribeProperty("temperature", value => {
+            console.log("Temperature changed to: " + value);
+          });
+          // subscribe to the “ready” event defined in the TD
+          await thing.subscribeEvent("ready", eventData => {
+            console.log("Ready; index: " + eventData);
+            // run the “startMeasurement” action defined by TD
+            await thing.invokeAction("startMeasurement", { units: "Celsius" });
+            console.log("Measurement started.");
+          });
+        } catch(e) {
+          console.log("Error starting measurement.");
+        }
+        setTimeout( () => {
+          console.log(“Temperature: “ + await thing.readProperty(“temperature”));
+          await thing.unsubscribe(“ready”);
+          console.log("Unsubscribed from the ‘ready’ event.");
+        },
+        10000);
+      
                      
+    
                       
+  
                       
+
+  
                      
+    
                      The ExposedThing interface
                      
+    
                      
+      The ExposedThing interface is the server API to operate the Thing that allows defining request handlers, Property, Action, and Event interactions.
+    
                      
+    
                      +      callback PropertyReadHandler = Promise<any>();
+      callback PropertyWriteHandler = Promise<void>(any value);
+      callback ActionHandler = Promise<any>(any parameters);
+      [Constructor(ThingInstance instance), SecureContext, Exposed=(Window,Worker)]
+      interface ExposedThing: ConsumedThing {
+        ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
+        ExposedThing setPropertyWriteHandler(DOMString name, PropertyWriteHandler writeHandler);
+        ExposedThing setActionHandler(DOMString name, ActionHandler action);
+        void emitEvent(DOMString name, any data);
+        Promise<void> expose();
+        Promise<void> destroy();
+      };
+    
                      
+    
                      
+      
                      Constructing ExposedThing
                      
+      
                      
+        The ExposedThing interface extends ConsumedThing.
+      
                      
       
                      
-        Removes the event specified by the name argument and updates the Thing Description. Returns a reference to the same object for supporting chaining.
+        The ExposedThing objects SHOULD only be created by the produce() method which internally uses the ExposedThing constructor by providing a ThingInstance. This specification currently does not provide an API to expose a standalone ThingInstance produced by the instantiate a TD steps. A ThingInstance is exposed only on ConsumedThing and ExposedThing objects. However, an existing ThingInstance can be used or modified and used for constructing another ExposedThing object. This is the current way of adding and removing Property, Action and Event definitions as also illustrated in the examples.
       
                      
     
                      
 
@@ -847,7 +897,7 @@ 
                      The PropertyWriteHandler callback
                      
     
                      
       
                      The ActionHandler callback
                      
       
                      
-        A function called with a parameters dictionary argument assembled by the WoT runtime based on the Thing Description and the external client request. It returns a Promise that rejects with an error or resolves if the action is successful or ongoing (may also resolve with a control object such as an Observable for actions that need progress notifications or that can be canceled).
+        A function called with a parameters dictionary argument assembled by the WoT runtime based on the Thing Description and the external client request. It returns a Promise that rejects with an error or resolves if the action is successful.
       
                      
     
                      
 
@@ -935,6 +985,64 @@ 
                      The ActionHandler callback
                      
       
                      
     
                      
 
+    
                       
                      The emitEvent() method
                      
+      
                      
+        void emitEvent(DOMString name, any data);
+      
                      
+    
                      
+
+    
                       
                      The expose() method
                      
+      
                      
+        Start serving external requests for the Thing, so that WoT Interactions using Properties, Actions and Events will be possible.
+      
                      
+      
                      
+        The expose() method MUST run the following steps:
+        
                        
+          
                      1. 
+            Return a Promise promise and execute the next steps in parallel.
+          
                        2. 
+          
                      2. 
+            If invoking expose() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
+          
                        3. 
+          
                      3. 
+            Make a request to the underlying platform to attach protocol handlers and start serving external requests for WoT Interactions (read, write and observe Properties, invoke Actions and manage Event subscriptions), based on the Protocol Bindings.
+          
                        4. 
+          
                      4. 
+            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 terminate these steps.
+          
                        5. 
+          
                      5. 
+            Otherwise resolve promise with td and terminate these steps.
+          
                        6. 
+        
                      
+      
                      
+    
                      
+
+    
                       
                      The destroy() method
                      
+      
                      
+        Stop serving external requests for the Thing and destroy the object. Note that eventual unregistering should be done before invoking this method.
+      
                      
+      
                      
+        The destroy() method MUST run the following steps:
+        
                        
+          
                      1. 
+            Return a Promise promise and execute the next steps in parallel.
+          
                        2. 
+          
                      2. 
+            If invoking destroy() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
+          
                        3. 
+          
                      3. 
+            Make a request to the underlying platform to stop serving external requests for WoT Interactions, based on the Protocol Bindings.
+          
                        4. 
+          
                      4. 
+            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 terminate these steps.
+          
                        5. 
+          
                      5. 
+            Otherwise resolve promise with td and terminate these steps.
+          
                        6. 
+        
                      
+      
                      
+    
                      
+
     
                      
       
                      Examples
                      
       
                      
@@ -1095,382 +1203,7 @@ 
                      Examples
                      
     
                       
   
                       
 
-  
                      
-    
                      Data types and structures
                      
-    
                      
-      The [[!WOT-TD]] specification defines the WoT information model, i.e. the data types and data structures used in WoT Interactions. In this API these definitions translate to dictionary objects that are extended with methods by the interfaces defined in this specification.
-    
                      
-    
                      
-      In order to avoid duplication of definitions, references to these data types and structures is defined in this section, but for their full description please refer to the Thing Description specification.
-    
                      
-    
                      
-      
                      The DataSchema dictionary and its subclasses
                      
-      
                      
-        Value types basically represent types that may be used in JSON object definitions and are used in ThingFragment to define Properties, Events and Action parameters. Value types are represented as dictionary objects whose properties and possible sub-classes are defined in the DataSchema section of [[!WOT-TD]].
-      
                      
-      
                      
-        One property of all DataSchema dictionary is the type property whose value is from a set of enumerated strings defined in the DataSchema section of [[!WOT-TD]] and is referred as DataType in this specification.
-      
                      
-      
                      
-        Based on type, the following sub-classes of DataSchema are defined in [[!WOT-TD]]: BooleanSchema, NumberSchema, IntegerSchema, StringSchema, ObjectSchema, ArraySchema.
-      
                      
-    
                      
-
-    
                      
-      
                      The SecurityScheme dictionary and its subclasses
                      
-      
                      
-        Security metadata is represented as dictionary objects whose properties and sub-classes are defined in the SecurityScheme section of [[!WOT-TD]].
-      
                      
-      
                      
-        One property of the SecurityScheme dictionary is the scheme property whose value is from a set of enumerated strings defined in the SecurityScheme section of [[!WOT-TD]]. Based on type, multiple subclasses of SecurityScheme are defined.
-    
                      
-
-    
                      
-      
                      The Link dictionary
                      
-      
                      
-        Represents a Web Link with  properties defined in the Link section of [[!WOT-TD]].
-      
                      
-    
                      
-
-    
                      
-      
                      The Form dictionary
                      
-      
                      
-        Represents metadata describing service details, with  properties defined in the Form section of [[!WOT-TD]].
-      
                      
-    
                      
-
-    
                      
-      
                      The InteractionFragment dictionary
                      
-      
                      
-        Represents the common properties of WoT Interactions, one of Property, Action or Event, as defined in the InteractionPattern section of [[!WOT-TD]]. Its subclasses are referred as PropertyFragment, ActionFragment and EventFragment.
-      
                      
-    
                      
-
-    
                      
-      
                      The PropertyFragment dictionary
                      
-      
                      
-        Represents the Property interaction data that initializes a ThingProperty object. Its properties are defined in the Property and InteractionPattern sections of [[!WOT-TD]].
-      
                      
-    
                      
-
-    
                      
-      
                      The ActionFragment dictionary
                      
-      
                      
-        Represents the Action interaction data that initializes a ThingAction object. Its properties are defined in the Action and InteractionPattern sections of [[!WOT-TD]].
-      
                      
-    
                      
-
-    
                      
-      
                      The EventFragment dictionary
                      
-      
                      
-        Represents the Event interaction data that initializes a ThingEvent object. Its properties are defined in the Event section of [[!WOT-TD]].
-      
                      
-    
                      
-
-    
                      
-      
                      The ThingFragment dictionary
                      
-      
                      
-        The ThingFragment dictionary is defined as Thing in [[!WOT-TD]]. It is a dictionary that contains properties representing semantic metadata and interactions (Properties, Actions and Events). It is used for initializing an internal representation of a Thing Description and its properties may be used in ThingFilter.
-      
                      
-    
                       
-
-  
                      
-
-  
                      
-    
                      Interfaces for WoT Interactions
                      
-    
                      
-      The data types and structures imported from [[!WOT-TD]] are extended by this specification in order to provide the interfaces for WoT Interactions.
-    
                      
-    
                      
-      Every Thing describes its metadata as defined in ThingFragment, and basic interactions defined as Properties, Actions and Events. The following interfaces are used for representing these interactions.
-    
                      
-
-    
                      
-      
                      The Interaction interface
                      
-      
                      
-        The Interaction interface is an abstract class to represent Thing interactions: Properties, Actions and Events.
-      
                      
-      
                      
-        The InteractionFragment dictionary holds the common properties of PropertyFragment, ActionFragment and EventFragment dictionaries used for initializing ThingProperty, ThingAction and ThingEvent objects in a ThingFragment dictionary used for creating an ExposedThing object.
-      
                      
-
-      
                      -        interface Interaction {
-          readonly attribute (Form or FrozenArray<Form>) forms;
-        };
-        Interaction includes InteractionFragment;
-      
                      
-      
                      
-        The forms read-only property represents the protocol bindings initialization data and is initialized by the WoT Runtime.
-      
                      
-    
                      
-
-    
                      
-      
                      The ThingProperty interface
                      
-      
                      
-        The ThingProperty interface is used in ConsumedThing and ExposedThing objects to represent Thing Property interactions.
-      
                      
-      
                      
-        The PropertyFragment dictionary is used for initializing Property objects in a ThingFragment dictionary used for creating an ExposedThing object. It MUST implement one of the DataSchema dictionaries.
-      
                      
-      
                      -        interface ThingProperty: Interaction {
-          // getter for PropertyFragment properties
-          getter any(DOMString name);
-          // get and set interface for the Property
-          Promise<any> read();
-          Promise<void> write(any value);
-        };
-        ThingProperty includes PropertyFragment;
-        ThingProperty includes Observable;
-      
                      
-      
                      
-        The ThingProperty interface contains all the properties defined on PropertyFragment as read-only properties.
-      
                      
-      
                      
-        The type read-only property represents the type definition for the Property as a DataSchema dictionary object.
-      
                      
-      
                      
-        The writable read-only property tells whether the Property value can be updated. If it is false, then the set(value) method SHOULD always reject.
-      
                      
-      
                      
-        The observable read-only property tells whether the Property supports subscribing to value change notifications. If it is false, then the subscribe() method SHOULD always fail.
-      
                      
-      
                      
-        The constant read-only property - defined in DataSchema - tells whether the Property value is a constant. If true, the set() and subscribe() methods SHOULD always fail.
-      
                      
-      
                      
-        The required read-only property  - defined in DataSchema - tells whether the Property should be always present on the ExposedThing object.
-      
                      
-      
                      
-        The read() method will fetch the value of the Property. Returns a Promise that resolves with the value, or rejects with an error.
-      
                      
-      
                      
-        The write() method will attempt to set the value of the Propertyspecified in the value argument whose type SHOULD match the one specified by the type property. Returns a Promise that resolves on success, or rejects on an error.
-      
                      
-    
                      
-
-    
                      
-      
                      The ThingAction interface
                      
-      
                      -        interface ThingAction: Interaction {
-          Promise<any> invoke(optional any inputValue);
-        };
-        ThingAction includes ActionFragment;
-      
                      
-      
                      
-        The invoke() method when invoked, starts the Action interaction with the input value provided by the inputValue argument. If inputValue is null, the action does not take any arguments and rejects if any arguments are provided. If the value is undefined, the action will ignore any arguments provided. Otherwise the type of inputValue SHOULD match the DataSchema definition in the input property. Returns a Promise that will reject with an error or will resolve with a value of type defined by the output property.
-      
                      
-    
                      
-
-    
                      The ThingEvent interface
                      
-      
                      -        interface ThingEvent: Interaction {
-        };
-        ThingEvent includes EventFragment;
-        ThingEvent includes ThingProperty;
-      
                      
-      
                      
-        Since ThingEvent implements Observable through the ThingProperty interface, event subscription is done by invoking the subscribe() method on the event object that returns a cancelable Subscription.
-      
                      
-    
                      
-
-    
                      The ExposedEvent interface
                      
-      
                      -        interface ExposedEvent: ThingEvent {
-          void emit(any payload);
-        };
-      
                      
-      
                       
                      The emit() method
                      
-        
                      
-          Emits an event that carries data specified by the payload argument.
-        
                      
-      
                      
-    
                      
-
-    
                      The value-matching algorithm
                      
-      
                      
-        The value-matching algorithm is applied to a value input in relation to a valueType property of type DataSchema, for instance the value and type properties of a PropertyFragment object, or the inputValue parameter to the invoke() method of a ThingAction object in relation to the same object. It executes the following steps:
-        
                        
-          
                      1. 
-            If valueType.type is not defined, or does not fully match a string enumerated in DataType, return false.
-          
                        2. 
-          
                      2. 
-            Otherwise, if valueType.type is "null": if value is null, return true, otherwise return false.
-          
                        3. 
-          
                      3. 
-            Otherwise, if valueType.type is "boolean": if value is either true or false, then return true, otherwise return false.
-          
                        4. 
-          
                      4. 
-            Otherwise, if valueType.type is "integer": if value is not an integer type defined by the underlying platform (such as long or long long), then return false, otherwise execute the following sub-steps:
-            
                          
-              
                        1. 
-                If valueType.minimum is defined and value is not greater or equal than that value, return false.
-              
                          2. 
-              
                        2. 
-                If valueType.maximum is defined and value is not less or equal than that value, return false.
-              
                          3. 
-              
                        3. 
-                Return true.
-              
                          4. 
-            
                        
-          
                        5. 
-          
                      5. 
-            Otherwise, if valueType.type is "number", if value is not an integer or floating point type defined by the underlying platform (such as long or long long or double), then return false, otherwise otherwise execute the following sub-steps:
-            
                          
-              
                        1. 
-                If valueType.minimum is defined and value is not greater or equal than that value, return false.
-              
                          2. 
-              
                        2. 
-                If valueType.maximum is defined and value is not less or equal than that value, return false.
-              
                          3. 
-              
                        3. 
-                Return true.
-              
                          4. 
-            
                        
-          
                        6. 
-          
                      6. 
-            Otherwise, if valueType.type is "string": if value is not a string type defined by the underlying platform, then return false, otherwise return true. In this case the algorithm expects a third parameter valueType.enum and runs the following sub-steps:
-            
                          
-              
                        • 
-                If valueType.enum is an array of strings, then if value fully matches one of the strings defined in the array, return true.
-              
                          • 
-              
                        • 
-                Otherwise, return false.
-              
                          • 
-            
                        
-          
                        7. 
-          
                      7. 
-            Otherwise, if valueType.type is "array", execute the following sub-steps:
-            
                          
-              
                        1. 
-                If value is not an array, return false.
-              
                          2. 
-              
                        2. 
-                If valueType.minItems is defined, and value does not contain at least valueType.minItems elements, return false.
-              
                          3. 
-              
                        3. 
-                If valueType.maxItems is defined, and value contains more than valueType.maxItems elements, return false.
-              
                          4. 
-              
                        4. 
-                Otherwise, if valueType.items is undefined, return false.
-              
                          5. 
-              
                        5. 
-                Otherwise, if valueType.items is null, return true (i.e. any type is accepted as array element, including heterogenous arrays).
-              
                          6. 
-              
                        6. 
-                Otherwise, for each element of the array value run the value-matching algorithm against the valueType.items object. If any of these runs returns false, then return false.
-              
                          7. 
-              
                        7. 
-                Otherwise, return true.
-              
                          8. 
-            
                        
-          
                        8. 
-          
                      8. 
-            Otherwise, if type is "object", execute the following sub-steps:
-            
                          
-              
                        1. 
-                If value is not an Object, return false.
-              
                          2. 
-              
                        2. 
-                If valueType.properties is not defined, return false.
-              
                          3. 
-              
                        3. 
-                If valueType.properties is null, return true (i.e. accept any object value).
-              
                          4. 
-              
                        4. 
-                For each string in the valueType.required array, if it does not match a property name in the value.properties object or in the value object, then return false.
-              
                          5. 
-              
                        5. 
-                For each property with name propName and value propDataSchema found in valueType.properties, run the following sub-steps:
-                
                            
-                  
                          1. 
-                    If the result of applying the value-matching algorithm on the value value[propName] and propDataSchema is false, then return false.
-                  
                            2. 
-                
                          
-              
                          6. 
-              
                        6. 
-                Return true.
-              
                          7. 
-            
                        
-          
                        9. 
-        
                      
-      
                      
-    
                      
-  
                      
-
-  
                      
-    
                      Observables
                      
-    
                      
-      Observables are proposed to be included in ECMAScript and are used for handling pushed data associated with various possible sources, for instance events, timers, streams, etc. A minimal required implementation is described here.
-    
                      
-    
                      
-      This section is informal and contains rather laconic information for implementations on what to support for interoperability.
-    
                      
-    
                      -      interface Observable {
-        Subscription subscribe(ObserverHandler handler,
-                               optional ErrorHandler errorHandler,
-                               optional OnComplete onComplete);
-      };
-      interface Subscription {
-        void unsubscribe();
-        readonly attribute boolean closed;
-      };
-      callback ObserverHandler = void (any value);
-      callback ErrorHandler = void (Error error);
-      callback OnComplete = void ();
-    
                      
-
-    
                      
-        The following callbacks can be provided when subscribing to an Observable:
-        
                        
-          
                      • 
-            The ObserverHandler callback takes the next sample for the data in the value argument.
-          
                        • 
-          
                      • 
-            The ErrorHandler callback takes an error in the value argument. It is called when an error occured in producing the data the client should know about.
-          
                        • 
-          
                      • 
-            The OnComplete callback is called when the data source has finished sending values.
-          
                        • 
-        
                      
-      
                      
-
-    
                      
-      
                      The Subscription interface
                      
-      
                      
-        Contains the closed property of type boolean that tells if the subscription is closed or active.
-      
                      
-      
                      
-        Also, contains the unsubscribe() method that cancels the subscription, i.e. makes a request to the underlying platform to stop receiving data from the source, and sets the closed property to false.
-      
                      
-    
                      
-
-    
                      
-      
                      The Observable interface
                      
-      
                      
-        The Observable interface enabled subscribing to pushed data notifications by the subscribe() method:
-      
                      
-      
                        
-        
                      • 
-          Initialize the data handler callback with the first function argument.
-        
                        • 
-        
                      • 
-          If the next argument is provided and is a function, initialize the error handling callback with that function, or throw on error.
-        
                        • 
-        
                      • 
-          If the third argument is provided and is a function, initialize the completion handler with that function, or throw on error.
-        
                        • 
-        
                      • 
-          After callback initializations, the implementation should request the underlying platform to provide data, error and completion notifications for the supported data source.
-        
                        • 
-      
                      
-    
                      
-  
                       
-
-
                       
                      Security and Privacy
                      
-
+  
                       
                      Security and Privacy
                      
   
                      
     A detailed discussion of security and privacy considerations for the Web of Things, including a threat model that can be adapted to various circumstances, is
     presented in the informative document [[!WOT-SECURITY-CONSIDERATIONS]].
@@ -1625,7 +1358,7 @@ 
                      Stale TD Security Risk
                      
     
                      
   
                      
 
-
                      
+  
                      
 
 
   
                       
                      Terminology and conventions
                      
@@ -1822,7 +1555,7 @@ 
                      Stale TD Security Risk
                      
 
   
                       
                      Acknowledgements
                      
     
                      
-      Special thanks to former editor Johannes Hund (until August 2017, when at Siemens AG) for developing this specification. Also, the editors would like to thank Dave Raggett, Matthias Kovatsch, Michael Koster and Michael McCool for their comments and guidance.
+      Special thanks to former editor Johannes Hund (until August 2017, when at Siemens AG) and Kazuaki Nimura (until December 2018) for developing this specification. Also, the editors would like to thank Dave Raggett, Matthias Kovatsch, Michael Koster, Elena Reshetova and Michael McCool for their comments, contributions and guidance.
     
                      
   
                      
 

From 92cd04b9be288d91cf9ce6279818e02cbcc3ee36 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Sun, 7 Apr 2019 18:44:29 +0300
Subject: [PATCH 308/464] Update ExposedThing methods and algorithms, update
 examples, update TD parsing and instantiating steps, the Changes and
 Acknowledgements sections.

Signed-off-by: Zoltan Kis 
---
 index.html | 326 +++++++++++++++++++++++++++++++++--------------------
 1 file changed, 202 insertions(+), 124 deletions(-)

diff --git a/index.html b/index.html
index 247f4310..5b213cd9 100644
--- a/index.html
+++ b/index.html
@@ -276,7 +276,7 @@ 
                      The WOT object
                      
         A ThingDescription is expected to be either a string representing a JSON-serialized object as described in the TD specification, or a JSON object representing a valid TD.
       
                      
       
                      
-        To parse a TD denoted as td, run the following steps:
+        To parse a TD (Thing Description) denoted as td, run the following steps:
         
                        
           
                      1. 
             If td is not a string, throw TypeError and terminate these steps.
@@ -299,13 +299,22 @@ 
                        The WOT object
                        
             If the td is not a string or an object, throw TypeError and terminate these steps.
           
                        2. 
           
                      2. 
-            If td is an object, let instance be td.
+            If td is a string, let json be the result of running the parse a TD steps on td. If that throws an error, re-throw the error and terminate these steps.
           
                        3. 
           
                      3. 
-            Otherwise, if td is a string, let instance be the result of running the parse a TD steps on td. If that fails by throwing an error, re-throw the error and terminate these steps.
+            If td is an object, let json be td.
           
                        4. 
           
                      4. 
-            Validate instance according to the TD instance validation. If that fails, throw SyntaxError and terminate these steps.
+            Let instance be an object with properties and default values defined in TD Thing.
+            
                        
+              As the TD specification owns the structure, validation and serialization of these objects, please refer to that specification on what properties need to be on the instance object. In this specification, instance is considered implementation-internal metadata, exposed for introspection.
+            
                        
+          
                        5. 
+          
                      5. 
+            Update the properties of instance also defined in json with the values defined in json.
+            
                        
+              When more efficient, implementations MAY reverse the last two steps, i.e. let instance be the result of adding json the missing properties with default values as defined in TD specification.
+            
                        
           
                        6. 
           
                      6. 
             Update instance with the WoT Runtime local settings.
@@ -317,10 +326,13 @@ 
                        The WOT object
                        
                 Initialize instance.security to the actual security scheme used by the WoT Runtime.
               
                        7. 
               
                      7. 
-                Update instance.forms with local settings specific to the WoT Runtime.
+                Update instance.forms with local settings specific to the WoT Runtime. Also, update the runtime-specific parts (if any) for the forms array of all elements in instance.properties, instance.actions and instance.events.
               
                        8.
                      • +
                    • + Validate instance according to the TD instance validation. If that fails, throw SyntaxError and terminate these steps. +
                    • Return instance.
                      • @@ -362,7 +374,10 @@

                      The WOT object

                      Let instance be the result of running the instantiate a TD steps on td. If that throws, re-throw the error and terminate these steps.
                    • - Let thing be a new ExposedThing object with thing.instance initialized with instance. + Let thing be a new ExposedThing object initialized with instance. The internal properties of thing.instance SHOULD be used for setting up the WoT Interactions based on the Thing Description as explained in [[!WOT-TD]]. This part is private to the implementations. +
                      • +
                    • + For each Property definition in thing.instance.properties initialize an internal slot for observers in order to store observe request data needed to notify the observers on value changes.
                    • Return thing. @@ -868,118 +883,158 @@

                      The ExposedThing interface

                      };
                      -

                      Constructing ExposedThing

                      +

                      Constructing ExposedThing

                      - The ExposedThing interface extends ConsumedThing. + The ExposedThing interface extends ConsumedThing and is constructed from a ThingInstance object.

                      - The ExposedThing objects SHOULD only be created by the produce() method which internally uses the ExposedThing constructor by providing a ThingInstance. This specification currently does not provide an API to expose a standalone ThingInstance produced by the instantiate a TD steps. A ThingInstance is exposed only on ConsumedThing and ExposedThing objects. However, an existing ThingInstance can be used or modified and used for constructing another ExposedThing object. This is the current way of adding and removing Property, Action and Event definitions as also illustrated in the examples. + The ExposedThing objects SHOULD only be created by the produce() method which internally uses the ExposedThing constructor with a ThingInstance object obtained either directly or by parsing a ThingDescription. +

                      +

                      + This specification currently does not provide an API to expose a standalone ThingInstance, as the instantiate a TD steps are private. A ThingInstance object is exposed only on ConsumedThing and ExposedThing. However, an existing ThingInstance 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 another ExposedThing object. This is the current way of adding and removing Property, Action and Event definitions, and later adding the service handler functions. This is illustrated in the examples.

                      The PropertyReadHandler callback

                      - A function that is called when an external request for reading a Property is received. It should return a Promise and resolves it with the value of the Property matching the name argument to the setPropertyReadHandler function, or rejects with an error if the property is not found or the value cannot be retrieved. -

                      -
                      - -
                      -

                      The PropertyWriteHandler callback

                      -

                      - A function that is called when an external request for writing a Property is received. It is given the requested new value as argument and should return a Promise which is resolved when the value of the Property that matches the name argument has been updated with value, or rejects with an error if the property is not found or the value cannot be updated. -

                      -

                      - Note that this function is invoked by implementations before the property is updated and it actually defines what to do when a write request is received. The code in this callback function can invoke the read() method to find out the old value of the property, if needed. Therefore the old value is not provided to this function. -

                      -
                      - -
                      -

                      The ActionHandler callback

                      -

                      - A function called with a parameters dictionary argument assembled by the WoT runtime based on the Thing Description and the external client request. It returns a Promise that rejects with an error or resolves if the action is successful. + A function that is called when an external request for reading a Property is received and defines what to do with such requests. It returns a Promise and resolves it when the value of the Property matching the name argument is obtained, or rejects with an error if the property is not found or the value cannot be retrieved.

                      The setPropertyReadHandler() method

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

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

                      - There SHOULD be at most one handler for any given Property and newly added handlers replace the old handlers. If no handler is initialized for any given Property, implementations SHOULD implement a default property read handler. + 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 MAY implement a default property read handler based on the Thing Description.

                      +
                      + +

                      Handling Property read requests

                      - When an external request for reading Property propertyName is received, the runtime SHOULD execute the following steps: + When a network request for reading Property propertyName is received by the implementation, run the following steps:

                      1. - Return a Promise promise and execute the next steps in parallel. + If a Property with propertyName does not exist, return ReferenceError in the reply and terminate these steps.
                      2. - If a Property with propertyName does not exist, reject promise with a ReferenceError and terminate these steps. + If there is a user provided read handler registered with setPropertyReadHandler(), invoke that wih propertyName, return the value with the reply and terminate these steps.
                      3. - Otherwise, if no read handler has been defined for propertyName, resolve promise with the value of the Property named propertyName provided by the runtime implementation and terminate these steps. + Otherwise, if there is a default read handler provided by the implementation, invoke it with propertyName, return the value with the reply and terminate these steps.
                      4. - Otherwise, invoke the read handler associated with propertyName. If it rejects, then reject promise with the same error, and resolve promise with the same value. + if there is no default handler defined by the implementation, return NotSupportedError with the reply and terminate these steps.

                      +

                      Handling Property observe requests

                      +

                      + When a network request for observing a Property propertyName is received by the implementation, run the following steps: +

                        +
                      1. + If a Property with propertyName does not exist, return ReferenceError in the reply and terminate these steps. +
                        2. +
                      2. + Save the request sender information to the Property's internal slot for observers in order to be able to notify about Property value changes. +
                        3. +
                      +

                      +
                      + +
                      +

                      The PropertyWriteHandler callback

                      +

                      + A function that is called when an external request for writing a Property is received and defines what to do with such requests. It expects the requested new value as argument and returns a Promise which is resolved when the value of the Property that matches the name argument has been updated with value, or rejects with an error if the property is not found or the value cannot be updated. +

                      +

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

                      +
                      +

                      The setPropertyWriteHandler() method

                      - Takes name as string argument and writeHandler as argument of type PropertyWriteHandler. Sets the handler function for writing the specified Property matched by name. Throws on error. Returns a reference to the same object for supporting chaining. + Takes name as string argument and writeHandler as argument of type PropertyWriteHandler. Sets the service handler for writing the specified Property matched by name. Throws on error. Returns a reference to this object for supporting chaining.

                      - There SHOULD be at most one write handler for any given Property and newly added handlers replace the old handlers. If no write handler is initialized for any given Property, implementations SHOULD implement default property update and notifying observers on change. + 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 MAY implement default property update and notifying observers on change, based on the Thing Description.

                      +
                      + +

                      Handling Property write requests

                      - When an external request for writing a Property propertyName with a new value value is received, the runtime SHOULD execute the following steps: + When a network request for writing a Property propertyName with a new value value is received, implementations SHOULD run the following update property steps, given propertyName, value and mode set to "single":

                      1. - Return a Promise promise and execute the next steps in parallel. + If a Property with propertyName does not exist, return ReferenceError in the reply and terminate these steps.
                      2. - If a Property with propertyName does not exist, reject promise with a ReferenceError and terminate these steps. + If there is a user provided write handler registered with setPropertyWriteHandler(), or if there is a default write handler, +
                          +
                        1. + Invoke the handler with propertyName. If it fails, return the error in the reply and terminate these steps. +
                          2. +
                        2. + Otherwise, if mode is "single", reply to the request with the new value, following to the Protocol Bindings. +
                          3. +
                        3. + For each item stored in the internal slot for observers of the Property with propertyName, send an observe reply with the new value attached. +
                        4. - Otherwise, if no write handler has been defined for propertyName, the runtime implementation SHOULD update the Property value with value, resolve promise and terminate these steps. + If there is no handler to handle the request, return NotSupportedError in the reply and terminate these steps.
                          5. +
                        +

                        +

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

                        1. - Otherwise, invoke the write handler associated with propertyName providing value as argument. If it rejects, then reject promise with the same error, and resolve promise with the same value. + For each property with key name and value value defined in propertyNames, run the update property steps with name, value and mode set to "multiple".
                          2. -
                        +
                      3. + Reply to the request (by sending a single or multiple replies) according to the Protocol Bindings defined for the Property. +
                        4. +

                        +
                      + +
                      +

                      The ActionHandler callback

                      +

                      + A function that is called when an external request for invoking an Action is received and defines what to do with such requests. It expects a parameters dictionary argument compiled by the implementation (based on the Thing Description and the external client request). It returns a Promise that rejects with an error or resolves if the action is successful.

                      The setActionHandler() method

                      - Takes name as string argument and action as argument of type ActionHandler. Sets the handler function for the specified Action matched by name. Throws on error. Returns a reference to the same object for supporting chaining. + Takes name as string argument and action as argument of type ActionHandler. Sets the handler function for the specified Action matched by name. Throws on error. Returns a reference to this object for supporting chaining.

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

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

                      +
                      + +

                      Handling Action requests

                      - When an external request for invoking the Action identified by name is received, the runtime SHOULD execute the following steps: + When a network request for invoking the Action identified by name is received, the runtime SHOULD execute the following steps:

                      1. - Return a Promise promise and execute the next steps in parallel. + If an Action identified by name does not exist, return ReferenceError in the reply and terminate these steps.
                      2. - If an Action identified by name does not exist, reject promise with a ReferenceError and terminate these steps. + If there is a user provided action handler registered with setActionHandler(), invoke that wih name, return the resulting value with the reply and terminate these steps.
                      3. - Otherwise, if no action handler has been defined for name, reject promise with a ReferenceError and terminate these steps. -
                        4. -
                      4. - Otherwise, invoke the Action handler associated with name. If it rejects with error, then reject promise with the same error, otherwise if it resolves with value, then resolve promise with the same value. + Otherwise return NotSupportedError with the reply and terminate these steps.

                      @@ -987,7 +1042,21 @@

                      The ActionHandler callback

                      The emitEvent() method

                      - void emitEvent(DOMString name, any data); + Takes name as string argument denoting an Event name, and a data argument of any type. +

                      +

                      + The emitEvent() method runs the following steps: +

                        +
                      1. + If invoking the method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps. +
                        2. +
                      2. + If an Event with the name name is not found in this.instance.events, throw NotFoundError and terminate these steps. +
                        3. +
                      3. + Make a request to the underlying platform to send an Event with data attached as property, using the Protocol Bindings, then terminate these steps. +
                        4. +

                      @@ -1005,7 +1074,7 @@

                      The ActionHandler callback

                      If invoking expose() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
                    • - Make a request to the underlying platform to attach protocol handlers and start serving external requests for WoT Interactions (read, write and observe Properties, invoke Actions and manage Event subscriptions), based on the 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.
                    • 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 terminate these steps. @@ -1049,18 +1118,14 @@

                      Examples

                      Below some ExposedThing interface examples are given.

                      - 
                      +      
                               try {
-          var temperatureValueDefinition = {
+          let temperaturePropertyDefinition = {
             type: "number",
             minimum: -50,
             maximum: 10000
           };
-          var temperaturePropertyDefinition = temperatureValueDefinition;
-          // add the 'forms' property
-          temperaturePropertyDefinition.forms = [ ... ];
-          var thing = WOT.produce({
-            name: "tempSensor",
+          let tdFragment = {
             properties: {
               temperature: temperaturePropertyDefinition
             },
@@ -1076,18 +1141,17 @@ 
                      Examples
                      
             },
             events: {
               onchange: temperatureValueDefinition
-            },
-            links: []
-          });
-          await thing.expose();
-          await wot.register("https://mydirectory.org", thing);
+            }
+          };
+          let thing1 = WOT.produce(tdFragment);
+          // TODO: add service handlers
+          await thing1.expose();
           // define Thing business logic
           setInterval( async () => {
             let mock = Math.random()*100;
-            let old = await thing["temperature"].read();
+            let old = await thing1.readProperty("temperature");
             if (old < mock) {
-              await thing["temperature"].write(mock);
-              thing.emitEvent("onchange", mock);
+              await thing1.writeProperty("temperature", mock);
             }
           }, 1000);
         } catch (err) {
@@ -1095,9 +1159,11 @@ 
                      Examples
                      
         }
       
                      
 
-      
                      +      
                               try {
-          var statusValueDefinition = {
+          // create a deep copy of thing1 instance
+          let instance = JSON.parse(JSON.stringify(thing1.instance));
+          const statusValueDefinition = {
             type: "object",
             properties: {
               brightness: {
@@ -1117,44 +1183,35 @@ 
                      Examples
                      
                 }
               }
           };
-          var statusPropertyDefinition = statusValueDefinition;
-          // add the 'forms' property
-          statusPropertyDefinition["forms"] = [];
-          var thing = WOT.produce({
-            name: "mySensor",
-            properties: {
-              brightness: {
-                type: "number",
-                minimum: 0.0,
-                maximum: 100.0,
-                required: true,
-              },
-              status: statusPropertyDefinition
-            },
-            actions: {
-              status: {
-                description: "Get status object",
-                input: null,
-                output: {
-                  status : statusValueDefinition;
-                },
-                forms: []
-              },
-            },
-            events: {
-              onstatuschange: statusValueDefinition;
+          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;
             },
-            links: []
-          });
-          thing.expose().then(() => {
-              thing.register();
+            forms: [...]
+          };
+          instance.events["onstatuschange"] = statusValueDefinition;
+          instance.forms = [...];  // update
+          var thing2 = WOT.produce(instance);
+          // TODO: add service handlers
+          await thing2.expose();
           });
         } catch (err) {
            console.log("Error creating ExposedThing: " + err);
         }
       
                      
 
-      
                      +      
                      +        // Typically a TD is obtained from somewhere, but let's write it now.
         let thingDescription = '{ \
           "name": "mySensor", \
           "@context": [ "http://www.w3.org/ns/td",\
@@ -1168,14 +1225,12 @@ 
                      Examples
                      
               "saref:TemperatureUnit": "degree_Celsius" \
           } } }';
         try {
-          // note that produce() fails if thingDescription contains error
+          // note that produce() fails if the TD contains an error
           let thing = WOT.produce(thingDescription);
           // Interactions were added from TD
           // WoT adds generic handler for reading any property
-          // define a specific handler for one property
-          let name = "examplePropertyName";
-          thing.setPropertyReadHandler(name, () => {
-            console.log("Handling read request for " + name);
+          // Define a specific handler for a Property
+          thing.setPropertyReadHandler("prop1", () => {
             return new Promise((resolve, reject) => {
                 let examplePropertyValue = 5;
                 resolve(examplePropertyValue);
@@ -1184,22 +1239,11 @@ 
                      Examples
                      
                 console.log("Error");
               });
           });
-          thing.expose();
+          await thing.expose();
         } catch(err) {
            console.log("Error creating ExposedThing: " + err);
         }
       
                      
-
-      
                      -        // fetch an external TD, e.g., to set up a proxy for that Thing
-        WOT.fetch("http://myservice.org/mySensor/description").then(td => {
-          // WOT.produce() ignores instance-specific metadata (security, form)
-          let thing = WOT.produce(td);
-          // Interactions were added from TD
-          // add server functionality
-          // ...
-        });
-      
                      
      
    
 
@@ -1523,14 +1567,42 @@ 
                      Stale TD Security Risk
                      
 
   
                      Changes
                      
     
                      
-      The following is a list of major changes to the document. For a complete list of changes, see the github change log. You can also view the recently closed issues.
-    
                      
-    
                      
+      The following is a list of major changes to the document. Major versions of this specification are the following:
       
                      
+      For a complete list of changes, see the github change log. You can also view the recently closed issues.
     
                      
   
                      
 
@@ -1539,6 +1611,12 @@ 
                      Stale TD Security Risk
                      
       The following problems are being discussed and need most attention:
     
                      
       
                        
+        
                      • 
+          The API for adding and removing Property, Action and Event definitions on ExposedThing.
+        
                        • 
+        
                      • 
+          Provide an API that is compatible with the Web Platform (browser implementations) and is efficient to implement in constrained runtimes.
+        
                        • 
         
                      • 
           Security related metadata (https://github.com/w3c/wot-scripting-api/issues/91).
         
                        • 
@@ -1555,7 +1633,7 @@ 
                        Stale TD Security Risk
                        
 
   
                         
                        Acknowledgements
                        
     
                        
-      Special thanks to former editor Johannes Hund (until August 2017, when at Siemens AG) and Kazuaki Nimura (until December 2018) for developing this specification. Also, the editors would like to thank Dave Raggett, Matthias Kovatsch, Michael Koster, Elena Reshetova and Michael McCool for their comments, contributions and guidance.
+      Special thanks to former editor Johannes Hund (until August 2017, when at Siemens AG) and Kazuaki Nimura (until December 2018) for developing this specification. Also, the editors would like to thank Dave Raggett, Matthias Kovatsch, Michael Koster, Elena Reshetova, Michael McCool as well as the other WoT WG members for their comments, contributions and guidance.
     
                        
   
                        
 

From 1bbfd71b0186943d3ec3d36c3271264f65d259b9 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Sun, 7 Apr 2019 19:23:13 +0300
Subject: [PATCH 309/464] Add missing ConsumedThing method specifications.

Signed-off-by: Zoltan Kis 
---
 index.html | 150 +++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 141 insertions(+), 9 deletions(-)

diff --git a/index.html b/index.html
index 5b213cd9..d2bac919 100644
--- a/index.html
+++ b/index.html
@@ -709,7 +709,7 @@ 
                        The readProperty() method
                        
             Make a request to the underlying platform (via the Protocol Bindings) to retrieve the value of the Property given by propertyName with optional URI templates given in options.uriVariables.
           
           
                      • 
-            If the request fails, return the error received from the Protocol Bindings and terminate these steps.
+            If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps.
           
                        • 
           
                      • 
             Let value be the result of the request.
@@ -721,14 +721,11 @@ 
                        The readProperty() method
                        
                 Based on the DataSchema definition, value MUST be a JSON value and comply to the data schema defined for the Property that is found in this.instance.properties[propertyName].
               
                        • 
               
                      • 
-                If this fails, return SyntaxError and terminate these steps.
-              
                        • 
-              
                      • 
-                Return value.
+                If this fails, throw SyntaxError, otherwise return value.
             
                        • 
           
           
                      • 
-            If these steps returned an error, reject promise with that error and terminate these steps.
+            If these above steps failed, reject promise with SyntaxError and terminate these steps.
           
                        • 
           
                      • 
             Otherwise resolve promise with value.
@@ -785,42 +782,177 @@ 
                        The readAllProperties() method
                        
     
                        
       
                        The writeProperty() method
                        
       
                        
+        Writes a single Property. Takes the following arguments: a string propertyName, a value value and an optional InteractionOptions options argument. It returns success or failure. It runs the following steps:
+        
                          
+          
                        1. 
+            Return a Promise promise and execute the next steps in parallel.
+          
                          2. 
+          
                        2. 
+            If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
+          
                          3. 
+          
                        3. 
+            Run the validate Property value steps on value. If that fails, reject promise with SyntaxError and terminate these steps.
+          
                          4. 
+          
                        4. 
+            Make a request to the underlying platform (via the Protocol Bindings) to write value to the Property given by propertyName with optional URI templates given in options.uriVariables.
+          
                          5. 
+          
                        5. 
+            If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps.
+          
                          6. 
+          
                        6. 
+            Otherwise resolve promise.
+          
                          7. 
+        
                        
       
                        
     
                        
 
     
                        
       
                        The writeMultipleProperties() method
                        
       
                        
+        Writes a multiple Property values with one request. Takes the following arguments: an object properties with keys as Property names and values as Property values and an optional argument options of type InteractionOptions. It returns success or failure. It runs the following steps:
+        
                          
+          
                        1. 
+            Return a Promise promise and execute the next steps in parallel.
+          
                          2. 
+          
                        2. 
+            If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
+          
                          3. 
+          
                        3. 
+            For each key name on properties, take its value as value and run the validate Property value steps on value. If that fails in for any name, reject promise with SyntaxError and terminate these steps.
+          
                          4. 
+          
                        4. 
+            Make a single request to the underlying platform (via the Protocol Bindings) to write the each Property given 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 NotSupportedError and terminate these steps.
+          
                          5. 
+          
                        5. 
+            If the request fails, return the error received from the Protocol Bindings and terminate these steps.
+          
                          6. 
+          
                        6. 
+            Otherwise resolve promise.
+          
                          7. 
+        
                        
       
                        
     
                        
 
     
                        
-      
                        The invokeAction() method
                        
+      
                        The subscribeProperty() method
                        
       
                        
+        Makes a request for Property value change notifications. Takes the following arguments: a string propertyName and an optional InteractionOptions options argument. It returns success or failure. It runs the following steps:
+        
                          
+          
                        1. 
+            Return a Promise promise and execute the next steps in parallel.
+          
                          2. 
+          
                        2. 
+            If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
+          
                          3. 
+          
                        3. 
+            Make a request to the underlying platform (via the Protocol Bindings) to observe Property identified by propertyName, with optional URI templates given in options.uriVariables.
+          
                          4. 
+          
                        4. 
+            If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps.
+          
                          5. 
+          
                        5. 
+            Otherwise resolve promise.
+          
                          6. 
+        
                        
       
                        
     
                        
 
     
                        
-      
                        The subscribeProperty() method
                        
+      
                        The unsubscribeProperty() method
                        
       
                        
+        Makes a request for unsubscribing from Property value change notifications. Takes the following arguments: a string propertyName and an optional InteractionOptions options argument. It returns success or failure. It runs the following steps:
+        
                          
+          
                        1. 
+            Return a Promise promise and execute the next steps in parallel.
+          
                          2. 
+          
                        2. 
+            If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
+          
                          3. 
+          
                        3. 
+            Make a request to the underlying platform (via the Protocol Bindings) to stop observing the Property identified by propertyName, with optional URI templates given in options.uriVariables.
+          
                          4. 
+          
                        4. 
+            If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps.
+          
                          5. 
+          
                        5. 
+            Otherwise resolve promise.
+          
                          6. 
+        
                        
       
                        
     
                        
 
     
                        
-      
                        The unsubscribeProperty() method
                        
+      
                        The invokeAction() method
                        
       
                        
+        Makes a request for invoking an Action and return the result. Takes the following arguments: a string actionName, an optional arguments parameters of type any and an optional InteractionOptions options argument. It returns the result of the Action or an error. It runs the following steps:
+        
                          
+          
                        1. 
+            Return a Promise promise and execute the next steps in parallel.
+          
                          2. 
+          
                        2. 
+            If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
+          
                          3. 
+          
                        3. 
+            Make a request to the underlying platform (via the Protocol Bindings) to invoke the Action identified by actionName, given params and optional URI templates in options.uriVariables.
+          
                          4. 
+          
                        4. 
+            If the request fails locally or returns an error over the network, reject promise with the error received from the Protocol Bindings and terminate these steps.
+          
                          5. 
+          
                        5. 
+            Otherwise let value be the result returned in the reply and run the validate Property value steps on it. If that fails, reject promise with SyntaxError and terminate these steps.
+          
                          6. 
+          
                        6. 
+            Reject promise with value.
+          
                          7. 
+        
                        
       
                        
     
                        
 
     
                        
       
                        The subscribeEvent() method
                        
       
                        
+        Makes a request for subscribing to Event notifications. Takes the following arguments: a string eventName and an optional InteractionOptions options argument. It returns success or failure. It runs the following steps:
+        
                          
+          
                        1. 
+            Return a Promise promise and execute the next steps in parallel.
+          
                          2. 
+          
                        2. 
+            If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
+          
                          3. 
+          
                        3. 
+            Make a request to the underlying platform (via the Protocol Bindings) to subscribe to an Event identified by eventName, with optional URI templates given in options.uriVariables.
+          
                          4. 
+          
                        4. 
+            If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps.
+          
                          5. 
+          
                        5. 
+            Otherwise resolve promise.
+          
                          6. 
+        
                        
       
                        
     
                        
 
     
                        
       
                        The unsubscribeEvent() method
                        
       
                        
+        Makes a request for unsubscribing from Event notifications. Takes the following arguments: a string eventName and an optional InteractionOptions options argument. It returns success or failure. It runs the following steps:
+        
                          
+          
                        1. 
+            Return a Promise promise and execute the next steps in parallel.
+          
                          2. 
+          
                        2. 
+            If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
+          
                          3. 
+          
                        3. 
+            Make a request to the underlying platform (via the Protocol Bindings) to unsubscribe from the Event identified by eventName, with optional URI templates given in options.uriVariables.
+          
                          4. 
+          
                        4. 
+            If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps.
+          
                          5. 
+          
                        5. 
+            Otherwise resolve promise.
+          
                          6. 
+        
                        
       
                        
     
                        
 

From 99cd379659193d31b04a8c4030e22de62f03a92b Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Mon, 8 Apr 2019 22:15:54 +0300
Subject: [PATCH 310/464] Editorial sweep: clarify sections, correct white
 spacing etc

Signed-off-by: Zoltan Kis 
---
 index.html | 450 +++++++++++++++++++++++++++--------------------------
 1 file changed, 228 insertions(+), 222 deletions(-)

diff --git a/index.html b/index.html
index d2bac919..c362d2ea 100644
--- a/index.html
+++ b/index.html
@@ -238,22 +238,42 @@
   
                        
     
                        The WOT object
                        
     
                        
-      The WOT object is the API entry point and it is exposed by an implementation of the WoT Runtime as a singleton. The WOT object contains the API methods for discovering, consuming and exposing a Thing.
+      Defines the API entry point exposed as a singleton and contains the API methods for discovering, consuming and producing a Thing based on Thing Descriptions.
     
                        
     
                        
        Browser implementations SHOULD use a namespace object such as navigator.wot. Node.js-like runtimes MAY provide the API object through the require() or import mechanism.
     
                        
     
                        -      typedef (USVString or object) ThingDescription;
-      typedef object ThingInstance;
       [SecureContext, Exposed=(Window,Worker)]
       interface WOT {
         ConsumedThing consume(ThingDescription td);
         ExposedThing produce(ThingDescription td);
         void discover(ThingDiscovery discovery);
       };
+      typedef (USVString or object) ThingDescription;
+      typedef object ThingInstance;
     
                        
 
+    
                         
                        The ThingDescription type
                        
+      
                        
+        Represents a Thing Description (TD). It is expected to be either a string representing a JSON-serialized object as described in the TD specification, or a parsed JSON object representing a valid TD.
+      
                        
+      
                        
+        To parse a TD (Thing Description) denoted as td, run the following steps:
+        
                          
+          
                        1. 
+            If td is not a string, throw TypeError and terminate these steps.
+          
                          2. 
+          
                        2. 
+            Let json be the result of invoking parse JSON from bytes on td. If that fails, throw SyntaxError and terminate these steps.
+          
                          3. 
+          
                        3. 
+            Return json.
+          
                          4. 
+        
                        
+      
                        
+    
                        
+
     
                         
                         Fetching a Thing Description
                        
       
                        
         The fetch() method has been part of this API in earlier versions. However, now fetching a TD should be done with an external method, such as the Fetch API or a HTTP client library.
@@ -271,32 +291,15 @@ 
                        The WOT object
                        
       
                      
     
 
-    
                       
                      Instantiating a Thing Description
                      
-      
                      
-        A ThingDescription is expected to be either a string representing a JSON-serialized object as described in the TD specification, or a JSON object representing a valid TD.
-      
                      
-      
                      
-        To parse a TD (Thing Description) denoted as td, run the following steps:
-        
                        
-          
                      1. 
-            If td is not a string, throw TypeError and terminate these steps.
-          
                        2. 
-          
                      2. 
-            Let json be the result of invoking JSON.parse() on td. If that fails, throw SyntaxError and terminate these steps.
-          
                        3. 
-          
                      3. 
-            Return json.
-          
                        4. 
-        
                      
-      
                      
+    
                       
                      The ThingInstance type
                      
       
                      
-        A ThingInstance denotes an object that represents a Thing Description in the local WoT Runtime.
+        Denotes an object that represents a TD Thing, i.e. a Thing Description initialized in the local WoT Runtime.
       
                      
       
                      
-        To instantiate a TD denoted as td, run the following steps:
+        To instantiate a TD, given td, run the following steps:
         
                        
           
                      1. 
-            If the td is not a string or an object, throw TypeError and terminate these steps.
+            If the td argument is not a string or an object, throw TypeError and terminate these steps.
           
                        2. 
           
                      2. 
             If td is a string, let json be the result of running the parse a TD steps on td. If that throws an error, re-throw the error and terminate these steps.
@@ -348,10 +351,10 @@ 
                        The WOT object
                        
             Let instance be the result of running the instantiate a TD steps on td. If that throws, re-throw the error and terminate these steps.
           
                        3. 
           
                      3. 
-            Let thing be a new ConsumedThing object with thing.instance initialized with instance.
+            Let thing be a new ConsumedThing object constructed with instance.
           
                        4. 
           
                      4. 
-            Make a request to the underlying platform to subscribe to TD change notifications.
+            Make a request to the underlying platform to subscribe to TD change notifications for this TD, connected to the thing.onchange event.
             
                        
               This mechanism needs to be defined more exactly in the Thing Description specification.
             
                        
@@ -374,7 +377,7 @@ 
                        The WOT object
                        
             Let instance be the result of running the instantiate a TD steps on td. If that throws, re-throw the error and terminate these steps.
           
                        5. 
           
                      5. 
-            Let thing be a new ExposedThing object initialized with instance. The internal properties of thing.instance SHOULD be used for setting up the WoT Interactions based on the Thing Description as explained in [[!WOT-TD]]. This part is private to the implementations.
+            Let thing be a new ExposedThing object constructed  with instance. The internal properties of thing.instance SHOULD be used for setting up the WoT Interactions based on the Thing Description as explained in [[!WOT-TD]]. This part is private to the implementations.
           
                        6. 
           
                      6. 
             For each Property definition in thing.instance.properties initialize an internal slot for observers in order to store observe request data needed to notify the observers on value changes.
@@ -386,20 +389,22 @@ 
                        The WOT object
                        
       
                        
     
                       
 
-    
                       
                      The discover() method
                      
+    
                       
                      Discovering Things
                      
       
                      
-        Starts the discovery process that will look for Thing Descriptions that match an optional filter which can specify the discovery method and match a specific source URL, a query and a template object. Check the  example code. Fires an event with a fetchable Thing Description URL whenever a matching Thing Description is found. It MUST run the following steps:
-        
                        
-          
                      1. 
-            If invoking discover() is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
-          
                        2. 
+        Discovery is making a request to retrieve a list of Thing Descriptions that match an optional filter. There are two equivalent ways to make discovery with this API:
+        
                      
+        
+
+        The discovery implementation will fire an event with a parsed ThingDescription object for each matching TD found, another event if the discovery process is known to have completed, and will fire an error event on errors.
       
                      
 
       
                      
@@ -441,7 +446,7 @@ 
                      The ThingFilter dictionary
                      
           The method property represents the discovery type that should be used in the discovery process. The possible values are defined by the DiscoveryMethod enumeration that MAY be extended by string values defined by solutions (with no guarantee of interoperability).
         
                      
         
                      
-          The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, for instance a Thing Directory (if method is "directory") or a Thing (otherwise).
+          The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, for instance the URL of a Thing Directory (if method is "directory") or that of a Thing (otherwise).
         
                      
         
                      
           The query property represents a query string accepted by the implementation, for instance a SPARQL or JSON query. Support may be implemented locally in the WoT Runtime or remotely as a service in a Thing Directory.
@@ -468,7 +473,7 @@ 
                      The ThingDiscovery interface
                      
             attribute EventHandler oncomplete;
           };
           interface ThingDescriptionEvent: Event {
-            readonly attribute object jsonTD;
+            readonly attribute object td;
           };
         
                      
         
                      
@@ -484,7 +489,7 @@ 
                      The ThingDiscovery interface
                      
           The stop() method 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 inactive.
         
                      
         
                      
-          The onfound event of type ThingDescriptionEvent is fired when a Thing Description has been discovered. It contains a JSON object jsonTD representing a parsed, but not yet instantiated Thing Description.
+          The onfound event of type ThingDescriptionEvent is fired when a Thing Description has been discovered. It contains a JSON object td representing a parsed, but not yet instantiated Thing Description.
         
                      
         
                      
           The onerror is of type ErrorEvent and is fired when the discovery process reports an error. It might not be supported by all discovery methods and endpoints.
@@ -494,7 +499,7 @@ 
                      The ThingDiscovery interface
                      
         
                      
 
         
                      
-          The start() method runs the following steps:
+          The start() method MUST run the following steps:
           
                        
             
                      1. 
               If this.filter is defined,
@@ -534,7 +539,7 @@ 
                        The ThingDiscovery interface
                        
                   Fetch the td.
                 
                        2. 
                 
                      2. 
-                   Let json be the result of running the parse a TD steps on td. If that fails, fire an onerror event with that error, discard td and continue the discovery process.
+                   Let json be the result of running the parse a TD steps on td. If that fails, fire an onerror event with that error, discard td and continue the discovery process.
                 
                        3. 
                 
                      3. 
                   If filter.query is defined, check if json is a match for the query. The matching algorithm is encapsulated by implementations. If that returns false, discard td and continue the discovery process.
@@ -543,21 +548,21 @@ 
                        The ThingDiscovery interface
                        
                   If filter.fragment is defined, for each property defined in it, check if that property exists in json.properties and has the same value. If this is false in any checks, discard td and continue the discovery process.
                 
                        4. 
                 
                      4. 
-                  Otherwise if td has not been discarded in the previous steps, fire an onfound event with its td property set to json.
+                  Otherwise if td has not been discarded in the previous steps, fire an onfound event with its td property set to json.
                 
                        5.
                    • - Whenever an error occurs during the discovery process, fire an onerror event, whose message property is set to DiscoveryError unless there was an error code provided by the Protocol Bindings, in which case set it to that value. + Whenever an error occurs during the discovery process, fire an onerror event, whose message property is set to DiscoveryError unless there was an error code provided by the Protocol Bindings, in which case set it to that value.
                    • - When the discovery process is completed, fire the oncomplete event, remove all event listeners and set the this.active property to false. + When the discovery process is completed, fire the oncomplete event, remove all event listeners and set the this.active property to false.

                      • - The stop() runs the following steps: + The stop() MUST run the following steps:

                      1. 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. @@ -571,6 +576,24 @@

                        The ThingDiscovery interface

                      + + +

                      The discover() method

                      +

                      + Starts the discovery process that will look for Thing Descriptions that match an optional filter which can specify the discovery method and match a specific source URL, a query and a template object. Check the example code. Fires an event with a fetchable Thing Description URL whenever a matching Thing Description is found. It MUST run the following steps: +

                        +
                      1. + If invoking discover() is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps. +
                        2. +
                      2. + If the argument discovery is not defined or it is not an instance of ThingDiscovery, throw TypeError and terminate these steps. +
                        3. +
                      3. + Invoke the discovery.start() method. +
                        4. +
                      +

                      +

                      Examples

                      @@ -580,8 +603,8 @@

                      The ThingDiscovery interface

                      url: "http://directory.wotservice.org" }; let discovery = new ThingDiscovery(discoveryFilter); - discovery.addEventListener("found", event => { - let td = event.jsonTD; + discovery.onfound = event => { + let td = event.td; console.log("Found Thing Description for " + td.name); let thing = WOT.consume(td); console.log("Thing name: " + thing.instance.name); @@ -602,7 +625,7 @@

                      The ThingDiscovery interface

                               let discovery = new ThingDiscovery({ method: "local" });
         discovery.onfound = event => {
-          let td = event.jsonTD;
+          let td = event.td;
           console.log("Found Thing Description for " + td.name);
           let thing = WOT.consume(td);
           console.log("Thing name: " + thing.instance.name);
@@ -646,32 +669,35 @@ 
                      The ConsumedThing interface
                      
     
                      
       
                      Constructing ConsumedThing
                      
       
                      
-        The instance read-only property is a JSON object that represents the Thing instance, i.e. the result of the instantiate a TD steps given the Thing Description of the Thing.
+        A ConsumedThing object is constructed by providing a ThingInstance object that initializes the instance attribute of ConsumedThing, without running the instantiate a TD steps.
       
                      
       
                      
-        The ConsumedThing objects SHOULD only be created by the consume() method which internally uses the ConsumedThing constructor by providing a ThingInstance. This specification currently does not provide an API to expose a standalone ThingInstance produced by the instantiate a TD steps. A ThingInstance is exposed only on ConsumedThing and ExposedThing objects. However, an existing ThingInstance can be used for constructing another ConsumedThing object that will basically be a deep clone and will represent the same remote Thing. A ThingInstance object can also be modified before feeding to the constructor, but then an inconsistent ConsumedThing would be created whose interactions may fail. A modified ThingInstance can be used in turn to create a new ExposedThing where the necessary request handlers can be added.
+        The ConsumedThing objects SHOULD only be created by the WOT.consume() method which internally uses this constructor by providing a ThingInstance object with a ThingInstance object obtained either directly or by parsing a ThingDescription and also running the instantiate a TD steps on it.
+      
                      
+      
                      
+        Note that a valid ThingInstance object can be provided either by the instantiate a TD steps, or also by external libraries that implement [[!WOT-TD]].
       
                      
     
                      
 
     
                      
-      
                      The TD change steps
                      
+      
                      Handling TD change
                      
       
                      
-        The onchange event is fired when the Thing Description has been changed by the source from where it was consumed.
+        The onchange event is fired when the Thing Description has been reported to be changed by the source from where it was consumed.
       
                      
       
                      
-        When the Thing Description is changed by the source and the underlying platform gets a change notification, run the following steps:
+        Whenever the the underlying platform gets a notification that the Thing Description has been changed by the source, run the following steps:
         
                        
           
                      1. 
-            Fetch the new Thing Description and let td be the result of running the parse a TD steps on it. If that throws an error, terminate these steps.
+            Fetch the new Thing Description and let td be the result of running the parse a TD steps on it. If that throws an error, terminate these steps.
           
                        2. 
           
                      2. 
-            Let instance be the result of running the instantiate a TD steps on td. If that throws an error, terminate these steps.
+            Let instance be the result of running the instantiate a TD steps on td in the context of this object. If that throws an error, terminate these steps.
           
                        3. 
           
                      3. 
             Replace this.instance with instance.
           
                        4. 
           
                      4. 
-            Fire an onchange event.
+            Fire an onchange event.
           
                        5. 
         
                      
       
                      
@@ -697,7 +723,7 @@ 
                      The WotListener callback
                      
     
                      
       
                      The readProperty() method
                      
       
                      
-        Reads a Property value. Takes the following arguments: a string propertyName and an optional InteractionOptions options argument. It returns a Property value represented as any type. It runs the following steps:
+        Reads a Property value. Takes the following arguments: a string propertyName and an optional InteractionOptions options argument. It returns a Property value represented as any type. It MUST run the following steps:
         
                        
           
                      1. 
             Return a Promise promise and execute the next steps in parallel.
@@ -737,7 +763,7 @@ 
                        The readProperty() method
                        
     
                        
       
                        The readMultipleProperties() method
                        
       
                        
-        Reads multiple Property values with one or multiple requests. Takes the following arguments: a sequence of strings propertyNames and an optional InteractionOptions options argument. It returns an object with keys from propertyNames and values returned by this algorithm. The method runs the following steps:
+        Reads multiple Property values with one or multiple requests. Takes the following arguments: a sequence of strings propertyNames and an optional InteractionOptions options argument. It returns an object with keys from propertyNames and values returned by this algorithm. The method MUST run the following steps:
         
                          
           
                        1. 
             Return a Promise promise and execute the next steps in parallel.
@@ -764,7 +790,7 @@ 
                          The readMultipleProperties() method
                          
     
                          
       
                          The readAllProperties() method
                          
       
                          
-        Reads all properties of the Thing with one or multiple requests. Takes an optional InteractionOptions options argument. It returns an object with keys from Property names and values returned by this algorithm. The method runs the following steps:
+        Reads all properties of the Thing with one or multiple requests. Takes an optional InteractionOptions options argument. It returns an object with keys from Property names and values returned by this algorithm. The method MUST run the following steps:
         
                            
           
                          1. 
             Let propertyNames be a sequence created from all the Property names of this Thing as found in this.instance.properties.
@@ -782,7 +808,7 @@ 
                            The readAllProperties() method
                            
     
                            
       
                            The writeProperty() method
                            
       
                            
-        Writes a single Property. Takes the following arguments: a string propertyName, a value value and an optional InteractionOptions options argument. It returns success or failure. It runs the following steps:
+        Writes a single Property. Takes the following arguments: a string propertyName, a value value and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps:
         
                              
           
                            1. 
             Return a Promise promise and execute the next steps in parallel.
@@ -809,7 +835,7 @@ 
                              The writeProperty() method
                              
     
                              
       
                              The writeMultipleProperties() method
                              
       
                              
-        Writes a multiple Property values with one request. Takes the following arguments: an object properties with keys as Property names and values as Property values and an optional argument options of type InteractionOptions. It returns success or failure. It runs the following steps:
+        Writes a multiple Property values with one request. Takes the following arguments: an object properties with keys as Property names and values as Property values and an optional argument options of type InteractionOptions. It returns success or failure. The method MUST run the following steps:
         
                                
           
                              1. 
             Return a Promise promise and execute the next steps in parallel.
@@ -836,7 +862,7 @@ 
                                The writeMultipleProperties() method
                                
     
                                
       
                                The subscribeProperty() method
                                
       
                                
-        Makes a request for Property value change notifications. Takes the following arguments: a string propertyName and an optional InteractionOptions options argument. It returns success or failure. It runs the following steps:
+        Makes a request for Property value change notifications. Takes the following arguments: a string propertyName and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps:
         
                                  
           
                                1. 
             Return a Promise promise and execute the next steps in parallel.
@@ -860,7 +886,7 @@ 
                                  The subscribeProperty() method
                                  
     
                                  
       
                                  The unsubscribeProperty() method
                                  
       
                                  
-        Makes a request for unsubscribing from Property value change notifications. Takes the following arguments: a string propertyName and an optional InteractionOptions options argument. It returns success or failure. It runs the following steps:
+        Makes a request for unsubscribing from Property value change notifications. Takes the following arguments: a string propertyName and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps:
         
                                    
           
                                  1. 
             Return a Promise promise and execute the next steps in parallel.
@@ -884,7 +910,7 @@ 
                                    The unsubscribeProperty() method
                                    
     
                                    
       
                                    The invokeAction() method
                                    
       
                                    
-        Makes a request for invoking an Action and return the result. Takes the following arguments: a string actionName, an optional arguments parameters of type any and an optional InteractionOptions options argument. It returns the result of the Action or an error. It runs the following steps:
+        Makes a request for invoking an Action and return the result. Takes the following arguments: a string actionName, an optional arguments parameters of type any and an optional InteractionOptions options argument. It returns the result of the Action or an error. The method MUST run the following steps:
         
                                      
           
                                    1. 
             Return a Promise promise and execute the next steps in parallel.
@@ -911,7 +937,7 @@ 
                                      The invokeAction() method
                                      
     
                                      
       
                                      The subscribeEvent() method
                                      
       
                                      
-        Makes a request for subscribing to Event notifications. Takes the following arguments: a string eventName and an optional InteractionOptions options argument. It returns success or failure. It runs the following steps:
+        Makes a request for subscribing to Event notifications. Takes the following arguments: a string eventName and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps:
         
                                        
           
                                      1. 
             Return a Promise promise and execute the next steps in parallel.
@@ -935,7 +961,7 @@ 
                                        The subscribeEvent() method
                                        
     
                                        
       
                                        The unsubscribeEvent() method
                                        
       
                                        
-        Makes a request for unsubscribing from Event notifications. Takes the following arguments: a string eventName and an optional InteractionOptions options argument. It returns success or failure. It runs the following steps:
+        Makes a request for unsubscribing from Event notifications. Takes the following arguments: a string eventName and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps:
         
                                          
           
                                        1. 
             Return a Promise promise and execute the next steps in parallel.
@@ -1001,9 +1027,6 @@ 
                                          The ExposedThing interface
                                          
       The ExposedThing interface is the server API to operate the Thing that allows defining request handlers, Property, Action, and Event interactions.
     
                                          
     
                                          -      callback PropertyReadHandler = Promise<any>();
-      callback PropertyWriteHandler = Promise<void>(any value);
-      callback ActionHandler = Promise<any>(any parameters);
       [Constructor(ThingInstance instance), SecureContext, Exposed=(Window,Worker)]
       interface ExposedThing: ConsumedThing {
         ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
@@ -1013,17 +1036,23 @@ 
                                          The ExposedThing interface
                                          
         Promise<void> expose();
         Promise<void> destroy();
       };
+      callback PropertyReadHandler = Promise<any>();
+      callback PropertyWriteHandler = Promise<void>(any value);
+      callback ActionHandler = Promise<any>(any parameters);
     
                                          
     
                                          
       
                                          Constructing ExposedThing
                                          
       
                                          
-        The ExposedThing interface extends ConsumedThing and is constructed from a ThingInstance object.
+        The ExposedThing interface extends ConsumedThing and is constructed by providing a ThingInstance object that initializes the instance attribute of ExposedThing, without running the instantiate a TD steps.
+      
                                          
+      
                                          
+        The ExposedThing objects SHOULD only be created by the produce() method which internally uses the ExposedThing constructor with a ThingInstance object obtained either directly or by parsing a ThingDescription and also running the instantiate a TD steps on it.
       
                                          
       
                                          
-        The ExposedThing objects SHOULD only be created by the produce() method which internally uses the ExposedThing constructor with a ThingInstance object obtained either directly or by parsing a ThingDescription.
+        Note that a valid ThingInstance object can be provided either by the instantiate a TD steps, or also by external libraries that implement [[!WOT-TD]].
       
                                          
       
                                          
-         This specification currently does not provide an API to expose a standalone ThingInstance, as the instantiate a TD steps are private. A ThingInstance object is exposed only on ConsumedThing and ExposedThing. However, an existing ThingInstance 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 another ExposedThing object. This is the current way of adding and removing Property, Action and Event definitions, and later adding the service handler functions. This is illustrated in the examples.
+         Note that an existing ThingInstance 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 another ExposedThing object. This is the current way of adding and removing Property, Action and Event definitions, and later adding the service handler functions. This is illustrated in the examples.
       
                                          
     
                                          
 
@@ -1174,10 +1203,7 @@ 
                                          The ActionHandler callback
                                          
 
     
                                           
                                          The emitEvent() method
                                          
       
                                          
-        Takes name as string argument denoting an Event name, and a data argument of any type.
-      
                                          
-      
                                          
-        The emitEvent() method runs the following steps:
+        Takes name as string argument denoting an Event name, and a data argument of any type. The method MUST run the following steps:
         
                                            
           
                                          1. 
             If invoking the method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
@@ -1194,10 +1220,7 @@ 
                                            The ActionHandler callback
                                            
 
     
                                             
                                            The expose() method
                                            
       
                                            
-        Start serving external requests for the Thing, so that WoT Interactions using Properties, Actions and Events will be possible.
-      
                                            
-      
                                            
-        The expose() method MUST run the following 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:
         
                                              
           
                                            1. 
             Return a Promise promise and execute the next steps in parallel.
@@ -1220,10 +1243,7 @@ 
                                              The ActionHandler callback
                                              
 
     
                                               
                                              The destroy() method
                                              
       
                                              
-        Stop serving external requests for the Thing and destroy the object. Note that eventual unregistering should be done before invoking this method.
-      
                                              
-      
                                              
-        The destroy() method MUST run the following steps:
+        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:
         
                                                
           
                                              1. 
             Return a Promise promise and execute the next steps in parallel.
@@ -1380,160 +1400,146 @@ 
                                                Examples
                                                
   
                                               
 
   
                                               
                                              Security and Privacy
                                              
-  
                                              
-    A detailed discussion of security and privacy considerations for the Web of Things, including a threat model that can be adapted to various circumstances, is
-    presented in the informative document [[!WOT-SECURITY-CONSIDERATIONS]].
-    This section discusses only security and privacy risks and possible mitigations
-    directly relevant to the scripts and WoT Scripting API.
-  
                                              
-
-  
                                              
-    A suggested set of best practices to improve security for WoT devices and
-    services has been documented in [[!WOT-SECURITY-BEST-PRACTICES]].
-    That document may be updated as security measures evolve.
-    Following these practices does not guarantee security,
-    but it might help avoid common known vulnerabilities.
-  
                                              
-
-  
                                              
-    The WoT security risks and possible mitigations are concerning the following groups:
-    
                                                
-      
                                              • 
-        Implementors of WoT Runtimes that do not implement a Scripting Runtime.
-        The [[!WOT-ARCHITECTURE]] document provides generic security guidelines
-        for this group.
-      
                                                • 
-      
                                              • 
-        Implementors of the WoT Scripting API in a WoT Scripting Runtime. This is the main scope and is covered in the
-        
-        Scripting Runtime Security and Privacy Risks sub-section that
-        contains normative text regarding security.
-      
                                                • 
-      
                                              • 
-        WoT script developers, covered in the
-        
-        Script Security and Privacy Risks sub-section that contains
-        informative recommendations concerning security.
-      
                                                • 
-    
                                              
-  
                                              
-
-  
                                              
-    
                                              Scripting Runtime Security and Privacy Risks
                                              
     
                                              
-      This section is normative and contains specific risks relevant for the WoT Scripting Runtime.
+      A detailed discussion of security and privacy considerations for the Web of Things, including a threat model that can be adapted to various circumstances, is
+      presented in the informative document [[!WOT-SECURITY-CONSIDERATIONS]].
+      This section discusses only security and privacy risks and possible mitigations
+      directly relevant to the scripts and WoT Scripting API.
+    
                                              
+    
                                              
+      A suggested set of best practices to improve security for WoT devices and
+      services has been documented in [[!WOT-SECURITY-BEST-PRACTICES]].
+      That document may be updated as security measures evolve.
+      Following these practices does not guarantee security,
+      but it might help avoid common known vulnerabilities.
+    
                                              
+    
                                              
+      The WoT security risks and possible mitigations are concerning the following groups:
+      
                                                
+        
                                              • 
+          Implementors of WoT Runtimes that do not implement a Scripting Runtime.
+          The [[!WOT-ARCHITECTURE]] document provides generic security guidelines
+          for this group.
+        
                                                • 
+        
                                              • 
+          Implementors of the WoT Scripting API in a WoT Scripting Runtime. This is the main scope and is covered in the
+          
+          Scripting Runtime Security and Privacy Risks sub-section that
+          contains normative text regarding security.
+        
                                                • 
+        
                                              • 
+          WoT script developers, covered in the
+          
+          Script Security and Privacy Risks sub-section that contains
+          informative recommendations concerning security.
+        
                                                • 
+      
                                              
     
                                              
 
-    
                                              
-     
                                              Corrupted Input Security and Privacy Risk
                                              
-     
                                              
-        A typical way to compromise any process is to send it a corrupted input
-        via one of the exposed interfaces. This can be done to a script instance
-        using WoT interface it exposes.
+    
                                              
+      
                                              Scripting Runtime Security and Privacy Risks
                                              
+      
                                              
+        This section is normative and contains specific risks relevant for the WoT Scripting Runtime.
       
                                              
-      
                                              Mitigation:
                                              
-          Implementors of this API SHOULD perform validation on all script inputs.
-          In addition to input validation,
-          fuzzing should be used
-          to verify that the input processing is done correctly.
-          There are many tools and techniques in existence to do such validation.
-          More details can be found in [[!WOT-SECURITY-TESTING]].
-      
                                              
-    
                                              
 
+      
                                              
+        
                                              Corrupted Input Security and Privacy Risk
                                              
+        
                                              
+          A typical way to compromise any process is to send it a corrupted input
+          via one of the exposed interfaces. This can be done to a script instance
+          using WoT interface it exposes.
+        
                                              
+        
                                              Mitigation:
                                              
+          Implementors of this API SHOULD perform validation on all script inputs. In addition to input validation, fuzzing should be used to verify that the input processing is done correctly. There are many tools and techniques in existence to do such validation. More details can be found in [[!WOT-SECURITY-TESTING]].
+        
                                              
+      
                                              
 
-    
                                              
-     
                                              Physical Device Direct Access Security and Privacy Risk
                                              
-     
                                              
-        In case a script is compromised or misbehaving, the underlying physical device
-        (and potentially surrounded environment) can be damaged if a script can use directly exposed native device interfaces. If such interfaces lack safety checks on their inputs, they might bring the underlying physical device (or environment) to an unsafe state (i.e. device overheats and explodes).
-      
                                              
-      
                                              Mitigation:
                                              
-         The WoT Scripting Runtime SHOULD avoid directly exposing the native device interfaces to the script developers. Instead, a WoT Scripting Runtime should provide a hardware abstraction layer for accessing the native device interfaces. Such hardware abstraction layer should refuse to execute commands that might put the device (or environment) to an unsafe state.
-         Additionally, in order to reduce the damage to a physical WoT device in cases a script gets compromised, it is important to minimize the number of interfaces that are exposed or accessible to a particular script based on its functionality.
-      
                                              
-    
                                              
+      
                                              
+        
                                              Physical Device Direct Access Security and Privacy Risk
                                              
+        
                                              
+          In case a script is compromised or misbehaving, the underlying physical device (and potentially surrounded environment) can be damaged if a script can use directly exposed native device interfaces. If such interfaces lack safety checks on their inputs, they might bring the underlying physical device (or environment) to an unsafe state (i.e. device overheats and explodes).
+        
                                              
+        
                                              Mitigation:
                                              
+          The WoT Scripting Runtime SHOULD avoid directly exposing the native device interfaces to the script developers. Instead, a WoT Scripting Runtime should provide a hardware abstraction layer for accessing the native device interfaces. Such hardware abstraction layer should refuse to execute commands that might put the device (or environment) to an unsafe state.
+          Additionally, in order to reduce the damage to a physical WoT device in cases a script gets compromised, it is important to minimize the number of interfaces that are exposed or accessible to a particular script based on its functionality.
+        
                                              
+      
                                              
 
-    
                                              
-     
                                              Provisioning and Update Security Risk
                                              
-     
                                              
-        If the WoT Scripting Runtime supports post-manufacturing provisioning
-        or updates of scripts, WoT Scripting Runtime or any related data
-        (including security credentials), it can be a major attack vector.
-        An attacker can try to modify any above described element
-        during the update or provisioning process or simply
-        provision attacker's code and data directly.
-      
                                              
-      
                                              Mitigation:
                                              
-          Post-manufacturing provisioning or update of scripts,
-          WoT Scripting Runtime or any related data should be done in a secure fashion.
-          A set of recommendations for secure update and post-manufacturing
-          provisioning can be found in [[!WOT-SECURITY-CONSIDERATIONS]].
-       
                                              
-    
                                              
+      
                                              
+        
                                              Provisioning and Update Security Risk
                                              
+        
                                              
+          If the WoT Scripting Runtime supports post-manufacturing provisioning
+          or updates of scripts, WoT Scripting Runtime or any related data
+          (including security credentials), it can be a major attack vector.
+          An attacker can try to modify any above described element
+          during the update or provisioning process or simply
+          provision attacker's code and data directly.
+        
                                              
+        
                                              Mitigation:
                                              
+            Post-manufacturing provisioning or update of scripts,
+            WoT Scripting Runtime or any related data should be done in a secure fashion.
+            A set of recommendations for secure update and post-manufacturing
+            provisioning can be found in [[!WOT-SECURITY-CONSIDERATIONS]].
+        
                                              
+      
                                              
 
-   
                                              
-     
                                              Security Credentials Storage Security and Privacy Risk
                                              
-     
                                              
-        Typically the WoT Scripting Runtime needs to store the security credentials that are provisioned to a WoT device to operate in WoT network. If an attacker can compromise the confidentiality or integrity of these credentials, then it can obtain access to the WoT assets, impersonate WoT things or devices or create Denial-Of-Service (DoS) attacks.
-      
                                              
-      
                                              Mitigation:
                                              
+      
                                              
+        
                                              Security Credentials Storage Security and Privacy Risk
                                              
+        
                                              
+          Typically the WoT Scripting Runtime needs to store the security credentials that are provisioned to a WoT device to operate in WoT network. If an attacker can compromise the confidentiality or integrity of these credentials, then it can obtain access to the WoT assets, impersonate WoT things or devices or create Denial-Of-Service (DoS) attacks.
+        
                                              
+        
                                              Mitigation:
                                              
           The WoT Scripting Runtime should securely store the provisioned security credentials, guaranteeing their integrity and confidentiality.
           In case there are more than one tenant on a single WoT-enabled device, a WoT Scripting Runtime should guarantee isolation of each tenant provisioned security credentials.
           Additionally, in order to minimize a risk that provisioned security credentials get compromised, the WoT Scripting Runtime should not expose any API for scripts to query the provisioned security credentials.
-      
                                              
+        
                                              
+      
                                              
     
                                              
-  
                                              
-
-  
                                              
-    
                                              Script Security and Privacy Risks
                                              
-    
                                              
-      This section describes specific risks relevant for script developers.
-    
                                              
 
-    
                                              
-     
                                              Corrupted Script Input Security and Privacy Risk
                                              
-     
                                              
-        A script instance may receive data formats defined by the TD, or data formats defined by the applications. While the WoT Scripting Runtime SHOULD perform validation on all input fields defined by the TD, scripts may be still exploited by input data.
+    
                                              
+      
                                              Script Security and Privacy Risks
                                              
+      
                                              
+        This section describes specific risks relevant for script developers.
       
                                              
-      
                                              Mitigation:
                                              
-          Script developers should perform validation on all application defined script inputs. In addition to input validation,
-          fuzzing could be used
-          to verify that the input processing is done correctly.
-          There are many tools and techniques in existence to do such validation.
-          More details can be found in [[!WOT-SECURITY-TESTING]].
-      
                                              
-    
                                              
 
-    
                                              
-     
                                              Denial Of Service Security Risk
                                              
-     
                                              
-        If a script performs a heavy functional processing on received requests before the request is authenticated, it presents a great risk for Denial-Of-Service (DOS) attacks.
-     
                                              
-     
                                              Mitigation:
                                              
-        Scripts should avoid heavy functional processing without prior successful
-        authentication of requestor. The set of recommended authentication mechanisms
-        can be found in [[!WOT-SECURITY-BEST-PRACTICES]].
-      
                                              
-    
                                              
+      
                                              
+        
                                              Corrupted Script Input Security and Privacy Risk
                                              
+        
                                              
+          A script instance may receive data formats defined by the TD, or data formats defined by the applications. While the WoT Scripting Runtime SHOULD perform validation on all input fields defined by the TD, scripts may be still exploited by input data.
+        
                                              
+        
                                              Mitigation:
                                              
+          Script developers should perform validation on all application defined script inputs. In addition to input validation, fuzzing could be used to verify that the input processing is done correctly. There are many tools and techniques in existence to do such validation. More details can be found in [[!WOT-SECURITY-TESTING]].
+        
                                              
+      
                                              
 
-    
                                              
-     
                                              Stale TD Security Risk
                                              
-     
                                              
-        During the lifetime of a WoT network, a content of a TD can change.
-        This includes its identifier, which might not be an immutable one and might be updated periodically.
-     
                                              
-     
                                              Mitigation:
                                              
-        Scripts should use this API to subscribe for notifications
-        on TD changes and do not rely on TD values to remain persistent.
-     
                                              
-      
                                              
-        While stale TDs can present a potential problem for WoT network operation,
-        it might not be a security risk.
-      
                                              
-    
                                              
-  
                                              
+      
                                              
+        
                                              Denial Of Service Security Risk
                                              
+        
                                              
+          If a script performs a heavy functional processing on received requests before the request is authenticated, it presents a great risk for Denial-Of-Service (DOS) attacks.
+        
                                              
+        
                                              Mitigation:
                                              
+          Scripts should avoid heavy functional processing without prior successful
+          authentication of requestor. The set of recommended authentication mechanisms
+          can be found in [[!WOT-SECURITY-BEST-PRACTICES]].
+        
                                              
+      
                                              
 
+      
                                              
+        
                                              Stale TD Security Risk
                                              
+        
                                              
+          During the lifetime of a WoT network, a content of a TD can change.
+          This includes its identifier, which might not be an immutable one and might be updated periodically.
+        
                                              
+        
                                              Mitigation:
                                              
+          Scripts should use this API to subscribe for notifications
+          on TD changes and do not rely on TD values to remain persistent.
+        
                                              
+        
                                              
+          While stale TDs can present a potential problem for WoT network operation,
+          it might not be a security risk.
+        
                                              
+      
                                              
+    
                                              
   
                                              
 
 
@@ -1759,7 +1765,7 @@ 
                                              Stale TD Security Risk
                                              
       
   
                                            
 
-
                                            
+
                                             
                                            Full Web IDL
                                            
   
 
                                            
 

From f47906a812ee9f4f2da67858cf025de679df6691 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Wed, 10 Apr 2019 22:49:36 +0300
Subject: [PATCH 311/464] Refactor discovery without events

Signed-off-by: Zoltan Kis 
---
 index.html | 406 ++++++++++++++++++++++++++---------------------------
 1 file changed, 202 insertions(+), 204 deletions(-)

diff --git a/index.html b/index.html
index c362d2ea..36f995d8 100644
--- a/index.html
+++ b/index.html
@@ -248,7 +248,7 @@ 
                                            The WOT object
                                            
       interface WOT {
         ConsumedThing consume(ThingDescription td);
         ExposedThing produce(ThingDescription td);
-        void discover(ThingDiscovery discovery);
+        ThingDiscovery discover(optional ThingFilter filter);
       };
       typedef (USVString or object) ThingDescription;
       typedef object ThingInstance;
@@ -345,7 +345,7 @@ 
                                            The WOT object
                                            
 
     
                                             
                                             The consume() method
                                            
       
                                            
-        Accepts an td argument and returns a ConsumedThing object that represents a client interface to operate with the Thing. It MUST run the following steps:
+        Accepts an td argument and returns a ConsumedThing object that represents a client interface to operate with the Thing. The method MUST run the following steps:
         
                                              
           
                                            1. 
             Let instance be the result of running the instantiate a TD steps on td. If that throws, re-throw the error and terminate these steps.
@@ -368,10 +368,10 @@ 
                                              The WOT object
                                              
 
     
                                               
                                              The produce() method
                                              
       
                                              
-        Accepts a td argument and returns an ExposedThing object that extends ConsumedThing with a server interface, i.e. the ability to define request handlers. It MUST run the following steps:
+        Accepts a td argument and returns an ExposedThing object that extends ConsumedThing with a server interface, i.e. the ability to define request handlers. The method MUST run the following steps:
         
                                                
           
                                              1. 
-            If invoking produce() is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
+            If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
           
                                                2. 
           
                                              2. 
             Let instance be the result of running the instantiate a TD steps on td. If that throws, re-throw the error and terminate these steps.
@@ -380,7 +380,7 @@ 
                                                The WOT object
                                                
             Let thing be a new ExposedThing object constructed  with instance. The internal properties of thing.instance SHOULD be used for setting up the WoT Interactions based on the Thing Description as explained in [[!WOT-TD]]. This part is private to the implementations.
           
                                                3. 
           
                                              3. 
-            For each Property definition in thing.instance.properties initialize an internal slot for observers in order to store observe request data needed to notify the observers on value changes.
+            For each Property definition in thing.instance.properties initialize an internal observer list in order to store observe request data needed to notify the observers on value changes.
           
                                                4. 
           
                                              4. 
             Return thing.
@@ -389,212 +389,221 @@ 
                                                The WOT object
                                                
       
                                                
     
                                               
 
-    
                                               
                                              Discovering Things
                                              
+    
                                               
                                              The discover() method
                                              
       
                                              
-        Discovery is making a request to retrieve a list of Thing Descriptions that match an optional filter. There are two equivalent ways to make discovery with this API:
-        
                                                
+        Starts the discovery process that will provide parsed ThingDescription objects for Thing Descriptions that match an optional filter argument which can specify the discovery method and match a specific source URL, a query and a template object. Check the  example code. The method MUST run the following steps:
+        
                                                  
           
                                                1. 
-            By creating a ThingDiscovery object and invoking its start() method.
+            If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
           
                                                  2. 
           
                                                2. 
-            By creating a ThingDiscovery object and invoking the WOT.discover() method on it.
-            
                                                  
-              This is provided for consistency with the factory methods WOT.consume() and WOT.produce().
-            
                                                  
-          
                                                  3. 
-        
                                              
-
-        The discovery implementation will fire an event with a parsed ThingDescription object for each matching TD found, another event if the discovery process is known to have completed, and will fire an error event on errors.
-      
                                              
-
-      
                                              
-        
                                              The DiscoveryMethod enumeration
                                              
-        
                                              -          typedef DOMString DiscoveryMethod;
-        
                                              
-        
                                              
-          DiscoveryMethod represents the discovery type to be used:
-        
                                              
-        
                                                
-          
                                              • "any" does not provide any restriction
                                                • 
-          
                                              • 
-            "local" for discovering Things defined in the same device or connected to the device by wired or wireless means.
+            Construct a ThingDiscovery object discovery with filter.
           
                                                • 
           
                                              • 
-            "directory" for discovery based on a service provided by a Thing Directory.
+            Invoke the discovery.start() method.
           
                                                • 
           
                                              • 
-            "multicast" for discovering Things in the device's network by using a supported multicast protocol.
+            Return discovery.
           
                                                • 
-        
                                              
-      
                                              
-
-      
                                              
-        
                                              The ThingFilter dictionary
                                              
-        
                                              
-          The ThingFilter dictionary that represents the constraints for discovering Things as key-value pairs.
-        
                                              
-        
                                              -          dictionary ThingFilter {
-            (DiscoveryMethod or DOMString) method = "any";
-            USVString? url;
-            USVString? query;
-            object? fragment;
-          };
-        
                                              
-        
                                              
-          The method property represents the discovery type that should be used in the discovery process. The possible values are defined by the DiscoveryMethod enumeration that MAY be extended by string values defined by solutions (with no guarantee of interoperability).
-        
                                              
-        
                                              
-          The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, for instance the URL of a Thing Directory (if method is "directory") or that of a Thing (otherwise).
-        
                                              
-        
                                              
-          The query property represents a query string accepted by the implementation, for instance a SPARQL or JSON query. Support may be implemented locally in the WoT Runtime or remotely as a service in a Thing Directory.
-        
                                              
-        
                                              
-          The fragment property represents a template object used for matching property by property against discovered Things.
-        
                                              
-      
                                              
+        
                                            
+      
                                            
+    
                                             
+  
                                             
 
-      
                                            
-        
                                            The ThingDiscovery interface
                                            
-        
                                            
-          Constructed given a filter and provides the events and methods controlling the discovery process.
-        
                                            
-        
                                            -          [Constructor(optional ThingFilter filter), SecureContext, Exposed=(Window,Worker)]
-          interface ThingDiscovery: EventTarget {
-            readonly attribute ThingFilter? filter;
-            readonly attribute boolean active;
-            void start();
-            void stop();
-            attribute EventHandler onfound;
-            attribute EventHandler onerror;
-            attribute EventHandler oncomplete;
-          };
-          interface ThingDescriptionEvent: Event {
-            readonly attribute object td;
-          };
-        
                                            
-        
                                            
-          The filter property represents the discovery filter of type ThingFilter specified for the discovery.
-        
                                            
-        
                                            
-          The active property represents whether the discovery is actively ongoing or not (i.e. it has either been completed or stopped).
-        
                                            
-        
                                            
-          The start() method starts the discovery process, or if the discovery is already active, does nothing.
-        
                                            
-        
                                            
-          The stop() method 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 inactive.
-        
                                            
-        
                                            
-          The onfound event of type ThingDescriptionEvent is fired when a Thing Description has been discovered. It contains a JSON object td representing a parsed, but not yet instantiated Thing Description.
-        
                                            
-        
                                            
-          The onerror is of type ErrorEvent and is fired when the discovery process reports an error. It might not be supported by all discovery methods and endpoints.
-        
                                            
-        
                                            
-          The oncomplete simple event is fired when the discovery process is completed, i.e. there are no more Thing Descriptions to discover. It might not be supported by all discovery methods (e.g. multicast discovery) and endpoints.
-        
                                            
+  
                                            
+    
                                            The ThingDiscovery interface
                                            
+    
                                            
+      Constructed given a filter and provides the events and methods controlling the discovery process.
+    
                                            
+    
                                            +      [Constructor(optional ThingFilter filter), SecureContext, Exposed=(Window,Worker)]
+      interface ThingDiscovery {
+        readonly attribute ThingFilter? filter;
+        readonly attribute boolean active;
+        readonly attribute boolean completed;
+        readonly attribute Error? error;
+        void start();
+        Promise<object> next();
+        void stop();
+      };
+    
                                            
+    
                                            
+      The filter property represents the discovery filter of type ThingFilter specified for the discovery.
+    
                                            
+    
                                            
+      The active property represents whether the discovery is actively ongoing or not (i.e. it has either been completed or stopped).
+    
                                            
+    
                                            
+      The completed property represents whether the discovery has been known to have been completed with no more Thing Descriptions to be discovered with the optionally given filter.
+    
                                            
+    
                                            
+      The error property represents an error that occured during the discovery process.
+    
                                            
 
-        
                                            
-          The start() method MUST run the following steps:
-          
                                              
+    
                                               
                                              The start() method
                                              
+    
                                              
+      Starts the discovery process. The method MUST run the following steps:
+      
                                                
+        
                                              1. 
+          If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
+        
                                                2. 
+        
                                              2. 
+          Create an internal discovery queue for storing discovered ThingDescriptions.
+        
                                                3. 
+        
                                              3. 
+          If this.filter is defined,
+          
                                                  
             
                                                • 
-              If this.filter is defined,
-              
                                                    
-                
                                                  • 
-                  Let filter denote this.filter.
-                
                                                    • 
-                
                                                  • 
-                  If filter.query is defined, pass it as an opaque string to the underlying implementation to be matched against discovered items. The underlying implementation is responsible to parse it e.g. as a SPARQL or JSON query and match it against the Thing Descriptions found during the discovery process. If queries are not supported, implementations SHOULD throw a NotSupported error and terminate these steps.
-                
                                                    • 
-              
                                                  
+              Let filter denote this.filter.
             
                                                  • 
             
                                                • 
-              Request the underlying platform to start the discovery process, with the following parameters:
-              
                                                    
-                
                                                  • 
-                  If filter.method is not defined or the value is "any", use the widest discovery method supported by the underlying platform.
-                
                                                    • 
-                
                                                  • 
-                  Otherwise if filter.method is "local", use the local Thing Directory for discovery. Usually that defines Things deployed in the same device, or connected to the device in slave mode (e.g. sensors connected via Bluetooth or a serial connection).
-                
                                                    • 
-                
                                                  • 
-                  Otherwise if filter.method is "directory", use the remote Thing Directory specified in filter.url.
-                
                                                    • 
-                
                                                  • 
-                  Otherwise if filter.method is "multicast", use all the multicast discovery protocols supported by the underlying platform.
-                
                                                    • 
-              
                                                  
+              If filter.query is defined, pass it as an opaque string to the underlying implementation to be matched against discovered items. The underlying implementation is responsible to parse it e.g. as a SPARQL or JSON query and match it against the Thing Descriptions found during the discovery process. If queries are not supported, implementations SHOULD throw a NotSupported error and terminate these steps.
             
                                                  • 
+          
                                                
+        
                                                4. 
+        
                                              4. 
+          Request the underlying platform to start the discovery process, with the following parameters:
+          
                                                  
             
                                                • 
-              When the underlying platform has started the discovery process, set the active property to true.
+              If filter.method is not defined or the value is "any", use the widest discovery method supported by the underlying platform.
             
                                                  • 
             
                                                • 
-              Whenever a new Thing Description td is discovered by the underlying platform, run the following sub-steps:
-              
                                                    
-                
                                                  1. 
-                  Fetch the td.
-                
                                                    2. 
-                
                                                  2. 
-                   Let json be the result of running the parse a TD steps on td. If that fails, fire an onerror event with that error, discard td and continue the discovery process.
-                
                                                    3. 
-                
                                                  3. 
-                  If filter.query is defined, check if json is a match for the query. The matching algorithm is encapsulated by implementations. If that returns false, discard td and continue the discovery process.
-                
                                                    4. 
-                
                                                  4. 
-                  If filter.fragment is defined, for each property defined in it, check if that property exists in json.properties and has the same value. If this is false in any checks, discard td and continue the discovery process.
-                
                                                    5. 
-                
                                                  5. 
-                  Otherwise if td has not been discarded in the previous steps, fire an onfound event with its td property set to json.
-                
                                                    6. 
-              
                                                  
+              Otherwise if filter.method is "local", use the local Thing Directory for discovery. Usually that defines Things deployed in the same device, or connected to the device in slave mode (e.g. sensors connected via Bluetooth or a serial connection).
             
                                                  • 
             
                                                • 
-              Whenever an error occurs during the discovery process, fire an onerror event, whose message property is set to DiscoveryError unless there was an error code provided by the Protocol Bindings, in which case set it to that value.
+              Otherwise if filter.method is "directory", use the remote Thing Directory specified in filter.url.
             
                                                  • 
             
                                                • 
-              When the discovery process is completed, fire the oncomplete event, remove all event listeners and set the this.active property to false.
+              Otherwise if filter.method is "multicast", use all the multicast discovery protocols supported by the underlying platform.
             
                                                  • 
-          
                                              
-        
                                              
-
-        
                                              
-          The stop() MUST run the following steps:
+          
+        
+        
                                            1. 
+          When the underlying platform has started the discovery process, set the active property to true.
+        
                                              2. 
+        
                                            2. 
+          Whenever a new Thing Description td is discovered by the underlying platform, run the following sub-steps:
           
                                                
             
                                              1. 
-              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.
+              Fetch td.
+            
                                                2. 
+            
                                              2. 
+               Let json be the result of running the parse a TD steps on td. If that fails, fire an onerror event with that error, discard td and continue the discovery process.
             
                                                3. 
             
                                              3. 
-              Remove all event listeners.
+              If filter.query is defined, check if json is a match for the query. The matching algorithm is encapsulated by implementations. If that returns false, discard td and continue the discovery process.
             
                                                4. 
             
                                              4. 
-              Set the this.active property to false.
+              If filter.fragment is defined, for each property defined in it, check if that property exists in json.properties and has the same value. If this is false in any checks, discard td and continue the discovery process.
+            
                                                5. 
+            
                                              5. 
+              Otherwise if td has not been discarded in the previous steps, add it to the internal queue.
+            
                                                6. 
+            
                                              6. 
+              Set this.error to null.
             
                                                7. 
           
                                              
-        
                                              
-      
                                              3.  
+        
+        
                                            3. 
+          Whenever an error occurs during the discovery process,
+          
                                                
+            
                                              1. 
+              Set this.error to a new Error object whose message property is set to 'DiscoveryError', unless there was an error message provided by the Protocol Bindings, in which case set it to that value.
+            
                                                2. 
+            
                                              2. 
+              If the error is irrecoverable and discovery cannot continue, set this.active to false.
+            
                                                3. 
+          
                                              
+        
                                              4. 
+        
                                            4. 
+          When the discovery process has completed, set this.completed to true and set this.active to false.
+        
                                              5. 
+      
                                            
+    
                                            
     
                                            
 
-    
                                             
                                            The discover() method
                                            
+    
                                             
                                            The next() method
                                            
+    
                                            
+      Resolves with the next ThingDescription that is discovered, or rejects with an error. The method MUST run the following steps:
+      
                                              
+        
                                            1. 
+          Return a Promise promise and execute the next steps in parallel.
+        
                                              2. 
+        
                                            2. 
+          If this.active is false, invoke start().
+        
                                              3. 
+        
                                            3. 
+          Wait until the internal discovery queue is not empty.
+        
                                              4. 
+        
                                            4. 
+          Remove the first item from the internal discovery queue denoted by td. Resolve promise with td and terminate these steps.
+        
                                              5. 
+      
                                            
+    
                                            
+    
                                            
+
+    
                                             
                                            The stop() method
                                            
+    
                                            
+      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 inactive. The method MUST run the following steps:
+      
                                              
+        
                                            1. 
+          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.
+        
                                              2. 
+        
                                            2. 
+          Set this.active to false.
+        
                                              3. 
+      
                                            
+    
                                            
+    
                                            
+
+    
                                            
+      
                                            The DiscoveryMethod enumeration
                                            
+      
                                            +        typedef DOMString DiscoveryMethod;
+      
                                            
       
                                            
-        Starts the discovery process that will look for Thing Descriptions that match an optional filter which can specify the discovery method and match a specific source URL, a query and a template object. Check the  example code. Fires an event with a fetchable Thing Description URL whenever a matching Thing Description is found. It MUST run the following steps:
-        
                                              
-          
                                            1. 
-            If invoking discover() is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
-          
                                              2. 
-          
                                            2. 
-            If the argument discovery is not defined or it is not an instance of ThingDiscovery,  throw TypeError and terminate these steps.
-          
                                              3. 
-          
                                            3. 
-            Invoke the discovery.start() method.
-          
                                              4. 
-        
                                            
+        Represents the discovery type to be used:
       
                                            
+      
                                              
+        
                                            • "any" does not provide any restriction
                                              • 
+        
                                            • 
+          "local" for discovering Things defined in the same device or connected to the device by wired or wireless means.
+        
                                              • 
+        
                                            • 
+          "directory" for discovery based on a service provided by a Thing Directory.
+        
                                              • 
+        
                                            • 
+          "multicast" for discovering Things in the device's network by using a supported multicast protocol.
+        
                                              • 
+      
                                            
+    
                                            
 
-    
                                             
+    
                                            
+      
                                            The ThingFilter dictionary
                                            
+      
                                            
+        Represents an object containing the constraints for discovering Things as key-value pairs.
+      
                                            
+      
                                            +        dictionary ThingFilter {
+          (DiscoveryMethod or DOMString) method = "any";
+          USVString? url;
+          USVString? query;
+          object? fragment;
+        };
+      
                                            
+      
                                            
+        The method property represents the discovery type that should be used in the discovery process. The possible values are defined by the DiscoveryMethod enumeration that MAY be extended by string values defined by solutions (with no guarantee of interoperability).
+      
                                            
+      
                                            
+        The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, for instance the URL of a Thing Directory (if method is "directory") or that of a Thing (otherwise).
+      
                                            
+      
                                            
+        The query property represents a query string accepted by the implementation, for instance a SPARQL or JSON query. Support may be implemented locally in the WoT Runtime or remotely as a service in a Thing Directory.
+      
                                            
+      
                                            
+        The fragment property represents a template object used for matching property by property against discovered Things.
+      
                                            
+    
                                            
 
     
                                             
                                            Examples
                                            
       
                                            @@ -602,42 +611,31 @@ 
                                            The ThingDiscovery interface
                                            
           method: "directory",
           url: "http://directory.wotservice.org"
         };
-        let discovery = new ThingDiscovery(discoveryFilter);
-        discovery.onfound = event => {
-          let td = event.td;
-          console.log("Found Thing Description for " + td.name);
-          let thing = WOT.consume(td);
-          console.log("Thing name: " + thing.instance.name);
-        });
-        discovery.onerror = error => {
-          console.log("Discovery error" + error.message);
-        });
-        discovery.oncomplete = event => {
-          console.log("Discovery finished successfully";
-        });
+        let discovery = WOT.discover(discoveryFilter);
         discovery.start();
         setTimeout( () => {
             discovery.stop();
             console.log("Discovery timeout");
           },
           5000);
+        do {
+          let td = await discovery.next();
+          console.log("Found Thing Description for " + td.name);
+          let thing = WOT.consume(td);
+          console.log("Thing name: " + thing.instance.name);
+        } while (discovery.active && !discovery.completed);
       
                                            
       
                                            -        let discovery = new ThingDiscovery({ method: "local" });
-        discovery.onfound = event => {
-          let td = event.td;
+        let discovery = WOT.discover({ method: "local" });
+        do {
+          let td = await discovery.next();  // also starts, if needed
           console.log("Found Thing Description for " + td.name);
           let thing = WOT.consume(td);
           console.log("Thing name: " + thing.instance.name);
-        };
-        discovery.onerror = error =>
-          console.log("Discovery error" + error.message);
-        discovery.oncomplete = event =>
-          console.log("Discovery finished successfully";
-        discovery.start();
+        } while (discovery.active);
       
                                            
     
                                             
-  
                                             
+  
                                           
 
   
                                          
     
                                          The ConsumedThing interface
                                          
@@ -723,7 +721,7 @@ 
                                          The WotListener callback
                                          
     
                                          
       
                                          The readProperty() method
                                          
       
                                          
-        Reads a Property value. Takes the following arguments: a string propertyName and an optional InteractionOptions options argument. It returns a Property value represented as any type. It MUST run the following steps:
+        Reads a Property value. Takes the following arguments: a string propertyName and an optional InteractionOptions options argument. It returns a Property value represented as any type. The method MUST run the following steps:
         
                                            
           
                                          1. 
             Return a Promise promise and execute the next steps in parallel.
@@ -1103,7 +1101,7 @@ 
                                            The PropertyReadHandler callback
                                            
             If a Property with propertyName does not exist, return ReferenceError in the reply and terminate these steps.
           
                                            2. 
           
                                          2. 
-            Save the request sender information to the Property's internal slot for observers in order to be able to notify about Property value changes.
+            Save the request sender information to the Property's internal observer list in order to be able to notify about Property value changes.
           
                                            3. 
         
                                          
       
                                          
@@ -1145,7 +1143,7 @@ 
                                          The PropertyWriteHandler callback
                                          
                 Otherwise, if mode is "single", reply to the request with the new value, following to the Protocol Bindings.
               
                                          2. 
               
                                        2. 
-                For each item stored in the internal slot for observers of the Property with propertyName, send an observe reply with the new value attached.
+                For each item stored in the internal observer list of the Property with propertyName, send an observe reply with the new value attached.
               
                                          3. 
           
           
                                        3. 
@@ -1206,7 +1204,7 @@ 
                                          The ActionHandler callback
                                          
         Takes name as string argument denoting an Event name, and a data argument of any type. The method MUST run the following steps:
         
                                            
           
                                          1. 
-            If invoking the method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
+            If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
           
                                            2. 
           
                                          2. 
             If an Event with the name name is not found in this.instance.events, throw NotFoundError and terminate these steps.
@@ -1226,7 +1224,7 @@ 
                                            The ActionHandler callback
                                            
             Return a Promise promise and execute the next steps in parallel.
           
                                            3. 
           
                                          3. 
-            If invoking expose() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
+            If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
           
                                            4. 
           
                                          4. 
             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.
@@ -1249,7 +1247,7 @@ 
                                            The ActionHandler callback
                                            
             Return a Promise promise and execute the next steps in parallel.
           
                                            5. 
           
                                          5. 
-            If invoking destroy() is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
+            If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
           
                                            6. 
           
                                          6. 
             Make a request to the underlying platform to stop serving external requests for WoT Interactions, based on the Protocol Bindings.

From 687bf235277b4d0ba3ec29f260929425d616fee1 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Thu, 11 Apr 2019 23:06:07 +0300
Subject: [PATCH 312/464] Refine discovery, add more example. Improve text in
 first chapters.

Signed-off-by: Zoltan Kis 
---
 index.html | 163 ++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 118 insertions(+), 45 deletions(-)

diff --git a/index.html b/index.html
index 36f995d8..43ec2590 100644
--- a/index.html
+++ b/index.html
@@ -115,16 +115,19 @@
 
   
                                            
     
                                            
-      The key Web of Things (WoT) concepts are described in the WoT Architecture document. The Web of Things is made of entities (Things) that can describe their capabilities in a machine-interpretable format, the Thing Description (TD) and expose these capabilities through the WoT Interface, 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 key Web of Things (WoT) concepts are described in the WoT Architecture document. The Web of Things is made of entities (Things) that can describe their capabilities in a machine-interpretable format, the Thing Description (TD) and expose these capabilities through the WoT Interface, 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).
     
                                            
     
                                            
-      Scripting is an optional "convenience" building block in WoT and it is typically used in gateways that are able to run a WoT Runtime and script management, providing a convenient way to extend WoT support to new types of endpoints and implement WoT applications like Thing Directory.
+      Scripting is an optional "convenience" building block in WoT and it is typically used in gateways that are able to run a WoT Runtime and script management, providing a convenient way to extend WoT support to new types of endpoints and implement WoT applications such as Thing Directory.
     
                                            
     
                                            
-      This specification describes a programming interface representing the WoT Interface that allows scripts run on a Thing to discover and consume (retrieve) other Thing Descriptions and to expose Things characterized by  WoT Interactions specified by a script. It deliberately follows the WoT Thing Description specification closely. It is possible to implement simpler APIs on top of this API, or implementing directly the WoT network facing interface (i.e. the WoT Interface).
+      This specification describes a programming interface representing the WoT Interface that allows scripts to discover and operate Things and to expose locally defined Things characterized by  WoT Interactions specified by a script.
+    
                                            
+    
                                            
+      The specification deliberately follows the WoT Thing Description specification closely. It is possible to implement simpler APIs on top of this API, or implementing directly the WoT network facing interface (i.e. the WoT Interface).
     
                                            
     
                                            
-      This specification is implemented at least by the ThingWeb project, which is considered the reference open source implementation at the moment. Check the  source code, including examples. Other, currently closed source implementations have been made by some of the WG member companies and tested against node-wot in plug-fests.
+      This specification is implemented at least by the ThingWeb project also known as node-wot, which is considered the reference open source implementation at the moment. Check its  source code, including examples. Other, closed source implementations have been made by WG member companies and tested against node-wot in plug-fests.
     
                                            
   
                                            
 
@@ -140,13 +143,26 @@
 
   
                                             
                                            Introduction
                                            
     
                                            
-      WoT provides layered interoperability based on how Things are modeled: as being "consumed" and "exposed".
+      WoT provides layered interoperability based on how Things are used: "consumed" and "exposed".
     
                                            
     
                                            
-      By consuming a TD, a client Thing creates a runtime resource model that allows accessing the Properties, Actions and Events exposed by the  server Thing exposed on a remote device.
+      By consuming a TD, a client Thing creates a local runtime resource model that allows accessing the Properties, Actions and Events exposed by the server Thing on a remote device.
     
                                            
     
                                            
-      Exposing a Thing requires defining a Thing Description (TD) and instantiating a software stack to serve requests for accessing the exposed Properties, Actions and Events. This specification describes how to expose and consume Things by a script.
+      Exposing a Thing requires
+      
                                            
+
+      This specification describes how to expose and consume Things by a script.
     
                                            
     
                                            
       Typically scripts are meant to be used on devices able to provide resources (with a WoT Interface) for managing (installing, updating, running) scripts, such as bridges or gateways that expose and control simpler devices as WoT Things.
@@ -165,12 +181,12 @@
     
                                            
     
                                            Discovery
                                            
     
                                              
-      
                                            • Discover all Things in the WoT network by sending a broadcast request.
                                              • 
+      
                                            • Discover Things in a network by sending a broadcast request.
                                              • 
       
                                            • Discover Things running in the local WoT Runtime.
                                              • 
       
                                            • Discover nearby Things, for instance connected by NFC or Bluetooth.
                                              • 
       
                                            • Discover Things by sending a discovery request to a given registry.
                                              • 
-      
                                            • Discover Things by filters defined on Thing Descriptions
                                              • 
-      
                                            • Discover Things by semantic queries.
                                              • 
+      
                                            • Discover Things filtered by filters defined on Thing Descriptions
                                              • 
+      
                                            • Discover Things filtered by semantic queries.
                                              • 
       
                                            • Stop or suppress an ongoing discovery process.
                                              • 
       
                                            • 
           Optionally specify a timeout to the discovery process after which it is stopped/suppressed.
@@ -241,7 +257,7 @@ 
                                              The WOT object
                                              
       Defines the API entry point exposed as a singleton and contains the API methods for discovering, consuming and producing a Thing based on Thing Descriptions.
     
                                              
     
                                              
-       Browser implementations SHOULD use a namespace object such as navigator.wot. Node.js-like runtimes MAY provide the API object through the require() or import mechanism.
+       Browser implementations should use a namespace object such as navigator.wot. Standalone runtimes may expose the API object through mechanisms like require() or import.
     
                                              
     
                                                     [SecureContext, Exposed=(Window,Worker)]
@@ -256,10 +272,10 @@ 
                                              The WOT object
                                              
 
     
                                               
                                              The ThingDescription type
                                              
       
                                              
-        Represents a Thing Description (TD). It is expected to be either a string representing a JSON-serialized object as described in the TD specification, or a parsed JSON object representing a valid TD.
+        Represents a Thing Description (TD). It is expected to be either a TD string (a JSON-serialized object as described in the TD serialization), or a TD object (a parsed JSON object validated using JSON schema validation). A TD object is obtained by parsing a TD string.
       
                                              
       
                                              
-        To parse a TD (Thing Description) denoted as td, run the following steps:
+        To parse a TD string td, run the following steps:
         
                                                
           
                                              1. 
             If td is not a string, throw TypeError and terminate these steps.
@@ -276,7 +292,7 @@ 
                                                The WOT object
                                                
 
     
                                                 
                                                 Fetching a Thing Description
                                                
       
                                                
-        The fetch() method has been part of this API in earlier versions. However, now fetching a TD should be done with an external method, such as the Fetch API or a HTTP client library.
+        The fetch(url) method has been part of this API in earlier versions. However, now fetching a TD given a URL should be done with an external method, such as the Fetch API or a HTTP client library, which offer already standardized options on specifying fetch details.
       
                                                
       
                                                         try {
@@ -293,7 +309,7 @@ 
                                                The WOT object
                                                
 
     
                                                 
                                                The ThingInstance type
                                                
       
                                                
-        Denotes an object that represents a TD Thing, i.e. a Thing Description initialized in the local WoT Runtime.
+        Denotes an object that is obtained from a TD object and represents an instantiated TD Thing, i.e. a Thing Description that has been initialized in the local WoT Runtime.
       
                                                
       
                                                
         To instantiate a TD, given td, run the following steps:
@@ -302,7 +318,7 @@ 
                                                The WOT object
                                                
             If the td argument is not a string or an object, throw TypeError and terminate these steps.
           
                                                2. 
           
                                              2. 
-            If td is a string, let json be the result of running the parse a TD steps on td. If that throws an error, re-throw the error and terminate these steps.
+            If td is a string, let json be the result of running the parse a TD string steps on td. If that throws an error, re-throw the error and terminate these steps.
           
                                                3. 
           
                                              3. 
             If td is an object, let json be td.
@@ -391,13 +407,13 @@ 
                                                The WOT object
                                                
 
     
                                                 
                                                The discover() method
                                                
       
                                                
-        Starts the discovery process that will provide parsed ThingDescription objects for Thing Descriptions that match an optional filter argument which can specify the discovery method and match a specific source URL, a query and a template object. Check the  example code. The method MUST run the following steps:
+        Starts the discovery process that will provide TD objects of Thing Descriptions that match an optional filter argument which can specify the discovery method and match a specific source URL, a query and a template object. Check the  examples. The method MUST run the following steps:
         
                                                  
           
                                                1. 
             If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
           
                                                  2. 
           
                                                2. 
-            Construct a ThingDiscovery object discovery with filter.
+            Construct a ThingDiscovery object discovery using filter.
           
                                                  3. 
           
                                                3. 
             Invoke the discovery.start() method.
@@ -423,9 +439,13 @@ 
                                                  The ThingDiscovery interface
                                                  
         readonly attribute boolean completed;
         readonly attribute Error? error;
         void start();
-        Promise<object> next();
+        Promise<DiscoveryResult> next();
         void stop();
       };
+      dictionary DiscoveryResult {
+        required object td;
+        required boolean available;
+      };
     
                                              
     
                                              
       The filter property represents the discovery filter of type ThingFilter specified for the discovery.
@@ -437,9 +457,27 @@ 
                                              The ThingDiscovery interface
                                              
       The completed property represents whether the discovery has been known to have been completed with no more Thing Descriptions to be discovered with the optionally given filter.
     
                                              
     
                                              
-      The error property represents an error that occured during the discovery process.
+      The error property represents the last error that occured during the discovery process. Typically used for critical errors that stop discovery.
+    
                                              
+    
                                              
+      Also, ThingDiscovery has an internal slot discovery results for storing the found TD objects.
     
                                              
 
+    
                                              
+      
                                              The DiscoveryResult dictionary
                                              
+      
                                              
+        Represents an object with the following mandatory properties:
+        
                                              
+      
                                              
+    
                                              
+
     
                                               
                                              The start() method
                                              
     
                                              
       Starts the discovery process. The method MUST run the following steps:
@@ -447,9 +485,6 @@ 
                                              The ThingDiscovery interface
                                              
         
                                            • 
           If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
         
                                              • 
-        
                                            • 
-          Create an internal discovery queue for storing discovered ThingDescriptions.
-        
                                              • 
         
                                            • 
           If this.filter is defined,
           
                                                
@@ -461,6 +496,9 @@ 
                                                The ThingDiscovery interface
                                                
             
           
                                              
         
                                              • 
+        
                                            • 
+          Create the discovery results internal slot for storing discovered TD objects.
+        
                                              • 
         
                                            • 
           Request the underlying platform to start the discovery process, with the following parameters:
           
                                                
@@ -488,7 +526,7 @@ 
                                                The ThingDiscovery interface
                                                
               Fetch td.
             
             
                                              • 
-               Let json be the result of running the parse a TD steps on td. If that fails, fire an onerror event with that error, discard td and continue the discovery process.
+               Let json be the result of running the parse a TD string steps on td. If that fails, set this.error to SyntaxError, discard td and continue the discovery process.
             
                                                • 
             
                                              • 
               If filter.query is defined, check if json is a match for the query. The matching algorithm is encapsulated by implementations. If that returns false, discard td and continue the discovery process.
@@ -497,10 +535,10 @@ 
                                                The ThingDiscovery interface
                                                
               If filter.fragment is defined, for each property defined in it, check if that property exists in json.properties and has the same value. If this is false in any checks, discard td and continue the discovery process.
             
                                                • 
             
                                              • 
-              Otherwise if td has not been discarded in the previous steps, add it to the internal queue.
+              Otherwise if td has not been discarded in the previous steps, add td to the discovery results.
             
                                                • 
             
                                              • 
-              Set this.error to null.
+              At this point implementations MAY control the flow of the discovery process (depending on memory constraints, for instance temporarily stop discovery if the queue is getting too large, or resume discovery when the queue is emptied sufficiently).
             
                                                • 
           
                                          
         
                                          4. 
@@ -511,7 +549,7 @@ 
                                          The ThingDiscovery interface
                                          
               Set this.error to a new Error object whose message property is set to 'DiscoveryError', unless there was an error message provided by the Protocol Bindings, in which case set it to that value.
             
             
                                        4. 
-              If the error is irrecoverable and discovery cannot continue, set this.active to false.
+              If the error is irrecoverable and discovery has been stopped by the underlying platform, set this.active to false.
             
                                          5. 
           
                                        
         
                                        2. 
@@ -524,19 +562,22 @@ 
                                        The ThingDiscovery interface
                                        
 
     
                                         
                                        The next() method
                                        
     
                                        
-      Resolves with the next ThingDescription that is discovered, or rejects with an error. The method MUST run the following steps:
+      Provides the next discovered ThingDescription, or rejects with an error. The method MUST run the following steps:
       
                                          
         
                                        1. 
           Return a Promise promise and execute the next steps in parallel.
         
                                          2. 
         
                                        2. 
-          If this.active is false, invoke start().
+          Wait until the discovery results internal slot is not empty.
+        
                                          3. 
+        
                                        3. 
+          Remove the first TD object from the  discovery results denoted by td.
         
                                          4. 
         
                                        4. 
-          Wait until the internal discovery queue is not empty.
+          Create a DiscoveryResult object result. Let result.td be td. Let result.available be false if discovery results is empty, or true otherwise.
         
                                          5. 
         
                                        5. 
-          Remove the first item from the internal discovery queue denoted by td. Resolve promise with td and terminate these steps.
+          Resolve promise with result and terminate these steps.
         
                                          6. 
       
                                        
     
                                        
@@ -605,32 +646,64 @@ 
                                        The ThingFilter dictionary
                                        
       
                                        
     
                                        
 
-    
                                         
                                        Examples
                                        
+    
                                         
                                        Discovery Examples
                                        
+      
                                        
+        The following example finds TD objects of Things that are exposed by local hardware, regardless how many instances of WoT Runtime it is running. Note that the discovery can end before the internal queue is emptied, so we need to continue reading TD objectss even after discovery has become inactive. This is almost certain with local and directory type discoveries.
+      
                                        
+      
                                        +        let discovery = WOT.discover({ method: "local" });
+        do {
+          let { td, available } = await discovery.next();
+          console.log("Found Thing Description for " + td.name);
+          let thing = WOT.consume(td);
+          console.log("Thing name: " + thing.instance.name);
+        } while (discovery.active || available > 0);
+        if (discovery.completed) {  // likely
+          console.log("Discovery completed.");
+        }
+      
                                        
+      
                                        
+        The next example finds TD objects of Things listed in a Thing Directory service. Again, this is likely to return a large number of TD objects very soon, so we need to keep reading the TD objects even after discovery has stopped. We set a timeout for safety, but this discovery should complete without issues.
+      
                                        
       
                                                 let discoveryFilter = {
           method: "directory",
           url: "http://directory.wotservice.org"
         };
         let discovery = WOT.discover(discoveryFilter);
-        discovery.start();
         setTimeout( () => {
             discovery.stop();
             console.log("Discovery timeout");
           },
-          5000);
+          3000);
         do {
-          let td = await discovery.next();
+          let { td, available } = await discovery.next();
           console.log("Found Thing Description for " + td.name);
           let thing = WOT.consume(td);
           console.log("Thing name: " + thing.instance.name);
-        } while (discovery.active && !discovery.completed);
+        } while (available > 0 || discovery.active);
+        if (discovery.completed){  // likely
+          console.log("Discovery completed.");
+        } else {  // likely there was an error
+          console.log("Discovery stopped.");
+          if (discovery.error) {
+            console.log("Discovery error: " + error.message);
+          }
+        }
       
                                        
-      
                                        -        let discovery = WOT.discover({ method: "local" });
+      
                                        
+        The next example is for an open-ended multicast discovery, which likely won't complete soon (depending on the underlying protocol), so stopping it with a timeout is a good idea. It will likely deliver results one by one. A timeout needs to be set up if we want to stop discovery after a while.
+      
                                        
+      
                                        +        let discovery = WOT.discover({ method: "multicast" });
+        setTimeout( () => {
+            discovery.stop();
+            console.log("Stopped open-ended discovery");
+          },
+          10000);
         do {
-          let td = await discovery.next();  // also starts, if needed
-          console.log("Found Thing Description for " + td.name);
-          let thing = WOT.consume(td);
+          let result = await discovery.next();
+          let thing = WOT.consume(result.td);
           console.log("Thing name: " + thing.instance.name);
         } while (discovery.active);
       
                                        
@@ -686,7 +759,7 @@ 
                                        Handling TD change
                                        
         Whenever the the underlying platform gets a notification that the Thing Description has been changed by the source, run the following steps:
         
                                          
           
                                        1. 
-            Fetch the new Thing Description and let td be the result of running the parse a TD steps on it. If that throws an error, terminate these steps.
+            Fetch the new Thing Description and let td be the result of running the parse a TD string steps on it. If that throws an error, terminate these steps.
           
                                          2. 
           
                                        2. 
             Let instance be the result of running the instantiate a TD steps on td in the context of this object. If that throws an error, terminate these steps.
@@ -981,7 +1054,7 @@ 
                                          The unsubscribeEvent() method
                                          
     
                                        
 
     
                                        
-      
                                        Examples
                                        
+      
                                        ConsumedThing Examples
                                        
       
                                        
         This example illustrates how to fetch a TD by URL, create a ConsumedThing, read metadata (name), read property value, subscribe to property change, subscribe to a WoT event, unsubscribe.
       
                                        
@@ -1050,7 +1123,7 @@ 
                                        Constructing ExposedThing
                                        
         Note that a valid ThingInstance object can be provided either by the instantiate a TD steps, or also by external libraries that implement [[!WOT-TD]].
       
                                        
       
                                        
-         Note that an existing ThingInstance 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 another ExposedThing object. This is the current way of adding and removing Property, Action and Event definitions, and later adding the service handler functions. This is illustrated in the examples.
+         Note that an existing ThingInstance 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 another ExposedThing object. This is the current way of adding and removing Property, Action and Event definitions, and later adding the service handler functions. This is illustrated in the examples.
       
                                        
     
                                        
 
@@ -1263,7 +1336,7 @@ 
                                        The ActionHandler callback
                                        
     
                                        
 
     
                                        
-      
                                        Examples
                                        
+      
                                        ExposedThing Examples
                                        
       
                                        
         Below some ExposedThing interface examples are given.
       
                                        

From f42c2ce44f678c50e32baca28cc94f1e7b8d5050 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Fri, 12 Apr 2019 11:02:17 +0300
Subject: [PATCH 313/464] Simplify discovery

Signed-off-by: Zoltan Kis 
---
 index.html | 87 ++++++++++++++++++++----------------------------------
 1 file changed, 32 insertions(+), 55 deletions(-)

diff --git a/index.html b/index.html
index 43ec2590..16916cfc 100644
--- a/index.html
+++ b/index.html
@@ -436,54 +436,35 @@ 
                                        The ThingDiscovery interface
                                        
       interface ThingDiscovery {
         readonly attribute ThingFilter? filter;
         readonly attribute boolean active;
-        readonly attribute boolean completed;
+        readonly attribute boolean done;
         readonly attribute Error? error;
         void start();
-        Promise<DiscoveryResult> next();
+        Promise<object> next();
         void stop();
       };
-      dictionary DiscoveryResult {
-        required object td;
-        required boolean available;
-      };

                      - The filter property represents the discovery filter of type ThingFilter specified for the discovery. + The discovery results internal slot is an internal queue for temporarily storing the found TD objects until they are consumed by the application.

                      - The active property represents whether the discovery is actively ongoing or not (i.e. it has either been completed or stopped). + The filter property represents the discovery filter of type ThingFilter specified for the discovery.

                      - The completed property represents whether the discovery has been known to have been completed with no more Thing Descriptions to be discovered with the optionally given filter. + The active property is true is the discovery is actively ongoing on protocol level (i.e. new TDs may still arrive) and false otherwise.

                      - The error property represents the last error that occured during the discovery process. Typically used for critical errors that stop discovery. + The done property is true if the discovery has been completed with no more results to report and the discovery results queue is also empty. It should be used for testing if the next() method is worth calling.

                      - Also, ThingDiscovery has an internal slot discovery results for storing the found TD objects. + The error property represents the last error that occured during the discovery process. Typically used for critical errors that stop discovery.

                      -
                      -

                      The DiscoveryResult dictionary

                      -

                      - Represents an object with the following mandatory properties: -

                      -

                      -
                      -

                      The start() method

                      Starts the discovery process. The method MUST run the following steps:

                      1. - If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps. + If invoking this method is not allowed for the current scripting context for security reasons, set this.error to SecurityError and terminate these steps.
                      2. If this.filter is defined, @@ -492,7 +473,7 @@

                        The DiscoveryResult dictionary

                        Let filter denote this.filter.
                      3. - If filter.query is defined, pass it as an opaque string to the underlying implementation to be matched against discovered items. The underlying implementation is responsible to parse it e.g. as a SPARQL or JSON query and match it against the Thing Descriptions found during the discovery process. If queries are not supported, implementations SHOULD throw a NotSupported error and terminate these steps. + If filter.query is defined, pass it as an opaque string to the underlying implementation to be matched against discovered items. The underlying implementation is responsible to parse it e.g. as a SPARQL or JSON query and match it against the Thing Descriptions found during the discovery process. If queries are not supported, set this.error to NotSupportedError and terminate these steps.
                        4. @@ -535,7 +516,7 @@

                        The DiscoveryResult dictionary

                        If filter.fragment is defined, for each property defined in it, check if that property exists in json.properties and has the same value. If this is false in any checks, discard td and continue the discovery process.
                      4. - Otherwise if td has not been discarded in the previous steps, add td to the discovery results. + Otherwise add td to the discovery results.
                      5. At this point implementations MAY control the flow of the discovery process (depending on memory constraints, for instance temporarily stop discovery if the queue is getting too large, or resume discovery when the queue is emptied sufficiently). @@ -546,7 +527,10 @@

                        The DiscoveryResult dictionary

                        Whenever an error occurs during the discovery process,
                        1. - Set this.error to a new Error object whose message property is set to 'DiscoveryError', unless there was an error message provided by the Protocol Bindings, in which case set it to that value. + Set this.error to a new Error object error. Set error.name to 'DiscoveryError'. +
                          2. +
                        2. + If there was an error code or message provided by the Protocol Bindings, set error.message to that value as string.
                        3. If the error is irrecoverable and discovery has been stopped by the underlying platform, set this.active to false. @@ -554,7 +538,7 @@

                          The DiscoveryResult dictionary

                      6. - When the discovery process has completed, set this.completed to true and set this.active to false. + When the underlying platform reports the discovery process has completed, set this.active to false.

                      @@ -562,22 +546,22 @@

                      The DiscoveryResult dictionary

                      The next() method

                      - Provides the next discovered ThingDescription, or rejects with an error. The method MUST run the following steps: + Provides the next discovered TD object. The method MUST run the following steps:

                      1. Return a Promise promise and execute the next steps in parallel.
                      2. - Wait until the discovery results internal slot is not empty. + If this.active is true, wait until the discovery results internal slot is not empty.
                      3. - Remove the first TD object from the discovery results denoted by td. + If discovery results is empty and this.active is false, set this.done to true and reject promise.
                      4. - Create a DiscoveryResult object result. Let result.td be td. Let result.available be false if discovery results is empty, or true otherwise. + Remove the first TD object td from discovery results.
                      5. - Resolve promise with result and terminate these steps. + Resolve promise with td and terminate these steps.

                      @@ -648,22 +632,19 @@

                      The ThingFilter dictionary

                      Discovery Examples

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

                               let discovery = WOT.discover({ method: "local" });
         do {
-          let { td, available } = await discovery.next();
+          let td = await discovery.next();
           console.log("Found Thing Description for " + td.name);
           let thing = WOT.consume(td);
           console.log("Thing name: " + thing.instance.name);
-        } while (discovery.active || available > 0);
-        if (discovery.completed) {  // likely
-          console.log("Discovery completed.");
-        }
+        } while (!discovery.done);

                      - The next example finds TD objects of Things listed in a Thing Directory service. Again, this is likely to return a large number of TD objects very soon, so we need to keep reading the TD objects even after discovery has stopped. We set a timeout for safety, but this discovery should complete without issues. + The next example finds TD objects of Things listed in a Thing Directory service. We set a timeout for safety. 

                               let discoveryFilter = {
@@ -677,22 +658,18 @@ 
                      The ThingFilter dictionary
                      
           },
           3000);
         do {
-          let { td, available } = await discovery.next();
+          let td = await discovery.next();
           console.log("Found Thing Description for " + td.name);
           let thing = WOT.consume(td);
           console.log("Thing name: " + thing.instance.name);
-        } while (available > 0 || discovery.active);
-        if (discovery.completed){  // likely
-          console.log("Discovery completed.");
-        } else {  // likely there was an error
+        } while (!discovery.done);
+        if (discovery.error) {
           console.log("Discovery stopped.");
-          if (discovery.error) {
-            console.log("Discovery error: " + error.message);
-          }
+          console.log("Discovery error: " + error.message);
         }

                      - The next example is for an open-ended multicast discovery, which likely won't complete soon (depending on the underlying protocol), so stopping it with a timeout is a good idea. It will likely deliver results one by one. A timeout needs to be set up if we want to stop discovery after a while. + The next example is for an open-ended multicast discovery, which likely won't complete soon (depending on the underlying protocol), so stopping it with a timeout is a good idea. It will likely deliver results one by one. 

                               let discovery = WOT.discover({ method: "multicast" });
@@ -702,10 +679,10 @@ 
                      The ThingFilter dictionary
                      
           },
           10000);
         do {
-          let result = await discovery.next();
-          let thing = WOT.consume(result.td);
+          let td = await discovery.next();
+          let thing = WOT.consume(td);
           console.log("Thing name: " + thing.instance.name);
-        } while (discovery.active);
+        } while (!discovery.done);
                      From a7271055020072d11bf7533852bcfe446692376d Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 15 Apr 2019 15:37:37 +0300 Subject: [PATCH 314/464] Clarify name for TD object and string. Remove TD change event and use case. Note on uriVariables. Signed-off-by: Zoltan Kis --- index.html | 76 +++++++++++++++++++----------------------------------- 1 file changed, 26 insertions(+), 50 deletions(-) diff --git a/index.html b/index.html index 16916cfc..3bf313aa 100644 --- a/index.html +++ b/index.html @@ -232,12 +232,14 @@
                    • Emit a WoT Event, i.e. notify all subscribed listeners.
                      • +
                    • Register service handlers for external requests:
                      • to retrieve a Property value;
                        • @@ -272,10 +274,10 @@

                        The WOT object

                        The ThingDescription type

                        - Represents a Thing Description (TD). It is expected to be either a TD string (a JSON-serialized object as described in the TD serialization), or a TD object (a parsed JSON object validated using JSON schema validation). A TD object is obtained by parsing a TD string. + Represents a Thing Description (TD). It is expected to be either a ThingDescription string (a JSON-serialized object as described in the TD serialization), or a ThingDescription object (a parsed JSON object validated using JSON schema validation). A ThingDescription object is obtained by parsing a ThingDescription string.

                        - To parse a TD string td, run the following steps: + To parse a ThingDescription string td, run the following steps:

                        1. If td is not a string, throw TypeError and terminate these steps. @@ -309,7 +311,7 @@

                          The WOT object

                          The ThingInstance type

                          - Denotes an object that is obtained from a TD object and represents an instantiated TD Thing, i.e. a Thing Description that has been initialized in the local WoT Runtime. + Denotes an object that is obtained from a ThingDescription object and represents an instantiated TD Thing, i.e. a Thing Description that has been initialized in the local WoT Runtime.

                          To instantiate a TD, given td, run the following steps: @@ -318,7 +320,7 @@

                          The WOT object

                          If the td argument is not a string or an object, throw TypeError and terminate these steps.
                        2. - If td is a string, let json be the result of running the parse a TD string steps on td. If that throws an error, re-throw the error and terminate these steps. + If td is a string, let json be the result of running the parse a ThingDescription string steps on td. If that throws an error, re-throw the error and terminate these steps.
                        3. If td is an object, let json be td. @@ -369,12 +371,6 @@

                          The WOT object

                        4. Let thing be a new ConsumedThing object constructed with instance.
                          5. -
                        5. - Make a request to the underlying platform to subscribe to TD change notifications for this TD, connected to the thing.onchange event. -

                          - This mechanism needs to be defined more exactly in the Thing Description specification. -

                          -
                        6. Return thing.
                          7. @@ -407,7 +403,7 @@

                          The WOT object

                          The discover() method

                          - Starts the discovery process that will provide TD objects of Thing Descriptions that match an optional filter argument which can specify the discovery method and match a specific source URL, a query and a template object. Check the examples. The method MUST run the following steps: + Starts the discovery process that will provide ThingDescription objects of Thing Descriptions that match an optional filter argument which can specify the discovery method and match a specific source URL, a query and a template object. Check the examples. The method MUST run the following steps:

                          1. If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps. @@ -439,25 +435,28 @@

                            The ThingDiscovery interface

                            readonly attribute boolean done; readonly attribute Error? error; void start(); - Promise<object> next(); + Promise<ThingDescription> next(); void stop(); };

                            - The discovery results internal slot is an internal queue for temporarily storing the found TD objects until they are consumed by the application. + The discovery results internal slot is an internal queue for temporarily storing the found ThingDescription objects until they are consumed by the application using the next() method.

                            The filter property represents the discovery filter of type ThingFilter specified for the discovery.

                            - The active property is true is the discovery is actively ongoing on protocol level (i.e. new TDs may still arrive) and false otherwise. + The active property is true when the discovery is actively ongoing on protocol level (i.e. new TDs may still arrive) and false otherwise.

                            - The done property is true if the discovery has been completed with no more results to report and the discovery results queue is also empty. It should be used for testing if the next() method is worth calling. + The done property is true if the discovery has been completed with no more results to report and discovery results is also empty.

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

                            +

                            + When ThingDiscovery is created, active and done are false, done is null. The start() sets active to true. The stop() method sets active to false, but done may be still false if there are ThingDescription objects in the discovery results not yet consumed with next(). During successive calls of next(), active may be true or false, but done is set to false by next() only when both active is false and discovery results is empty. +

                            The start() method

                            @@ -478,7 +477,7 @@

                            The ThingDiscovery interface

                    • - Create the discovery results internal slot for storing discovered TD objects. + Create the discovery results internal slot for storing discovered ThingDescription objects.
                    • Request the underlying platform to start the discovery process, with the following parameters: @@ -507,7 +506,7 @@

                      The ThingDiscovery interface

                      Fetch td.
                    • - Let json be the result of running the parse a TD string steps on td. If that fails, set this.error to SyntaxError, discard td and continue the discovery process. + Let json be the result of running the parse a ThingDescription string steps on td. If that fails, set this.error to SyntaxError, discard td and continue the discovery process.
                    • If filter.query is defined, check if json is a match for the query. The matching algorithm is encapsulated by implementations. If that returns false, discard td and continue the discovery process. @@ -546,7 +545,7 @@

                      The ThingDiscovery interface

                      The next() method

                      - Provides the next discovered TD object. The method MUST run the following steps: + Provides the next discovered ThingDescription object. The method MUST run the following steps:

                      1. Return a Promise promise and execute the next steps in parallel. @@ -558,7 +557,7 @@

                        The ThingDiscovery interface

                        If discovery results is empty and this.active is false, set this.done to true and reject promise.
                      2. - Remove the first TD object td from discovery results. + Remove the first ThingDescription object td from discovery results.
                      3. Resolve promise with td and terminate these steps. @@ -632,7 +631,7 @@

                        The ThingFilter dictionary

                        Discovery Examples

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

                                 let discovery = WOT.discover({ method: "local" });
@@ -644,7 +643,7 @@ 
                        The ThingFilter dictionary
                        
         } while (!discovery.done);

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

                                 let discoveryFilter = {
@@ -654,7 +653,7 @@ 
                        The ThingFilter dictionary
                        
         let discovery = WOT.discover(discoveryFilter);
         setTimeout( () => {
             discovery.stop();
-            console.log("Discovery timeout");
+            console.log("Discovery stopped after timeout.");
           },
           3000);
         do {
@@ -664,8 +663,7 @@ 
                        The ThingFilter dictionary
                        
           console.log("Thing name: " + thing.instance.name);
         } while (!discovery.done);
         if (discovery.error) {
-          console.log("Discovery stopped.");
-          console.log("Discovery error: " + error.message);
+          console.log("Discovery stopped because of an error: " + error.message);
         }

                        @@ -694,7 +692,7 @@

                        The ConsumedThing interface

                               [Constructor(ThingInstance instance), SecureContext, Exposed=(Window,Worker)]
-      interface ConsumedThing: EventTarget {
+      interface ConsumedThing {
         Promise<any> readProperty(DOMString propertyName, optional InteractionOptions options);
         Promise<object> readAllProperties(optional InteractionOptions options);
         Promise<object> readMultipleProperties(sequence<DOMString> propertyNames, optional InteractionOptions options);
@@ -706,13 +704,15 @@ 
                        The ConsumedThing interface
                        
         Promise<void> subscribeEvent(DOMString name, WotListener listener);
         Promise<void> unsubscribeEvent(DOMString name);
         readonly attribute ThingInstance instance;
-        attribute EventHandler onchange;
       };
       callback WotListener = void(any data);
       dictionary InteractionOptions {
         object uriVariables;
       };
                        +

                        + It is under discussion whether InteractionOptions could be actually encapsulated by Protocol Bindings. See TD issue #569. +

                        Constructing ConsumedThing

                        @@ -727,30 +727,6 @@

                        Constructing ConsumedThing

                        -
                        -

                        Handling TD change

                        -

                        - The onchange event is fired when the Thing Description has been reported to be changed by the source from where it was consumed. -

                        -

                        - Whenever the the underlying platform gets a notification that the Thing Description has been changed by the source, run the following steps: -

                          -
                        1. - Fetch the new Thing Description and let td be the result of running the parse a TD string steps on it. If that throws an error, terminate these steps. -
                          2. -
                        2. - Let instance be the result of running the instantiate a TD steps on td in the context of this object. If that throws an error, terminate these steps. -
                          3. -
                        3. - Replace this.instance with instance. -
                          4. -
                        4. - Fire an onchange event. -
                          5. -
                        -

                        -
                        -

                        The InteractionOptions dictionary

                        From 25dff59e5ebf2aad4ea81eef3e4002395c10ff31 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Thu, 18 Apr 2019 09:53:22 +0300 Subject: [PATCH 315/464] Fix #166: remove uriVariables from this API version Signed-off-by: Zoltan Kis --- index.html | 59 +++++++++++++++++++++++++----------------------------- 1 file changed, 27 insertions(+), 32 deletions(-) diff --git a/index.html b/index.html index 3bf313aa..736daa85 100644 --- a/index.html +++ b/index.html @@ -693,12 +693,12 @@

                        The ConsumedThing interface

                               [Constructor(ThingInstance instance), SecureContext, Exposed=(Window,Worker)]
       interface ConsumedThing {
-        Promise<any> readProperty(DOMString propertyName, optional InteractionOptions options);
-        Promise<object> readAllProperties(optional InteractionOptions options);
-        Promise<object> readMultipleProperties(sequence<DOMString> propertyNames, optional InteractionOptions options);
-        Promise<void> writeProperty(DOMString propertyName, any value, optional InteractionOptions options);
-        Promise<void> writeMultipleProperties(object valueMap, optional InteractionOptions options);
-        Promise<any> invokeAction(DOMString actionName, optional any params, optional InteractionOptions options);
+        Promise<any> readProperty(DOMString propertyName);
+        Promise<object> readAllProperties();
+        Promise<object> readMultipleProperties(sequence<DOMString> propertyNames);
+        Promise<void> writeProperty(DOMString propertyName, any value);
+        Promise<void> writeMultipleProperties(object valueMap);
+        Promise<any> invokeAction(DOMString actionName, optional any params);
         Promise<void> subscribeProperty(DOMString name, WotListener listener);
         Promise<void> unsubscribeProperty(DOMString name);
         Promise<void> subscribeEvent(DOMString name, WotListener listener);
@@ -706,13 +706,7 @@ 
                        The ConsumedThing interface
                        
         readonly attribute ThingInstance instance;
       };
       callback WotListener = void(any data);
-      dictionary InteractionOptions {
-        object uriVariables;
-      };
                        -

                        - It is under discussion whether InteractionOptions could be actually encapsulated by Protocol Bindings. See TD issue #569. -

                        Constructing ConsumedThing

                        @@ -727,6 +721,7 @@

                        Constructing ConsumedThing

                        +

                        The WotListener callback

                        @@ -747,7 +742,7 @@

                        The WotListener callback

                        The readProperty() method

                        - Reads a Property value. Takes the following arguments: a string propertyName and an optional InteractionOptions options argument. It returns a Property value represented as any type. The method MUST run the following steps: + Reads a Property value. Takes a string argument propertyName and returns a Property value represented as any type. The method MUST run the following steps:

                        1. Return a Promise promise and execute the next steps in parallel. @@ -756,7 +751,7 @@

                          The readProperty() method

                          If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
                        2. - Make a request to the underlying platform (via the Protocol Bindings) to retrieve the value of the Property given by propertyName with optional URI templates given in options.uriVariables. + Make a request to the underlying platform (via the Protocol Bindings) to retrieve the value of the Property given by propertyName.
                        3. If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps. @@ -787,7 +782,7 @@

                          The readProperty() method

                          The readMultipleProperties() method

                          - Reads multiple Property values with one or multiple requests. Takes the following arguments: a sequence of strings propertyNames and an optional InteractionOptions options argument. It returns an object with keys from propertyNames and values returned by this algorithm. The method MUST run the following steps: + Reads multiple Property values with one or multiple requests. Takes one argument, a sequence of strings propertyNames and returns an object with keys from propertyNames and values returned by this algorithm. The method MUST run the following steps:

                          1. Return a Promise promise and execute the next steps in parallel. @@ -799,7 +794,7 @@

                            The readMultipleProperties() method

                            Let result be an object and for each string name in propertyNames add a property with key name and the value null.
                          2. - Make a request to the underlying platform (via the Protocol Bindings) to retrieve the Property values given by propertyNames with optional URI templates given in options.uriVariables. If the Protocol Bindings support this using one request, use that, otherwise run the readProperty() steps on each property name in propertyNames and options and store the resulting values in result for each name in propertyNames. + Make a request to the underlying platform (via the Protocol Bindings) to retrieve the Property values given by propertyNames. If the Protocol Bindings support this using one request, use that, otherwise run the readProperty() steps on each property name in propertyNames and options and store the resulting values in result for each name in propertyNames.
                          3. If the above step fails at any point, reject promise with SyntaxError and terminate these steps. @@ -814,7 +809,7 @@

                            The readMultipleProperties() method

                            The readAllProperties() method

                            - Reads all properties of the Thing with one or multiple requests. Takes an optional InteractionOptions options argument. It returns an object with keys from Property names and values returned by this algorithm. The method MUST run the following steps: + Reads all properties of the Thing with one or multiple requests. Takes no arguments. It returns an object with keys from Property names and values returned by this algorithm. The method MUST run the following steps:

                            1. Let propertyNames be a sequence created from all the Property names of this Thing as found in this.instance.properties. @@ -832,7 +827,7 @@

                              The readAllProperties() method

                              The writeProperty() method

                              - Writes a single Property. Takes the following arguments: a string propertyName, a value value and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps: + Writes a single Property. Takes a string argument propertyName and a value argument value. It returns success or failure. The method MUST run the following steps:

                              1. Return a Promise promise and execute the next steps in parallel. @@ -844,7 +839,7 @@

                                The writeProperty() method

                                Run the validate Property value steps on value. If that fails, reject promise with SyntaxError and terminate these steps.
                              2. - Make a request to the underlying platform (via the Protocol Bindings) to write value to the Property given by propertyName with optional URI templates given in options.uriVariables. + Make a request to the underlying platform (via the Protocol Bindings) to write value to the Property given by propertyName.
                              3. If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps. @@ -859,7 +854,7 @@

                                The writeProperty() method

                                The writeMultipleProperties() method

                                - Writes a multiple Property values with one request. Takes the following arguments: an object properties with keys as Property names and values as Property values and an optional argument options of type InteractionOptions. It returns success or failure. The method MUST run the following steps: + Writes a multiple Property values with one request. Takes one argument, an object properties with keys as Property names and values as Property values. It returns success or failure. The method MUST run the following steps:

                                1. Return a Promise promise and execute the next steps in parallel. @@ -871,7 +866,7 @@

                                  The writeMultipleProperties() method

                                  For each key name on properties, take its value as value and run the validate Property value steps on value. If that fails in for any name, reject promise with SyntaxError and terminate these steps.
                                2. - Make a single request to the underlying platform (via the Protocol Bindings) to write the each Property given 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 NotSupportedError and terminate these steps. + Make a single request to the underlying platform (via the Protocol Bindings) to write the each Property provided in properties. If this cannot be done with a single request with the Protocol Bindings of the Thing, then reject promise with NotSupportedError and terminate these steps.
                                3. If the request fails, return the error received from the Protocol Bindings and terminate these steps. @@ -886,7 +881,7 @@

                                  The writeMultipleProperties() method

                                  The subscribeProperty() method

                                  - Makes a request for Property value change notifications. Takes the following arguments: a string propertyName and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps: + Makes a request for Property value change notifications. Takes a string argument propertyName and returns success or failure. The method MUST run the following steps:

                                  1. Return a Promise promise and execute the next steps in parallel. @@ -895,7 +890,7 @@

                                    The subscribeProperty() method

                                    If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
                                  2. - Make a request to the underlying platform (via the Protocol Bindings) to observe Property identified by propertyName, with optional URI templates given in options.uriVariables. + Make a request to the underlying platform (via the Protocol Bindings) to observe Property identified by propertyName.
                                  3. If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps. @@ -910,7 +905,7 @@

                                    The subscribeProperty() method

                                    The unsubscribeProperty() method

                                    - Makes a request for unsubscribing from Property value change notifications. Takes the following arguments: a string propertyName and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps: + Makes a request for unsubscribing from Property value change notifications. Takes a string argument propertyName and returns success or failure. The method MUST run the following steps:

                                    1. Return a Promise promise and execute the next steps in parallel. @@ -919,7 +914,7 @@

                                      The unsubscribeProperty() method

                                      If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
                                    2. - Make a request to the underlying platform (via the Protocol Bindings) to stop observing the Property identified by propertyName, with optional URI templates given in options.uriVariables. + Make a request to the underlying platform (via the Protocol Bindings) to stop observing the Property identified by propertyName.
                                    3. If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps. @@ -934,7 +929,7 @@

                                      The unsubscribeProperty() method

                                      The invokeAction() method

                                      - Makes a request for invoking an Action and return the result. Takes the following arguments: a string actionName, an optional arguments parameters of type any and an optional InteractionOptions options argument. It returns the result of the Action or an error. The method MUST run the following steps: + Makes a request for invoking an Action and return the result. Takes a string argument actionName, and an optional argument parameters of type any. It returns the result of the Action or an error. The method MUST run the following steps:

                                      1. Return a Promise promise and execute the next steps in parallel. @@ -943,7 +938,7 @@

                                        The invokeAction() method

                                        If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
                                      2. - Make a request to the underlying platform (via the Protocol Bindings) to invoke the Action identified by actionName, given params and optional URI templates in options.uriVariables. + Make a request to the underlying platform (via the Protocol Bindings) to invoke the Action identified by actionName with parameters provided in params.
                                      3. If the request fails locally or returns an error over the network, reject promise with the error received from the Protocol Bindings and terminate these steps. @@ -961,7 +956,7 @@

                                        The invokeAction() method

                                        The subscribeEvent() method

                                        - Makes a request for subscribing to Event notifications. Takes the following arguments: a string eventName and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps: + Makes a request for subscribing to Event notifications. Takes a string argument eventName and returns success or failure. The method MUST run the following steps:

                                        1. Return a Promise promise and execute the next steps in parallel. @@ -970,7 +965,7 @@

                                          The subscribeEvent() method

                                          If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
                                        2. - Make a request to the underlying platform (via the Protocol Bindings) to subscribe to an Event identified by eventName, with optional URI templates given in options.uriVariables. + Make a request to the underlying platform (via the Protocol Bindings) to subscribe to an Event identified by eventName.
                                        3. If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps. @@ -985,7 +980,7 @@

                                          The subscribeEvent() method

                                          The unsubscribeEvent() method

                                          - Makes a request for unsubscribing from Event notifications. Takes the following arguments: a string eventName and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps: + Makes a request for unsubscribing from Event notifications. Takes a string argument eventName and returns success or failure. The method MUST run the following steps:

                                          1. Return a Promise promise and execute the next steps in parallel. @@ -994,7 +989,7 @@

                                            The unsubscribeEvent() method

                                            If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
                                          2. - Make a request to the underlying platform (via the Protocol Bindings) to unsubscribe from the Event identified by eventName, with optional URI templates given in options.uriVariables. + Make a request to the underlying platform (via the Protocol Bindings) to unsubscribe from the Event identified by eventName.
                                          3. If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps. From c911aa6979b359fad53500e4e72d347d7faffc0d Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Tue, 30 Apr 2019 11:29:34 +0300 Subject: [PATCH 316/464] Move discovery in its own section, separated from the core API Signed-off-by: Zoltan Kis --- index.html | 588 +++++++++++++++++++++++++++-------------------------- 1 file changed, 304 insertions(+), 284 deletions(-) diff --git a/index.html b/index.html index 736daa85..86e98ff7 100644 --- a/index.html +++ b/index.html @@ -266,7 +266,6 @@

                                            The WOT object

                                            interface WOT { ConsumedThing consume(ThingDescription td); ExposedThing produce(ThingDescription td); - ThingDiscovery discover(optional ThingFilter filter); }; typedef (USVString or object) ThingDescription; typedef object ThingInstance; @@ -293,6 +292,9 @@

                                            The WOT object

                                          Fetching a Thing Description

                                          +

                                          + This API works with Thing Descriptions that can be obtained either by direct fetch or by discovery. +

                                          The fetch(url) method has been part of this API in earlier versions. However, now fetching a TD given a URL should be done with an external method, such as the Fetch API or a HTTP client library, which offer already standardized options on specifying fetch details.

                                          @@ -400,291 +402,8 @@

                                          The WOT object

                                        - -

                                        The discover() method

                                        -

                                        - Starts the discovery process that will provide ThingDescription objects of Thing Descriptions that match an optional filter argument which can specify the discovery method and match a specific source URL, a query and a template object. Check the examples. The method MUST run the following steps: -

                                          -
                                        1. - If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps. -
                                          2. -
                                        2. - Construct a ThingDiscovery object discovery using filter. -
                                          3. -
                                        3. - Invoke the discovery.start() method. -
                                          4. -
                                        4. - Return discovery. -
                                          5. -
                                        -

                                        -
                                      -
                                      -

                                      The ThingDiscovery interface

                                      -

                                      - Constructed given a filter and provides the events and methods controlling the discovery process. -

                                      - 
                                      -      [Constructor(optional ThingFilter filter), SecureContext, Exposed=(Window,Worker)]
-      interface ThingDiscovery {
-        readonly attribute ThingFilter? filter;
-        readonly attribute boolean active;
-        readonly attribute boolean done;
-        readonly attribute Error? error;
-        void start();
-        Promise<ThingDescription> next();
-        void stop();
-      };
-
                                      -

                                      - The discovery results internal slot is an internal queue for temporarily storing the found ThingDescription objects until they are consumed by the application using the next() method. -

                                      -

                                      - The filter property represents the discovery filter of type ThingFilter specified for the discovery. -

                                      -

                                      - The active property is true when the discovery is actively ongoing on protocol level (i.e. new TDs may still arrive) and false otherwise. -

                                      -

                                      - The done property is true if the discovery has been completed with no more results to report and discovery results is also empty. -

                                      -

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

                                      -

                                      - When ThingDiscovery is created, active and done are false, done is null. The start() sets active to true. The stop() method sets active to false, but done may be still false if there are ThingDescription objects in the discovery results not yet consumed with next(). During successive calls of next(), active may be true or false, but done is set to false by next() only when both active is false and discovery results is empty. -

                                      - -

                                      The start() method

                                      -

                                      - Starts the discovery process. The method MUST run the following steps: -

                                        -
                                      1. - If invoking this method is not allowed for the current scripting context for security reasons, set this.error to SecurityError and terminate these steps. -
                                        2. -
                                      2. - If this.filter is defined, -
                                          -
                                        • - Let filter denote this.filter. -
                                          • -
                                        • - If filter.query is defined, pass it as an opaque string to the underlying implementation to be matched against discovered items. The underlying implementation is responsible to parse it e.g. as a SPARQL or JSON query and match it against the Thing Descriptions found during the discovery process. If queries are not supported, set this.error to NotSupportedError and terminate these steps. -
                                          • -
                                        -
                                        3. -
                                      3. - Create the discovery results internal slot for storing discovered ThingDescription objects. -
                                        4. -
                                      4. - Request the underlying platform to start the discovery process, with the following parameters: -
                                          -
                                        • - If filter.method is not defined or the value is "any", use the widest discovery method supported by the underlying platform. -
                                          • -
                                        • - Otherwise if filter.method is "local", use the local Thing Directory for discovery. Usually that defines Things deployed in the same device, or connected to the device in slave mode (e.g. sensors connected via Bluetooth or a serial connection). -
                                          • -
                                        • - Otherwise if filter.method is "directory", use the remote Thing Directory specified in filter.url. -
                                          • -
                                        • - Otherwise if filter.method is "multicast", use all the multicast discovery protocols supported by the underlying platform. -
                                          • -
                                        -
                                        5. -
                                      5. - When the underlying platform has started the discovery process, set the active property to true. -
                                        6. -
                                      6. - Whenever a new Thing Description td is discovered by the underlying platform, run the following sub-steps: -
                                          -
                                        1. - Fetch td. -
                                          2. -
                                        2. - Let json be the result of running the parse a ThingDescription string steps on td. If that fails, set this.error to SyntaxError, discard td and continue the discovery process. -
                                          3. -
                                        3. - If filter.query is defined, check if json is a match for the query. The matching algorithm is encapsulated by implementations. If that returns false, discard td and continue the discovery process. -
                                          4. -
                                        4. - If filter.fragment is defined, for each property defined in it, check if that property exists in json.properties and has the same value. If this is false in any checks, discard td and continue the discovery process. -
                                          5. -
                                        5. - Otherwise add td to the discovery results. -
                                          6. -
                                        6. - At this point implementations MAY control the flow of the discovery process (depending on memory constraints, for instance temporarily stop discovery if the queue is getting too large, or resume discovery when the queue is emptied sufficiently). -
                                          7. -
                                        -
                                        7. -
                                      7. - Whenever an error occurs during the discovery process, -
                                          -
                                        1. - Set this.error to a new Error object error. Set error.name to 'DiscoveryError'. -
                                          2. -
                                        2. - If there was an error code or message provided by the Protocol Bindings, set error.message to that value as string. -
                                          3. -
                                        3. - If the error is irrecoverable and discovery has been stopped by the underlying platform, set this.active to false. -
                                          4. -
                                        -
                                        8. -
                                      8. - When the underlying platform reports the discovery process has completed, set this.active to false. -
                                        9. -
                                      -

                                      -
                                      - -

                                      The next() method

                                      -

                                      - Provides the next discovered ThingDescription object. The method MUST run the following steps: -

                                        -
                                      1. - Return a Promise promise and execute the next steps in parallel. -
                                        2. -
                                      2. - If this.active is true, wait until the discovery results internal slot is not empty. -
                                        3. -
                                      3. - If discovery results is empty and this.active is false, set this.done to true and reject promise. -
                                        4. -
                                      4. - Remove the first ThingDescription object td from discovery results. -
                                        5. -
                                      5. - Resolve promise with td and terminate these steps. -
                                        6. -
                                      -

                                      -
                                      - -

                                      The stop() method

                                      -

                                      - 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 inactive. The method MUST run the following steps: -

                                        -
                                      1. - 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. -
                                        2. -
                                      2. - Set this.active to false. -
                                        3. -
                                      -

                                      -
                                      - -
                                      -

                                      The DiscoveryMethod enumeration

                                      - 
                                      -        typedef DOMString DiscoveryMethod;
-
                                      -

                                      - Represents the discovery type to be used: -

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

                                      The ThingFilter dictionary

                                      -

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

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

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

                                      -

                                      - The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, for instance the URL of a Thing Directory (if method is "directory") or that of a Thing (otherwise). -

                                      -

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

                                      -

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

                                      -
                                      - -

                                      Discovery Examples

                                      -

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

                                      - 
                                      -        let discovery = WOT.discover({ method: "local" });
-        do {
-          let td = await discovery.next();
-          console.log("Found Thing Description for " + td.name);
-          let thing = WOT.consume(td);
-          console.log("Thing name: " + thing.instance.name);
-        } while (!discovery.done);
-
                                      -

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

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

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

                                      - 
                                      -        let discovery = WOT.discover({ method: "multicast" });
-        setTimeout( () => {
-            discovery.stop();
-            console.log("Stopped open-ended discovery");
-          },
-          10000);
-        do {
-          let td = await discovery.next();
-          let thing = WOT.consume(td);
-          console.log("Thing name: " + thing.instance.name);
-        } while (!discovery.done);
-
                                      -
                                      -
                                      -

                                      The ConsumedThing interface

                                      @@ -1418,6 +1137,307 @@

                                      ExposedThing Examples

                                    +
                                    +

                                    Discovery

                                    +

                                    + Discovery is basically 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. +

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

                                    The discover() method

                                    +

                                    + Starts the discovery process that will provide ThingDescription objects of Thing Descriptions that match an optional filter argument which can specify the discovery method and match a specific source URL, a query and a template object. Check the examples. The method MUST run the following steps: +

                                      +
                                    1. + If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps. +
                                      2. +
                                    2. + If this method is not supported by the implementation, throw NotSupportedError and terminate these steps. +
                                      3. +
                                    3. + Construct a ThingDiscovery object discovery using filter. +
                                      4. +
                                    4. + Invoke the discovery.start() method. +
                                      5. +
                                    5. + Return discovery. +
                                      6. +
                                    +

                                    +
                                    + +
                                    +

                                    The ThingDiscovery interface

                                    +

                                    + Constructed given a filter and provides the events and methods controlling the discovery process. +

                                    + 
                                    +        [Constructor(optional ThingFilter filter), SecureContext, Exposed=(Window,Worker)]
+        interface ThingDiscovery {
+          readonly attribute ThingFilter? filter;
+          readonly attribute boolean active;
+          readonly attribute boolean done;
+          readonly attribute Error? error;
+          void start();
+          Promise<ThingDescription> next();
+          void stop();
+        };
+
                                    +

                                    + The discovery results internal slot is an internal queue for temporarily storing the found ThingDescription objects until they are consumed by the application using the next() method. +

                                    +

                                    + The filter property represents the discovery filter of type ThingFilter specified for the discovery. +

                                    +

                                    + The active property is true when the discovery is actively ongoing on protocol level (i.e. new TDs may still arrive) and false otherwise. +

                                    +

                                    + The done property is true if the discovery has been completed with no more results to report and discovery results is also empty. +

                                    +

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

                                    +

                                    + When ThingDiscovery is created, active and done are false, error is null. The start() sets active to true. The stop() method sets active to false, but done may be still false if there are ThingDescription objects in the discovery results not yet consumed with next(). During successive calls of next(), active may be true or false, but done is set to false by next() only when both active is false and discovery results is empty. +

                                    + +

                                    The start() method

                                    +

                                    + Starts the discovery process. The method MUST run the following steps: +

                                      +
                                    1. + If invoking this method is not allowed for the current scripting context for security reasons, set this.error to SecurityError and terminate these steps. +
                                      2. +
                                    2. + If discovery is not supported by the implementation, set this.error to NotSupportedError and terminate these steps. +
                                      3. +
                                    3. + If this.filter is defined, +
                                        +
                                      • + Let filter denote this.filter. +
                                        • +
                                      • + If filter.query is defined, pass it as an opaque string to the underlying implementation to be matched against discovered items. The underlying implementation is responsible to parse it e.g. as a SPARQL or JSON query and match it against the Thing Descriptions found during the discovery process. If queries are not supported, set this.error to NotSupportedError and terminate these steps. +
                                        • +
                                      +
                                      4. +
                                    4. + Create the discovery results internal slot for storing discovered ThingDescription objects. +
                                      5. +
                                    5. + Request the underlying platform to start the discovery process, with the following parameters: +
                                        +
                                      • + If filter.method is not defined or the value is "any", use the widest discovery method supported by the underlying platform. +
                                        • +
                                      • + Otherwise if filter.method is "local", use the local Thing Directory for discovery. Usually that defines Things deployed in the same device, or connected to the device in slave mode (e.g. sensors connected via Bluetooth or a serial connection). +
                                        • +
                                      • + Otherwise if filter.method is "directory", use the remote Thing Directory specified in filter.url. +
                                        • +
                                      • + Otherwise if filter.method is "multicast", use all the multicast discovery protocols supported by the underlying platform. +
                                        • +
                                      +
                                      6. +
                                    6. + When the underlying platform has started the discovery process, set the active property to true. +
                                      7. +
                                    7. + Whenever a new Thing Description td is discovered by the underlying platform, run the following sub-steps: +
                                        +
                                      1. + Fetch td. +
                                        2. +
                                      2. + Let json be the result of running the parse a ThingDescription string steps on td. If that fails, set this.error to SyntaxError, discard td and continue the discovery process. +
                                        3. +
                                      3. + If filter.query is defined, check if json is a match for the query. The matching algorithm is encapsulated by implementations. If that returns false, discard td and continue the discovery process. +
                                        4. +
                                      4. + If filter.fragment is defined, for each property defined in it, check if that property exists in json.properties and has the same value. If this is false in any checks, discard td and continue the discovery process. +
                                        5. +
                                      5. + Otherwise add td to the discovery results. +
                                        6. +
                                      6. + At this point implementations MAY control the flow of the discovery process (depending on memory constraints, for instance temporarily stop discovery if the queue is getting too large, or resume discovery when the queue is emptied sufficiently). +
                                        7. +
                                      +
                                      8. +
                                    8. + Whenever an error occurs during the discovery process, +
                                        +
                                      1. + Set this.error to a new Error object error. Set error.name to 'DiscoveryError'. +
                                        2. +
                                      2. + If there was an error code or message provided by the Protocol Bindings, set error.message to that value as string. +
                                        3. +
                                      3. + If the error is irrecoverable and discovery has been stopped by the underlying platform, set this.active to false. +
                                        4. +
                                      +
                                      9. +
                                    9. + When the underlying platform reports the discovery process has completed, set this.active to false. +
                                      10. +
                                    +

                                    +
                                    + +

                                    The next() method

                                    +

                                    + Provides the next discovered ThingDescription object. The method MUST run the following steps: +

                                      +
                                    1. + Return a Promise promise and execute the next steps in parallel. +
                                      2. +
                                    2. + If this.active is true, wait until the discovery results internal slot is not empty. +
                                      3. +
                                    3. + If discovery results is empty and this.active is false, set this.done to true and reject promise. +
                                      4. +
                                    4. + Remove the first ThingDescription object td from discovery results. +
                                      5. +
                                    5. + Resolve promise with td and terminate these steps. +
                                      6. +
                                    +

                                    +
                                    + +

                                    The stop() method

                                    +

                                    + 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 inactive. The method MUST run the following steps: +

                                      +
                                    1. + 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. +
                                      2. +
                                    2. + Set this.active to false. +
                                      3. +
                                    +

                                    +
                                    + +
                                    +

                                    The DiscoveryMethod enumeration

                                    + 
                                    +        typedef DOMString DiscoveryMethod;
+
                                    +

                                    + Represents the discovery type to be used: +

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

                                    The ThingFilter dictionary

                                    +

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

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

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

                                    +

                                    + The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, for instance the URL of a Thing Directory (if method is "directory") or that of a Thing (otherwise). +

                                    +

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

                                    +

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

                                    +
                                    +
                                    + +

                                    Discovery Examples

                                    +

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

                                    + 
                                    +        let discovery = WOT.discover({ method: "local" });
+        do {
+          let td = await discovery.next();
+          console.log("Found Thing Description for " + td.name);
+          let thing = WOT.consume(td);
+          console.log("Thing name: " + thing.instance.name);
+        } while (!discovery.done);
+
                                    +

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

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

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

                                    + 
                                    +        let discovery = WOT.discover({ method: "multicast" });
+        setTimeout( () => {
+            discovery.stop();
+            console.log("Stopped open-ended discovery");
+          },
+          10000);
+        do {
+          let td = await discovery.next();
+          let thing = WOT.consume(td);
+          console.log("Thing name: " + thing.instance.name);
+        } while (!discovery.done);
+
                                    +
                                    +
                                    +

                                    Security and Privacy

                                    A detailed discussion of security and privacy considerations for the Web of Things, including a threat model that can be adapted to various circumstances, is From ab5ee2a2bb610777f3231a4984d12ef8d0f1a243 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 6 May 2019 17:42:42 +0300 Subject: [PATCH 317/464] Editorial fixes: move discovery use cases, add links, correct Thingweb Signed-off-by: Zoltan Kis --- index.html | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/index.html b/index.html index 86e98ff7..7c309859 100644 --- a/index.html +++ b/index.html @@ -127,7 +127,7 @@ The specification deliberately follows the WoT Thing Description specification closely. It is possible to implement simpler APIs on top of this API, or implementing directly the WoT network facing interface (i.e. the WoT Interface).

                                    - This specification is implemented at least by the ThingWeb project also known as node-wot, which is considered the reference open source implementation at the moment. Check its source code, including examples. Other, closed source implementations have been made by WG member companies and tested against node-wot in plug-fests. + This specification is implemented at least by the Thingweb project also known as node-wot, which is considered the reference open source implementation at the moment. Check its source code, including examples. Other, closed source implementations have been made by WG member companies and tested against node-wot in plug-fests.

                                    @@ -179,20 +179,6 @@

                                    The following scripting use cases are supported in this specification:

                                    -

                                    Discovery

                                    -
                                      -
                                    • Discover Things in a network by sending a broadcast request.
                                      • -
                                    • Discover Things running in the local WoT Runtime.
                                      • -
                                    • Discover nearby Things, for instance connected by NFC or Bluetooth.
                                      • -
                                    • Discover Things by sending a discovery request to a given registry.
                                      • -
                                    • Discover Things filtered by filters defined on Thing Descriptions
                                      • -
                                    • Discover Things filtered by semantic queries.
                                      • -
                                    • Stop or suppress an ongoing discovery process.
                                      • -
                                    • - Optionally specify a timeout to the discovery process after which it is stopped/suppressed. -
                                      • -
                                    -

                                    Consuming a Thing

                                    • @@ -210,6 +196,7 @@
                                    +

                                    Exposing a Thing

                                    • @@ -251,12 +238,27 @@
                                    + +

                                    Discovery

                                    +
                                      +
                                    • Discover Things in a network by sending a broadcast request.
                                      • +
                                    • Discover Things running in the local WoT Runtime.
                                      • +
                                    • Discover nearby Things, for instance connected by NFC or Bluetooth.
                                      • +
                                    • Discover Things by sending a discovery request to a given registry.
                                      • +
                                    • Discover Things filtered by filters defined on Thing Descriptions
                                      • +
                                    • Discover Things filtered by semantic queries.
                                      • +
                                    • Stop or suppress an ongoing discovery process.
                                      • +
                                    • + Optionally specify a timeout to the discovery process after which it is stopped/suppressed. +
                                      • +
                                    +

                                  The WOT object

                                  - Defines the API entry point exposed as a singleton and contains the API methods for discovering, consuming and producing a Thing based on Thing Descriptions. + Defines the API entry point exposed as a singleton and contains the API methods for consuming and producing a Thing based on Thing Descriptions, together with a generic discovery API.

                                  Browser implementations should use a namespace object such as navigator.wot. Standalone runtimes may expose the API object through mechanisms like require() or import. From d9c18c76473064ea6589db5f9e07a3b4c6e1b65a Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 13 May 2019 17:10:38 +0300 Subject: [PATCH 318/464] Fix #169: Property observation Signed-off-by: Zoltan Kis --- index.html | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/index.html b/index.html index 7c309859..5bf2f48b 100644 --- a/index.html +++ b/index.html @@ -420,8 +420,8 @@

                                  The ConsumedThing interface

                                  Promise<void> writeProperty(DOMString propertyName, any value); Promise<void> writeMultipleProperties(object valueMap); Promise<any> invokeAction(DOMString actionName, optional any params); - Promise<void> subscribeProperty(DOMString name, WotListener listener); - Promise<void> unsubscribeProperty(DOMString name); + Promise<void> observeProperty(DOMString name, WotListener listener); + Promise<void> unobserveProperty(DOMString name); Promise<void> subscribeEvent(DOMString name, WotListener listener); Promise<void> unsubscribeEvent(DOMString name); readonly attribute ThingInstance instance; @@ -600,7 +600,7 @@

                                  The writeMultipleProperties() method

                                  -

                                  The subscribeProperty() method

                                  +

                                  The observeProperty() method

                                  Makes a request for Property value change notifications. Takes a string argument propertyName and returns success or failure. The method MUST run the following steps:

                                    @@ -624,7 +624,7 @@

                                    The subscribeProperty() method

                                  -

                                  The unsubscribeProperty() method

                                  +

                                  The unobserveProperty() method

                                  Makes a request for unsubscribing from Property value change notifications. Takes a string argument propertyName and returns success or failure. The method MUST run the following steps:

                                    @@ -738,7 +738,7 @@

                                    ConsumedThing Examples

                                    }; try { // subscribe to property change for “temperature” - await thing.subscribeProperty("temperature", value => { + await thing.observeProperty("temperature", value => { console.log("Temperature changed to: " + value); }); // subscribe to the “ready” event defined in the TD From 2fce1fd6bbf119790db65c4b21fbbf3e6db8064f Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Tue, 14 May 2019 14:45:38 +0200 Subject: [PATCH 319/464] feat: add observeProperty/unobserveProperty as well as subscribeEvent/unsubscribeEvent --- typescript/index.d.ts | 10 ++++++++++ typescript/package.json | 2 +- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index 2e567a0e..15b4a5f4 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -207,9 +207,19 @@ export interface ThingInstance extends ThingFragment { writeMultipleProperties(valueMap: { [key: string]: any }): Promise; invokeAction(actionName: string, parameter?: any): Promise; + + observeProperty(name: string, listener: WotListener): Promise; + unobserveProperty(name: string): Promise; + + subscribeEvent(name: string, listener: WotListener): Promise; + unsubscribeEvent(name: string): Promise; + // XXX add more + // e.g., readonly attribute ThingInstance instance; } +export declare type WotListener = (data: any) => void; + /** * The Interaction interface is an abstract class to represent Thing interactions: Properties, Actions and Events. */ diff --git a/typescript/package.json b/typescript/package.json index c92dc13b..6285a640 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.7.0-NEXT-SNAPSHOT.5", + "version": "0.7.0-NEXT-SNAPSHOT.6", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From ce8e2133fb9768d0019979f5117bcd22a6db86dd Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Thu, 16 May 2019 10:36:53 +0200 Subject: [PATCH 320/464] fix: align with latest CR thing-description changes * rename "name" to "title" * add "titles" to thing level * change "Versioning" to "VersionInfo" * change "lastModified" to "modified" --- typescript/index.d.ts | 18 ++++++++++-------- typescript/package.json | 2 +- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index 6e50dc7a..e7d9465b 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -85,7 +85,7 @@ export declare enum DiscoveryMethod { export declare type ThingDescription = string; /** Carries version information about the TD instance. If required, additional version information such as firmware and hardware version (term definitions outside of the TD namespace) can be extended here. */ -export interface Versioning { +export interface VersionInfo { instance?: string; } @@ -95,22 +95,24 @@ export interface Versioning { export interface ThingFragment { /** A hint to gernerate the identifier for the Thing */ id?: string; - /** The name attribute represents the user given name of the Thing */ - name?: string; + /** The title attribute provides a human-readable title */ + title?: string; + /** Provides multi-language human-readable titles */ + titles?: MultiLanguage; /** Define the base URI that is valid for all defined local interaction resources */ - base?: string; + base?: string; // anyURI /** A human-readable description of the Thing */ description?: string; /** Human-readable descriptions in different languages */ descriptions?: MultiLanguage; /** Information about the Thing maintainer, e.g., author or contact URI */ - support?: string; + support?: string; // anyURI /** Provides information when the TD instance was last modified */ - lastModified?: string; + modified?: string; // dateTime /** Provides information when the TD instance was created */ - created?: string; + created?: string; // dateTime /** Provides version information */ - version?: Versioning; + version?: VersionInfo; /** Set of named security configurations (definitions only). Not actually applied unless names are used in a security section */ securityDefinitions?: { [key: string]: Security } diff --git a/typescript/package.json b/typescript/package.json index 6cca2fc6..a7bbfe37 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.7.0-SNAPSHOT.1", + "version": "0.6.2-SNAPSHOT.1", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From 0dcb8d2da12bde96537a602450f7914cfd28086a Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Thu, 16 May 2019 15:44:00 +0200 Subject: [PATCH 321/464] fix: remaining change "name" to "title" --- typescript/index.d.ts | 4 ++-- typescript/package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index e7d9465b..15424c6f 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -188,8 +188,8 @@ export interface EventFragment extends InteractionFragment { export interface ThingInstance extends ThingFragment { /** id becomes mandatory for Thing instances */ id: string; - /** name becomes mandatory for Thing instances */ - name: string; + /** title becomes mandatory for Thing instances */ + title: string; /** base becomes available for Thing instances (part of binding metadata) */ base?: string; diff --git a/typescript/package.json b/typescript/package.json index a7bbfe37..907cd470 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.6.2-SNAPSHOT.1", + "version": "0.6.2-SNAPSHOT.2", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From dad958d3683d23bef41ba05e54c3c1d1901b8691 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 12 Jun 2019 16:21:09 +0300 Subject: [PATCH 322/464] Fix ReSpec error, add data-cite to Error Signed-off-by: Zoltan Kis --- index.html | 1 + 1 file changed, 1 insertion(+) diff --git a/index.html b/index.html index 5bf2f48b..61d75a18 100644 --- a/index.html +++ b/index.html @@ -1664,6 +1664,7 @@

                                    Stale TD Security Risk

                                    Promise, + Error, JSON, JSON.stringify, JSON.parse and From 86208da72a4cde1ed4d308a666416a398a0b2ab2 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 12 Jun 2019 16:23:29 +0300 Subject: [PATCH 323/464] Fix #171: change name to title Signed-off-by: Zoltan Kis --- index.html | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/index.html b/index.html index 61d75a18..5d113de7 100644 --- a/index.html +++ b/index.html @@ -306,7 +306,7 @@

                                    The WOT object

                                    // ... additional checks possible on res.headers let td = await res.json(); // could also be res.text() let thing = WOT.consume(td); - console.log("Thing name: " + thing.instance.name); + console.log("Thing name: " + thing.instance.title); } catch (err) { console.log("Fetching TD failed", err.message); } @@ -732,7 +732,7 @@

                                    ConsumedThing Examples

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

                                    The ThingFilter dictionary

                                    let discovery = WOT.discover({ method: "local" }); do { let td = await discovery.next(); - console.log("Found Thing Description for " + td.name); + console.log("Found Thing Description for " + td.title); let thing = WOT.consume(td); - console.log("Thing name: " + thing.instance.name); + console.log("Thing name: " + thing.instance.title); } while (!discovery.done);

                                    @@ -1413,9 +1413,9 @@

                                    The ThingFilter dictionary

                                    3000); do { let td = await discovery.next(); - console.log("Found Thing Description for " + td.name); + console.log("Found Thing Description for " + td.title); let thing = WOT.consume(td); - console.log("Thing name: " + thing.instance.name); + console.log("Thing name: " + thing.instance.title); } while (!discovery.done); if (discovery.error) { console.log("Discovery stopped because of an error: " + error.message); @@ -1434,7 +1434,7 @@

                                    The ThingFilter dictionary

                                    do { let td = await discovery.next(); let thing = WOT.consume(td); - console.log("Thing name: " + thing.instance.name); + console.log("Thing name: " + thing.instance.title); } while (!discovery.done);
                                  From cf61cb97a421145b6a289ea5e30aa2420e743e01 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 12 Jun 2019 21:13:08 +0300 Subject: [PATCH 324/464] Fix #173: separate client and server interfaces Signed-off-by: Zoltan Kis --- index.html | 66 ++++++++++++++++++++++-------------------------------- 1 file changed, 27 insertions(+), 39 deletions(-) diff --git a/index.html b/index.html index 5d113de7..f0608b32 100644 --- a/index.html +++ b/index.html @@ -165,7 +165,7 @@ This specification describes how to expose and consume Things by a script.

                                  - Typically scripts are meant to be used on devices able to provide resources (with a WoT Interface) for managing (installing, updating, running) scripts, such as bridges or gateways that expose and control simpler devices as WoT Things. + Typically scripts are meant to be used on bridges or gateways that expose and control simpler devices as WoT Things and have means to handle (e.g. install, uninstall, update etc.) and run scripts.

                                  This specification does not make assumptions on how the WoT Runtime handles and runs scripts, including single or multiple tenancy, script deployment and lifecycle management. The API already supports the generic mechanisms that make it possible to implement script management, for instance by exposing a manager Thing whose Actions (action handlers) implement script lifecycle management operations. @@ -189,9 +189,9 @@

                                4. Observe value changes of a Property.
                                5. Invoke an Action.
                                6. Observe WoT Events emitted by the Thing.
                                  7. -
                                7. Observe changes to the Thing Description of the Thing.
                                  8. -
                                8. Get the Thing Description.
                                  9. -
                                9. Get the list of linked resources based on the Thing Description.
                                  10. +
                                10. + Introspect the Thing Description, including the list of linked resources based on the Thing Description. +
                                  11. @@ -255,19 +255,18 @@
                              -
                              -

                              The WOT object

                              +
                              +

                              The ThingClient API object

                              - Defines the API entry point exposed as a singleton and contains the API methods for consuming and producing a Thing based on Thing Descriptions, together with a generic discovery API. + Defines the WoT client API entry point exposed as a singleton and contains the API method for consuming a Thing based on Thing Description.

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

                                     [SecureContext, Exposed=(Window,Worker)]
-      interface WOT {
+      interface ThingClient {
         ConsumedThing consume(ThingDescription td);
-        ExposedThing produce(ThingDescription td);
       };
       typedef (USVString or object) ThingDescription;
       typedef object ThingInstance;
@@ -382,6 +381,23 @@ 
                              The WOT object
                              +
                              + +
                              +

                              The ThingServer API object

                              +

                              + Defines the WoT server API entry point exposed as a singleton and contains the API method for producing a Thing based on Thing Descriptions. +

                              +

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

                              + 
                              +      [SecureContext, Exposed=(Window,Worker)]
+      interface ThingServer {
+        ExposedThing produce(ThingDescription td);
+      };
+
                              +

                              The produce() method

                              Accepts a td argument and returns an ExposedThing object that extends ConsumedThing with a server interface, i.e. the ability to define request handlers. The method MUST run the following steps: @@ -404,7 +420,7 @@

                              The WOT object

                            -
                          +

                        The ConsumedThing interface

                        @@ -1139,39 +1155,11 @@

                        ExposedThing Examples

                        -
                        +

                        Discovery

                        Discovery is basically 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.

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

                        The discover() method

                        -

                        - Starts the discovery process that will provide ThingDescription objects of Thing Descriptions that match an optional filter argument which can specify the discovery method and match a specific source URL, a query and a template object. Check the examples. The method MUST run the following steps: -

                          -
                        1. - If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps. -
                          2. -
                        2. - If this method is not supported by the implementation, throw NotSupportedError and terminate these steps. -
                          3. -
                        3. - Construct a ThingDiscovery object discovery using filter. -
                          4. -
                        4. - Invoke the discovery.start() method. -
                          5. -
                        5. - Return discovery. -
                          6. -
                        -

                        -

                        The ThingDiscovery interface

                        From adfd0a0b66bf23fc14264fecf557a8aea514ca99 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Thu, 13 Jun 2019 23:30:06 +0300 Subject: [PATCH 325/464] Remove ThingInstance and string ThingDescription Signed-off-by: Zoltan Kis --- index.html | 351 +++++++++++++++++++---------------------------------- 1 file changed, 127 insertions(+), 224 deletions(-) diff --git a/index.html b/index.html index f0608b32..e2dc7ffd 100644 --- a/index.html +++ b/index.html @@ -268,27 +268,13 @@

                        The ThingClient API object

                        interface ThingClient { ConsumedThing consume(ThingDescription td); }; - typedef (USVString or object) ThingDescription; - typedef object ThingInstance; + typedef object ThingDescription;

                        The ThingDescription type

                        - Represents a Thing Description (TD). It is expected to be either a ThingDescription string (a JSON-serialized object as described in the TD serialization), or a ThingDescription object (a parsed JSON object validated using JSON schema validation). A ThingDescription object is obtained by parsing a ThingDescription string. -

                        -

                        - To parse a ThingDescription string td, run the following steps: -

                          -
                        1. - If td is not a string, throw TypeError and terminate these steps. -
                          2. -
                        2. - Let json be the result of invoking parse JSON from bytes on td. If that fails, throw SyntaxError and terminate these steps. -
                          3. -
                        3. - Return json. -
                          4. -
                        + Represents a Thing Description (TD). It is expected to be + a parsed JSON object validated using JSON schema validation).

                        @@ -303,31 +289,37 @@

                        The ThingClient API object

                        try { let res = await fetch('https://tds.mythings.biz/sensor11'); // ... additional checks possible on res.headers - let td = await res.json(); // could also be res.text() - let thing = WOT.consume(td); - console.log("Thing name: " + thing.instance.title); + let td = await res.json(); + let thing = ThingClient.consume(td); + console.log("Thing name: " + thing.td.title); } catch (err) { console.log("Fetching TD failed", err.message); }
                        -

                        The ThingInstance type

                        -

                        - Denotes an object that is obtained from a ThingDescription object and represents an instantiated TD Thing, i.e. a Thing Description that has been initialized in the local WoT Runtime. -

                        +

                        The consume() method

                        - To instantiate a TD, given td, run the following steps: + Expects an td argument and returns a ConsumedThing object that represents a client interface to operate with the Thing. The method MUST run the following steps:

                        1. - If the td argument is not a string or an object, throw TypeError and terminate these steps. + If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps. +
                          2. +
                        2. + Let thing be a new ConsumedThing object.
                        3. - If td is a string, let json be the result of running the parse a ThingDescription string steps on td. If that throws an error, re-throw the error and terminate these steps. + Let thing.td be the result of running the instantiate a TD steps on td. If that throws, re-throw the error and terminate these steps.
                        4. - If td is an object, let json be td. + Return thing.
                          5. +
                        +

                        +

                        + After constructing a ConsumedThing, its Thing Description td needs to be instantiated, i.e. initialized with specific values provided by the underlying platform. + To instantiate a TD, given td, run the following steps: +

                        1. Let instance be an object with properties and default values defined in TD Thing.

                          @@ -335,9 +327,9 @@

                          The ThingClient API object

                        2. - Update the properties of instance also defined in json with the values defined in json. + Update the properties of instance also defined in td with the values defined in td.

                          - When more efficient, implementations MAY reverse the last two steps, i.e. let instance be the result of adding json the missing properties with default values as defined in TD specification. + When more efficient, implementations MAY reverse the last two steps, i.e. let instance be the result of adding td the missing properties with default values as defined in TD specification.

                        3. @@ -364,23 +356,6 @@

                          The ThingClient API object

                        -

                        The consume() method

                        -

                        - Accepts an td argument and returns a ConsumedThing object that represents a client interface to operate with the Thing. The method MUST run the following steps: -

                          -
                        1. - Let instance be the result of running the instantiate a TD steps on td. If that throws, re-throw the error and terminate these steps. -
                          2. -
                        2. - Let thing be a new ConsumedThing object constructed with instance. -
                          3. -
                        3. - Return thing. -
                          4. -
                        -

                        -
                        -
                        @@ -400,19 +375,22 @@

                        The ThingServer API object

                        The produce() method

                        - Accepts a td argument and returns an ExposedThing object that extends ConsumedThing with a server interface, i.e. the ability to define request handlers. The method MUST run the following steps: + Expects a td argument and returns an ExposedThing object that extends ConsumedThing with a server interface, i.e. the ability to define request handlers. The method MUST run the following steps:

                        1. If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
                        2. - Let instance be the result of running the instantiate a TD steps on td. If that throws, re-throw the error and terminate these steps. + Let thing be a new ExposedThing object.
                        3. - Let thing be a new ExposedThing object constructed with instance. The internal properties of thing.instance SHOULD be used for setting up the WoT Interactions based on the Thing Description as explained in [[!WOT-TD]]. This part is private to the implementations. + Let thing.td be the result of running the instantiate a TD steps on td. If that throws, re-throw the error and terminate these steps. +

                          + Implementations should use thing.td for setting up the WoT Interactions based on the Thing Description as explained in [[WOT-TD]] and [[WOT-PROTOCOL-BINDINGS]]. This is private to the implementations and out of scope of this specification. +

                        4. - For each Property definition in thing.instance.properties initialize an internal observer list in order to store observe request data needed to notify the observers on value changes. + For each Property definition in thing.td.properties initialize an internal observer list in order to store observe request data needed to notify the observers on value changes.
                        5. Return thing. @@ -428,7 +406,6 @@

                          The ConsumedThing interface

                          Represents a client API to operate a Thing. 

                          -      [Constructor(ThingInstance instance), SecureContext, Exposed=(Window,Worker)]
       interface ConsumedThing {
         Promise<any> readProperty(DOMString propertyName);
         Promise<object> readAllProperties();
@@ -440,44 +417,27 @@ 
                          The ConsumedThing interface
                          
         Promise<void> unobserveProperty(DOMString name);
         Promise<void> subscribeEvent(DOMString name, WotListener listener);
         Promise<void> unsubscribeEvent(DOMString name);
-        readonly attribute ThingInstance instance;
+        readonly attribute ThingDescription td;
       };
       callback WotListener = void(any data);
                          -

                          Constructing ConsumedThing

                          -

                          - A ConsumedThing object is constructed by providing a ThingInstance object that initializes the instance attribute of ConsumedThing, without running the instantiate a TD steps. -

                          +

                          The td property

                          - The ConsumedThing objects SHOULD only be created by the WOT.consume() method which internally uses this constructor by providing a ThingInstance object with a ThingInstance object obtained either directly or by parsing a ThingDescription and also running the instantiate a TD steps on it. -

                          -

                          - Note that a valid ThingInstance object can be provided either by the instantiate a TD steps, or also by external libraries that implement [[!WOT-TD]]. + Represents the instantiated Thing Description of this Thing.

                          -
                          -

                          The WotListener callback

                          +

                          The WotListener callback

                          User provided callback that takes any argument and is used for Property change and Event subscriptions. As subscriptions are WoT interactions, they are not modelled with software events.

                          -

                          The readProperty() method

                          +

                          The readProperty() method

                          Reads a Property value. Takes a string argument propertyName and returns a Property value represented as any type. The method MUST run the following steps:

                            @@ -500,7 +460,7 @@

                            The readProperty() method

                            Run the validate Property value sub-steps on value:
                            1. - Based on the DataSchema definition, value MUST be a JSON value and comply to the data schema defined for the Property that is found in this.instance.properties[propertyName]. + Based on the DataSchema definition, value MUST be a JSON value and comply to the data schema defined for the Property that is found in this.td.properties[propertyName].
                            2. If this fails, throw SyntaxError, otherwise return value. @@ -517,7 +477,7 @@

                              The readProperty() method

                          -

                          The readMultipleProperties() method

                          +

                          The readMultipleProperties() method

                          Reads multiple Property values with one or multiple requests. Takes one argument, a sequence of strings propertyNames and returns an object with keys from propertyNames and values returned by this algorithm. The method MUST run the following steps:

                            @@ -544,12 +504,12 @@

                            The readMultipleProperties() method

                          -

                          The readAllProperties() method

                          +

                          The readAllProperties() method

                          Reads all properties of the Thing with one or multiple requests. Takes no arguments. It returns an object with keys from Property names and values returned by this algorithm. The method MUST run the following steps:

                          1. - Let propertyNames be a sequence created from all the Property names of this Thing as found in this.instance.properties. + Let propertyNames be a sequence created from all the Property names of this Thing as found in this.td.properties.
                          2. Let result be the result of running the readMultipleProperties() steps on propertyNames and options. If that fails, reject promise with that error and terminate these steps. @@ -562,7 +522,7 @@

                            The readAllProperties() method

                          -

                          The writeProperty() method

                          +

                          The writeProperty() method

                          Writes a single Property. Takes a string argument propertyName and a value argument value. It returns success or failure. The method MUST run the following steps:

                            @@ -589,7 +549,7 @@

                            The writeProperty() method

                          -

                          The writeMultipleProperties() method

                          +

                          The writeMultipleProperties() method

                          Writes a multiple Property values with one request. Takes one argument, an object properties with keys as Property names and values as Property values. It returns success or failure. The method MUST run the following steps:

                            @@ -616,7 +576,7 @@

                            The writeMultipleProperties() method

                          -

                          The observeProperty() method

                          +

                          The observeProperty() method

                          Makes a request for Property value change notifications. Takes a string argument propertyName and returns success or failure. The method MUST run the following steps:

                            @@ -640,7 +600,7 @@

                            The observeProperty() method

                          -

                          The unobserveProperty() method

                          +

                          The unobserveProperty() method

                          Makes a request for unsubscribing from Property value change notifications. Takes a string argument propertyName and returns success or failure. The method MUST run the following steps:

                            @@ -664,7 +624,7 @@

                            The unobserveProperty() method

                          -

                          The invokeAction() method

                          +

                          The invokeAction() method

                          Makes a request for invoking an Action and return the result. Takes a string argument actionName, and an optional argument parameters of type any. It returns the result of the Action or an error. The method MUST run the following steps:

                            @@ -691,7 +651,7 @@

                            The invokeAction() method

                          -

                          The subscribeEvent() method

                          +

                          The subscribeEvent() method

                          Makes a request for subscribing to Event notifications. Takes a string argument eventName and returns success or failure. The method MUST run the following steps:

                            @@ -715,7 +675,7 @@

                            The subscribeEvent() method

                          -

                          The unsubscribeEvent() method

                          +

                          The unsubscribeEvent() method

                          Makes a request for unsubscribing from Event notifications. Takes a string argument eventName and returns success or failure. The method MUST run the following steps:

                            @@ -741,14 +701,14 @@

                            The unsubscribeEvent() method

                            ConsumedThing Examples

                            - This example illustrates how to fetch a TD by URL, create a ConsumedThing, read metadata (name), read property value, subscribe to property change, subscribe to a WoT event, unsubscribe. + This example illustrates how to fetch a TD by URL, create a ConsumedThing, read metadata (title), read property value, subscribe to property change, subscribe to a WoT event, unsubscribe. 

                                     try {
           let res = await fetch("https://tds.mythings.org/sensor11");
           let td = res.json();
-          let thing = new ConsumedThing(td);
-          console.log("Thing " + thing.instance.title + " consumed.");
+          let thing = ThingClient.consume(td);
+          console.log("Thing " + thing.td.title + " consumed.");
         } catch(e) {
           console.log("TD fetch error: " + e.message); },
         };
@@ -783,7 +743,6 @@ 
                            The ExposedThing interface
                            
       The ExposedThing interface is the server API to operate the Thing that allows defining request handlers, Property, Action, and Event interactions.
     
                            
     
                            -      [Constructor(ThingInstance instance), SecureContext, Exposed=(Window,Worker)]
       interface ExposedThing: ConsumedThing {
         ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
         ExposedThing setPropertyWriteHandler(DOMString name, PropertyWriteHandler writeHandler);
@@ -796,21 +755,6 @@ 
                            The ExposedThing interface
                            
       callback PropertyWriteHandler = Promise<void>(any value);
       callback ActionHandler = Promise<any>(any parameters);
     
                            
-    
                            
-      
                            Constructing ExposedThing
                            
-      
                            
-        The ExposedThing interface extends ConsumedThing and is constructed by providing a ThingInstance object that initializes the instance attribute of ExposedThing, without running the instantiate a TD steps.
-      
                            
-      
                            
-        The ExposedThing objects SHOULD only be created by the produce() method which internally uses the ExposedThing constructor with a ThingInstance object obtained either directly or by parsing a ThingDescription and also running the instantiate a TD steps on it.
-      
                            
-      
                            
-        Note that a valid ThingInstance object can be provided either by the instantiate a TD steps, or also by external libraries that implement [[!WOT-TD]].
-      
                            
-      
                            
-         Note that an existing ThingInstance 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 another ExposedThing object. This is the current way of adding and removing Property, Action and Event definitions, and later adding the service handler functions. This is illustrated in the examples.
-      
                            
-    
                            
 
     
                            
       
                            The PropertyReadHandler callback
                            
@@ -965,7 +909,7 @@ 
                            The ActionHandler callback
                            
             If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
           
           
                          1. 
-            If an Event with the name name is not found in this.instance.events, throw NotFoundError and terminate these steps.
+            If an Event with the name name is not found in this.td.events, throw NotFoundError and terminate these steps.
           
                            2. 
           
                          2. 
             Make a request to the underlying platform to send an Event with data attached as property, using the Protocol Bindings, then terminate these steps.
@@ -1051,7 +995,7 @@ 
                            ExposedThing Examples
                            
               onchange: temperatureValueDefinition
             }
           };
-          let thing1 = WOT.produce(tdFragment);
+          let thing1 = ThingServer.produce(tdFragment);
           // TODO: add service handlers
           await thing1.expose();
           // define Thing business logic
@@ -1070,7 +1014,7 @@ 
                            ExposedThing Examples
                            
       
                                     try {
           // create a deep copy of thing1 instance
-          let instance = JSON.parse(JSON.stringify(thing1.instance));
+          let instance = JSON.parse(JSON.stringify(thing1.td));
           const statusValueDefinition = {
             type: "object",
             properties: {
@@ -1109,7 +1053,7 @@ 
                            ExposedThing Examples
                            
           };
           instance.events["onstatuschange"] = statusValueDefinition;
           instance.forms = [...];  // update
-          var thing2 = WOT.produce(instance);
+          var thing2 = ThingServer.produce(instance);
           // TODO: add service handlers
           await thing2.expose();
           });
@@ -1117,87 +1061,50 @@ 
                            ExposedThing Examples
                            
            console.log("Error creating ExposedThing: " + err);
         }
       
                            
-
-      
                            -        // Typically a TD is obtained from somewhere, but let's write it now.
-        let thingDescription = '{ \
-          "name": "mySensor", \
-          "@context": [ "http://www.w3.org/ns/td",\
-             "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ],\
-          "@type": [ "Thing", "Sensor" ], \
-          "geo:location": "testspace", \
-          "properties": { \
-            "prop1": { \
-              "type": "number",\
-              "@type": [ "Property", "Temperature" ], \
-              "saref:TemperatureUnit": "degree_Celsius" \
-          } } }';
-        try {
-          // note that produce() fails if the TD contains an error
-          let thing = WOT.produce(thingDescription);
-          // Interactions were added from TD
-          // WoT adds generic handler for reading any property
-          // Define a specific handler for a Property
-          thing.setPropertyReadHandler("prop1", () => {
-            return new Promise((resolve, reject) => {
-                let examplePropertyValue = 5;
-                resolve(examplePropertyValue);
-              },
-              e => {
-                console.log("Error");
-              });
-          });
-          await thing.expose();
-        } catch(err) {
-           console.log("Error creating ExposedThing: " + err);
-        }
-      
                            
     
                            3.
                            -
                            -

                            Discovery

                            +
                            +

                            The ThingDiscovery interface

                            - Discovery is basically 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. + 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 ThingDiscovery object is constructed given a filter and provides the properties and methods controlling the discovery process. +

                            + 
                            +      [Constructor(optional ThingFilter filter), SecureContext, Exposed=(Window,Worker)]
+      interface ThingDiscovery {
+        readonly attribute ThingFilter? filter;
+        readonly attribute boolean active;
+        readonly attribute boolean done;
+        readonly attribute Error? error;
+        void start();
+        Promise<ThingDescription> next();
+        void stop();
+      };
+
                            +

                            + The discovery results internal slot is an internal queue for temporarily storing the found ThingDescription objects until they are consumed by the application using the next() method. +

                            +

                            + The filter property represents the discovery filter of type ThingFilter specified for the discovery. +

                            +

                            + The active property is true when the discovery is actively ongoing on protocol level (i.e. new TDs may still arrive) and false otherwise. +

                            +

                            + The done property is true if the discovery has been completed with no more results to report and discovery results is also empty. +

                            +

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

                            +

                            + When ThingDiscovery is created, active and done are false, error is null. The start() sets active to true. The stop() method sets active to false, but done may be still false if there are ThingDescription objects in the discovery results not yet consumed with next(). During successive calls of next(), active may be true or false, but done is set to false by next() only when both active is false and discovery results is empty.

                            -
                            -

                            The ThingDiscovery interface

                            -

                            - Constructed given a filter and provides the events and methods controlling the discovery process. -

                            - 
                            -        [Constructor(optional ThingFilter filter), SecureContext, Exposed=(Window,Worker)]
-        interface ThingDiscovery {
-          readonly attribute ThingFilter? filter;
-          readonly attribute boolean active;
-          readonly attribute boolean done;
-          readonly attribute Error? error;
-          void start();
-          Promise<ThingDescription> next();
-          void stop();
-        };
-
                            -

                            - The discovery results internal slot is an internal queue for temporarily storing the found ThingDescription objects until they are consumed by the application using the next() method. -

                            -

                            - The filter property represents the discovery filter of type ThingFilter specified for the discovery. -

                            -

                            - The active property is true when the discovery is actively ongoing on protocol level (i.e. new TDs may still arrive) and false otherwise. -

                            -

                            - The done property is true if the discovery has been completed with no more results to report and discovery results is also empty. -

                            -

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

                            -

                            - When ThingDiscovery is created, active and done are false, error is null. The start() sets active to true. The stop() method sets active to false, but done may be still false if there are ThingDescription objects in the discovery results not yet consumed with next(). During successive calls of next(), active may be true or false, but done is set to false by next() only when both active is false and discovery results is empty. -

                            - -

                            The start() method

                            +
                            +

                            The start() method

                            Starts the discovery process. The method MUST run the following steps:

                              @@ -1219,7 +1126,7 @@

                              The ThingDiscovery interface

                            1. - Create the discovery results internal slot for storing discovered ThingDescription objects. + Create the discovery results internal slot for storing discovered ThingDescription objects.
                            2. Request the underlying platform to start the discovery process, with the following parameters: @@ -1245,10 +1152,7 @@

                              The ThingDiscovery interface

                              Whenever a new Thing Description td is discovered by the underlying platform, run the following sub-steps:
                              1. - Fetch td. -
                                2. -
                              2. - Let json be the result of running the parse a ThingDescription string steps on td. If that fails, set this.error to SyntaxError, discard td and continue the discovery process. + Fetch td as a JSON object json. If that fails, set this.error to SyntaxError, discard td and continue the discovery process.
                              3. If filter.query is defined, check if json is a match for the query. The matching algorithm is encapsulated by implementations. If that returns false, discard td and continue the discovery process. @@ -1283,11 +1187,12 @@

                                The ThingDiscovery interface

                              -
                            +
                            -

                            The next() method

                            +
                            +

                            The next() method

                            - Provides the next discovered ThingDescription object. The method MUST run the following steps: + Provides the next discovered ThingDescription object. The method MUST run the following steps:

                            1. Return a Promise promise and execute the next steps in parallel. @@ -1299,16 +1204,17 @@

                              The ThingDiscovery interface

                              If discovery results is empty and this.active is false, set this.done to true and reject promise.
                            2. - Remove the first ThingDescription object td from discovery results. + Remove the first ThingDescription object td from discovery results.
                            3. Resolve promise with td and terminate these steps.

                            -
                            +
                            -

                            The stop() method

                            +
                            +

                            The stop() method

                            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 inactive. The method MUST run the following steps:

                              @@ -1320,10 +1226,10 @@

                              The ThingDiscovery interface

                            -
                            +
                            -
                            -

                            The DiscoveryMethod enumeration

                            +
                            +

                            The DiscoveryMethod enumeration

                                     typedef DOMString DiscoveryMethod;
                            @@ -1342,10 +1248,10 @@

                            The DiscoveryMethod enumeration

                            "multicast" for discovering Things in the device's network by using a supported multicast protocol. -
                            +
                            -
                            -

                            The ThingFilter dictionary

                            +
                            +

                            The ThingFilter dictionary

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

                            @@ -1369,31 +1275,31 @@

                            The ThingFilter dictionary

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

                            -
                            -

                            Discovery Examples

                            +
                            +

                            Discovery Examples

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

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

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

                                     let discoveryFilter = {
           method: "directory",
           url: "http://directory.wotservice.org"
         };
-        let discovery = WOT.discover(discoveryFilter);
+        let discovery = new ThingDiscovery(discoveryFilter);
         setTimeout( () => {
             discovery.stop();
             console.log("Discovery stopped after timeout.");
@@ -1402,8 +1308,8 @@ 
                            The ThingFilter dictionary
                            
         do {
           let td = await discovery.next();
           console.log("Found Thing Description for " + td.title);
-          let thing = WOT.consume(td);
-          console.log("Thing name: " + thing.instance.title);
+          let thing = ThingClient.consume(td);
+          console.log("Thing name: " + thing.td.title);
         } while (!discovery.done);
         if (discovery.error) {
           console.log("Discovery stopped because of an error: " + error.message);
@@ -1413,7 +1319,7 @@ 
                            The ThingFilter dictionary
                            
         The next example is for an open-ended multicast discovery, which likely won't complete soon (depending on the underlying protocol), so stopping it with a timeout is a good idea. It will likely deliver results one by one.
       
                            
       
                            -        let discovery = WOT.discover({ method: "multicast" });
+        let discovery = new ThingDiscovery({ method: "multicast" });
         setTimeout( () => {
             discovery.stop();
             console.log("Stopped open-ended discovery");
@@ -1421,8 +1327,8 @@ 
                            The ThingFilter dictionary
                            
           10000);
         do {
           let td = await discovery.next();
-          let thing = WOT.consume(td);
-          console.log("Thing name: " + thing.instance.title);
+          let thing = ThingClient.consume(td);
+          console.log("Thing name: " + thing.td.title);
         } while (!discovery.done);
                            @@ -1472,7 +1378,7 @@

                            Scripting Runtime Security and Privacy Risks

                            -

                            Corrupted Input Security and Privacy Risk

                            +

                            Corrupted Input Security and Privacy Risk

                            A typical way to compromise any process is to send it a corrupted input via one of the exposed interfaces. This can be done to a script instance @@ -1484,7 +1390,7 @@

                            Corrupted Input Security and Privacy Risk

                            -

                            Physical Device Direct Access Security and Privacy Risk

                            +

                            Physical Device Direct Access Security and Privacy Risk

                            In case a script is compromised or misbehaving, the underlying physical device (and potentially surrounded environment) can be damaged if a script can use directly exposed native device interfaces. If such interfaces lack safety checks on their inputs, they might bring the underlying physical device (or environment) to an unsafe state (i.e. device overheats and explodes).

                            @@ -1495,7 +1401,7 @@

                            Physical Device Direct Access Security and Privacy Risk

                            -

                            Provisioning and Update Security Risk

                            +

                            Provisioning and Update Security Risk

                            If the WoT Scripting Runtime supports post-manufacturing provisioning or updates of scripts, WoT Scripting Runtime or any related data @@ -1513,7 +1419,7 @@

                            Provisioning and Update Security Risk

                            -

                            Security Credentials Storage Security and Privacy Risk

                            +

                            Security Credentials Storage Security and Privacy Risk

                            Typically the WoT Scripting Runtime needs to store the security credentials that are provisioned to a WoT device to operate in WoT network. If an attacker can compromise the confidentiality or integrity of these credentials, then it can obtain access to the WoT assets, impersonate WoT things or devices or create Denial-Of-Service (DoS) attacks.

                            @@ -1532,7 +1438,7 @@

                            Script Security and Privacy Risks

                            -

                            Corrupted Script Input Security and Privacy Risk

                            +

                            Corrupted Script Input Security and Privacy Risk

                            A script instance may receive data formats defined by the TD, or data formats defined by the applications. While the WoT Scripting Runtime SHOULD perform validation on all input fields defined by the TD, scripts may be still exploited by input data.

                            @@ -1542,7 +1448,7 @@

                            Corrupted Script Input Security and Privacy Risk

                            -

                            Denial Of Service Security Risk

                            +

                            Denial Of Service Security Risk

                            If a script performs a heavy functional processing on received requests before the request is authenticated, it presents a great risk for Denial-Of-Service (DOS) attacks.

                            @@ -1554,7 +1460,7 @@

                            Denial Of Service Security Risk

                            -

                            Stale TD Security Risk

                            +

                            Stale TD Security Risk

                            During the lifetime of a WoT network, a content of a TD can change. This includes its identifier, which might not be an immutable one and might be updated periodically. @@ -1759,10 +1665,7 @@

                            Stale TD Security Risk

                            Align the discovery API to other similar APIs (such as W3C Generic Sensor API).
                          3. - Introduce ThingInstance for a simpler way to instrospect, add and remove WoT Interactions on Things. -
                            4. -
                          4. - Remove the large data definition API for constructing TDs and leverage using ThingInstance instead. + Remove the large data definition API for constructing TDs and leverage using ThingDescription instead.
                          5. Add missing algorithms and rework most existing ones. From 59ae0c8124b7de9794e9d39f7023e7fe1fcda75b Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Fri, 14 Jun 2019 21:50:00 +0300 Subject: [PATCH 326/464] Make constructible ConsumedThing, ExposedThing and ThingDiscovery primary API entry points Signed-off-by: Zoltan Kis --- index.html | 327 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 189 insertions(+), 138 deletions(-) diff --git a/index.html b/index.html index e2dc7ffd..9fb18260 100644 --- a/index.html +++ b/index.html @@ -162,7 +162,7 @@
                            6. - This specification describes how to expose and consume Things by a script. + This specification describes how to expose and consume Things by a script. Also, it defines a generic API for Thing discovery.

                            Typically scripts are meant to be used on bridges or gateways that expose and control simpler devices as WoT Things and have means to handle (e.g. install, uninstall, update etc.) and run scripts. @@ -170,9 +170,11 @@

                            This specification does not make assumptions on how the WoT Runtime handles and runs scripts, including single or multiple tenancy, script deployment and lifecycle management. The API already supports the generic mechanisms that make it possible to implement script management, for instance by exposing a manager Thing whose Actions (action handlers) implement script lifecycle management operations.

                            +

                            Use Cases

                            @@ -255,33 +257,18 @@
                            -
                            -

                            The ThingClient API object

                            -

                            - Defines the WoT client API entry point exposed as a singleton and contains the API method for consuming a Thing based on Thing Description. -

                            -

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

                            +
                            +

                            The ThingDescription type

                            -      [SecureContext, Exposed=(Window,Worker)]
-      interface ThingClient {
-        ConsumedThing consume(ThingDescription td);
-      };
       typedef object ThingDescription;
                            -

                            The ThingDescription type

                            -

                            - Represents a Thing Description (TD). It is expected to be - a parsed JSON object validated using JSON schema validation). -

                            -
                            +

                            + Represents a Thing Description (TD). It is expected to be + a parsed JSON object that is validated using JSON schema validation. +

                            Fetching a Thing Description

                            -

                            - This API works with Thing Descriptions that can be obtained either by direct fetch or by discovery. -

                            The fetch(url) method has been part of this API in earlier versions. However, now fetching a TD given a URL should be done with an external method, such as the Fetch API or a HTTP client library, which offer already standardized options on specifying fetch details.

                            @@ -290,115 +277,14 @@

                            The ThingClient API object

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

                            The consume() method

                            -

                            - Expects an td argument and returns a ConsumedThing object that represents a client interface to operate with the Thing. The method MUST run the following steps: -

                              -
                            1. - If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps. -
                              2. -
                            2. - Let thing be a new ConsumedThing object. -
                              3. -
                            3. - Let thing.td be the result of running the instantiate a TD steps on td. If that throws, re-throw the error and terminate these steps. -
                              4. -
                            4. - Return thing. -
                              5. -
                            -

                            -

                            - After constructing a ConsumedThing, its Thing Description td needs to be instantiated, i.e. initialized with specific values provided by the underlying platform. - To instantiate a TD, given td, run the following steps: -

                              -
                            1. - Let instance be an object with properties and default values defined in TD Thing. -

                              - As the TD specification owns the structure, validation and serialization of these objects, please refer to that specification on what properties need to be on the instance object. In this specification, instance is considered implementation-internal metadata, exposed for introspection. -

                              -
                              2. -
                            2. - Update the properties of instance also defined in td with the values defined in td. -

                              - When more efficient, implementations MAY reverse the last two steps, i.e. let instance be the result of adding td the missing properties with default values as defined in TD specification. -

                              -
                              3. -
                            3. - Update instance with the WoT Runtime local settings. -
                                -
                              1. - Initialize instance.id to be the final unique identifier of the Thing instance. -
                                2. -
                              2. - Initialize instance.security to the actual security scheme used by the WoT Runtime. -
                                3. -
                              3. - Update instance.forms with local settings specific to the WoT Runtime. Also, update the runtime-specific parts (if any) for the forms array of all elements in instance.properties, instance.actions and instance.events. -
                                4. -
                              -
                              4. -
                            4. - Validate instance according to the TD instance validation. If that fails, throw SyntaxError and terminate these steps. -
                              5. -
                            5. - Return instance. -
                              6. -
                            -

                            -
                            - -
                            - -
                            -

                            The ThingServer API object

                            -

                            - Defines the WoT server API entry point exposed as a singleton and contains the API method for producing a Thing based on Thing Descriptions. -

                            -

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

                            - 
                            -      [SecureContext, Exposed=(Window,Worker)]
-      interface ThingServer {
-        ExposedThing produce(ThingDescription td);
-      };
-
                            - -

                            The produce() method

                            -

                            - Expects a td argument and returns an ExposedThing object that extends ConsumedThing with a server interface, i.e. the ability to define request handlers. The method MUST run the following steps: -

                              -
                            1. - If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps. -
                              2. -
                            2. - Let thing be a new ExposedThing object. -
                              3. -
                            3. - Let thing.td be the result of running the instantiate a TD steps on td. If that throws, re-throw the error and terminate these steps. -

                              - Implementations should use thing.td for setting up the WoT Interactions based on the Thing Description as explained in [[WOT-TD]] and [[WOT-PROTOCOL-BINDINGS]]. This is private to the implementations and out of scope of this specification. -

                              -
                              4. -
                            4. - For each Property definition in thing.td.properties initialize an internal observer list in order to store observe request data needed to notify the observers on value changes. -
                              5. -
                            5. - Return thing. -
                              6. -
                            -

                            -
                            -
                            +

                            The ConsumedThing interface

                            @@ -406,6 +292,7 @@

                            The ConsumedThing interface

                            Represents a client API to operate a Thing. 

                            +      [Constructor(ThingDescription td), SecureContext, Exposed=(Window,Worker)]
       interface ConsumedThing {
         Promise<any> readProperty(DOMString propertyName);
         Promise<object> readAllProperties();
@@ -425,14 +312,93 @@ 
                            The ConsumedThing interface
                            
     
                            
       
                            The td property
                            
       
                            
-        Represents the instantiated Thing Description of this Thing.
+        Represents the Thing Description of the ConsumedThing.
+      
                            
+      
                            
+        Note that [[WOT-TD]] allows using a shortened Thing Description
+        by the means of defaults and requiring clients to expand them with default values specified in
+        [[WOT-TD]] for the properties that are not explicitly defined in a given
+        TD.
+      
                            
+      
                            
+        Therefore, when getting the td property, implementations SHOULD
+        provide the default values for all the sub-properties that have a default value specified in [[!WOT-TD]] in the TD default values table,
+        even if they are not defined in the td object.
+      
                            
+      
                            
+        Implementations MAY optimize this step by creating an expanded
+        ThingDescription object as an internal slot or by adding the
+        missing properties with default values to td when they are first
+        read from td. The resulting td is equivalent with the one
+        provided to the ConsumedThing constructor.
+      
                            
+      
                            
+        To validate a TD given td, run the following steps:
+        
                              
+          
                            1. 
+            If td is not an object, throw "TypeError"
+            and terminate these steps.
+          
                              2. 
+          
                            2. 
+            If any of the mandatory properties defined in [[!WOT-TD]] for
+            Thing
+            that don't have default definitions
+            are missing from td, throw "TypeError" and terminate these steps.
+          
                              3. 
+        
                            
+      
                            
+      
                            
+        To fully validate a TD given td according to
+        [[!WOT-TD]], run the following steps:
+        
                              
+          
                            1. 
+            If running the validate a TD steps on td throws, re-throw and terminate these steps.
+          
                              2. 
+          
                            2. 
+            In addition, if JSON schema validation fails on td, throw "TypeError" and terminate these steps.
+          
                              3. 
+        
                            
+      
                            
+      
                            
+        Since TD validation is defined in [[!WOT-TD]], this API expects
+        the ThingDescription objects be validated before given to the
+        ConsumedThing or ExposedThing constructors. However, implementations SHOULD make basic validation of TD parameters as
+        defined in validate a TD steps.
       
                            
     
                            
 
     
                            
-      
                            The WotListener callback
                            
+      
                            Constructing ConsumedThing
                            
       
                            
-        User provided callback that takes any argument and is used for Property change and Event subscriptions. As subscriptions are WoT interactions, they are not modelled with software events.
+        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:
+        
                              
+          
                            1. 
+            If running validate a TD on td fails, throw
+            "TypeError" and terminate these steps.
+            
                              
+              This represents very basic and fast validation that checks the
+              presence of a very few mandatory properties required by [[WOT-TD]].
+            
                              
+          
                              2. 
+          
                            2. 
+            Let thing be a new ConsumedThing object and
+            let thing.td be td.
+          
                              3. 
+          
                            3. 
+            For each Property definition in thing.td.properties initialize an internal observer list
+            internal slot in order to store observe request data needed to
+            notify the observers on value changes.
+          
                              4. 
+          
                            4. 
+            Return thing.
+          
                              5. 
+        
                            
       
                            
     
                            
 
@@ -575,10 +541,20 @@ 
                            The writeMultipleProperties() method
                            +
                            +

                            The WotListener callback

                            +

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

                            +
                            +

                            The observeProperty() method

                            - Makes a request for Property value change notifications. Takes a string argument propertyName and returns success or failure. The method MUST run the following steps: + Makes a request for Property value change notifications. Takes a string argument propertyName and a WotListener + callback function listener. It returns success or failure. + The method MUST run the following steps:

                            1. Return a Promise promise and execute the next steps in parallel. @@ -586,6 +562,10 @@

                              The observeProperty() method

                            2. If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
                              3. +
                            3. + If listener is not a function, reject promise + with "TypeError" and terminate these steps. +
                            4. Make a request to the underlying platform (via the Protocol Bindings) to observe Property identified by propertyName.
                              5. @@ -595,6 +575,18 @@

                              The observeProperty() method

                            5. Otherwise resolve promise.
                              6. +
                            6. + Whenever the underlying platform receives a notification for this subscription with new Property value value, run + the following sub-steps: +
                                +
                              • + If running the validate Property value steps on value fails, terminate these steps. +
                                • +
                              • + Invoke listener with value as parameter. +
                                • +
                              +

                            @@ -653,7 +645,9 @@

                            The invokeAction() method

                            The subscribeEvent() method

                            - Makes a request for subscribing to Event notifications. Takes a string argument eventName and returns success or failure. The method MUST run the following steps: + Makes a request for subscribing to Event notifications. Takes a string argument eventName and a WotListener + callback function listener. It returns success or failure. + The method MUST run the following steps:

                            1. Return a Promise promise and execute the next steps in parallel. @@ -661,6 +655,10 @@

                              The subscribeEvent() method

                            2. If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
                              3. +
                            3. + If listener is not a function, reject promise + with "TypeError" and terminate these steps. +
                            4. Make a request to the underlying platform (via the Protocol Bindings) to subscribe to an Event identified by eventName.
                              5. @@ -670,6 +668,11 @@

                              The subscribeEvent() method

                            5. Otherwise resolve promise.
                              6. +
                            6. + Whenever the underlying platform receives a notification for this Event subscription, implementations SHOULD invoke + listener, giving the data provided with the Event + as parameter. +

                            @@ -707,7 +710,7 @@

                            ConsumedThing Examples

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

                            The ExposedThing interface

                            callback ActionHandler = Promise<any>(any parameters); +
                            +

                            Constructing ExposedThing

                            +

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

                            +

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

                            +

                            + To construct an ExposedThing with the ThingDescription + td, run the following steps: +

                              +
                            1. + If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps. +
                              2. +
                            2. + If td is not a an object, throw TypeError + and terminate these steps. +
                              3. +
                            3. + Let thing be a new ExposedThing object. +
                              4. +
                            4. + Let thing.td be td. +
                              5. +
                            5. + Return thing. +
                              6. +
                            +

                            +
                            +

                            The PropertyReadHandler callback

                            @@ -929,13 +969,24 @@

                            The ActionHandler callback

                            If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
                          6. + If running the fully validate a TD on this.td fails, + reject promise with "TypeError" and terminate + these steps. +
                            7. +
                          7. + For each Property definition in this.instance.properties initialize an internal observer list internal slot + in order to store observe request data needed to notify the observers on value changes. +
                            8. +
                          8. + Set up the WoT Interactions based on introspecting td + as explained in [[!WOT-TD]]. 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.
                          9. 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 terminate these steps.
                          10. - Otherwise resolve promise with td and terminate these steps. + Otherwise resolve promise and terminate these steps.

                          @@ -958,7 +1009,7 @@

                          The ActionHandler callback

                          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 terminate these steps.
                        6. - Otherwise resolve promise with td and terminate these steps. + Otherwise resolve promise and terminate these steps.

                        @@ -995,7 +1046,7 @@

                        ExposedThing Examples

                        onchange: temperatureValueDefinition } }; - let thing1 = ThingServer.produce(tdFragment); + let thing1 = new ExposedThing(tdFragment); // TODO: add service handlers await thing1.expose(); // define Thing business logic @@ -1053,7 +1104,7 @@

                        ExposedThing Examples

                        }; instance.events["onstatuschange"] = statusValueDefinition; instance.forms = [...]; // update - var thing2 = ThingServer.produce(instance); + var thing2 = new ExposedThing(instance); // TODO: add service handlers await thing2.expose(); }); @@ -1287,7 +1338,7 @@

                        Discovery Examples

                        do { let td = await discovery.next(); console.log("Found Thing Description for " + td.title); - let thing = ThinClient.consume(td); + let thing = new ConsumedThing(td); console.log("Thing name: " + thing.td.title); } while (!discovery.done); @@ -1308,7 +1359,7 @@

                        Discovery Examples

                        do { let td = await discovery.next(); console.log("Found Thing Description for " + td.title); - let thing = ThingClient.consume(td); + let thing = new ConsumedThing(td); console.log("Thing name: " + thing.td.title); } while (!discovery.done); if (discovery.error) { @@ -1327,7 +1378,7 @@

                        Discovery Examples

                        10000); do { let td = await discovery.next(); - let thing = ThingClient.consume(td); + let thing = new ConsumedThing(td); console.log("Thing name: " + thing.td.title); } while (!discovery.done); From 1bb38d942199564f2204b4d81ec5d2d445bc4373 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Tue, 18 Jun 2019 17:09:52 +0300 Subject: [PATCH 327/464] Add UA conformance classes. Add WoT object and keep constructors. Editorial fixes Signed-off-by: Zoltan Kis --- index.html | 636 +++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 441 insertions(+), 195 deletions(-) diff --git a/index.html b/index.html index 9fb18260..4d36f4e2 100644 --- a/index.html +++ b/index.html @@ -115,13 +115,13 @@

                        - The key Web of Things (WoT) concepts are described in the WoT Architecture document. The Web of Things is made of entities (Things) that can describe their capabilities in a machine-interpretable format, the Thing Description (TD) and expose these capabilities through the WoT Interface, 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 WoT Architecture document. 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).

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

                        - This specification describes a programming interface representing the WoT Interface that allows scripts to discover and operate Things and to expose locally defined Things characterized by WoT Interactions specified by a script. + This specification describes a programming interface 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 specification deliberately follows the WoT Thing Description specification closely. It is possible to implement simpler APIs on top of this API, or implementing directly the WoT network facing interface (i.e. the WoT Interface). @@ -143,7 +143,8 @@

                        Introduction

                        - WoT provides layered interoperability based on how Things are used: "consumed" and "exposed". + WoT provides layered interoperability based on how Things are used: + "consumed" and "exposed", as defined in [[WOT-ARCHITECTURE]].

                        By consuming a TD, a client Thing creates a local runtime resource model that allows accessing the Properties, Actions and Events exposed by the server Thing on a remote device. @@ -257,6 +258,56 @@

                        +
                        +

                        + This specification describes the conformance criteria for the following classes of user agent (UA). +

                        +

                        + Due to requirements of small embedded implementations, splitting WoT client and server interfaces was needed. Then, discovery is a distributed application, but typical scenarios have been covered by a generic discovery API in this specification. This resulted in using 3 conformance classes for a UA that implements this API, one for client, one for server, and one for discovery. An application that uses this API can introspect for the presence of the consume(), produce() and discover() methods on the WoT API object in order to determine which conformance class the UA implements. +

                        +
                        +
                        + WoT Client User Agent +
                        +
                        +

                        + Implementations of this conformance class MUST implement the ConsumedThing interface and the consume() method on the WoT API object. +

                        +
                        +
                        + WoT Server User Agent +
                        +
                        +

                        + Implementations of this conformance class MUST implement ExposedThing interface and the produce() method on the WoT API object. +

                        +
                        +
                        + WoT Discovery User Agent +
                        +
                        +

                        + Implementations of this conformance class MUST implement the ThingDiscovery interface and the discover() method on the WoT API object. +

                        +
                        +
                        +

                        + These conformance classes MAY be implemented in a single UA. +

                        +

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

                        +

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

                        +

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

                        +

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

                        +
                        +

                        The ThingDescription type

                        @@ -264,13 +315,13 @@ 
                        The ThingDescription type

                        - Represents a Thing Description (TD). It is expected to be + Represents a Thing Description (TD) as defined in [[!WOT-TD]]. It is expected to be a parsed JSON object that is validated using JSON schema validation.

                        Fetching a Thing Description

                        - The fetch(url) method has been part of this API in earlier versions. However, now fetching a TD given a URL should be done with an external method, such as the Fetch API or a HTTP client library, which offer already standardized options on specifying fetch details. + Fetching a TD given a URL should be done with an external method, such as the Fetch API or a HTTP client library, which offer already standardized options on specifying fetch details. 

                                 try {
@@ -284,36 +335,8 @@ 
                        The ThingDescription type
                        
         }
                        -
                        - -
                        -

                        The ConsumedThing interface

                        -

                        - Represents a client API to operate a Thing. -

                        - 
                        -      [Constructor(ThingDescription td), SecureContext, Exposed=(Window,Worker)]
-      interface ConsumedThing {
-        Promise<any> readProperty(DOMString propertyName);
-        Promise<object> readAllProperties();
-        Promise<object> readMultipleProperties(sequence<DOMString> propertyNames);
-        Promise<void> writeProperty(DOMString propertyName, any value);
-        Promise<void> writeMultipleProperties(object valueMap);
-        Promise<any> invokeAction(DOMString actionName, optional any params);
-        Promise<void> observeProperty(DOMString name, WotListener listener);
-        Promise<void> unobserveProperty(DOMString name);
-        Promise<void> subscribeEvent(DOMString name, WotListener listener);
-        Promise<void> unsubscribeEvent(DOMString name);
-        readonly attribute ThingDescription td;
-      };
-      callback WotListener = void(any data);
-
                        -
                        -

                        The td property

                        -

                        - Represents the Thing Description of the ConsumedThing. -

                        +

                        Expanding a Thing Description

                        Note that [[WOT-TD]] allows using a shortened Thing Description by the means of defaults and requiring clients to expand them with default values specified in @@ -321,20 +344,22 @@

                        The td property

                        TD.

                        - Therefore, when getting the td property, implementations SHOULD - provide the default values for all the sub-properties that have a default value specified in [[!WOT-TD]] in the TD default values table, - even if they are not defined in the td object. + To expand a TD given td, run the following steps: +

                          +
                        1. + For each item in the TD default values table from [[!WOT-TD]], if the term is not defined in td, add the term definition with the default value specified in [[!WOT-TD]]. +
                          2. +

                        +
                        + +

                        Validating a Thing Description

                        - Implementations MAY optimize this step by creating an expanded - ThingDescription object as an internal slot or by adding the - missing properties with default values to td when they are first - read from td. The resulting td is equivalent with the one - provided to the ConsumedThing constructor. + The [[!WOT-TD]] specification defines how a TD should be validated. + Therefore, this API expects the ThingDescription objects be validated before used as parameters. This specification defines a basic TD validation as follows.

                        To validate a TD given td, run the following steps: -

                        1. If td is not an object, throw "TypeError" and terminate these steps. @@ -345,27 +370,146 @@

                          The td property

                          that don't have default definitions are missing from td, throw "TypeError" and terminate these steps.
                          2. -
                        -

                        -

                        - To fully validate a TD given td according to - [[!WOT-TD]], run the following steps: -

                        1. - If running the validate a TD steps on td throws, re-throw and terminate these steps. -
                          2. -
                        2. - In addition, if JSON schema validation fails on td, throw "TypeError" and terminate these steps. + If JSON schema validation fails on td, throw "TypeError" and terminate these steps.

                        -

                        - Since TD validation is defined in [[!WOT-TD]], this API expects - the ThingDescription objects be validated before given to the - ConsumedThing or ExposedThing constructors. However, implementations SHOULD make basic validation of TD parameters as - defined in validate a TD steps. -

                        +
                        +
                        + +
                        +

                        The WoT API object

                        +

                        + Defines the API entry point exposed as a singleton and contains the API methods. +

                        +

                        The WOT interface

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

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

                        +
                        +

                        The consume() method

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

                        + Belongs to the WoT Client user agent 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: +

                          +
                        1. + Return a Promise promise and execute the next steps in parallel. +
                          2. +
                        2. + If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps. +
                          3. +
                        3. + Run the validate a TD steps on td. If that throws, reject promise with the error and terminate these steps. +
                          4. +
                        4. + Let thing be a new ConsumedThing object constructed from td. +
                          5. +
                        5. + Use td to initialize WoT Interactions based on it as specified in [[WOT-TD]] and [[WOT-PROTOCOL-BINDINGS]]. The details are private to the implementations and out of scope of this specification. +
                          6. +
                        6. + Resolve promise with thing. +
                          7. +
                        +

                        +
                        + +

                        The produce() method

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

                        + Belongs to the WoT Server user agent conformance class. Expects a td 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 method MUST run the following steps: +

                          +
                        1. + Return a Promise promise and execute the next steps in parallel. +
                          2. +
                        2. + If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps. +
                          3. +
                        3. + Let thing be a new ExposedThing object constructed with td. +
                          4. +
                        4. + Run the validate a TD steps on td. If that throws, reject promise with the error and terminate these steps. +
                          5. +
                        5. + Let thing.td be td. +
                          6. +
                        6. + Resolve promise with thing. +
                          7. +
                        +

                        +
                        + +

                        The discover() method

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

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

                          +
                        1. + If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps. +
                          2. +
                        2. + Construct a ThingDiscovery object discovery with filter. +
                          3. +
                        3. + Invoke the discovery.start() method. +
                          4. +
                        4. + Return discovery. +
                          5. +
                        +

                        +

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

                        +
                        + +
                        + +
                        +

                        The ConsumedThing interface

                        +

                        + Represents a client API to operate a Thing. Belongs to the + WoT Client user agent conformance class. +

                        + 
                        +      [Constructor(ThingDescription td), SecureContext, Exposed=(Window,Worker)]
+      interface ConsumedThing {
+        Promise<any> readProperty(DOMString propertyName);
+        Promise<object> readAllProperties();
+        Promise<object> readMultipleProperties(sequence<DOMString> propertyNames);
+        Promise<void> writeProperty(DOMString propertyName, any value);
+        Promise<void> writeMultipleProperties(object valueMap);
+        Promise<any> invokeAction(DOMString actionName, optional any params);
+        Promise<void> observeProperty(DOMString name, WotListener listener);
+        Promise<void> unobserveProperty(DOMString name);
+        Promise<void> subscribeEvent(DOMString name, WotListener listener);
+        Promise<void> unsubscribeEvent(DOMString name);
+        readonly attribute ThingDescription td;
+      };
+      callback WotListener = void(any data);
+

                        Constructing ConsumedThing

                        @@ -379,21 +523,15 @@

                        Constructing ConsumedThing

                        td, run the following steps:
                        1. - If running validate a TD on td fails, throw - "TypeError" and terminate these steps. -

                          - This represents very basic and fast validation that checks the - presence of a very few mandatory properties required by [[WOT-TD]]. -

                          + If td is not an object, throw "TypeError" + and terminate these steps.
                        2. - Let thing be a new ConsumedThing object and - let thing.td be td. + Run the expand a TD steps on td.
                        3. - For each Property definition in thing.td.properties initialize an internal observer list - internal slot in order to store observe request data needed to - notify the observers on value changes. + Let thing be a new ConsumedThing object and + let thing.td be td.
                        4. Return thing. @@ -402,6 +540,14 @@

                          Constructing ConsumedThing

                        +
                        +

                        The td property

                        +

                        + Represents the Thing Description of the ConsumedThing. + Applications may consult the Thing metadata stored in td in order to introspect its capabilities before interacting with it. +

                        +
                        +

                        The readProperty() method

                        @@ -457,7 +603,7 @@

                        The readMultipleProperties() method

                        Let result be an object and for each string name in propertyNames add a property with key name and the value null.
                      4. - Make a request to the underlying platform (via the Protocol Bindings) to retrieve the Property values given by propertyNames. If the Protocol Bindings support this using one request, use that, otherwise run the readProperty() steps on each property name in propertyNames and options and store the resulting values in result for each name in propertyNames. + Make a request to the underlying platform (via the Protocol Bindings) to retrieve the Property values given by propertyNames. If the Protocol Bindings support this using one request, use that, otherwise run the readProperty() steps on each property name in propertyNames and store the resulting values in result for each name in propertyNames.
                      5. If the above step fails at any point, reject promise with SyntaxError and terminate these steps. @@ -478,7 +624,7 @@

                        The readAllProperties() method

                        Let propertyNames be a sequence created from all the Property names of this Thing as found in this.td.properties.
                      6. - Let result be the result of running the readMultipleProperties() steps on propertyNames and options. If that fails, reject promise with that error and terminate these steps. + Let result be the result of running the readMultipleProperties() steps on propertyNames. If that fails, reject promise with that error and terminate these steps.
                      7. Resolve promise with result. @@ -704,7 +850,7 @@

                        The unsubscribeEvent() method

                        ConsumedThing Examples

                        - This 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. + The next example illustrates how to fetch a TD by URL, create a ConsumedThing, read metadata (title), read property value, subscribe to property change, subscribe to a WoT event, unsubscribe. 

                                 try {
@@ -969,12 +1115,15 @@ 
                        The ActionHandler callback
                        
             If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
                      8. - If running the fully validate a TD on this.td fails, + Run the expand a TD steps on this.td. +
                        9. +
                      9. + Run the validate a TD on this.td. If that fails, reject promise with "TypeError" and terminate these steps.
                      10. - For each Property definition in this.instance.properties initialize an internal observer list internal slot + For each Property definition in this.instance.properties initialize an internal observer list internal slot in order to store observe request data needed to notify the observers on value changes.
                      11. @@ -1018,9 +1167,8 @@

                        The ActionHandler callback

                        ExposedThing Examples

                        - Below some ExposedThing interface examples are given. + The next example illustrates how to create an ExposedThing based on a partial TD object constructed beforehands.

                        - 
                                 try {
           let temperaturePropertyDefinition = {
@@ -1046,7 +1194,7 @@ 
                        ExposedThing Examples
                        
               onchange: temperatureValueDefinition
             }
           };
-          let thing1 = new ExposedThing(tdFragment);
+          let thing1 = await WOT.produce(tdFragment);
           // TODO: add service handlers
           await thing1.expose();
           // define Thing business logic
@@ -1062,9 +1210,12 @@ 
                        ExposedThing Examples
                        
         }
                        +

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

                                 try {
-          // create a deep copy of thing1 instance
+          // create a deep copy of thing1's TD
           let instance = JSON.parse(JSON.stringify(thing1.td));
           const statusValueDefinition = {
             type: "object",
@@ -1136,7 +1287,7 @@ 
                        The ThingDiscovery interface
                        
       };

                        - The discovery results internal slot is an internal queue for temporarily storing the found ThingDescription objects until they are consumed by the application using the next() method. + The discovery results internal slot is an internal queue for temporarily storing the found ThingDescription objects until they are consumed by the application using the next() method. Implementations MAY optimize the size of this queue based on e.g. the available resources and the frequency of invoking the next() method.

                        The filter property represents the discovery filter of type ThingFilter specified for the discovery. @@ -1150,9 +1301,86 @@

                        The ThingDiscovery interface

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

                        -

                        - When ThingDiscovery is created, active and done are false, error is null. The start() sets active to true. The stop() method sets active to false, but done may be still false if there are ThingDescription objects in the discovery results not yet consumed with next(). During successive calls of next(), active may be true or false, but done is set to false by next() only when both active is false and discovery results is empty. -

                        + +

                        Constructing ThingDiscovery

                        +

                        + To create ThingDiscovery with the ThingFilter + filter, run the following steps: +

                          +
                        1. + If filter is not an object or null, throw "TypeError" + and terminate these steps. +
                          2. +
                        2. + Let discovery be a new ThingDiscovery object. +
                          3. +
                        3. + Set the filter property to filter. +
                          4. +
                        4. + Set active and done to false. Set error to null. +
                          5. +
                        5. + Return discovery. +
                          6. +
                        +

                        +

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

                        +

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

                        +
                        + +
                        +

                        The DiscoveryMethod enumeration

                        + 
                        +        typedef DOMString DiscoveryMethod;
+
                        +

                        + Represents the discovery type to be used: +

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

                        The ThingFilter dictionary

                        +

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

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

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

                        +

                        + The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, for instance the URL of a Thing Directory (if method is "directory") or that of a Thing (otherwise). +

                        +

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

                        +

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

                        +

                        The start() method

                        @@ -1279,55 +1507,6 @@

                        The stop() method

                        -
                        -

                        The DiscoveryMethod enumeration

                        - 
                        -        typedef DOMString DiscoveryMethod;
-
                        -

                        - Represents the discovery type to be used: -

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

                        The ThingFilter dictionary

                        -

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

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

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

                        -

                        - The url property represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, for instance the URL of a Thing Directory (if method is "directory") or that of a Thing (otherwise). -

                        -

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

                        -

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

                        -
                        -

                        Discovery Examples

                        @@ -1531,7 +1710,7 @@

                        Stale TD Security Risk

                        Terminology and conventions

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

                        JSON-LD is defined in [[!JSON-LD]] as a JSON document that is augmented with support for Linked Data. @@ -1567,20 +1746,7 @@

                        Stale TD Security Risk

                        are defined in [[!ENCODING]].

                        - ASCII decode, - ASCII lowercase, string, - byte, - byte sequence, - set, - exists, - list, - for each, - continue, - is empty, - is not empty, - append, - contains, parse JSON from bytes and serialize JSON to bytes, are defined in [[!INFRA]]. @@ -1622,44 +1788,14 @@

                        Stale TD Security Risk

                        top-level browsing context, global object, current settings object, - Document, - document base URL, - Window, - WindowProxy, - origin, - serialized origin, - executing algorithms in parallel, - queue a task, - task source, - iframe, - relevant settings object, - active document, - environment settings object, - EventHandler, + executing algorithms in parallel are defined in [[!HTML5]] and are used in the context of browser implementations.

                        -

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

                        The term secure context is defined in [[!WEBAPPSEC]].

                        -

                        - fire an event, - AbortSignal, - aborted flag, and - add the following abort steps - are defined in [[!DOM]]. -

                        IANA media types (formerly known as MIME types) are defined in RFC2046. @@ -1669,25 +1805,135 @@

                        Stale TD Security Risk

                        -
                        -

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

                        -

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

                        -

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

                        +
                        +

                        API design rationale

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

                        -

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

                        -

                        - This document serves a general description of the WoT Scripting API. Language and runtime specific issues are discussed in separate extensions of this document. + API rationale usually belongs to a separate document, but in the WoT case + the complexity of the context justifies including basic rationale here.

                        +

                        Approaches to WoT application development

                        +

                        + The WoT Interest Group and Working Group have explored different + approaches to application development for WoT that have been all + implemented and tested. +

                        +

                        No Scripting API

                        +

                        + It is possible to develop WoT applications that only use the + WoT network interface, typically exposed by a WoT gateway that + presents a REST-ful API towards clients and implements IoT protocol + plugins that communicate with supported IoT deployments. One such + implementation is the + Mozilla WebThings platform. +

                        +
                        +

                        Simple Scripting API

                        +

                        + WoT Things show good synergy with software objects, so a + Thing can be represented as a software object, with Properties represented as object properties, Actions as methods, and + Events as events. In addition, metadata is stored in special + properties. Consuming and exposing is done with factory methods that + produce a software object that directly represents a remote Thing + and its interactions. One such implementation is the + Arena Web Hub + project. +

                        +

                        + In the next example, a Thing that represents interactions with + a lock would look like the following: the status property + and the open() method are directly exposed on the object. +

                        + 
                        +          let lock = await WoT.consume(‘https://td.my.com/lock-00123’);
+          console.log(lock.status);
+          lock.open('withThisKey');
+
                        +
                        +

                        This API, aligned with [[WOT-TD]]

                        +

                        + Since the direct mapping of Things to software objects have had + some challenges, this specification takes another approach that + exposes software objects to represent the Thing metadata as + data property and the WoT interactions as methods. One implementation + is node-wot + in the the Eclipse ThingWeb project, + which is the current reference implementation of the API specified in + this document. +

                        +

                        + The same example now would look like the following: the + status property and the open() method are + represented indirectly. +

                        + 
                        +          let res = await fetch(‘https://td.my.com/lock-00123’);
+          let td = await res.json();
+          let lock = new ConsumedThing(td);
+          console.log(lock.readProperty(‘status’));
+          lock.invokeAction(‘open’, 'withThisKey');
+
                        +
                        +

                        + In conclusion, the WoT WG decided to explore the third option that + closely follows the [[WOT-TD]] specification. Based on this, a simple + API can also be implemented. + Since Scripting is an optional module in WoT, this leaves room for + applications that only use the WoT network interface. + Therefore all three approaches above are supported by [[WOT-TD]]. +

                        +

                        + Moreover, the WoT network interface can be implemented in many languages + and runtimes. Consider this API an example for what needs to be taken + into consideration when designing a Scripting API for WoT. +

                        +
                        +

                        Fetching and validating a TD

                        +

                        + The fetch(url) method has been part of this API in earlier versions. However, now fetching a TD given a URL should be done with an external method, such as the Fetch API or a HTTP client library, which offer already standardized options on specifying fetch details. The reason is that while simple fetch operations (covering most use cases) could be done in this API, when various fetch options were needed, there was no point in duplicating existing work to re-expose those options in this API. +

                        +

                        + Since fetching a TD has been scoped out, and TD validation + is defined externally in [[WOT-TD]], that is scoped out, too. This specification expects a TD as + parsed JSON object that has been validated according to the [[WOT-TD]] specification. +

                        +
                        +

                        Factory vs constructors

                        +

                        + The factory methods for consuming and exposing Things are asynchronous and fully validate the input TD. In addition, one can also construct ConsumedThing and ExposedThing by providing a parsed and validated TD. Platform initialization is then done when needed during the WoT interactions. So applications that prefer validating a TD themselves, may use the constructors, whereas applications that leave validation to implementations and prefer interactions initialized up front SHOULD use the factory methods on the WoT API object. +

                        +
                        +

                        Observers

                        +

                        + Earlier drafts used the + Observer + construct, but since it has not become standard, a new design was needed + that was light enough for embedded implementations. Therefore observing + Property changes and handling WoT Events is done with + callback registrations. +

                        +
                        +

                        Using Events

                        +

                        + This API ended up not using software events at all, for the following + reasons: +

                          +
                        • + Subscription to WoT Events may be different from handling software events (subscription might need parameters, might involve security tokens etc). +
                          • +
                        • + Most implementations are for Node.js and browser implementations will likely be libraries (because possible dependency management issues in native implementations), using Events has been challenging. +
                          • +
                        • + Observing Property changes and handling WoT Events is done with the solution above. +
                          • +
                        +

                        +
                        +

                        Polymorphic functions

                        +

                        + The reason to use function names like readProperty(), readMultipleProperties() etc. instead of a generic polymorphic read() function is that the current names map exactly to the "op" vocabulary from the Form definition in [[WOT-TD]]. +

                        +

                        Changes

                        @@ -1753,7 +1999,7 @@

                        Stale TD Security Risk

                        -

                        Acknowledgements

                        +

                        Acknowledgements

                        Special thanks to former editor Johannes Hund (until August 2017, when at Siemens AG) and Kazuaki Nimura (until December 2018) for developing this specification. Also, the editors would like to thank Dave Raggett, Matthias Kovatsch, Michael Koster, Elena Reshetova, Michael McCool as well as the other WoT WG members for their comments, contributions and guidance.

                        From ebfaf321b1b2b09046e5dfa94ea47795116e3c25 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 19 Jun 2019 09:58:55 +0300 Subject: [PATCH 328/464] Fix #172: update security references Signed-off-by: Zoltan Kis --- index.html | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/index.html b/index.html index 4d36f4e2..bd2881eb 100644 --- a/index.html +++ b/index.html @@ -77,15 +77,15 @@ publisher: "W3C", date: "6 February 2017" }, - "WOT-SECURITY-CONSIDERATIONS" : { + "WOT-SECURITY-GUIDELINES" : { href: "https://w3c.github.io/wot-security/", - title: "Web of Things Security and Privacy Considerations", + title: "Web of Things Security and Privacy Guidelines", publisher: "W3C", date: "28 August 2017" }, "WOT-SECURITY-BEST-PRACTICES" : { href: "https://github.com/w3c/wot-security/blob/master/wot-security-best-practices.md", - title: "Web of Things Security and Privacy Best Practices (WIP)", + title: "Web of Things Security and Privacy Best Practices", publisher: "W3C", date: "WIP" }, @@ -1567,7 +1567,7 @@

                        Discovery Examples

                        Security and Privacy

                        A detailed discussion of security and privacy considerations for the Web of Things, including a threat model that can be adapted to various circumstances, is - presented in the informative document [[!WOT-SECURITY-CONSIDERATIONS]]. + presented in the informative document [[!WOT-SECURITY-GUIDELINES]]. This section discusses only security and privacy risks and possible mitigations directly relevant to the scripts and WoT Scripting API.

                        @@ -1644,7 +1644,7 @@

                        Provisioning and Update Security Risk

                        Post-manufacturing provisioning or update of scripts, WoT Scripting Runtime or any related data should be done in a secure fashion. A set of recommendations for secure update and post-manufacturing - provisioning can be found in [[!WOT-SECURITY-CONSIDERATIONS]]. + provisioning can be found in [[!WOT-SECURITY-GUIDELINES]].
                        From d24c67723e5267ef91576cb2f1f057f27e7fc7cf Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 19 Jun 2019 19:10:29 +0300 Subject: [PATCH 329/464] Align conformance class names with Architecture spec Signed-off-by: Zoltan Kis --- index.html | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/index.html b/index.html index bd2881eb..583c1496 100644 --- a/index.html +++ b/index.html @@ -267,7 +267,7 @@

                        - WoT Client User Agent + WoT Consumer UA

                        @@ -275,7 +275,7 @@

                        - WoT Server User Agent + WoT Producer UA

                        @@ -283,7 +283,7 @@

                        - WoT Discovery User Agent + WoT Discovery UA

                        @@ -402,7 +402,7 @@

                        The WoT API object

                        };

                        - Belongs to the WoT Client user agent 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: + 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:

                        1. Return a Promise promise and execute the next steps in parallel. @@ -433,7 +433,7 @@

                          The WoT API object

                          };

                          - Belongs to the WoT Server user agent conformance class. Expects a td 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 method MUST run the following steps: + Belongs to the WoT Producer conformance class. Expects a td 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 method MUST run the following steps:

                          1. Return a Promise promise and execute the next steps in parallel. @@ -464,7 +464,7 @@

                            The WoT API object

                            };

                            - Belongs to the WoT Discovery user agent conformance class. Starts the discovery process that will provide ThingDescription objects for Thing Descriptions that match an optional filter argument. The method MUST run the following steps: + 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. The method MUST run the following steps:

                            1. If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps. @@ -491,7 +491,7 @@

                              The WoT API object

                              The ConsumedThing interface

                              Represents a client API to operate a Thing. Belongs to the - WoT Client user agent conformance class. + WoT Consumer conformance class. 

                                     [Constructor(ThingDescription td), SecureContext, Exposed=(Window,Worker)]

From 8a6050692e8eada1b936e86330cd5d1c84580312 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Wed, 26 Jun 2019 14:48:38 +0300
Subject: [PATCH 330/464] Editorial sweep

Signed-off-by: Zoltan Kis 
---
 index.html | 31 ++++++++++++++++---------------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/index.html b/index.html
index 583c1496..803c5efc 100644
--- a/index.html
+++ b/index.html
@@ -417,7 +417,8 @@ 
                              The WoT API object
                              
           Let thing be a new ConsumedThing object constructed from td.
                            2. - Use td to initialize WoT Interactions based on it as specified in [[WOT-TD]] and [[WOT-PROTOCOL-BINDINGS]]. The details are private to the implementations and out of scope of this specification. + 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. + The details are private to the implementations and out of scope of this specification.
                            3. Resolve promise with thing. @@ -933,7 +934,7 @@

                              Constructing ExposedThing

                              Let thing be a new ExposedThing object.
                            4. - Let thing.td be td. + Let thing.td be td. There is no validation or any transformation done on td at this stage.
                            5. Return thing. @@ -1128,8 +1129,8 @@

                              The ActionHandler callback

                            6. Set up the WoT Interactions based on introspecting td - as explained in [[!WOT-TD]]. - 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. + 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. The details are private to the implementations and out of scope of this specification.
                            7. 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 terminate these steps. @@ -1707,7 +1708,6 @@

                              Stale TD Security Risk

                        -

                        Terminology and conventions

                        The generic WoT terminology is defined in [[!WOT-ARCHITECTURE]]: Thing, Thing Description (in short TD), Web of Things (in short WoT), WoT Interface (same as WoT network interface), Protocol Bindings, WoT Runtime, Consuming a Thing Description, Thing Directory, WoT Interactions, Property, Action, Event etc. @@ -1805,7 +1805,7 @@

                        Stale TD Security Risk

                        -
                        +

                        API design rationale

                        API rationale usually belongs to a separate document, but in the WoT case @@ -1967,9 +1967,17 @@

                        API design rationale

                      12. Add missing algorithms and rework most existing ones.
                        13. +
                      13. + Allow constructors for ConsumedThing and ExposedThing. +
                        14. +
                      14. + Add API rationale as an appendix to this document. +
                        15. +

                        +

                        For a complete list of changes, see the github change log. You can also view the recently closed issues.

                      @@ -1980,18 +1988,11 @@

                      API design rationale

                      • - The API for adding and removing Property, Action and Event definitions on ExposedThing. -
                        • -
                      • - Provide an API that is compatible with the Web Platform (browser implementations) and is efficient to implement in constrained runtimes. -
                        • -
                      • - Security related metadata (https://github.com/w3c/wot-scripting-api/issues/91). + Script management and runtime related issues (https://github.com/w3c/wot-scripting-api/issues/)
                      • - Providing Protocol Binding for ExposedThing (https://github.com/w3c/wot-scripting-api/issues/45). + An explicit API for adding and removing Property, Action and Event definitions on ExposedThing (it was present in earlier versions, but removed for complexity and a simpler way to do it.
                        • -
                      • Script management and runtime related issues (https://github.com/w3c/wot-scripting-api/issues/)
                      • From 2bb9a0da219f27e5a1b076d6e43968a88444d053 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Tue, 9 Jul 2019 10:22:25 +0200 Subject: [PATCH 331/464] chore: update typescript definitions version for next node-wot release --- typescript/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/typescript/package.json b/typescript/package.json index 907cd470..c008105d 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.6.2-SNAPSHOT.2", + "version": "0.6.2", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From 1f49ad350f19118bc21e9d0443dbd052290ecb5c Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 10 Jul 2019 10:04:06 +0200 Subject: [PATCH 332/464] fix: align with TD "Versioning" --> "VersionInfo" --- typescript/index.d.ts | 4 ++-- typescript/package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index 15b4a5f4..f32f38e1 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -85,7 +85,7 @@ export declare enum DiscoveryMethod { export declare type ThingDescription = string; /** Carries version information about the TD instance. If required, additional version information such as firmware and hardware version (term definitions outside of the TD namespace) can be extended here. */ -export interface Versioning { +export interface VersionInfo { instance?: string; } @@ -110,7 +110,7 @@ export interface ThingFragment { /** Provides information when the TD instance was created */ created?: string; /** Provides version information */ - version?: Versioning; + version?: VersionInfo; /** Set of named security configurations (definitions only). Not actually applied unless names are used in a security section */ securityDefinitions?: { [key: string]: Security } diff --git a/typescript/package.json b/typescript/package.json index 6285a640..39230ccc 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.7.0-NEXT-SNAPSHOT.6", + "version": "0.7.0-NEXT-SNAPSHOT.7", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From 86f01e1b8e7240fec4f27d171e37b9def84e2cb4 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 10 Jul 2019 10:44:38 +0200 Subject: [PATCH 333/464] fix: align with TD ("name" --> "title") --- typescript/index.d.ts | 8 ++++---- typescript/package.json | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index f32f38e1..c67dc2ba 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -95,8 +95,8 @@ export interface VersionInfo { export interface ThingFragment { /** A hint to gernerate the identifier for the Thing */ id?: string; - /** The name attribute represents the user given name of the Thing */ - name?: string; + /** The title attribute represents the user given name of the Thing */ + title?: string; /** Define the base URI that is valid for all defined local interaction resources */ base?: string; /** A human-readable description of the Thing */ @@ -186,8 +186,8 @@ export interface EventFragment extends InteractionFragment { export interface ThingInstance extends ThingFragment { /** id becomes mandatory for Thing instances */ id: string; - /** name becomes mandatory for Thing instances */ - name: string; + /** title becomes mandatory for Thing instances */ + title: string; /** base becomes available for Thing instances (part of binding metadata) */ base?: string; diff --git a/typescript/package.json b/typescript/package.json index 39230ccc..12f39b08 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.7.0-NEXT-SNAPSHOT.7", + "version": "0.7.0-NEXT-SNAPSHOT.8", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From 184a3c5538bb3e335aba218adc321e2face221b0 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 22 Jul 2019 16:39:59 +0300 Subject: [PATCH 334/464] Correct Web IDL for new errors. Add ed note for iterables. Signed-off-by: Zoltan Kis --- index.html | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 803c5efc..4d111008 100644 --- a/index.html +++ b/index.html @@ -461,7 +461,7 @@

                      The WoT API object

                      The discover() method

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

                      @@ -893,6 +893,7 @@

                      The ExposedThing interface

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

                      +      [SecureContext, Exposed=(Window,Worker)]
       interface ExposedThing: ConsumedThing {
         ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
         ExposedThing setPropertyWriteHandler(DOMString name, PropertyWriteHandler writeHandler);
@@ -1276,7 +1277,7 @@ 
                      The ThingDiscovery interface
                      
       The ThingDiscovery object is constructed given a filter and provides the properties and methods controlling the discovery process.
     
                      
     
                      -      [Constructor(optional ThingFilter filter), SecureContext, Exposed=(Window,Worker)]
+      [Constructor(optional ThingFilter filter = null), SecureContext, Exposed=(Window,Worker)]
       interface ThingDiscovery {
         readonly attribute ThingFilter? filter;
         readonly attribute boolean active;
@@ -1287,6 +1288,9 @@ 
                      The ThingDiscovery interface
                      
         void stop();
       };
     
                      
+    
                      
+      The ThingDiscovery interface has a next() method and a done property, but it is not an Iterable. Look into Issue 177 for rationale.
+    
                      
     
                      
       The discovery results internal slot is an internal queue for temporarily storing the found ThingDescription objects until they are consumed by the application using the next() method. Implementations MAY optimize the size of this queue based on e.g. the available resources and the frequency of invoking the next() method.
     
                      

From 6c5404face87124232395218c33fa84e2b18df0d Mon Sep 17 00:00:00 2001
From: danielpeintner 
Date: Tue, 23 Jul 2019 16:31:17 +0200
Subject: [PATCH 335/464] feat: align with WoT interface

* rename WoTFactory to WoT
* adapt discover
* change consume using Promise
* change produce using Promise
* remove register and unregister from WoT interface
---
 typescript/index.d.ts | 39 +++++++++++++++++++++++----------------
 1 file changed, 23 insertions(+), 16 deletions(-)

diff --git a/typescript/index.d.ts b/typescript/index.d.ts
index c67dc2ba..36fe986d 100644
--- a/typescript/index.d.ts
+++ b/typescript/index.d.ts
@@ -4,18 +4,19 @@ import { Subscription } from 'rxjs/Subscription';
 export as namespace WoT;
 
 /**
- * The WoTFactory (usually instantiated as "WoT" object) is the main API entry point
- * and it is exposed by an implementation of the WoT Runtime.
+ * The WoT interface defines the API entry point exposed as a singleton and contains the API methods.
  */
-export interface WoTFactory {
+export interface WoT {
     /**
      * Starts the discovery process that will provide ConsumedThing 
      * 
      * @param filter represents the constraints for discovering Things as key-value pairs
      */
-    discover(filter?: ThingFilter): Observable;
+    discover(filter?: ThingFilter): ThingDiscovery;
+
 
     /**
+     * TODO REMOVE
      * Accepts an url argument and returns a Promise of a ThingDescription
      * @param url URL of a thing description
      */
@@ -23,25 +24,16 @@ export interface WoTFactory {
 
     /**
      * Accepts a ThingDescription and returns a ConsumedThing
-     * @param url URL of a thing description
+     * @param td thing description
      */
-    consume(td: ThingDescription): ConsumedThing;
+    consume(td: ThingDescription): Promise;
 
     /**
      * Accepts a model argument of type ThingModel and returns an ExposedThing object
      * 
      * @param model can be either a ThingTemplate, or a ThingDescription. 
      */
-    produce(model: ThingModel): ExposedThing;
-
-    /**
-     * Make a request to register td to the given WoT Thing Directory..
-     */
-    register(directory: string, thing: ExposedThing): Promise;
-
-    /**
-     * Makes a request to unregister the thing from the given WoT Thing Directory. */
-    unregister(directory: string, thing: ExposedThing): Promise;
+    produce(model: ThingModel): Promise;
 }
 
 /**
@@ -78,6 +70,21 @@ export declare enum DiscoveryMethod {
     "multicast"
 }
 
+/**
+ * The ThingDiscovery object is constructed given a filter and provides the properties and methods
+ * controlling the discovery process. 
+ */
+export interface ThingDiscovery {
+    filter?: ThingFilter;
+    active: boolean;
+    done: boolean;
+    error?: Error;
+    start(): void;
+    next(): Promise;
+    stop(): void;
+}
+
+
 /**
  * WoT provides a unified representation for data exchange between Things, standardized in the Wot Things Description specification.
  * In this version of the API, Thing Descriptions are represented as opaque strings, denoting a serialized form, for instance JSON or JSON-LD

From 6287bb8e8552a73284193bced3d40abbf5aff8d9 Mon Sep 17 00:00:00 2001
From: danielpeintner 
Date: Tue, 23 Jul 2019 16:31:56 +0200
Subject: [PATCH 336/464] increase snapshot version

---
 typescript/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/typescript/package.json b/typescript/package.json
index 12f39b08..a22cc22f 100644
--- a/typescript/package.json
+++ b/typescript/package.json
@@ -1,6 +1,6 @@
 {
   "name": "wot-typescript-definitions",
-  "version": "0.7.0-NEXT-SNAPSHOT.8",
+  "version": "0.7.0-NEXT-SNAPSHOT.9",
   "description": "TypeScript definitions for the W3C WoT Scripting API",
   "author": "W3C Web of Things Working Group",
   "license": "W3C-20150513",

From e77ca4a45eb4b12cc56864f43eca5ae1c6dfc52d Mon Sep 17 00:00:00 2001
From: danielpeintner 
Date: Thu, 25 Jul 2019 09:35:54 +0200
Subject: [PATCH 337/464] feat: more alignments with current scripting API *
 remove fetch * produce accepting TD string only * remove ThingModel

---
 typescript/index.d.ts   | 17 +++--------------
 typescript/package.json |  2 +-
 2 files changed, 4 insertions(+), 15 deletions(-)

diff --git a/typescript/index.d.ts b/typescript/index.d.ts
index 36fe986d..81ffaf9e 100644
--- a/typescript/index.d.ts
+++ b/typescript/index.d.ts
@@ -14,14 +14,6 @@ export interface WoT {
      */
     discover(filter?: ThingFilter): ThingDiscovery;
 
-
-    /**
-     * TODO REMOVE
-     * Accepts an url argument and returns a Promise of a ThingDescription
-     * @param url URL of a thing description
-     */
-    fetch(url: string): Promise;
-
     /**
      * Accepts a ThingDescription and returns a ConsumedThing
      * @param td thing description
@@ -29,11 +21,11 @@ export interface WoT {
     consume(td: ThingDescription): Promise;
 
     /**
-     * Accepts a model argument of type ThingModel and returns an ExposedThing object
+     * Accepts a ThingDescription and returns a ExposedThing
      * 
-     * @param model can be either a ThingTemplate, or a ThingDescription. 
+     * @param td thing description 
      */
-    produce(model: ThingModel): Promise;
+    produce(td: ThingDescription): Promise;
 }
 
 /**
@@ -141,9 +133,6 @@ export interface ThingFragment {
     [key: string]: any;
 }
 
-/** A Thing model is used for producing a new ExposedThing and can be either a ThingTemplate, or a ThingDescription.  */
-export declare type ThingModel = (ThingDescription | ThingFragment);
-
 /** Base for representing Thing Interaction descriptions */
 export interface InteractionFragment {
     /** A human-readable title for the Interaction, e.g., for UIs */
diff --git a/typescript/package.json b/typescript/package.json
index a22cc22f..bfa8fb96 100644
--- a/typescript/package.json
+++ b/typescript/package.json
@@ -1,6 +1,6 @@
 {
   "name": "wot-typescript-definitions",
-  "version": "0.7.0-NEXT-SNAPSHOT.9",
+  "version": "0.7.0-NEXT-SNAPSHOT.10",
   "description": "TypeScript definitions for the W3C WoT Scripting API",
   "author": "W3C Web of Things Working Group",
   "license": "W3C-20150513",

From 0f5e4e18197085aa8fc76f0e4804205d5ed79581 Mon Sep 17 00:00:00 2001
From: danielpeintner 
Date: Mon, 29 Jul 2019 15:47:54 +0200
Subject: [PATCH 338/464] feat: align with new scripting API

* ThingDescription object vs. string
* simplify/remove all other definitions
---
 typescript/index.d.ts   | 670 ++++++++++++++++++++--------------------
 typescript/package.json |   2 +-
 2 files changed, 338 insertions(+), 334 deletions(-)

diff --git a/typescript/index.d.ts b/typescript/index.d.ts
index 81ffaf9e..6b713b32 100644
--- a/typescript/index.d.ts
+++ b/typescript/index.d.ts
@@ -1,5 +1,5 @@
-import { Observable } from 'rxjs/Observable';
-import { Subscription } from 'rxjs/Subscription';
+// import { Observable } from 'rxjs/Observable';
+// import { Subscription } from 'rxjs/Subscription';
 
 export as namespace WoT;
 
@@ -45,9 +45,9 @@ export interface ThingFilter {
      */
     query?: string;
     /**
-     * The fragment field represents a ThingFragment dictionary used for matching against discovered Things.
+     * The fragment field represents a template object used for matching against discovered Things.
      */
-    fragment?: ThingFragment;
+    fragment?: object;
 }
 
 /** The DiscoveryMethod enumeration represents the discovery type to be used */
@@ -79,120 +79,119 @@ export interface ThingDiscovery {
 
 /**
  * WoT provides a unified representation for data exchange between Things, standardized in the Wot Things Description specification.
- * In this version of the API, Thing Descriptions are represented as opaque strings, denoting a serialized form, for instance JSON or JSON-LD
+ * In this version of the API, Thing Descriptions is expected to be a parsed JSON object.
  */
-export declare type ThingDescription = string;
-
-/** Carries version information about the TD instance. If required, additional version information such as firmware and hardware version (term definitions outside of the TD namespace) can be extended here. */
-export interface VersionInfo {
-    instance?: string;
-}
+export declare type ThingDescription = object;
+
+// /** Carries version information about the TD instance. If required, additional version information such as firmware and hardware version (term definitions outside of the TD namespace) can be extended here. */
+// export interface VersionInfo {
+//     instance?: string;
+// }
+
+// /**
+//  * The ThingFragment dictionary contains fields to initialize a Thing or to match during discovery
+//  */
+// export interface ThingFragment {
+//     /** A hint to gernerate the identifier for the Thing */
+//     id?: string;
+//     /** The title attribute represents the user given name of the Thing */
+//     title?: string;
+//     /** Define the base URI that is valid for all defined local interaction resources */
+//     base?: string;
+//     /** A human-readable description of the Thing */
+//     description?: string;
+//     /** Human-readable descriptions in different languages */
+//     descriptions?: MultiLanguage;
+//     /** Information about the Thing maintainer, e.g., author or contact URI */
+//     support?: string;
+//     /** Provides information when the TD instance was last modified */
+//     lastModified?: string;
+//     /** Provides information when the TD instance was created */
+//     created?: string;
+//     /** Provides version information */
+//     version?: VersionInfo;
+
+//     /** Set of named security configurations (definitions only). Not actually applied unless names are used in a security section */
+//     securityDefinitions?: { [key: string]: Security }
+//     /** Set of security definition names, chosen from those defined in securityDefinitions.  */
+//     security?: Array;
+
+//     /** A map of PropertyFragments with decriptions only */
+//     properties?: { [key: string]: PropertyFragment }
+//     /** A map of ActionFragments with decriptions only */
+//     actions?: { [key: string]: ActionFragment }
+//     /** A map of EventFragments with decriptions only */
+//     events?: { [key: string]: EventFragment }
+//     /** A list of Web links to other Things or metadata */
+//     links?: Array;
+//     /** Indicates one or more endpoints at which operation(s) on this resource are accessible */
+//     forms?: Array;
+//     /**
+//      * A collection of predicate terms that reference values of any type,
+//      * e.g., @context, @type, or other terms from the vocabulary defined in @context.
+//      */
+//     [key: string]: any;
+// }
+
+// /** Base for representing Thing Interaction descriptions */
+// export interface InteractionFragment {
+//     /** A human-readable title for the Interaction, e.g., for UIs */
+//     title?: string;
+//     /** Human-readable titles for the Interaction, in different languages */
+//     titles?: MultiLanguage;
+//     /** A human-readable description of the Interaction */
+//     description?: string;
+//     /** Human-readable descriptions in different languages */
+//     descriptions?: MultiLanguage;
+//     /** Set of authorization scope identifiers */
+//     scopes?: Array;
+//     /** URI template variables */
+//     uriVariables?: { [key: string]: DataSchema };
+//     /** Set of security definition names */
+//     security?: Array;
+
+//     /**
+//      * A collection of predicate terms that reference values of any type,
+//      * e.g., @type, or other terms from the vocabulary defined in @context.
+//      */
+//     [key: string]: any;
+// }
+
+// /** Represents a Thing Property description */
+// export interface PropertyFragment extends InteractionFragment, BaseSchema {
+//     observable?: boolean;
+// }
+// /** Represents a Thing Action description */
+// export interface ActionFragment extends InteractionFragment {
+//     input?: DataSchema;
+//     output?: DataSchema;
+//     safe?: boolean;
+//     idempotent?: boolean;
+// }
+// /** Represents a Thing Event description */
+// export interface EventFragment extends InteractionFragment {
+//     subscription?: DataSchema;
+//     data?: DataSchema;
+//     cancellation?: DataSchema;
+// }
 
 /**
- * The ThingFragment dictionary contains fields to initialize a Thing or to match during discovery
+ * The ConsumedThing interface instance represents a client API to operate a Thing.
  */
-export interface ThingFragment {
-    /** A hint to gernerate the identifier for the Thing */
-    id?: string;
-    /** The title attribute represents the user given name of the Thing */
-    title?: string;
-    /** Define the base URI that is valid for all defined local interaction resources */
-    base?: string;
-    /** A human-readable description of the Thing */
-    description?: string;
-    /** Human-readable descriptions in different languages */
-    descriptions?: MultiLanguage;
-    /** Information about the Thing maintainer, e.g., author or contact URI */
-    support?: string;
-    /** Provides information when the TD instance was last modified */
-    lastModified?: string;
-    /** Provides information when the TD instance was created */
-    created?: string;
-    /** Provides version information */
-    version?: VersionInfo;
-
-    /** Set of named security configurations (definitions only). Not actually applied unless names are used in a security section */
-    securityDefinitions?: { [key: string]: Security }
-    /** Set of security definition names, chosen from those defined in securityDefinitions.  */
-    security?: Array;
-
-    /** A map of PropertyFragments with decriptions only */
-    properties?: { [key: string]: PropertyFragment }
-    /** A map of ActionFragments with decriptions only */
-    actions?: { [key: string]: ActionFragment }
-    /** A map of EventFragments with decriptions only */
-    events?: { [key: string]: EventFragment }
-    /** A list of Web links to other Things or metadata */
-    links?: Array;
-    /** Indicates one or more endpoints at which operation(s) on this resource are accessible */
-    forms?: Array;
-    /**
-     * A collection of predicate terms that reference values of any type,
-     * e.g., @context, @type, or other terms from the vocabulary defined in @context.
-     */
-    [key: string]: any;
-}
-
-/** Base for representing Thing Interaction descriptions */
-export interface InteractionFragment {
-    /** A human-readable title for the Interaction, e.g., for UIs */
-    title?: string;
-    /** Human-readable titles for the Interaction, in different languages */
-    titles?: MultiLanguage;
-    /** A human-readable description of the Interaction */
-    description?: string;
-    /** Human-readable descriptions in different languages */
-    descriptions?: MultiLanguage;
-    /** Set of authorization scope identifiers */
-    scopes?: Array;
-    /** URI template variables */
-    uriVariables?: { [key: string]: DataSchema };
-    /** Set of security definition names */
-    security?: Array;
-
-    /**
-     * A collection of predicate terms that reference values of any type,
-     * e.g., @type, or other terms from the vocabulary defined in @context.
-     */
-    [key: string]: any;
-}
-
-/** Represents a Thing Property description */
-export interface PropertyFragment extends InteractionFragment, BaseSchema {
-    observable?: boolean;
-}
-/** Represents a Thing Action description */
-export interface ActionFragment extends InteractionFragment {
-    input?: DataSchema;
-    output?: DataSchema;
-    safe?: boolean;
-    idempotent?: boolean;
-}
-/** Represents a Thing Event description */
-export interface EventFragment extends InteractionFragment {
-    subscription?: DataSchema;
-    data?: DataSchema;
-    cancellation?: DataSchema;
-}
-
-/**
- * A Thing instance must have an id and a name and its Interactions do have forms and
- * functions to interact (read/write/invoke/subscribe/emit).
- */
-export interface ThingInstance extends ThingFragment {
-    /** id becomes mandatory for Thing instances */
-    id: string;
-    /** title becomes mandatory for Thing instances */
-    title: string;
-    /** base becomes available for Thing instances (part of binding metadata) */
-    base?: string;
-
-    /** A map of ThingProperties (PropertyFragment plus mandatory binding metadata (forms)) */
-    properties: { [key: string]: ThingProperty };
-    /** A map of ThingActions (ActionFragment plus mandatory binding metadata (forms)) */
-    actions: { [key: string]: ThingAction };
-    /** A map of ThingEvents (EventFragment plus mandatory binding metadata (forms)) */
-    events: { [key: string]: ThingEvent };
+export interface ConsumedThing {
+    // /** id becomes mandatory for Thing instances */
+    // id: string;
+    // /** title becomes mandatory for Thing instances */
+    // title: string;
+    // /** base becomes available for Thing instances (part of binding metadata) */
+    // base?: string;
+
+    // /** A map of ThingProperties (PropertyFragment plus mandatory binding metadata (forms)) */
+    // properties: { [key: string]: ThingProperty };
+    // /** A map of ThingActions (ActionFragment plus mandatory binding metadata (forms)) */
+    // actions: { [key: string]: ThingAction };
+    // /** A map of ThingEvents (EventFragment plus mandatory binding metadata (forms)) */
+    // events: { [key: string]: ThingEvent };
 
     // next API
     // XXX add additional 'options' field to allow for uriVariables et cetera
@@ -210,45 +209,48 @@ export interface ThingInstance extends ThingFragment {
     subscribeEvent(name: string, listener: WotListener): Promise;
     unsubscribeEvent(name: string): Promise;
 
-    // XXX add more
-    // e.g., readonly attribute ThingInstance instance;
+    getTD(): ThingDescription;
+    // replace getTD with attribute?
+    // td: ThingDescription;
 }
 
 export declare type WotListener = (data: any) => void;
 
-/**
- * The Interaction interface is an abstract class to represent Thing interactions: Properties, Actions and Events.
- */
-export interface ThingInteraction extends InteractionFragment {
-    forms: Array;
-}
-
-/** Represents an interactable Thing Property */
-export interface ThingProperty extends ThingInteraction, PropertyFragment //, Observable
-{
-    read(options?: any): Promise;
-    write(value: any, options?: any): Promise;
-    subscribe(next?: (value: any) => void, error?: (error: any) => void, complete?: () => void): Subscription;
-}
-/** Represents an interactable Thing Action */
-export interface ThingAction extends ThingInteraction, ActionFragment {
-    invoke(parameter?: any, options?: any): Promise;
-}
-
-/** Represents an interactable Thing Event */
-// FIXME: Events are different on ConsumendThing and ExposedThing
-export interface ThingEvent extends ThingInteraction, EventFragment {
-    subscribe(next?: (data: any) => void, error?: (error: any) => void, complete?: () => void): Subscription;
-    // FIXME emit should be only on ExposedThings' ThingEvents - therefore move emit() to ExposedThing?
-    emit?(data?: any): void;
-}
+// /**
+//  * The Interaction interface is an abstract class to represent Thing interactions: Properties, Actions and Events.
+//  */
+// export interface ThingInteraction extends InteractionFragment {
+//     forms: Array;
+// }
+
+// /** Represents an interactable Thing Property */
+// export interface ThingProperty extends ThingInteraction, PropertyFragment //, Observable
+// {
+//     read(options?: any): Promise;
+//     write(value: any, options?: any): Promise;
+//     subscribe(next?: (value: any) => void, error?: (error: any) => void, complete?: () => void): Subscription;
+// }
+// /** Represents an interactable Thing Action */
+// export interface ThingAction extends ThingInteraction, ActionFragment {
+//     invoke(parameter?: any, options?: any): Promise;
+// }
+
+// /** Represents an interactable Thing Event */
+// // FIXME: Events are different on ConsumendThing and ExposedThing
+// export interface ThingEvent extends ThingInteraction, EventFragment {
+//     subscribe(next?: (data: any) => void, error?: (error: any) => void, complete?: () => void): Subscription;
+//     // FIXME emit should be only on ExposedThings' ThingEvents - therefore move emit() to ExposedThing?
+//     emit?(data?: any): void;
+// }
+
+// /** Represents a client API object to consume Things and their Properties, Actions, and Events */
+// export interface ConsumedThing extends ThingInstance {
+// }
 
-/** Represents a client API object to consume Things and their Properties, Actions, and Events */
-export interface ConsumedThing extends ThingInstance {
-}
-
-/** Represents a server API object to expose Things and their Properties, Actions, and Events */
-export interface ExposedThing extends ThingInstance {
+/**
+ * The ExposedThing interface is the server API to operate the Thing that allows defining request handlers, Property, Action, and Event interactions.
+ **/
+export interface ExposedThing extends ConsumedThing {
 
     // define how to expose and run the Thing
 
@@ -264,42 +266,42 @@ export interface ExposedThing extends ThingInstance {
 
     // define Thing Description modifiers
 
-    /**
-     * Adds a Property with name defined by the name argument, the data schema provided by the property argument of type PropertyFragment, and optionally an initial value provided in the argument initValue whose type should match the one defined in the type property.
-     */
-    addProperty(name: string, property: PropertyFragment, init?: any): ExposedThing;
-
-    /**
-     * Removes the Property specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
-     */
-    removeProperty(name: string): ExposedThing;
-
-    /**
-     * Adds to the actions property of a Thing object an Action with name defined by the name argument, defines input and output data format by the action argument of type ActionFragment, and adds the function provided in the handler argument as a handler, then updates the Thing Description.
-     * Throws on error.
-     * Returns a reference to the same object for supporting chaining.
-     */
-    addAction(name: string, action: ActionFragment, handler: ActionHandler): ExposedThing;
-
-    /**
-     * Removes the Action specified by the name argument and updates the Thing Description.
-     * Throws on error.
-     * Returns a reference to the same object for supporting chaining.
-     */
-    removeAction(name: string): ExposedThing;
-
-    /**
-     * Adds an event with name defined by the name argument and qualifiers and initialization value provided by the event argument of type EventFragmentto the Thing object and updates the Thing Description.
-     * Throws on error.
-     * Returns a reference to the same object for supporting chaining.
-     */
-    addEvent(name: string, event: EventFragment): ExposedThing;
-
-    /**
-     * Removes the event specified by the name argument and updates the Thing Description.
-     * Returns a reference to the same object for supporting chaining.
-     */
-    removeEvent(name: string): ExposedThing;
+    // /**
+    //  * Adds a Property with name defined by the name argument, the data schema provided by the property argument of type PropertyFragment, and optionally an initial value provided in the argument initValue whose type should match the one defined in the type property.
+    //  */
+    // addProperty(name: string, property: PropertyFragment, init?: any): ExposedThing;
+
+    // /**
+    //  * Removes the Property specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
+    //  */
+    // removeProperty(name: string): ExposedThing;
+
+    // /**
+    //  * Adds to the actions property of a Thing object an Action with name defined by the name argument, defines input and output data format by the action argument of type ActionFragment, and adds the function provided in the handler argument as a handler, then updates the Thing Description.
+    //  * Throws on error.
+    //  * Returns a reference to the same object for supporting chaining.
+    //  */
+    // addAction(name: string, action: ActionFragment, handler: ActionHandler): ExposedThing;
+
+    // /**
+    //  * Removes the Action specified by the name argument and updates the Thing Description.
+    //  * Throws on error.
+    //  * Returns a reference to the same object for supporting chaining.
+    //  */
+    // removeAction(name: string): ExposedThing;
+
+    // /**
+    //  * Adds an event with name defined by the name argument and qualifiers and initialization value provided by the event argument of type EventFragmentto the Thing object and updates the Thing Description.
+    //  * Throws on error.
+    //  * Returns a reference to the same object for supporting chaining.
+    //  */
+    // addEvent(name: string, event: EventFragment): ExposedThing;
+
+    // /**
+    //  * Removes the event specified by the name argument and updates the Thing Description.
+    //  * Returns a reference to the same object for supporting chaining.
+    //  */
+    // removeEvent(name: string): ExposedThing;
 
     // define request handlers
 
@@ -326,6 +328,8 @@ export interface ExposedThing extends ThingInstance {
      * Returns a reference to the same object for supporting chaining.
      */
     setActionHandler(name: string, handler: ActionHandler): ExposedThing;
+
+    emitEvent(name: string, data: any): void;
 }
 
 // TODO: Decide if decorator (with 'internal') or replacement (without 'internal') for get()
@@ -338,153 +342,153 @@ export declare type PropertyWriteHandler = (value: any, options?: any) => Promis
 
 export declare type ActionHandler = (parameters: any, options?: any) => Promise;
 
-export interface Link {
-    href: string;
-    rel?: string | Array;
-    type?: string; // media type hint, no media type parameters
-    anchor?: string;
-}
-
-export interface ExpectedResponse {
-    contentType?: string;
-}
-
-export interface Form {
-    href: string;
-    subprotocol?: string;
-    op?: string | Array;
-    contentType?: string; // media type + parameter(s), e.g., text/plain;charset=utf8
-    security?: Array; // Set of security definition names, chosen from those defined in securityDefinitions  // Security;
-    scopes?: Array;
-    response?: ExpectedResponse;
-}
-
-export declare type MultiLanguage = any; // object?
-
-export type DataSchema = BooleanSchema | IntegerSchema | NumberSchema | StringSchema | ObjectSchema | ArraySchema | NullSchema;
-
-export interface BaseSchema {
-    type?: string;
-    title?: string;
-    titles?: MultiLanguage;
-    description?: string;
-    descriptions?: MultiLanguage;
-    writeOnly?: boolean;
-    readOnly?: boolean;
-    oneOf?: Array;
-    unit?: string;
-    const?: any;
-    enum?: Array;
-}
-
-export interface BooleanSchema extends BaseSchema {
-    type: "boolean";
-}
-
-export interface IntegerSchema extends BaseSchema {
-    type: "integer";
-    minimum?: number;
-    maximum?: number;
-}
-
-export interface NumberSchema extends BaseSchema {
-    type: "number";
-    minimum?: number;
-    maximum?: number;
-}
-
-export interface StringSchema extends BaseSchema {
-    type: "string";
-}
-
-export interface ObjectSchema extends BaseSchema {
-    type: "object";
-    properties: { [key: string]: DataSchema };
-    required?: Array;
-}
-
-export interface ArraySchema extends BaseSchema {
-    type: "array";
-    items: DataSchema;
-    minItems?: number;
-    maxItems?: number;
-}
-
-export interface NullSchema extends BaseSchema {
-    type: "null";
-}
-
-export type Security = NoSecurityScheme | BasicSecurityScheme | DigestSecurityScheme | BearerSecurityScheme | CertSecurityScheme | PoPSecurityScheme | APIKeySecurityScheme | OAuth2SecurityScheme | PSKSecurityScheme | PublicSecurityScheme;
-
-
-export interface SecurityScheme {
-    scheme: string;
-    description?: string;
-    proxy?: string;
-}
-
-export interface NoSecurityScheme extends SecurityScheme {
-    scheme: "nosec";
-}
-
-export interface BasicSecurityScheme extends SecurityScheme {
-    scheme: "basic";
-    in?: string;
-    name?: string;
-}
-
-export interface DigestSecurityScheme extends SecurityScheme {
-    scheme: "digest";
-    name?: string;
-    in?: string;
-    qop?: string;
-}
-
-export interface APIKeySecurityScheme extends SecurityScheme {
-    scheme: "apikey";
-    in?: string;
-    name?: string;
-}
-
-export interface BearerSecurityScheme extends SecurityScheme {
-    scheme: "bearer";
-    in?: string;
-    alg?: string;
-    format?: string;
-    name?: string;
-    authorization?: string;
-}
-
-export interface CertSecurityScheme extends SecurityScheme {
-    scheme: "cert";
-    identity?: string;
-}
-
-export interface PSKSecurityScheme extends SecurityScheme {
-    scheme: "psk";
-    identity?: string;
-}
-
-export interface PublicSecurityScheme extends SecurityScheme {
-    scheme: "public";
-    identity?: string;
-}
-
-export interface PoPSecurityScheme extends SecurityScheme {
-    scheme: "pop";
-    format?: string;
-    authorization?: string;
-    alg?: string;
-    name?: string;
-    in?: string;
-}
-
-export interface OAuth2SecurityScheme extends SecurityScheme {
-    scheme: "oauth2";
-    authorization?: string;
-    flow?: string; // one of implicit, password, client, or code
-    token?: string;
-    refresh?: string;
-    scopes?: Array;
-}
+// export interface Link {
+//     href: string;
+//     rel?: string | Array;
+//     type?: string; // media type hint, no media type parameters
+//     anchor?: string;
+// }
+
+// export interface ExpectedResponse {
+//     contentType?: string;
+// }
+
+// export interface Form {
+//     href: string;
+//     subprotocol?: string;
+//     op?: string | Array;
+//     contentType?: string; // media type + parameter(s), e.g., text/plain;charset=utf8
+//     security?: Array; // Set of security definition names, chosen from those defined in securityDefinitions  // Security;
+//     scopes?: Array;
+//     response?: ExpectedResponse;
+// }
+
+// export declare type MultiLanguage = any; // object?
+
+// export type DataSchema = BooleanSchema | IntegerSchema | NumberSchema | StringSchema | ObjectSchema | ArraySchema | NullSchema;
+
+// export interface BaseSchema {
+//     type?: string;
+//     title?: string;
+//     titles?: MultiLanguage;
+//     description?: string;
+//     descriptions?: MultiLanguage;
+//     writeOnly?: boolean;
+//     readOnly?: boolean;
+//     oneOf?: Array;
+//     unit?: string;
+//     const?: any;
+//     enum?: Array;
+// }
+
+// export interface BooleanSchema extends BaseSchema {
+//     type: "boolean";
+// }
+
+// export interface IntegerSchema extends BaseSchema {
+//     type: "integer";
+//     minimum?: number;
+//     maximum?: number;
+// }
+
+// export interface NumberSchema extends BaseSchema {
+//     type: "number";
+//     minimum?: number;
+//     maximum?: number;
+// }
+
+// export interface StringSchema extends BaseSchema {
+//     type: "string";
+// }
+
+// export interface ObjectSchema extends BaseSchema {
+//     type: "object";
+//     properties: { [key: string]: DataSchema };
+//     required?: Array;
+// }
+
+// export interface ArraySchema extends BaseSchema {
+//     type: "array";
+//     items: DataSchema;
+//     minItems?: number;
+//     maxItems?: number;
+// }
+
+// export interface NullSchema extends BaseSchema {
+//     type: "null";
+// }
+
+// export type Security = NoSecurityScheme | BasicSecurityScheme | DigestSecurityScheme | BearerSecurityScheme | CertSecurityScheme | PoPSecurityScheme | APIKeySecurityScheme | OAuth2SecurityScheme | PSKSecurityScheme | PublicSecurityScheme;
+
+
+// export interface SecurityScheme {
+//     scheme: string;
+//     description?: string;
+//     proxy?: string;
+// }
+
+// export interface NoSecurityScheme extends SecurityScheme {
+//     scheme: "nosec";
+// }
+
+// export interface BasicSecurityScheme extends SecurityScheme {
+//     scheme: "basic";
+//     in?: string;
+//     name?: string;
+// }
+
+// export interface DigestSecurityScheme extends SecurityScheme {
+//     scheme: "digest";
+//     name?: string;
+//     in?: string;
+//     qop?: string;
+// }
+
+// export interface APIKeySecurityScheme extends SecurityScheme {
+//     scheme: "apikey";
+//     in?: string;
+//     name?: string;
+// }
+
+// export interface BearerSecurityScheme extends SecurityScheme {
+//     scheme: "bearer";
+//     in?: string;
+//     alg?: string;
+//     format?: string;
+//     name?: string;
+//     authorization?: string;
+// }
+
+// export interface CertSecurityScheme extends SecurityScheme {
+//     scheme: "cert";
+//     identity?: string;
+// }
+
+// export interface PSKSecurityScheme extends SecurityScheme {
+//     scheme: "psk";
+//     identity?: string;
+// }
+
+// export interface PublicSecurityScheme extends SecurityScheme {
+//     scheme: "public";
+//     identity?: string;
+// }
+
+// export interface PoPSecurityScheme extends SecurityScheme {
+//     scheme: "pop";
+//     format?: string;
+//     authorization?: string;
+//     alg?: string;
+//     name?: string;
+//     in?: string;
+// }
+
+// export interface OAuth2SecurityScheme extends SecurityScheme {
+//     scheme: "oauth2";
+//     authorization?: string;
+//     flow?: string; // one of implicit, password, client, or code
+//     token?: string;
+//     refresh?: string;
+//     scopes?: Array;
+// }
 
diff --git a/typescript/package.json b/typescript/package.json
index bfa8fb96..087c0209 100644
--- a/typescript/package.json
+++ b/typescript/package.json
@@ -1,6 +1,6 @@
 {
   "name": "wot-typescript-definitions",
-  "version": "0.7.0-NEXT-SNAPSHOT.10",
+  "version": "0.7.0-NEXT-SNAPSHOT.11",
   "description": "TypeScript definitions for the W3C WoT Scripting API",
   "author": "W3C Web of Things Working Group",
   "license": "W3C-20150513",

From 6ef8d7ec68ed8a96300dd177fa509c26890e2cd3 Mon Sep 17 00:00:00 2001
From: danielpeintner 
Date: Tue, 30 Jul 2019 10:12:45 +0200
Subject: [PATCH 339/464] feat: define ThingDescription as any key/value map to
 avoid TD warnings/errors

---
 typescript/index.d.ts   | 2 +-
 typescript/package.json | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/typescript/index.d.ts b/typescript/index.d.ts
index 6b713b32..037ebc90 100644
--- a/typescript/index.d.ts
+++ b/typescript/index.d.ts
@@ -81,7 +81,7 @@ export interface ThingDiscovery {
  * WoT provides a unified representation for data exchange between Things, standardized in the Wot Things Description specification.
  * In this version of the API, Thing Descriptions is expected to be a parsed JSON object.
  */
-export declare type ThingDescription = object;
+export declare type ThingDescription = object | {[ key: string ]: any; };
 
 // /** Carries version information about the TD instance. If required, additional version information such as firmware and hardware version (term definitions outside of the TD namespace) can be extended here. */
 // export interface VersionInfo {
diff --git a/typescript/package.json b/typescript/package.json
index 087c0209..5f14d267 100644
--- a/typescript/package.json
+++ b/typescript/package.json
@@ -1,6 +1,6 @@
 {
   "name": "wot-typescript-definitions",
-  "version": "0.7.0-NEXT-SNAPSHOT.11",
+  "version": "0.7.0-NEXT-SNAPSHOT.12",
   "description": "TypeScript definitions for the W3C WoT Scripting API",
   "author": "W3C Web of Things Working Group",
   "license": "W3C-20150513",

From a68938a6031b912da0ea82e6f73c77a6d0e29c11 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Tue, 20 Aug 2019 12:58:11 +0300
Subject: [PATCH 340/464] Fix #183: add id to observe and subscribe

Signed-off-by: Zoltan Kis 
---
 index.html | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/index.html b/index.html
index 4d111008..aca03fe5 100644
--- a/index.html
+++ b/index.html
@@ -503,10 +503,10 @@ 
                      The ConsumedThing interface
                      
         Promise<void> writeProperty(DOMString propertyName, any value);
         Promise<void> writeMultipleProperties(object valueMap);
         Promise<any> invokeAction(DOMString actionName, optional any params);
-        Promise<void> observeProperty(DOMString name, WotListener listener);
-        Promise<void> unobserveProperty(DOMString name);
-        Promise<void> subscribeEvent(DOMString name, WotListener listener);
-        Promise<void> unsubscribeEvent(DOMString name);
+        Promise<DOMString> observeProperty(DOMString name, WotListener listener);
+        Promise<void> unobserveProperty(DOMString subscriptionId);
+        Promise<DOMString> subscribeEvent(DOMString name, WotListener listener);
+        Promise<void> unsubscribeEvent(DOMString subscriptionId);
         readonly attribute ThingDescription td;
       };
       callback WotListener = void(any data);
@@ -720,7 +720,7 @@ 
                      The observeProperty() method
                      
             If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps.
           
           
                    • 
-            Otherwise resolve promise.
+            Otherwise let id be a string generated by the implementation to identify the subscription in a later unobserve request. Resolve promise with a id.
           
                      • 
           
                    • 
             Whenever the underlying platform receives a notification for this subscription with new Property value value, run
@@ -741,7 +741,7 @@ 
                      The observeProperty() method
                      
     
                      
       
                      The unobserveProperty() method
                      
       
                      
-        Makes a request for unsubscribing from Property value change notifications. Takes a string argument propertyName and returns success or failure. The method MUST run the following steps:
+        Makes a request for unsubscribing from Property value change notifications. Takes a string argument subscriptionId and returns success or failure. The method MUST run the following steps:
         
                        
           
                      1. 
             Return a Promise promise and execute the next steps in parallel.
@@ -750,7 +750,7 @@ 
                        The unobserveProperty() method
                        
             If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
           
                        2. 
           
                      2. 
-            Make a request to the underlying platform (via the Protocol Bindings) to stop observing the Property identified by propertyName.
+            Make a request to the underlying platform (via the Protocol Bindings) to stop observing the Property identified by subscriptionId.
           
                        3. 
           
                      3. 
             If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps.
@@ -813,7 +813,7 @@ 
                        The subscribeEvent() method
                        
             If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps.
           
                        4. 
           
                      4. 
-            Otherwise resolve promise.
+            Otherwise let id be a string generated by the implementation to identify the subscription in a later unsubscribe request. Resolve promise.
           
                        5. 
           
                      5. 
             Whenever the underlying platform receives a notification for this Event subscription, implementations SHOULD invoke
@@ -827,7 +827,7 @@ 
                        The subscribeEvent() method
                        
     
                        
       
                        The unsubscribeEvent() method
                        
       
                        
-        Makes a request for unsubscribing from Event notifications. Takes a string argument eventName and returns success or failure. The method MUST run the following steps:
+        Makes a request for unsubscribing from Event notifications. Takes a string argument subscriptionId and returns success or failure. The method MUST run the following steps:
         
                          
           
                        1. 
             Return a Promise promise and execute the next steps in parallel.
@@ -836,7 +836,7 @@ 
                          The unsubscribeEvent() method
                          
             If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
           
                          2. 
           
                        2. 
-            Make a request to the underlying platform (via the Protocol Bindings) to unsubscribe from the Event identified by eventName.
+            Make a request to the underlying platform (via the Protocol Bindings) to unsubscribe from the Event identified by subscriptionId.
           
                          3. 
           
                        3. 
             If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps.

From 129c1e35baa3f7d92c6aeeef2a2231fa1de7ad44 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Tue, 20 Aug 2019 13:16:26 +0300
Subject: [PATCH 341/464] Fix #184: change .td to function
 .getThingDescription() and add the ||td|| internal slot

Signed-off-by: Zoltan Kis 
---
 index.html | 49 ++++++++++++++++++++-----------------------------
 1 file changed, 20 insertions(+), 29 deletions(-)

diff --git a/index.html b/index.html
index aca03fe5..a568e179 100644
--- a/index.html
+++ b/index.html
@@ -329,7 +329,7 @@ 
                          The ThingDescription type
                          
           // ... additional checks possible on res.headers
           let td = await res.json();
           let thing = new ConsumedThing(td);
-          console.log("Thing name: " + thing.td.title);
+          console.log("Thing name: " + thing.getThingDescription().title);
         } catch (err) {
           console.log("Fetching TD failed", err.message);
         }
@@ -445,12 +445,6 @@ 
                          The WoT API object
                          
         
                        4. 
           Let thing be a new ExposedThing object constructed with td.
         
                          5. 
-        
                        5. 
-          Run the validate a TD steps on td. If that throws, reject promise with the error and terminate these steps.
-        
                          6. 
-        
                        6. 
-          Let thing.td be td.
-        
                          7. 
         
                        7. 
           Resolve promise with thing.
         
                          8. 
@@ -507,7 +501,7 @@ 
                          The ConsumedThing interface
                          
         Promise<void> unobserveProperty(DOMString subscriptionId);
         Promise<DOMString> subscribeEvent(DOMString name, WotListener listener);
         Promise<void> unsubscribeEvent(DOMString subscriptionId);
-        readonly attribute ThingDescription td;
+        ThingDescription getThingDescription();
       };
       callback WotListener = void(any data);
                      • @@ -524,15 +518,13 @@

                      Constructing ConsumedThing

                      td, run the following steps:
                      1. - If td is not an object, throw "TypeError" - and terminate these steps. + Run the expand a TD steps on td. If that fails, re-throw the error and terminate these steps.
                      2. - Run the expand a TD steps on td. + Let thing be a new ConsumedThing object.
                      3. - Let thing be a new ConsumedThing object and - let thing.td be td. + Let ||td|| be an internal slot of thing and let td be its value.
                      4. Return thing. @@ -542,10 +534,10 @@

                        Constructing ConsumedThing

                      -

                      The td property

                      +

                      The getThingDescription() method

                      - 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. + Returns the internal slot ||td|| of the ConsumedThing object that represents the Thing Description of the ConsumedThing. + Applications may consult the Thing metadata stored in ||td|| in order to introspect its capabilities before interacting with it.

                      @@ -573,7 +565,7 @@

                      The readProperty() method

                      Run the validate Property value sub-steps on value:
                      1. - Based on the DataSchema definition, value MUST be a JSON value and comply to the data schema defined for the Property that is found in this.td.properties[propertyName]. + Based on the DataSchema definition, value MUST be a JSON value and comply to the data schema defined for the Property that is found in this.getTD().properties[propertyName].
                      2. If this fails, throw SyntaxError, otherwise return value. @@ -622,7 +614,7 @@

                        The readAllProperties() method

                        Reads all properties of the Thing with one or multiple requests. Takes no arguments. It returns an object with keys from Property names and values returned by this algorithm. The method MUST run the following steps:
                        1. - Let propertyNames be a sequence created from all the Property names of this Thing as found in this.td.properties. + Let propertyNames be a sequence created from all the Property names of this Thing as found in this.getThingDescription().properties.
                        2. Let result be the result of running the readMultipleProperties() steps on propertyNames. If that fails, reject promise with that error and terminate these steps. @@ -858,7 +850,7 @@

                          ConsumedThing Examples

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

                          Constructing ExposedThing

                          If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
                        3. - If td is not a an object, throw TypeError - and terminate these steps. + Run the expand a TD steps on td. If that fails, re-throw the error and terminate these steps.
                        4. Let thing be a new ExposedThing object.
                        5. - Let thing.td be td. There is no validation or any transformation done on td at this stage. + Let ||td|| be an internal slot of thing and let td be its value.
                        6. Return thing. @@ -1097,7 +1088,7 @@

                          The ActionHandler callback

                          If invoking this method is not allowed for the current scripting context for security reasons, throw SecurityError and terminate these steps.
                        7. - If an Event with the name name is not found in this.td.events, throw NotFoundError and terminate these steps. + If an Event with the name name is not found in this.getThingDescription().events, throw NotFoundError and terminate these steps.
                        8. Make a request to the underlying platform to send an Event with data attached as property, using the Protocol Bindings, then terminate these steps. @@ -1117,15 +1108,15 @@

                          The ActionHandler callback

                          If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
                        9. - Run the expand a TD steps on this.td. + Run the expand a TD steps on the internal slot ||td||.
                        10. - Run the validate a TD on this.td. If that fails, + Run the validate a TD on ||td||. If that fails, reject promise with "TypeError" and terminate these steps.
                        11. - For each Property definition in this.instance.properties initialize an internal observer list internal slot + For each Property definition in this.instance.properties initialize an |internal observer list| internal slot in order to store observe request data needed to notify the observers on value changes.
                        12. @@ -1523,7 +1514,7 @@

                          Discovery Examples

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

                          @@ -1544,7 +1535,7 @@

                          Discovery Examples

                          let td = await discovery.next(); console.log("Found Thing Description for " + td.title); let thing = new ConsumedThing(td); - console.log("Thing name: " + thing.td.title); + console.log("Thing name: " + thing.getThingDescription().title); } while (!discovery.done); if (discovery.error) { console.log("Discovery stopped because of an error: " + error.message); @@ -1563,7 +1554,7 @@

                          Discovery Examples

                          do { let td = await discovery.next(); let thing = new ConsumedThing(td); - console.log("Thing name: " + thing.td.title); + console.log("Thing name: " + thing.getThingDescription().title); } while (!discovery.done);
                      From 8e969ce6e1dac3eed45cfae974c487c2114f284c Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Tue, 20 Aug 2019 19:18:13 +0300 Subject: [PATCH 342/464] Fix #182: re-add InteractionOptions that contain uriVariables, define PropertyValueMap Signed-off-by: Zoltan Kis --- index.html | 126 +++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 99 insertions(+), 27 deletions(-) diff --git a/index.html b/index.html index a568e179..4c18e523 100644 --- a/index.html +++ b/index.html @@ -491,18 +491,46 @@

                      The ConsumedThing interface

                             [Constructor(ThingDescription td), SecureContext, Exposed=(Window,Worker)]
       interface ConsumedThing {
-        Promise<any> readProperty(DOMString propertyName);
-        Promise<object> readAllProperties();
-        Promise<object> readMultipleProperties(sequence<DOMString> propertyNames);
-        Promise<void> writeProperty(DOMString propertyName, any value);
-        Promise<void> writeMultipleProperties(object valueMap);
-        Promise<any> invokeAction(DOMString actionName, optional any params);
-        Promise<DOMString> observeProperty(DOMString name, WotListener listener);
+        Promise<any> readProperty(DOMString propertyName,
+            optional InteractionOptions options = null
+        );
+        Promise<object> readAllProperties(
+            optional InteractionOptions options = null
+        );
+        Promise<object> readMultipleProperties(
+            sequence<DOMString> propertyNames,
+            optional InteractionOptions options = null
+        );
+        Promise<void> writeProperty(DOMString propertyName,
+            any value,
+            optional InteractionOptions options = null
+        );
+        Promise<void> writeMultipleProperties(
+            PropertyValueMap valueMap,
+            optional InteractionOptions options = null
+        );
+        Promise<any> invokeAction(
+            DOMString actionName,
+            optional any params = null,
+            optional InteractionOptions options = null
+        );
+        Promise<DOMString> observeProperty(DOMString name,
+            WotListener listener,
+            optional InteractionOptions options = null
+        );
         Promise<void> unobserveProperty(DOMString subscriptionId);
-        Promise<DOMString> subscribeEvent(DOMString name, WotListener listener);
+        Promise<DOMString> subscribeEvent(
+            DOMString name,
+            WotListener listener,
+            optional InteractionOptions options = null
+        );
         Promise<void> unsubscribeEvent(DOMString subscriptionId);
         ThingDescription getThingDescription();
       };
+      dictionary InteractionOptions {
+        object uriVariables;
+      };
+      typedef object PropertyValueMap;
       callback WotListener = void(any data);
                      @@ -541,10 +569,30 @@

                      The getThingDescription() method

                      +
                      +

                      The InteractionOptions dictionary

                      +

                      + Holds the interaction options that need to be exposed for application scripts according to the Thing Description. In this version of the specification only URI template variables are used, represented as parsed JSON objects defined in [[!WOT-TD]]. +

                      +

                      + The support for URI variables comes from the need exposed by [[WOT-TD]] to be able to describe existing TDs that use them, but it should be possible to write a Thing Description that would use Actions for representing the interactions that need URI variables and represent the URI variables as parameters to the Action. +

                      +
                      + +
                      +

                      The PropertyValueMap type

                      +

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

                      +

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

                      +
                      +

                      The readProperty() method

                      - Reads a Property value. Takes a string argument propertyName and returns a Property value represented as any type. The method MUST run the following steps: + Reads a Property value. Takes a string argument propertyName and and an optional InteractionOptions options argument. It returns a Property value represented as any type. The method MUST run the following steps:

                      1. Return a Promise promise and execute the next steps in parallel. @@ -553,7 +601,7 @@

                        The readProperty() method

                        If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
                      2. - Make a request to the underlying platform (via the Protocol Bindings) to retrieve the value of the Property given by propertyName. + Make a request to the underlying platform (via the Protocol Bindings) to retrieve the value of the Property given by propertyName with optional URI templates given in options.uriVariables.
                      3. If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps. @@ -584,7 +632,7 @@

                        The readProperty() method

                        The readMultipleProperties() method

                        - Reads multiple Property values with one or multiple requests. Takes one argument, a sequence of strings propertyNames and returns an object with keys from propertyNames and values returned by this algorithm. The method MUST run the following steps: + Reads multiple Property values with one or multiple requests. Takes the propertyNames argument as a sequence of strings and an optional InteractionOptions options argument. It returns an object with keys from propertyNames and values returned by this algorithm. The method MUST run the following steps:

                        1. Return a Promise promise and execute the next steps in parallel. @@ -596,7 +644,13 @@

                          The readMultipleProperties() method

                          Let result be an object and for each string name in propertyNames add a property with key name and the value null.
                        2. - Make a request to the underlying platform (via the Protocol Bindings) to retrieve the Property values given by propertyNames. If the Protocol Bindings support this using one request, use that, otherwise run the readProperty() steps on each property name in propertyNames and store the resulting values in result for each name in propertyNames. + Make a request to the underlying platform (via the Protocol Bindings) to retrieve the Property values given by propertyNames with optional URI templates given in options.uriVariables. +
                          3. +
                        3. + If this cannot be done with a single request with the Protocol Bindings of the Thing, then reject promise with NotSupportedError and terminate these steps. +
                          4. +
                        4. + Process the reply and update all properties in result with the values obtained in the reply.
                        5. If the above step fails at any point, reject promise with SyntaxError and terminate these steps. @@ -611,13 +665,28 @@

                          The readMultipleProperties() method

                          The readAllProperties() method

                          - Reads all properties of the Thing with one or multiple requests. Takes no arguments. It returns an object with keys from Property names and values returned by this algorithm. The method MUST run the following steps: + Reads all properties of the Thing with one or multiple requests. Takes an optional InteractionOptions options argument. It returns an object with keys from Property names and values returned by this algorithm. The method MUST run the following steps:

                          1. - Let propertyNames be a sequence created from all the Property names of this Thing as found in this.getThingDescription().properties. + Return a Promise promise and execute the next steps in parallel.
                          2. - Let result be the result of running the readMultipleProperties() steps on propertyNames. If that fails, reject promise with that error and terminate these steps. + If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps. +
                            3. +
                          3. + Let result be an object and for each string name in propertyNames add a property with key name and the value null. +
                            4. +
                          4. + Make a request to the underlying platform (via the Protocol Bindings) to retrieve the value of the all the Property definitions from the TD with optional URI templates given in options.uriVariables. +
                            5. +
                          5. + If this cannot be done with a single request with the Protocol Bindings of the Thing, then reject promise with NotSupportedError and terminate these steps. +
                            6. +
                          6. + If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps. +
                            7. +
                          7. + Process the reply and update all properties in result with the values obtained in the reply.
                          8. Resolve promise with result. @@ -629,7 +698,7 @@

                            The readAllProperties() method

                            The writeProperty() method

                            - Writes a single Property. Takes a string argument propertyName and a value argument value. It returns success or failure. The method MUST run the following steps: + Writes a single Property. Takes a string argument propertyName, a value argument value and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps:

                            1. Return a Promise promise and execute the next steps in parallel. @@ -641,7 +710,7 @@

                              The writeProperty() method

                              Run the validate Property value steps on value. If that fails, reject promise with SyntaxError and terminate these steps.
                            2. - Make a request to the underlying platform (via the Protocol Bindings) to write value to the Property given by propertyName. + Make a request to the underlying platform (via the Protocol Bindings) to write value to the Property given by propertyName with optional URI templates given in options.uriVariables.
                            3. If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps. @@ -656,7 +725,7 @@

                              The writeProperty() method

                              The writeMultipleProperties() method

                              - Writes a multiple Property values with one request. Takes one argument, an object properties with keys as Property names and values as Property values. It returns success or failure. The method MUST run the following steps: + Writes a multiple Property values with one request. Takes a properties argument as an object with keys being Property names and values as Property values and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps:

                              1. Return a Promise promise and execute the next steps in parallel. @@ -668,7 +737,10 @@

                                The writeMultipleProperties() method

                                For each key name on properties, take its value as value and run the validate Property value steps on value. If that fails in for any name, reject promise with SyntaxError and terminate these steps.
                              2. - Make a single request to the underlying platform (via the Protocol Bindings) to write the each Property provided in properties. If this cannot be done with a single request with the Protocol Bindings of the Thing, then reject promise with NotSupportedError and terminate these steps. + Make a single request to the underlying platform (via the Protocol Bindings) to write the each Property provided in properties with optional URI templates given in options.uriVariables. +
                                3. +
                              3. + If this cannot be done with a single request with the Protocol Bindings of the Thing, then reject promise with NotSupportedError and terminate these steps.
                              4. If the request fails, return the error received from the Protocol Bindings and terminate these steps. @@ -691,8 +763,8 @@

                                The WotListener callback

                                The observeProperty() method

                                - Makes a request for Property value change notifications. Takes a string argument propertyName and a WotListener - callback function listener. It returns success or failure. + Makes a request for Property value change notifications. Takes a string argument propertyName, a WotListener + callback function listener and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps:

                                1. @@ -706,7 +778,7 @@

                                  The observeProperty() method

                                  with "TypeError" and terminate these steps.
                                2. - Make a request to the underlying platform (via the Protocol Bindings) to observe Property identified by propertyName. + Make a request to the underlying platform (via the Protocol Bindings) to observe Property identified by propertyName with optional URI templates given in options.uriVariables.
                                3. If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps. @@ -757,7 +829,7 @@

                                  The unobserveProperty() method

                                  The invokeAction() method

                                  - Makes a request for invoking an Action and return the result. Takes a string argument actionName, and an optional argument parameters of type any. It returns the result of the Action or an error. The method MUST run the following steps: + Makes a request for invoking an Action and return the result. Takes a string argument actionName, an optional argument parameters of type any and an optional InteractionOptions options argument. It returns the result of the Action or an error. The method MUST run the following steps:

                                  1. Return a Promise promise and execute the next steps in parallel. @@ -766,7 +838,7 @@

                                    The invokeAction() method

                                    If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
                                  2. - Make a request to the underlying platform (via the Protocol Bindings) to invoke the Action identified by actionName with parameters provided in params. + Make a request to the underlying platform (via the Protocol Bindings) to invoke the Action identified by actionName with parameters provided in params with optional URI templates given in options.uriVariables.
                                  3. If the request fails locally or returns an error over the network, reject promise with the error received from the Protocol Bindings and terminate these steps. @@ -784,8 +856,8 @@

                                    The invokeAction() method

                                    The subscribeEvent() method

                                    - Makes a request for subscribing to Event notifications. Takes a string argument eventName and a WotListener - callback function listener. It returns success or failure. + Makes a request for subscribing to Event notifications. Takes a string argument eventName, a WotListener + callback function listener and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps:

                                    1. @@ -799,7 +871,7 @@

                                      The subscribeEvent() method

                                      with "TypeError" and terminate these steps.
                                    2. - Make a request to the underlying platform (via the Protocol Bindings) to subscribe to an Event identified by eventName. + Make a request to the underlying platform (via the Protocol Bindings) to subscribe to an Event identified by eventNamewith optional URI templates given in options.uriVariables.
                                    3. If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps. From 7a6dd344856ed2ddf0d36fbac6ffa3d8a0e39ee0 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 21 Aug 2019 17:59:12 +0300 Subject: [PATCH 343/464] Fix #180: Clarify ExposedThing Property initialization Signed-off-by: Zoltan Kis --- index.html | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/index.html b/index.html index 4c18e523..2349c0bd 100644 --- a/index.html +++ b/index.html @@ -980,9 +980,10 @@

                                      Constructing ExposedThing

                                      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, - and later adding the service handler functions. - This is illustrated in the examples. + removing Property, Action and Event definitions, as illustrated in the examples. +

                                      +

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

                                      To construct an ExposedThing with the ThingDescription @@ -1260,16 +1261,14 @@

                                      ExposedThing Examples

                                      } }; let thing1 = await WOT.produce(tdFragment); - // TODO: add service handlers + // initialize Properties + await thing1.writeProperty("temperature", 0); + // add service handlers + thing1.setPropertyReadHandler("temperature", () => { + return readLocalTemperatureSensor(); // Promise + }); + // start serving requests await thing1.expose(); - // define Thing business logic - setInterval( async () => { - let mock = Math.random()*100; - let old = await thing1.readProperty("temperature"); - if (old < mock) { - await thing1.writeProperty("temperature", mock); - } - }, 1000); } catch (err) { console.log("Error creating ExposedThing: " + err); } From bd3372d19de78718cc907e85779801e9d4f90328 Mon Sep 17 00:00:00 2001 From: ashimura Date: Thu, 22 Aug 2019 01:58:32 +0900 Subject: [PATCH 344/464] add .pr-preview.json --- .pr-preview.json | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 .pr-preview.json diff --git a/.pr-preview.json b/.pr-preview.json new file mode 100644 index 00000000..010969ea --- /dev/null +++ b/.pr-preview.json @@ -0,0 +1,4 @@ +{ + "src_file": "index.html", + "type": "respec" + } From e5caa3f4def04772134d1b1679409afd2d827e36 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 26 Aug 2019 15:40:37 +0300 Subject: [PATCH 345/464] Clarify ExposedThing default handlers vs script provided handlers. Editorial fixes. Signed-off-by: Zoltan Kis --- index.html | 29 ++++++++++++++++++++++------- 1 file changed, 22 insertions(+), 7 deletions(-) diff --git a/index.html b/index.html index 2349c0bd..d72c3ebc 100644 --- a/index.html +++ b/index.html @@ -491,7 +491,8 @@

                                      The ConsumedThing interface

                                             [Constructor(ThingDescription td), SecureContext, Exposed=(Window,Worker)]
       interface ConsumedThing {
-        Promise<any> readProperty(DOMString propertyName,
+        Promise<any> readProperty(
+            DOMString propertyName,
             optional InteractionOptions options = null
         );
         Promise<object> readAllProperties(
@@ -501,7 +502,8 @@ 
                                      The ConsumedThing interface
                                      
             sequence<DOMString> propertyNames,
             optional InteractionOptions options = null
         );
-        Promise<void> writeProperty(DOMString propertyName,
+        Promise<void> writeProperty(
+            DOMString propertyName,
             any value,
             optional InteractionOptions options = null
         );
@@ -514,7 +516,8 @@ 
                                      The ConsumedThing interface
                                      
             optional any params = null,
             optional InteractionOptions options = null
         );
-        Promise<DOMString> observeProperty(DOMString name,
+        Promise<DOMString> observeProperty(
+            DOMString name,
             WotListener listener,
             optional InteractionOptions options = null
         );
@@ -575,7 +578,7 @@ 
                                      The InteractionOptions dictionary
                                      
         Holds the interaction options that need to be exposed for application scripts according to the Thing Description. In this version of the specification only URI template variables are used, represented as parsed JSON objects defined in [[!WOT-TD]].
       
                                      
       
                                      
-        The support for URI variables comes from the need exposed by [[WOT-TD]] to be able to describe existing TDs that use them, but it should be possible to write a Thing Description that would use Actions for representing the interactions that need URI variables and represent the URI variables as parameters to the Action.
+        The support for URI variables comes from the need exposed by [[WOT-TD]] to be able to describe existing TDs that use them, but it should be possible to write a Thing Description that would use Actions for representing the interactions that need URI variables and represent the URI variables as parameters to the Action and in that case that could be encapsulated by the implementations and the options parameter could be dismissed from the methods exposed by this API.
                                    @@ -613,7 +616,7 @@

                                    The readProperty() method

                                    Run the validate Property value sub-steps on value:
                                    1. - Based on the DataSchema definition, value MUST be a JSON value and comply to the data schema defined for the Property that is found in this.getTD().properties[propertyName]. + Based on the DataSchema definition, value MUST be a JSON value and comply to the data schema defined for the Property that is found in this.getThingDescription().properties[propertyName].
                                    2. If this fails, throw SyntaxError, otherwise return value. @@ -1007,6 +1010,18 @@

                                      Constructing ExposedThing

                                  +
                                  +

                                  Methods inherited from ConsumedThing

                                  +

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

                                  +

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

                                  +

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

                                  +

                                  The PropertyReadHandler callback

                                  @@ -1023,7 +1038,7 @@

                                  The PropertyReadHandler callback

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

                                  - There MUST be at most one handler for any given Property, so newly added handlers MUST replace the previous handlers. If no handler is initialized for any given Property, implementations MAY implement a default property read handler based on the Thing Description. + 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.

                                  @@ -1076,7 +1091,7 @@

                                  The PropertyWriteHandler callback

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

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

                                From 8eb4b232d88a0a321f6bc4da5cafc00412ca4b55 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Tue, 27 Aug 2019 09:11:03 +0200 Subject: [PATCH 346/464] feat: align with latest scripting changes * subscriptionId * getThingDescription() * optional InteractionOptions --- typescript/index.d.ts | 369 ++-------------------------------------- typescript/package.json | 2 +- 2 files changed, 18 insertions(+), 353 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index 037ebc90..8a832581 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -1,6 +1,3 @@ -// import { Observable } from 'rxjs/Observable'; -// import { Subscription } from 'rxjs/Subscription'; - export as namespace WoT; /** @@ -81,179 +78,43 @@ export interface ThingDiscovery { * WoT provides a unified representation for data exchange between Things, standardized in the Wot Things Description specification. * In this version of the API, Thing Descriptions is expected to be a parsed JSON object. */ -export declare type ThingDescription = object | {[ key: string ]: any; }; - -// /** Carries version information about the TD instance. If required, additional version information such as firmware and hardware version (term definitions outside of the TD namespace) can be extended here. */ -// export interface VersionInfo { -// instance?: string; -// } - -// /** -// * The ThingFragment dictionary contains fields to initialize a Thing or to match during discovery -// */ -// export interface ThingFragment { -// /** A hint to gernerate the identifier for the Thing */ -// id?: string; -// /** The title attribute represents the user given name of the Thing */ -// title?: string; -// /** Define the base URI that is valid for all defined local interaction resources */ -// base?: string; -// /** A human-readable description of the Thing */ -// description?: string; -// /** Human-readable descriptions in different languages */ -// descriptions?: MultiLanguage; -// /** Information about the Thing maintainer, e.g., author or contact URI */ -// support?: string; -// /** Provides information when the TD instance was last modified */ -// lastModified?: string; -// /** Provides information when the TD instance was created */ -// created?: string; -// /** Provides version information */ -// version?: VersionInfo; - -// /** Set of named security configurations (definitions only). Not actually applied unless names are used in a security section */ -// securityDefinitions?: { [key: string]: Security } -// /** Set of security definition names, chosen from those defined in securityDefinitions. */ -// security?: Array; - -// /** A map of PropertyFragments with decriptions only */ -// properties?: { [key: string]: PropertyFragment } -// /** A map of ActionFragments with decriptions only */ -// actions?: { [key: string]: ActionFragment } -// /** A map of EventFragments with decriptions only */ -// events?: { [key: string]: EventFragment } -// /** A list of Web links to other Things or metadata */ -// links?: Array; -// /** Indicates one or more endpoints at which operation(s) on this resource are accessible */ -// forms?: Array; -// /** -// * A collection of predicate terms that reference values of any type, -// * e.g., @context, @type, or other terms from the vocabulary defined in @context. -// */ -// [key: string]: any; -// } - -// /** Base for representing Thing Interaction descriptions */ -// export interface InteractionFragment { -// /** A human-readable title for the Interaction, e.g., for UIs */ -// title?: string; -// /** Human-readable titles for the Interaction, in different languages */ -// titles?: MultiLanguage; -// /** A human-readable description of the Interaction */ -// description?: string; -// /** Human-readable descriptions in different languages */ -// descriptions?: MultiLanguage; -// /** Set of authorization scope identifiers */ -// scopes?: Array; -// /** URI template variables */ -// uriVariables?: { [key: string]: DataSchema }; -// /** Set of security definition names */ -// security?: Array; - -// /** -// * A collection of predicate terms that reference values of any type, -// * e.g., @type, or other terms from the vocabulary defined in @context. -// */ -// [key: string]: any; -// } +export declare type ThingDescription = object | { [key: string]: any; }; -// /** Represents a Thing Property description */ -// export interface PropertyFragment extends InteractionFragment, BaseSchema { -// observable?: boolean; -// } -// /** Represents a Thing Action description */ -// export interface ActionFragment extends InteractionFragment { -// input?: DataSchema; -// output?: DataSchema; -// safe?: boolean; -// idempotent?: boolean; -// } -// /** Represents a Thing Event description */ -// export interface EventFragment extends InteractionFragment { -// subscription?: DataSchema; -// data?: DataSchema; -// cancellation?: DataSchema; -// } /** * The ConsumedThing interface instance represents a client API to operate a Thing. */ export interface ConsumedThing { - // /** id becomes mandatory for Thing instances */ - // id: string; - // /** title becomes mandatory for Thing instances */ - // title: string; - // /** base becomes available for Thing instances (part of binding metadata) */ - // base?: string; + readProperty(propertyName: string, options?: InteractionOptions): Promise; + readAllProperties(options?: InteractionOptions): Promise; + readMultipleProperties(propertyNames: string[], options?: InteractionOptions): Promise; + writeProperty(propertyName: string, value: any, options?: InteractionOptions): Promise; + writeMultipleProperties(valueMap: PropertyValueMap, options?: InteractionOptions): Promise; - // /** A map of ThingProperties (PropertyFragment plus mandatory binding metadata (forms)) */ - // properties: { [key: string]: ThingProperty }; - // /** A map of ThingActions (ActionFragment plus mandatory binding metadata (forms)) */ - // actions: { [key: string]: ThingAction }; - // /** A map of ThingEvents (EventFragment plus mandatory binding metadata (forms)) */ - // events: { [key: string]: ThingEvent }; + invokeAction(actionName: string, parameter?: any, options?: InteractionOptions): Promise; - // next API - // XXX add additional 'options' field to allow for uriVariables et cetera - readProperty(propertyName: string): Promise; - readAllProperties(): Promise; - readMultipleProperties(propertyNames: string[]): Promise; - writeProperty(propertyName: string, value: any): Promise; - writeMultipleProperties(valueMap: { [key: string]: any }): Promise; + observeProperty(name: string, listener: WotListener, options?: InteractionOptions): Promise; + unobserveProperty(subscriptionId: string): Promise; - invokeAction(actionName: string, parameter?: any): Promise; + subscribeEvent(name: string, listener: WotListener, options?: InteractionOptions): Promise; + unsubscribeEvent(subscriptionId: string): Promise; - observeProperty(name: string, listener: WotListener): Promise; - unobserveProperty(name: string): Promise; - - subscribeEvent(name: string, listener: WotListener): Promise; - unsubscribeEvent(name: string): Promise; - - getTD(): ThingDescription; - // replace getTD with attribute? - // td: ThingDescription; + getThingDescription(): ThingDescription; } -export declare type WotListener = (data: any) => void; - -// /** -// * The Interaction interface is an abstract class to represent Thing interactions: Properties, Actions and Events. -// */ -// export interface ThingInteraction extends InteractionFragment { -// forms: Array; -// } +export interface InteractionOptions { + uriVariables: object; +} -// /** Represents an interactable Thing Property */ -// export interface ThingProperty extends ThingInteraction, PropertyFragment //, Observable -// { -// read(options?: any): Promise; -// write(value: any, options?: any): Promise; -// subscribe(next?: (value: any) => void, error?: (error: any) => void, complete?: () => void): Subscription; -// } -// /** Represents an interactable Thing Action */ -// export interface ThingAction extends ThingInteraction, ActionFragment { -// invoke(parameter?: any, options?: any): Promise; -// } +export declare type PropertyValueMap = object | { [key: string]: any; }; -// /** Represents an interactable Thing Event */ -// // FIXME: Events are different on ConsumendThing and ExposedThing -// export interface ThingEvent extends ThingInteraction, EventFragment { -// subscribe(next?: (data: any) => void, error?: (error: any) => void, complete?: () => void): Subscription; -// // FIXME emit should be only on ExposedThings' ThingEvents - therefore move emit() to ExposedThing? -// emit?(data?: any): void; -// } +export declare type WotListener = (data: any) => void; -// /** Represents a client API object to consume Things and their Properties, Actions, and Events */ -// export interface ConsumedThing extends ThingInstance { -// } /** * The ExposedThing interface is the server API to operate the Thing that allows defining request handlers, Property, Action, and Event interactions. **/ export interface ExposedThing extends ConsumedThing { - - // define how to expose and run the Thing - /** * Start serving external requests for the Thing, so that WoT Interactions using Properties, Actions and Events will be possible. */ @@ -264,47 +125,6 @@ export interface ExposedThing extends ConsumedThing { */ destroy(): Promise; - // define Thing Description modifiers - - // /** - // * Adds a Property with name defined by the name argument, the data schema provided by the property argument of type PropertyFragment, and optionally an initial value provided in the argument initValue whose type should match the one defined in the type property. - // */ - // addProperty(name: string, property: PropertyFragment, init?: any): ExposedThing; - - // /** - // * Removes the Property specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining. - // */ - // removeProperty(name: string): ExposedThing; - - // /** - // * Adds to the actions property of a Thing object an Action with name defined by the name argument, defines input and output data format by the action argument of type ActionFragment, and adds the function provided in the handler argument as a handler, then updates the Thing Description. - // * Throws on error. - // * Returns a reference to the same object for supporting chaining. - // */ - // addAction(name: string, action: ActionFragment, handler: ActionHandler): ExposedThing; - - // /** - // * Removes the Action specified by the name argument and updates the Thing Description. - // * Throws on error. - // * Returns a reference to the same object for supporting chaining. - // */ - // removeAction(name: string): ExposedThing; - - // /** - // * Adds an event with name defined by the name argument and qualifiers and initialization value provided by the event argument of type EventFragmentto the Thing object and updates the Thing Description. - // * Throws on error. - // * Returns a reference to the same object for supporting chaining. - // */ - // addEvent(name: string, event: EventFragment): ExposedThing; - - // /** - // * Removes the event specified by the name argument and updates the Thing Description. - // * Returns a reference to the same object for supporting chaining. - // */ - // removeEvent(name: string): ExposedThing; - - // define request handlers - /** * Takes name as string argument and handler as argument of type PropertyReadHandler. * Sets the handler function for reading the specified Property matched by name. @@ -332,163 +152,8 @@ export interface ExposedThing extends ConsumedThing { emitEvent(name: string, data: any): void; } -// TODO: Decide if decorator (with 'internal') or replacement (without 'internal') for get() -// For now decorator in node-wot export declare type PropertyReadHandler = (internal?: any, options?: any) => Promise; -// TODO: Decide if decorator (return any) or replacement (return void) for set() -// For now decorator in node-wot export declare type PropertyWriteHandler = (value: any, options?: any) => Promise; export declare type ActionHandler = (parameters: any, options?: any) => Promise; - -// export interface Link { -// href: string; -// rel?: string | Array; -// type?: string; // media type hint, no media type parameters -// anchor?: string; -// } - -// export interface ExpectedResponse { -// contentType?: string; -// } - -// export interface Form { -// href: string; -// subprotocol?: string; -// op?: string | Array; -// contentType?: string; // media type + parameter(s), e.g., text/plain;charset=utf8 -// security?: Array; // Set of security definition names, chosen from those defined in securityDefinitions // Security; -// scopes?: Array; -// response?: ExpectedResponse; -// } - -// export declare type MultiLanguage = any; // object? - -// export type DataSchema = BooleanSchema | IntegerSchema | NumberSchema | StringSchema | ObjectSchema | ArraySchema | NullSchema; - -// export interface BaseSchema { -// type?: string; -// title?: string; -// titles?: MultiLanguage; -// description?: string; -// descriptions?: MultiLanguage; -// writeOnly?: boolean; -// readOnly?: boolean; -// oneOf?: Array; -// unit?: string; -// const?: any; -// enum?: Array; -// } - -// export interface BooleanSchema extends BaseSchema { -// type: "boolean"; -// } - -// export interface IntegerSchema extends BaseSchema { -// type: "integer"; -// minimum?: number; -// maximum?: number; -// } - -// export interface NumberSchema extends BaseSchema { -// type: "number"; -// minimum?: number; -// maximum?: number; -// } - -// export interface StringSchema extends BaseSchema { -// type: "string"; -// } - -// export interface ObjectSchema extends BaseSchema { -// type: "object"; -// properties: { [key: string]: DataSchema }; -// required?: Array; -// } - -// export interface ArraySchema extends BaseSchema { -// type: "array"; -// items: DataSchema; -// minItems?: number; -// maxItems?: number; -// } - -// export interface NullSchema extends BaseSchema { -// type: "null"; -// } - -// export type Security = NoSecurityScheme | BasicSecurityScheme | DigestSecurityScheme | BearerSecurityScheme | CertSecurityScheme | PoPSecurityScheme | APIKeySecurityScheme | OAuth2SecurityScheme | PSKSecurityScheme | PublicSecurityScheme; - - -// export interface SecurityScheme { -// scheme: string; -// description?: string; -// proxy?: string; -// } - -// export interface NoSecurityScheme extends SecurityScheme { -// scheme: "nosec"; -// } - -// export interface BasicSecurityScheme extends SecurityScheme { -// scheme: "basic"; -// in?: string; -// name?: string; -// } - -// export interface DigestSecurityScheme extends SecurityScheme { -// scheme: "digest"; -// name?: string; -// in?: string; -// qop?: string; -// } - -// export interface APIKeySecurityScheme extends SecurityScheme { -// scheme: "apikey"; -// in?: string; -// name?: string; -// } - -// export interface BearerSecurityScheme extends SecurityScheme { -// scheme: "bearer"; -// in?: string; -// alg?: string; -// format?: string; -// name?: string; -// authorization?: string; -// } - -// export interface CertSecurityScheme extends SecurityScheme { -// scheme: "cert"; -// identity?: string; -// } - -// export interface PSKSecurityScheme extends SecurityScheme { -// scheme: "psk"; -// identity?: string; -// } - -// export interface PublicSecurityScheme extends SecurityScheme { -// scheme: "public"; -// identity?: string; -// } - -// export interface PoPSecurityScheme extends SecurityScheme { -// scheme: "pop"; -// format?: string; -// authorization?: string; -// alg?: string; -// name?: string; -// in?: string; -// } - -// export interface OAuth2SecurityScheme extends SecurityScheme { -// scheme: "oauth2"; -// authorization?: string; -// flow?: string; // one of implicit, password, client, or code -// token?: string; -// refresh?: string; -// scopes?: Array; -// } - diff --git a/typescript/package.json b/typescript/package.json index 5f14d267..f80b69b0 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.7.0-NEXT-SNAPSHOT.12", + "version": "0.7.0-NEXT-SNAPSHOT.13", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From c5f886011d00c2d9cca85d088b611805fe07f3ab Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Tue, 27 Aug 2019 10:13:30 +0200 Subject: [PATCH 347/464] fix: readAllProperties() returns PropertyValueMap also --- typescript/index.d.ts | 2 +- typescript/package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index 8a832581..524f4ceb 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -86,7 +86,7 @@ export declare type ThingDescription = object | { [key: string]: any; }; */ export interface ConsumedThing { readProperty(propertyName: string, options?: InteractionOptions): Promise; - readAllProperties(options?: InteractionOptions): Promise; + readAllProperties(options?: InteractionOptions): Promise; readMultipleProperties(propertyNames: string[], options?: InteractionOptions): Promise; writeProperty(propertyName: string, value: any, options?: InteractionOptions): Promise; writeMultipleProperties(valueMap: PropertyValueMap, options?: InteractionOptions): Promise; diff --git a/typescript/package.json b/typescript/package.json index f80b69b0..07b33b9d 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.7.0-NEXT-SNAPSHOT.13", + "version": "0.7.0-NEXT-SNAPSHOT.14", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From e9edde4e50f65557f38a476fd6c9386f0bbca762 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Tue, 27 Aug 2019 14:19:54 +0300 Subject: [PATCH 348/464] Consistently use PropertyMap for Property interactions Signed-off-by: Zoltan Kis --- index.html | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/index.html b/index.html index d72c3ebc..537633d5 100644 --- a/index.html +++ b/index.html @@ -495,10 +495,10 @@

                                The ConsumedThing interface

                                DOMString propertyName, optional InteractionOptions options = null ); - Promise<object> readAllProperties( + Promise<PropertyMap> readAllProperties( optional InteractionOptions options = null ); - Promise<object> readMultipleProperties( + Promise<PropertyMap> readMultipleProperties( sequence<DOMString> propertyNames, optional InteractionOptions options = null ); @@ -508,7 +508,7 @@

                                The ConsumedThing interface

                                optional InteractionOptions options = null ); Promise<void> writeMultipleProperties( - PropertyValueMap valueMap, + PropertyMap valueMap, optional InteractionOptions options = null ); Promise<any> invokeAction( @@ -533,7 +533,7 @@

                                The ConsumedThing interface

                                dictionary InteractionOptions { object uriVariables; }; - typedef object PropertyValueMap; + typedef object PropertyMap; callback WotListener = void(any data); @@ -583,7 +583,7 @@

                                The InteractionOptions dictionary

                                -

                                The PropertyValueMap type

                                +

                                The PropertyMap type

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

                                From e1ebe86c55227a5b1692e5b86e3e73f2aadbb7a5 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 9 Sep 2019 11:13:43 +0300 Subject: [PATCH 349/464] Add InteractionOptions parameters to handlers. Update Web IDL constructors. Signed-off-by: Zoltan Kis --- index.html | 74 ++++++++++++++++++++++++------------------------------ 1 file changed, 33 insertions(+), 41 deletions(-) diff --git a/index.html b/index.html index 537633d5..226fa770 100644 --- a/index.html +++ b/index.html @@ -489,44 +489,30 @@

                                The ConsumedThing interface

                                WoT Consumer conformance class. 

                                -      [Constructor(ThingDescription td), SecureContext, Exposed=(Window,Worker)]
+      [SecureContext, Exposed=(Window,Worker)]
       interface ConsumedThing {
-        Promise<any> readProperty(
-            DOMString propertyName,
-            optional InteractionOptions options = null
-        );
-        Promise<PropertyMap> readAllProperties(
-            optional InteractionOptions options = null
-        );
+        constructor(ThingDescription td);
+        Promise<any> readProperty(DOMString propertyName,
+                                  optional InteractionOptions options = null);
+        Promise<PropertyMap> readAllProperties(optional InteractionOptions options = null);
         Promise<PropertyMap> readMultipleProperties(
-            sequence<DOMString> propertyNames,
-            optional InteractionOptions options = null
-        );
-        Promise<void> writeProperty(
-            DOMString propertyName,
-            any value,
-            optional InteractionOptions options = null
-        );
-        Promise<void> writeMultipleProperties(
-            PropertyMap valueMap,
-            optional InteractionOptions options = null
-        );
-        Promise<any> invokeAction(
-            DOMString actionName,
-            optional any params = null,
-            optional InteractionOptions options = null
-        );
-        Promise<DOMString> observeProperty(
-            DOMString name,
-            WotListener listener,
-            optional InteractionOptions options = null
-        );
+                                  sequence<DOMString> propertyNames,
+                                  optional InteractionOptions options = null);
+        Promise<void> writeProperty(DOMString propertyName,
+                                    any value,
+                                    optional InteractionOptions options = null);
+        Promise<void> writeMultipleProperties(PropertyMap valueMap,
+                                    optional InteractionOptions options = null);
+        Promise<any> invokeAction(DOMString actionName,
+                                    optional any params = null,
+                                    optional InteractionOptions options = null);
+        Promise<DOMString> observeProperty(DOMString name,
+                                    WotListener listener,
+                                    optional InteractionOptions options = null);
         Promise<void> unobserveProperty(DOMString subscriptionId);
-        Promise<DOMString> subscribeEvent(
-            DOMString name,
-            WotListener listener,
-            optional InteractionOptions options = null
-        );
+        Promise<DOMString> subscribeEvent(DOMString name,
+                                    WotListener listener,
+                                    optional InteractionOptions options = null);
         Promise<void> unsubscribeEvent(DOMString subscriptionId);
         ThingDescription getThingDescription();
       };
@@ -962,16 +948,21 @@ 
                                The ExposedThing interface
                                
     
                                       [SecureContext, Exposed=(Window,Worker)]
       interface ExposedThing: ConsumedThing {
-        ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
-        ExposedThing setPropertyWriteHandler(DOMString name, PropertyWriteHandler writeHandler);
+        ExposedThing setPropertyReadHandler(DOMString name,
+                PropertyReadHandler readHandler);
+        ExposedThing setPropertyWriteHandler(DOMString name,
+                PropertyWriteHandler writeHandler);
         ExposedThing setActionHandler(DOMString name, ActionHandler action);
         void emitEvent(DOMString name, any data);
         Promise<void> expose();
         Promise<void> destroy();
       };
-      callback PropertyReadHandler = Promise<any>();
-      callback PropertyWriteHandler = Promise<void>(any value);
-      callback ActionHandler = Promise<any>(any parameters);
+      callback PropertyReadHandler = Promise<any>(
+              optional InteractionOptions options = null);
+      callback PropertyWriteHandler = Promise<void>(any value,
+              optional InteractionOptions options = null);
+      callback ActionHandler = Promise<any>(any parameters,
+              optional InteractionOptions options = null);
     
                                
 
     
                                
@@ -1354,8 +1345,9 @@ 
                                The ThingDiscovery interface
                                
       The ThingDiscovery object is constructed given a filter and provides the properties and methods controlling the discovery process.
     
                                
     
                                -      [Constructor(optional ThingFilter filter = null), SecureContext, Exposed=(Window,Worker)]
+      [SecureContext, Exposed=(Window,Worker)]
       interface ThingDiscovery {
+        constructor(optional ThingFilter filter = null);
         readonly attribute ThingFilter? filter;
         readonly attribute boolean active;
         readonly attribute boolean done;

From 2992fbfe0f19a0fa0d448c2b3b6aecc58e971b55 Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Mon, 9 Sep 2019 15:17:36 +0300
Subject: [PATCH 350/464] Align params name between invokeAction and
 ActionHandler

Signed-off-by: Zoltan Kis 
---
 index.html | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/index.html b/index.html
index 226fa770..7cdae8a4 100644
--- a/index.html
+++ b/index.html
@@ -818,7 +818,7 @@ 
                                The unobserveProperty() method
                                
     
                                
       
                                The invokeAction() method
                                
       
                                
-        Makes a request for invoking an Action and return the result. Takes a string argument actionName, an optional argument parameters of type any and an optional InteractionOptions options argument. It returns the result of the Action or an error. The method MUST run the following steps:
+        Makes a request for invoking an Action and return the result. Takes a string argument actionName, an optional argument params of type any and an optional InteractionOptions options argument. It returns the result of the Action or an error. The method MUST run the following steps:
         
                                  
           
                                1. 
             Return a Promise promise and execute the next steps in parallel.
@@ -961,7 +961,7 @@ 
                                  The ExposedThing interface
                                  
               optional InteractionOptions options = null);
       callback PropertyWriteHandler = Promise<void>(any value,
               optional InteractionOptions options = null);
-      callback ActionHandler = Promise<any>(any parameters,
+      callback ActionHandler = Promise<any>(any params,
               optional InteractionOptions options = null);
     
                                
 
@@ -1126,7 +1126,11 @@ 
                                The PropertyWriteHandler callback
                                
     
                                
       
                                The ActionHandler callback
                                
       
                                
-        A function that is called when an external request for invoking an Action is received and defines what to do with such requests. It expects a parameters dictionary argument compiled by the implementation (based on the Thing Description and the external client request). It returns a Promise that rejects with an error or resolves if the action is successful.
+        A function that is called when an external request for invoking an
+        Action is received and defines what to do with such requests.
+        It is invoked with a params dictionary argument.
+        It returns a Promise that rejects with an error or resolves if
+        the action is successful.
       
                                
     
                                
 

From a1b68fba2f7ec4dff881e9f00102dc115f431ea5 Mon Sep 17 00:00:00 2001
From: danielpeintner 
Date: Mon, 9 Sep 2019 15:02:17 +0200
Subject: [PATCH 351/464] feat: align with WebIDL changes

* add InteractionOptions
---
 typescript/index.d.ts   | 8 ++++----
 typescript/package.json | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/typescript/index.d.ts b/typescript/index.d.ts
index 524f4ceb..25016220 100644
--- a/typescript/index.d.ts
+++ b/typescript/index.d.ts
@@ -91,7 +91,7 @@ export interface ConsumedThing {
     writeProperty(propertyName: string, value: any, options?: InteractionOptions): Promise;
     writeMultipleProperties(valueMap: PropertyValueMap, options?: InteractionOptions): Promise;
 
-    invokeAction(actionName: string, parameter?: any, options?: InteractionOptions): Promise;
+    invokeAction(actionName: string, params?: any, options?: InteractionOptions): Promise;
 
     observeProperty(name: string, listener: WotListener, options?: InteractionOptions): Promise;
     unobserveProperty(subscriptionId: string): Promise;
@@ -152,8 +152,8 @@ export interface ExposedThing extends ConsumedThing {
     emitEvent(name: string, data: any): void;
 }
 
-export declare type PropertyReadHandler = (internal?: any, options?: any) => Promise;
+export declare type PropertyReadHandler = (options?: InteractionOptions) => Promise;
 
-export declare type PropertyWriteHandler = (value: any, options?: any) => Promise;
+export declare type PropertyWriteHandler = (value: any, options?: InteractionOptions) => Promise;
 
-export declare type ActionHandler = (parameters: any, options?: any) => Promise;
+export declare type ActionHandler = (params: any, options?: InteractionOptions) => Promise;
diff --git a/typescript/package.json b/typescript/package.json
index 07b33b9d..b80671e0 100644
--- a/typescript/package.json
+++ b/typescript/package.json
@@ -1,6 +1,6 @@
 {
   "name": "wot-typescript-definitions",
-  "version": "0.7.0-NEXT-SNAPSHOT.14",
+  "version": "0.7.0-NEXT-SNAPSHOT.15",
   "description": "TypeScript definitions for the W3C WoT Scripting API",
   "author": "W3C Web of Things Working Group",
   "license": "W3C-20150513",

From c9203ae108daaf8ef5ed62761b7ef55b8cd01f5d Mon Sep 17 00:00:00 2001
From: danielpeintner 
Date: Wed, 11 Sep 2019 10:01:28 +0200
Subject: [PATCH 352/464] add pr-preview

---
 .pr-preview.json | 4 ++++
 1 file changed, 4 insertions(+)
 create mode 100644 .pr-preview.json

diff --git a/.pr-preview.json b/.pr-preview.json
new file mode 100644
index 00000000..010969ea
--- /dev/null
+++ b/.pr-preview.json
@@ -0,0 +1,4 @@
+{
+    "src_file": "index.html",
+    "type": "respec"
+    }

From f2af6d562bf1d885da534fb1be385b234e77504f Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Wed, 11 Sep 2019 15:18:36 +0300
Subject: [PATCH 353/464] Revert subscription ID change, see #183

Signed-off-by: Zoltan Kis 
---
 index.html | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/index.html b/index.html
index 7cdae8a4..8a77fcb6 100644
--- a/index.html
+++ b/index.html
@@ -506,14 +506,14 @@ 
                                The ConsumedThing interface
                                
         Promise<any> invokeAction(DOMString actionName,
                                     optional any params = null,
                                     optional InteractionOptions options = null);
-        Promise<DOMString> observeProperty(DOMString name,
+        Promise<void> observeProperty(DOMString name,
                                     WotListener listener,
                                     optional InteractionOptions options = null);
-        Promise<void> unobserveProperty(DOMString subscriptionId);
-        Promise<DOMString> subscribeEvent(DOMString name,
+        Promise<void> unobserveProperty(DOMString name);
+        Promise<void> subscribeEvent(DOMString name,
                                     WotListener listener,
                                     optional InteractionOptions options = null);
-        Promise<void> unsubscribeEvent(DOMString subscriptionId);
+        Promise<void> unsubscribeEvent(DOMString name);
         ThingDescription getThingDescription();
       };
       dictionary InteractionOptions {
@@ -773,7 +773,7 @@ 
                                The observeProperty() method
                                
             If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps.
           
           
                              5. 
-            Otherwise let id be a string generated by the implementation to identify the subscription in a later unobserve request. Resolve promise with a id.
+            Otherwise resolve promise.
           
                                6. 
           
                              6. 
             Whenever the underlying platform receives a notification for this subscription with new Property value value, run
@@ -794,7 +794,8 @@ 
                                The observeProperty() method
                                
     
                                
       
                                The unobserveProperty() method
                                
       
                                
-        Makes a request for unsubscribing from Property value change notifications. Takes a string argument subscriptionId and returns success or failure. The method MUST run the following steps:
+        Makes a request for unsubscribing from Property value change notifications. Takes a string argument propertyName and
+        returns success or failure. The method MUST run the following steps:
         
                                  
           
                                1. 
             Return a Promise promise and execute the next steps in parallel.
@@ -803,7 +804,7 @@ 
                                  The unobserveProperty() method
                                  
             If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
           
                                  2. 
           
                                2. 
-            Make a request to the underlying platform (via the Protocol Bindings) to stop observing the Property identified by subscriptionId.
+            Make a request to the underlying platform (via the Protocol Bindings) to stop observing the Property identified by propertyName.
           
                                  3. 
           
                                3. 
             If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps.
@@ -866,7 +867,7 @@ 
                                  The subscribeEvent() method
                                  
             If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps.
           
                                  4. 
           
                                4. 
-            Otherwise let id be a string generated by the implementation to identify the subscription in a later unsubscribe request. Resolve promise.
+            Otherwise resolve promise.
           
                                  5. 
           
                                5. 
             Whenever the underlying platform receives a notification for this Event subscription, implementations SHOULD invoke
@@ -880,7 +881,7 @@ 
                                  The subscribeEvent() method
                                  
     
                                  
       
                                  The unsubscribeEvent() method
                                  
       
                                  
-        Makes a request for unsubscribing from Event notifications. Takes a string argument subscriptionId and returns success or failure. The method MUST run the following steps:
+        Makes a request for unsubscribing from Event notifications. Takes a string argument eventName and returns success or failure. The method MUST run the following steps:
         
                                    
           
                                  1. 
             Return a Promise promise and execute the next steps in parallel.
@@ -889,7 +890,7 @@ 
                                    The unsubscribeEvent() method
                                    
             If invoking this method is not allowed for the current scripting context for security reasons, reject promise with SecurityError and terminate these steps.
           
                                    2. 
           
                                  2. 
-            Make a request to the underlying platform (via the Protocol Bindings) to unsubscribe from the Event identified by subscriptionId.
+            Make a request to the underlying platform (via the Protocol Bindings) to unsubscribe from the Event identified by eventName.
           
                                    3. 
           
                                  3. 
             If the request fails, reject promise with the error received from the Protocol Bindings and terminate these steps.
@@ -1058,7 +1059,8 @@ 
                                    The PropertyReadHandler callback
                                    
         When a network request for observing a Property propertyName is received by the implementation, run the following steps:
         
                                      
           
                                    1. 
-            If a Property with propertyName does not exist, return ReferenceError in the reply and terminate these steps.
+            If a Property with propertyName does not exist, return an error in the reply (as defined in the
+            Thing Description) and terminate these steps.
           
                                      2. 
           
                                    2. 
             Save the request sender information to the Property's internal observer list in order to be able to notify about Property value changes.

From 8e21aa48be3b0504e193fe40a5f7b6ce68b3194e Mon Sep 17 00:00:00 2001
From: danielpeintner 
Date: Wed, 11 Sep 2019 15:00:55 +0200
Subject: [PATCH 354/464] fix: revert subscriptionID

---
 typescript/index.d.ts   | 8 ++++----
 typescript/package.json | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/typescript/index.d.ts b/typescript/index.d.ts
index 25016220..75c20ca0 100644
--- a/typescript/index.d.ts
+++ b/typescript/index.d.ts
@@ -93,11 +93,11 @@ export interface ConsumedThing {
 
     invokeAction(actionName: string, params?: any, options?: InteractionOptions): Promise;
 
-    observeProperty(name: string, listener: WotListener, options?: InteractionOptions): Promise;
-    unobserveProperty(subscriptionId: string): Promise;
+    observeProperty(name: string, listener: WotListener, options?: InteractionOptions): Promise;
+    unobserveProperty(name: string): Promise;
 
-    subscribeEvent(name: string, listener: WotListener, options?: InteractionOptions): Promise;
-    unsubscribeEvent(subscriptionId: string): Promise;
+    subscribeEvent(name: string, listener: WotListener, options?: InteractionOptions): Promise;
+    unsubscribeEvent(name: string): Promise;
 
     getThingDescription(): ThingDescription;
 }
diff --git a/typescript/package.json b/typescript/package.json
index b80671e0..bf3d7bc5 100644
--- a/typescript/package.json
+++ b/typescript/package.json
@@ -1,6 +1,6 @@
 {
   "name": "wot-typescript-definitions",
-  "version": "0.7.0-NEXT-SNAPSHOT.15",
+  "version": "0.7.0-NEXT-SNAPSHOT.16",
   "description": "TypeScript definitions for the W3C WoT Scripting API",
   "author": "W3C Web of Things Working Group",
   "license": "W3C-20150513",

From 8db2fa44067c22dd3abbb1c4f81b5e2925d3df7f Mon Sep 17 00:00:00 2001
From: Zoltan Kis 
Date: Fri, 27 Sep 2019 16:02:57 +0300
Subject: [PATCH 355/464] Editorial: fix HTML errors

Signed-off-by: Zoltan Kis 
---
 index.html | 158 +++++++++++++++++++++++++----------------------------
 1 file changed, 73 insertions(+), 85 deletions(-)

diff --git a/index.html b/index.html
index 8a77fcb6..6059e014 100644
--- a/index.html
+++ b/index.html
@@ -149,8 +149,8 @@
     
                                      
       By consuming a TD, a client Thing creates a local runtime resource model that allows accessing the Properties, Actions and Events exposed by the server Thing on a remote device.
     
                                      
-    
                                      
-      Exposing a Thing requires
+    
                                      
+      Exposing a Thing requires:
       
-
       This specification describes how to expose and consume Things by a script. Also, it defines a generic API for Thing discovery.
-    
                                      
+    
                                      
     
                                      
       Typically scripts are meant to be used on bridges or gateways that expose and control simpler devices as WoT Things and have means to handle (e.g. install, uninstall, update etc.) and run scripts.
     
                                      
@@ -208,11 +207,6 @@
       
                                    3. 
         Create a local Thing to be exposed, based on a Thing Description provided in string serialized format, or out of an existing Thing object.
       
                                      4. 
-
       
                                    4. Add a Property definition to the Thing.
                                      5. 
       
                                    5. Remove a Property definition from the Thing.
                                      6. 
       
                                    6. Add an Action definition to the Thing.
                                      7. 
@@ -222,14 +216,6 @@
       
                                    7. 
         Emit a WoT Event, i.e. notify all subscribed listeners.
       
                                      8. 
-
       
                                    8. Register service handlers for external requests:
         
                                        
           
                                      • to retrieve a Property value;
                                        • 
@@ -343,14 +329,14 @@ 
                                        The ThingDescription type
                                        
         [[WOT-TD]] for the properties that are not explicitly defined in a given
         TD.
       
                                        
-      
                                        
+      
                                        
         To expand a TD given td, run the following steps:
         
                                          
           
                                        1. 
             For each item in the TD default values table from [[!WOT-TD]], if the term is not defined in td, add the term definition with the default value specified in [[!WOT-TD]].
           
                                          2. 
         
                                        
-      
                                        
+      
                                        
     
                                  
 
     
                                   
                                  Validating a Thing Description
                                  
@@ -358,8 +344,9 @@ 
                                  The ThingDescription type
                                  
         The [[!WOT-TD]] specification defines how a TD should be validated.
         Therefore, this API expects the ThingDescription objects be validated before used as parameters. This specification defines a basic TD validation as follows.
       
                                  
-      
                                  
+      
                                  
         To validate a TD given td, run the following steps:
+        
                                    
           
                                  1. 
             If td is not an object, throw "TypeError"
             and terminate these steps.
@@ -374,12 +361,11 @@ 
                                    The ThingDescription type
                                    
             If JSON schema validation fails on td, throw "TypeError" and terminate these steps.
           
                                    2. 
         
                                  
-      
                                  
+      
                                  
     
                                  
   
                                
-
                                7. 
 
-
                                
+  
                                
   
                                The WoT API object
                                
   
                                
     Defines the API entry point exposed as a singleton and contains the API methods.
@@ -401,7 +387,7 @@ 
                                The WoT API object
                                
         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:
                                1. @@ -424,7 +410,7 @@

                                  The WoT API object

                                  Resolve promise with thing.
                                -

                                +

                                The produce() method

                                @@ -433,7 +419,7 @@

                                The WoT API object

                                Promise<ExposedThing> produce(ThingDescription td); }; -

                                +

                                Belongs to the WoT Producer conformance class. Expects a td 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 method MUST run the following steps:
                                1. @@ -449,7 +435,7 @@

                                  The WoT API object

                                  Resolve promise with thing.
                                -

                                +

                                The discover() method

                                @@ -458,7 +444,7 @@

                                The WoT API object

                                ThingDiscovery discover(optional ThingFilter filter = null); }; -

                                +

                                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. The method MUST run the following steps:
                                1. @@ -474,7 +460,7 @@

                                  The WoT API object

                                  Return discovery.
                                -

                                +

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

                                @@ -530,7 +516,7 @@

                                Constructing ConsumedThing

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

                                -

                                +

                                To create ConsumedThing with the ThingDescription td, run the following steps:
                                  @@ -547,7 +533,7 @@

                                  Constructing ConsumedThing

                                  Return thing.
                                -

                                +
                                @@ -580,7 +566,7 @@

                                The PropertyMap type

                                The readProperty() method

                                -

                                +

                                Reads a Property value. Takes a string argument propertyName and and an optional InteractionOptions options argument. It returns a Property value represented as any type. The method MUST run the following steps:
                                1. @@ -615,12 +601,12 @@

                                  The readProperty() method

                                  Otherwise resolve promise with value.
                                -

                                +

                                The readMultipleProperties() method

                                -

                                +

                                Reads multiple Property values with one or multiple requests. Takes the propertyNames argument as a sequence of strings and an optional InteractionOptions options argument. It returns an object with keys from propertyNames and values returned by this algorithm. The method MUST run the following steps:
                                1. @@ -648,12 +634,12 @@

                                  The readMultipleProperties() method

                                  Resolve promise with result.
                                -

                                +

                                The readAllProperties() method

                                -

                                +

                                Reads all properties of the Thing with one or multiple requests. Takes an optional InteractionOptions options argument. It returns an object with keys from Property names and values returned by this algorithm. The method MUST run the following steps:
                                1. @@ -681,12 +667,12 @@

                                  The readAllProperties() method

                                  Resolve promise with result.
                                -

                                +

                                The writeProperty() method

                                -

                                +

                                Writes a single Property. Takes a string argument propertyName, a value argument value and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps:
                                1. @@ -708,12 +694,12 @@

                                  The writeProperty() method

                                  Otherwise resolve promise.
                                -

                                +

                                The writeMultipleProperties() method

                                -

                                +

                                Writes a multiple Property values with one request. Takes a properties argument as an object with keys being Property names and values as Property values and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps:
                                1. @@ -738,7 +724,7 @@

                                  The writeMultipleProperties() method

                                  Otherwise resolve promise.
                                -

                                +
                                @@ -751,7 +737,7 @@

                                The WotListener callback

                                The observeProperty() method

                                -

                                +

                                Makes a request for Property value change notifications. Takes a string argument propertyName, a WotListener callback function listener and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps: @@ -788,12 +774,12 @@

                                The observeProperty() method

                                -

                                +

                                The unobserveProperty() method

                                -

                                +

                                Makes a request for unsubscribing from Property value change notifications. Takes a string argument propertyName and returns success or failure. The method MUST run the following steps:
                                  @@ -813,12 +799,12 @@

                                  The unobserveProperty() method

                                  Otherwise resolve promise.
                                -

                                +

                                The invokeAction() method

                                -

                                +

                                Makes a request for invoking an Action and return the result. Takes a string argument actionName, an optional argument params of type any and an optional InteractionOptions options argument. It returns the result of the Action or an error. The method MUST run the following steps:
                                1. @@ -840,12 +826,12 @@

                                  The invokeAction() method

                                  Reject promise with value.
                                -

                                +

                                The subscribeEvent() method

                                -

                                +

                                Makes a request for subscribing to Event notifications. Takes a string argument eventName, a WotListener callback function listener and an optional InteractionOptions options argument. It returns success or failure. The method MUST run the following steps: @@ -875,12 +861,12 @@

                                The subscribeEvent() method

                                as parameter. -

                                +

                                The unsubscribeEvent() method

                                -

                                +

                                Makes a request for unsubscribing from Event notifications. Takes a string argument eventName and returns success or failure. The method MUST run the following steps:
                                1. @@ -899,7 +885,7 @@

                                  The unsubscribeEvent() method

                                  Otherwise resolve promise.
                                -

                                +
                                @@ -980,7 +966,7 @@

                                Constructing ExposedThing

                                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 ThingDescription td, run the following steps:
                                  @@ -1000,7 +986,7 @@

                                  Constructing ExposedThing

                                  Return thing.
                                -

                                +

                                Methods inherited from ConsumedThing

                                @@ -1035,7 +1021,7 @@

                                The PropertyReadHandler callback

                                Handling Property read requests

                                -

                                +

                                When a network request for reading Property propertyName is received by the implementation, run the following steps:
                                1. @@ -1051,11 +1037,11 @@

                                  The PropertyReadHandler callback

                                  if there is no default handler defined by the implementation, return NotSupportedError with the reply and terminate these steps.
                                -

                                +

                                Handling Property observe requests

                                -

                                +

                                When a network request for observing a Property propertyName is received by the implementation, run the following steps:
                                1. @@ -1066,7 +1052,7 @@

                                  The PropertyReadHandler callback

                                  Save the request sender information to the Property's internal observer list in order to be able to notify about Property value changes.
                                -

                                +
                                @@ -1089,7 +1075,7 @@

                                The PropertyWriteHandler callback

                                Handling Property write requests

                                -

                                +

                                When a network request for writing a Property propertyName with a new value value is received, implementations SHOULD run the following update property steps, given propertyName, value and mode set to "single":
                                1. @@ -1107,13 +1093,14 @@

                                  The PropertyWriteHandler callback

                                2. For each item stored in the internal observer list of the Property with propertyName, send an observe reply with the new value attached.
                                  3. +
                              7. If there is no handler to handle the request, return NotSupportedError in the reply and terminate these steps.
                                8. -

                                -

                                +

                                > +
                                When a network request for writing multiple Properties given in an object propertyNames is received, run the following steps:
                                1. @@ -1122,7 +1109,8 @@

                                  The PropertyWriteHandler callback

                                2. Reply to the request (by sending a single or multiple replies) according to the Protocol Bindings defined for the Property.
                                  3. -

                                  +
                                +
                                @@ -1149,7 +1137,7 @@

                                The ActionHandler callback

                                Handling Action requests

                                -

                                +

                                When a network request for invoking the Action identified by name is received, the runtime SHOULD execute the following steps:
                                1. @@ -1162,11 +1150,11 @@

                                  The ActionHandler callback

                                  Otherwise return NotSupportedError with the reply and terminate these steps.
                                -

                                +

                                The emitEvent() method

                                -

                                +

                                Takes name as string argument denoting an Event name, and a data argument of any type. The method MUST run the following steps:
                                1. @@ -1179,11 +1167,11 @@

                                  The ActionHandler callback

                                  Make a request to the underlying platform to send an Event with data attached as property, using the Protocol Bindings, then terminate these steps.
                                -

                                +

                                The expose() method

                                -

                                +

                                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:
                                1. @@ -1216,11 +1204,11 @@

                                  The ActionHandler callback

                                  Otherwise resolve promise and terminate these steps.
                                -

                                +

                                The destroy() method

                                -

                                +

                                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:
                                1. @@ -1239,7 +1227,7 @@

                                  The ActionHandler callback

                                  Otherwise resolve promise and terminate these steps.
                                -

                                +
                                @@ -1383,7 +1371,7 @@

                                The ThingDiscovery interface

                                Constructing ThingDiscovery

                                -

                                +

                                To create ThingDiscovery with the ThingFilter filter, run the following steps:
                                  @@ -1404,7 +1392,7 @@

                                  The ThingDiscovery interface

                                  Return discovery.
                                -

                                +

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

                                @@ -1464,7 +1452,7 @@

                                The ThingFilter dictionary

                                The start() method

                                -

                                +

                                Starts the discovery process. The method MUST run the following steps:
                                1. @@ -1545,12 +1533,12 @@

                                  The start() method

                                  When the underlying platform reports the discovery process has completed, set this.active to false.
                                -

                                +

                                The next() method

                                -

                                +

                                Provides the next discovered ThingDescription object. The method MUST run the following steps:
                                1. @@ -1569,12 +1557,12 @@

                                  The next() method

                                  Resolve promise with td and terminate these steps.
                                -

                                +

                                The stop() method

                                -

                                +

                                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 inactive. The method MUST run the following steps:
                                1. @@ -1584,7 +1572,7 @@

                                  The stop() method

                                  Set this.active to false.
                                -

                                +
                                @@ -1658,7 +1646,7 @@

                                Discovery Examples

                                Following these practices does not guarantee security, but it might help avoid common known vulnerabilities.

                                -

                                +

                                The WoT security risks and possible mitigations are concerning the following groups:
                                • @@ -1679,7 +1667,7 @@

                                  Discovery Examples

                                  informative recommendations concerning security.
                                -

                                +

                                Scripting Runtime Security and Privacy Risks

                                @@ -1992,7 +1980,7 @@

                                API design rationale

                                Using Events

                                -

                                +

                                This API ended up not using software events at all, for the following reasons:
                                  @@ -2006,7 +1994,7 @@

                                  API design rationale

                                  Observing Property changes and handling WoT Events is done with the solution above.
                                -

                                +

                                Polymorphic functions

                                @@ -2016,7 +2004,7 @@

                                API design rationale

                                Changes

                                -

                                +

                                The following is a list of major changes to the document. Major versions of this specification are the following:
                                • @@ -2055,16 +2043,15 @@

                                  API design rationale

                                -

                                +

                                For a complete list of changes, see the github change log. You can also view the recently closed issues.

                                Open issues

                                -

                                +

                                The following problems are being discussed and need most attention: -

                                • Script management and runtime related issues (https://github.com/w3c/wot-scripting-api/issues/) @@ -2073,6 +2060,7 @@

                                  API design rationale

                                  An explicit API for adding and removing Property, Action and Event definitions on ExposedThing (it was present in earlier versions, but removed for complexity and a simpler way to do it.
                                +

                                Full Web IDL

                                From cd2f8d797278e00ab3c26cf8d6e6bc3654085a32 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 2 Oct 2019 13:17:19 +0300 Subject: [PATCH 356/464] Release WD4 Signed-off-by: Zoltan Kis --- releases/wd4/Overview.html | 6136 ++++++++++ releases/wd4/README.md | 15 + releases/wd4/diff.html | 22501 +++++++++++++++++++++++++++++++++++ releases/wd4/manifest.txt | 2 + 4 files changed, 28654 insertions(+) create mode 100644 releases/wd4/Overview.html create mode 100644 releases/wd4/README.md create mode 100644 releases/wd4/diff.html create mode 100644 releases/wd4/manifest.txt diff --git a/releases/wd4/Overview.html b/releases/wd4/Overview.html new file mode 100644 index 00000000..81dcda3d --- /dev/null +++ b/releases/wd4/Overview.html @@ -0,0 +1,6136 @@ + + + + + + + + + + + + +Web of Things (WoT) Scripting API + + + + + + + + + + + + + + + + + + +
                                +

                                Web of Things (WoT) Scripting +API

                                +

                                W3C Editor's Draft

                                +
                                +
                                This version:
                                +
                                https://w3c.github.io/wot-scripting-api/
                                +
                                Latest published version:
                                +
                                https://www.w3.org/TR/wot-scripting-api/
                                +
                                Latest editor's draft:
                                +
                                https://w3c.github.io/wot-scripting-api/
                                +
                                Editors:
                                +
                                Zoltan +Kis (Intel)
                                +
                                Daniel +Peintner (Siemens AG)
                                +
                                Johannes +Hund (Former Editor, when at Siemens AG)
                                +
                                Kazuaki +Nimura (Former Editor, at Fujitsu Ltd.)
                                +
                                Repository:
                                +
                                On +GitHub
                                +
                                File +a bug
                                +
                                Contributors:
                                +
                                Contributors +on GitHub
                                +
                                +

                                Copyright +© 2017-2019 W3C® (MIT, ERCIM, +Keio, Beihang). W3C liability, +trademark +and +permissive document license rules apply.

                                +
                                +
                                +

                                Abstract

                                +

                                The main Web of Things (WoT) concepts are described +in the WoT +Architecture document. The Web of Things is made of entities +(Things) that can describe their capabilities in a +machine-interpretable 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).

                                +

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

                                +

                                This specification describes a programming interface +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 specification deliberately follows the WoT Thing Description +specification closely. It is possible to implement simpler APIs +on top of this API, or implementing directly the WoT network facing +interface (i.e. the WoT Interface).

                                +
                                +
                                Editor's note
                                +

                                This specification is implemented at least by the +Thingweb project also known +as node-wot, which +is considered the reference open source implementation at the +moment. Check its source code, +including examples. Other, +closed source implementations have been made by WG member companies +and tested against node-wot in +plug-fests.

                                +
                                +
                                +
                                +

                                Status of This Document

                                +

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

                                +

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

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

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

                                +
                                +

                                This document was published by the Web of Things Working Group as an +Editor's Draft.

                                +

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

                                +

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

                                +

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

                                +

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

                                +
                                + +
                                +

                                1. +Introduction

                                +

                                WoT provides layered interoperability based on how Things +are used: "consumed" and "exposed", as defined +in [WOT-ARCHITECTURE].

                                +

                                By consuming a TD, a client Thing creates a local +runtime resource model that allows accessing the Properties, Actions and Events exposed by the server +Thing on a remote device.

                                +
                                +

                                Exposing a Thing requires:

                                + +This specification describes how to expose and consume Things +by a script. Also, it defines a generic API for Thing +discovery.
                                +
                                +
                                Note
                                +

                                Typically scripts are meant to be used on bridges or +gateways that expose and control simpler devices as WoT Things +and have means to handle (e.g. install, uninstall, update etc.) and +run scripts.

                                +
                                +
                                +
                                Note
                                +

                                This specification does not make assumptions on how the +WoT Runtime handles and runs scripts, including single or +multiple tenancy, script deployment and lifecycle management. The +API already supports the generic mechanisms that make it possible +to implement script management, for instance by exposing a manager +Thing whose Actions (action handlers) implement script +lifecycle management operations.

                                +
                                +
                                +
                                +

                                2. Use +Cases

                                +

                                This section is non-normative.

                                +

                                The following scripting use cases are supported in this +specification:

                                +
                                +

                                2.1 +Consuming a Thing

                                + +
                                +
                                +

                                2.2 +Exposing a Thing

                                +
                                  +
                                • Exposing the Thing includes generating the protocol +bindings in order to access lower level functionality.
                                  • +
                                • Create a local Thing to be exposed, based on a Thing Description provided in string serialized format, +or out of an existing Thing object.
                                  • +
                                • Add a Property definition to the Thing.
                                  • +
                                • Remove a Property definition from the Thing.
                                  • +
                                • Add an Action definition to the Thing.
                                  • +
                                • Remove an Action definition from the Thing.
                                  • +
                                • Add a WoT Event definition to the Thing.
                                  • +
                                • Remove a WoT Event definition from the Thing.
                                  • +
                                • Emit a WoT Event, i.e. notify all subscribed +listeners.
                                  • +
                                • Register service handlers for external requests: +
                                    +
                                  • to retrieve a Property value;
                                    • +
                                  • to update a Property value;
                                    • +
                                  • to invoke an Action: take the parameters from the +request, execute the defined action, and return the result;
                                    • +
                                  +
                                  • +
                                +
                                +
                                +

                                2.3 +Discovery

                                +
                                  +
                                • Discover Things in a network by sending a broadcast +request.
                                  • +
                                • Discover Things running in the local WoT +Runtime.
                                  • +
                                • Discover nearby Things, for instance connected by NFC or +Bluetooth.
                                  • +
                                • Discover Things by sending a discovery request to a +given registry.
                                  • +
                                • Discover Things filtered by filters defined on +Thing Descriptions
                                  • +
                                • Discover Things filtered by semantic queries.
                                  • +
                                • Stop or suppress an ongoing discovery process.
                                  • +
                                • Optionally specify a timeout to the discovery process after +which it is stopped/suppressed.
                                  • +
                                +
                                +
                                +
                                +

                                3. +Conformance

                                +

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

                                +

                                The key words MAY, MUST, and SHOULD in this +document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, +they appear in all capitals, as shown here.

                                +

                                This specification describes the conformance criteria for the +following classes of user agent (UA).

                                +

                                Due to requirements of small embedded implementations, splitting +WoT client and server interfaces was needed. Then, discovery is a +distributed application, but typical scenarios have been covered by +a generic discovery API in this specification. This resulted in +using 3 conformance classes for a UA that implements this API, +one for client, one for server, and one for discovery. An +application that uses this API can introspect for the presence of +the consume(), produce() and +discover() methods on the WoT +API object in order to determine which conformance class the +UA +implements.

                                +
                                +
                                WoT +Consumer UA
                                +
                                +

                                Implementations of this conformance class MUST implement the ConsumedThing interface and the +consume() method on the WoT API object.

                                +
                                +
                                WoT +Producer UA
                                +
                                +

                                Implementations of this conformance class MUST implement ExposedThing interface and the +produce() method on the WoT API object.

                                +
                                +
                                WoT +Discovery UA
                                +
                                +

                                Implementations of this conformance class MUST implement the ThingDiscovery interface and the +discover() method on the WoT API object.

                                +
                                +
                                +

                                These conformance classes MAY be implemented in a single UA.

                                +

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

                                +

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

                                +

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

                                +

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

                                +
                                +
                                +

                                4. +The ThingDescription +type

                                +
                                typedef object ThingDescription;
                                +

                                Represents a Thing Description (TD) as +defined in [WOT-TD]. It is expected to be a parsed JSON +object that is validated using +JSON schema validation.

                                +
                                +

                                4.1 Fetching a Thing Description

                                +

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

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

                                4.2 Expanding a Thing Description

                                +

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

                                +
                                +

                                To expand a +TD given td, run the following steps:

                                +
                                  +
                                1. For each item in the TD +default values table from [WOT-TD], if the term is not defined in td, add the +term definition with the default value specified in +[WOT-TD].
                                  2. +
                                +
                                +
                                +
                                +

                                4.3 Validating a Thing Description

                                +

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

                                +
                                +

                                To validate a +TD given td, run the following steps:

                                +
                                  +
                                1. If td is not an object, throw +"TypeError" and terminate these steps.
                                  2. +
                                2. If any of the mandatory properties defined in [WOT-TD] for Thing that +don't have default +definitions are missing from td, throw +"TypeError" and terminate these steps.
                                  3. +
                                3. If +JSON schema validation fails on td, throw +"TypeError" and terminate these steps.
                                  4. +
                                +
                                +
                                +
                                +
                                +

                                5. The +WoT API +object

                                +

                                Defines the API entry point exposed as a singleton and contains +the API methods.

                                +
                                +

                                5.1 The +WOT +interface

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

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

                                +
                                +
                                +
                                +

                                5.2 The +consume() +method

                                +
                                partial interface 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:

                                +
                                  +
                                1. Return a Promise +promise and execute the next steps in +parallel.
                                  2. +
                                2. If invoking this method is not allowed for the current +scripting context for security reasons, reject promise +with SecurityError and terminate these steps.
                                  3. +
                                3. Run the validate a TD steps on td. If +that throws, reject promise with the error and terminate +these steps.
                                  4. +
                                4. Let thing be a new ConsumedThing object constructed from +td.
                                  5. +
                                5. 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. The details are private to the +implementations and out of scope of this specification.
                                  6. +
                                6. Resolve promise with thing.
                                  7. +
                                +
                                +
                                +
                                +

                                5.3 The +produce() +method

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

                                Belongs to the WoT Producer conformance class. Expects a +td 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 method MUST run +the following steps:

                                +
                                  +
                                1. Return a Promise +promise and execute the next steps in +parallel.
                                  2. +
                                2. If invoking this method is not allowed for the current +scripting context for security reasons, reject promise +with SecurityError and terminate these steps.
                                  3. +
                                3. Let thing be a new ExposedThing object constructed with +td.
                                  4. +
                                4. Resolve promise with thing.
                                  5. +
                                +
                                +
                                +
                                +

                                5.4 The +discover() +method

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

                                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. The method MUST run the following steps:

                                +
                                  +
                                1. If invoking this method is not allowed for the current +scripting context for security reasons, throw +SecurityError and terminate these steps.
                                  2. +
                                2. Construct a ThingDiscovery object +discovery with filter.
                                  3. +
                                3. Invoke the discovery.start() +method.
                                  4. +
                                4. Return discovery.
                                  5. +
                                +
                                +

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

                                +
                                +
                                +
                                +

                                6. +The ConsumedThing interface

                                +

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

                                +
                                [SecureContext, Exposed=(Window,Worker)]
+interface ConsumedThing {
+  constructor(ThingDescription td);
+  Promise<any> readProperty(DOMString propertyName,
+                            optional InteractionOptions options = null);
+  Promise<PropertyMap> readAllProperties(optional InteractionOptions options = null);
+  Promise<PropertyMap> readMultipleProperties(
+                            sequence<DOMString> propertyNames,
+                            optional InteractionOptions options = null);
+  Promise<void> writeProperty(DOMString propertyName,
+                              any value,
+                              optional InteractionOptions options = null);
+  Promise<void> writeMultipleProperties(PropertyMap valueMap,
+                              optional InteractionOptions options = null);
+  Promise<any> invokeAction(DOMString actionName,
+                              optional any params = null,
+                              optional InteractionOptions options = null);
+  Promise<void> observeProperty(DOMString name,
+                              WotListener listener,
+                              optional InteractionOptions options = null);
+  Promise<void> unobserveProperty(DOMString name);
+  Promise<void> subscribeEvent(DOMString name,
+                              WotListener listener,
+                              optional InteractionOptions options = null);
+  Promise<void> unsubscribeEvent(DOMString name);
+  ThingDescription getThingDescription();
+};
+dictionary InteractionOptions {
+  object uriVariables;
+};
+typedef object PropertyMap;
+callback WotListener = void(any data);
                                +
                                +

                                6.1 Constructing ConsumedThing

                                +

                                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:

                                +
                                  +
                                1. Run the expand a TD steps on td. If +that fails, re-throw the error and terminate these steps.
                                  2. +
                                2. Let thing be a new ConsumedThing object.
                                  3. +
                                3. Let |td| be an internal slot of thing and +let td be its value.
                                  4. +
                                4. Return thing.
                                  5. +
                                +
                                +
                                +
                                +

                                6.2 The +getThingDescription() method

                                +

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

                                +
                                +
                                +

                                6.3 The InteractionOptions +dictionary

                                +

                                Holds the interaction options that need to be exposed for +application scripts according to the Thing Description. In this version of the specification +only URI template variables are used, represented as parsed JSON +objects defined in [WOT-TD].

                                +
                                +
                                Editor's note
                                +

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

                                +
                                +
                                +
                                +

                                6.4 The +PropertyMap type

                                +

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

                                +
                                +
                                Editor's note
                                +

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

                                +
                                +
                                +
                                +

                                6.5 +The +readProperty() method

                                +
                                +

                                Reads a Property value. Takes a string argument +propertyName and and an optional InteractionOptions options +argument. It returns a Property value represented +as any type. The method MUST run the following steps:

                                +
                                  +
                                1. Return a Promise +promise and execute the next steps in +parallel.
                                  2. +
                                2. If invoking this method is not allowed for the current +scripting context for security reasons, reject promise +with SecurityError and terminate these steps.
                                  3. +
                                3. Make a request to the underlying platform (via the Protocol Bindings) to retrieve the value of the Property given by propertyName with optional +URI templates given in options.uriVariables.
                                  4. +
                                4. If the request fails, reject promise with the error +received from the Protocol Bindings and +terminate these steps.
                                  5. +
                                5. Let value be the result of the request.
                                  6. +
                                6. Run the validate Property value +sub-steps on value: +
                                    +
                                  1. Based on the DataSchema +definition, value MUST be a JSON value and comply to the data schema +defined for the Property that is found in +this.getThingDescription().properties[propertyName].
                                    2. +
                                  2. If this fails, throw SyntaxError, otherwise return +value.
                                    3. +
                                  +
                                  7. +
                                7. If these above steps failed, reject promise with +SyntaxError and terminate these steps.
                                  8. +
                                8. Otherwise resolve promise with +value.
                                  9. +
                                +
                                +
                                +
                                +

                                6.6 The +readMultipleProperties() method

                                +
                                +

                                Reads multiple Property values with one or multiple +requests. Takes the propertyNames argument as a sequence +of strings and an optional InteractionOptions options +argument. It returns an object with keys from +propertyNames and values returned by this algorithm. The +method MUST run the following +steps:

                                +
                                  +
                                1. Return a Promise +promise and execute the next steps in +parallel.
                                  2. +
                                2. If invoking this method is not allowed for the current +scripting context for security reasons, reject promise +with SecurityError and terminate these steps.
                                  3. +
                                3. Let result be an object and for each string +name in propertyNames add a property with key +name and the value null.
                                  4. +
                                4. Make a request to the underlying platform (via the Protocol Bindings) to retrieve the Property values given by propertyNames with +optional URI templates given in +options.uriVariables.
                                  5. +
                                5. If this cannot be done with a single request with the Protocol Bindings of the Thing, then reject +promise with NotSupportedError and +terminate these steps.
                                  6. +
                                6. Process the reply and update all properties in +result with the values obtained in the reply.
                                  7. +
                                7. If the above step fails at any point, reject promise +with SyntaxError and terminate these steps.
                                  8. +
                                8. Resolve promise with result.
                                  9. +
                                +
                                +
                                +
                                +

                                6.7 The +readAllProperties() method

                                +
                                +

                                Reads all properties of the Thing with one or multiple +requests. Takes an optional InteractionOptions options +argument. It returns an object with keys from Property names and values returned by this algorithm. The +method MUST run the following +steps:

                                +
                                  +
                                1. Return a Promise +promise and execute the next steps in +parallel.
                                  2. +
                                2. If invoking this method is not allowed for the current +scripting context for security reasons, reject promise +with SecurityError and terminate these steps.
                                  3. +
                                3. Let result be an object and for each string +name in propertyNames add a property with key +name and the value null.
                                  4. +
                                4. Make a request to the underlying platform (via the Protocol Bindings) to retrieve the value of the all the +Property definitions from the TD with optional URI +templates given in options.uriVariables.
                                  5. +
                                5. If this cannot be done with a single request with the Protocol Bindings of the Thing, then reject +promise with NotSupportedError and +terminate these steps.
                                  6. +
                                6. If the request fails, reject promise with the error +received from the Protocol Bindings and +terminate these steps.
                                  7. +
                                7. Process the reply and update all properties in +result with the values obtained in the reply.
                                  8. +
                                8. Resolve promise with result.
                                  9. +
                                +
                                +
                                +
                                +

                                6.8 +The +writeProperty() method

                                +
                                +

                                Writes a single Property. Takes a string argument +propertyName, a value argument value and an +optional InteractionOptions +options argument. It returns success or failure. The +method MUST run the following +steps:

                                +
                                  +
                                1. Return a Promise +promise and execute the next steps in +parallel.
                                  2. +
                                2. If invoking this method is not allowed for the current +scripting context for security reasons, reject promise +with SecurityError and terminate these steps.
                                  3. +
                                3. Run the validate Property value +steps on value. If that fails, reject promise +with SyntaxError and terminate these steps.
                                  4. +
                                4. Make a request to the underlying platform (via the Protocol Bindings) to write value to the +Property given by propertyName with optional +URI templates given in options.uriVariables.
                                  5. +
                                5. If the request fails, reject promise with the error +received from the Protocol Bindings and +terminate these steps.
                                  6. +
                                6. Otherwise resolve promise.
                                  7. +
                                +
                                +
                                +
                                +

                                6.9 The +writeMultipleProperties() method

                                +
                                +

                                Writes a multiple Property values with one request. Takes a +properties argument as an object with keys being +Property names and values as Property values and an +optional InteractionOptions +options argument. It returns success or failure. The +method MUST run the following +steps:

                                +
                                  +
                                1. Return a Promise +promise and execute the next steps in +parallel.
                                  2. +
                                2. If invoking this method is not allowed for the current +scripting context for security reasons, reject promise +with SecurityError and terminate these steps.
                                  3. +
                                3. For each key name on properties, take its +value as value and run the validate Property value steps on value. If +that fails in for any name, reject promise +with SyntaxError and terminate these steps.
                                  4. +
                                4. Make a single request to the underlying platform (via the +Protocol Bindings) to write the each +Property provided in properties with optional +URI templates given in options.uriVariables.
                                  5. +
                                5. If this cannot be done with a single request with the Protocol Bindings of the Thing, then reject +promise with NotSupportedError and +terminate these steps.
                                  6. +
                                6. If the request fails, return the error received from the +Protocol Bindings and terminate these +steps.
                                  7. +
                                7. Otherwise resolve promise.
                                  8. +
                                +
                                +
                                +
                                +

                                6.10 The WotListener callback

                                +

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

                                +
                                +
                                +

                                6.11 The +observeProperty() method

                                +
                                +

                                Makes a request for Property value change +notifications. Takes a string argument propertyName, a +WotListener callback function +listener and an optional InteractionOptions options +argument. It returns success or failure. The method MUST run the following steps:

                                +
                                  +
                                1. Return a Promise +promise and execute the next steps in +parallel.
                                  2. +
                                2. If invoking this method is not allowed for the current +scripting context for security reasons, reject promise +with SecurityError and terminate these steps.
                                  3. +
                                3. If listener is not a function, reject +promise with "TypeError" and terminate +these steps.
                                  4. +
                                4. Make a request to the underlying platform (via the Protocol Bindings) to observe Property identified by +propertyName with optional URI templates given in +options.uriVariables.
                                  5. +
                                5. If the request fails, reject promise with the error +received from the Protocol Bindings and +terminate these steps.
                                  6. +
                                6. Otherwise resolve promise.
                                  7. +
                                7. Whenever the underlying platform receives a notification for +this subscription with new Property value +value, run the following sub-steps: +
                                    +
                                  • If running the validate Property value +steps on value fails, terminate these steps.
                                    • +
                                  • Invoke listener with value as +parameter.
                                    • +
                                  +
                                  8. +
                                +
                                +
                                +
                                +

                                6.12 The +unobserveProperty() method

                                +
                                +

                                Makes a request for unsubscribing from Property value change +notifications. Takes a string argument propertyName and +returns success or failure. The method MUST run the following steps:

                                +
                                  +
                                1. Return a Promise +promise and execute the next steps in +parallel.
                                  2. +
                                2. If invoking this method is not allowed for the current +scripting context for security reasons, reject promise +with SecurityError and terminate these steps.
                                  3. +
                                3. Make a request to the underlying platform (via the Protocol Bindings) to stop observing the Property identified by propertyName.
                                  4. +
                                4. If the request fails, reject promise with the error +received from the Protocol Bindings and +terminate these steps.
                                  5. +
                                5. Otherwise resolve promise.
                                  6. +
                                +
                                +
                                +
                                +

                                6.13 The +invokeAction() method

                                +
                                +

                                Makes a request for invoking an Action and return the +result. Takes a string argument actionName, an optional +argument params of type any and an optional +InteractionOptions +options argument. It returns the result of the Action +or an error. The method MUST +run the following steps:

                                +
                                  +
                                1. Return a Promise +promise and execute the next steps in +parallel.
                                  2. +
                                2. If invoking this method is not allowed for the current +scripting context for security reasons, reject promise +with SecurityError and terminate these steps.
                                  3. +
                                3. Make a request to the underlying platform (via the Protocol Bindings) to invoke the Action identified by +actionName with parameters provided in params +with optional URI templates given in +options.uriVariables.
                                  4. +
                                4. If the request fails locally or returns an error over the +network, reject promise with the error received from the +Protocol Bindings and terminate these +steps.
                                  5. +
                                5. Otherwise let value be the result returned in the +reply and run the validate Property value +steps on it. If that fails, reject promise with +SyntaxError and terminate these steps.
                                  6. +
                                6. Reject promise with value.
                                  7. +
                                +
                                +
                                +
                                +

                                6.14 The +subscribeEvent() method

                                +
                                +

                                Makes a request for subscribing to Event notifications. Takes a +string argument eventName, a WotListener callback function +listener and an optional InteractionOptions options +argument. It returns success or failure. The method MUST run the following steps:

                                +
                                  +
                                1. Return a Promise +promise and execute the next steps in +parallel.
                                  2. +
                                2. If invoking this method is not allowed for the current +scripting context for security reasons, reject promise +with SecurityError and terminate these steps.
                                  3. +
                                3. If listener is not a function, reject +promise with "TypeError" and terminate +these steps.
                                  4. +
                                4. Make a request to the underlying platform (via the Protocol Bindings) to subscribe to an Event +identified by eventNamewith optional URI templates given +in options.uriVariables.
                                  5. +
                                5. If the request fails, reject promise with the error +received from the Protocol Bindings and +terminate these steps.
                                  6. +
                                6. Otherwise resolve promise.
                                  7. +
                                7. Whenever the underlying platform receives a notification for +this Event subscription, implementations SHOULD invoke listener, giving the +data provided with the Event as parameter.
                                  8. +
                                +
                                +
                                +
                                +

                                6.15 The +unsubscribeEvent() method

                                +
                                +

                                Makes a request for unsubscribing from Event notifications. +Takes a string argument eventName and returns success or +failure. The method MUST run +the following steps:

                                +
                                  +
                                1. Return a Promise +promise and execute the next steps in +parallel.
                                  2. +
                                2. If invoking this method is not allowed for the current +scripting context for security reasons, reject promise +with SecurityError and terminate these steps.
                                  3. +
                                3. Make a request to the underlying platform (via the Protocol Bindings) to unsubscribe from the Event +identified by eventName.
                                  4. +
                                4. If the request fails, reject promise with the error +received from the Protocol Bindings and +terminate these steps.
                                  5. +
                                5. Otherwise resolve promise.
                                  6. +
                                +
                                +
                                +
                                +

                                6.16 +ConsumedThing Examples

                                +

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

                                +
                                +
                                Example +2: Thing Client API +example
                                +
                                try {
+  let res = await fetch("https://tds.mythings.org/sensor11");
+  let td = res.json();
+  let thing = new ConsumedThing(td);
+  console.log("Thing " + thing.getThingDescription().title + " consumed.");
+} catch(e) {
+  console.log("TD fetch error: " + e.message); },
+};
+try {
+  // subscribe to property change for “temperature”
+  await thing.observeProperty("temperature", value => {
+    console.log("Temperature changed to: " + value);
+  });
+  // subscribe to the “ready” event defined in the TD
+  await thing.subscribeEvent("ready", eventData => {
+    console.log("Ready; index: " + eventData);
+    // run the “startMeasurement” action defined by TD
+    await thing.invokeAction("startMeasurement", { units: "Celsius" });
+    console.log("Measurement started.");
+  });
+} catch(e) {
+  console.log("Error starting measurement.");
+}
+setTimeout( () => {
+  console.log(“Temperature: “ + await thing.readProperty(“temperature”));
+  await thing.unsubscribe(“ready”);
+  console.log("Unsubscribed from the ‘ready’ event.");
+},
+10000);
                                +
                                +
                                +
                                +

                                7. +The ExposedThing interface

                                +

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

                                +
                                [SecureContext, Exposed=(Window,Worker)]
+interface ExposedThing: ConsumedThing {
+  ExposedThing setPropertyReadHandler(DOMString name,
+          PropertyReadHandler readHandler);
+  ExposedThing setPropertyWriteHandler(DOMString name,
+          PropertyWriteHandler writeHandler);
+  ExposedThing setActionHandler(DOMString name, ActionHandler action);
+  void emitEvent(DOMString name, any data);
+  Promise<void> expose();
+  Promise<void> destroy();
+};
+callback PropertyReadHandler = Promise<any>(
+        optional InteractionOptions options = null);
+callback PropertyWriteHandler = Promise<void>(any value,
+        optional InteractionOptions options = null);
+callback ActionHandler = Promise<any>(any params,
+        optional InteractionOptions options = null);
                                +
                                +

                                7.1 Constructing ExposedThing

                                +

                                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 +ThingDescription td, run the +following steps:

                                +
                                  +
                                1. If invoking this method is not allowed for the current +scripting context for security reasons, throw +SecurityError and terminate these steps.
                                  2. +
                                2. Run the expand a TD steps on td. If +that fails, re-throw the error and terminate these steps.
                                  3. +
                                3. Let thing be a new ExposedThing object.
                                  4. +
                                4. Let |td| be an internal slot of thing and +let td be its value.
                                  5. +
                                5. Return thing.
                                  6. +
                                +
                                +
                                +
                                +

                                7.2 Methods inherited from ConsumedThing

                                +

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

                                +

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

                                +

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

                                +
                                +
                                +

                                7.3 The PropertyReadHandler +callback

                                +

                                A function that is called when an external request for reading a +Property is received and defines what to do with such +requests. It returns a Promise +and resolves it when the value of the Property matching the +name argument is obtained, or rejects with an error if +the property is not found or the value cannot be retrieved.

                                +
                                +
                                +

                                7.4 The +setPropertyReadHandler() method

                                +

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

                                +

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

                                +

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

                                +
                                +
                                +

                                7.5 Handling Property read +requests

                                +
                                +

                                When a network request for reading Property +propertyName is received by the implementation, run the +following steps:

                                +
                                  +
                                1. If a Property with propertyName does +not exist, return ReferenceError in the reply and +terminate these steps.
                                  2. +
                                2. If there is a user provided read handler registered with +setPropertyReadHandler(), invoke that wih +propertyName, return the value with the reply and +terminate these steps.
                                  3. +
                                3. Otherwise, if there is a default read handler provided by the +implementation, invoke it with propertyName, return the +value with the reply and terminate these steps.
                                  4. +
                                4. if there is no default handler defined by the implementation, +return NotSupportedError +with the reply and terminate these steps.
                                  5. +
                                +
                                +
                                +
                                +

                                7.6 Handling Property observe +requests

                                +
                                +

                                When a network request for observing a Property +propertyName is received by the implementation, run the +following steps:

                                +
                                  +
                                1. If a Property with propertyName does +not exist, return an error in the reply (as defined in the Thing Description) and terminate these steps.
                                  2. +
                                2. Save the request sender information to the Property's internal observer list in +order to be able to notify about Property value changes.
                                  3. +
                                +
                                +
                                +
                                +

                                7.7 The PropertyWriteHandler +callback

                                +

                                A function that is called when an external request for writing a +Property is received and defines what to do with such +requests. It expects the requested new value as +argument and returns a Promise +which is resolved when the value of the Property that matches +the name argument has been updated with +value, or rejects with an error if the property is not +found or the value cannot be updated.

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

                                +
                                +
                                +
                                +

                                7.8 The +setPropertyWriteHandler() method

                                +

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

                                +

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

                                +
                                +
                                +

                                7.9 Handling Property write +requests

                                +
                                +

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

                                +
                                  +
                                1. If a Property with propertyName does +not exist, return ReferenceError in the reply and +terminate these steps.
                                  2. +
                                2. If there is a user provided write handler registered with +setPropertyWriteHandler(), or if there is a default +write handler, +
                                    +
                                  1. Invoke the handler with propertyName. If it fails, +return the error in the reply and terminate these steps.
                                    2. +
                                  2. Otherwise, if mode is "single", reply +to the request with the new value, following to the Protocol Bindings.
                                    3. +
                                  3. For each item stored in the internal observer list of the Property with +propertyName, send an observe reply with the new value +attached.
                                    4. +
                                  +
                                  3. +
                                3. If there is no handler to handle the request, return +NotSupportedError +in the reply and terminate these steps.
                                  4. +
                                +
                                +
                                +

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

                                +
                                  +
                                1. For each property with key name and value +value defined in propertyNames, run the +update property steps with +name, value and mode set to +"multiple".
                                  2. +
                                2. Reply to the request (by sending a single or multiple replies) +according to the Protocol Bindings defined +for the Property.
                                  3. +
                                +
                                +
                                +
                                +

                                7.10 The ActionHandler callback

                                +

                                A function that is called when an external request for invoking +an Action is received and defines what to do with such +requests. It is invoked with a params dictionary +argument. It returns a Promise +that rejects with an error or resolves if the action is +successful.

                                +
                                +
                                +

                                7.11 The +setActionHandler() method

                                +

                                Takes name as string argument and +action as argument of type ActionHandler. Sets the handler function for +the specified Action matched by name. +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.

                                +
                                +
                                +

                                7.12 Handling Action requests

                                +
                                +

                                When a network request for invoking the Action identified by +name is received, the runtime SHOULD execute the following steps:

                                +
                                  +
                                1. If an Action identified by name does +not exist, return ReferenceError in the reply and +terminate these steps.
                                  2. +
                                2. If there is a user provided action handler registered with +setActionHandler(), invoke that wih name, +return the resulting value with the reply and terminate these +steps.
                                  3. +
                                3. Otherwise return NotSupportedError +with the reply and terminate these steps.
                                  4. +
                                +
                                +
                                +
                                +

                                7.13 +The +emitEvent() method

                                +
                                +

                                Takes name as string argument denoting an Event +name, and a data argument of any type. The +method MUST run the following +steps:

                                +
                                  +
                                1. If invoking this method is not allowed for the current +scripting context for security reasons, throw +SecurityError and terminate these steps.
                                  2. +
                                2. If an Event with the name name is not found in +this.getThingDescription().events, throw +NotFoundError and terminate these steps.
                                  3. +
                                3. Make a request to the underlying platform to send an Event +with data attached as property, using the Protocol Bindings, then terminate these steps.
                                  4. +
                                +
                                +
                                +
                                +

                                7.14 The +expose() +method

                                +
                                +

                                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:

                                +
                                  +
                                1. Return a Promise +promise and execute the next steps in +parallel.
                                  2. +
                                2. If invoking this method is not allowed for the current +scripting context for security reasons, reject promise +with SecurityError and terminate these steps.
                                  3. +
                                3. Run the expand a TD steps on the internal slot +|td|.
                                  4. +
                                4. Run the validate a TD on |td|. If that +fails, reject promise with "TypeError" and +terminate these steps.
                                  5. +
                                5. For each Property definition in +this.instance.properties initialize an +|internal +observer list| internal slot in order to store observe +request data needed to notify the observers on value changes.
                                  6. +
                                6. 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. The +details are private to the implementations and out of scope of this +specification.
                                  7. +
                                7. 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 +terminate these steps.
                                  8. +
                                8. Otherwise resolve promise and terminate these +steps.
                                  9. +
                                +
                                +
                                +
                                +

                                7.15 The + +destroy() method

                                +
                                +

                                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:

                                +
                                  +
                                1. Return a Promise +promise and execute the next steps in +parallel.
                                  2. +
                                2. If invoking this method is not allowed for the current +scripting context for security reasons, reject promise +with SecurityError and terminate these steps.
                                  3. +
                                3. Make a request to the underlying platform to stop serving +external requests for WoT Interactions, based on +the Protocol Bindings.
                                  4. +
                                4. 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 +terminate these steps.
                                  5. +
                                5. Otherwise resolve promise and terminate these +steps.
                                  6. +
                                +
                                +
                                +
                                +

                                7.16 +ExposedThing Examples

                                +

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

                                +
                                +
                                Example +3: 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 +4: 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);
+}
                                +
                                +
                                +
                                +

                                8. The ThingDiscovery +interface

                                +

                                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 ThingDiscovery object is +constructed given a filter and provides the properties and methods +controlling the discovery process.

                                +
                                [SecureContext, Exposed=(Window,Worker)]
+interface ThingDiscovery {
+  constructor(optional ThingFilter filter = null);
+  readonly attribute ThingFilter? filter;
+  readonly attribute boolean active;
+  readonly attribute boolean done;
+  readonly attribute Error? error;
+  void start();
+  Promise<ThingDescription> next();
+  void stop();
+};
                                +
                                +
                                Editor's note
                                +

                                The ThingDiscovery interface has +a next() method and a done property, but +it is not an Iterable. Look into Issue 177 +for rationale.

                                +
                                +

                                The discovery results internal slot is an +internal queue for temporarily storing the found ThingDescription objects until they are +consumed by the application using the next() method. Implementations MAY optimize the size of this queue +based on e.g. the available resources and the frequency of invoking +the next() method.

                                +

                                The filter +property represents the discovery filter of type ThingFilter specified for the discovery.

                                +

                                The active property +is true when the discovery is actively ongoing on +protocol level (i.e. new TDs may still arrive) and +false otherwise.

                                +

                                The done property is +true if the discovery has been completed with no more +results to report and discovery results is also +empty.

                                +

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

                                +
                                +

                                8.1 Constructing ThingDiscovery

                                +
                                +

                                To create ThingDiscovery with the +ThingFilter filter, run the +following steps:

                                +
                                  +
                                1. If filter is not an object or null, +throw "TypeError" and terminate these steps.
                                  2. +
                                2. Let discovery be a new ThingDiscovery object.
                                  3. +
                                3. Set the filter +property to filter.
                                  4. +
                                4. Set active and +done to false. +Set error to +null.
                                  5. +
                                5. Return discovery.
                                  6. +
                                +
                                +

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

                                +

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

                                +
                                +
                                +

                                8.2 The DiscoveryMethod +enumeration

                                +
                                typedef DOMString DiscoveryMethod;
                                +

                                Represents the discovery type to be used:

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

                                8.3 The ThingFilter dictionary

                                +

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

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

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

                                +

                                The url property represents additional +information for the discovery method, such as the URL of the target +entity serving the discovery request, for instance the URL of a +Thing Directory (if method is +"directory") or that of a Thing (otherwise).

                                +

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

                                +

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

                                +
                                +
                                +

                                8.4 The +start() +method

                                +
                                +

                                Starts the discovery process. The method MUST run the following steps:

                                +
                                  +
                                1. If invoking this method is not allowed for the current +scripting context for security reasons, set this.error +to SecurityError and terminate these steps.
                                  2. +
                                2. If discovery is not supported by the implementation, set +this.error to NotSupportedError and +terminate these steps.
                                  3. +
                                3. If this.filter is defined, +
                                    +
                                  • Let filter denote this.filter.
                                    • +
                                  • If filter.query is defined, pass it as an opaque +string to the underlying implementation to be matched against +discovered items. The underlying implementation is responsible to +parse it e.g. as a SPARQL or JSON query and match it against the +Thing Descriptions found during the +discovery process. If queries are not supported, set +this.error to NotSupportedError and +terminate these steps.
                                    • +
                                  +
                                  4. +
                                4. Create the discovery results internal slot for +storing discovered ThingDescription objects.
                                  5. +
                                5. Request the underlying platform to start the discovery process, +with the following parameters: +
                                    +
                                  • If filter.method is not defined or the value is +"any", use the widest discovery method supported by +the underlying platform.
                                    • +
                                  • Otherwise if filter.method is "local", +use the local Thing Directory for discovery. Usually +that defines Things deployed in the same device, or +connected to the device in slave mode (e.g. sensors connected via +Bluetooth or a serial connection).
                                    • +
                                  • Otherwise if filter.method is +"directory", use the remote Thing Directory specified in filter.url.
                                    • +
                                  • Otherwise if filter.method is +"multicast", use all the multicast discovery protocols +supported by the underlying platform.
                                    • +
                                  +
                                  6. +
                                6. When the underlying platform has started the discovery process, +set the active property to true.
                                  7. +
                                7. Whenever a new Thing Description +td is discovered by the underlying platform, run the +following sub-steps: +
                                    +
                                  1. Fetch +td as a JSON object json. If that fails, set +this.error to SyntaxError, discard +td and continue the discovery process.
                                    2. +
                                  2. If filter.query is defined, check if json +is a match for the query. The matching algorithm is encapsulated by +implementations. If that returns false, discard +td and continue the discovery process.
                                    3. +
                                  3. If filter.fragment is defined, for each property +defined in it, check if that property exists in +json.properties and has the same value. If this is +false in any checks, discard td and +continue the discovery process.
                                    4. +
                                  4. Otherwise add td to the discovery results.
                                    5. +
                                  5. At this point implementations MAY control the flow of the discovery process (depending +on memory constraints, for instance temporarily stop discovery if +the queue is getting too large, or resume discovery when the queue +is emptied sufficiently).
                                    6. +
                                  +
                                  8. +
                                8. Whenever an error occurs during the discovery process, +
                                    +
                                  1. Set this.error to a new Error object +error. Set error.name to +'DiscoveryError'.
                                    2. +
                                  2. If there was an error code or message provided by the Protocol Bindings, set error.message to that +value as string.
                                    3. +
                                  3. If the error is irrecoverable and discovery has been stopped by +the underlying platform, set this.active to +false.
                                    4. +
                                  +
                                  9. +
                                9. When the underlying platform reports the discovery process has +completed, set this.active to false.
                                  10. +
                                +
                                +
                                +
                                +

                                8.5 The +next() +method

                                +
                                +

                                Provides the next discovered ThingDescription object. The method +MUST run the following +steps:

                                +
                                  +
                                1. Return a Promise +promise and execute the next steps in +parallel.
                                  2. +
                                2. If this.active is true, wait until the +discovery results internal slot is not +empty.
                                  3. +
                                3. If discovery results is empty and +this.active is false, set +this.done to true and reject +promise.
                                  4. +
                                4. Remove the first ThingDescription object td from +discovery results.
                                  5. +
                                5. Resolve promise with td and terminate +these steps.
                                  6. +
                                +
                                +
                                +
                                +

                                8.6 The +stop() +method

                                +
                                +

                                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 inactive. The method MUST run the following steps:

                                +
                                  +
                                1. 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.
                                  2. +
                                2. Set this.active to false.
                                  3. +
                                +
                                +
                                +
                                +

                                8.7 +Discovery Examples

                                +

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

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

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

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

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

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

                                9. Security and +Privacy

                                +

                                A detailed discussion of security and privacy considerations for +the Web of Things, including a threat model that can be adapted to +various circumstances, is presented in the informative document +[WOT-SECURITY-GUIDELINES]. This section +discusses only security and privacy risks and possible mitigations +directly relevant to the scripts and WoT Scripting API.

                                +

                                A suggested set of best practices to improve security for WoT +devices and services has been documented in [WOT-SECURITY-BEST-PRACTICES]. That document may +be updated as security measures evolve. Following these practices +does not guarantee security, but it might help avoid common known +vulnerabilities.

                                +
                                +

                                The WoT security risks and possible mitigations are concerning +the following groups:

                                +
                                  +
                                • Implementors of WoT Runtimes that do not implement a Scripting +Runtime. The [WOT-ARCHITECTURE] document provides generic +security guidelines for this group.
                                  • +
                                • Implementors of the WoT Scripting API in a WoT Scripting +Runtime. This is the main scope and is covered in the Scripting Runtime Security +and Privacy Risks sub-section that contains normative text +regarding security.
                                  • +
                                • WoT script developers, covered in the Script Security and Privacy +Risks sub-section that contains informative recommendations +concerning security.
                                  • +
                                +
                                +
                                +

                                +9.1 Scripting Runtime Security and Privacy +Risks

                                +

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

                                +
                                +

                                +9.1.1 Corrupted Input Security and Privacy +Risk

                                +

                                A typical way to compromise any process is to send it a +corrupted input via one of the exposed interfaces. This can be done +to a script instance using WoT interface it exposes.

                                +
                                +
                                Mitigation:
                                +
                                Implementors of this API SHOULD perform validation on all script inputs. In +addition to input validation, fuzzing should be used +to verify that the input processing is done correctly. There are +many tools and techniques in existence to do such validation. More +details can be found in [WOT-SECURITY-TESTING].
                                +
                                +
                                +
                                +

                                +9.1.2 Physical Device Direct Access +Security and Privacy Risk

                                +

                                In case a script is compromised or misbehaving, the underlying +physical device (and potentially surrounded environment) can be +damaged if a script can use directly exposed native device +interfaces. If such interfaces lack safety checks on their inputs, +they might bring the underlying physical device (or environment) to +an unsafe state (i.e. device overheats and explodes).

                                +
                                +
                                Mitigation:
                                +
                                The WoT Scripting Runtime SHOULD avoid directly exposing the native device +interfaces to the script developers. Instead, a WoT Scripting +Runtime should provide a hardware abstraction layer for accessing +the native device interfaces. Such hardware abstraction layer +should refuse to execute commands that might put the device (or +environment) to an unsafe state. Additionally, in order to reduce +the damage to a physical WoT device in cases a script gets +compromised, it is important to minimize the number of interfaces +that are exposed or accessible to a particular script based on its +functionality.
                                +
                                +
                                +
                                +

                                9.1.3 Provisioning and Update Security Risk

                                +

                                If the WoT Scripting Runtime supports post-manufacturing +provisioning or updates of scripts, WoT Scripting Runtime or any +related data (including security credentials), it can be a major +attack vector. An attacker can try to modify any above described +element during the update or provisioning process or simply +provision attacker's code and data directly.

                                +
                                +
                                Mitigation:
                                +
                                Post-manufacturing provisioning or update of scripts, WoT +Scripting Runtime or any related data should be done in a secure +fashion. A set of recommendations for secure update and +post-manufacturing provisioning can be found in [WOT-SECURITY-GUIDELINES].
                                +
                                +
                                +
                                +

                                +9.1.4 Security Credentials Storage +Security and Privacy Risk

                                +

                                Typically the WoT Scripting Runtime needs to store the security +credentials that are provisioned to a WoT device to operate in WoT +network. If an attacker can compromise the confidentiality or +integrity of these credentials, then it can obtain access to the +WoT assets, impersonate WoT things or devices or create +Denial-Of-Service (DoS) attacks.

                                +
                                +
                                Mitigation:
                                +
                                The WoT Scripting Runtime should securely store the provisioned +security credentials, guaranteeing their integrity and +confidentiality. In case there are more than one tenant on a single +WoT-enabled device, a WoT Scripting Runtime should guarantee +isolation of each tenant provisioned security credentials. +Additionally, in order to minimize a risk that provisioned security +credentials get compromised, the WoT Scripting Runtime should not +expose any API for scripts to query the provisioned security +credentials.
                                +
                                +
                                +
                                +
                                +

                                9.2 Script Security and Privacy Risks

                                +

                                This section is non-normative.

                                +

                                This section describes specific risks relevant for script +developers.

                                +
                                +

                                +9.2.1 Corrupted Script Input Security and +Privacy Risk

                                +

                                A script instance may receive data formats defined by the TD, or +data formats defined by the applications. While the WoT Scripting +Runtime SHOULD perform +validation on all input fields defined by the TD, scripts may be +still exploited by input data.

                                +
                                +
                                Mitigation:
                                +
                                Script developers should perform validation on all application +defined script inputs. In addition to input validation, fuzzing could be used +to verify that the input processing is done correctly. There are +many tools and techniques in existence to do such validation. More +details can be found in [WOT-SECURITY-TESTING].
                                +
                                +
                                +
                                +

                                9.2.2 Denial Of Service Security Risk

                                +

                                If a script performs a heavy functional processing on received +requests before the request is authenticated, it presents a great +risk for Denial-Of-Service (DOS) attacks.

                                +
                                +
                                Mitigation:
                                +
                                Scripts should avoid heavy functional processing without prior +successful authentication of requestor. The set of recommended +authentication mechanisms can be found in [WOT-SECURITY-BEST-PRACTICES].
                                +
                                +
                                +
                                +

                                9.2.3 Stale TD Security Risk

                                +

                                During the lifetime of a WoT network, a content of a TD can +change. This includes its identifier, which might not be an +immutable one and might be updated periodically.

                                +
                                +
                                Mitigation:
                                +
                                Scripts should use this API to subscribe for notifications on +TD changes and do not rely on TD values to remain persistent.
                                +
                                +
                                +
                                Editor's note
                                +

                                While stale TDs can present a potential problem for WoT +network operation, it might not be a security risk.

                                +
                                +
                                +
                                +
                                +
                                +

                                10. Terminology and conventions

                                +

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

                                +

                                JSON-LD is +defined in [JSON-LD] as a JSON +document that is augmented with support for Linked Data.

                                +

                                The terms URL, +URL +scheme, URL host, +URL +path, URL record, +parse a +URL, absolute-URL +string, path-absolute-URL +string, basic URL +parser are defined in [URL].

                                +

                                The terms MIME type, +Parsing a +MIME type, Serializing +a MIME type, valid MIME +type string, JSON MIME +type are defined in [MIMESNIFF].

                                +

                                The terms UTF-8 encoding, +UTF-8 +decode, encode, +decode are +defined in [ENCODING].

                                +

                                string, +parse JSON +from bytes and serialize +JSON to bytes, are defined in [INFRA].

                                +

                                The terms throw, +creating, +DOMString, +Dictionary, +ArrayBuffer, +BufferSource, +any, +not +present, DOMException, +AbortError, +SyntaxError, +NotSupportedError, +NetworkError, +TypeError, +NotReadableError, +TimeoutError, + +NoModificationAllowedError, SecurityError, +are defined in [WEBIDL].

                                +

                                Promise, +Error, +JSON, +JSON.stringify, +JSON.parse +and +internal slots are defined in [ECMASCRIPT].

                                +

                                The terms browsing +context, +top-level browsing context, global +object, current +settings object, executing algorithms in +parallel are defined in [HTML5] and are used in the context of browser +implementations.

                                +

                                The term +secure +context is defined in [WEBAPPSEC].

                                +

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

                                +

                                The terms hyperlink reference and +relation type +are defined in [HTML5] and RFC8288.

                                +
                                +
                                +

                                A. API +design rationale

                                +

                                API rationale usually belongs to a separate document, but in the +WoT case the complexity of the context justifies including basic +rationale here.

                                +
                                +

                                A.1 Approaches to WoT application +development

                                +

                                The WoT Interest Group and Working Group have explored different +approaches to application development for WoT that have been all +implemented and tested.

                                +
                                +

                                A.1.1 No +Scripting API

                                +

                                It is possible to develop WoT applications that only use the +WoT network interface, typically exposed +by a WoT gateway that presents a REST-ful API towards clients and +implements IoT protocol plugins that communicate with supported IoT +deployments. One such implementation is the Mozilla WebThings platform.

                                +
                                +
                                +

                                A.1.2 +Simple Scripting API

                                +

                                WoT Things show good synergy with software objects, so a +Thing can be represented as a software object, with +Properties represented as object properties, Actions +as methods, and Events as events. In addition, metadata is +stored in special properties. Consuming and exposing is done with +factory methods that produce a software object that directly +represents a remote Thing and its interactions. One such +implementation is the Arena Web Hub +project.

                                +

                                In the next example, a Thing that represents interactions with a +lock would look like the following: the status property +and the open() method are directly exposed on the +object.

                                +
                                +
                                Example +8: Open a lock with a +simple API
                                +
                                let lock = await WoT.consume(‘https://td.my.com/lock-00123’);
+console.log(lock.status);
+lock.open('withThisKey');
                                +
                                +
                                +

                                A.1.3 This API, aligned with [WOT-TD]

                                +

                                Since the direct mapping of Things to software objects +have had some challenges, this specification takes another approach +that exposes software objects to represent the Thing +metadata as data property and the WoT interactions as methods. One +implementation is node-wot in the +the Eclipse ThingWeb project, +which is the current reference implementation of the API specified +in this document.

                                +

                                The same example now would look like the following: the +status property and the open() method are +represented indirectly.

                                +
                                +
                                Example 9: Open a lock
                                +
                                let res = await fetch(‘https://td.my.com/lock-00123’);
+let td = await res.json();
+let lock = new ConsumedThing(td);
+console.log(lock.readProperty(‘status’));
+lock.invokeAction(‘open’, 'withThisKey');
                                +
                                +

                                In conclusion, the WoT WG decided to explore the third option +that closely follows the [WOT-TD] specification. Based on this, a simple +API can also be implemented. Since Scripting is an optional module +in WoT, this leaves room for applications that only use the WoT +network interface. Therefore all three approaches above are +supported by [WOT-TD].

                                +

                                Moreover, the WoT network interface can be implemented in many +languages and runtimes. Consider this API an example for what needs +to be taken into consideration when designing a Scripting API for +WoT.

                                +
                                +
                                +

                                A.2 Fetching and validating a TD

                                +

                                The fetch(url) method has been part of this API in +earlier versions. However, now fetching a TD given a URL should be +done with an external method, such as the Fetch API or a HTTP +client library, which offer already standardized options on +specifying fetch details. The reason is that while simple fetch +operations (covering most use cases) could be done in this API, +when various fetch options were needed, there was no point in +duplicating existing work to re-expose those options in this +API.

                                +

                                Since fetching a TD has been scoped out, and TD +validation is defined externally in [WOT-TD], that is scoped out, too. This +specification expects a TD as parsed JSON +object that has been validated according to the +[WOT-TD] +specification.

                                +
                                +
                                +

                                A.3 +Factory vs constructors

                                +

                                The factory methods for consuming and exposing Things +are asynchronous and fully validate the input TD. In addition, one +can also construct ConsumedThing and ExposedThing by providing a parsed and +validated TD. Platform initialization is then done when needed +during the WoT interactions. So applications that prefer validating +a TD +themselves, may use the constructors, whereas applications that +leave validation to implementations and prefer interactions +initialized up front SHOULD +use the factory methods on the WoT API object.

                                +
                                +
                                +

                                A.4 +Observers

                                +

                                Earlier drafts used the Observer +construct, but since it has not become standard, a new design was +needed that was light enough for embedded implementations. +Therefore observing Property changes and handling WoT Events +is done with callback registrations.

                                +
                                +
                                +

                                A.5 Using +Events

                                +
                                +

                                This API ended up not using software events at all, for the +following reasons:

                                +
                                  +
                                • Subscription to WoT Events may be different from handling +software events (subscription might need parameters, might involve +security tokens etc).
                                  • +
                                • Most implementations are for Node.js and browser +implementations will likely be libraries (because possible +dependency management issues in native implementations), using +Events has been challenging.
                                  • +
                                • Observing Property changes and handling WoT Events +is done with the solution above.
                                  • +
                                +
                                +
                                +
                                +

                                A.6 +Polymorphic functions

                                +

                                The reason to use function names like +readProperty(), readMultipleProperties() +etc. instead of a generic polymorphic read() function +is that the current names map exactly to the "op" +vocabulary from the Form +definition in [WOT-TD].

                                +
                                +
                                +
                                +

                                B. Changes

                                +
                                +

                                The following is a list of major changes to the document. Major +versions of this specification are the following:

                                + +
                                +

                                For a complete list of changes, see the github +change log. You can also view the +recently closed issues.

                                +
                                +
                                +

                                C. +Open issues

                                +
                                +

                                The following problems are being discussed and need most +attention:

                                +
                                  +
                                • Script management and runtime related issues +(https://github.com/w3c/wot-scripting-api/issues/)
                                  • +
                                • An explicit API for adding and removing Property, Action and Event definitions on +ExposedThing (it was present in earlier +versions, but removed for complexity and a simpler way to do +it.
                                  • +
                                +
                                +
                                +
                                +

                                D. Full Web +IDL

                                +
                                typedef object ThingDescription;
+
+[SecureContext, Exposed=(Window,Worker)]
+interface WOT {
+  // methods defined in UA conformance classes
+};
+
+partial interface WOT {
+  Promise<ConsumedThing> consume(ThingDescription td);
+};
+
+partial interface WOT {
+  Promise<ExposedThing> produce(ThingDescription td);
+};
+
+partial interface WOT {
+  ThingDiscovery discover(optional ThingFilter filter = null);
+};
+
+[SecureContext, Exposed=(Window,Worker)]
+interface ConsumedThing {
+  constructor(ThingDescription td);
+  Promise<any> readProperty(DOMString propertyName,
+                            optional InteractionOptions options = null);
+  Promise<PropertyMap> readAllProperties(optional InteractionOptions options = null);
+  Promise<PropertyMap> readMultipleProperties(
+                            sequence<DOMString> propertyNames,
+                            optional InteractionOptions options = null);
+  Promise<void> writeProperty(DOMString propertyName,
+                              any value,
+                              optional InteractionOptions options = null);
+  Promise<void> writeMultipleProperties(PropertyMap valueMap,
+                              optional InteractionOptions options = null);
+  Promise<any> invokeAction(DOMString actionName,
+                              optional any params = null,
+                              optional InteractionOptions options = null);
+  Promise<void> observeProperty(DOMString name,
+                              WotListener listener,
+                              optional InteractionOptions options = null);
+  Promise<void> unobserveProperty(DOMString name);
+  Promise<void> subscribeEvent(DOMString name,
+                              WotListener listener,
+                              optional InteractionOptions options = null);
+  Promise<void> unsubscribeEvent(DOMString name);
+  ThingDescription getThingDescription();
+};
+dictionary InteractionOptions {
+  object uriVariables;
+};
+typedef object PropertyMap;
+callback WotListener = void(any data);
+
+[SecureContext, Exposed=(Window,Worker)]
+interface ExposedThing: ConsumedThing {
+  ExposedThing setPropertyReadHandler(DOMString name,
+          PropertyReadHandler readHandler);
+  ExposedThing setPropertyWriteHandler(DOMString name,
+          PropertyWriteHandler writeHandler);
+  ExposedThing setActionHandler(DOMString name, ActionHandler action);
+  void emitEvent(DOMString name, any data);
+  Promise<void> expose();
+  Promise<void> destroy();
+};
+callback PropertyReadHandler = Promise<any>(
+        optional InteractionOptions options = null);
+callback PropertyWriteHandler = Promise<void>(any value,
+        optional InteractionOptions options = null);
+callback ActionHandler = Promise<any>(any params,
+        optional InteractionOptions options = null);
+
+[SecureContext, Exposed=(Window,Worker)]
+interface ThingDiscovery {
+  constructor(optional ThingFilter filter = null);
+  readonly attribute ThingFilter? filter;
+  readonly attribute boolean active;
+  readonly attribute boolean done;
+  readonly attribute Error? error;
+  void start();
+  Promise<ThingDescription> next();
+  void stop();
+};
+
+typedef DOMString DiscoveryMethod;
+
+dictionary ThingFilter {
+  (DiscoveryMethod or DOMString) method = "any";
+  USVString? url;
+  USVString? query;
+  object? fragment;
+};
                                +
                                +

                                E. +Acknowledgements

                                +

                                Special thanks to former editor Johannes Hund (until August +2017, when at Siemens AG) and Kazuaki Nimura (until December 2018) +for developing this specification. Also, the editors would like to +thank Dave Raggett, Matthias Kovatsch, Michael Koster, Elena +Reshetova, Michael McCool as well as the other WoT WG members for +their comments, contributions and guidance.

                                +
                                +
                                +

                                F. +References

                                +
                                +

                                F.1 +Normative references

                                +
                                +
                                [ECMASCRIPT]
                                +
                                ECMAScript +Language Specification. Ecma International. URL: +https://tc39.github.io/ecma262/
                                +
                                [ENCODING]
                                +
                                Encoding +Standard. Anne van Kesteren. WHATWG. Living Standard. +URL: https://encoding.spec.whatwg.org/
                                +
                                [HTML]
                                +
                                HTML +Standard. Anne van Kesteren; Domenic Denicola; Ian +Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. +URL: https://html.spec.whatwg.org/multipage/
                                +
                                [HTML5]
                                +
                                HTML5. +Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika +Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. W3C. 27 March +2018. W3C Recommendation. URL: https://www.w3.org/TR/html5/
                                +
                                [INFRA]
                                +
                                Infra +Standard. Anne van Kesteren; Domenic Denicola. WHATWG. +Living Standard. URL: https://infra.spec.whatwg.org/
                                +
                                [JSON-LD]
                                +
                                JSON-LD +1.0. Manu Sporny; Gregg Kellogg; Markus Lanthaler. W3C. +16 January 2014. W3C Recommendation. URL: https://www.w3.org/TR/json-ld/
                                +
                                [MIMESNIFF]
                                +
                                MIME +Sniffing Standard. Gordon P. Hemsley. WHATWG. Living +Standard. URL: https://mimesniff.spec.whatwg.org/
                                +
                                [RFC2119]
                                +
                                Key words +for use in RFCs to Indicate Requirement Levels. S. +Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
                                +
                                [RFC8174]
                                +
                                Ambiguity +of Uppercase vs Lowercase in RFC 2119 Key Words. B. +Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174
                                +
                                [TYPESCRIPT]
                                +
                                +TypeScript Language Specification. Microsoft. 1 October +2012. URL: https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md
                                +
                                [URL]
                                +
                                URL +Standard. Anne van Kesteren. WHATWG. Living Standard. +URL: https://url.spec.whatwg.org/
                                +
                                [WEBAPPSEC]
                                +
                                Secure +Contexts. W3C. 17 July 2015. URL: https://w3c.github.io/webappsec/specs/powerfulfeatures
                                +
                                [WEBIDL]
                                +
                                Web +IDL. Boris Zbarsky. W3C. 15 December 2016. W3C Editor's +Draft. URL: https://heycam.github.io/webidl/
                                +
                                [WOT-ARCHITECTURE]
                                +
                                Web of +Things Architecture. W3C. 20 August 2017. URL: https://w3c.github.io/wot-architecture/
                                +
                                [WOT-PROTOCOL-BINDINGS]
                                +
                                Web of Things +Protocol Binding Templates. W3C. 20 August 2017. URL: +https://w3c.github.io/wot-binding-templates/
                                +
                                +[WOT-SECURITY-BEST-PRACTICES]
                                +
                                +Web of Things Security and Privacy Best Practices. +W3C. WIP. URL: +https://github.com/w3c/wot-security/blob/master/wot-security-best-practices.md
                                +
                                [WOT-SECURITY-GUIDELINES]
                                +
                                Web of +Things Security and Privacy Guidelines. W3C. 28 August +2017. URL: https://w3c.github.io/wot-security/
                                +
                                [WOT-SECURITY-TESTING]
                                +
                                +Web of Things Security Testing and Validation. +W3C. WIP. URL: +https://github.com/w3c/wot-security/blob/master/wot-security-testing.md
                                +
                                [WOT-TD]
                                +
                                WoT Thing +Description . W3C. 20 August 2017. URL: https://w3c.github.io/wot-thing-description/
                                +
                                +
                                +
                                + + + + diff --git a/releases/wd4/README.md b/releases/wd4/README.md new file mode 100644 index 00000000..c1a29281 --- /dev/null +++ b/releases/wd4/README.md @@ -0,0 +1,15 @@ +# WoT Scripting API - Release Notes + +The changes compared to [previous version](https://www.w3.org/TR/2018/WD-wot-scripting-api-20181129/) are also enumerated in the +[Changes](https://w3c.github.io/wot-scripting-api/#Changes) section of the spec. + +This version, introducing the following major changes: +- Remove fetch() for fetching a TD (delegated to external API). +- Remove Observer and use W3C TAG recommended design patterns. +- Align the discovery API to other similar APIs (such as W3C Generic Sensor API). +-Remove the large data definition API for constructing TDs and leverage using ThingDescription instead. +- Add missing algorithms and rework most existing ones. +- Allow constructors for ConsumedThing and ExposedThing. +- Add API rationale as an appendix to this document. + +For a complete list of changes, see the [github change log](https://github.com/w3c/wot-scripting-api/commits/master). \ No newline at end of file diff --git a/releases/wd4/diff.html b/releases/wd4/diff.html new file mode 100644 index 00000000..1eb3ba0d --- /dev/null +++ b/releases/wd4/diff.html @@ -0,0 +1,22501 @@ + + + Web of Things (WoT) Scripting API + + + + +
                                +

                                Web of Things (WoT) Scripting API

                                + +

                                + W3C Editor's Draft + +

                                +
                                +
                                This version:
                                + https://w3c.github.io/wot-scripting-api/ +
                                Latest published version:
                                + https://www.w3.org/TR/wot-scripting-api/ +
                                +
                                Latest editor's draft:
                                https://w3c.github.io/wot-scripting-api/
                                + + + + + + +
                                Editors:
                                +
                                Zoltan Kis + (Intel) +
                                Daniel Peintner + (Siemens AG) +
                                Johannes Hund (Former Editor, when at Siemens AG)
                                Kazuaki Nimura (Former Editor, at Fujitsu Ltd.)
                                + + +
                                Repository:
                                + On GitHub +
                                + File a bug +
                                Contributors:
                                + Contributors on GitHub +
                                +
                                + + + +

                                + Copyright + © + 2017-2019 + + W3C® (MIT, + ERCIM, Keio, + Beihang). + W3C liability, + trademark and permissive document license rules + apply. +

                                +
                                +

                                Web +of +Things +(WoT) +Scripting +API +W3C +Working +Draft +29 +November +2018 +This +version: +https://www.w3.org/TR/2018/WD-wot-scripting-api-20181129/ +Latest +published +version: +https://www.w3.org/TR/wot-scripting-api/ +Latest +editor's +draft: +https://w3c.github.io/wot-scripting-api/ +Previous +version: +https://www.w3.org/TR/2018/WD-wot-scripting-api-20180405/ +Editors: +Zoltan +Kis +( +Intel +) +Kazuaki +Nimura +( +Fujitsu +Ltd. +) +Daniel +Peintner +( +Siemens +AG +) +Johannes +Hund +(Former +Editor, +when +at +Siemens +AG) +Contributors: +In +the +GitHub +repository +Repository: +We +are +on +GitHub +File +a +bug +Copyright +© +2017-2018 +W3C +® +( +MIT +, +ERCIM +, +Keio +, +Beihang +). +W3C +liability +, +trademark +and +permissive +document +license +rules +apply. +Abstract +

                                Abstract

                                +The +overall + +main + +Web +of +Things + +(WoT) +concepts +are +described +in +the + +WoT +Architecture + +document. +The +Web +of +Things +is +made +of +entities +( + +Thing + +s) +that +can +describe +their +capabilities +in +a +machine-interpretable +format, +the + + +Thing +Description + +(TD) +and +expose +these +capabilities +through +the + +WoT +Interface +, +that +is, +network +interactions +modeled +as + +Properties + +for + +(for + +reading +and +writing +values, + +values), + +Action + +s +to + +(to + +execute +remote +procedures +with +or +without +return +values + +values) + +and + +Event + +s +for + +(for + +signaling +notifications. +This +specification +describes +a +programming +interface +representing +the +WoT +Interface +that +allows +scripts +run +on +a +Thing +to +discover +and +consume +(retrieve) +other +Thing +Description +s +and +to +expose +Things +characterized +by +WoT +Interactions +specified +by +a +script. + +notifications). + +

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

                                Status +of +This +Document +

                                +This +section + +specification + +describes +a +programming +interface +representing + +the +status +of +this +document +at +the +time +of +its +publication. +Other +documents +may +supersede +this +document. +A +list +of +current +W3C +publications + + +WoT +Interface + +that +allows +scripts +to +discover, +operate + +Thing + +s + +and +to +expose +locally +defined + +Things + +characterized +by + +WoT +Interactions + +specified +by +a +script. +

                                +The +specification +deliberately +follows + +the +latest +revision + + +WoT +Thing +Description +specification + +closely. +It +is +possible +to +implement +simpler +APIs +on +top + +of +this +technical +report +can +be +found +in + +API, +or +implementing +directly + +the +W3C +technical +reports +index + +WoT +network +facing +interface +(i.e. +the + +WoT +Interface + + +). +

                                Editor's note

                                +This +specification +is +implemented + +at +https://www.w3.org/TR/. + +least +by +the + +Thingweb + +project +also +known +as + +node-wot +, +which +is +considered +the +reference +open +source +implementation +at +the +moment. +Check +its + +source +code +, +including + +examples +. +Other, +closed +source +implementations +have +been +made +by +WG +member +companies +and +tested +against + +node-wot + +in +plug-fests. + +

                                Status of This Document

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

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

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

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

                                This +document +was +published +by +the +Web +of +Things +Working +Group +as +a +Working +Draft. +This +document +is +intended +to +become +a +W3C +Recommendation. +Comments +regarding +this +document +are +welcome. +Please +send +them +to +public-wot-wg@w3.org +( +subscribe +, +archives +). +Changes +from +the +previous +publication +can +be +found +in +Appendix +A +. +A +diff-marked +version +of +this +document +is +also +available +for +comparison +purposes. +Publication +as +a +Working +Draft +does +not +imply +endorsement +by +the +W3C +Membership. +This +is +a +draft +document +and +may +be +updated, +replaced +or +obsoleted +by +other +documents +at +any +time. +It +is +inappropriate +to +cite +this +document +as +other +than +work +in +progress. +This +document +was +produced +by +a +group +operating +under +the +W3C +Patent +Policy +. +W3C +maintains +a +public +list +of +any +patent +disclosures +made +in +connection +with +the +deliverables +of +the +group; +that +page +also +includes +instructions +for +disclosing +a +patent. +An +individual +who +has +actual +knowledge +of +a +patent +which +the +individual +believes +contains +Essential +Claim(s) +must +disclose +the +information +in +accordance +with +section +6 +of +the +W3C +Patent +Policy +. +This +document +is +governed +by +the +1 +February +2018 +W3C +Process +Document +. +

                                + This document was published by the Web of Things Working Group as an + Editor's Draft. + +

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

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

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

                                + This document is governed by the + 1 March 2019 W3C Process Document. +

                                Table +of +Contents +1. +Introduction +2. +Use +Cases +2.1 +Discovery +2.2 +Consuming +a +Thing +2.3 +Exposing +a +Thing +3. +The +WoT +object +3.1 +The +discover() +method +3.1.1 +The +DiscoveryMethod +enumeration +3.1.2 +The +ThingFilter +dictionary +3.2 +The +fetch() +method +3.3 +The +consume() +method +3.4 +The +produce() +method +3.5 +The +register() +method +3.6 +The +unregister() +method +3.7 +Examples +4. +The +ConsumedThing +interface +4.1 +Examples +5. +The +ExposedThing +interface +5.1 +The +expose() +method +5.2 +The +destroy() +method +5.3 +The +addProperty() +method +5.4 +The +removeProperty() +method +5.5 +The +addAction() +method +5.6 +The +removeAction() +method +5.7 +The +addEvent() +method +5.8 +The +removeEvent() +method +5.9 +The +PropertyReadHandler +callback +5.10 +The +PropertyWriteHandler +callback +5.11 +The +ActionHandler +callback +5.12 +The +setPropertyReadHandler() +method +5.13 +The +setPropertyWriteHandler() +method +5.14 +The +setActionHandler() +method +5.15 +Examples +6. +Data +types +and +structures +6.1 +The +DataSchema +dictionary +and +its +subclasses +6.2 +The +SecurityScheme +dictionary +and +its +subclasses +6.3 +The +Link +dictionary +6.4 +The +Form +dictionary +6.5 +The +InteractionFragment +dictionary +6.6 +The +PropertyFragment +dictionary +6.7 +The +ActionFragment +dictionary +6.8 +The +EventFragment +dictionary +6.9 +The +ThingFragment +dictionary +6.10 +The +ThingDescription +type +7. +Interfaces +for +WoT +Interactions +7.1 +The +Interaction +interface +7.2 +The +ThingProperty +interface +7.3 +The +ThingAction +interface +7.4 +The +ThingEvent +interface +7.5 +The +ExposedEvent +interface +7.5.1 +The +emit() +method +7.6 +The +value-matching +algorithm +8. +Observables +8.1 +The +Subscription +interface +8.2 +The +Observable +interface +9. +Security +and +Privacy +10. +Terminology +and +conventions +11. +Conformance +A. +Changes +B. +Open +issues +C. +Acknowledgments +D. +References +D.1 +Normative +references +D.2 +Informative +references +

                                1. +Introduction +

                                1. +

                                +WoT +provides +layered +interoperability +based +on +how + +Thing + +s +are +modeled: +as +being + +used: + +"consumed" +and +"exposed". + +"exposed", +as + +defined + +in +[WOT-ARCHITECTURE]. + +

                                +By + +consuming +a +TD +, +a +client + +Thing + +creates +a +local + +runtime +resource +model +that +allows +accessing +the + +Properties +, + +Actions + +and + +Events + +exposed +by +the +server + +Thing + +exposed + +on +a +remote +device. +

                                Exposing +a + +Thing + +requires + +requires: +

                                +This +specification +describes +how +to +expose +and +consume + +Thing + +s +by +a +script. +Note + +Also, +it +defines +a +generic +API +for + +Thing + +discovery. + +
                                Note

                                +Typically +scripts +are +meant +to +be +used +on +devices +able +to +provide +resources +(with +a +WoT +Interface +) +for +managing +(installing, +updating, +running) +scripts, +such +as + +bridges +or +gateways +that +expose +and +control +simpler +devices +as +WoT + +Thing + +s. + +s +and +have +means +to +handle +(e.g. +install, +uninstall, +update +etc.) +and +run +scripts. + +

                                Note +
                                Note

                                +This +specification +does +not +make +assumptions +on +how +the + +WoT +Runtime + +handles +and +runs +scripts, +including +single +or +multiple +tenancy, +script +deployment +and +lifecycle +management. +The +API +already +supports +the +generic +mechanisms +that +make +it +possible +to +implement +script +management, +for +instance +by +exposing +a +manager + +Thing + +whose + +Actions + +(action +handlers) +implement +script +lifecycle +management +operations. +

                                For +an +introduction +on +how +scripts +could +be +used +in +Web +of +Things +, +check +the +Primer +document. +For +some +background +on +API +design +decisions +check +the +Rationale +document. +
                                2. +

                                2. +Use +Cases +This +section +is +non-normative. + +

                                This section is non-normative.

                                +The +following +scripting +use +cases +are +supported +in +this +specification: +

                                2.1 +Discovery +Discover +all +Thing +s +in +the +WoT +network +by +sending +a +broadcast +request. +Discover +Thing +s +running +in +the +local +WoT +Runtime +. +Discover +nearby +Thing +s, +for +instance +connected +by +NFC +or +Bluetooth. +Discover +Thing +s +by +sending +a +discovery +request +to +a +given +registry. +Discover +Thing +s +by +filters +defined +on +Thing +Description +s +Discover +Thing +s +by +semantic +queries. +Stop +or +suppress +an +ongoing +discovery +process. +Optionally +specify +a +timeout +to +the +discovery +process +after +which +it +is +stopped/suppressed. +

                                2.1 +Consuming +a +Thing +

                                2.2 +

                                2.2 +Exposing +a +Thing +

                                2.3 +

                                  +
                                • +Exposing +the + +Thing + +includes +generating +the +protocol +bindings +in +order +to +access +lower +level +functionality. +
                                  • +
                                • +Create +a +local +ExposedThing + + +Thing + + +to +be +exposed, +based +on +a + +Thing +Description + +provided +in +string +serialized +format, +or +out +of +a +template +or + +an +existing +ConsumedThing + + +Thing + + +object. +
                                  • +
                                • +Add +a + +Property + +definition +to +the + +Thing +. +
                                  • +
                                • +Add +an +Action + +Remove +a + +Property + + +definition +to + +from + +the + +Thing +. +
                                  • +
                                • +Add +an +Event + + +Action + + +definition +to +the + +Thing +. +
                                  • +
                                • +Attach +semantic +information +to + +Remove +an + +Action + +definition +from + +the + +Thing +. +
                                  • +
                                • +Attach +semantic +information +to + +Add + +a +Property +. +Attach +semantic +information + +WoT + +Event + +definition + +to +an +Action + +the + +Thing + +. +
                                  • +
                                • +Attach +semantic +information +to +an + +Remove +a +WoT + +Event + +definition +from +the + +Thing + +. +
                                  • +
                                • +Emit +an + +a +WoT + +Event +, +i.e. +notify +all +listeners +subscribed +to +that +Event +. +Provide +notifications +for +TD +changes +to +clients + +subscribed +to +that. +Mark/unmark +the +Thing +to +be +discoverable. +Mark/unmark +the +Thing +to +be +consumable. +Start +the +exposed +Thing +in +order +to +process +external +requests. +Stop +the +exposed +Thing +. + +listeners. + +
                                  • +
                                • +Register +service + +handlers +for +external +requests: +
                                    +
                                  • +to +retrieve +a + +Property + +value; +
                                    • +
                                  • +to +update +a + +Property + +value; +
                                    • +
                                  • +to +run + +invoke + +an + +Action +: +take +the +parameters +from +the +request, +execute +the +defined +action, +and +return +the +result; +
                                    • +
                                  +
                                  • +
                                3. +The +WoT +object +

                                2.3 +Discovery +

                                • +Discover + +Thing + + +The +WoT +object +is +the +API +entry +point +and +it +is +exposed + +s +in +a +network + +by +an +implementation +of + +sending +a +broadcast +request. +
                                • +Discover + +Thing + +s +running +in + +the +local + +WoT +Runtime +. +The +WoT +object +does +not +expose +properties, +only +methods + +
                                  • +
                                • +Discover +nearby + +Thing + +s, + +for +discovering, +consuming +and +exposing + +instance +connected +by +NFC +or +Bluetooth. +
                                • +Discover + +Thing + +s +by +sending + +a +discovery +request +to +a +given +registry. +
                                • +Discover + +Thing +. + + +s +filtered +by +filters +defined +on + +Thing +Description + +s +
                                • +Discover + +Thing + +s +filtered +by +semantic +queries. +
                                • +Stop +or +suppress +an +ongoing +discovery +process. +
                                • +Optionally +specify +a +timeout +to +the +discovery +process +after +which +it +is +stopped/suppressed. +

                                3. Conformance

                                + As well as sections marked as non-normative, all authoring guidelines, + diagrams, examples, and notes in this specification are non-normative. + Everything else in this specification is normative. +

                                + The key words MAY, MUST, SHOULD, and SHOULD NOT in this document + are to be interpreted as described in + BCP 14 + [RFC2119] + [RFC8174] when, and only when, they appear + in all capitals, as shown here. +

                                +This +specification +describes +the +conformance +criteria +for +the +following +classes +of + +user +agent + +( + +UA + +). + +

                                Note +Browser +implementations +SHOULD +use +

                                +Due +to +requirements +of +small +embedded +implementations, +splitting +WoT +client +and +server +interfaces +was +needed. +Then, +discovery +is + +a +namespace +object +such +as +navigator.wot +. +Node.js + +distributed +application, +but +typical +scenarios +have +been +covered +by +a +generic +discovery +API +in +this +specification. +This +resulted +in +using +3 +conformance +classes +for +a + +UA + + +-like +runtimes +MAY +provide +the + +that +implements +this +API, +one +for +client, +one +for +server, +and +one +for +discovery. +An +application +that +uses +this + +API +object +through + +can +introspect +for +the +presence +of + +the +require() +or +import +mechanism. +// [SecureContext] +// [NamespaceObject] +

                                }; +typedef +typedef +typedef +typedef +typedef +typedef +typedef +typedef +typedef +typedef +( + + +ThingFragment +or + +consume() +, + +ThingDescription + +produce() + + +) + +and + + +ThingModel + +discover() + + +; +Editor's +note +The +algorithms +for + +methods +on + +the + +WoT +methods +will +be +specified +later, +including +error +handling +and +security +considerations. + +API +object + +in +order +to +determine +which +conformance +class +the + +UA + +implements. + +

                                +
                                + +WoT +Consumer + +UA +
                                +

                                +The + +Implementations +of +this +conformance +class +MUST +implement +the + + +ThingModel + +type +represents +either +a + + +ConsumedThing + +ThingFragment + + +, +or +a + +interface +and +the + + +ThingDescription + +consume() + + +method +on +the + +WoT +API +object + +. +

                                +3.1 +The +discover() + +
                                +
                                + +WoT +Producer + + +method + + +UA + + +
                                +
                                +

                                +Starts +the +discovery +process +that +will +provide +ThingDescription +s +that +match +the +optional +argument +filter + +Implementations + +of +type + +this +conformance +class +MUST +implement + + +ThingFilter + + +ExposedThing + + +. +Returns +an +[ +Observable + + +](https://github.com/tc39/proposal-observable) +object +that +can +be +subscribed +to + +interface + +and +unsubscribed +from. +The +handler +function +provided +to + +the +Observable +during +subscription +will +receive +an +argument +of +type + + +USVString +representing +a +ThingDescription + +produce() + + +method +on +the + +WoT +API +object + +. +

                                +3.1.1 +The +DiscoveryMethod + +
                                +
                                + +WoT +Discovery + + +enumeration +typedef +DOMString + + +UA + + +
                                +
                                +

                                +Implementations +of +this +conformance +class +MUST +implement +the + + +DiscoveryMethod + + +ThingDiscovery + + +; + + +interface +and +the + + +DiscoveryMethod + +discover() + + +represents + +method +on + +the +discovery +type +to + + +WoT +API +object +.

                                +These +conformance +classes +MAY + +be +used: + +implemented +in +a +single + +UA +. +

                                "any" +does +not +provide +any +restriction +"local" +

                                +This +specification +can +be +used + +for +discovering +Thing + +implementing +the +WoT +Scripting +API +in +multiple +programming +languages. +The +interface +definitions +are +specified +in +[WEBIDL]. +

                                +The + +UA + + +s +defined + +may +be +implemented + +in +the +same +device + +browser, + +or +connected + +in +a +separate +runtime +environment, +such +as + +Node.js + +or +in +small +embedded +runtimes. +

                                +Implementations +that +use +ECMAScript +executed +in +a +browser + +to +implement + +the +device +by +wired + +APIs +defined +in +this +document +MUST +implement +them +in +a +manner +consistent +with +the +ECMAScript +Bindings +defined +in +the +Web +IDL +specification +[WEBIDL]. +

                                +Implementations +that +use +TypeScript + +or +wireless +means. +"directory" +for +discovery +based +on + +ECMAScript +in + +a +service +provided +by + +runtime +to +implement +the +APIs +defined +in +this +document +MUST +implement +them +in + +a +Thing +Directory +. +"multicast" +for +discovering +Thing +s + +manner +consistent +with +the +TypeScript +Bindings +defined + +in +the +device's +network +by +using +a +supported +multicast +protocol. + +TypeScript +specification +[TYPESCRIPT]. +

                                3.1.2 +

                                4. +The +ThingFilter + + +ThingDescription + + +dictionary + +type +

                                typedef object ThingDescription;

                                +The +ThingFilter + +Represents +a + +Thing +Description + +( + +TD + +) +as +defined +in +[WOT-TD]. +It +is +expected +to +be +a + +parsed +JSON +object + + +dictionary + +that +represents +the +constraints +for +discovering + +is +validated +using + +JSON +schema +validation +.

                                4.1 +Fetching +a + +Thing +Description +

                                +Fetching +a + +TD + + +s + +given +a +URL +should +be +done +with +an +external +method, +such + +as +key-value +pairs. + +the + +Fetch +API + +or +a +HTTP +client +library, +which +offer +already +standardized +options +on +specifying +fetch +details. + +

                                +( + + + +

                                }; +

                                +
                                +
                                + Example 1: Fetching a Thing Description + 
                                        try {
+          let res = await fetch('https://tds.mythings.biz/sensor11');
+          // ... additional checks possible on res.headers
+          let td = await res.json();
+          let thing = new ConsumedThing(td);
+          console.log("Thing name: " + thing.getThingDescription().title);
+        } catch (err) {
+          console.log("Fetching TD failed", err.message);
+        }
+
                                +
                                +

                                4.2 +Expanding +a +Thing +Description +

                                +The +method +property +represents +the +discovery +type + +Note + +that +should +be +used +in + +[WOT-TD] +allows +using +a +shortened + +Thing +Description + +by + +the +discovery +process. +The +possible + +means +of + +defaults + +and +requiring +clients +to +expand +them +with +default + +values +specified +in +[WOT-TD] +for +the +properties +that + +are +not +explicitly + +defined +by + +in +a +given + +TD +.

                                +To + +expand +a +TD + +given + +td +, +run + +the +DiscoveryMethod +enumeration +that +MAY +be +extended +by +string + +following +steps: +
                                1. +For +each +item +in +the + +TD +default + +values + +table +from +[WOT-TD], +if +the +term +is +not + +defined +by +solutions +(with +no +guarantee +of +interoperability). + +in + +td +, +add +the +term +definition +with +the +default +value +specified +in +[WOT-TD]. +

                                4.3 +Validating +a +Thing +Description +

                                +The +url +property +represents +additional +information +for + +[WOT-TD] +specification +defines +how +a + +TD + +should +be +validated. +Therefore, +this +API +expects + +the +discovery +method, +such + + +ThingDescription + +objects +be +validated +before +used + +as +parameters. +This +specification +defines +a +basic + +TD + +validation +as +follows. +

                                +To + +validate +a +TD + +given + +td +, +run + +the +URL + +following +steps: +
                                1. +If + +td + +is +not +an +object, +throw + +"TypeError" + +and +terminate +these +steps. +
                                2. +If +any + +of +the +target +entity +serving +the +discovery +request, + +mandatory +properties +defined +in +[WOT-TD] + +for +instance +a + + +Thing +Directory + + +(if + +that +don't +have + +default +definitions + +are +missing +from + +td +, +throw + + +method + +"TypeError" + + +is + +and +terminate +these +steps. +
                                3. +If + +JSON +schema +validation + +fails +on + +td +, +throw + + +"directory" + +"TypeError" + + +) +or +a +Thing +(otherwise). + +and +terminate +these +steps. +

                                5. +The +query + + +WoT +API +object + + +property +represents + +

                                +Defines +the +API +entry +point +exposed +as + +a +query +string +accepted +by + +singleton +and +contains + +the +implementation, +for +instance + +API +methods. +

                                5.1 +The + +WOT + +interface +

                                      [SecureContext, Exposed=(Window,Worker)]
+      interface WOT {
+        // methods defined in UA conformance classes
+      };
                                Note

                                +Browser +implementations +should +use + +a +SPARQL +or +JSON +query. +Support + +namespace +object +such +as + +navigator.wot +. +Standalone +runtimes + +may +be +implemented +locally +in + +expose + +the +WoT +Runtime + +API +object +through +mechanisms +like + +require() + + +or +remotely +as +a +service +in +a +Thing +Directory + + +import + +. +

                                5.2 +The +fragment + + +consume() + + +property +represents + +method +

                                      partial interface WOT {
+        Promise<ConsumedThing> consume(ThingDescription td);
+      };
                                +Belongs +to +the + +WoT +Consumer + +conformance +class. +Expects +an + +td + +argument +and +returns + +a +ThingFragment + + +Promise + + +dictionary +used +for +matching +property +by +property +against +discovered +Thing + +that +resolves +with +a + +ConsumedThing + + +s. + +object +that +represents +a +client +interface +to +operate +with +the + +Thing +. +The +discover(filter) + +method +MUST +run +the +following +steps: +
                                  +
                                1. +Return +a + +Promise + +promise + +and +execute +the +next +steps + +in +parallel +.
                                2. +If +invoking +discover() + +this +method + +is +not +allowed +for +the +current +scripting +context +for +security +reasons, +throw + +reject + +promise + +with + + +SecurityError + +and +terminate +these +steps. +
                                  3. +
                                3. +Return +an +Observable + +Run +the + +validate +a +TD + + +steps +on + + +obs + +td +. +If +that +throws, +reject + +promise + + +with +the +error + +and +execute + +terminate +these +steps. +
                                4. +Let + +thing + +be +a +new + +ConsumedThing + +object +constructed +from + +td +.
                                5. +Set +up + +the +next +steps + + +WoT +Interactions + +based +on +introspecting + +td + +as +explained + +in +parallel + +[WOT-TD] +and +[WOT-PROTOCOL-BINDINGS]. +Make +a +request +to +the +underlying +platform +to +initialize +the + +Protocol +Bindings + +. +The +details +are +private +to +the +implementations +and +out +of +scope +of +this +specification. + +
                                  6. +
                                6. +If + +Resolve + +promise + +with + +thing +.

                                5.3 +The + +produce() + +method +

                                      partial interface WOT {
+        Promise<ExposedThing> produce(ThingDescription td);
+      };
                                +Belongs +to +the + +WoT +Producer + +conformance +class. +Expects +a + + +obs.subscribe(handler, +errorHandler, +complete) + +td + + +is +called, +execute + +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 +method +MUST +run + +the +following +sub-steps: + +steps: + +
                                  +
                                1. +If +the +first +argument + +Return +a + +Promise + + +handler + +promise + + +is +not +defined +or +it +is +not +a +function, +throw +TypeError + +and +terminate + +execute + +the +algorithm. +Otherwise +configure +handler +to +be +invoked +when +a +discovery +hit +happens. + +next +steps + +in +parallel +. +
                                  2. +
                                2. +If +the +second +argument +errorHandler +is +defined, +but +it + +invoking +this +method + +is +not +a +function, +throw + +allowed +for +the +current +scripting +context +for +security +reasons, +reject + +promise + +with + + +TypeError + +SecurityError + + +and +terminate +these +steps. +Otherwise +if +defined, +save +it +to + +
                                  3. +
                                3. +Let + +thing + +be +invoked +in +error +conditions. + +a +new + +ExposedThing + +object +constructed +with + +td +. +
                                  4. +
                                4. +If + +Resolve + +promise + +with + +thing +.

                                5.4 +The + +discover() + +method +

                                      partial interface WOT {
+        ThingDiscovery discover(optional ThingFilter filter = null);
+      };
                                +Belongs +to + +the +third +argument + + +WoT +Discovery + +conformance +class. +Starts +the +discovery +process +that +will +provide + +ThingDescription + +objects +for + +Thing +Description + +s +that +match +an +optional + + +onComplete + +filter + + +is +defined, +but +it + +argument. +The +method +MUST +run +the +following +steps: +
                                1. +If +invoking +this +method + +is +not +a +function, + +allowed +for +the +current +scripting +context +for +security +reasons, + +throw + +TypeError + +SecurityError + + +and +terminate +these +steps. +Otherwise +if +defined, +save +it +to +be +invoked +when +the +discovery +process +finished +for +other +reasons +than +having +been +canceled. + +
                                  2. +
                                2. +If + +Construct +a + +ThingDiscovery + +object + + +filter.query + +discovery + + +is +defined, +pass +it +as +an +opaque +string +to + +with + +filter +.
                                3. +Invoke + +the +underlying +implementation + + +discovery.start() + +method. +
                                4. +Return + +discovery +.

                                +Refer + +to +the + +ThingDiscovery + +section +for +how +discovery +should + +be +matched +against +discovered +items. + +implemented. +

                                6. +The +underlying +implementation +is +responsible + + +ConsumedThing + +interface +

                                +Represents +a +client +API + +to +parse +it +e.g. +as + +operate + +a +SPARQL +or +JSON +query +and +match +it +against + + +Thing +. +Belongs +to + +the + +WoT +Consumer + +conformance +class. +

                                      [SecureContext, Exposed=(Window,Worker)]
+      interface ConsumedThing {
+        constructor(ThingDescription td);
+        Promise<any> readProperty(DOMString propertyName,
+                                  optional InteractionOptions options = null);
+        Promise<PropertyMap> readAllProperties(optional InteractionOptions options = null);
+        Promise<PropertyMap> readMultipleProperties(
+                                  sequence<DOMString> propertyNames,
+                                  optional InteractionOptions options = null);
+        Promise<void> writeProperty(DOMString propertyName,
+                                    any value,
+                                    optional InteractionOptions options = null);
+        Promise<void> writeMultipleProperties(PropertyMap valueMap,
+                                    optional InteractionOptions options = null);
+        Promise<any> invokeAction(DOMString actionName,
+                                    optional any params = null,
+                                    optional InteractionOptions options = null);
+        Promise<void> observeProperty(DOMString name,
+                                    WotListener listener,
+                                    optional InteractionOptions options = null);
+        Promise<void> unobserveProperty(DOMString name);
+        Promise<void> subscribeEvent(DOMString name,
+                                    WotListener listener,
+                                    optional InteractionOptions options = null);
+        Promise<void> unsubscribeEvent(DOMString name);
+        ThingDescription getThingDescription();
+      };
+      dictionary InteractionOptions {
+        object uriVariables;
+      };
+      typedef object PropertyMap;
+      callback WotListener = void(any data);

                                6.1 +Constructing + +ConsumedThing +

                                +After + +fetching + +a + +Thing +Description + +s +found +during + +as +a +JSON +object, +one +can +create +a + +ConsumedThing + +object. +

                                +To +create + +ConsumedThing + +with + +the +discovery +process. +If +queries +are +not +supported, +implementations +SHOULD +throw + + +ThingDescription + +td +, +run +the +following +steps: +
                                1. +Run +the + +expand + +a +NotSupported + +TD + +steps +on + +td +. +If +that +fails, +re-throw +the + +error +and +terminate +these +steps. +
                                  2. +
                                2. +If + +Let + + +filter.fragment + +thing + +be +a +new + +ConsumedThing + +object. +
                                3. +Let +|td| +be +an +internal +slot +of + +thing + + +is +defined, + +and +if +it +contains +other +properties +than + +let + +td + +be +its +value. +
                                4. +Return + +thing +.

                                6.2 +The + +getThingDescription() + +method +

                                +Returns + +the +ones +defined +in +ThingFragment +, +throw +TypeError +and +terminate +these +steps. +Otherwise +save + +internal +slot +|td| +of + +the + +ConsumedThing + +object +for +matching + +that +represents + +the +discovered +items +against + + +Thing +Description + +of +the + +ConsumedThing +. +Applications +may +consult +the + +Thing + +metadata +stored +in +|td| +in +order +to +introspect +its +capabilities +before +interacting +with + +it. +Request + +

                                6.3 +The + +InteractionOptions + +dictionary +

                                +Holds + +the +underlying +platform + +interaction +options +that +need +to +be +exposed +for +application +scripts +according + +to +start + +the +discovery +process, +with + + +Thing +Description +. +In +this +version +of + +the +following +parameters: +If +filter.method +is +not + +specification +only +URI +template +variables +are +used, +represented +as + +parsed +JSON +objects + +defined +or +the +value +is +"any" +, +use + +in +[WOT-TD]. +

                                Editor's note

                                +The +support +for +URI +variables +comes +from + +the +widest +discovery +method +supported + +need +exposed + +by +the +underlying +platform. +Otherwise +if +filter.method +is +"local" +, + +[WOT-TD] +to +be +able +to +describe +existing + +TD + +s +that + +use +the +local + +them, +but +it +should +be +possible +to +write +a + +Thing +Directory + +Description + + +for +discovery. +Usually + +that +defines +Thing + +would +use + +Action + + +s +deployed +in + +for +representing + +the +same +device, +or +connected +to + +interactions +that +need +URI +variables +and +represent + +the +device +in +slave +mode +(e.g. +sensors +connected +via +Bluetooth +or +a +serial +connection). +Otherwise +if +filter.method +is +"directory" +, +use + +URI +variables +as +parameters +to + +the +remote +Thing +Directory + + +Action + + +specified + +and + +in +that +case +that +could +be +encapsulated +by +the +implementations +and +the + + +filter.url +. +Otherwise +if +filter.method + +options + + +is +"multicast" +, +use +all + +parameter +could +be +dismissed +from + +the +multicast +discovery +protocols +supported + +methods +exposed + +by +this +API. +

                                6.4 +The + +PropertyMap + +type +

                                +Represents +a +map +of + +Property + +names +as +strings +to +a +value +that + +the +underlying +platform. +Whenever + + +Property + +can +take. +It +is +used +as + +a +new +item + +property +bag +for +interactions +that +involve +multiple + +Properties + +at +once. +

                                Editor's note

                                +It +could +be +defined +in +Web +IDL +(as +well +as + +ThingDescription + +) +as +a + +maplike + +interface +from + +string + +to + +any +.

                                6.5 +The + +readProperty() + +method +

                                +Reads +a + +Property + +value. +Takes +a +string +argument + + +td + +propertyName + + +is +discovered +by +the +underlying +platform, + +and +and +an +optional + +InteractionOptions + +options + +argument. +It +returns +a + +Property + +value +represented +as + +any + +type. +The +method +MUST + +run +the +following +sub-steps: + +steps: + +
                                  +
                                1. +If +filter.query +is +defined, +check +if +td +is + +Return + +a +match +for +the +query. +The +matching +algorithm +is +encapsulated +by +implementations. +If +that +returns +false +, +discard + + +Promise + + +td + +promise + + +and +continue + +execute + +the +discovery +process. + +next +steps + +in +parallel +. +
                                  2. +
                                2. +If +filter.fragment + +invoking +this +method + +is +defined, + +not +allowed + +for +each +property +defined +in +it, +check +if +that +property +exists +in + +the +current +scripting +context +for +security +reasons, +reject + + +td + +promise + + +and +has +the +same +value. +If +this +is + +with + + +false + +SecurityError + + +in +any +checks, +discard +td + +and +continue +the +discovery +process. + +terminate +these +steps. + +
                                  3. +
                                3. +Otherwise +if +td +has +not +been +discarded +in + +Make +a +request +to + +the +previous +steps, +invoke + +underlying +platform +(via +the + +Protocol +Bindings + +) +to +retrieve +the +value +of + +the + +Property + +given +by + + +handler + +propertyName + + +function + +with +optional +URI +templates +given +in + + +td +as +parameter. + +options.uriVariables +. +
                                  4. +
                                4. +Whenever +an +error +occurs +during + +If + +the +discovery +process, +and +if + +request +fails, +reject + + +errorHandler + +promise + + +is +defined, +invoke +it + +with +an +argument +of +type +Error +whose +message +property +is +set +to +UnknownError +unless +there +was +an + +the + +error +code +provided +by + +received +from + +the + +Protocol +Bindings +, +in +which +case +set +it +to +that +value. + + +and +terminate +these +steps. + +
                                  5. +
                                5. +When +the +discovery +process +is +finished, +and +if + +Let + + +onComplete + +value + + +is +defined, +invoke +it +run + +be + +the +cancel +discovery +steps. + +result +of +the +request. + +
                                  6. +
                                6. +When +the +obs.unsubscribe() +method +is +called, +run + +Run + +the +following +cancel +discovery + + +validate +Property +value + + +steps: + +sub-steps +on + +value +: +
                                    +
                                  1. +Request + +Based +on + +the +underlying +platform + + +DataSchema +definition +, +value + +MUST +be +a +JSON +value +and +comply + +to +stop + +the +discovery +process. +If +this +returns +an +error, +or +if +it +is +not +possible, + +data +schema +defined + +for +instance +when +discovery +is +based +on +open +ended +multicast +requests, + +the +implementation +SHOULD +discard +subsequent +discovered +items. +Set + + +Property + +that +is +found +in + +this.getThingDescription().properties[ + + +obs.closed + +propertyName + + +to + + +false + +] + +. +
                                    2. +
                                  2. +If +this +fails, +throw + +SyntaxError +, +otherwise +return + +value +.
                                    3. +
                                  +
                                7. +If +these +above +steps +failed, +reject + +promise + +with + +SyntaxError + +and +terminate +these +steps. +
                                8. +Otherwise +resolve + +promise + +with + +value +. +
                                  9. +
                                +
                                3.2 +

                                6.6 +The +fetch() + + +readMultipleProperties() + + +method +

                                Accepts +an +url +

                                Reads +multiple + +Property + +values +with +one +or +multiple +requests. +Takes +the + +propertyNames + +argument +of +type +USVString +that +represents + +as + +a +URL +(e.g. +"file://..." +or +"https://..." +) + +sequence +of +strings + +and +returns +a +Promise + +an +optional + +InteractionOptions + + +that +resolves + + +options + +argument. +It +returns +an +object + +with +a +ThingDescription +(a +serialized +JSON-LD +document +of +type +USVString +). + +keys +from + +propertyNames + +and +values +returned +by +this +algorithm. + +The +fetch(url) + +method +MUST +run +the +following +steps:

                                +
                                  +
                                1. +Return +a + +Promise + + +promise + +and +execute +the +next +steps + +in +parallel +. +
                                  2. +
                                2. +If +invoking +fetch() + +this +method + +is +not +allowed +for +the +current +scripting +context +for +security +reasons, +reject + +promise + +with + +SecurityError + +and +terminate +these +steps. +
                                  3. +
                                3. +If +the +argument + +Let + + +url + +result + + +is +not +a +URL, +reject + +be +an +object +and +for +each +string + + +promise + +name + + +in + +propertyNames + +add +a +property + +with +TypeError + +key + +name + +and +terminate +these +steps. + +the +value + +null +. +
                                  4. +
                                4. +Make +a +request +to +fetch + +the +content +of +url +as +described +by + +underlying +platform +(via + +the + +Protocol +Bindings + +and +wait +for + +) +to +retrieve + +the +reply. +Implementations +encapsulate + + +Property + +values +given +by + +propertyNames + +with +optional +URI +templates +given +in + +options.uriVariables +.
                                5. +If +this +cannot +be +done +with +a +single +request +with + +the +fetching +process +and + + +Protocol +Bindings + +of + +the +accepted +media +types +(such +as + + +Thing +, +then +reject + +promise + +with + + +application/td+json + +NotSupportedError + + +), +as +far +as +a +valid +Thing +Description +can +be +obtained +as +defined + +and +terminate +these +steps. +
                                6. +Process +the +reply +and +update +all +properties + +in +[ +WOT-TD +]. +Let + + +td + +result + + +be +the +Thing +Description +string-serialized +from + +with + +the +returned +content, +as +specified + +values +obtained + +in +the +Thing +Description +serialization +. + +reply. + +
                                  7. +
                                7. +If +there +was +an +error +during + +the +request, + +above +step +fails +at +any +point, + +reject + +promise + +with +an +Error +object +error +with + + +error.message + +SyntaxError + + +set +to +the +error +code +seen +by +the +Protocol +Bindings + +and +terminate +these +steps. +
                                  8. +
                                8. +Otherwise +resolve + +Resolve + + +promise + +with + +td +and +terminate +these +steps. + +result +. +
                                  9. +
                                +
                                3.3 +

                                6.7 +The +consume() + + +readAllProperties() + + +method +

                                Accepts +an +td +argument +

                                Reads +all +properties + +of +type +ThingDescription + +the + +Thing + + +and +returns +a +ConsumedThing + +with +one +or +multiple +requests. +Takes +an +optional + +InteractionOptions + + + +options + +argument. +It +returns +an + +object +instantiated +based +on +parsing +that +description. + +with +keys +from + +Property + +names +and +values +returned +by +this +algorithm. + +The +consume(td) + +method +must + +MUST + +run +the +following +steps:

                                +
                                  +
                                1. +If +the +argument + +Return +a + +Promise + + +td + +promise + + +and +execute +the +next +steps + +in +parallel +.
                                2. +If +invoking +this +method + +is +not +a +string, +throw +a + +allowed +for +the +current +scripting +context +for +security +reasons, +reject + +promise + +with + + +TypeError + +SecurityError + + +and +terminate +these +steps. +
                                  3. +
                                3. +Let + +stub + +result + + +be +an +object +and +for +each +string + +name + +in + +propertyNames + +add +a +property +with +key + +name + +and + +the +result + +value + +null +.
                                4. +Make +a +request +to +the +underlying +platform +(via +the + +Protocol +Bindings + +) +to +retrieve +the +value + +of +running + +the +all +the + +Property + +definitions +from +the + +TD +parsing +algorithm + + +with +optional +URI +templates +given +in + + +td + +options.uriVariables +.
                                5. +If +this +cannot +be +done +with +a +single +request +with +the + +Protocol +Bindings + +of +the + +Thing +, +then +reject + +promise + + +as +argument. + +with + +NotSupportedError + +and +terminate +these +steps. +
                                6. +If +that +throws +an +error, +re-throw + +the +request +fails, +reject + +promise + +with + +the +error +received +from +the + +Protocol +Bindings + +and +terminate +these +steps. +
                                  7. +
                                7. +If + +Process +the +reply +and +update +all +properties +in + + +stub + +result + + +does +not +have +an +own +property +that +is +defined + +with +the +values +obtained + +in +ThingFragment + +the +reply. +
                                8. +Resolve + +promise + +with +a +default +value, +add +that +property +and +value +to + + +stub + +result + +. +
                                  9. +Create + +
                                +

                                6.8 +The + +writeProperty() + +method +

                                +Writes + +a +ConsumedThing + +single + +Property +. +Takes +a +string +argument + +propertyName +, +a +value +argument + +value + +and +an +optional + +InteractionOptions + + +object + + +thing + +options + + +initialized +from + +argument. +It +returns +success +or +failure. +The +method +MUST +run +the +following +steps: +
                                1. +Return +a + +Promise + + +stub + +promise + + +that +implements +Observable + +and +execute +the +next +steps + +in +parallel + +. +
                                  2. +
                                2. +Add + +If +invoking +this +method +is +not +allowed +for + +the +current +scripting +context +for +security +reasons, +reject + +promise + +with + + +read() + +SecurityError + + +and +write() +methods +to + +terminate +these +steps. +
                                3. +Run + +the +ThingProperty + + +validate +Property +value + + +elements +so + +steps +on + +value +. +If + +that +they +make +requests +to +access +the +remote +Thing +s +and +wait +for +the +reply, +as +defined +by +the +Protocol +Bindings +. +Also, +all +ThingProperty + +fails, +reject + +promise + + +elements +SHOULD +implement + +with + + +Observable + +SyntaxError + + +, +i.e. +define + +and +terminate +these +steps. +
                                4. +Make + +a +subscribe() +method +that +should +make + +request +to +observe + +the +given +Properties +as +defined +by + +underlying +platform +(via + +the + +Protocol +Bindings +. +Add +the +invoke() +methods +to +the +ThingAction + + +elements +so +that +they +make +requests + +) +to +write + +value + +to +the +remote +Thing + + +Property + + +to +invoke +its +actions, +as +defined + +given + +by +the +Protocol +Bindings +. + + +propertyName + +with +optional +URI +templates +given +in + +options.uriVariables +. +
                                  5. +
                                5. +Add +the +subscribe() +method +to +all +ThingEvent +elements +so +that +they +make +requests +to +subscribe +to + +If + +the +events +defined +by + +request +fails, +reject + +promise + +with + +the +remote +Thing +, +as +defined +by + +error +received +from + +the + +Protocol +Bindings +. + + +and +terminate +these +steps. + +
                                  6. +
                                6. +Return + +Otherwise +resolve + + +thing + +promise + +. +
                                  7. +
                                +
                                3.4 +

                                6.9 +The +produce() + + +writeMultipleProperties() + + +method +

                                Accepts +

                                Writes + +a +model + +multiple + +Property + +values +with +one +request. +Takes +a + +properties + +argument +of +type +ThingModel + +as +an +object +with +keys +being + +Property + + +names +and +values +as + +Property + +values + +and +returns + +an +ExposedThing + +optional + +InteractionOptions + + +object. + + +options + +argument. +It +returns +success +or +failure. + +The +produce(model) + +method +MUST +run +the +following +steps:

                                +
                                  +
                                1. +Return +a + +Promise + +promise + +and +execute +the +next +steps + +in +parallel +.
                                2. +If +invoking +produce() + +this +method + +is +not +allowed +for +the +current +scripting +context +for +security +reasons, +throw + +reject + +promise + +with + + +SecurityError + +and +terminate +these +steps. +
                                  3. +
                                3. +If +the +argument + +For +each +key + + +model + +name + + +is +a +string, +then +run +the +TD +parsing +algorithm +with + +on + + +model +passed + +properties +, +take +its +value + +as +parameter. +If +it +throws +an +error, +re-throw +that +error +and +terminate +this +algorithm. +Otherwise +let + + +model + +value + + +be + +and +run + +the +returned +value. + + +validate +Property +value + +steps +on + +value +. +If +that +fails +in +for +any + + +model +is +not +an +object, +throw + +name +, +reject + +promise + +with + + +TypeError + +SyntaxError + + +and +terminate +these +steps. +
                                  4. +
                                4. +If +model +does +not +have +an +own +property +that +is +defined +in +ThingFragment +with + +Make + +a +default +value, +add +that +property +and +value + +single +request + +to +model +. +Create +an +ExposedThing + +the +underlying +platform +(via +the + +Protocol +Bindings + + +object + +) +to +write +the +each + +Property + +provided +in + + +thing + +properties + + +initialized +from + +with +optional +URI +templates +given +in + + +model + +options.uriVariables + +. +
                                  5. +
                                5. +For +each +property +of +ExposedThing +defined +in +ThingFragment +, +initialize +the +property +based +on +the +provided +initial +or +default +values +provided +to +the +local +WoT +Runtime +implementation, +for +instance +initialize: +the +id +property +to + +If +this +cannot + +be +done +with +a +single +request +with + +the +final +unique +identifier + + +Protocol +Bindings + +of +the + +Thing +, +the +security +object +of +type + +then +reject + +promise + +with + + +SecurityScheme + +NotSupportedError + + +to +represent +the +actual +security +scheme + +and +its +properties +as +set +up +by +the +implementation, + +terminate +these +steps. + +
                                  6. +
                                6. +If + +the +properties +property +to +be +an +object +with +all +properties +being +ThingProperty +objects +in +which + +request +fails, +return + +the +read() +and +write() +methods +are +provided +to +define +local +methods +to +get +and +set + +error +received +from + +the +Property + + +Protocol +Bindings + + +values, + +and +terminate +these +steps. + +
                                  7. +
                                7. +the + +Otherwise +resolve + +promise +.

                                6.10 +The + +WotListener + +callback +

                                +User +provided +callback +that +takes + + +actions + +any + + +property + +argument +and +is +used +for +observing + +Property + +changes +and +handling + +Event + +notifications. +Since +subscribing + +to +be +an +object + +these +are +WoT +interactions, +they +are +not +modelled + +with +all +properties +being +ThingAction +objects +in +which +the +invoke() + +software +events. +

                                6.11 +The + +observeProperty() + +method +is +provided +to +define + +

                                Makes + +a +local + +request +for + +Property + +value +change +notifications. +Takes +a +string +argument + +propertyName +, +a + +WotListener + +callback +function + +listener + +and +an +optional + +InteractionOptions + +options + +argument. +It +returns +success +or +failure. +The + +method +to + +MUST + +run +the +defined +Action + +following +steps: +

                                1. +Return +a + +Promise + + +s, + + +promise + +and +execute +the +next +steps + +in +parallel +. +
                                  2. +
                                2. +If +invoking +this +method +is +not +allowed +for + +the +events +property +to +be +an +object + +current +scripting +context +for +security +reasons, +reject + +promise + +with +all +properties +being + + +ExposedEvent +objects +in +which +the +emit() + +SecurityError + + +method +is +provided +to +define +a +local +way +to +trigger +sending +notifications +to +all +subscribed +clients, + +and +initialize +the +other +properties +as +initialized +from +model +. + +terminate +these +steps. + +
                                  3. +
                                3. +Return + +If + + +thing +. +The +TD +parsing +algorithm +takes + +listener + +is +not + +a +string + +function, +reject + + +td + +promise + + +as +argument + +with + +"TypeError" + +and +runs +the +following +steps: + +terminate +these +steps. +
                                  4. +
                                4. +Parse +td +according + +Make +a +request + +to +the +WoT +Thing +Description + +underlying +platform +(via +the + +Protocol +Bindings + + +in +order + +) + +to +produce +a +JSON +object + +observe + +Property + + +identified +by + + +json +. +Update +thing + +propertyName + + +with +the +properties +and +values +defined + +optional +URI +templates +given + +in + +json + +options.uriVariables + +. +
                                  5. +
                                5. +If +there +was +an +error +during + +the +parsing, +throw +that + +request +fails, +reject + +promise + +with +the + +error +received +from +the + +Protocol +Bindings + +and +terminate +these +steps. +
                                  6. +
                                6. +Otherwise +return + +resolve + + +json + +promise + +. +
                                  7. +3.5 +The +register() +method +Takes +two +mandatory +arguments: +directory +denoting +a +Thing +Directory +, +and + +
                                7. +thing +denoting +an +ExposedThing +object. +Generate + +Whenever + +the +Thing +Description + +underlying +platform +receives +a +notification +for +this +subscription +with +new + +Property + + +as + +value + + +td + +value + +, +given + +run + +the +Properties +, +Action +s +and +Event +s +defined +for +this +ExposedThing + +following +sub-steps: +
                                  • +If +running +the + +validate +Property +value + + +object. +Then +make +a +request +to +register + +steps +on + + +td + +value + + +to +the +given +WoT +Thing +Directory +. + +fails, +terminate +these +steps. +
                                  • +Invoke + +listener + +with + +value + +as +parameter. +
                                3.6 +

                                6.12 +The +unregister() + + +unobserveProperty() + + +method +

                                Makes +a +request +for +unsubscribing +from + +Property + +value +change +notifications. + +Takes +two +mandatory +arguments: + +a +string +argument + +propertyName + +and +returns +success +or +failure. +The +method +MUST +run +the +following +steps: +

                                  +
                                1. +directory +denoting + +Return + +a +Thing +Directory +, + + +Promise + +promise + +and +execute +the +next +steps + +in +parallel +. +
                                  2. +
                                2. +If +invoking +this +method +is +not +allowed +for +the +current +scripting +context +for +security +reasons, +reject + +promise + +with + + +thing +denoting +an +ExposedThing + +SecurityError + + +object. + +and +terminate +these +steps. + +
                                  3. +Makes + +
                                3. +Make + +a +request +to +unregister + +the +thing +from + +underlying +platform +(via + +the +given +WoT +Thing +Directory +. +3.7 +Examples +Example +1 + + +Protocol +Bindings + + +: +Discover +Things +via +directory +discoveryFilter = { +, + +

                                  }; +subscription = wot.discover(discoveryFilter).subscribe( +{

                                  +
                                    +
                                  • td.name);
                                    • +
                                  +

                                  thing = wot.consume(td); +}, +error => { + error.message); }, +() => { );} +); +setTimeout( { +subscription.unsubscribe(); +); +}, +5000 +); +Example +2 +

                                  ) +to +stop +observing +the + +Property + + +: +Discover +Things +exposed + +identified + +by +local +hardware +}).subscribe(

                                  + +
                                    +
                                  • td.name); }, +error => { + error.message); }, +() => { );} +); +Example +3 +: +Same +as +above +but + +propertyName +. +
                                  • +If +the +request +fails, +reject + +promise + +with +different +Observable +syntax +}).subscribe({ +td => { + td.name); },
                                    • +
                                  • err.message); }, +);} +}); +the +error +received +from +the + +Protocol +Bindings + +and +terminate +these +steps. +
                                  • +Otherwise +resolve + +promise +.
                                    • +
                                   +
                                  4. +
                                +
                                4. +

                                6.13 +The +ConsumedThing + + +invokeAction() + + +interface +Represents +an +object +that +extends + +method +

                                +Makes + +a +ThingFragment +with +methods +for +client +interactions +(send + +request +for +reading +and +writing +Properties +), +invoke + +invoking +an + +Action + +s, +subscribe + +and +unsubscribe +for +Property +changes +and +Event +s. + +

                                readonly attribute +readonly attribute +readonly attribute +readonly attribute +readonly attribute +readonly attribute +// getter for ThingFragment properties

                                +

                                }; +[] +interface +readonly maplike< +}; +[] +interface +readonly maplike< +}; +[] +interface +readonly maplike< +}; +ConsumedThing +includes +

                                return +the +result. +Takes +a +string +argument + +actionName +, +an +optional +argument + +params + +of +type + + +Observable + +any + + +and +an +optional + +InteractionOptions + + +; +// +for +TD +changes +The +id +attribute +represents + + +options + +argument. +It +returns + +the +unique +identifier + +result + +of +the +Thing + + +Action + + +instance, +typically +a +URI, +IRI, + +or +URN +as +USVString +. + +an +error. + +The +name +attribute +represents +the +name +of + +method +MUST +run + +the +Thing + +following +steps: +

                                +
                                1. +Return +a + +Promise + + +as +DOMString +. +The +base +attribute +represents + + +promise + +and +execute + +the +base +URI +that + +next +steps + +in +parallel +.
                                2. +If +invoking +this +method + +is +valid + +not +allowed + +for +all +defined +local +interaction +resources. +The +properties +attribute +represents +a +dictionary +of +ThingProperty +items. +The +PropertyMap +interface +represents +a +maplike +dictionary +where +all +values +are +ThingProperty +objects. +The + +the +current +scripting +context +for +security +reasons, +reject + +promise + +with + + +read() + +SecurityError + + +and +write() +methods +make + +terminate +these +steps. +
                                3. +Make + +a +request +to +access + +the +Properties +on + +underlying +platform +(via + +the +remote +Thing +represented +by +this +ConsumedThing +proxy +object. +The +actions +attribute +represents +a +dictionary +of +ThingAction +items. +The +ActionMap +interface +represents +a +maplike +dictionary +where +all +values +are +ThingAction + + +Protocol +Bindings + + +objects. +The +invoke() +method +represents +a +request + +) + +to +invoke +the + +Action + +on +the +remote +Thing +. +The +events +attribute +represents +a +dictionary +of +ThingEvent +items. +The +EventMap +interface +represents +a +maplike +dictionary +where +all +values +are +ThingEvent +objects. +Subscribing +to + +identified +by + +actionName + +with +parameters +provided +in + +params + +with +optional +URI +templates +given +in + +options.uriVariables +.
                                4. +If + +the +events +involves +setting +up + +request +fails +locally +or +returns + +an +observation +(subscription) +mechanism +on +the +remote +object. +4.1 +Examples +Below +a +ConsumedThing +interface +example +is +given. +Example +4 +: +Consume +a +Thing +{ +}).subscribe( +{ +thing = wot.consume(td); +); +{ +
                                    +
                                  • value); +}); +thing.actions[ }) +.then(); }) +.catch( { +); +subscription.unsubscribe(); +}) +}, +error => { + error.message); }, +() => { );} +); +} (error) {
                                      +
                                    • error.message); +};
                                      • +
                                    +5. +The +ExposedThing +interface +The +ExposedThing +interface +is +error +over + +the +server +API +that +allows +defining +request +handlers, +properties, +Actions +, +and +Events +to +a +Thing +. +It +also +implements + +network, +reject + +promise + +with + +the +Observable +interface. +An +ExposedThing +is +created +by + +error +received +from + +the +produce() +method. +
                                    • +
                                  +

                                  readonly attribute +readonly attribute +readonly attribute +// getter for ThingFragment properties

                                  +

                                  // setter for ThingFragment properties

                                  +

                                  // methods to expose and destroy the Thing

                                  +

                                  // define Properties

                                  +

                                  // define Actions

                                  +

                                  // define Events

                                  +

                                  }; +[] +interface +maplike< +}; +callback +callback +callback +ActionHandler += +Promise +< +any +

                                  +
                                  +
                                  +

                                  ( +any +parameters +); +The +properties +attribute +represents +a +dictionary +of +ThingProperty + + +Protocol +Bindings + + +items +in +which +the +read() + +and +write() +methods +define +local +methods +that +access +the +physical +representations +of + +terminate +these +steps. + +

                                  +                                   +
                                5. +Otherwise +let + +value + +be + +the +Properties +. +The +actions +attribute +represents +a +dictionary +of +ThingAction +items + +result +returned + +in +which + +the +invoke() +method +represents +a +local +method +to +invoke + +reply +and +run + +the +Action +. +The +events +attribute +represents +a +dictionary +of +ExposedEvent + + +validate +Property +value + + +items + +steps +on +it. +If + +that +add +the +emit() +method +to +the +ThingEvent +definition. +The +ExposedEvents +interface +represents +a +maplike +dictionary +where +all +values +are + +fails, +reject + +promise + +with + + +ExposedEvent + +SyntaxError + + +objects. +5.1 + +and +terminate +these +steps. +
                                6. +Reject + +promise + +with + +value +.
                                  7. +
                                +                                 +

                                6.14 +The +expose() + + +subscribeEvent() + + +method +

                                Start +serving +external +requests +

                                Makes +a +request + +for +the +Thing +, +so +that +WoT +Interactions + +subscribing +to + +Event + + +using +Properties +, +Action + +notifications. +Takes +a +string +argument + +eventName +, +a + +WotListener + + +s + +callback +function + +listener + +and +Event + +an +optional + +InteractionOptions + + +s +will +be +possible. + + +options + +argument. +It +returns +success +or +failure. + +The +expose() + +method +MUST +run +the +following +steps:

                                +
                                  +
                                1. +Return +a + +Promise + + +promise + +and +execute +the +next +steps + +in +parallel +. +
                                  2. +
                                2. +If +invoking +expose() + +this +method + +is +not +allowed +for +the +current +scripting +context +for +security +reasons, +reject + +promise + +with + +SecurityError + +and +terminate +these +steps. +
                                  3. +
                                3. +If + +listener + +is +not +a +function, +reject + +promise + +with + +"TypeError" + +and +terminate +these +steps. +
                                4. +Make +a +request +to +the +underlying +platform +to +attach +protocol +handlers +and +start +serving +external +requests +for +WoT +Interactions +(read, +write +and +observe +Properties +, +invoke +Action +s +and +manage +Event +subscriptions), +based +on + +(via + +the + +Protocol +Bindings +. + + +) +to +subscribe +to +an + +Event + +identified +by + +eventName + +with +optional +URI +templates +given +in + +options.uriVariables +. +
                                  5. +
                                5. +If +there +was +an +error +during + +the +request, + +request +fails, + +reject + +promise + +with +an +Error +object +error +with +error.message +set +to + +the +error +code +seen +by + +received +from + +the + +Protocol +Bindings + +and +terminate +these +steps. +
                                  6. +
                                6. +Otherwise +resolve + +promise +with + +. +
                                  7. +
                                7. +Whenever +the +underlying +platform +receives +a +notification +for +this + +Event + +subscription, +implementations +SHOULD +invoke + + +td +and +terminate +these +steps. + +listener +, +giving +the +data +provided +with +the + +Event + +as +parameter. + +
                                  8. +
                                +
                                5.2 +

                                6.15 +The +destroy() + + +unsubscribeEvent() + + +method +

                                Stop +serving +external +requests +

                                Makes +a +request + +for +the +Thing + +unsubscribing +from + +Event + + +notifications. +Takes +a +string +argument + +eventName + +and +destroy +the +object. +Note +that +eventual +unregistering +should +be +done +before +invoking +this +method. + +returns +success +or +failure. + +The +destroy() + +method +MUST +run +the +following +steps:

                                +
                                  +
                                1. +Return +a + +Promise + + +promise + +and +execute +the +next +steps + +in +parallel +. +
                                  2. +
                                2. +If +invoking +destroy() + +this +method + +is +not +allowed +for +the +current +scripting +context +for +security +reasons, +reject + +promise + +with + +SecurityError + +and +terminate +these +steps. +
                                  3. +
                                3. +Make +a +request +to +the +underlying +platform +to +stop +serving +external +requests +for +WoT +Interactions +, +based +on + +(via + +the + +Protocol +Bindings +. + + +) +to +unsubscribe +from +the + +Event + +identified +by + +eventName +. +
                                  4. +
                                4. +If +there +was +an +error +during + +the +request, + +request +fails, + +reject + +promise + +with +an +Error +object +error +with +error.message +set +to + +the +error +code +seen +by + +received +from + +the + +Protocol +Bindings + +and +terminate +these +steps. +
                                  5. +
                                5. +Otherwise +resolve + +promise +with +td +and +terminate +these +steps. + +. +
                                  6. +
                                +
                                5.3 +The +addProperty() +method +

                                6.16 +ConsumedThing +Examples +

                                +Adds + +The +next +example +illustrates +how +to +fetch + +a +Property + + +TD + + +with +name +defined +by +the +name +argument, +the +data +schema +provided + +by +the +property +argument +of +type +PropertyFragment + +URL, +create +a + +ConsumedThing + +, +and +optionally +an +initial +value +provided +in +the +argument +initValue +whose +type +should +match +the +one +defined +in +the +type + +read +metadata +(title), +read + +property +according + +value, +subscribe + +to +the +value-matching +algorithm +. +If +initValue +is +not +provided, +it +SHOULD +be +initialized +as +undefined +. +Implementations +SHOULD +update +the +Thing +Description +. +Throws +on +error. +Returns +a +reference + +property +change, +subscribe + +to +the +same +object +for +supporting +chaining. + +a +WoT +event, +unsubscribe. + +

                                +
                                + Example 2: Thing Client API example + 
                                        try {
+          let res = await fetch("https://tds.mythings.org/sensor11");
+          let td = res.json();
+          let thing = new ConsumedThing(td);
+          console.log("Thing " + thing.getThingDescription().title + " consumed.");
+        } catch(e) {
+          console.log("TD fetch error: " + e.message); },
+        };
+        try {
+          // subscribe to property change for “temperature”
+          await thing.observeProperty("temperature", value => {
+            console.log("Temperature changed to: " + value);
+          });
+          // subscribe to the “ready” event defined in the TD
+          await thing.subscribeEvent("ready", eventData => {
+            console.log("Ready; index: " + eventData);
+            // run the “startMeasurement” action defined by TD
+            await thing.invokeAction("startMeasurement", { units: "Celsius" });
+            console.log("Measurement started.");
+          });
+        } catch(e) {
+          console.log("Error starting measurement.");
+        }
+        setTimeout( () => {
+          console.log(“Temperature: “ + await thing.readProperty(“temperature”));
+          await thing.unsubscribe(“ready”);
+          console.log("Unsubscribed from the ‘ready’ event.");
+        },
+        10000);
+
                                +
                                5.4 +

                                7. +The +removeProperty() + + +ExposedThing + + +method + +interface +

                                +Removes +the +Property + +The + +ExposedThing + + +specified +by +the +name +argument +and +updates + +interface +is + +the +Thing +Description +. +Throws +on +error. +Returns +a +reference + +server +API + +to +operate + +the +same +object +for +supporting +chaining. + + +Thing + +that +allows +defining +request +handlers, + +Property +, +Action +, +and + +Event + +interactions. + +

                                5.5 +The +
                                      [SecureContext, Exposed=(Window,Worker)]
+      interface ExposedThing: ConsumedThing {
+        ExposedThing setPropertyReadHandler(DOMString name,
+                PropertyReadHandler readHandler);
+        ExposedThing setPropertyWriteHandler(DOMString name,
+                PropertyWriteHandler writeHandler);
+        ExposedThing setActionHandler(DOMString name, ActionHandler action);
+        void emitEvent(DOMString name, any data);
+        Promise<void> expose();
+        Promise<void> destroy();
+      };
+      callback PropertyReadHandler = Promise<any>(
+              optional InteractionOptions options = null);
+      callback PropertyWriteHandler = Promise<void>(any value,
+              optional InteractionOptions options = null);
+      callback ActionHandler = Promise<any>(any params,
+              optional InteractionOptions options = null);

                                7.1 +Constructing + + +addAction() + +ExposedThing + + +method + +

                                +Adds +to +the + +The + + +actions + +ExposedThing + + +property +of + +interface +extends + +ConsumedThing +. +It +is +constructed +from + +a +Thing + +full +or +partial + +ThingDescription + + +object + +object. +

                                Note

                                +Note +that + +an +Action + +existing + +ThingDescription + + +with +name +defined + +object +can +be +optionally +modified +(for +instance + +by +the + +adding +or +removing +elements +on +its + + +name + +properties +, +actions + + +argument, +defines +input + +and +output +data +format +by +the + + +init + +events + + +argument +of +type +ActionFragment +, + +internal +properties) + +and +adds + +the +function +provided +in + +resulting +object +can +used +for +constructing +an + +ExposedThing + +object. +This +is + +the +action +argument + +current +way +of +adding +and +removing + +Property +, +Action + +and + +Event + +definitions, + +as +a +handler, +then +updates + +illustrated +in + +the +Thing +Description + + +examples + +. +Throws +on +error. +Returns +a +reference +to + +

                                Note

                                +Before +invoking + +expose() +, +the +same + + +ExposedThing + +object +for +supporting +chaining. + +does +not +serve +any +requests. +This +allows +first +constructing + +ExposedThing + +and +then +initialize +its + +Properties + +and +service +handlers +before +starting +serving +requests. + +

                                The +provided +action +callback +function +will +implement +invoking +

                                To +construct + +an +Action + + +ExposedThing + + +and +SHOULD +be +called +by +implementations +when +a +request +for +invoking + +with + +the +Action + + +ThingDescription + + + +td +, +run +the +following +steps: +

                                1. +If +invoking +this +method + +is +received +from + +not +allowed +for + +the +underlying +platform. +The +callback +will +receive +a + +current +scripting +context +for +security +reasons, +throw + + +parameters + +SecurityError + + +dictionary +argument +according +to + +and +terminate +these +steps. +
                                2. +Run + +the +definition +in + + +expand +a +TD + +steps +on + +td +. +If +that +fails, +re-throw + +the +error +and +terminate +these +steps. +
                                3. +Let + + +init.input + +thing + + +argument +and +will +return + +be + +a +value + +new + +ExposedThing + +object. +
                                4. +Let +|td| +be +an +internal +slot + +of +type +defined +by +the + + +init.output + +thing + +and +let + +td + + +argument +according +to +the +value-matching +algorithm +. +There +SHOULD + +be +exactly +one +handler +for +any +given +Action +. +If +no +handler +is +initialized +for +any +given +Action +, +implementations +SHOULD +throw +a +TypeError +. + +its +value. +
                                5. +Return + +thing +.
                                +
                                5.6 +The +removeAction() +method +

                                7.2 +Methods +inherited +from + +ConsumedThing + + +

                                +Removes +the +Action +specified +by + +The + +readProperty() +, +readMultipleProperties() +, +readAllProperties() +, +writeProperty() +, +writeMultipleProperties() +, +writeAllProperties() + +methods +have + +the +same +algorithmic +steps +as +described +in + + +name + +ConsumedThing + + +argument +and +updates + +, +with + +the +Thing +Description +. +Throws +on +error. +Returns + +difference +that +making + +a +reference + +request + +to +the +same +object +for +supporting +chaining. + +underlying +platform +MAY +be +implemented +with +local +methods +or +libraries +and +don't +necessarily +need +to +involve +network +operations. + +

                                5.7 +

                                +The +addEvent() +method + +implementation +of + +ConsumedThing + + +Adds + +interface +in + +an +event + + +ExposedThing + +provide +the + +default + +methods +to +interact + +with +name +defined +by + +the +name +argument + + +ExposedThing +.

                                +After +constructing +an + +ExposedThing +, +a +script +can +initialize +its + +Properties + +and +qualifiers + +can +set +up +the +optional +read, +write + +and +initialization +value + +action +request +handlers +(the +default +ones +are + +provided +by +the +event +argument +of +type +EventFragment +to + +implementation). +The +script +provided +handlers +MAY +use + +the +Thing +object +and +updates + +default +handlers, +thereby +extending + +the +Thing +Description +. +Throws +on +error. +Returns +a +reference +to + +default +behavior, +but +they +can +also +bypass +them, +overriding + +the +same +object +for +supporting +chaining. + +default +behavior. +Finally, +the +script +would +call + +5.8 +The + + +removeEvent() + +expose() + + +method + + +Removes +the +event +specified +by +the +name +argument +and +updates + +on + +the +Thing +Description +. +Returns +a +reference + + +ExposedThing + +in +order + +to +the +same +object +for +supporting +chaining. + +start +serving +external +requests. + +

                                5.9 +

                                7.3 +The + +PropertyReadHandler + +callback +

                                +A +function +that +is +called +when +an +external +request +for +reading +a + +Property + +is +received. + +received +and +defines +what +to +do +with +such +requests. + +It +should +return + +returns + +a + +Promise + +and +resolves +it +with + +when + +the +value +of +the + +Property + +matching +the + +name + +argument +to +the +setPropertyReadHandler +function, +or +rejects +with +an +error +if +the +property +is +not +found +or +the +value +cannot +be +retrieved. +5.10 +The +PropertyWriteHandler +callback +A +function +that +is +called +when +an +external +request +for +writing +a +Property +is +received. +It +is +given +the +requested +new +value +as +argument +and +should +return +a +Promise +which + +is +resolved +when +the +value +of +the +Property +that +matches +the +name +argument +has +been +updated +with +value +, + +obtained, + +or +rejects +with +an +error +if +the +property +is +not +found +or +the +value +cannot +be +updated. +Editor's +note +Note +that +this +function +is +invoked +by +implementations +before +the +property +is +updated +and +it +actually +defines +what +to +do +when +a +write +request +is +received. +The +code +in +this +callback +function +can +invoke +the +read() +method +to +find +out +the +old +value +of +the +property, +if +needed. +Therefore +the +old +value +is +not +provided +to +this +function. +5.11 +The +ActionHandler +callback +A +function +called +with +a +parameters +dictionary +argument +assembled +by +the +WoT +runtime +based +on +the +Thing +Description +and +the +external +client +request. +It +returns +a +Promise +that +rejects +with +an +error +or +resolves +if +the +action +is +successful +or +ongoing +(may +also +resolve +with +a +control +object +such +as +an +Observable +for +actions +that +need +progress +notifications +or +that +can +be +canceled). + +retrieved. + +

                                5.12 +

                                7.4 +The + +setPropertyReadHandler() + +method +

                                +Takes + +name + +as +string +argument +and + +readHandler + +as +argument +of +type + +PropertyReadHandler +. +Sets +the +service + +handler +function + +for +reading +the +specified + +Property + +matched +by + +name +. +Throws +on +error. +Returns +a +reference +to +the +same + + +this + +object +for +supporting +chaining. +

                                +The + +readHandler + +callback +function +will + +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 +SHOULD + +MUST + +be +at +most +one +handler +for +any +given + +Property +and + +, +so + +newly +added +handlers +MUST + +replace +the +old + +previous + +handlers. +If +no +handler +is +initialized +for +any +given + +Property +, +implementations +SHOULD +implement +a +default +property +read +handler. + +handler +based +on +the + +Thing +Description +. +

                                7.5 +Handling + +Property + +read +requests +

                                When +an +external + +a +network + +request +for +reading + +Property + + +propertyName + +is +received, + +received +by + +the +runtime +SHOULD +execute + +implementation, +run + +the +following +steps:

                                +
                                  +
                                1. +Return +a +Promise +promise +and +execute +the +next +steps +in +parallel +. + +If +a + +Property + +with + +propertyName + +does +not +exist, +reject +promise +with +a + +return + + +ReferenceError + +in +the +reply + +and +terminate +these +steps. +
                                  2. +
                                2. +Otherwise, +if +no + +If +there +is +a +user +provided + +read +handler +has +been +defined +for + +registered +with + +setPropertyReadHandler() +, +invoke +that +wih + + +propertyName +, +resolve +promise +with + +return + +the +value +of +the +Property +named +propertyName +provided +by + +with + +the +runtime +implementation + +reply + +and +terminate +these +steps. +
                                  3. +
                                3. +Otherwise, +if +there +is +a +default +read +handler +provided +by +the +implementation, + +invoke +it +with + +propertyName +, +return + +the +read + +value +with +the +reply +and +terminate +these +steps. +
                                4. +if +there +is +no +default + +handler +associated + +defined +by +the +implementation, +return + +NotSupportedError + +with +the +reply +and +terminate +these +steps. +

                                7.6 +Handling + +Property + +observe +requests +

                                +When +a +network +request +for +observing +a + +Property + + +propertyName +. + + +is +received +by +the +implementation, +run +the +following +steps: +
                                1. +If +it +rejects, +then +reject + +a + +Property + +with + + +promise + +propertyName + + +with + +does +not +exist, +return +an +error +in + +the +same +error, +and +resolve +promise + +reply +(as +defined +in +the + +Thing +Description + + +with + +) +and +terminate +these +steps. +
                                2. +Save + +the +same +value. + +request +sender +information +to +the + +Property + +'s + +internal +observer +list + +in +order +to +be +able +to +notify +about + +Property + +value +changes. + +
                                  3. +
                                +
                                5.13 +

                                7.7 +The + +PropertyWriteHandler + +callback +

                                +A +function +that +is +called +when +an +external +request +for +writing +a + +Property + +is +received +and +defines +what +to +do +with +such +requests. +It +expects +the +requested +new + + +setPropertyWriteHandler() + +value + + +as +argument +and +returns +a + +Promise + +which +is +resolved +when +the +value +of +the + +Property + +that +matches +the + +name + +argument +has +been +updated +with + +value +, +or +rejects +with +an +error +if +the +property +is +not +found +or +the +value +cannot +be +updated. +

                                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. +

                                7.8 +The + +setPropertyWriteHandler() + + +method +

                                +Takes + +name + +as +string +argument +and + +writeHandler + +as +argument +of +type + +PropertyWriteHandler +. +Sets +the +service + +handler +function + +for +writing +the +specified + +Property + +matched +by + +name +. +Throws +on +error. +Returns +a +reference +to +the +same + + +this + +object +for +supporting +chaining. +

                                +There +SHOULD + +MUST + +be +at +most +one +write +handler +for +any +given + +Property +and + +, +so + +newly +added +handlers +MUST + +replace +the +old + +previous + +handlers. +If +no +write +handler +is +initialized +for +any +given + +Property +, +implementations +SHOULD +implement +default +property +update +and +notifying +observers +on +change. + +change, +based +on +the + +Thing +Description +. +

                                7.9 +Handling + +Property + +write +requests +

                                When +an +external + +a +network + +request +for +writing +a + +Property + + +propertyName + +with +a +new +value + +value + +is +received, +the +runtime + +implementations + +SHOULD +execute + +run + +the +following +steps: +Return +a +Promise +promise +and +execute +the +next + + +update +property + +steps +in +parallel +. + +, +given + +propertyName +, +value + +and + +mode + +set +to + +"single" +:

                                  +
                                1. +If +a + +Property + +with + +propertyName + +does +not +exist, +reject +promise +with +a + +return + + +ReferenceError + +in +the +reply + +and +terminate +these +steps. +
                                  2. +
                                2. +Otherwise, + +If +there +is +a +user +provided +write +handler +registered +with + +setPropertyWriteHandler() +, +or + +if +no + +there +is +a +default + +write +handler, +
                                  1. +Invoke +the + +handler +has +been +defined +for + +with + + +propertyName +, + +. +If +it +fails, +return + +the +runtime +implementation +SHOULD +update + +error +in + +the +reply +and +terminate +these +steps. +
                                  2. +Otherwise, +if + +mode + +is + +"single" +, +reply +to +the +request +with +the +new +value, +following +to +the + +Protocol +Bindings +.
                                  3. +For +each +item +stored +in +the + +internal +observer +list + +of +the + +Property + +value + +with + +value + +propertyName + +, +resolve +promise + +send +an +observe +reply +with +the +new +value +attached. +
                                3. +If +there +is +no +handler +to +handle +the +request, +return + +NotSupportedError + +in +the +reply + +and +terminate +these +steps. +
                                  4. +Otherwise, +invoke + +
                                +
                                > +
                                +When +a +network +request +for +writing +multiple + +Properties + +given +in +an +object + +propertyNames + +is +received, +run + +the +write +handler +associated + +following +steps: +
                                1. +For +each +property + +with +key + + +propertyName + +name + + +providing + +and +value + + +value + +as +argument. +If +it +rejects, +then +reject + +defined +in + + +promise +with + +propertyNames +, +run + +the +same +error, +and +resolve +promise + + +update +property +steps + + +with + +name +, +value + +and + +mode + +set +to + +"multiple" +.
                                2. +Reply +to + +the +same +value. + +request +(by +sending +a +single +or +multiple +replies) +according +to +the + +Protocol +Bindings + +defined +for +the + +Property +. +
                                  3. +
                                +
                                5.14 +

                                7.10 +The + +ActionHandler + +callback +

                                +A +function +that +is +called +when +an +external +request +for +invoking +an + +Action + +is +received +and +defines +what +to +do +with +such +requests. +It +is +invoked +with +a + + +setActionHandler() + +params + + +dictionary +argument. +It +returns +a + +Promise + +that +rejects +with +an +error +or +resolves +if +the +action +is +successful. +

                                7.11 +The + +setActionHandler() + + +method +

                                +Takes + +name + +as +string +argument +and + +action + +as +argument +of +type + +ActionHandler +. +Sets +the +handler +function +for +the +specified + +Action + +matched +by + +name +. +Throws +on +error. +Returns +a +reference +to +the +same + + +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 +SHOULD + +MUST + +be +at +most +one +handler +for +any +given + +Action +and + +, +so + +newly +added +handlers +MUST + +replace +the +old + +previous + +handlers. +

                                7.12 +Handling + +Action + +requests +

                                When +an +external + +a +network + +request +for +invoking +the + +Action + +identified +by + +name + +is +received, +the +runtime +SHOULD +execute +the +following +steps:

                                +
                                  +
                                1. +Return +a +Promise +promise +and +execute +the +next +steps +in +parallel +. + +If +an + +Action + +identified +by + +name + +does +not +exist, +reject +promise +with +a + +return + + +ReferenceError + +in +the +reply + +and +terminate +these +steps. +
                                  2. +
                                2. +Otherwise, +if +no + +If +there +is +a +user +provided + +action +handler +has +been +defined +for + +registered +with + +setActionHandler() +, +invoke +that +wih + + +name +, +reject +promise + +return +the +resulting +value + +with +a +ReferenceError + +the +reply + +and +terminate +these +steps. +
                                  3. +
                                3. +Otherwise, +invoke +the +Action +handler +associated +with +name +. +If +it +rejects +with +error +, +then +reject +promise +with +the +same +error +, +otherwise +if +it +resolves +with +value +, +then +resolve +promise + +Otherwise +return + +NotSupportedError + + +with +the +same +value +. + +reply +and +terminate +these +steps. + +
                                  4. +
                                +
                                5.15 +Examples +

                                7.13 +The + +emitEvent() + +method + +

                                Below +some +ExposedThing +interface +examples +are +given. +Example +5 +: +Create +a +new +exposed +Thing +with +a +simple +property +{ +temperatureValueDefinition = { +, +, + +

                                }; +temperaturePropertyDefinition = temperatureValueDefinition;

                                +

                                temperaturePropertyDefinition.forms = [ ... ]; +thing = WoT.produce({ +, +: { +: temperaturePropertyDefinition +}, +: { +: { +, +: { +: temperatureValueDefinition +}, +, +: [] +}, +}, +: { +: temperatureValueDefinition +}, +: [] +}); +thing.expose(); +, thing);

                                +

                                setInterval( () => { +; +].read(); +(old < mock) { +].write(mock); +thing.emitEvent(, mock); +} +}, ); +} (err) {

                                +
                                  +
                                • err); +} +Example +6 +: +Create +a +new +exposed +Thing +with +object +property +{ +statusValueDefinition = { +, +: { +: { +, +, +,
                                  • +
                                +

                                }, +: { +, +, +, +: { +, +,

                                +

                                } +} +}; +statusPropertyDefinition = statusValueDefinition;

                                +

                                statusPropertyDefinition[] = []; +thing = WoT.produce({ +, +: { +: { +, +, +, +, +}, +: statusPropertyDefinition +}, +: { +: { +, +, +: { +: statusValueDefinition; +}, +: [] +}, +}, +: { +: statusValueDefinition; +}, +: [] +}); +thing.expose().then( { +thing.register(); +}); +} (err) {

                                +
                                  +
                                • err); +} +Example +7 +: +Create +a +new +exposed +Thing +from +a +Thing +Description +'{
                                  "name": "mySensor",
                                  "@context": [ "http://www.w3.org/ns/td",\ +"https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ],
                                  "@type": [ "Thing", "Sensor" ],
                                  "geo:location": "testspace",
                                  "properties": {
                                  "prop1": {
                                  "type": "number",
                                  "@type": [ "Property", "Temperature" ],
                                  "saref:TemperatureUnit": "degree_Celsius"
                                  } } }'; +{
                                  • +
                                +

                                thing = WoT.produce(thingDescription);

                                +

                                ; +thing.setPropertyReadHandler(name, () => {

                                +
                                  +
                                • name); +{ +; +resolve(examplePropertyValue); +}, +e => { +); +}); +}); +thing.expose(); +} (err) {
                                  • +
                                • err); +} +Example +8 +

                                  Takes + +name + +as +string +argument +denoting +an + +Event + + +: +Create +a +new +exposed +Thing +from +a +TD +URI

                                  +

                                  WoT.fetch( {

                                  +

                                  thing = WoT.produce(td);

                                  +

                                  });

                                  • +
                                +

                                6. +Data +types

                                +

                                name, + +and +structures + +a + +data + +argument +of + +any + +type. + +The +[ +WOT-TD +] +specification +defines + +method +MUST +run + +the +WoT +information +model +, +i.e. + +following +steps: +

                                +
                                1. +If +invoking +this +method +is +not +allowed +for + +the +data +types + +current +scripting +context +for +security +reasons, +throw + +SecurityError + +and +data +structures +used +in +WoT +Interactions +. +In +this +API + +terminate + +these +definitions +translate +to +dictionary +objects +that +are +extended + +steps. +
                                2. +If +an + +Event + +with +methods +by + +the +interfaces +defined + +name + +name + +is +not +found + +in +this +specification. +In +order + + +this.getThingDescription().events +, +throw + +NotFoundError + +and +terminate +these +steps. +
                                3. +Make +a +request + +to +avoid +duplication +of +definitions, +references + +the +underlying +platform + +to +these + +send +an + +Event + +with + +data +types +and +structures +is +defined +in +this +section, +but +for +their +full +description +please +refer +to + + +attached +as +property, +using + +the +Thing +Description +specification +. +6.1 + + +Protocol +Bindings +, +then +terminate +these +steps. +
                                +

                                7.14 +The +DataSchema + + +expose() + + +dictionary +and +its +subclasses + +method + +

                                Value +types +basically +represent +types +

                                Start +serving +external +requests +for +the + +Thing +, +so + +that +may +be +used +in +JSON +object +definitions +and +are +used +in +ThingFragment + + +WoT +Interactions + + +to +define + +using + +Properties +, +Event +s +and + + +Action + +parameters. +Value +types +are +represented +as +dictionary +objects +whose +properties + +s + +and +possible +sub-classes +are +defined +in +the +DataSchema +section +of +[ +WOT-TD +]. +One +property +of +all +DataSchema + + +Event + + +dictionary +is + +s +will +be +possible. +The +method +MUST +run + +the +type +property +whose +value +is +from + +following +steps: +

                                1. +Return + +a +set +of +enumerated +strings +defined +in +the +DataSchema +section +of +[ +WOT-TD + + +Promise + + +] + + +promise + +and +is +referred +as +DataType +in +this +specification. +Based +on +type +, + +execute + +the +following +sub-classes +of +DataSchema +are +defined + +next +steps + +in +[ +WOT-TD +]: +BooleanSchema +, +NumberSchema +, +IntegerSchema +, +StringSchema +, +ObjectSchema +, +ArraySchema + +parallel + +. +6.2 +The + +
                                  2. +
                                2. +If +invoking +this +method +is +not +allowed +for +the +current +scripting +context +for +security +reasons, +reject + +promise + +with + + +SecurityScheme + +SecurityError + + +dictionary + +and +its +subclasses +Security +metadata +is +represented +as +dictionary +objects +whose +properties +and +sub-classes +are +defined +in + +terminate +these +steps. +
                                3. +Run + +the +SecurityScheme +section +of +[ +WOT-TD + + +expand +a +TD + + +]. +One +property +of + +steps +on + +the +SecurityScheme +dictionary +is + +internal +slot +|td|. +
                                4. +Run + +the +scheme +property +whose +value +is +from + + +validate + +a +set +of +enumerated +strings +defined +in +the +SecurityScheme +section +of +[ +WOT-TD + +TD + + +]. +Based + +on +|td|. +If +that +fails, +reject + +promise + +with + + +type +, +multiple +subclasses +of +SecurityScheme +are +defined. +6.3 +The +Link + +"TypeError" + + +dictionary +Represents +a +Web +Link + +and +terminate +these +steps. +
                                5. +For +each + +Property + + +with +properties +defined + +definition + +in +the +Link +section +of +[ +WOT-TD +]. +6.4 +The +Form + + +this.instance.properties + +initialize +an +| + +internal +observer +list + + +dictionary +Represents +metadata +describing +service +details, +with +properties +defined + +| +internal +slot + +in +order +to +store +observe +request +data +needed +to +notify + +the +Form +section +of +[ +WOT-TD +]. +6.5 +The +InteractionFragment +dictionary +Represents + +observers +on +value +changes. +
                                6. +Set +up + +the +common +properties +of + + +WoT +Interactions +, +one +of +Property +, +Action + + +or +Event +, + +based +on +introspecting + +td + +as +defined + +explained + +in +[WOT-TD] +and +[WOT-PROTOCOL-BINDINGS]. +Make +a +request +to + +the +InteractionPattern + +underlying +platform +to +initialize +the + +Protocol +Bindings + + +section +of +[ +WOT-TD + +and +then +start +serving +external +requests +for + +WoT +Interactions + + +]. +Its +subclasses +are +referred +as +PropertyFragment + +(read, +write +and +observe + +Properties + +, +ActionFragment + +invoke + +Action + + +s + +and +EventFragment +. +6.6 +The +PropertyFragment +dictionary + +manage + +Event + + +Represents + +subscriptions), +based +on + +the +Property +interaction +data +that +initializes +a +ThingProperty +object. +Its +properties + + +Protocol +Bindings +. +The +details + +are +defined +in + +private +to + +the +Property + +implementations + +and +InteractionPattern +sections + +out + +of +[ +WOT-TD +]. +6.7 +The +ActionFragment +dictionary +Represents + +scope +of +this +specification. +
                                7. +If +there +was +an +error +during + +the +Action +interaction +data +that +initializes +a + +request, +reject + +promise + +with +an + + +ThingAction + +Error + + +object. +Its +properties +are +defined +in +the +Action +and +InteractionPattern +sections +of +[ +WOT-TD +]. +6.8 +The + +object + +error + +with + + +EventFragment + +error.message + + +dictionary +Represents + +set +to + +the +Event +interaction +data +that +initializes +a +ThingEvent +object. +Its +properties +are +defined +in + +error +code +seen +by + +the +Event +section +of +[ +WOT-TD + + +Protocol +Bindings + + +]. + +and +terminate +these +steps. +
                                8. +Otherwise +resolve + +promise + +and +terminate +these +steps. +
                                6.9 +

                                7.15 +The +ThingFragment + + +destroy() + + +dictionary + +method + +

                                The +ThingFragment +dictionary +is +defined +as +Thing +in +[ +WOT-TD +]. +It +is +a +dictionary +that +contains +properties +representing +semantic +metadata +and +interactions +( +Properties +, +Action +s +and +Event +s). +It +is +used +

                                Stop +serving +external +requests + +for +initializing +an +internal +representation +of +a + +the + +Thing +Description + + +and +its +properties +may + +destroy +the +object. +Note +that +eventual +unregistering +should + +be +used +in +ThingFilter +. +6.10 + +done +before +invoking +this +method. + +The +ThingDescription +type +Serialized +representation +of + +method +MUST +run + +the +Thing +Description +(a +JSON-LD + +following +steps: +

                                1. +Return +a + +Promise + + +document). +Note +In + + +promise + +and +execute +the +next +steps + +in +parallel +.
                                2. +If +invoking + +this +version +of + +method +is +not +allowed +for + +the +API, +Thing +Description +s +are +represented +as +an +opaque + +current +scripting +context +for +security +reasons, +reject + +promise + +with + + +USVString + +SecurityError + + +that +can +be +transmitted +between +devices. +7. +Interfaces +for +WoT +Interactions +The +data +types + +and +structures +imported +from +[ +WOT-TD +] +are +extended +by +this +specification +in +order + +terminate +these +steps. +
                                3. +Make +a +request + +to +provide + +the +interfaces + +underlying +platform +to +stop +serving +external +requests + +for + +WoT +Interactions +. +Every +Thing +describes +its +metadata +as +defined +in +ThingFragment +, +and +basic +interactions +defined +as +Properties + +, +Action +s +and +Event +s. +The +following +interfaces +are +used +for +representing +these +interactions. +7.1 +The + +based +on +the + +Protocol +Bindings +.
                                4. +If +there +was +an +error +during +the +request, +reject + +promise + +with +an + + +Interaction + +Error + + +interface +The + +object + +error + +with + + +Interaction + +error.message + + +interface +is +an +abstract +class + +set + +to +represent +Thing +interactions: +Properties +, +Actions + +the +error +code +seen +by +the + +Protocol +Bindings + + +and +Events +. + +terminate +these +steps. +
                                5. +Otherwise +resolve + +promise + +and +terminate +these +steps. +
                                +

                                7.16 +ExposedThing +Examples +

                                +The +InteractionFragment +dictionary +holds +the +common +properties +of +PropertyFragment +, +ActionFragment +and +EventFragment +dictionaries +used +for +initializing +ThingProperty +, + +next +example +illustrates +how +to +create +an + + +ThingAction + + +ExposedThing + + +and + +ThingEvent + + +based +on +a +partial + +TD + + +objects +in + +object +constructed +beforehands. +

                                +
                                + Example 3: 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 +ThingFragment + + +Property + + +dictionary +used +for +creating + +definition +on + +an +ExposedThing +object. +

                                readonly attribute +}; +

                                existing + + +Interaction + + +ExposedThing + + +includes +InteractionFragment + +: +take +its + +td + +property, +add +or +modify +it, +then +create +another + +ExposedThing + + +; + +with +that. +

                                +
                                + Example 4: 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);
+        }
+
                                +

                                8. +The +forms + + +ThingDiscovery + + +read-only +property +represents +the +protocol +bindings +initialization +data +and + +interface +

                                +Discovery + +is +initialized +by + +a +distributed +application +that +requires +provisioning +and +support +from +participating +network +nodes +(clients, +servers, +directory +services). +This +API +models + +the +WoT +Runtime +. + +client +side +of +typical +discovery +schemes +supported +by +various +IoT +deployments. + +

                                7.2 +

                                +The +ThingProperty +interface + + +ThingDiscovery + + +object +is +constructed +given +a +filter +and +provides +the +properties +and +methods +controlling +the +discovery +process. +

                                      [SecureContext, Exposed=(Window,Worker)]
+      interface ThingDiscovery {
+        constructor(optional ThingFilter filter = null);
+        readonly attribute ThingFilter? filter;
+        readonly attribute boolean active;
+        readonly attribute boolean done;
+        readonly attribute Error? error;
+        void start();
+        Promise<ThingDescription> next();
+        void stop();
+      };
                                Editor's note

                                +The +ThingProperty + + +ThingDiscovery + + +interface +is +used +in + +has +a + + +ConsumedThing + +next() + + +method + +and +a + + +ExposedThing + +done + + +objects +to +represent +Thing +Property + +property, +but +it +is +not +an + +Iterable +. +Look +into + +Issue +177 + + +interactions. + +for +rationale. + +

                                +The +PropertyFragment +dictionary + + +discovery +results + +internal +slot + +is +used + +an +internal +queue + +for +initializing +Property + +temporarily +storing +the +found + +ThingDescription + + +objects +in +a +ThingFragment +dictionary +used +for +creating +an +ExposedThing +object. +It +MUST +implement +one +of + +until +they +are +consumed +by + +the +DataSchema +dictionaries. +

                                // getter for PropertyFragment properties

                                // get and set interface for the Property

                                }; +ThingProperty +includes +Observable +; +The +ThingProperty + +

                                application +using +the + +next() + + +interface +contains +all + +method. +Implementations +MAY +optimize + +the +properties +defined + +size +of +this +queue +based + +on +PropertyFragment + +e.g. +the +available +resources +and +the +frequency +of +invoking +the + +next() + + +as +read-only +properties. + +method. +

                                +The +type + + +filter + + +read-only + +property +represents +the +discovery +filter +of + +type +definition + + +ThingFilter + +specified + +for +the +Property +as +a +DataSchema +dictionary +object. + +discovery. + +

                                +The +writable + + +active + + +read-only + +property +tells +whether +the +Property +value +can +be +updated. +If +it + +is + +false +, +then +the +set(value) + +true + + +method +SHOULD +always +reject. +The +observable +read-only +property +tells +whether + +when + +the +Property +supports +subscribing +to +value +change +notifications. +If +it + +discovery + +is +actively +ongoing +on +protocol +level +(i.e. +new + +TD + +s +may +still +arrive) +and + + +false +, +then +the +subscribe() + + +method +SHOULD +always +fail. + +otherwise. + +

                                +The +constant +read-only + + +done + +property +- +defined +in +DataSchema +- +tells +whether +the +Property +value + +is +a +constant. +If + + +true +, +the +set() +and +subscribe() +methods +SHOULD +always +fail. +The +required +read-only +property +- +defined +in +DataSchema + + +- +tells +whether +the +Property +should +be +always +present +on + +if + +the +ExposedThing + +discovery +has +been +completed +with +no +more +results +to +report +and + +discovery +results + + +object. + +is +also +empty. + +

                                +The +read() + + +error + + +method +will +fetch +the +value +of + +property +represents + +the +Property +. +Returns +a +Promise + +last +error + +that +resolves +with + +occured +during + +the +value, +or +rejects +with +an +error. + +discovery +process. +Typically +used +for +critical +errors +that +stop +discovery. + +

                                The +

                                8.1 +Constructing + + +write() + +ThingDiscovery + + +method +will +attempt +to +set +the +value +of + +

                                To +create + +ThingDiscovery + +with + +the +Property + + +ThingFilter + + +specified +in + + +filter +, +run + +the +following +steps: +

                                1. +If + +filter + +is +not +an +object +or + + +value +argument +whose +type +SHOULD +match +the +one +specified +by +the + +null +, +throw + + +type + +"TypeError" + + +property. +Returns + +and +terminate +these +steps. +
                                2. +Let + +discovery + +be + +a +Promise + +new + +ThingDiscovery + + +that +resolves +on +success, +or +rejects +on +an +error. +7.3 +The +ThingAction +interface + +object. +
                                3. +Set +the + +filter + + + + +

                                  }; +ThingAction +

                                  property +to + +filter +.

                                  + +                                   +
                                4. +Set + +active + + +includes + +and + +done + +to + + +ActionFragment + +false +. +Set + +error + + +; + +to + +null +.
                                5. +Return + +discovery +.
                                  6. +
                                +

                                +The + +start() + +method +sets + +active + +to + + +invoke() + +true +. +The + +stop() + +method +when +invoked, +starts +the +Action + +sets + +active + + +interaction +with +the +input +value +provided +by +the +inputValue +argument. +If + +to + + +inputValue +is + +false +, +but + +done + +may +be +still + + +null +, +the +action +does +not +take +any +arguments +and +rejects + +false + +if +any +arguments + +there + +are +provided. +If +the +value +is +undefined +, +the +action +will +ignore +any +arguments +provided. +Otherwise +the +type +of +inputValue +SHOULD +match +the +DataSchema + + +ThingDescription + + +definition + +objects + +in +the +input +property. +Returns +a +Promise + + +discovery +results + + +that +will +reject +with +an +error +or +will +resolve + +not +yet +consumed + +with +a +value + + +next() +.

                                +During +successive +calls + +of +type +defined +by +the + + +next() +, +active + +may +be + + +output + +true + + +property. +7.4 +The + +or + + +ThingEvent +interface + +false +, +but + +done + + +{ +}; + +is +set +to + + +ThingEvent + +false + + +by + +next() + + +includes + +only +when +both + +active + +is + + +ThingProperty + +false + + +and + +discovery +results + + +; + +is +empty. +

                                8.2 +The + +DiscoveryMethod + +enumeration +

                                typedef DOMString DiscoveryMethod;

                                +Since +ThingEvent +implements +Observable +through + +Represents + +the +ThingProperty + +discovery +type +to +be +used: +

                                • + +"any" + +does +not +provide +any +restriction +
                                • +"local" + +for +discovering + +Thing + + +interface, +event +subscription +is +done +by +invoking + +s +defined +in + +the +subscribe() +method +on + +same +device +or +connected +to + +the +event +object +that +returns + +device +by +wired +or +wireless +means. +
                                • +"directory" + +for +discovery +based +on + +a +cancelable +Subscription + +service +provided +by +a + +Thing +Directory + +. +
                                  • +
                                • + +"multicast" + +for +discovering + +Thing + +s +in +the +device's +network +by +using +a +supported +multicast +protocol. +
                                7.5 +

                                8.3 +The +ExposedEvent + + +ThingFilter + + +interface + +dictionary + +

                                +void +}; +

                                +Represents +an +object +containing +the +constraints +for +discovering + +Thing + +s +as +key-value +pairs. +

                                        dictionary ThingFilter {
+          (DiscoveryMethod or DOMString) method = "any";
+          USVString? url;
+          USVString? query;
+          object? fragment;
+        };
                                7.5.1 +

                                +The +emit() + + +method +Emits +an +event + + +property +represents +the +discovery +type + +that +carries +data +specified + +should +be +used +in +the +discovery +process. +The +possible +values +are +defined + +by +the + +payload +argument. +7.6 +The +value-matching +algorithm + + +DiscoveryMethod + + + +enumeration +that +MAY +be +extended +by +string +values +defined +by +solutions +(with +no +guarantee +of +interoperability). +

                                +The +value-matching +algorithm +is +applied +to +a +value +input +in +relation +to +a +valueType + + +url + +property +represents +additional +information +for +the +discovery +method, +such +as +the +URL + +of +type +DataSchema +, + +the +target +entity +serving +the +discovery +request, + +for +instance +the +URL +of +a + +Thing +Directory + +(if + + +value + +method + + +and + +is + + +type + +"directory" + + +properties + +) +or +that + +of +a +PropertyFragment + + +Thing + + +object, +or +the +inputValue +parameter +to + +(otherwise). +

                                +The + +query + +property +represents +a +query +string +accepted +by + +the +invoke() +method +of + +implementation, +for +instance + +a +ThingAction + +SPARQL +or +JSON +query. +Support +may +be +implemented +locally +in +the + +WoT +Runtime + + +object + +or +remotely +as +a +service + +in +relation +to + +a + +Thing +Directory +.

                                +The + +fragment + +property +represents +a +template +object +used +for +matching +property +by +property +against +discovered + +Thing + +s. +

                                8.4 +The + +start() + +method +

                                +Starts + +the +same +object. +It +executes + +discovery +process. +The +method +MUST +run + +the +following +steps: +
                                  +
                                1. +If +valueType.type + +invoking +this +method + +is +not +defined, +or +does +not +fully +match +a +string +enumerated +in +DataType +, +return + +allowed +for +the +current +scripting +context +for +security +reasons, +set + +this.error + +to + + +false +. + +SecurityError + +and +terminate +these +steps. + +
                                  2. +
                                2. +Otherwise, +if +valueType.type + +If +discovery + +is +"null" +: +if + +not +supported +by +the +implementation, +set + + +value + +this.error + + +is +null +, +return +true +, +otherwise +return + +to + + +false +. + +NotSupportedError + +and +terminate +these +steps. + +
                                  3. +
                                3. +Otherwise, +if + +If + + +valueType.type + +this.filter + + +is +"boolean" +: +if + +defined, +
                                  • +Let + + +value + +filter + + +is +either +true +or +false +, +then +return +true +, +otherwise +return +false +. + +denote + +this.filter +. +
                                    • +
                                  • +Otherwise, +if +valueType.type +is +"integer" +: +if + +If + + +value + +filter.query + + +is +not + +defined, +pass +it +as + +an +integer +type +defined +by + +opaque +string +to + +the +underlying +platform +(such + +implementation +to +be +matched +against +discovered +items. +The +underlying +implementation +is +responsible +to +parse +it +e.g. + +as +long + +a +SPARQL + +or +JSON +query +and +match +it +against +the + +Thing +Description + +s +found +during +the +discovery +process. +If +queries +are +not +supported, +set + +this.error + +to + + +long +long + +NotSupportedError + + +), +then +return +false +, +otherwise +execute + +and +terminate +these +steps. +
                                4. +Create +the + +discovery +results + +internal +slot +for +storing +discovered + +ThingDescription + +objects. +
                                5. +Request +the +underlying +platform +to +start +the +discovery +process, +with + +the +following +sub-steps: + +parameters: +
                                    +
                                  • +If + +valueType.minimum + +filter.method + + +is +not + +defined +and + +or +the + +value +is +not +greater +or +equal +than +that +value, +return +false +. + + +"any" +, +use +the +widest +discovery +method +supported +by +the +underlying +platform. + +
                                    • +
                                  • +If +valueType.maximum +is +defined +and + +Otherwise +if + + +value + +filter.method + + +is +not +less +or +equal +than +that +value, +return +false +. +Return + + +true +. + +"local" +, +use +the +local + +Thing +Directory + +for +discovery. +Usually +that +defines + +Thing + +s +deployed +in +the +same +device, +or +connected +to +the +device +in +slave +mode +(e.g. +sensors +connected +via +Bluetooth +or +a +serial +connection). + +
                                    • +
                                  • +Otherwise, + +Otherwise + +if + +valueType.type + +filter.method + + +is + +"number" + +"directory" + +, +use +the +remote + +Thing +Directory + +specified +in + +filter.url +.
                                  • +Otherwise + +if + +value + +filter.method + + +is +not +an +integer +or +floating +point +type +defined + + +"multicast" +, +use +all +the +multicast +discovery +protocols +supported + +by +the +underlying +platform. +
                                6. +When +the +underlying + +platform +(such +as +long +or +long +long +or + +has +started +the +discovery +process, +set +the + + +double + +active + + +), +then +return + +property +to + + +false +, +otherwise +otherwise +execute + +true +.
                                7. +Whenever +a +new + +Thing +Description + +td + +is +discovered +by +the +underlying +platform, +run + +the +following +sub-steps: +
                                    +
                                  1. +If +valueType.minimum +is +defined +and + + +Fetch + + +value + +td + + +is +not +greater +or +equal +than +that +value, +return + +as +a +JSON +object + + +false + +json + +. +If +that +fails, +set + + +valueType.maximum + +this.error + + +is +defined +and + +to + +SyntaxError +, +discard + + +value + +td + + +is +not +less +or +equal +than +that +value, +return +false +. +Return +true +. + +and +continue +the +discovery +process. + +
                                    2. +
                                  2. +Otherwise, +if + +If + + +valueType.type + +filter.query + + +is +"string" +: + +defined, +check + +if + +value + +json + + +is +not + +a +string +type +defined +by + +match +for + +the +underlying +platform, +then +return + +query. +The +matching +algorithm +is +encapsulated +by +implementations. +If +that +returns + + +false +, +otherwise +return +true +. +In +this +case +the +algorithm +expects +a +third +parameter + +discard + + +valueType.enum + +td + + +and +runs + +continue + +the +following +sub-steps: + +discovery +process. +
                                    3. +
                                  3. +If + +valueType.enum + +filter.fragment + + +is +an +array +of +strings, +then + +defined, +for +each +property +defined +in +it, +check + +if +that +property +exists +in + + +value + +json.properties + + +fully +matches +one +of + +and +has + +the +strings +defined + +same +value. +If +this +is + +false + +in +the +array, +return + +any +checks, +discard + + +true +. + +td + +and +continue +the +discovery +process. + +
                                    4. +
                                  4. +Otherwise, +return + +Otherwise +add + + +false +. + +td + +to +the + +discovery +results +. +
                                    5. +
                                  5. +Otherwise, + +At +this +point +implementations +MAY +control +the +flow +of +the +discovery +process +(depending +on +memory +constraints, +for +instance +temporarily +stop +discovery + +if +valueType.type + +the +queue + +is +"array" +, +execute + +getting +too +large, +or +resume +discovery +when + +the +following +sub-steps: +If +value + +queue + +is +not +an +array, +return +false +. + +emptied +sufficiently). +
                                  +
                                  8. +
                                8. +If + +Whenever +an +error +occurs +during +the +discovery +process, +
                                  1. +Set + + +valueType.minItems + +this.error + + +is +defined, +and + +to +a +new + +Error + +object + + +value +does +not +contain +at +least + +error +. +Set + + +valueType.minItems + +error.name + + +elements, +return +false +. + +to + +'DiscoveryError' +. +
                                    2. +
                                  2. +If +there +was +an +error +code +or +message +provided +by +the + +Protocol +Bindings +, +set + + +valueType.maxItems + +error.message + + +is +defined, +and + +to +that + +value +contains +more +than +valueType.maxItems +elements, +return +false +. + +as +string. + +
                                    3. +
                                  3. +Otherwise, +if +valueType.items + +If +the +error + +is +irrecoverable +and +discovery +has +been +stopped +by +the +underlying +platform, +set + + +undefined +, +return + +this.active + +to + + +false +. +
                                    4. +Otherwise, +if +valueType.items +is +null +, +return +true +(i.e. +any +type +is +accepted +as +array +element, +including +heterogenous +arrays). + +
                                  +
                                  9. +
                                9. +Otherwise, +for +each +element +of +the +array +value +run + +When + +the +value-matching +algorithm +against + +underlying +platform +reports + +the +discovery +process +has +completed, +set + + +valueType.items + +this.active + + +object. +If +any +of +these +runs +returns +false +, +then +return + +to + + +false +. +
                                  10. +Otherwise, +return +true +. + +
                                +

                                8.5 +The + +next() + +method +

                                +Provides +the +next +discovered + +ThingDescription + +object. +The +method +MUST +run +the +following +steps: +
                                  +
                                1. +Otherwise, +if + +Return +a + +Promise + + +type + +promise + + +is +"object" +, + +and + +execute +the +following +sub-steps: + +next +steps + +in +parallel +.
                                  2. +
                                2. +If + +value + +this.active + + +is +not +an + + +Object + +true + +, +return +false +. +If +valueType.properties + +wait +until +the + +discovery +results + +internal +slot + +is +not +defined, +return +false +. + +empty. + +
                                  3. +
                                3. +If + +discovery +results + +is +empty +and + + +valueType.properties + +this.active + + +is + +null + +false + +, +return + +set + +this.done + +to + + +true + +(i.e. +accept +any +object +value). + +and +reject + +promise +. +
                                  4. +
                                4. +For +each +string +in +the +valueType.required +array, +if +it +does +not +match +a +property +name +in + +Remove + +the +value.properties + +first + +ThingDescription + +object +or +in +the + + +value + +td + + +object, +then +return +false +. + +from + +discovery +results +. +
                                  5. +
                                5. +For +each +property +with +name +propName +and +value + +Resolve + + +propDataSchema + +promise + + +found +in +valueType.properties +, +run +the +following +sub-steps: +If +the +result +of +applying +the +value-matching +algorithm +on +the +value + +with + + +value[propName] + +td + + +and +propDataSchema +is +false +, +then +return +false +. +Return +true +. + +terminate +these +steps. + +
                                  6. +
                                +
                                8. +Observables +This +section +is +non-normative. +Observables +

                                8.6 +The + +stop() + + +are +proposed +to + +method +

                                +Stops +or +suppresses +the +discovery +process. +It +might +not + +be +included +in +ECMAScript + +supported +by +all +discovery +methods + +and +are +used +for +handling +pushed +data +associated +with +various +possible +sources, +for +instance +events, +timers, +streams, +etc. +A +minimal +required +implementation +is +described +here. +Editor's +note +This +section +is +informal + +endpoints, +however, +any +further +discovery +results +or +errors +will +be +discarded + +and +contains +rather +laconic +information +for +implementations +on +what +to +support +for +interoperability. + + +
                                               optional
+               optional

                                }; +

                                interface +void +readonly attribute +}; +callback +callback +callback +OnComplete += +void +(); +

                                +

                                the +discovery +is +marked +inactive. + +The +method +MUST +run +the + +following +callbacks +can +be +provided +when +subscribing +to +an +Observable +: + +steps: +

                                +
                                  +
                                1. +The +EventHandler +callback +takes +the +next +sample +for + +Request + +the +data +in + +underlying +platform +to +stop + +the +value +argument. +The +ErrorHandler +callback +takes + +discovery +process. +If +this +returns + +an +error +in +the +value +argument. +It + +error, +or +if +it + +is +called + +not +possible, +for +instance + +when +an +error +occurred +in +producing +the +data + +discovery +is +based +on +open +ended +multicast +requests, + +the +client +should +know +about. + +implementation +SHOULD +discard +subsequent +discovered +items. + +
                                  2. +
                                2. +The + +Set + + +OnComplete + +this.active + + +callback +is +called +when +the +data +source +has +finished +sending +values. +8.1 +The + +to + + +Subscription +interface + +false +.
                                +                                 +

                                8.7 +Discovery +Examples + +

                                +Contains +the +closed +property + +The +following +example +finds + +ThingDescription + +objects + +of +type +boolean + + +Thing + +s + +that +tells +if +the +subscription + +are +exposed +by +local +hardware, +regardless +how +many +instances +of + +WoT +Runtime + +it + +is +closed +or +active. +Also, +contains +the +unsubscribe +() +method + +running. +Note + +that +cancels + +the +subscription, +i.e. +makes +a +request +to + +discovery +can +end +(become +inactive) +before + +the +underlying +platform + +internal + +discovery +results + +queue +is +emptied, +so +we +need + +to +stop +receiving +data +from +the +source, + +continue +reading + +ThingDescription + +objects +until +done. +This +is +typical +with +local + +and +sets +the +closed +property +to +false +. + +directory +type +discoveries. + +

                                8.2 +The +Observable +interface +
                                +
                                + Example 5: Discover Things exposed by local hardware + 
                                        let discovery = new ThingDiscovery({ method: "local" });
+        do {
+          let td = await discovery.next();
+          console.log("Found Thing Description for " + td.title);
+          let thing = new ConsumedThing(td);
+          console.log("Thing name: " + thing.getThingDescription().title);
+        } while (!discovery.done);
+
                                +

                                +The +Observable + +next +example +finds + +ThingDescription + + +interface +enabled +subscribing +to +pushed +data +notifications +by +the +subscribe +() +method: + +objects +of + +Thing + +s +listed +in +a + +Thing +Directory + +service. +We +set +a +timeout +for +safety. + +

                                Initialize +the +data +handler +callback +with +the +first +function +argument. +If +the +
                                +
                                + Example 6: Discover Things via directory + 
                                        let discoveryFilter = {
+          method: "directory",
+          url: "http://directory.wotservice.org"
+        };
+        let discovery = new ThingDiscovery(discoveryFilter);
+        setTimeout( () => {
+            discovery.stop();
+            console.log("Discovery stopped after timeout.");
+          },
+          3000);
+        do {
+          let td = await discovery.next();
+          console.log("Found Thing Description for " + td.title);
+          let thing = new ConsumedThing(td);
+          console.log("Thing name: " + thing.getThingDescription().title);
+        } while (!discovery.done);
+        if (discovery.error) {
+          console.log("Discovery stopped because of an error: " + error.message);
+        }
+
                                +

                                +The + +next +argument +is +provided +and + +example + +is +a +function, +initialize +the +error +handling +callback +with +that +function, +or +throw + +for +an +open-ended +multicast +discovery, +which +likely +won't +complete +soon +(depending + +on +error. +If + +the +third +argument +is +provided +and + +underlying +protocol), +so +stopping +it +with +a +timeout + +is +a +function, +initialize +the +completion +handler +with +that +function, +or +throw +on +error. +After +callback +initializations, +the +implementation +should +request +the +underlying +platform +to +provide +data, +error +and +completion +notifications +for +the +supported +data +source. + +good +idea. +It +will +likely +deliver +results +one +by +one. +

                                +
                                + Example 7: Discover Things in a network + 
                                        let discovery = new ThingDiscovery({ method: "multicast" });
+        setTimeout( () => {
+            discovery.stop();
+            console.log("Stopped open-ended discovery");
+          },
+          10000);
+        do {
+          let td = await discovery.next();
+          let thing = new ConsumedThing(td);
+          console.log("Thing name: " + thing.getThingDescription().title);
+        } while (!discovery.done);
+
                                +

                                9. +9. + +Security +and +Privacy +

                                +In +general +the +security +measures +taken +to +protect +a +WoT +system +will +depend +on +the +threats +and +attackers +that +system +may +face +and +the +value +of +the +assets +needs +to +protect. + +A +detailed +discussion +of +security +and +privacy +considerations +for +the +Web +of +Things, +including +a +threat +model +that +can +be +adapted +to +various +circumstances, +is +presented +in +the +informative +document +[ +WOT-SECURITY-CONSIDERATIONS +]. + +[WOT-SECURITY-GUIDELINES]. + +This +section +includes + +discusses + +only +normative +recommendations + +security +and +privacy +risks +and +possible +mitigations +directly + +relevant +to +the +scripts +and + +WoT +Thing +Description. + +Scripting +API. + +

                                +When +designing +new +devices +and +services +for +use +with +the +WoT, +we +have +documented +a + +A +suggested + +set +of +best +practices +to +improve +security +for +WoT +devices +and +services +has +been +documented + +in +[ +WOT-SECURITY-BEST-PRACTICES +] +that +SHOULD +be +followed. +This +best-practices + +[WOT-SECURITY-BEST-PRACTICES]. +That + +document +may +be +updated +as +security +measures +evolve. +Following +these +practices +does +not +guarantee +security, +but +it +at +least +will + +might + +help +to + +avoid +common +known +vulnerabilities +and +pitfalls. + +vulnerabilities. + +

                                Below +are +specific +recommendations +related +to +

                                The + +WoT +runtime +implementations: + +security +risks +and +possible +mitigations +are +concerning +the +following +groups: +

                                +
                                  +
                                • +In +basic +WoT +setups, +all +scripts +running +inside +the + +Implementors +of + +WoT +runtime +are +considered +trusted, +and +therefore +there +is +no +strong +need +to +perform +strict +isolation +between +each +running +script +instance. +However, +depending +on +device +capabilities +and +deployment +use +case +scenario +risk +level +it +might +be +desirable +to + +Runtimes +that + +do +so. + +not +implement +a +Scripting +Runtime. +The +[WOT-ARCHITECTURE] +document +provides +generic +security +guidelines +for +this +group. +
                                  • +
                                • +For +example, +if +one +script +handles +sensitive +privacy-related +data +and +well-audited, +it +might +be +desirable +to +separate +it +from +the +rest + +Implementors + +of +the +script +instances +to +minimize +the +risk +of +data +exposure + +WoT +Scripting +API + +in +case +some +other +script +inside + +a + +WoT +gets +compromised +during +the +runtime. +Therefore + +Scripting +Runtime. +This +is + +the +WoT +runtime +SHOULD +perform +isolation +of +script +instances + +main +scope + +and +their +data + +is +covered + +in +cases +when +scripts +handle +privacy-related +or +other +critical +security +data. + +the + +Scripting +Runtime +Security +and +Privacy +Risks + +sub-section +that +contains +normative +text +regarding +security. + +
                                  • +
                                • +Another +example +is +mutual +co-existence +of +different +tenants +on +a +single +WoT +device. +In +this +case +each + +WoT +runtime +instance +will +be +hosting +a +different +tenant, + +script +developers, +covered +in +the + +Script +Security + +and +isolation +between +them + +Privacy +Risks + +sub-section +that +contains +informative +recommendations +concerning +security. +

                                9.1 +Scripting +Runtime +Security +and +Privacy +Risks +

                                +This +section + +is +required. +Therefore + +normative +and +contains +specific +risks +relevant +for + +the +WoT +runtime +SHOULD +perform +isolation +of +WoT +runtime +instances + +Scripting +Runtime. +

                                9.1.1 +Corrupted +Input +Security + +and +their +data +if + +Privacy +Risk +

                                +A +typical +way +to +compromise +any +process +is +to +send +it + +a +WoT +device +has +more +than + +corrupted +input +via + +one +tenant. +Such +isolation + +of +the +exposed +interfaces. +This + +can +be +performed +within +the +WoT +Runtime +using +platform +security +mechanisms +available +on +the +device. +For +more +information +see +Section +"WoT +Servient +Single-Tenant" +and +"WoT +Servient +Multi-Tenant" +of +[ +WOT-SECURITY-CONSIDERATIONS +]. +WoT +scripts +are + +done +to +a +script +instance + +using +WoT +Scripting + +interface +it +exposes. +

                                +Mitigation: +
                                +Implementors +of +this + +API +to +implement +the +functionality +and +logic +for +WoT +Things. + +SHOULD +perform +validation +on +all +script +inputs. + +In +addition +to +providing + +input +validation, + +fuzzing + +should +be +used +to +verify +that + +the +isolation +between +script + +input +processing +is +done +correctly. +There +are +many +tools + +and +runtime +instances, +the +WoT +runtime +needs + +techniques +in +existence + +to +protect + +do +such +validation. +More +details +can +be +found +in +[WOT-SECURITY-TESTING]. +

                                9.1.2 +Physical +Device +Direct +Access +Security +and +Privacy +Risk +

                                +In +case +a +script +is +compromised +or +misbehaving, + +the +underlying +physical +device +from + +(and + +potentially +misbehaving +WoT +scripts. +Therefore + +surrounded +environment) +can +be +damaged +if +a +script +can +use +directly +exposed +native +device +interfaces. +If +such +interfaces +lack +safety +checks +on +their +inputs, +they +might +bring + +the +underlying +physical +device +(or +environment) +to +an +unsafe +state +(i.e. +device +overheats +and +explodes). +

                                +Mitigation: +
                                +The + +WoT +Scripting + +Runtime +SHOULD +avoid +directly +exposing +the +native +device +interfaces +to +the +script +developers. +Instead + +Instead, + +a +WoT +Scripting + +Runtime +should +provide +a +hardware +abstraction +layer +for +accessing +the +native +device +interfaces. +Such +hardware +abstraction +layer +should +refuse +to +execute +commands +that +might +put +the +device +(or +environment) +to +an +unsafe +state. + +Additionally, +in +order +to +reduce +the +damage +to +a +physical +WoT +device +in +cases +a +WoT + +script +gets +compromised, +it +is +important +to +minimize +the +number +of +interfaces +that +are +exposed +or +accessible +to +a +particular +WoT + +script +based +on +its +functionality. +Therefore +the +WoT +Runtime +SHOULD +only +expose +a +minimal +set +of +interfaces +to +a +WoT +script +based +on +its +intended +functionality. + +

                                9.1.3 +Provisioning +and +Update +Security +Risk +

                                +If +the +WoT +runtime + +Scripting +Runtime + +supports +post-manufacturing +provisioning +or +update + +updates + +of +WoT + +scripts, +WoT +runtime + +Scripting +Runtime + +or +any +related +data +(including +security +credentials), +it +can +be +a +major +attack +vector. +An +attacker +can +try +to +modify +any +above +described +part + +element + +during +the +update +or +provisioning +process +or +simply +provision +attacker's +code +and +data +directly. +Therefore, +if +WoT +Runtime +supports +post-manufacturing + +

                                +
                                +Mitigation: +
                                +Post-manufacturing + +provisioning +or +update +of +WoT + +scripts, +WoT +runtime + +Scripting +Runtime + +or +any +related +data, +such +operations +SHOULD + +data +should + +be +done +in +a +secure +fashion. +A +set +of +recommendations +for +secure +update +and +post-manufacturing +provisioning +can +be +found +in +[ +WOT-SECURITY-BEST-PRACTICES +]. + +[WOT-SECURITY-GUIDELINES]. +

                                9.1.4 +Security +Credentials +Storage +Security +and +Privacy +Risk +

                                +Typically +the +WoT +runtime + +Scripting +Runtime + +needs +to +store +the +security +credentials +that +are +provisioned +to +a +WoT +device +to +operate +in +WoT +network. +The + +If +an +attacker +can +compromise +the + +confidentiality +or +integrity +of +these +credentials +should +not +be +compromised. +Therefore + +credentials, +then +it +can +obtain +access +to + +the +WoT +runtime +SHOULD + +assets, +impersonate +WoT +things +or +devices +or +create +Denial-Of-Service +(DoS) +attacks. +

                                +Mitigation: +
                                +The +WoT +Scripting +Runtime +should + +securely +store +the +provisioned +security +credentials, +guaranteeing +their +integrity +and +confidentiality. +In +case +there +are +more +than +one +tenant +on +a +single +WoT-enabled +device, +a +WoT +Scripting + +Runtime +SHOULD + +should + +guarantee +isolation +of +each +tenant +provisioned +security +credentials. +Additionally, +in +order +to +minimize +a +risk +that +provisioned +security +credentials +get +compromised, +the +WoT +runtime + +Scripting +Runtime + +should +not +have +any +way +for +WoT +scripts +to +query +these +credentials. +Therefore, +the +WoT +Runtime +SHOULD NOT + +expose +any +API +for +WoT + +scripts +to +query +the +provisioned +security +credentials. +

                                9.2 +Script +Security +and +Privacy +Risks +

                                This section is non-normative.

                                +Some +additional + +This +section +describes + +specific +recommendations + +risks + +relevant +for +WoT + +script +developers: + +developers. + +

                                9.2.1 +Corrupted +Script +Input +Security +and +Privacy +Risk +

                                +A +typical +way +to +compromise +any +process +is +to +send +it +a +corrupted + +script +instance +may +receive +data +formats +defined +by +the +TD, +or +data +formats +defined +by +the +applications. +While +the +WoT +Scripting +Runtime +SHOULD +perform +validation +on +all + +input +via +one +of + +fields +defined +by + +the +exposed +interfaces. +Therefore + +TD, +scripts +may +be +still +exploited +by +input +data. +

                                +Mitigation: +
                                +Script + +developers +SHOULD + +should + +perform +validation +on +all +WoT + +application +defined + +script +inputs, +including + +inputs. +In +addition +to +input +validation, + + +fuzzing +. + + +could +be +used +to +verify +that +the +input +processing +is +done +correctly. + +There +are +many +tool + +tools + +and +techniques +in +existence +to +do +such +validation. +More +details +can +be +found +in +[ +WOT-SECURITY-TESTING +]. +As +any +software, +complex +scripts +with +a +lot +of +functionality +presents +a +higher +risk +of +development +mistakes. +Such +scripts +are +also +hard +to +verify +and +test +appropriately. +Therefore +developers +SHOUD +minimize +the +functionality +and +complexity +of +WoT +scripts. + +[WOT-SECURITY-TESTING]. +

                                9.2.2 +Denial +Of +Service +Security +Risk +

                                +If +a +WoT + +script +performs +a +heavy +functional +processing +on +received +requests +before +the +request +is +authenticated, +it +presents +a +great +risk +for +Denial-Of-Service +(DOS) +attacks. +Therefore +WoT +scripts +SHOULD + +

                                +
                                +Mitigation: +
                                +Scripts +should + +avoid +heavy +functional +processing +without +prior +successful +authentication +of +requestor. +The +set +of +recommended +authentication +mechanisms +can +be +found +in +[ +WOT-SECURITY-BEST-PRACTICES +]. + +[WOT-SECURITY-BEST-PRACTICES]. +

                                9.2.3 +Stale +TD +Security +Risk +

                                +During +the +lifetime +of +a + +WoT +developers +should +remember +that + +network, + +a +content +of +a +TD +can +change, +including + +change. +This +includes + +its +identified, +id, + +identifier, + +which +is + +might + +not +be + +an +immutable +identifier. +Therefore +WoT +scripts +SHOULD + +one +and +might +be +updated +periodically. +

                                +Mitigation: +
                                +Scripts +should + +use +the +provided +WoT +script + +this + +API +to +subscribe +for +notifications +on +TD +changes. + +changes +and +do +not +rely +on +TD +values +to +remain +persistent. +
                                Editor's note

                                +While +stale +TDs +can +present +a +potential +problem +for +WoT +network +operation, +it +might +not +be +a +security +risk. +

                                10. +

                                10. +Terminology +and +conventions +

                                +The +generic +WoT +terminology +is +defined +in +[ +WOT-ARCHITECTURE +]: + +[WOT-ARCHITECTURE]: + +Thing +, + +Thing +Description + +(in +short + +TD + +), + +Web +of +Things + +(in +short + + +WoT + + +), + +WoT +Interface +, + + +(same +as + +WoT +network +interface + +), + +Protocol +Bindings +, + +WoT +Runtime +, + +Consuming +a +Thing +Description +, + +Thing +Directory +, + +WoT +Interactions +, + +Property +, + +Action +, + +Event + +etc. +

                                + +JSON-LD + +is +defined +in +[ +JSON-LD +] + +[JSON-LD] + +as +a +JSON +document +that +is +augmented +with +support +for +Linked +Data. +

                                +The +terms + +URL +and + +, + +URL +scheme +, +URL +host +, +URL +path +, + +URL +record +, +parse +a +URL +, +absolute-URL +string +, +path-absolute-URL +string +, +basic +URL +parser + + +are +defined +in +[ +URL +]. + +[URL]. + +

                                +The +following + +terms + +MIME +type +, +Parsing +a +MIME +type +, +Serializing +a +MIME +type +, +valid +MIME +type +string +, +JSON +MIME +type + +are +defined +in +[ +HTML52 +] +and + +[MIMESNIFF]. +

                                +The +terms + +UTF-8 +encoding +, +UTF-8 +decode +, +encode +, +decode + +are +used + +defined + +in +the +context +of +browser +implementations: +browsing +context +, +top-level +browsing +context +, +global +object + +[ENCODING]. +

                                +string +, +parse +JSON +from +bytes + + +and + +serialize +JSON +to +bytes +, +are +defined +in +[INFRA]. +

                                +The +terms + +, +incumbent +settings +object + + +throw + +, +Document + +, + +, +document +base +URL + + +creating + +, +Window + +, + +, +WindowProxy + + +DOMString + +, +origin + +, + +, +ASCII +serialized +origin + + +Dictionary + +, +executing +algorithms +in +parallel + +, + +, +queue +a +task + + +ArrayBuffer + +, +task +source + +, + +, +iframe + + +BufferSource + +, +valid +MIME +type + +, + +. +A +browsing +context +refers +to +the +environment +in +which +Document +objects +are +presented +to +the +user. +A +given +browsing +context +has +a +single + + +any + +WindowProxy + +, + +not +present +, +object, +but +it +can +have +many + + +DOMException + +Document + +, + +objects, +with +their +associated + + +AbortError + +Window + +, + + +SyntaxError + + +objects. +The +script +execution +context +associated +with +the +browsing +context +identifies +the +entity +which +invokes +this +API, +which +can +be +a +web +app +, +a +web +page +, +or +an +iframe +. +The +term +secure +context + +is +defined +in +[ + +, + +WEBAPPSEC + + +NotSupportedError + +]. + +, + + +NetworkError + +Error +, +EvalError +, +RangeError +, +ReferenceError +, +SyntaxError + +, + + +TypeError + +, +URIError + + +, + + +NotReadableError + +script +execution +context + +, + +, +Promise + + +TimeoutError + +, +JSON + +, + +, +JSON.stringify + + +NoModificationAllowedError + +and +JSON.parse + +, + + +SecurityError +, +are +defined +in +[ +ECMASCRIPT +]. + +[WEBIDL]. + +

                                + +DOMString +, +USVString +, +ArrayBuffer +, + + +Promise + +BufferSource + +, + +Error +, +JSON +, +JSON.stringify +, +JSON.parse + + +and +any + + +internal +slots + + +are +defined +in +[ +WEBIDL +]. + +[ECMASCRIPT]. + +

                                +The +terms + +browsing +context +, +top-level +browsing +context +, +global +object +, +current +settings +object +, +executing + +algorithms +utf-8 +encode + + +in +parallel + + +, + +are +defined +in +[HTML5] + +and +utf-8 +decode + +are +used +in +the +context +of +browser +implementations. +

                                +The +term + +secure +context + + + +are + +is + +defined +in +[ +ENCODING +]. + +[WEBAPPSEC]. + +

                                + +IANA +media +type + +s +(formerly +known +as +MIME +types) +are +defined +in + +RFC2046 +. +

                                +The +terms + +hyperlink +reference + +and + +relation +type + +are +defined +in +[ +HTML52 +] + +[HTML5] + +and + +RFC8288 +. +

                                11. +Conformance +

                                A. +API +design +rationale + +

                                +As +well +as +sections +marked +as +non-normative, +all +authoring +guidelines, +diagrams, +examples, +and +notes +in +this +specification +are +non-normative. +Everything +else + +API +rationale +usually +belongs +to +a +separate +document, +but + +in +this +specification +is +normative. + +the +WoT +case +the +complexity +of +the +context +justifies +including +basic +rationale +here. + +

                                A.1 +Approaches +to +WoT +application +development +

                                +The +key +words +MAY +, +MUST +, +SHOULD +, + +WoT +Interest +Group + +and +SHOULD NOT +are + +Working +Group +have +explored +different +approaches +to +application +development +for +WoT +that +have +been +all +implemented +and +tested. +

                                A.1.1 +No +Scripting +API +

                                +It +is +possible + +to +develop +WoT +applications +that +only +use +the + +WoT +network +interface +, +typically +exposed +by +a +WoT +gateway +that +presents +a +REST-ful +API +towards +clients +and +implements +IoT +protocol +plugins +that +communicate +with +supported +IoT +deployments. +One +such +implementation +is +the + +Mozilla +WebThings + +platform. +

                                A.1.2 +Simple +Scripting +API +

                                +WoT + +Thing + +s +show +good +synergy +with +software +objects, +so +a + +Thing + +can + +be +interpreted + +represented + +as +described + +a +software +object, +with + +Properties + +represented +as +object +properties, + +Action + +s +as +methods, +and + +Event + +s +as +events. +In +addition, +metadata +is +stored + +in +[ +RFC2119 + +special +properties. +Consuming +and +exposing +is +done +with +factory +methods +that +produce +a +software +object +that +directly +represents +a +remote + +Thing + + +]. + +and +its +interactions. +One +such +implementation +is +the + +Arena +Web +Hub + +project. + +

                                +This +document +defines +conformance +criteria + +In +the +next +example, +a + +Thing + +that +apply +to + +represents +interactions +with + +a +single +product: + +lock +would +look +like + +the +UA +(user +agent) +that +implements + +following: + +the +interfaces +it +contains. + + +status + +property +and +the + +open() + +method +are +directly +exposed +on +the +object. + +

                                +
                                + Example 8: Open a lock with a simple API + 
                                          let lock = await WoT.consume(‘https://td.my.com/lock-00123’);
+          console.log(lock.status);
+          lock.open('withThisKey');
+
                                +

                                A.1.3 +This +API, +aligned +with +[WOT-TD] +

                                +Since +the +direct +mapping +of + +Thing + +s +to +software +objects +have +had +some +challenges, +this + +specification +can +be +used +for +implementing + +takes +another +approach +that +exposes +software +objects +to +represent +the + +Thing + +metadata +as +data +property +and + +the +WoT +Scripting + +interactions +as +methods. +One +implementation +is + +node-wot + +in +the +the + +Eclipse +ThingWeb + +project, +which +is +the +current +reference +implementation +of +the + +API +specified + +in +multiple +programming +languages. + +this +document. +

                                +The +interface +definitions + +same +example +now +would +look +like +the +following: +the + +status + +property +and +the + +open() + +method + +are +specified + +represented +indirectly. +

                                +
                                + Example 9: Open a lock + 
                                          let res = await fetch(‘https://td.my.com/lock-00123’);
+          let td = await res.json();
+          let lock = new ConsumedThing(td);
+          console.log(lock.readProperty(‘status’));
+          lock.invokeAction(‘open’, 'withThisKey');
+
                                +

                                +In +conclusion, +the +WoT +WG +decided +to +explore +the +third +option +that +closely +follows +the +[WOT-TD] +specification. +Based +on +this, +a +simple +API +can +also +be +implemented. +Since +Scripting +is +an +optional +module + +in +[ +WEBIDL +]. + +WoT, +this +leaves +room +for +applications +that +only +use +the +WoT +network +interface. +Therefore +all +three +approaches +above +are +supported +by +[WOT-TD]. + +

                                +The +user +agent +(UA) +may + +Moreover, +the +WoT +network +interface +can + +be +implemented +in +the +browser, +or + +many +languages +and +runtimes. +Consider +this +API +an +example +for +what +needs +to +be +taken +into +consideration +when +designing +a +Scripting +API +for +WoT. +

                                A.2 +Fetching +and +validating +a +TD +

                                +The + +fetch(url) + +method +has +been +part +of +this +API + +in +earlier +versions. +However, +now +fetching + +a +separate +runtime +environment, + + +TD + +given +a +URL +should +be +done +with +an +external +method, + +such +as +Node.js + +the + +Fetch +API + + +or +small +embedded +runtimes. +Implementations + +a +HTTP +client +library, +which +offer +already +standardized +options +on +specifying +fetch +details. +The +reason +is + +that +while +simple +fetch +operations +(covering +most + +use +ECMAScript +executed + +cases) +could +be +done + +in +a +browser + +this +API, +when +various +fetch +options +were +needed, +there +was +no +point +in +duplicating +existing +work + +to +implement +the +APIs +defined + +re-expose +those +options + +in +this +document +MUST +implement +them +in + +API. +

                                +Since +fetching + +a +manner +consistent +with +the +ECMAScript +Bindings + + +TD + +has +been +scoped +out, +and + +TD + +validation +is + +defined +externally + +in +the +Web +IDL + +[WOT-TD], +that +is +scoped +out, +too. +This + +specification +[ +WEBIDL + +expects +a + +TD + + +]. + +as + +parsed +JSON +object + +that +has +been +validated +according +to +the +[WOT-TD] +specification. + +

                                A.3 +Factory +vs +constructors +

                                +Implementations + +The +factory +methods +for +consuming +and +exposing + +Thing + +s +are +asynchronous +and +fully +validate +the +input + +TD +. +In +addition, +one +can +also +construct + +ConsumedThing + +and + +ExposedThing + +by +providing +a +parsed +and +validated + +TD +. +Platform +initialization +is +then +done +when +needed +during +the +WoT +interactions. +So +applications + +that +use +TypeScript +or +ECMAScript +in + +prefer +validating + +a +runtime + + +TD + +themselves, +may +use +the +constructors, +whereas +applications +that +leave +validation + +to +implement + +implementations +and +prefer +interactions +initialized +up +front +SHOULD +use + +the +APIs +defined +in +this +document +MUST +implement +them +in +a +manner +consistent +with + +factory +methods +on + +the +TypeScript +Bindings +defined +in + + +WoT +API +object +.

                                A.4 +Observers +

                                +Earlier +drafts +used + +the +TypeScript +specification +[ +TYPESCRIPT + + +Observer + + +]. + +construct, +but +since +it +has +not +become +standard, +a +new +design +was +needed +that +was +light +enough +for +embedded +implementations. +Therefore +observing + +Property + +changes +and +handling +WoT + +Event + +s +is +done +with +callback +registrations. + +

                                A.5 +Using +Events +

                                This +document +serves +a +general +description +of + +API +ended +up +not +using +software +events +at +all, +for + +the +following +reasons: +

                                • +Subscription +to + +WoT +Scripting +API. +Language + + +Event + +s +may +be +different +from +handling +software +events +(subscription +might +need +parameters, +might +involve +security +tokens +etc). +
                                • +Most +implementations +are +for +Node.js + +and +runtime +specific + +browser +implementations +will +likely +be +libraries +(because +possible +dependency +management + +issues +are +discussed + +in +separate +extensions + +native +implementations), +using +Events +has +been +challenging. +
                                • +Observing + +Property + +changes +and +handling +WoT + +Event + +s +is +done +with +the +solution +above. +
                                +

                                A.6 +Polymorphic +functions +

                                +The +reason +to +use +function +names +like + +readProperty() +, +readMultipleProperties() + +etc. +instead + +of +this +document. + +a +generic +polymorphic + +read() + +function +is +that +the +current +names +map +exactly +to +the + +"op" + +vocabulary +from +the + +Form + +definition +in +[WOT-TD]. + +

                                B. +Changes +

                                A. +

                                The +following +is +a +list +of +major +changes +to +the +document. +Major +versions +of +this +specification +are +the +following: +

                                +

                                +For +a +complete +list +of +changes, +see +the + +github +change +log +. +You +can +also +view +the + +recently +closed +issues +. +

                                Make +the +Scripting +API +refer +to +(rather +then +locally +re-define) +the +data +structures +defined +in +the +Thing +Description +specification +. +

                                C. +Open +issues +

                                B. +

                                The +following +problems +are +being +discussed +and +need +most +attention:

                                +
                                  +
                                • +Security +related +metadata +(https://github.com/w3c/wot-scripting-api/issues/91). +Providing +Protocol +Binding +for +ExposedThing +(https://github.com/w3c/wot-scripting-api/issues/45). + +Script +management +and +runtime +related +issues +(https://github.com/w3c/wot-scripting-api/issues/) +
                                  • +
                                • +An +explicit +API +for +adding +and +removing + +Property +, +Action + +and + +Event + +definitions +on + +ExposedThing + +(it +was +present +in +earlier +versions, +but +removed +for +complexity +and +a +simpler +way +to +do +it. +
                                  • +
                                +
                                C. +Acknowledgments +

                                D. +Full +Web +IDL +

                                typedef object ThingDescription;
+
+      [SecureContext, Exposed=(Window,Worker)]
+      interface WOT {
+        // methods defined in UA conformance classes
+      };
+
+      partial interface WOT {
+        Promise<ConsumedThing> consume(ThingDescription td);
+      };
+
+      partial interface WOT {
+        Promise<ExposedThing> produce(ThingDescription td);
+      };
+
+      partial interface WOT {
+        ThingDiscovery discover(optional ThingFilter filter = null);
+      };
+
+      [SecureContext, Exposed=(Window,Worker)]
+      interface ConsumedThing {
+        constructor(ThingDescription td);
+        Promise<any> readProperty(DOMString propertyName,
+                                  optional InteractionOptions options = null);
+        Promise<PropertyMap> readAllProperties(optional InteractionOptions options = null);
+        Promise<PropertyMap> readMultipleProperties(
+                                  sequence<DOMString> propertyNames,
+                                  optional InteractionOptions options = null);
+        Promise<void> writeProperty(DOMString propertyName,
+                                    any value,
+                                    optional InteractionOptions options = null);
+        Promise<void> writeMultipleProperties(PropertyMap valueMap,
+                                    optional InteractionOptions options = null);
+        Promise<any> invokeAction(DOMString actionName,
+                                    optional any params = null,
+                                    optional InteractionOptions options = null);
+        Promise<void> observeProperty(DOMString name,
+                                    WotListener listener,
+                                    optional InteractionOptions options = null);
+        Promise<void> unobserveProperty(DOMString name);
+        Promise<void> subscribeEvent(DOMString name,
+                                    WotListener listener,
+                                    optional InteractionOptions options = null);
+        Promise<void> unsubscribeEvent(DOMString name);
+        ThingDescription getThingDescription();
+      };
+      dictionary InteractionOptions {
+        object uriVariables;
+      };
+      typedef object PropertyMap;
+      callback WotListener = void(any data);
+
+      [SecureContext, Exposed=(Window,Worker)]
+      interface ExposedThing: ConsumedThing {
+        ExposedThing setPropertyReadHandler(DOMString name,
+                PropertyReadHandler readHandler);
+        ExposedThing setPropertyWriteHandler(DOMString name,
+                PropertyWriteHandler writeHandler);
+        ExposedThing setActionHandler(DOMString name, ActionHandler action);
+        void emitEvent(DOMString name, any data);
+        Promise<void> expose();
+        Promise<void> destroy();
+      };
+      callback PropertyReadHandler = Promise<any>(
+              optional InteractionOptions options = null);
+      callback PropertyWriteHandler = Promise<void>(any value,
+              optional InteractionOptions options = null);
+      callback ActionHandler = Promise<any>(any params,
+              optional InteractionOptions options = null);
+
+      [SecureContext, Exposed=(Window,Worker)]
+      interface ThingDiscovery {
+        constructor(optional ThingFilter filter = null);
+        readonly attribute ThingFilter? filter;
+        readonly attribute boolean active;
+        readonly attribute boolean done;
+        readonly attribute Error? error;
+        void start();
+        Promise<ThingDescription> next();
+        void stop();
+      };
+
+typedef DOMString DiscoveryMethod;
+
+        dictionary ThingFilter {
+          (DiscoveryMethod or DOMString) method = "any";
+          USVString? url;
+          USVString? query;
+          object? fragment;
+        };

                                E. +Acknowledgements + +

                                +Special +thanks +to +former +editor +Johannes +Hund +(until +August +2017, +when +at +Siemens +AG) +and +Kazuaki +Nimura +(until +December +2018) + +for +developing +this +specification. +Also, +the +editors +would +like +to +thank +Dave +Raggett, +Matthias +Kovatsch, +Michael +Koster +and + +Koster, +Elena +Reshetova, + +Michael +McCool +as +well +as +the +other +WoT +WG +members + +for +their +comments + +comments, +contributions + +and +guidance. +

                                D. +References +D.1 +Normative +references +[ECMASCRIPT] +ECMAScript +Language +Specification +. +Ecma +International. +URL: +https://tc39.github.io/ecma262/ +[ENCODING] +Encoding +. +Anne +van +Kesteren; +Joshua +Bell; +Addison +Phillips. +W3C. +15 +December +2016. +W3C +Candidate +Recommendation. +URL: +https://www.w3.org/TR/encoding/ +[HTML52] +HTML +5.2 +. +Steve +Faulkner; +Arron +Eicholz; +Travis +Leithead; +Alex +Danilo; +Sangwhan +Moon; +Erika +Doyle +Navara; +Theresa +O'Connor; +Robin +Berjon. +W3C. +14 +December +2017. +W3C +Recommendation. +URL: +https://www.w3.org/TR/html52/ +[JSON-LD] +JSON-LD +1.0 +. +Manu +Sporny; +Gregg +Kellogg; +Markus +Lanthaler. +W3C. +16 +January +2014. +W3C +Recommendation. +URL: +https://www.w3.org/TR/json-ld/ +[RFC2119] +Key +words +for +use +in +RFCs +to +Indicate +Requirement +Levels +. +S. +Bradner. +IETF. +March +1997. +Best +Current +Practice. +URL: +https://tools.ietf.org/html/rfc2119 +[TYPESCRIPT] +TypeScript +Language +Specification +. +Microsoft. +1 +October +2012. +URL: +https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md +[URL] +URL +Standard +. +Anne +van +Kesteren. +WHATWG. +Living +Standard. +URL: +https://url.spec.whatwg.org/ +[WEBAPPSEC] +Secure +Contexts +. +W3C. +17 +July +2015. +URL: +https://w3c.github.io/webappsec/specs/powerfulfeatures +[WEBIDL] +Web +IDL +. +Cameron +McCormack; +Boris +Zbarsky; +Tobie +Langel. +W3C. +15 +December +2016. +W3C +Editor's +Draft. +URL: +https://heycam.github.io/webidl/ +[WOT-ARCHITECTURE] +Web +of +Things +Architecture +. +W3C. +20 +August +2017. +URL: +https://w3c.github.io/wot-architecture/ +[WOT-SECURITY-BEST-PRACTICES] +Web +of +Things +Security +and +Privacy +Best +Practices +(WIP) +. +W3C. +WIP. +URL: +https://github.com/w3c/wot-security/blob/master/wot-security-best-practices.md +[WOT-SECURITY-CONSIDERATIONS] +Web +of +Things +Security +and +Privacy +Considerations +. +W3C. +28 +August +2017. +URL: +https://w3c.github.io/wot-security/ +[WOT-SECURITY-TESTING] +Web +of +Things +Security +Testing +and +Validation +. +W3C. +WIP. +URL: +https://github.com/w3c/wot-security/blob/master/wot-security-testing.md +[WOT-TD] +WoT +Thing +Description +. +W3C. +21 +October +2018. +URL: +https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/ +D.2 +Informative +references +[HTML] +HTML +Standard +. +Anne +van +Kesteren; +Domenic +Denicola; +Ian +Hickson; +Philip +Jägenstedt; +Simon +Pieters. +WHATWG. +Living +Standard. +URL: +https://html.spec.whatwg.org/multipage/ +↑ +
                                0 of 3546
                                ‹ previous
                                next ›
                                +

                                F. References

                                + +
                                +

                                F.1 Normative references

                                +
                                +
                                [ECMASCRIPT]
                                ECMAScript Language Specification. Ecma International. URL: https://tc39.github.io/ecma262/
                                [ENCODING]
                                Encoding Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://encoding.spec.whatwg.org/
                                [HTML]
                                HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
                                [HTML5]
                                HTML5. Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. W3C. 27 March 2018. W3C Recommendation. URL: https://www.w3.org/TR/html5/
                                [INFRA]
                                Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
                                [JSON-LD]
                                JSON-LD 1.0. Manu Sporny; Gregg Kellogg; Markus Lanthaler. W3C. 16 January 2014. W3C Recommendation. URL: https://www.w3.org/TR/json-ld/
                                [MIMESNIFF]
                                MIME Sniffing Standard. Gordon P. Hemsley. WHATWG. Living Standard. URL: https://mimesniff.spec.whatwg.org/
                                [RFC2119]
                                Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
                                [RFC8174]
                                Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174
                                [TYPESCRIPT]
                                TypeScript Language Specification. Microsoft. 1 October 2012. URL: https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md
                                [URL]
                                URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/
                                [WEBAPPSEC]
                                Secure Contexts. W3C. 17 July 2015. URL: https://w3c.github.io/webappsec/specs/powerfulfeatures
                                [WEBIDL]
                                Web IDL. Boris Zbarsky. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/
                                [WOT-ARCHITECTURE]
                                Web of Things Architecture. W3C. 20 August 2017. URL: https://w3c.github.io/wot-architecture/
                                [WOT-PROTOCOL-BINDINGS]
                                Web of Things Protocol Binding Templates. W3C. 20 August 2017. URL: https://w3c.github.io/wot-binding-templates/
                                [WOT-SECURITY-BEST-PRACTICES]
                                Web of Things Security and Privacy Best Practices. W3C. WIP. URL: https://github.com/w3c/wot-security/blob/master/wot-security-best-practices.md
                                [WOT-SECURITY-GUIDELINES]
                                Web of Things Security and Privacy Guidelines. W3C. 28 August 2017. URL: https://w3c.github.io/wot-security/
                                [WOT-SECURITY-TESTING]
                                Web of Things Security Testing and Validation. W3C. WIP. URL: https://github.com/w3c/wot-security/blob/master/wot-security-testing.md
                                [WOT-TD]
                                WoT Thing Description . W3C. 20 August 2017. URL: https://w3c.github.io/wot-thing-description/
                                +
                                \ No newline at end of file diff --git a/releases/wd4/manifest.txt b/releases/wd4/manifest.txt new file mode 100644 index 00000000..578b5801 --- /dev/null +++ b/releases/wd4/manifest.txt @@ -0,0 +1,2 @@ +Overview.html +diff.html From 01afe70975de36d824b612eeaf51bbfd49df1633 Mon Sep 17 00:00:00 2001 From: ashimura Date: Mon, 21 Oct 2019 17:38:18 +0900 Subject: [PATCH 357/464] tidy again with -i option --- releases/wd4/Overview.html | 8977 ++++++++++++++++++++---------------- 1 file changed, 4894 insertions(+), 4083 deletions(-) diff --git a/releases/wd4/Overview.html b/releases/wd4/Overview.html index 81dcda3d..c2ba5bf6 100644 --- a/releases/wd4/Overview.html +++ b/releases/wd4/Overview.html @@ -1,69 +1,68 @@ - - - - - - - + - - + -Web of Things (WoT) Scripting API - - + Web of Things (WoT) Scripting API + - - + - - + - - + - - + + - - + - - - - + } + + + -
                                -

                                Web of Things (WoT) Scripting -API

                                -

                                W3C Editor's Draft

                                -
                                -
                                This version:
                                -
                                https://w3c.github.io/wot-scripting-api/
                                -
                                Latest published version:
                                -
                                https://www.w3.org/TR/wot-scripting-api/
                                -
                                Latest editor's draft:
                                -
                                https://w3c.github.io/wot-scripting-api/
                                -
                                Editors:
                                -
                                Zoltan -Kis (Intel)
                                -
                                Daniel -Peintner (Siemens AG)
                                -
                                Johannes -Hund (Former Editor, when at Siemens AG)
                                -
                                Kazuaki -Nimura (Former Editor, at Fujitsu Ltd.)
                                -
                                Repository:
                                -
                                On -GitHub
                                -
                                File -a bug
                                -
                                Contributors:
                                -
                                Contributors -on GitHub
                                -
                                -

                                Copyright -© 2017-2019 W3C® (MIT, ERCIM, -Keio, Beihang). W3C liability, -trademark -and -permissive document license rules apply.

                                -
                                -
                                -

                                Abstract

                                -

                                The main Web of Things (WoT) concepts are described -in the WoT -Architecture document. The Web of Things is made of entities -(Things) that can describe their capabilities in a -machine-interpretable 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).

                                -

                                Scripting is an optional "convenience" building block in WoT and -it is typically used in gateways that are able to run a WoT -Runtime and -script management, providing a convenient way to extend WoT -support to new types of endpoints and implement WoT applications -such as -Thing Directory.

                                -

                                This specification describes a programming interface -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 specification deliberately follows the WoT Thing Description -specification closely. It is possible to implement simpler APIs -on top of this API, or implementing directly the WoT network facing -interface (i.e. the WoT Interface).

                                -
                                -
                                Editor's note
                                -

                                This specification is implemented at least by the -Thingweb project also known -as node-wot, which -is considered the reference open source implementation at the -moment. Check its source code, -including examples. Other, -closed source implementations have been made by WG member companies -and tested against node-wot in -plug-fests.

                                -
                                -
                                -
                                -

                                Status of This Document

                                -

                                This section describes the status of this document at the -time of its publication. Other documents may supersede this -document. A list of current W3C publications and the latest -revision of this technical report can be found in the W3C technical reports index -at https://www.w3.org/TR/.

                                -

                                Implementers need to be aware that this specification is -considered unstable. Vendors interested in implementing this -specification before it eventually reaches the Candidate -Recommendation phase should subscribe to the repository and take -part in the discussions.

                                -
                                -
                                Editor's note: The W3C WoT WG is asking for feedback
                                -

                                Please contribute to this draft using the GitHub Issue -feature of the WoT Scripting API -repository. For feedback on security and privacy considerations, -please use the WoT Security and -Privacy Issues.

                                -
                                -

                                This document was published by the Web of Things Working Group as an -Editor's Draft.

                                -

                                Comments regarding this document are welcome. Please send them -to public-wot-wg@w3.org -(archives).

                                -

                                Publication as an Editor's Draft does not imply endorsement by -the W3C Membership. -This is a draft document and may be updated, replaced or obsoleted -by other documents at any time. It is inappropriate to cite this -document as other than work in progress.

                                -

                                This document was produced by a group operating under the -W3C Patent Policy. -W3C maintains a -public list of any patent -disclosures made in connection with the deliverables of the -group; that page also includes instructions for disclosing a -patent. An individual who has actual knowledge of a patent which -the individual believes contains Essential -Claim(s) must disclose the information in accordance with -section -6 of the W3C Patent -Policy.

                                -

                                This document is governed by the 1 March 2019 -W3C Process -Document.

                                -
                                - -
                                -

                                1. -Introduction

                                -

                                WoT provides layered interoperability based on how Things -are used: "consumed" and "exposed", as defined -in [WOT-ARCHITECTURE].

                                -

                                By consuming a TD, a client Thing creates a local -runtime resource model that allows accessing the Properties, Actions and Events exposed by the server -Thing on a remote device.

                                -
                                -

                                Exposing a Thing requires:

                                - -This specification describes how to expose and consume Things -by a script. Also, it defines a generic API for Thing -discovery.
                                -
                                -
                                Note
                                -

                                Typically scripts are meant to be used on bridges or -gateways that expose and control simpler devices as WoT Things -and have means to handle (e.g. install, uninstall, update etc.) and -run scripts.

                                -
                                -
                                -
                                Note
                                -

                                This specification does not make assumptions on how the -WoT Runtime handles and runs scripts, including single or -multiple tenancy, script deployment and lifecycle management. The -API already supports the generic mechanisms that make it possible -to implement script management, for instance by exposing a manager -Thing whose Actions (action handlers) implement script -lifecycle management operations.

                                -
                                -
                                -
                                -

                                2. Use -Cases

                                -

                                This section is non-normative.

                                -

                                The following scripting use cases are supported in this -specification:

                                -
                                -

                                2.1 -Consuming a Thing

                                - -
                                -
                                -

                                2.2 -Exposing a Thing

                                -
                                  -
                                • Exposing the Thing includes generating the protocol -bindings in order to access lower level functionality.
                                  • -
                                • Create a local Thing to be exposed, based on a Thing Description provided in string serialized format, -or out of an existing Thing object.
                                  • -
                                • Add a Property definition to the Thing.
                                  • -
                                • Remove a Property definition from the Thing.
                                  • -
                                • Add an Action definition to the Thing.
                                  • -
                                • Remove an Action definition from the Thing.
                                  • -
                                • Add a WoT Event definition to the Thing.
                                  • -
                                • Remove a WoT Event definition from the Thing.
                                  • -
                                • Emit a WoT Event, i.e. notify all subscribed -listeners.
                                  • -
                                • Register service handlers for external requests: -
                                    -
                                  • to retrieve a Property value;
                                    • -
                                  • to update a Property value;
                                    • -
                                  • to invoke an Action: take the parameters from the -request, execute the defined action, and return the result;
                                    • -
                                  -
                                  • -
                                -
                                -
                                -

                                2.3 -Discovery

                                -
                                  -
                                • Discover Things in a network by sending a broadcast -request.
                                  • -
                                • Discover Things running in the local WoT -Runtime.
                                  • -
                                • Discover nearby Things, for instance connected by NFC or -Bluetooth.
                                  • -
                                • Discover Things by sending a discovery request to a -given registry.
                                  • -
                                • Discover Things filtered by filters defined on -Thing Descriptions
                                  • -
                                • Discover Things filtered by semantic queries.
                                  • -
                                • Stop or suppress an ongoing discovery process.
                                  • -
                                • Optionally specify a timeout to the discovery process after -which it is stopped/suppressed.
                                  • -
                                -
                                -
                                -
                                -

                                3. -Conformance

                                -

                                As well as sections marked as non-normative, all authoring -guidelines, diagrams, examples, and notes in this specification are -non-normative. Everything else in this specification is -normative.

                                -

                                The key words MAY, MUST, and SHOULD in this -document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, -they appear in all capitals, as shown here.

                                -

                                This specification describes the conformance criteria for the -following classes of user agent (UA).

                                -

                                Due to requirements of small embedded implementations, splitting -WoT client and server interfaces was needed. Then, discovery is a -distributed application, but typical scenarios have been covered by -a generic discovery API in this specification. This resulted in -using 3 conformance classes for a UA that implements this API, -one for client, one for server, and one for discovery. An -application that uses this API can introspect for the presence of -the consume(), produce() and -discover() methods on the WoT -API object in order to determine which conformance class the -UA -implements.

                                -
                                -
                                WoT -Consumer UA
                                -
                                -

                                Implementations of this conformance class MUST implement the ConsumedThing interface and the -consume() method on the WoT API object.

                                -
                                -
                                WoT -Producer UA
                                -
                                -

                                Implementations of this conformance class MUST implement ExposedThing interface and the -produce() method on the WoT API object.

                                -
                                -
                                WoT -Discovery UA
                                -
                                -

                                Implementations of this conformance class MUST implement the ThingDiscovery interface and the -discover() method on the WoT API object.

                                -
                                -
                                -

                                These conformance classes MAY be implemented in a single UA.

                                -

                                This specification can be used for implementing the WoT -Scripting API in multiple programming languages. The interface -definitions are specified in [WEBIDL].

                                -

                                The UA may be implemented in the browser, or in a separate -runtime environment, such as Node.js or in small embedded -runtimes.

                                -

                                Implementations that use ECMAScript executed in a browser to -implement the APIs defined in this document MUST implement them in a manner consistent with -the ECMAScript Bindings defined in the Web IDL specification -[WEBIDL].

                                -

                                Implementations that use TypeScript or ECMAScript in a runtime -to implement the APIs defined in this document MUST implement them in a manner consistent with -the TypeScript Bindings defined in the TypeScript specification -[TYPESCRIPT].

                                -
                                -
                                -

                                4. -The ThingDescription -type

                                -
                                typedef object 
+    
+    
                                Web of Things (WoT)
+    Scripting API
                                
+    
                                W3C Editor's Draft 
                                
+    
                                
+      
                                This version:
                                
+      
                                
+        https://w3c.github.io/wot-scripting-api/
+      
                                
+      
                                Latest published version:
                                
+      
                                
+        https://www.w3.org/TR/wot-scripting-api/
+      
                                
+      
                                Latest editor's draft:
                                
+      
                                
+        https://w3c.github.io/wot-scripting-api/
+      
                                
+      
                                Editors:
                                
+      
                                
+        Zoltan Kis (Intel)
+      
                                
+      
                                
+        Daniel Peintner (Siemens AG)
+      
                                
+      
                                Johannes Hund (Former Editor, when at
+      Siemens AG)
                                
+      
                                Kazuaki Nimura (Former Editor, at Fujitsu
+      Ltd.)
                                
+      
                                Repository:
                                
+      
                                
+        On
+        GitHub
+      
                                
+      
                                
+        File a
+        bug
+      
                                
+      
                                Contributors:
                                
+      
                                
+        
+        Contributors on GitHub
+      
                                
+    
                                
+    
                                Copyright
+    © 2017-2019 W3C®
+    (MIT,
+    ERCIM,
+    Keio, Beihang). W3C 
+    liability, 
+    trademark and 
+    permissive document license rules apply.
                                
+    
                                
+  
+  
                                
+    
                                Abstract
                                
+    
                                The main Web of Things (WoT) concepts are
+    described in the WoT Architecture
+    document. The Web of Things is made of entities (Things) that can describe their capabilities in a
+    machine-interpretable 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).
                                
+    
                                Scripting is an optional "convenience" building block in WoT
+    and it is typically used in gateways that are able to run a
+    WoT Runtime and 
+    script management, providing a convenient way to extend WoT
+    support to new types of endpoints and implement WoT
+    applications such as 
+    Thing Directory.
                                
+    
                                This specification describes a programming interface
+    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 specification deliberately follows the WoT Thing
+    Description specification closely. It is possible to
+    implement simpler APIs on top of this API, or implementing
+    directly the WoT network facing interface (i.e. the WoT Interface).
                                
+    
                                
+      
                                
+        Editor's note
+      
                                
+      
                                This specification is implemented at least by the
+      Thingweb project also
+      known as node-wot,
+      which is considered the reference open source implementation
+      at the moment. Check its source
+      code, including examples.
+      Other, closed source implementations have been made by WG
+      member companies and tested against node-wot
+      in plug-fests.
                                
+    
                                
+  
                                
+  
                                
+    
                                Status of This Document
                                
+    
                                This section describes the status of this document at
+    the time of its publication. Other documents may supersede this
+    document. A list of current W3C publications and the
+    latest revision of this technical report can be found in the
+    W3C technical reports
+    index at https://www.w3.org/TR/.
                                
+    
                                Implementers need to be aware that this specification is
+    considered unstable. Vendors interested in implementing this
+    specification before it eventually reaches the Candidate
+    Recommendation phase should subscribe to the repository and
+    take part in the discussions.
                                
+    
                                
+      
                                
+        Editor's note: The
+        W3C WoT WG is asking for feedback
+      
                                
+      
                                Please contribute to this draft using the
+      GitHub
+      Issue feature of the WoT Scripting
+      API repository. For feedback on security and privacy
+      considerations, please use the WoT Security and
+      Privacy Issues.
                                
+    
                                
+    
                                This document was published by the Web of Things Working Group as
+    an Editor's Draft.
                                
+    
                                Comments regarding this document are welcome. Please send
+    them to public-wot-wg@w3.org
+    (archives).
                                
+    
                                Publication as an Editor's Draft does not imply endorsement
+    by the W3C
+    Membership. This is a draft document and may be updated,
+    replaced or obsoleted by other documents at any time. It is
+    inappropriate to cite this document as other than work in
+    progress.
                                
+    
                                This document was produced by a group operating under the
+    W3C Patent Policy.
+    W3C maintains a
+    public list of any patent
+    disclosures made in connection with the deliverables of the
+    group; that page also includes instructions for disclosing a
+    patent. An individual who has actual knowledge of a patent
+    which the individual believes contains Essential
+    Claim(s) must disclose the information in accordance with
+    section
+    6 of the W3C
+    Patent Policy.
                                
+    
                                This document is governed by the 1 March 2019
+    W3C Process
+    Document.
                                
+  
                                
+  
+  
                                
+    
                                1.
+    Introduction
                                
+    
                                WoT provides layered interoperability based on how Things are used: "consumed" and "exposed", as
+    defined
+    in [WOT-ARCHITECTURE].
                                
+    
                                By consuming a TD, a client Thing creates a local runtime resource model that
+    allows accessing the Properties, Actions and Events exposed by the server Thing on a remote device.
                                
+    
                                
+      
                                Exposing a Thing requires:
                                
+      This specification describes how to expose and consume
+      Things by a script. Also, it defines a generic API
+      for Thing discovery.
+    
                                
+    
                                
+      
                                
+        Note
+      
                                
+      
                                Typically scripts are meant to be used on bridges
+      or gateways that expose and control simpler devices as WoT
+      Things and have means to handle (e.g. install,
+      uninstall, update etc.) and run scripts.
                                
+    
                                
+    
                                
+      
                                
+        Note
+      
                                
+      
                                This specification does not make assumptions on
+      how the WoT Runtime handles and runs
+      scripts, including single or multiple tenancy, script
+      deployment and lifecycle management. The API already supports
+      the generic mechanisms that make it possible to implement
+      script management, for instance by exposing a manager
+      Thing whose Actions (action
+      handlers) implement script lifecycle management
+      operations.
                                
+    
                                
+  
                                
+  
                                
+    
                                2. Use
+    Cases
                                
+    
                                This section is non-normative.
                                
+    
                                The following scripting use cases are supported in this
+    specification:
                                
+    
                                
+      
                                2.1
+      Consuming a Thing
                                
+      
+    
                                
+    
                                
+      
                                2.2
+      Exposing a Thing
                                
+      
                                  
+        
                                • Exposing the Thing includes generating the
+          protocol bindings in order to access lower level
+          functionality.
+        
                                  • 
+        
                                • Create a local Thing to be exposed,
+        based on a Thing Description
+        provided in string serialized format, or out of an existing
+        Thing object.
+        
                                  • 
+        
                                • Add a Property definition to the
+          Thing.
+        
                                  • 
+        
                                • Remove a Property definition from the
+          Thing.
+        
                                  • 
+        
                                • Add an Action definition to the
+          Thing.
+        
                                  • 
+        
                                • Remove an Action definition from the
+          Thing.
+        
                                  • 
+        
                                • Add a WoT Event definition to the Thing.
+        
                                  • 
+        
                                • Remove a WoT Event definition from the
+          Thing.
+        
                                  • 
+        
                                • Emit a WoT Event, i.e. notify all subscribed
+        listeners.
+        
                                  • 
+        
                                • Register service handlers for external requests:
+          
                                    
+            
                                  • to retrieve a Property value;
+            
                                    • 
+            
                                  • to update a Property value;
+            
                                    • 
+            
                                  • to invoke an Action: take the
+            parameters from the request, execute the defined
+            action, and return the result;
+            
                                    • 
+          
                                  
+        
                                  • 
+      
                                
+    
                                
+    
                                
+      
                                2.3
+      Discovery
                                
+      
                                  
+        
                                • Discover Things in a network by sending a
+        broadcast request.
+        
                                  • 
+        
                                • Discover Things running in the local
+        WoT Runtime.
+        
                                  • 
+        
                                • Discover nearby Things, for instance
+        connected by NFC or Bluetooth.
+        
                                  • 
+        
                                • Discover Things by sending a discovery
+        request to a given registry.
+        
                                  • 
+        
                                • Discover Things filtered by filters defined
+        on Thing Descriptions
+        
                                  • 
+        
                                • Discover Things filtered by semantic
+        queries.
+        
                                  • 
+        
                                • Stop or suppress an ongoing discovery process.
                                  • 
+        
                                • Optionally specify a timeout to the discovery process
+        after which it is stopped/suppressed.
                                  • 
+      
                                
+    
                                
+  
                                
+  
                                
+    
                                3.
+    Conformance
                                
+    
                                As well as sections marked as non-normative, all authoring
+    guidelines, diagrams, examples, and notes in this specification
+    are non-normative. Everything else in this specification is
+    normative.
                                
+    
                                The key words MAY, MUST, and SHOULD in
+    this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only
+    when, they appear in all capitals, as shown here.
                                
+    
                                This specification describes the conformance criteria for
+    the following classes of user agent (UA).
                                
+    
                                Due to requirements of small embedded implementations,
+    splitting WoT client and server interfaces was needed. Then,
+    discovery is a distributed application, but typical scenarios
+    have been covered by a generic discovery API in this
+    specification. This resulted in using 3 conformance classes for
+    a UA that implements this API, one for client, one for
+    server, and one for discovery. An application that uses this
+    API can introspect for the presence of the
+    consume(), produce() and
+    discover() methods on the WoT API object in order to determine which
+    conformance class the UA implements.
                                
+    
                                
+      
                                
+        WoT
+        Consumer UA
+      
                                
+      
                                
+        
                                Implementations of this conformance class MUST implement the
+        ConsumedThing
+        interface and the consume() method on the
+        WoT API object.
                                
+      
                                
+      
                                
+        WoT
+        Producer UA
+      
                                
+      
                                
+        
                                Implementations of this conformance class MUST implement ExposedThing interface and
+        the produce() method on the WoT API object.
                                
+      
                                
+      
                                
+        WoT
+        Discovery UA
+      
                                
+      
                                
+        
                                Implementations of this conformance class MUST implement the
+        ThingDiscovery
+        interface and the discover() method on the
+        WoT API object.
                                
+      
                                
+    
                                
+    
                                These conformance classes MAY be implemented in a single UA.
                                
+    
                                This specification can be used for implementing the WoT
+    Scripting API in multiple programming languages. The interface
+    definitions are specified in [WEBIDL].
                                
+    
                                The UA may be implemented in the browser, or in a
+    separate runtime environment, such as Node.js or in small embedded
+    runtimes.
                                
+    
                                Implementations that use ECMAScript executed in a browser to
+    implement the APIs defined in this document MUST implement them in a manner consistent
+    with the ECMAScript Bindings defined in the Web IDL
+    specification [WEBIDL].
                                
+    
                                Implementations that use TypeScript or ECMAScript in a
+    runtime to implement the APIs defined in this document
+    MUST implement them in a
+    manner consistent with the TypeScript Bindings defined in the
+    TypeScript specification [TYPESCRIPT].
                                
+  
                                
+  
                                
+    
                                4. The ThingDescription
+    type
                                
+    
                                typedef object ThingDescription;
                                
-
                                Represents a Thing Description (TD) as
-defined in [WOT-TD]. It is expected to be a parsed JSON
-object that is validated using 
-JSON schema validation.
                                
-
                                
-
                                4.1 Fetching a Thing Description
                                
-
                                Fetching a TD given a URL should be done with an external method,
-such as the Fetch API or a HTTP
-client library, which offer already standardized options on
-specifying fetch details.
                                
-
                                
-
                                Example
-1: Fetching a Thing
-Description
                                
-
                                try {
+    
                                Represents a Thing Description
+    (TD) as defined in [WOT-TD]. It is expected to be a parsed
+    JSON object that is validated using 
+    JSON schema validation.
                                
+    
                                
+      
                                4.1 Fetching a Thing Description
                                
+      
                                Fetching a TD given a URL should be done with
+      an external method, such as the Fetch API or a
+      HTTP client library, which offer already standardized options
+      on specifying fetch details.
                                
+      
                                
+        
                                
+          Example
+          1: Fetching a
+          Thing Description
+        
                                
+        
                                try {
   let res = await fetch('https://tds.mythings.biz/sensor11');
@@ -2001,95 +2272,109 @@ 
                                catch (err) {
   console.log("Fetching TD failed", err.message);
-}
                                
-
                                
-
                                
-
                                4.2 Expanding a Thing Description
                                
-
                                Note that [WOT-TD]
-allows using a shortened Thing Description by the
-means of defaults
-and requiring clients to expand them with default values specified
-in [WOT-TD]
-for the properties that are not explicitly defined in a given
-TD.
                                
-
                                
-
                                To expand a
-TD given td, run the following steps:
                                
-
                                  
-
                                1. For each item in the TD
-default values table from [WOT-TD], if the term is not defined in td, add the
-term definition with the default value specified in
-[WOT-TD].
                                  2. 
-
                                
-
                                
-
                                
-
                                
-
                                4.3 Validating a Thing Description
                                
-
                                The [WOT-TD]
-specification defines how a TD should be validated. Therefore, this
-API expects the ThingDescription objects be
-validated before used as parameters. This specification defines a
-basic TD validation as follows.
                                
-
                                
-
                                To validate a
-TD given td, run the following steps:
                                
-
                                  
-
                                1. If td is not an object, throw
-"TypeError" and terminate these steps.
                                  2. 
-
                                2. If any of the mandatory properties defined in [WOT-TD] for Thing that
-don't have default
-definitions are missing from td, throw
-"TypeError" and terminate these steps.
                                  3. 
-
                                3. If 
-JSON schema validation fails on td, throw
-"TypeError" and terminate these steps.
                                  4. 
-
                                
-
                                
-
                                
-
                                
-
                                
-
                                5. The
-WoT API
-object
                                
-
                                Defines the API entry point exposed as a singleton and contains
-the API methods.
                                
-
                                
-
                                5.1 The
-WOT
-interface
                                
-
                                [SecureContext, 
                                
+      
+    
                                
+    
                                
+      
                                4.2 Expanding a Thing Description
                                
+      
                                Note that [WOT-TD] allows using a shortened Thing Description by the means of 
+      defaults and requiring clients to expand them with
+      default values specified in [WOT-TD] for the properties that are not
+      explicitly defined in a given TD.
                                
+      
                                
+        
                                To expand
+        a TD given td, run the following
+        steps:
                                
+        
                                  
+          
                                1. For each item in the 
+            TD default values table from [WOT-TD], if the term is not defined
+            in td, add the term definition
+            with the default value specified in [WOT-TD].
+          
                                  2. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                4.3 Validating a Thing Description
                                
+      
                                The [WOT-TD] specification defines how a
+      TD should be validated. Therefore, this API expects
+      the ThingDescription
+      objects be validated before used as parameters. This
+      specification defines a basic TD validation as
+      follows.
                                
+      
                                
+        
                                To validate a TD given
+        td, run the following steps:
                                
+        
                                  
+          
                                1. If td is not an object, throw
+          "TypeError" and terminate these steps.
                                  2. 
+          
                                2. If any of the mandatory properties defined in
+          [WOT-TD] for Thing
+          that don't have 
+            default definitions are missing from td,
+            throw "TypeError" and terminate these
+            steps.
+          
                                  3. 
+          
                                3. If 
+            JSON schema validation fails on td,
+            throw "TypeError" and terminate these
+            steps.
+          
                                  4. 
+        
                                
+      
                                
+    
                                
+  
                                
+  
                                
+    
                                5. The
+    WoT API
+    object
                                
+    
                                Defines the API entry point exposed as a singleton and
+    contains the API methods.
                                
+    
                                
+      
                                5.1
+      The WOT interface
                                
+      
                                [SecureContext, Exposed=(5.1 The
 "#dom-wot">WOT {
   // methods defined in UA conformance classes
 };
                                
-
                                
-
                                Note
                                
-
                                Browser implementations should use a namespace object
-such as navigator.wot. Standalone runtimes may expose
-the API object through mechanisms like require() or import.
                                
-
                                
-
                                
-
                                
-
                                5.2 The
-consume()
-method
                                
-
                                partial interface WOT {
+      
                                
+        
                                
+          Note
+        
                                
+        
                                Browser implementations should use a namespace
+        object such as navigator.wot. Standalone
+        runtimes may expose the API object through mechanisms like
+        require()
+        or 
+        import.
                                
+      
                                
+    
                                
+    
                                
+      
                                5.2
+      The consume()
+      method
                                
+      
                                partial interface WOT {
   Promise<5.2 The
 "idl">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:
                                
-
                                  
-
                                1. Return a Promise
-promise and execute the next steps in
-parallel.
                                  2. 
-
                                2. If invoking this method is not allowed for the current
-scripting context for security reasons, reject promise
-with SecurityError and terminate these steps.
                                  3. 
-
                                3. Run the validate a TD steps on td. If
-that throws, reject promise with the error and terminate
-these steps.
                                  4. 
-
                                4. Let thing be a new ConsumedThing object constructed from
-td.
                                  5. 
-
                                5. 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. The details are private to the
-implementations and out of scope of this specification.
                                  6. 
-
                                6. Resolve promise with thing.
                                  7. 
-
                                
-
                                
-
                                
-
                                
-
                                5.3 The
-produce()
-method
                                
-
                                partial interface WOT {
+      
                                
+        
                                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:
                                
+        
                                  
+          
                                1. Return a Promise
+          promise and execute the next steps
+          in
+          parallel.
+          
                                  2. 
+          
                                2. If invoking this method is not allowed for the
+          current scripting context for security reasons, reject
+          promise with SecurityError and
+          terminate these steps.
                                  3. 
+          
                                3. Run the validate a TD
+          steps on td. If that throws, reject
+          promise with the error and terminate these
+          steps.
+          
                                  4. 
+          
                                4. Let thing be a new ConsumedThing
+            object constructed from td.
+          
                                  5. 
+          
                                5. 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. The details
+            are private to the implementations and out of scope of
+            this specification.
+          
                                  6. 
+          
                                6. Resolve promise with
+          thing.
                                  7. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                5.3
+      The produce()
+      method
                                
+      
                                partial interface WOT {
   Promise<5.3 The
 "idl">ThingDescription td);
 };
                                
-
                                
-
                                Belongs to the WoT Producer conformance class. Expects a
-td 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 method MUST run
-the following steps:
                                
-
                                  
-
                                1. Return a Promise
-promise and execute the next steps in
-parallel.
                                  2. 
-
                                2. If invoking this method is not allowed for the current
-scripting context for security reasons, reject promise
-with SecurityError and terminate these steps.
                                  3. 
-
                                3. Let thing be a new ExposedThing object constructed with
-td.
                                  4. 
-
                                4. Resolve promise with thing.
                                  5. 
-
                                
-
                                
-
                                
-
                                
-
                                5.4 The
-discover()
-method
                                
-
                                partial interface WOT {
+      
                                
+        
                                Belongs to the WoT Producer
+        conformance class. Expects a td 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 method MUST run the following steps:
                                
+        
                                  
+          
                                1. Return a Promise
+          promise and execute the next steps
+          in
+          parallel.
+          
                                  2. 
+          
                                2. If invoking this method is not allowed for the
+          current scripting context for security reasons, reject
+          promise
+          with SecurityError and terminate these
+          steps.
+          
                                  3. 
+          
                                3. Let thing be a new ExposedThing object constructed
+          with td.
+          
                                  4. 
+          
                                4. Resolve promise with
+          thing.
                                  5. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                5.4 The discover()
+      method
                                
+      
                                partial interface WOT {
   ThingDiscovery 5.4 The
 "idl">ThingFilter filter = null);
 };
                                
-
                                
-
                                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. The method MUST run the following steps:
                                
-
                                  
-
                                1. If invoking this method is not allowed for the current
-scripting context for security reasons, throw
-SecurityError and terminate these steps.
                                  2. 
-
                                2. Construct a ThingDiscovery object
-discovery with filter.
                                  3. 
-
                                3. Invoke the discovery.start()
-method.
                                  4. 
-
                                4. Return discovery.
                                  5. 
-
                                
-
                                
-
                                Refer to the ThingDiscovery section for
-how discovery should be implemented.
                                
-
                                
-
                                
-
                                
-
                                6.
-The ConsumedThing interface
                                
-
                                Represents a client API to operate a Thing. Belongs to the
-WoT Consumer conformance class.
                                
-
                                [SecureContext, 
+        
                                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. The
+        method MUST run the
+        following steps:
                                
+        
                                  
+          
                                1. If invoking this method is not allowed for the
+          current scripting context for security reasons, throw
+          SecurityError and terminate these
+          steps.
                                  2. 
+          
                                2. Construct a ThingDiscovery object
+          discovery with filter.
+          
                                  3. 
+          
                                3. Invoke the discovery.start() method.
+          
                                  4. 
+          
                                4. Return discovery.
                                  5. 
+        
                                
+      
+      
                                Refer to the ThingDiscovery section for how
+      discovery should be implemented.
                                
+    
                                
+  
                                
+  
                                
+    
                                6. The ConsumedThing
+    interface
                                
+    
                                Represents a client API to operate a Thing. Belongs to
+    the WoT Consumer conformance class.
                                
+    
                                [SecureContext, Exposed=(6.
 "https://heycam.github.io/webidl/#idl-void">void(any data);
                                
-
                                
-
                                6.1 Constructing ConsumedThing
                                
-
                                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:
                                
-
                                  
-
                                1. Run the expand a TD steps on td. If
-that fails, re-throw the error and terminate these steps.
                                  2. 
-
                                2. Let thing be a new ConsumedThing object.
                                  3. 
-
                                3. Let |td| be an internal slot of thing and
-let td be its value.
                                  4. 
-
                                4. Return thing.
                                  5. 
-
                                
-
                                
-
                                
-
                                
-
                                6.2 The 
-getThingDescription() method
                                
-
                                Returns the internal slot |td| of the ConsumedThing object that represents the
-Thing Description of the ConsumedThing. Applications may consult the
-Thing metadata stored in |td| in order to
-introspect its capabilities before interacting with it.
                                
-
                                
-
                                
-
                                6.3 The InteractionOptions
-dictionary
                                
-
                                Holds the interaction options that need to be exposed for
-application scripts according to the Thing Description. In this version of the specification
-only URI template variables are used, represented as parsed JSON
-objects defined in [WOT-TD].
                                
-
                                
-
                                Editor's note
                                
-
                                The support for URI variables comes from the need
-exposed by [WOT-TD]
-to be able to describe existing TDs that use them, but it
-should be possible to write a Thing Description that
-would use Actions for representing the interactions
-that need URI variables and represent the URI variables as
-parameters to the Action and in that case that could be
-encapsulated by the implementations and the options
-parameter could be dismissed from the methods exposed by this
-API.
                                
-
                                
-
                                
-
                                
-
                                6.4 The
-PropertyMap type
                                
-
                                Represents a map of Property names as strings to
-a value that the Property can take. It is used as a
-property bag for interactions that involve multiple Properties at once.
                                
-
                                
-
                                Editor's note
                                
-
                                It could be defined in Web IDL (as well as ThingDescription) as a maplike
-interface from string to any.
                                
-
                                
-
                                
-
                                
-
                                6.5
-The 
-readProperty() method
                                
-
                                
-
                                Reads a Property value. Takes a string argument
-propertyName and and an optional InteractionOptions options
-argument. It returns a Property value represented
-as any type. The method MUST run the following steps:
                                
-
                                  
-
                                1. Return a Promise
-promise and execute the next steps in
-parallel.
                                  2. 
-
                                2. If invoking this method is not allowed for the current
-scripting context for security reasons, reject promise
-with SecurityError and terminate these steps.
                                  3. 
-
                                3. Make a request to the underlying platform (via the Protocol Bindings) to retrieve the value of the Property given by propertyName with optional
-URI templates given in options.uriVariables.
                                  4. 
-
                                4. If the request fails, reject promise with the error
-received from the Protocol Bindings and
-terminate these steps.
                                  5. 
-
                                5. Let value be the result of the request.
                                  6. 
-
                                6. Run the validate Property value
-sub-steps on value:
-
                                    
-
                                  1. Based on the DataSchema
-definition, value MUST be a JSON value and comply to the data schema
-defined for the Property that is found in
-this.getThingDescription().properties[propertyName].
                                    2. 
-
                                  2. If this fails, throw SyntaxError, otherwise return
-value.
                                    3. 
-
                                  
-
                                  7. 
-
                                7. If these above steps failed, reject promise with
-SyntaxError and terminate these steps.
                                  8. 
-
                                8. Otherwise resolve promise with
-value.
                                  9. 
-
                                
-
                                
-
                                
-
                                
-
                                6.6 The 
-readMultipleProperties() method
                                
-
                                
-
                                Reads multiple Property values with one or multiple
-requests. Takes the propertyNames argument as a sequence
-of strings and an optional InteractionOptions options
-argument. It returns an object with keys from
-propertyNames and values returned by this algorithm. The
-method MUST run the following
-steps:
                                
-
                                  
-
                                1. Return a Promise
-promise and execute the next steps in
-parallel.
                                  2. 
-
                                2. If invoking this method is not allowed for the current
-scripting context for security reasons, reject promise
-with SecurityError and terminate these steps.
                                  3. 
-
                                3. Let result be an object and for each string
-name in propertyNames add a property with key
-name and the value null.
                                  4. 
-
                                4. Make a request to the underlying platform (via the Protocol Bindings) to retrieve the Property values given by propertyNames with
-optional URI templates given in
-options.uriVariables.
                                  5. 
-
                                5. If this cannot be done with a single request with the Protocol Bindings of the Thing, then reject
-promise with NotSupportedError and
-terminate these steps.
                                  6. 
-
                                6. Process the reply and update all properties in
-result with the values obtained in the reply.
                                  7. 
-
                                7. If the above step fails at any point, reject promise
-with SyntaxError and terminate these steps.
                                  8. 
-
                                8. Resolve promise with result.
                                  9. 
-
                                
-
                                
-
                                
-
                                
-
                                6.7 The 
-readAllProperties() method
                                
-
                                
-
                                Reads all properties of the Thing with one or multiple
-requests. Takes an optional InteractionOptions options
-argument. It returns an object with keys from Property names and values returned by this algorithm. The
-method MUST run the following
-steps:
                                
-
                                  
-
                                1. Return a Promise
-promise and execute the next steps in
-parallel.
                                  2. 
-
                                2. If invoking this method is not allowed for the current
-scripting context for security reasons, reject promise
-with SecurityError and terminate these steps.
                                  3. 
-
                                3. Let result be an object and for each string
-name in propertyNames add a property with key
-name and the value null.
                                  4. 
-
                                4. Make a request to the underlying platform (via the Protocol Bindings) to retrieve the value of the all the
-Property definitions from the TD with optional URI
-templates given in options.uriVariables.
                                  5. 
-
                                5. If this cannot be done with a single request with the Protocol Bindings of the Thing, then reject
-promise with NotSupportedError and
-terminate these steps.
                                  6. 
-
                                6. If the request fails, reject promise with the error
-received from the Protocol Bindings and
-terminate these steps.
                                  7. 
-
                                7. Process the reply and update all properties in
-result with the values obtained in the reply.
                                  8. 
-
                                8. Resolve promise with result.
                                  9. 
-
                                
-
                                
-
                                
-
                                
-
                                6.8
-The 
-writeProperty() method
                                
-
                                
-
                                Writes a single Property. Takes a string argument
-propertyName, a value argument value and an
-optional InteractionOptions
-options argument. It returns success or failure. The
-method MUST run the following
-steps:
                                
-
                                  
-
                                1. Return a Promise
-promise and execute the next steps in
-parallel.
                                  2. 
-
                                2. If invoking this method is not allowed for the current
-scripting context for security reasons, reject promise
-with SecurityError and terminate these steps.
                                  3. 
-
                                3. Run the validate Property value
-steps on value. If that fails, reject promise
-with SyntaxError and terminate these steps.
                                  4. 
-
                                4. Make a request to the underlying platform (via the Protocol Bindings) to write value to the
-Property given by propertyName with optional
-URI templates given in options.uriVariables.
                                  5. 
-
                                5. If the request fails, reject promise with the error
-received from the Protocol Bindings and
-terminate these steps.
                                  6. 
-
                                6. Otherwise resolve promise.
                                  7. 
-
                                
-
                                
-
                                
-
                                
-
                                6.9 The 
-writeMultipleProperties() method
                                
-
                                
-
                                Writes a multiple Property values with one request. Takes a
-properties argument as an object with keys being
-Property names and values as Property values and an
-optional InteractionOptions
-options argument. It returns success or failure. The
-method MUST run the following
-steps:
                                
-
                                  
-
                                1. Return a Promise
-promise and execute the next steps in
-parallel.
                                  2. 
-
                                2. If invoking this method is not allowed for the current
-scripting context for security reasons, reject promise
-with SecurityError and terminate these steps.
                                  3. 
-
                                3. For each key name on properties, take its
-value as value and run the validate Property value steps on value. If
-that fails in for any name, reject promise
-with SyntaxError and terminate these steps.
                                  4. 
-
                                4. Make a single request to the underlying platform (via the
-Protocol Bindings) to write the each
-Property provided in properties with optional
-URI templates given in options.uriVariables.
                                  5. 
-
                                5. If this cannot be done with a single request with the Protocol Bindings of the Thing, then reject
-promise with NotSupportedError and
-terminate these steps.
                                  6. 
-
                                6. If the request fails, return the error received from the
-Protocol Bindings and terminate these
-steps.
                                  7. 
-
                                7. Otherwise resolve promise.
                                  8. 
-
                                
-
                                
-
                                
-
                                
-
                                6.10 The WotListener callback
                                
-
                                User provided callback that takes any argument and
-is used for observing Property changes and handling Event
-notifications. Since subscribing to these are WoT interactions,
-they are not modelled with software events.
                                
-
                                
-
                                
-
                                6.11 The 
-observeProperty() method
                                
-
                                
-
                                Makes a request for Property value change
-notifications. Takes a string argument propertyName, a
-WotListener callback function
-listener and an optional InteractionOptions options
-argument. It returns success or failure. The method MUST run the following steps:
                                
-
                                  
-
                                1. Return a Promise
-promise and execute the next steps in
-parallel.
                                  2. 
-
                                2. If invoking this method is not allowed for the current
-scripting context for security reasons, reject promise
-with SecurityError and terminate these steps.
                                  3. 
-
                                3. If listener is not a function, reject
-promise with "TypeError" and terminate
-these steps.
                                  4. 
-
                                4. Make a request to the underlying platform (via the Protocol Bindings) to observe Property identified by
-propertyName with optional URI templates given in
-options.uriVariables.
                                  5. 
-
                                5. If the request fails, reject promise with the error
-received from the Protocol Bindings and
-terminate these steps.
                                  6. 
-
                                6. Otherwise resolve promise.
                                  7. 
-
                                7. Whenever the underlying platform receives a notification for
-this subscription with new Property value
-value, run the following sub-steps:
-
                                    
-
                                  • If running the validate Property value
-steps on value fails, terminate these steps.
                                    • 
-
                                  • Invoke listener with value as
-parameter.
                                    • 
-
                                  
-
                                  8. 
-
                                
-
                                
-
                                
-
                                
-
                                6.12 The 
-unobserveProperty() method
                                
-
                                
-
                                Makes a request for unsubscribing from Property value change
-notifications. Takes a string argument propertyName and
-returns success or failure. The method MUST run the following steps:
                                
-
                                  
-
                                1. Return a Promise
-promise and execute the next steps in
-parallel.
                                  2. 
-
                                2. If invoking this method is not allowed for the current
-scripting context for security reasons, reject promise
-with SecurityError and terminate these steps.
                                  3. 
-
                                3. Make a request to the underlying platform (via the Protocol Bindings) to stop observing the Property identified by propertyName.
                                  4. 
-
                                4. If the request fails, reject promise with the error
-received from the Protocol Bindings and
-terminate these steps.
                                  5. 
-
                                5. Otherwise resolve promise.
                                  6. 
-
                                
-
                                
-
                                
-
                                
-
                                6.13 The 
-invokeAction() method
                                
-
                                
-
                                Makes a request for invoking an Action and return the
-result. Takes a string argument actionName, an optional
-argument params of type any and an optional
-InteractionOptions
-options argument. It returns the result of the Action
-or an error. The method MUST
-run the following steps:
                                
-
                                  
-
                                1. Return a Promise
-promise and execute the next steps in
-parallel.
                                  2. 
-
                                2. If invoking this method is not allowed for the current
-scripting context for security reasons, reject promise
-with SecurityError and terminate these steps.
                                  3. 
-
                                3. Make a request to the underlying platform (via the Protocol Bindings) to invoke the Action identified by
-actionName with parameters provided in params
-with optional URI templates given in
-options.uriVariables.
                                  4. 
-
                                4. If the request fails locally or returns an error over the
-network, reject promise with the error received from the
-Protocol Bindings and terminate these
-steps.
                                  5. 
-
                                5. Otherwise let value be the result returned in the
-reply and run the validate Property value
-steps on it. If that fails, reject promise with
-SyntaxError and terminate these steps.
                                  6. 
-
                                6. Reject promise with value.
                                  7. 
-
                                
-
                                
-
                                
-
                                
-
                                6.14 The 
-subscribeEvent() method
                                
-
                                
-
                                Makes a request for subscribing to Event notifications. Takes a
-string argument eventName, a WotListener callback function
-listener and an optional InteractionOptions options
-argument. It returns success or failure. The method MUST run the following steps:
                                
-
                                  
-
                                1. Return a Promise
-promise and execute the next steps in
-parallel.
                                  2. 
-
                                2. If invoking this method is not allowed for the current
-scripting context for security reasons, reject promise
-with SecurityError and terminate these steps.
                                  3. 
-
                                3. If listener is not a function, reject
-promise with "TypeError" and terminate
-these steps.
                                  4. 
-
                                4. Make a request to the underlying platform (via the Protocol Bindings) to subscribe to an Event
-identified by eventNamewith optional URI templates given
-in options.uriVariables.
                                  5. 
-
                                5. If the request fails, reject promise with the error
-received from the Protocol Bindings and
-terminate these steps.
                                  6. 
-
                                6. Otherwise resolve promise.
                                  7. 
-
                                7. Whenever the underlying platform receives a notification for
-this Event subscription, implementations SHOULD invoke listener, giving the
-data provided with the Event as parameter.
                                  8. 
-
                                
-
                                
-
                                
-
                                
-
                                6.15 The 
-unsubscribeEvent() method
                                
-
                                
-
                                Makes a request for unsubscribing from Event notifications.
-Takes a string argument eventName and returns success or
-failure. The method MUST run
-the following steps:
                                
-
                                  
-
                                1. Return a Promise
-promise and execute the next steps in
-parallel.
                                  2. 
-
                                2. If invoking this method is not allowed for the current
-scripting context for security reasons, reject promise
-with SecurityError and terminate these steps.
                                  3. 
-
                                3. Make a request to the underlying platform (via the Protocol Bindings) to unsubscribe from the Event
-identified by eventName.
                                  4. 
-
                                4. If the request fails, reject promise with the error
-received from the Protocol Bindings and
-terminate these steps.
                                  5. 
-
                                5. Otherwise resolve promise.
                                  6. 
-
                                
-
                                
-
                                
-
                                
-
                                6.16
-ConsumedThing Examples
                                
-
                                The next example illustrates how to fetch a TD by URL, create a
-ConsumedThing, read metadata (title), read
-property value, subscribe to property change, subscribe to a WoT
-event, unsubscribe.
                                
-
                                
-
                                Example
-2: Thing Client API
-example
                                
-
                                try {
+    
                                
+      
                                6.1 Constructing
+      ConsumedThing
                                
+      
                                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:
                                
+        
                                  
+          
                                1. Run the expand a TD steps
+          on td. If that fails, re-throw the error and
+          terminate these steps.
+          
                                  2. 
+          
                                2. Let thing be a new ConsumedThing
+            object.
+          
                                  3. 
+          
                                3. Let |td| be an internal slot of
+          thing and let td be its value.
                                  4. 
+          
                                4. Return thing.
                                  5. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                6.2 The 
+      getThingDescription() method
                                
+      
                                Returns the internal slot |td| of the ConsumedThing object that represents
+      the Thing Description of the ConsumedThing. Applications may
+      consult the Thing metadata stored in
+      |td| in order to introspect its capabilities
+      before interacting with it.
                                
+    
                                
+    
                                
+      
                                6.3 The InteractionOptions
+      dictionary
                                
+      
                                Holds the interaction options that need to be exposed for
+      application scripts according to the Thing Description. In this version of the
+      specification only URI template variables are used,
+      represented as parsed
+      JSON objects defined in [WOT-TD].
                                
+      
                                
+        
                                
+          Editor's note
+        
                                
+        
                                The support for URI variables comes from the
+        need exposed by [WOT-TD] to be able to describe existing
+        TDs that use them, but it should be possible to
+        write a Thing Description
+        that would use Actions for representing the
+        interactions that need URI variables and represent the URI
+        variables as parameters to the Action and in
+        that case that could be encapsulated by the implementations
+        and the options parameter could be dismissed
+        from the methods exposed by this API.
                                
+      
                                
+    
                                
+    
                                
+      
                                6.4 The PropertyMap
+      type
                                
+      
                                Represents a map of Property names as
+      strings to a value that the Property can take. It
+      is used as a property bag for interactions that involve
+      multiple Properties at once.
                                
+      
                                
+        
                                
+          Editor's note
+        
                                
+        
                                It could be defined in Web IDL (as well as
+        ThingDescription) as
+        a maplike
+        interface from string to any.
                                
+      
                                
+    
                                
+    
                                
+      
                                6.5 The 
+      readProperty() method
                                
+      
                                
+        
                                Reads a Property value. Takes a string
+        argument propertyName and and an optional
+        InteractionOptions
+        options argument. It returns a Property value represented as any
+        type. The method MUST
+        run the following steps:
                                
+        
                                  
+          
                                1. Return a Promise
+          promise and execute the next steps
+          in
+          parallel.
+          
                                  2. 
+          
                                2. If invoking this method is not allowed for the
+          current scripting context for security reasons, reject
+          promise with SecurityError and
+          terminate these steps.
                                  3. 
+          
                                3. Make a request to the underlying platform (via the
+          Protocol Bindings) to retrieve
+          the value of the Property given by
+          propertyName with optional URI templates given
+          in options.uriVariables.
+          
                                  4. 
+          
                                4. If the request fails, reject promise with
+          the error received from the Protocol Bindings and terminate
+          these steps.
+          
                                  5. 
+          
                                5. Let value be the result of the
+          request.
                                  6. 
+          
                                6. Run the validate Property
+          value sub-steps on value:
+            
                                    
+              
                                  1. Based on the 
+                DataSchema definition, value
+                MUST be a
+                JSON value and comply to the data schema defined
+                for the Property
+                that is found in
+                this.getThingDescription().properties[propertyName].
+              
                                    2. 
+              
                                  2. If this fails, throw SyntaxError,
+              otherwise return value.
                                    3. 
+            
                                  
+          
                                  7. 
+          
                                7. If these above steps failed, reject
+          promise with SyntaxError and
+          terminate these steps.
                                  8. 
+          
                                8. Otherwise resolve promise with
+          value.
                                  9. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                6.6 The 
+      readMultipleProperties() method
                                
+      
                                
+        
                                Reads multiple Property values with
+        one or multiple requests. Takes the
+        propertyNames argument as a sequence of strings
+        and an optional InteractionOptions
+        options argument. It returns an object with keys
+        from propertyNames and values returned by this
+        algorithm. The method MUST run the following steps:
                                
+        
                                  
+          
                                1. Return a Promise
+          promise and execute the next steps
+          in
+          parallel.
+          
                                  2. 
+          
                                2. If invoking this method is not allowed for the
+          current scripting context for security reasons, reject
+          promise with SecurityError and
+          terminate these steps.
                                  3. 
+          
                                3. Let result be an object and for each
+          string name in propertyNames add a
+          property with key name and the value
+          null.
                                  4. 
+          
                                4. Make a request to the underlying platform (via the
+          Protocol Bindings) to retrieve
+          the Property values given by
+          propertyNames with optional URI templates
+          given in options.uriVariables.
+          
                                  5. 
+          
                                5. If this cannot be done with a single request with the
+          Protocol Bindings of the
+            Thing, then reject
+            promise with NotSupportedError
+            and terminate these steps.
+          
                                  6. 
+          
                                6. Process the reply and update all properties in
+          result with the values obtained in the
+          reply.
                                  7. 
+          
                                7. If the above step fails at any point, reject
+          promise with SyntaxError and
+          terminate these steps.
                                  8. 
+          
                                8. Resolve promise with
+          result.
                                  9. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                6.7 The 
+      readAllProperties() method
                                
+      
                                
+        
                                Reads all properties of the Thing with one or
+        multiple requests. Takes an optional InteractionOptions
+        options argument. It returns an object with keys
+        from Property names and values returned
+        by this algorithm. The method MUST run the following steps:
                                
+        
                                  
+          
                                1. Return a Promise
+          promise and execute the next steps
+          in
+          parallel.
+          
                                  2. 
+          
                                2. If invoking this method is not allowed for the
+          current scripting context for security reasons, reject
+          promise with SecurityError and
+          terminate these steps.
                                  3. 
+          
                                3. Let result be an object and for each
+          string name in propertyNames add a
+          property with key name and the value
+          null.
                                  4. 
+          
                                4. Make a request to the underlying platform (via the
+          Protocol Bindings) to retrieve
+          the value of the all the Property
+            definitions from the TD with optional
+            URI templates given in options.uriVariables.
+          
                                  5. 
+          
                                5. If this cannot be done with a single request with the
+          Protocol Bindings of the
+            Thing, then reject
+            promise with NotSupportedError
+            and terminate these steps.
+          
                                  6. 
+          
                                6. If the request fails, reject promise with
+          the error received from the Protocol Bindings and terminate
+          these steps.
+          
                                  7. 
+          
                                7. Process the reply and update all properties in
+          result with the values obtained in the
+          reply.
                                  8. 
+          
                                8. Resolve promise with
+          result.
                                  9. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                6.8 The 
+      writeProperty() method
                                
+      
                                
+        
                                Writes a single Property. Takes a
+        string argument propertyName, a value argument
+        value and an optional InteractionOptions
+        options argument. It returns success or failure.
+        The method MUST run
+        the following steps:
                                
+        
                                  
+          
                                1. Return a Promise
+          promise and execute the next steps
+          in
+          parallel.
+          
                                  2. 
+          
                                2. If invoking this method is not allowed for the
+          current scripting context for security reasons, reject
+          promise with SecurityError and
+          terminate these steps.
                                  3. 
+          
                                3. Run the validate
+            Property value steps on value. If that
+            fails, reject promise
+            with SyntaxError and terminate these
+            steps.
+          
                                  4. 
+          
                                4. Make a request to the underlying platform (via the
+          Protocol Bindings) to write
+          value to the Property
+            given by propertyName with optional URI
+            templates given in options.uriVariables.
+          
                                  5. 
+          
                                5. If the request fails, reject promise with
+          the error received from the Protocol Bindings and terminate
+          these steps.
+          
                                  6. 
+          
                                6. Otherwise resolve promise.
                                  7. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                6.9 The 
+      writeMultipleProperties() method
                                
+      
                                
+        
                                Writes a multiple Property values with
+        one request. Takes a properties argument as an
+        object with keys being Property names and
+        values as Property values and an optional
+        InteractionOptions
+        options argument. It returns success or failure.
+        The method MUST run
+        the following steps:
                                
+        
                                  
+          
                                1. Return a Promise
+          promise and execute the next steps
+          in
+          parallel.
+          
                                  2. 
+          
                                2. If invoking this method is not allowed for the
+          current scripting context for security reasons, reject
+          promise with SecurityError and
+          terminate these steps.
                                  3. 
+          
                                3. For each key name on
+          properties, take its value as value
+          and run the validate
+            Property value steps on value. If that
+            fails in for any name, reject
+            promise
+            with SyntaxError and terminate these
+            steps.
+          
                                  4. 
+          
                                4. Make a single request to the underlying platform (via
+          the Protocol Bindings) to write
+            the each Property provided in
+            properties with optional URI templates given
+            in options.uriVariables.
+          
                                  5. 
+          
                                5. If this cannot be done with a single request with the
+          Protocol Bindings of the
+            Thing, then reject
+            promise with NotSupportedError
+            and terminate these steps.
+          
                                  6. 
+          
                                6. If the request fails, return the error received from
+          the Protocol Bindings and
+            terminate these steps.
+          
                                  7. 
+          
                                7. Otherwise resolve promise.
                                  8. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                6.10 The WotListener
+      callback
                                
+      
                                User provided callback that takes any
+      argument and is used for observing Property changes
+      and handling Event notifications. Since
+      subscribing to these are WoT interactions, they are not
+      modelled with software events.
                                
+    
                                
+    
                                
+      
                                6.11 The 
+      observeProperty() method
                                
+      
                                
+        
                                Makes a request for Property value
+        change notifications. Takes a string argument
+        propertyName, a WotListener callback function
+        listener and an optional InteractionOptions
+        options argument. It returns success or failure.
+        The method MUST run
+        the following steps:
                                
+        
                                  
+          
                                1. Return a Promise
+          promise and execute the next steps
+          in
+          parallel.
+          
                                  2. 
+          
                                2. If invoking this method is not allowed for the
+          current scripting context for security reasons, reject
+          promise with SecurityError and
+          terminate these steps.
                                  3. 
+          
                                3. If listener is not a function, reject
+          promise with "TypeError" and
+          terminate these steps.
                                  4. 
+          
                                4. Make a request to the underlying platform (via the
+          Protocol Bindings) to observe
+          Property identified by
+          propertyName with optional URI templates given
+          in options.uriVariables.
+          
                                  5. 
+          
                                5. If the request fails, reject promise with
+          the error received from the Protocol Bindings and terminate
+          these steps.
+          
                                  6. 
+          
                                6. Otherwise resolve promise.
                                  7. 
+          
                                7. Whenever the underlying platform receives a
+          notification for this subscription with new Property value value, run the
+          following sub-steps:
+            
                                    
+              
                                  • If running the validate Property value
+              steps on value fails, terminate these
+              steps.
+              
                                    • 
+              
                                  • Invoke listener with value
+              as parameter.
                                    • 
+            
                                  
+          
                                  8. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                6.12 The 
+      unobserveProperty() method
                                
+      
                                
+        
                                Makes a request for unsubscribing from Property value change notifications. Takes a
+        string argument propertyName and returns success
+        or failure. The method MUST run the following steps:
                                
+        
                                  
+          
                                1. Return a Promise
+          promise and execute the next steps
+          in
+          parallel.
+          
                                  2. 
+          
                                2. If invoking this method is not allowed for the
+          current scripting context for security reasons, reject
+          promise with SecurityError and
+          terminate these steps.
                                  3. 
+          
                                3. Make a request to the underlying platform (via the
+          Protocol Bindings) to stop
+          observing the Property
+          identified by propertyName.
+          
                                  4. 
+          
                                4. If the request fails, reject promise with
+          the error received from the Protocol Bindings and terminate
+          these steps.
+          
                                  5. 
+          
                                5. Otherwise resolve promise.
                                  6. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                6.13 The 
+      invokeAction() method
                                
+      
                                
+        
                                Makes a request for invoking an Action and
+        return the result. Takes a string argument
+        actionName, an optional argument
+        params of type any and an optional
+        InteractionOptions
+        options argument. It returns the result of the
+        Action or an error. The method MUST run the following
+        steps:
                                
+        
                                  
+          
                                1. Return a Promise
+          promise and execute the next steps
+          in
+          parallel.
+          
                                  2. 
+          
                                2. If invoking this method is not allowed for the
+          current scripting context for security reasons, reject
+          promise with SecurityError and
+          terminate these steps.
                                  3. 
+          
                                3. Make a request to the underlying platform (via the
+          Protocol Bindings) to invoke the
+          Action identified by
+            actionName with parameters provided in
+            params with optional URI templates given in
+            options.uriVariables.
+          
                                  4. 
+          
                                4. If the request fails locally or returns an error over
+          the network, reject promise with the error
+          received from the Protocol
+            Bindings and terminate these steps.
+          
                                  5. 
+          
                                5. Otherwise let value be the result returned
+          in the reply and run the validate Property value steps on
+          it. If that fails, reject promise with 
+            SyntaxError and terminate these steps.
+          
                                  6. 
+          
                                6. Reject promise with value.
                                  7. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                6.14 The 
+      subscribeEvent() method
                                
+      
                                
+        
                                Makes a request for subscribing to Event
+        notifications. Takes a string argument
+        eventName, a WotListener callback function
+        listener and an optional InteractionOptions
+        options argument. It returns success or failure.
+        The method MUST run
+        the following steps:
                                
+        
                                  
+          
                                1. Return a Promise
+          promise and execute the next steps
+          in
+          parallel.
+          
                                  2. 
+          
                                2. If invoking this method is not allowed for the
+          current scripting context for security reasons, reject
+          promise with SecurityError and
+          terminate these steps.
                                  3. 
+          
                                3. If listener is not a function, reject
+          promise with "TypeError" and
+          terminate these steps.
                                  4. 
+          
                                4. Make a request to the underlying platform (via the
+          Protocol Bindings) to subscribe
+          to an Event identified by
+          eventNamewith optional URI templates given in
+          options.uriVariables.
+          
                                  5. 
+          
                                5. If the request fails, reject promise with
+          the error received from the Protocol Bindings and terminate
+          these steps.
+          
                                  6. 
+          
                                6. Otherwise resolve promise.
                                  7. 
+          
                                7. Whenever the underlying platform receives a
+          notification for this Event
+          subscription, implementations SHOULD invoke listener,
+            giving the data provided with the Event as
+            parameter.
+          
                                  8. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                6.15 The 
+      unsubscribeEvent() method
                                
+      
                                
+        
                                Makes a request for unsubscribing from Event notifications. Takes a string argument
+        eventName and returns success or failure. The
+        method MUST run the
+        following steps:
                                
+        
                                  
+          
                                1. Return a Promise
+          promise and execute the next steps
+          in
+          parallel.
+          
                                  2. 
+          
                                2. If invoking this method is not allowed for the
+          current scripting context for security reasons, reject
+          promise with SecurityError and
+          terminate these steps.
                                  3. 
+          
                                3. Make a request to the underlying platform (via the
+          Protocol Bindings) to
+          unsubscribe from the Event identified
+          by eventName.
+          
                                  4. 
+          
                                4. If the request fails, reject promise with
+          the error received from the Protocol Bindings and terminate
+          these steps.
+          
                                  5. 
+          
                                5. Otherwise resolve promise.
                                  6. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                6.16 ConsumedThing Examples
                                
+      
                                The next example illustrates how to fetch a TD by
+      URL, create a ConsumedThing, read metadata (title),
+      read property value, subscribe to property change, subscribe
+      to a WoT event, unsubscribe.
                                
+      
                                
+        
                                
+          Example
+          2: Thing
+          Client API example
+        
                                
+        
                                try {
   let res = await fetch("https://tds.mythings.org/sensor11");
@@ -3256,31 +3711,32 @@ 
                                6.16
   console.log("Unsubscribed from the ‘ready’ event.");
 },
-10000);
                                
-
                                
-
                                
-
                                
-
                                7.
-The ExposedThing interface
                                
-
                                The ExposedThing interface is the
-server API to operate the Thing that allows defining request
-handlers, Property, Action, and Event
-interactions.
                                
-
                                [SecureContext, 10000);
                                
+      
+    
                                
+  
                                
+  
                                
+    
                                7. The ExposedThing
+    interface
                                
+    
                                The ExposedThing interface is
+    the server API to operate the Thing that allows
+    defining request handlers, Property, Action, and Event interactions.
                                
+    
                                [SecureContext, Exposed=(7.
 href="#dom-interactionoptions" class="internalDFN" data-link-type=
 "idl">InteractionOptions options = null);
                                
-
                                
-
                                7.1 Constructing ExposedThing
                                
-
                                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
-ThingDescription td, run the
-following steps:
                                
-
                                  
-
                                1. If invoking this method is not allowed for the current
-scripting context for security reasons, throw
-SecurityError and terminate these steps.
                                  2. 
-
                                2. Run the expand a TD steps on td. If
-that fails, re-throw the error and terminate these steps.
                                  3. 
-
                                3. Let thing be a new ExposedThing object.
                                  4. 
-
                                4. Let |td| be an internal slot of thing and
-let td be its value.
                                  5. 
-
                                5. Return thing.
                                  6. 
-
                                
-
                                
-
                                
-
                                
-
                                7.2 Methods inherited from ConsumedThing
                                
-
                                The readProperty(),
-readMultipleProperties(),
-readAllProperties(), writeProperty(),
-writeMultipleProperties(),
-writeAllProperties() methods have the same algorithmic
-steps as described in ConsumedThing, with
-the difference that making a request to the underlying platform
-MAY be implemented with local
-methods or libraries and don't necessarily need to involve network
-operations.
                                
-
                                The implementation of ConsumedThing
-interface in an ExposedThing provide the
-default methods to interact with the ExposedThing.
                                
-
                                After constructing an ExposedThing, a
-script can initialize its Properties and can set up
-the optional read, write and action request handlers (the default
-ones are provided by the implementation). The script provided
-handlers MAY use the default
-handlers, thereby extending the default behavior, but they can also
-bypass them, overriding the default behavior. Finally, the script
-would call expose()
-on the ExposedThing in order to
-start serving external requests.
                                
-
                                
-
                                
-
                                7.3 The PropertyReadHandler
-callback
                                
-
                                A function that is called when an external request for reading a
-Property is received and defines what to do with such
-requests. It returns a Promise
-and resolves it when the value of the Property matching the
-name argument is obtained, or rejects with an error if
-the property is not found or the value cannot be retrieved.
                                
-
                                
-
                                
-
                                7.4 The 
-setPropertyReadHandler() method
                                
-
                                Takes name as string argument and
-readHandler as argument of type PropertyReadHandler. Sets the service
-handler for reading the specified Property matched by
-name. Throws on error. Returns a reference to
-this object for supporting chaining.
                                
-
                                The readHandler callback function should implement
-reading a Property and SHOULD be called by implementations when a request
-for reading a Property is received from the underlying
-platform.
                                
-
                                There MUST be at most one
-handler for any given Property, so newly added handlers
-MUST replace the previous
-handlers. If no handler is initialized for any given Property, implementations SHOULD implement a default property read handler
-based on the Thing Description.
                                
-
                                
-
                                
-
                                7.5 Handling Property read
-requests
                                
-
                                
-
                                When a network request for reading Property
-propertyName is received by the implementation, run the
-following steps:
                                
-
                                  
-
                                1. If a Property with propertyName does
-not exist, return ReferenceError in the reply and
-terminate these steps.
                                  2. 
-
                                2. If there is a user provided read handler registered with
-setPropertyReadHandler(), invoke that wih
-propertyName, return the value with the reply and
-terminate these steps.
                                  3. 
-
                                3. Otherwise, if there is a default read handler provided by the
-implementation, invoke it with propertyName, return the
-value with the reply and terminate these steps.
                                  4. 
-
                                4. if there is no default handler defined by the implementation,
-return NotSupportedError
-with the reply and terminate these steps.
                                  5. 
-
                                
-
                                
-
                                
-
                                
-
                                7.6 Handling Property observe
-requests
                                
-
                                
-
                                When a network request for observing a Property
-propertyName is received by the implementation, run the
-following steps:
                                
-
                                  
-
                                1. If a Property with propertyName does
-not exist, return an error in the reply (as defined in the Thing Description) and terminate these steps.
                                  2. 
-
                                2. Save the request sender information to the Property's internal observer list in
-order to be able to notify about Property value changes.
                                  3. 
-
                                
-
                                
-
                                
-
                                
-
                                7.7 The PropertyWriteHandler
-callback
                                
-
                                A function that is called when an external request for writing a
-Property is received and defines what to do with such
-requests. It expects the requested new value as
-argument and returns a Promise
-which is resolved when the value of the Property that matches
-the name argument has been updated with
-value, or rejects with an error if the property is not
-found or the value cannot be updated.
                                
-
                                
-
                                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.
                                
-
                                
-
                                
-
                                
-
                                7.8 The 
-setPropertyWriteHandler() method
                                
-
                                Takes name as string argument and
-writeHandler as argument of type PropertyWriteHandler. Sets the service
-handler for writing the specified Property matched by
-name. Throws on error. Returns a reference to
-this object for supporting chaining.
                                
-
                                There MUST be at most one
-write handler for any given Property, so newly added
-handlers MUST replace the
-previous handlers. If no write handler is initialized for any given
-Property, implementations SHOULD implement default property update and
-notifying observers on change, based on the Thing Description.
                                
-
                                
-
                                
-
                                7.9 Handling Property write
-requests
                                
-
                                
-
                                When a network request for writing a Property
-propertyName with a new value value is
-received, implementations SHOULD run the following update property steps, given
-propertyName, value and mode set
-to "single":
                                
-
                                  
-
                                1. If a Property with propertyName does
-not exist, return ReferenceError in the reply and
-terminate these steps.
                                  2. 
-
                                2. If there is a user provided write handler registered with
-setPropertyWriteHandler(), or if there is a default
-write handler,
-
                                    
-
                                  1. Invoke the handler with propertyName. If it fails,
-return the error in the reply and terminate these steps.
                                    2. 
-
                                  2. Otherwise, if mode is "single", reply
-to the request with the new value, following to the Protocol Bindings.
                                    3. 
-
                                  3. For each item stored in the internal observer list of the Property with
-propertyName, send an observe reply with the new value
-attached.
                                    4. 
-
                                  
-
                                  3. 
-
                                3. If there is no handler to handle the request, return
-NotSupportedError
-in the reply and terminate these steps.
                                  4. 
-
                                
-
                                
-
                                
-
                                When a network request for writing multiple Properties given in an object propertyNames is
-received, run the following steps:
                                
-
                                  
-
                                1. For each property with key name and value
-value defined in propertyNames, run the
-update property steps with
-name, value and mode set to
-"multiple".
                                  2. 
-
                                2. Reply to the request (by sending a single or multiple replies)
-according to the Protocol Bindings defined
-for the Property.
                                  3. 
-
                                
-
                                
-
                                
-
                                
-
                                7.10 The ActionHandler callback
                                
-
                                A function that is called when an external request for invoking
-an Action is received and defines what to do with such
-requests. It is invoked with a params dictionary
-argument. It returns a Promise
-that rejects with an error or resolves if the action is
-successful.
                                
-
                                
-
                                
-
                                7.11 The 
-setActionHandler() method
                                
-
                                Takes name as string argument and
-action as argument of type ActionHandler. Sets the handler function for
-the specified Action matched by name.
-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.
                                
-
                                
-
                                
-
                                7.12 Handling Action requests
                                
-
                                
-
                                When a network request for invoking the Action identified by
-name is received, the runtime SHOULD execute the following steps:
                                
-
                                  
-
                                1. If an Action identified by name does
-not exist, return ReferenceError in the reply and
-terminate these steps.
                                  2. 
-
                                2. If there is a user provided action handler registered with
-setActionHandler(), invoke that wih name,
-return the resulting value with the reply and terminate these
-steps.
                                  3. 
-
                                3. Otherwise return NotSupportedError
-with the reply and terminate these steps.
                                  4. 
-
                                
-
                                
-
                                
-
                                
-
                                7.13
-The 
-emitEvent() method
                                
-
                                
-
                                Takes name as string argument denoting an Event
-name, and a data argument of any type. The
-method MUST run the following
-steps:
                                
-
                                  
-
                                1. If invoking this method is not allowed for the current
-scripting context for security reasons, throw
-SecurityError and terminate these steps.
                                  2. 
-
                                2. If an Event with the name name is not found in
-this.getThingDescription().events, throw
-NotFoundError and terminate these steps.
                                  3. 
-
                                3. Make a request to the underlying platform to send an Event
-with data attached as property, using the Protocol Bindings, then terminate these steps.
                                  4. 
-
                                
-
                                
-
                                
-
                                
-
                                7.14 The
-expose()
-method
                                
-
                                
-
                                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:
                                
-
                                  
-
                                1. Return a Promise
-promise and execute the next steps in
-parallel.
                                  2. 
-
                                2. If invoking this method is not allowed for the current
-scripting context for security reasons, reject promise
-with SecurityError and terminate these steps.
                                  3. 
-
                                3. Run the expand a TD steps on the internal slot
-|td|.
                                  4. 
-
                                4. Run the validate a TD on |td|. If that
-fails, reject promise with "TypeError" and
-terminate these steps.
                                  5. 
-
                                5. For each Property definition in
-this.instance.properties initialize an
-|internal
-observer list| internal slot in order to store observe
-request data needed to notify the observers on value changes.
                                  6. 
-
                                6. 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. The
-details are private to the implementations and out of scope of this
-specification.
                                  7. 
-
                                7. 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
-terminate these steps.
                                  8. 
-
                                8. Otherwise resolve promise and terminate these
-steps.
                                  9. 
-
                                
-
                                
-
                                
-
                                
-
                                7.15 The
-
-destroy() method
                                
-
                                
-
                                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:
                                
-
                                  
-
                                1. Return a Promise
-promise and execute the next steps in
-parallel.
                                  2. 
-
                                2. If invoking this method is not allowed for the current
-scripting context for security reasons, reject promise
-with SecurityError and terminate these steps.
                                  3. 
-
                                3. Make a request to the underlying platform to stop serving
-external requests for WoT Interactions, based on
-the Protocol Bindings.
                                  4. 
-
                                4. 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
-terminate these steps.
                                  5. 
-
                                5. Otherwise resolve promise and terminate these
-steps.
                                  6. 
-
                                
-
                                
-
                                
-
                                
-
                                7.16
-ExposedThing Examples
                                
-
                                The next example illustrates how to create an ExposedThing based on a partial
-TD
-object constructed beforehands.
                                
-
                                
-
                                Example
-3: Create ExposedThing
-with a simple Property
                                
-
                                try {
+    
                                
+      
                                7.1 Constructing
+      ExposedThing
                                
+      
                                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 ThingDescription td, run
+        the following steps:
                                
+        
                                  
+          
                                1. If invoking this method is not allowed for the
+          current scripting context for security reasons, throw
+          SecurityError and terminate these
+          steps.
                                  2. 
+          
                                2. Run the expand a TD steps
+          on td. If that fails, re-throw the error and
+          terminate these steps.
+          
                                  3. 
+          
                                3. Let thing be a new ExposedThing object.
+          
                                  4. 
+          
                                4. Let |td| be an internal slot of
+          thing and let td be its value.
                                  5. 
+          
                                5. Return thing.
                                  6. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                
+      7.2 Methods inherited from ConsumedThing
                                
+      
                                The readProperty(),
+      readMultipleProperties(),
+      readAllProperties(),
+      writeProperty(),
+      writeMultipleProperties(),
+      writeAllProperties() methods have the same
+      algorithmic steps as described in ConsumedThing,
+      with the difference that making a request to the underlying
+      platform MAY be
+      implemented with local methods or libraries and don't
+      necessarily need to involve network operations.
                                
+      
                                The implementation of ConsumedThing interface in an ExposedThing provide the
+      default methods to interact with the ExposedThing.
                                
+      
                                After constructing an ExposedThing, a script can initialize
+      its Properties and can set up the
+      optional read, write and action request handlers (the default
+      ones are provided by the implementation). The script provided
+      handlers MAY use the
+      default handlers, thereby extending the default behavior, but
+      they can also bypass them, overriding the default behavior.
+      Finally, the script would call expose() on the
+      ExposedThing in order
+      to start serving external requests.
                                
+    
                                
+    
                                
+      
                                7.3 The PropertyReadHandler
+      callback
                                
+      
                                A function that is called when an external request for
+      reading a Property is received and defines
+      what to do with such requests. It returns a
+      Promise
+      and resolves it when the value of the Property matching the name argument is
+      obtained, or rejects with an error if the property is not
+      found or the value cannot be retrieved.
                                
+    
                                
+    
                                
+      
                                7.4 The 
+      setPropertyReadHandler() method
                                
+      
                                Takes name as string argument and
+      readHandler as argument of type PropertyReadHandler.
+      Sets the service handler for reading the specified Property matched by name. Throws on
+      error. Returns a reference to this object for
+      supporting chaining.
                                
+      
                                The readHandler callback function should
+      implement reading a Property and
+      SHOULD be called by
+      implementations when a request for reading a Property is received from the underlying
+      platform.
                                
+      
                                There MUST be at
+      most one handler for any given Property, so
+      newly added handlers MUST replace the previous handlers. If no handler
+      is initialized for any given Property,
+      implementations SHOULD implement a default property read
+      handler based on the Thing Description.
                                
+    
                                
+    
                                
+      
                                7.5 Handling Property read
+      requests
                                
+      
                                
+        
                                When a network request for reading Property propertyName is received by
+        the implementation, run the following steps:
                                
+        
                                  
+          
                                1. If a Property with
+          propertyName does not exist, return
+          ReferenceError in the reply and terminate
+          these steps.
+          
                                  2. 
+          
                                2. If there is a user provided read handler registered
+          with setPropertyReadHandler(), invoke that
+          wih propertyName, return the value with the
+          reply and terminate these steps.
                                  3. 
+          
                                3. Otherwise, if there is a default read handler
+          provided by the implementation, invoke it with
+          propertyName, return the value with the reply
+          and terminate these steps.
                                  4. 
+          
                                4. if there is no default handler defined by the
+          implementation, return 
+            NotSupportedError with the reply and
+            terminate these steps.
+          
                                  5. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                7.6 Handling Property observe
+      requests
                                
+      
                                
+        
                                When a network request for observing a Property propertyName is received by
+        the implementation, run the following steps:
                                
+        
                                  
+          
                                1. If a Property with
+          propertyName does not exist, return an error
+          in the reply (as defined in the Thing Description) and terminate
+          these steps.
+          
                                  2. 
+          
                                2. Save the request sender information to the Property's internal observer list in order
+          to be able to notify about Property
+          value changes.
+          
                                  3. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                7.7 The PropertyWriteHandler
+      callback
                                
+      
                                A function that is called when an external request for
+      writing a Property is received and defines
+      what to do with such requests. It expects the requested new
+      value as argument and returns a
+      Promise
+      which is resolved when the value of the Property that matches the name
+      argument has been updated with value, or rejects
+      with an error if the property is not found or the value
+      cannot be updated.
                                
+      
                                
+        
                                
+          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.
                                
+      
                                
+    
                                
+    
                                
+      
                                7.8 The 
+      setPropertyWriteHandler() method
                                
+      
                                Takes name as string argument and
+      writeHandler as argument of type PropertyWriteHandler.
+      Sets the service handler for writing the specified Property matched by name. Throws on
+      error. Returns a reference to this object for
+      supporting chaining.
                                
+      
                                There MUST be at
+      most one write handler for any given Property, so newly added handlers MUST replace the previous
+      handlers. If no write handler is initialized for any given
+      Property, implementations SHOULD implement default property update
+      and notifying observers on change, based on the Thing Description.
                                
+    
                                
+    
                                
+      
                                7.9 Handling Property write
+      requests
                                
+      
                                
+        
                                When a network request for writing a Property propertyName with a new value
+        value is received, implementations SHOULD run the following
+        update property steps,
+        given propertyName, value and
+        mode set to "single":
                                
+        
                                  
+          
                                1. If a Property with
+          propertyName does not exist, return
+          ReferenceError in the reply and terminate
+          these steps.
+          
                                  2. 
+          
                                2. If there is a user provided write handler registered
+          with setPropertyWriteHandler(), or if there
+          is a default write handler,
+            
                                    
+              
                                  1. Invoke the handler with propertyName.
+              If it fails, return the error in the reply and
+              terminate these steps.
                                    2. 
+              
                                  2. Otherwise, if mode is
+              "single", reply to the request with the
+              new value, following to the Protocol Bindings.
+              
                                    3. 
+              
                                  3. For each item stored in the internal observer list of
+              the Property with
+              propertyName, send an observe reply with
+              the new value attached.
+              
                                    4. 
+            
                                  
+          
                                  3. 
+          
                                3. If there is no handler to handle the request, return
+          
+            NotSupportedError in the reply and terminate
+            these steps.
+          
                                  4. 
+        
                                
+      
                                
+      
                                
+        
                                When a network request for writing multiple Properties given in an object
+        propertyNames is received, run the following
+        steps:
                                
+        
                                  
+          
                                1. For each property with key name and value
+          value defined in propertyNames, run
+          the update property
+          steps with name, value and
+          mode set to "multiple".
+          
                                  2. 
+          
                                2. Reply to the request (by sending a single or multiple
+          replies) according to the Protocol Bindings defined for
+          the Property.
+          
                                  3. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                7.10 The ActionHandler
+      callback
                                
+      
                                A function that is called when an external request for
+      invoking an Action is received and defines what
+      to do with such requests. It is invoked with a
+      params dictionary argument. It returns a
+      Promise
+      that rejects with an error or resolves if the action is
+      successful.
                                
+    
                                
+    
                                
+      
                                7.11 The 
+      setActionHandler() method
                                
+      
                                Takes name as string argument and
+      action as argument of type ActionHandler. Sets the handler
+      function for the specified Action matched by
+      name. 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.
                                
+    
                                
+    
                                
+      
                                7.12 Handling Action
+      requests
                                
+      
                                
+        
                                When a network request for invoking the Action identified by name is received,
+        the runtime SHOULD
+        execute the following steps:
                                
+        
                                  
+          
                                1. If an Action identified by
+          name does not exist, return
+          ReferenceError in the reply and terminate
+          these steps.
+          
                                  2. 
+          
                                2. If there is a user provided action handler registered
+          with setActionHandler(), invoke that wih
+          name, return the resulting value with the
+          reply and terminate these steps.
                                  3. 
+          
                                3. Otherwise return 
+            NotSupportedError with the reply and
+            terminate these steps.
+          
                                  4. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                7.13 The 
+      emitEvent() method
                                
+      
                                
+        
                                Takes name as string argument denoting an
+        Event name, and a data argument of
+        any type. The method MUST run the following steps:
                                
+        
                                  
+          
                                1. If invoking this method is not allowed for the
+          current scripting context for security reasons, throw
+          SecurityError and terminate these
+          steps.
                                  2. 
+          
                                2. If an Event with the name
+          name is not found in
+          this.getThingDescription().events, throw
+          NotFoundError and terminate these steps.
+          
                                  3. 
+          
                                3. Make a request to the underlying platform to send an
+          Event with data
+            attached as property, using the Protocol Bindings, then
+            terminate these steps.
+          
                                  4. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                7.14 The 
+      expose() method
                                
+      
                                
+        
                                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:
                                
+        
                                  
+          
                                1. Return a Promise
+          promise and execute the next steps
+          in
+          parallel.
+          
                                  2. 
+          
                                2. If invoking this method is not allowed for the
+          current scripting context for security reasons, reject
+          promise with SecurityError and
+          terminate these steps.
                                  3. 
+          
                                3. Run the expand a TD steps
+          on the internal slot |td|.
+          
                                  4. 
+          
                                4. Run the validate a TD on
+          |td|. If that fails, reject promise
+          with "TypeError" and terminate these steps.
+          
                                  5. 
+          
                                5. For each Property
+          definition in this.instance.properties
+          initialize an |internal observer
+          list| internal slot in order to store observe
+          request data needed to notify the observers on value
+          changes.
+          
                                  6. 
+          
                                6. 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. The details
+            are private to the implementations and out of scope of
+            this specification.
+          
                                  7. 
+          
                                7. 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 terminate
+          these steps.
+          
                                  8. 
+          
                                8. Otherwise resolve promise and terminate
+          these steps.
                                  9. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                7.15 The 
+      destroy() method
                                
+      
                                
+        
                                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:
                                
+        
                                  
+          
                                1. Return a Promise
+          promise and execute the next steps
+          in
+          parallel.
+          
                                  2. 
+          
                                2. If invoking this method is not allowed for the
+          current scripting context for security reasons, reject
+          promise with SecurityError and
+          terminate these steps.
                                  3. 
+          
                                3. Make a request to the underlying platform to stop
+          serving external requests for WoT Interactions, based on the
+          Protocol Bindings.
+          
                                  4. 
+          
                                4. 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 terminate
+          these steps.
+          
                                  5. 
+          
                                5. Otherwise resolve promise and terminate
+          these steps.
                                  6. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                7.16 ExposedThing Examples
                                
+      
                                The next example illustrates how to create an
+      ExposedThing
+      based on a partial TD object constructed
+      beforehands.
                                
+      
                                
+        
                                
+          Example
+          3: Create
+          ExposedThing with a simple Property
+        
                                
+        
                                try {
   let temperaturePropertyDefinition = {
     type: 7.16
 } 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
-4: Add an object
-Property
                                
-
                                try {
+}
                                
+      
                                
+      
                                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
+          4: Add an
+          object Property
+        
                                
+        
                                try {
   // create a deep copy of thing1's TD
   let instance = 7.16
 } catch (err) {
    console.log("Error creating ExposedThing: " + err);
-}
                                
-
                                
-
                                
-
                                
-
                                8. The ThingDiscovery
-interface
                                
-
                                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 ThingDiscovery object is
-constructed given a filter and provides the properties and methods
-controlling the discovery process.
                                
-
                                [SecureContext, 
                                
+      
+    
                                
+  
                                
+  
                                
+    
                                8. The ThingDiscovery
+    interface
                                
+    
                                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 ThingDiscovery object is
+    constructed given a filter and provides the properties and
+    methods controlling the discovery process.
                                
+    
                                [SecureContext, Exposed=(stop();
 };
                                
-
                                
-
                                Editor's note
                                
-
                                The ThingDiscovery interface has
-a next() method and a done property, but
-it is not an Iterable. Look into Issue 177
-for rationale.
                                
-
                                
-
                                The discovery results internal slot is an
-internal queue for temporarily storing the found ThingDescription objects until they are
-consumed by the application using the next() method. Implementations MAY optimize the size of this queue
-based on e.g. the available resources and the frequency of invoking
-the next() method.
                                
-
                                The filter
-property represents the discovery filter of type ThingFilter specified for the discovery.
                                
-
                                The active property
-is true when the discovery is actively ongoing on
-protocol level (i.e. new TDs may still arrive) and
-false otherwise.
                                
-
                                The done property is
-true if the discovery has been completed with no more
-results to report and discovery results is also
-empty.
                                
-
                                The error property
-represents the last error that occured during the discovery
-process. Typically used for critical errors that stop
-discovery.
                                
-
                                
-
                                8.1 Constructing ThingDiscovery
                                
-
                                
-
                                To create ThingDiscovery with the
-ThingFilter filter, run the
-following steps:
                                
-
                                  
-
                                1. If filter is not an object or null,
-throw "TypeError" and terminate these steps.
                                  2. 
-
                                2. Let discovery be a new ThingDiscovery object.
                                  3. 
-
                                3. Set the filter
-property to filter.
                                  4. 
-
                                4. Set active and
-done to false.
-Set error to
-null.
                                  5. 
-
                                5. Return discovery.
                                  6. 
-
                                
-
                                
-
                                The start() method sets active to true. The
-stop() method sets active to false, but
-done may be still
-false if there are ThingDescription objects in the discovery results not yet consumed with next().
                                
-
                                During successive calls of next(),
-active may be
-true or false, but done is set to false by
-next() only when both active is false and
-discovery results is empty.
                                
-
                                
-
                                
-
                                8.2 The DiscoveryMethod
-enumeration
                                
-
                                typedef DOMString 
+      
                                
+        Editor's note
+      
                                
+      
                                The ThingDiscovery interface has a
+      next() method and a done property,
+      but it is not an Iterable. Look into Issue
+      177 for rationale.
                                
+    
+    
                                The discovery results internal slot
+    is an internal queue for temporarily storing the found ThingDescription objects until they are
+    consumed by the application using the next() method. Implementations MAY optimize the size of this queue
+    based on e.g. the available resources and the frequency of
+    invoking the next() method.
                                
+    
                                The filter
+    property represents the discovery filter of type ThingFilter specified for the
+    discovery.
                                
+    
                                The active
+    property is true when the discovery is actively
+    ongoing on protocol level (i.e. new TDs may still arrive)
+    and false otherwise.
                                
+    
                                The done
+    property is true if the discovery has been
+    completed with no more results to report and discovery results is also empty.
                                
+    
                                The error
+    property represents the last error that occured during the
+    discovery process. Typically used for critical errors that stop
+    discovery.
                                
+    
                                
+      
                                8.1 Constructing
+      ThingDiscovery
                                
+      
                                
+        
                                To create ThingDiscovery with the ThingFilter filter, run
+        the following steps:
                                
+        
                                  
+          
                                1. If filter is not an object or
+          null, throw "TypeError" and
+          terminate these steps.
                                  2. 
+          
                                2. Let discovery be a new ThingDiscovery
+            object.
+          
                                  3. 
+          
                                3. Set the filter property to 
+            filter.
+          
                                  4. 
+          
                                4. Set active
+          and done to 
+            false. Set error to
+            null.
+          
                                  5. 
+          
                                5. Return discovery.
                                  6. 
+        
                                
+      
                                
+      
                                The start() method sets
+      active to
+      true. The stop()
+      method sets active
+      to false, but done may be still
+      false if there are ThingDescription objects in the
+      discovery results not yet consumed
+      with next().
                                
+      
                                During successive calls of next(), active may be
+      true or false, but done is set to
+      false by next()
+      only when both active is false
+      and discovery results is empty.
                                
+    
                                
+    
                                
+      
                                8.2 The DiscoveryMethod
+      enumeration
                                
+      
                                typedef DOMString DiscoveryMethod;
                                
-
                                Represents the discovery type to be used:
                                
-
                                  
-
                                • "any" does not
-provide any restriction
                                  • 
-
                                • "local" for
-discovering Things defined in the same device or
-connected to the device by wired or wireless means.
                                  • 
-
                                • "directory"
-for discovery based on a service provided by a Thing Directory.
                                  • 
-
                                • "multicast"
-for discovering Things in the device's network by using a
-supported multicast protocol.
                                  • 
-
                                
-
                                
-
                                
-
                                8.3 The ThingFilter dictionary
                                
-
                                Represents an object containing the constraints for discovering
-Things as key-value pairs.
                                
-
                                dictionary ThingFilter {
+      
                                Represents the discovery type to be used:
                                
+      
                                  
+        
                                • "any" does
+        not provide any restriction
                                  • 
+        
                                • 
+          "local" for
+          discovering Things defined in the same
+          device or connected to the device by wired or wireless
+          means.
+        
                                  • 
+        
                                • 
+          "directory" for discovery based on
+          a service provided by a Thing
+          Directory.
+        
                                  • 
+        
                                • 
+          "multicast" for discovering
+          Things in the device's network by using a
+          supported multicast protocol.
+        
                                  • 
+      
                                
+    
                                
+    
                                
+      
                                8.3 The ThingFilter
+      dictionary
                                
+      
                                Represents an object containing the constraints for
+      discovering Things as key-value pairs.
                                
+      
                                dictionary ThingFilter {
   (DiscoveryMethod or fragment;
 };
                                
-
                                The method property
-represents the discovery type that should be used in the discovery
-process. The possible values are defined by the DiscoveryMethod enumeration that
-MAY be extended by string
-values defined by solutions (with no guarantee of
-interoperability).
                                
-
                                The url property represents additional
-information for the discovery method, such as the URL of the target
-entity serving the discovery request, for instance the URL of a
-Thing Directory (if method is
-"directory") or that of a Thing (otherwise).
                                
-
                                The query property represents a query
-string accepted by the implementation, for instance a SPARQL or
-JSON query. Support may be implemented locally in the WoT
-Runtime or remotely as a service in a Thing Directory.
                                
-
                                The fragment property represents a template
-object used for matching property by property against discovered
-Things.
                                
-
                                
-
                                
-
                                8.4 The
-start()
-method
                                
-
                                
-
                                Starts the discovery process. The method MUST run the following steps:
                                
-
                                  
-
                                1. If invoking this method is not allowed for the current
-scripting context for security reasons, set this.error
-to SecurityError and terminate these steps.
                                  2. 
-
                                2. If discovery is not supported by the implementation, set
-this.error to NotSupportedError and
-terminate these steps.
                                  3. 
-
                                3. If this.filter is defined,
-
                                    
-
                                  • Let filter denote this.filter.
                                    • 
-
                                  • If filter.query is defined, pass it as an opaque
-string to the underlying implementation to be matched against
-discovered items. The underlying implementation is responsible to
-parse it e.g. as a SPARQL or JSON query and match it against the
-Thing Descriptions found during the
-discovery process. If queries are not supported, set
-this.error to NotSupportedError and
-terminate these steps.
                                    • 
-
                                  
-
                                  4. 
-
                                4. Create the discovery results internal slot for
-storing discovered ThingDescription objects.
                                  5. 
-
                                5. Request the underlying platform to start the discovery process,
-with the following parameters:
-
                                    
-
                                  • If filter.method is not defined or the value is
-"any", use the widest discovery method supported by
-the underlying platform.
                                    • 
-
                                  • Otherwise if filter.method is "local",
-use the local Thing Directory for discovery. Usually
-that defines Things deployed in the same device, or
-connected to the device in slave mode (e.g. sensors connected via
-Bluetooth or a serial connection).
                                    • 
-
                                  • Otherwise if filter.method is
-"directory", use the remote Thing Directory specified in filter.url.
                                    • 
-
                                  • Otherwise if filter.method is
-"multicast", use all the multicast discovery protocols
-supported by the underlying platform.
                                    • 
-
                                  
-
                                  6. 
-
                                6. When the underlying platform has started the discovery process,
-set the active property to true.
                                  7. 
-
                                7. Whenever a new Thing Description
-td is discovered by the underlying platform, run the
-following sub-steps:
-
                                    
-
                                  1. Fetch
-td as a JSON object json. If that fails, set
-this.error to SyntaxError, discard
-td and continue the discovery process.
                                    2. 
-
                                  2. If filter.query is defined, check if json
-is a match for the query. The matching algorithm is encapsulated by
-implementations. If that returns false, discard
-td and continue the discovery process.
                                    3. 
-
                                  3. If filter.fragment is defined, for each property
-defined in it, check if that property exists in
-json.properties and has the same value. If this is
-false in any checks, discard td and
-continue the discovery process.
                                    4. 
-
                                  4. Otherwise add td to the discovery results.
                                    5. 
-
                                  5. At this point implementations MAY control the flow of the discovery process (depending
-on memory constraints, for instance temporarily stop discovery if
-the queue is getting too large, or resume discovery when the queue
-is emptied sufficiently).
                                    6. 
-
                                  
-
                                  8. 
-
                                8. Whenever an error occurs during the discovery process,
-
                                    
-
                                  1. Set this.error to a new Error object
-error. Set error.name to
-'DiscoveryError'.
                                    2. 
-
                                  2. If there was an error code or message provided by the Protocol Bindings, set error.message to that
-value as string.
                                    3. 
-
                                  3. If the error is irrecoverable and discovery has been stopped by
-the underlying platform, set this.active to
-false.
                                    4. 
-
                                  
-
                                  9. 
-
                                9. When the underlying platform reports the discovery process has
-completed, set this.active to false.
                                  10. 
-
                                
-
                                
-
                                
-
                                
-
                                8.5 The
-next()
-method
                                
-
                                
-
                                Provides the next discovered ThingDescription object. The method
-MUST run the following
-steps:
                                
-
                                  
-
                                1. Return a Promise
-promise and execute the next steps in
-parallel.
                                  2. 
-
                                2. If this.active is true, wait until the
-discovery results internal slot is not
-empty.
                                  3. 
-
                                3. If discovery results is empty and
-this.active is false, set
-this.done to true and reject
-promise.
                                  4. 
-
                                4. Remove the first ThingDescription object td from
-discovery results.
                                  5. 
-
                                5. Resolve promise with td and terminate
-these steps.
                                  6. 
-
                                
-
                                
-
                                
-
                                
-
                                8.6 The
-stop()
-method
                                
-
                                
-
                                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 inactive. The method MUST run the following steps:
                                
-
                                  
-
                                1. 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.
                                  2. 
-
                                2. Set this.active to false.
                                  3. 
-
                                
-
                                
-
                                
-
                                
-
                                8.7
-Discovery Examples
                                
-
                                The following example finds ThingDescription objects of Things
-that are exposed by local hardware, regardless how many instances
-of WoT Runtime it is running. Note that the discovery can
-end (become inactive) before the internal discovery results queue is emptied, so we need to
-continue reading ThingDescription objects until done. This is
-typical with local and directory type discoveries.
                                
-
                                
-
                                Example
-5: Discover Things
-exposed by local hardware
                                
-
                                let discovery = new ThingDiscovery({ method: "local" });
+      
                                The method
+      property represents the discovery type that should be used in
+      the discovery process. The possible values are defined by the
+      DiscoveryMethod
+      enumeration that MAY be
+      extended by string values defined by solutions (with no
+      guarantee of interoperability).
                                
+      
                                The url property represents
+      additional information for the discovery method, such as the
+      URL of the target entity serving the discovery request, for
+      instance the URL of a Thing Directory (if
+      method is "directory") or that of a
+      Thing (otherwise).
                                
+      
                                The query property represents a
+      query string accepted by the implementation, for instance a
+      SPARQL or JSON query. Support may be implemented locally in
+      the WoT Runtime or remotely as a service
+      in a Thing Directory.
                                
+      
                                The fragment property represents a
+      template object used for matching property by property
+      against discovered Things.
                                
+    
                                
+    
                                
+      
                                8.4
+      The 
+      start() method
                                
+      
                                
+        
                                Starts the discovery process. The method MUST run the following
+        steps:
                                
+        
                                  
+          
                                1. If invoking this method is not allowed for the
+          current scripting context for security reasons, set
+          this.error to SecurityError and
+          terminate these steps.
                                  2. 
+          
                                2. If discovery is not supported by the implementation,
+          set this.error to
+          NotSupportedError and terminate these
+          steps.
                                  3. 
+          
                                3. If this.filter is defined,
+            
                                    
+              
                                  • Let filter denote
+              this.filter.
                                    • 
+              
                                  • If filter.query is defined, pass it as
+              an opaque string to the underlying implementation to
+              be matched against discovered items. The underlying
+              implementation is responsible to parse it e.g. as a
+              SPARQL or JSON query and match it against the
+                Thing
+                Descriptions found during the discovery
+                process. If queries are not supported, set
+                this.error to
+                NotSupportedError and terminate these
+                steps.
+              
                                    • 
+            
                                  
+          
                                  4. 
+          
                                4. Create the discovery results
+          internal slot for storing discovered ThingDescription
+          objects.
+          
                                  5. 
+          
                                5. Request the underlying platform to start the
+          discovery process, with the following parameters:
+            
                                    
+              
                                  • If filter.method is not defined or the
+              value is "any", use the widest discovery
+              method supported by the underlying platform.
                                    • 
+              
                                  • Otherwise if filter.method is
+              "local", use the local Thing Directory for
+              discovery. Usually that defines Things
+                deployed in the same device, or connected to the
+                device in slave mode (e.g. sensors connected via
+                Bluetooth or a serial connection).
+              
                                    • 
+              
                                  • Otherwise if filter.method is
+              "directory", use the remote Thing Directory specified in
+              filter.url.
+              
                                    • 
+              
                                  • Otherwise if filter.method is
+              "multicast", use all the multicast
+              discovery protocols supported by the underlying
+              platform.
                                    • 
+            
                                  
+          
                                  6. 
+          
                                6. When the underlying platform has started the
+          discovery process, set the active property
+          to true.
                                  7. 
+          
                                7. Whenever a new Thing
+          Description td is discovered by the
+          underlying platform, run the following sub-steps:
+            
                                    
+              
                                  1. 
+                Fetch
+                td as a JSON object json. If
+                that fails, set this.error to
+                SyntaxError, discard td and
+                continue the discovery process.
+              
                                    2. 
+              
                                  2. If filter.query is defined, check if
+              json is a match for the query. The
+              matching algorithm is encapsulated by
+              implementations. If that returns false,
+              discard td and continue the discovery
+              process.
                                    3. 
+              
                                  3. If filter.fragment is defined, for
+              each property defined in it, check if that property
+              exists in json.properties and has the same
+              value. If this is false in any checks,
+              discard td and continue the discovery
+              process.
                                    4. 
+              
                                  4. Otherwise add td to the discovery results.
+              
                                    5. 
+              
                                  5. At this point implementations MAY control the flow of the
+              discovery process (depending on memory constraints,
+              for instance temporarily stop discovery if the queue
+              is getting too large, or resume discovery when the
+              queue is emptied sufficiently).
                                    6. 
+            
                                  
+          
                                  8. 
+          
                                8. Whenever an error occurs during the discovery
+          process,
+            
                                    
+              
                                  1. Set this.error to a new
+              Error object error. Set
+              error.name to
+              'DiscoveryError'.
                                    2. 
+              
                                  2. If there was an error code or message provided by
+              the Protocol
+              Bindings, set error.message to that
+              value as string.
+              
                                    3. 
+              
                                  3. If the error is irrecoverable and discovery has
+              been stopped by the underlying platform, set
+              this.active to false.
                                    4. 
+            
                                  
+          
                                  9. 
+          
                                9. When the underlying platform reports the discovery
+          process has completed, set this.active to
+          false.
                                  10. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                8.5
+      The 
+      next() method
                                
+      
                                
+        
                                Provides the next discovered ThingDescription object. The method
+        MUST run the
+        following steps:
                                
+        
                                  
+          
                                1. Return a Promise
+          promise and execute the next steps
+          in
+          parallel.
+          
                                  2. 
+          
                                2. If this.active is true, wait
+          until the discovery results
+          internal slot is not empty.
+          
                                  3. 
+          
                                3. If discovery results
+          is empty and this.active is
+          false, set this.done to
+          true and reject promise.
+          
                                  4. 
+          
                                4. Remove the first ThingDescription object
+          td from discovery
+            results.
+          
                                  5. 
+          
                                5. Resolve promise with td and
+          terminate these steps.
                                  6. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                8.6
+      The 
+      stop() method
                                
+      
                                
+        
                                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 inactive. The method
+        MUST run the
+        following steps:
                                
+        
                                  
+          
                                1. 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.
                                  2. 
+          
                                2. Set this.active to
+          false.
                                  3. 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                8.7
+      Discovery Examples
                                
+      
                                The following example finds ThingDescription objects of Things that are exposed by local hardware,
+      regardless how many instances of WoT Runtime it
+      is running. Note that the discovery can end (become inactive)
+      before the internal discovery results
+      queue is emptied, so we need to continue reading ThingDescription objects until done.
+      This is typical with local and directory type
+      discoveries.
                                
+      
                                
+        
                                
+          Example
+          5: Discover
+          Things exposed by local hardware
+        
                                
+        
                                let discovery = new ThingDiscovery({ method: "local" });
 do {
   let td = await discovery.next();
@@ -4643,21 +5287,26 @@ 
                                8.7
   console.log("Thing name: " + thing.getThingDescription().title);
 } while (!discovery.done);
                                
-
                                The next example finds ThingDescription objects of Things
-listed in a Thing Directory service. We set a timeout
-for safety.
                                
-
                                
-
                                Example
-6: Discover Things via
-directory
                                
-
                                let discoveryFilter = {
+"hljs-keyword">while (!discovery.done);
                                
+      
                                
+      
                                The next example finds ThingDescription objects of Things listed in a Thing Directory
+      service. We set a timeout for safety.
                                
+      
                                
+        
                                
+          Example
+          6: Discover
+          Things via directory
+        
                                
+        
                                let discoveryFilter = {
   method: "directory",
   url: 8.7
 if (discovery.error) {
   console.log("Discovery stopped because of an error: " + error.message);
-}
                                
-
                                The next example is for an open-ended multicast discovery, which
-likely won't complete soon (depending on the underlying protocol),
-so stopping it with a timeout is a good idea. It will likely
-deliver results one by one.
                                
-
                                
-
                                Example
-7: Discover Things in a
-network
                                
-
                                let discovery = new ThingDiscovery({ method: "multicast" });
+}
                                
+      
                                
+      
                                The next example is for an open-ended multicast discovery,
+      which likely won't complete soon (depending on the underlying
+      protocol), so stopping it with a timeout is a good idea. It
+      will likely deliver results one by one.
                                
+      
                                
+        
                                
+          Example
+          7: Discover
+          Things in a network
+        
                                
+        
                                let discovery = new ThingDiscovery({ method: "multicast" });
 setTimeout( () => {
     discovery.stop();
@@ -4715,534 +5369,604 @@ 
                                8.7
   console.log("Thing name: " + thing.getThingDescription().title);
 } while (!discovery.done);
                                
-
                                
-
                                
-
                                
-
                                9. Security and
-Privacy
                                
-
                                A detailed discussion of security and privacy considerations for
-the Web of Things, including a threat model that can be adapted to
-various circumstances, is presented in the informative document
-[WOT-SECURITY-GUIDELINES]. This section
-discusses only security and privacy risks and possible mitigations
-directly relevant to the scripts and WoT Scripting API.
                                
-
                                A suggested set of best practices to improve security for WoT
-devices and services has been documented in [WOT-SECURITY-BEST-PRACTICES]. That document may
-be updated as security measures evolve. Following these practices
-does not guarantee security, but it might help avoid common known
-vulnerabilities.
                                
-
                                
-
                                The WoT security risks and possible mitigations are concerning
-the following groups:
                                
-
                                  
-
                                • Implementors of WoT Runtimes that do not implement a Scripting
-Runtime. The [WOT-ARCHITECTURE] document provides generic
-security guidelines for this group.
                                  • 
-
                                • Implementors of the WoT Scripting API in a WoT Scripting
-Runtime. This is the main scope and is covered in the Scripting Runtime Security
-and Privacy Risks sub-section that contains normative text
-regarding security.
                                  • 
-
                                • WoT script developers, covered in the Script Security and Privacy
-Risks sub-section that contains informative recommendations
-concerning security.
                                  • 
-
                                
-
                                
-
                                
-
                                
-9.1 Scripting Runtime Security and Privacy
-Risks
                                
-
                                This section is normative and contains specific risks relevant
-for the WoT Scripting Runtime.
                                
-
                                
-
                                
-9.1.1 Corrupted Input Security and Privacy
-Risk
                                
-
                                A typical way to compromise any process is to send it a
-corrupted input via one of the exposed interfaces. This can be done
-to a script instance using WoT interface it exposes.
                                
-
                                
-
                                Mitigation:
                                
-
                                Implementors of this API SHOULD perform validation on all script inputs. In
-addition to input validation, fuzzing should be used
-to verify that the input processing is done correctly. There are
-many tools and techniques in existence to do such validation. More
-details can be found in [WOT-SECURITY-TESTING].
                                
-
                                
-
                                
-
                                
-
                                
-9.1.2 Physical Device Direct Access
-Security and Privacy Risk
                                
-
                                In case a script is compromised or misbehaving, the underlying
-physical device (and potentially surrounded environment) can be
-damaged if a script can use directly exposed native device
-interfaces. If such interfaces lack safety checks on their inputs,
-they might bring the underlying physical device (or environment) to
-an unsafe state (i.e. device overheats and explodes).
                                
-
                                
-
                                Mitigation:
                                
-
                                The WoT Scripting Runtime SHOULD avoid directly exposing the native device
-interfaces to the script developers. Instead, a WoT Scripting
-Runtime should provide a hardware abstraction layer for accessing
-the native device interfaces. Such hardware abstraction layer
-should refuse to execute commands that might put the device (or
-environment) to an unsafe state. Additionally, in order to reduce
-the damage to a physical WoT device in cases a script gets
-compromised, it is important to minimize the number of interfaces
-that are exposed or accessible to a particular script based on its
-functionality.
                                
-
                                
-
                                
-
                                
-
                                9.1.3 Provisioning and Update Security Risk
                                
-
                                If the WoT Scripting Runtime supports post-manufacturing
-provisioning or updates of scripts, WoT Scripting Runtime or any
-related data (including security credentials), it can be a major
-attack vector. An attacker can try to modify any above described
-element during the update or provisioning process or simply
-provision attacker's code and data directly.
                                
-
                                
-
                                Mitigation:
                                
-
                                Post-manufacturing provisioning or update of scripts, WoT
-Scripting Runtime or any related data should be done in a secure
-fashion. A set of recommendations for secure update and
-post-manufacturing provisioning can be found in [WOT-SECURITY-GUIDELINES].
                                
-
                                
-
                                
-
                                
-
                                
-9.1.4 Security Credentials Storage
-Security and Privacy Risk
                                
-
                                Typically the WoT Scripting Runtime needs to store the security
-credentials that are provisioned to a WoT device to operate in WoT
-network. If an attacker can compromise the confidentiality or
-integrity of these credentials, then it can obtain access to the
-WoT assets, impersonate WoT things or devices or create
-Denial-Of-Service (DoS) attacks.
                                
-
                                
-
                                Mitigation:
                                
-
                                The WoT Scripting Runtime should securely store the provisioned
-security credentials, guaranteeing their integrity and
-confidentiality. In case there are more than one tenant on a single
-WoT-enabled device, a WoT Scripting Runtime should guarantee
-isolation of each tenant provisioned security credentials.
-Additionally, in order to minimize a risk that provisioned security
-credentials get compromised, the WoT Scripting Runtime should not
-expose any API for scripts to query the provisioned security
-credentials.
                                
-
                                
-
                                
-
                                
-
                                
-
                                9.2 Script Security and Privacy Risks
                                
-
                                This section is non-normative.
                                
-
                                This section describes specific risks relevant for script
-developers.
                                
-
                                
-
                                
-9.2.1 Corrupted Script Input Security and
-Privacy Risk
                                
-
                                A script instance may receive data formats defined by the TD, or
-data formats defined by the applications. While the WoT Scripting
-Runtime SHOULD perform
-validation on all input fields defined by the TD, scripts may be
-still exploited by input data.
                                
-
                                
-
                                Mitigation:
                                
-
                                Script developers should perform validation on all application
-defined script inputs. In addition to input validation, fuzzing could be used
-to verify that the input processing is done correctly. There are
-many tools and techniques in existence to do such validation. More
-details can be found in [WOT-SECURITY-TESTING].
                                
-
                                
-
                                
-
                                
-
                                9.2.2 Denial Of Service Security Risk
                                
-
                                If a script performs a heavy functional processing on received
-requests before the request is authenticated, it presents a great
-risk for Denial-Of-Service (DOS) attacks.
                                
-
                                
-
                                Mitigation:
                                
-
                                Scripts should avoid heavy functional processing without prior
-successful authentication of requestor. The set of recommended
-authentication mechanisms can be found in [WOT-SECURITY-BEST-PRACTICES].
                                
-
                                
-
                                
-
                                
-
                                9.2.3 Stale TD Security Risk
                                
-
                                During the lifetime of a WoT network, a content of a TD can
-change. This includes its identifier, which might not be an
-immutable one and might be updated periodically.
                                
-
                                
-
                                Mitigation:
                                
-
                                Scripts should use this API to subscribe for notifications on
-TD changes and do not rely on TD values to remain persistent.
                                
-
                                
-
                                
-
                                Editor's note
                                
-
                                While stale TDs can present a potential problem for WoT
-network operation, it might not be a security risk.
                                
-
                                
-
                                
-
                                
-
                                
-
                                
-
                                10. Terminology and conventions
                                
-
                                The generic WoT terminology is defined in [WOT-ARCHITECTURE]: Thing, Thing Description (in short
-TD), Web of Things (in short
-WoT), WoT Interface (same as
-WoT network
-interface), Protocol Bindings,
-WoT Runtime,
-Consuming a Thing
-Description, Thing Directory, WoT Interactions,
-Property,
-Action, Event etc.
                                
-
                                JSON-LD is
-defined in [JSON-LD] as a JSON
-document that is augmented with support for Linked Data.
                                
-
                                The terms URL,
-URL
-scheme, URL host,
-URL
-path, URL record,
-parse a
-URL, absolute-URL
-string, path-absolute-URL
-string, basic URL
-parser are defined in [URL].
                                
-
                                The terms MIME type,
-Parsing a
-MIME type, Serializing
-a MIME type, valid MIME
-type string, JSON MIME
-type are defined in [MIMESNIFF].
                                
-
                                The terms UTF-8 encoding,
-UTF-8
-decode, encode,
-decode are
-defined in [ENCODING].
                                
-
                                string,
-parse JSON
-from bytes and serialize
-JSON to bytes, are defined in [INFRA].
                                
-
                                The terms throw,
-creating,
-DOMString,
-Dictionary,
-ArrayBuffer,
-BufferSource,
-any,
-not
-present, DOMException,
-AbortError,
-SyntaxError,
-NotSupportedError,
-NetworkError,
-TypeError,
-NotReadableError,
-TimeoutError,
-
-NoModificationAllowedError, SecurityError,
-are defined in [WEBIDL].
                                
-
                                Promise,
-Error,
-JSON,
-JSON.stringify,
-JSON.parse
-and 
-internal slots are defined in [ECMASCRIPT].
                                
-
                                The terms browsing
-context, 
-top-level browsing context, global
-object, current
-settings object, executing algorithms in
-parallel are defined in [HTML5] and are used in the context of browser
-implementations.
                                
-
                                The term 
-secure
-context is defined in [WEBAPPSEC].
                                
-
                                IANA media
-types (formerly known as MIME types) are defined in RFC2046.
                                
-
                                The terms hyperlink reference and
-relation type
-are defined in [HTML5] and RFC8288.
                                
-
                                
-
                                
-
                                A. API
-design rationale
                                
-
                                API rationale usually belongs to a separate document, but in the
-WoT case the complexity of the context justifies including basic
-rationale here.
                                
-
                                
-
                                A.1 Approaches to WoT application
-development
                                
-
                                The WoT Interest Group and Working Group have explored different
-approaches to application development for WoT that have been all
-implemented and tested.
                                
-
                                
-
                                A.1.1 No
-Scripting API
                                
-
                                It is possible to develop WoT applications that only use the
-WoT network interface, typically exposed
-by a WoT gateway that presents a REST-ful API towards clients and
-implements IoT protocol plugins that communicate with supported IoT
-deployments. One such implementation is the Mozilla WebThings platform.
                                
-
                                
-
                                
-
                                A.1.2
-Simple Scripting API
                                
-
                                WoT Things show good synergy with software objects, so a
-Thing can be represented as a software object, with
-Properties represented as object properties, Actions
-as methods, and Events as events. In addition, metadata is
-stored in special properties. Consuming and exposing is done with
-factory methods that produce a software object that directly
-represents a remote Thing and its interactions. One such
-implementation is the Arena Web Hub
-project.
                                
-
                                In the next example, a Thing that represents interactions with a
-lock would look like the following: the status property
-and the open() method are directly exposed on the
-object.
                                
-
                                
-
                                Example
-8: Open a lock with a
-simple API
                                
-
                                let lock = await WoT.consume(‘https://td.my.com/lock-00123’);
+"hljs-keyword">while (!discovery.done);
                                
+      
                                
+    
                                
+  
                                
+  
                                
+    
                                9. Security and
+    Privacy
                                
+    
                                A detailed discussion of security and privacy considerations
+    for the Web of Things, including a threat model that can be
+    adapted to various circumstances, is presented in the
+    informative document [WOT-SECURITY-GUIDELINES]. This section
+    discusses only security and privacy risks and possible
+    mitigations directly relevant to the scripts and WoT Scripting
+    API.
                                
+    
                                A suggested set of best practices to improve security for
+    WoT devices and services has been documented in
+    [WOT-SECURITY-BEST-PRACTICES]. That document
+    may be updated as security measures evolve. Following these
+    practices does not guarantee security, but it might help avoid
+    common known vulnerabilities.
                                
+    
                                
+      
                                The WoT security risks and possible mitigations are
+      concerning the following groups:
                                
+      
                                  
+        
                                • Implementors of WoT Runtimes that do not implement a
+        Scripting Runtime. The [WOT-ARCHITECTURE]
+        document provides generic security guidelines for this
+        group.
                                  • 
+        
                                • Implementors of the WoT Scripting API in a WoT
+        Scripting Runtime. This is the main scope and is covered in
+        the Scripting
+        Runtime Security and Privacy Risks sub-section that
+        contains normative text regarding security.
+        
                                  • 
+        
                                • WoT script developers, covered in the Script Security and
+        Privacy Risks sub-section that contains informative
+        recommendations concerning security.
+        
                                  • 
+      
                                
+    
                                
+    
                                
+      
                                
+      9.1 Scripting Runtime Security and
+      Privacy Risks
                                
+      
                                This section is normative and contains specific risks
+      relevant for the WoT Scripting Runtime.
                                
+      
                                
+        
                                
+        9.1.1 Corrupted Input Security and
+        Privacy Risk
                                
+        
                                A typical way to compromise any process is to send it a
+        corrupted input via one of the exposed interfaces. This can
+        be done to a script instance using WoT interface it
+        exposes.
                                
+        
                                
+          
                                Mitigation:
                                
+          
                                
+            Implementors of this API SHOULD perform validation on all script
+            inputs. In addition to input validation, fuzzing
+            should be used to verify that the input processing is
+            done correctly. There are many tools and techniques in
+            existence to do such validation. More details can be
+            found in [WOT-SECURITY-TESTING].
+          
                                
+        
                                
+      
                                
+      
                                
+        
                                
+        9.1.2 Physical Device Direct
+        Access Security and Privacy Risk
                                
+        
                                In case a script is compromised or misbehaving, the
+        underlying physical device (and potentially surrounded
+        environment) can be damaged if a script can use directly
+        exposed native device interfaces. If such interfaces lack
+        safety checks on their inputs, they might bring the
+        underlying physical device (or environment) to an unsafe
+        state (i.e. device overheats and explodes).
                                
+        
                                
+          
                                Mitigation:
                                
+          
                                The WoT Scripting Runtime SHOULD avoid directly exposing the native
+          device interfaces to the script developers. Instead, a
+          WoT Scripting Runtime should provide a hardware
+          abstraction layer for accessing the native device
+          interfaces. Such hardware abstraction layer should refuse
+          to execute commands that might put the device (or
+          environment) to an unsafe state. Additionally, in order
+          to reduce the damage to a physical WoT device in cases a
+          script gets compromised, it is important to minimize the
+          number of interfaces that are exposed or accessible to a
+          particular script based on its functionality.
                                
+        
                                
+      
                                
+      
                                
+        
                                
+        9.1.3 Provisioning and Update
+        Security Risk
                                
+        
                                If the WoT Scripting Runtime supports post-manufacturing
+        provisioning or updates of scripts, WoT Scripting Runtime
+        or any related data (including security credentials), it
+        can be a major attack vector. An attacker can try to modify
+        any above described element during the update or
+        provisioning process or simply provision attacker's code
+        and data directly.
                                
+        
                                
+          
                                Mitigation:
                                
+          
                                Post-manufacturing provisioning or update of scripts,
+          WoT Scripting Runtime or any related data should be done
+          in a secure fashion. A set of recommendations for secure
+          update and post-manufacturing provisioning can be found
+          in [WOT-SECURITY-GUIDELINES].
                                
+        
                                
+      
                                
+      
                                
+        
                                
+        9.1.4 Security Credentials Storage
+        Security and Privacy Risk
                                
+        
                                Typically the WoT Scripting Runtime needs to store the
+        security credentials that are provisioned to a WoT device
+        to operate in WoT network. If an attacker can compromise
+        the confidentiality or integrity of these credentials, then
+        it can obtain access to the WoT assets, impersonate WoT
+        things or devices or create Denial-Of-Service (DoS)
+        attacks.
                                
+        
                                
+          
                                Mitigation:
                                
+          
                                The WoT Scripting Runtime should securely store the
+          provisioned security credentials, guaranteeing their
+          integrity and confidentiality. In case there are more
+          than one tenant on a single WoT-enabled device, a WoT
+          Scripting Runtime should guarantee isolation of each
+          tenant provisioned security credentials. Additionally, in
+          order to minimize a risk that provisioned security
+          credentials get compromised, the WoT Scripting Runtime
+          should not expose any API for scripts to query the
+          provisioned security credentials.
                                
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                9.2 Script Security and Privacy Risks
                                
+      
                                This section is non-normative.
                                
+      
                                This section describes specific risks relevant for script
+      developers.
                                
+      
                                
+        
                                
+        9.2.1 Corrupted Script Input
+        Security and Privacy Risk
                                
+        
                                A script instance may receive data formats defined by
+        the TD, or data formats defined by the applications. While
+        the WoT Scripting Runtime SHOULD perform validation on all input fields
+        defined by the TD, scripts may be still exploited by input
+        data.
                                
+        
                                
+          
                                Mitigation:
                                
+          
                                
+            Script developers should perform validation on all
+            application defined script inputs. In addition to input
+            validation, fuzzing
+            could be used to verify that the input processing is
+            done correctly. There are many tools and techniques in
+            existence to do such validation. More details can be
+            found in [WOT-SECURITY-TESTING].
+          
                                
+        
                                
+      
                                
+      
                                
+        
                                9.2.2 Denial Of Service Security
+        Risk
                                
+        
                                If a script performs a heavy functional processing on
+        received requests before the request is authenticated, it
+        presents a great risk for Denial-Of-Service (DOS)
+        attacks.
                                
+        
                                
+          
                                Mitigation:
                                
+          
                                Scripts should avoid heavy functional processing
+          without prior successful authentication of requestor. The
+          set of recommended authentication mechanisms can be found
+          in [WOT-SECURITY-BEST-PRACTICES].
                                
+        
                                
+      
                                
+      
                                
+        
                                9.2.3 Stale TD Security Risk
                                
+        
                                During the lifetime of a WoT network, a content of a TD
+        can change. This includes its identifier, which might not
+        be an immutable one and might be updated periodically.
                                
+        
                                
+          
                                Mitigation:
                                
+          
                                Scripts should use this API to subscribe for
+          notifications on TD changes and do not rely on TD values
+          to remain persistent.
                                
+        
                                
+        
                                
+          
                                
+            Editor's note
+          
                                
+          
                                While stale TDs can present a potential
+          problem for WoT network operation, it might not be a
+          security risk.
                                
+        
                                
+      
                                
+    
                                
+  
                                
+  
                                
+    
                                10. Terminology and conventions
                                
+    
                                The generic WoT terminology is defined in [WOT-ARCHITECTURE]: Thing, Thing Description (in short
+    TD),
+    Web of
+    Things (in short WoT), WoT Interface (same as
+    WoT
+    network interface), Protocol Bindings,
+    WoT
+    Runtime, Consuming a Thing
+    Description, Thing Directory,
+    WoT
+    Interactions, Property, Action, Event etc.
                                
+    
                                JSON-LD is
+    defined in [JSON-LD] as a
+    JSON document that is augmented with support for Linked
+    Data.
                                
+    
                                The terms URL,
+    URL
+    scheme, URL
+    host, URL
+    path, URL
+    record, parse a
+    URL, absolute-URL
+    string, path-absolute-URL
+    string, basic
+    URL parser are defined in [URL].
                                
+    
                                The terms MIME
+    type, Parsing
+    a MIME type, Serializing
+    a MIME type, valid MIME
+    type string, JSON MIME
+    type are defined in [MIMESNIFF].
                                
+    
                                The terms UTF-8
+    encoding, UTF-8
+    decode, encode,
+    decode are
+    defined in [ENCODING].
                                
+    
                                string,
+    parse
+    JSON from bytes and serialize
+    JSON to bytes, are defined in [INFRA].
                                
+    
                                The terms throw,
+    creating,
+    DOMString,
+    Dictionary,
+    ArrayBuffer,
+    BufferSource,
+    any,
+    not
+    present, DOMException,
+    AbortError,
+    SyntaxError,
+    NotSupportedError,
+    NetworkError,
+    
+    TypeError, NotReadableError,
+    TimeoutError,
+    
+    NoModificationAllowedError,
+    SecurityError,
+    are defined in [WEBIDL].
                                
+    
                                Promise,
+    Error,
+    JSON,
+    JSON.stringify,
+    JSON.parse
+    and 
+    internal slots are defined in [ECMASCRIPT].
                                
+    
                                The terms browsing
+    context, 
+    top-level browsing context, global
+    object, 
+    current settings object, executing algorithms
+    in
+    parallel are defined in [HTML5] and are used in the context of
+    browser implementations.
                                
+    
                                The term 
+    secure
+    context is defined in [WEBAPPSEC].
                                
+    
                                IANA media
+    types (formerly known as MIME types) are defined in
+    RFC2046.
                                
+    
                                The terms hyperlink reference and
+    relation
+    type are defined in [HTML5] and RFC8288.
                                
+  
                                
+  
                                
+    
                                A. API
+    design rationale
                                
+    
                                API rationale usually belongs to a separate document, but in
+    the WoT case the complexity of the context justifies including
+    basic rationale here.
                                
+    
                                
+      
                                
+      A.1 Approaches to WoT application
+      development
                                
+      
                                The WoT Interest Group and Working Group have explored
+      different approaches to application development for WoT that
+      have been all implemented and tested.
                                
+      
                                
+        
                                A.1.1 No Scripting API
                                
+        
                                It is possible to develop WoT applications that only use
+        the WoT network
+        interface, typically exposed by a WoT gateway that
+        presents a REST-ful API towards clients and implements IoT
+        protocol plugins that communicate with supported IoT
+        deployments. One such implementation is the Mozilla WebThings
+        platform.
                                
+      
                                
+      
                                
+        
                                A.1.2 Simple Scripting API
                                
+        
                                WoT Things show good synergy with
+        software objects, so a Thing can be
+        represented as a software object, with Properties represented as object properties,
+        Actions as methods, and Events as
+        events. In addition, metadata is stored in special
+        properties. Consuming and exposing is done with factory
+        methods that produce a software object that directly
+        represents a remote Thing and its
+        interactions. One such implementation is the Arena Web
+        Hub project.
                                
+        
                                In the next example, a Thing that
+        represents interactions with a lock would look like the
+        following: the status property and the
+        open() method are directly exposed on the
+        object.
                                
+        
                                
+          
                                
+            Example
+            8: Open a
+            lock with a simple API
+          
                                
+          
                                let lock = await WoT.consume(‘https://td.my.com/lock-00123’);
 console.log(lock.status);
 lock.open('withThisKey');
                                
-
                                
-
                                
-
                                A.1.3 This API, aligned with [WOT-TD]
                                
-
                                Since the direct mapping of Things to software objects
-have had some challenges, this specification takes another approach
-that exposes software objects to represent the Thing
-metadata as data property and the WoT interactions as methods. One
-implementation is node-wot in the
-the Eclipse ThingWeb project,
-which is the current reference implementation of the API specified
-in this document.
                                
-
                                The same example now would look like the following: the
-status property and the open() method are
-represented indirectly.
                                
-
                                
-
                                Example 9: Open a lock
                                
-
                                let res = await fetch(‘https://td.my.com/lock-00123’);
+"hljs-string">'withThisKey');
                                
+        
                                
+      
                                
+      
                                
+        
                                A.1.3 This API, aligned with [WOT-TD]
                                
+        
                                Since the direct mapping of Things to software
+        objects have had some challenges, this specification takes
+        another approach that exposes software objects to represent
+        the Thing metadata as data property
+        and the WoT interactions as methods. One implementation is
+        node-wot
+        in the the Eclipse
+        ThingWeb project, which is the current reference
+        implementation of the API specified in this document.
                                
+        
                                The same example now would look like the following: the
+        status property and the open()
+        method are represented indirectly.
                                
+        
                                
+          
                                
+            Example
+            9: Open a
+            lock
+          
                                
+          
                                let res = await fetch(‘https://td.my.com/lock-00123’);
 let td = await res.json();
 let lock = console.log(lock.readProperty(‘status’));
 lock.invokeAction(‘open’, 'withThisKey');
                                
-
                                
-
                                In conclusion, the WoT WG decided to explore the third option
-that closely follows the [WOT-TD] specification. Based on this, a simple
-API can also be implemented. Since Scripting is an optional module
-in WoT, this leaves room for applications that only use the WoT
-network interface. Therefore all three approaches above are
-supported by [WOT-TD].
                                
-
                                Moreover, the WoT network interface can be implemented in many
-languages and runtimes. Consider this API an example for what needs
-to be taken into consideration when designing a Scripting API for
-WoT.
                                
-
                                
-
                                
-
                                A.2 Fetching and validating a TD
                                
-
                                The fetch(url) method has been part of this API in
-earlier versions. However, now fetching a TD given a URL should be
-done with an external method, such as the Fetch API or a HTTP
-client library, which offer already standardized options on
-specifying fetch details. The reason is that while simple fetch
-operations (covering most use cases) could be done in this API,
-when various fetch options were needed, there was no point in
-duplicating existing work to re-expose those options in this
-API.
                                
-
                                Since fetching a TD has been scoped out, and TD
-validation is defined externally in [WOT-TD], that is scoped out, too. This
-specification expects a TD as parsed JSON
-object that has been validated according to the
-[WOT-TD]
-specification.
                                
-
                                
-
                                
-
                                A.3
-Factory vs constructors
                                
-
                                The factory methods for consuming and exposing Things
-are asynchronous and fully validate the input TD. In addition, one
-can also construct ConsumedThing and ExposedThing by providing a parsed and
-validated TD. Platform initialization is then done when needed
-during the WoT interactions. So applications that prefer validating
-a TD
-themselves, may use the constructors, whereas applications that
-leave validation to implementations and prefer interactions
-initialized up front SHOULD
-use the factory methods on the WoT API object.
                                
-
                                
-
                                
-
                                A.4
-Observers
                                
-
                                Earlier drafts used the Observer
-construct, but since it has not become standard, a new design was
-needed that was light enough for embedded implementations.
-Therefore observing Property changes and handling WoT Events
-is done with callback registrations.
                                
-
                                
-
                                
-
                                A.5 Using
-Events
                                
-
                                
-
                                This API ended up not using software events at all, for the
-following reasons:
                                
-
                                  
-
                                • Subscription to WoT Events may be different from handling
-software events (subscription might need parameters, might involve
-security tokens etc).
                                  • 
-
                                • Most implementations are for Node.js and browser
-implementations will likely be libraries (because possible
-dependency management issues in native implementations), using
-Events has been challenging.
                                  • 
-
                                • Observing Property changes and handling WoT Events
-is done with the solution above.
                                  • 
-
                                
-
                                
-
                                
-
                                
-
                                A.6
-Polymorphic functions
                                
-
                                The reason to use function names like
-readProperty(), readMultipleProperties()
-etc. instead of a generic polymorphic read() function
-is that the current names map exactly to the "op"
-vocabulary from the Form
-definition in [WOT-TD].
                                
-
                                
-
                                
-
                                
-
                                B. Changes
                                
-
                                
-
                                The following is a list of major changes to the document. Major
-versions of this specification are the following:
                                
-
-
                                
-
                                For a complete list of changes, see the github
-change log. You can also view the 
-recently closed issues.
                                
-
                                
-
                                
-
                                C.
-Open issues
                                
-
                                
-
                                The following problems are being discussed and need most
-attention:
                                
-
                                  
-
                                • Script management and runtime related issues
-(https://github.com/w3c/wot-scripting-api/issues/)
                                  • 
-
                                • An explicit API for adding and removing Property, Action and Event definitions on
-ExposedThing (it was present in earlier
-versions, but removed for complexity and a simpler way to do
-it.
                                  • 
-
                                
-
                                
-
                                
-
                                
-
                                D. Full Web
-IDL
                                
-
                                typedef object 'withThisKey');
                                
+        
+      
                                
+      
                                In conclusion, the WoT WG decided to explore the third
+      option that closely follows the [WOT-TD] specification.
+      Based on this, a simple API can also be implemented. Since
+      Scripting is an optional module in WoT, this leaves room for
+      applications that only use the WoT network interface.
+      Therefore all three approaches above are supported by
+      [WOT-TD].
                                
+      
                                Moreover, the WoT network interface can be implemented in
+      many languages and runtimes. Consider this API an example for
+      what needs to be taken into consideration when designing a
+      Scripting API for WoT.
                                
+    
                                
+    
                                
+      
                                A.2 Fetching and validating a TD
                                
+      
                                The fetch(url) method has been part of this
+      API in earlier versions. However, now fetching a TD
+      given a URL should be done with an external method, such as
+      the Fetch
+      API or a HTTP client library, which offer already
+      standardized options on specifying fetch details. The reason
+      is that while simple fetch operations (covering most use
+      cases) could be done in this API, when various fetch options
+      were needed, there was no point in duplicating existing work
+      to re-expose those options in this API.
                                
+      
                                Since fetching a TD has been scoped out, and TD
+      validation is defined externally in [WOT-TD], that is scoped
+      out, too. This specification expects a TD as parsed
+      JSON object that has been validated according to the
+      [WOT-TD] specification.
                                
+    
                                
+    
                                
+      
                                A.3 Factory vs constructors
                                
+      
                                The factory methods for consuming and exposing Things are asynchronous and fully validate the
+      input TD. In addition, one can also construct ConsumedThing and ExposedThing by providing a parsed and
+      validated TD. Platform initialization is then
+      done when needed during the WoT interactions. So applications
+      that prefer validating a TD themselves, may use
+      the constructors, whereas applications that leave validation
+      to implementations and prefer interactions initialized up
+      front SHOULD use the
+      factory methods on the WoT API object.
                                
+    
                                
+    
                                
+      
                                A.4
+      Observers
                                
+      
                                Earlier drafts used the Observer
+      construct, but since it has not become standard, a new design
+      was needed that was light enough for embedded
+      implementations. Therefore observing Property changes and handling WoT Events is done with callback registrations.
                                
+    
                                
+    
                                
+      
                                A.5 Using
+      Events
                                
+      
                                
+        
                                This API ended up not using software events at all, for
+        the following reasons:
                                
+        
                                  
+          
                                • Subscription to WoT Events may be
+          different from handling software events (subscription
+          might need parameters, might involve security tokens
+          etc).
+          
                                  • 
+          
                                • Most implementations are for Node.js and browser
+          implementations will likely be libraries (because
+          possible dependency management issues in native
+          implementations), using Events has been challenging.
                                  • 
+          
                                • Observing Property changes
+          and handling WoT Events is done
+          with the solution above.
+          
                                  • 
+        
                                
+      
                                
+    
                                
+    
                                
+      
                                A.6 Polymorphic functions
                                
+      
                                The reason to use function names like
+      readProperty(),
+      readMultipleProperties() etc. instead of a
+      generic polymorphic read() function is that the
+      current names map exactly to the "op" vocabulary
+      from the Form
+      definition in [WOT-TD].
                                
+    
                                
+  
                                
+  
                                
+    
                                B. Changes
                                
+    
                                
+      
                                The following is a list of major changes to the document.
+      Major versions of this specification are the following:
                                
+      
+    
                                
+    
                                For a complete list of changes, see the github
+    change log. You can also view the 
+    recently closed issues.
                                
+  
                                
+  
                                
+    
                                C. Open issues
                                
+    
                                
+      
                                The following problems are being discussed and need most
+      attention:
                                
+      
                                  
+        
                                • Script management and runtime related issues
+        (https://github.com/w3c/wot-scripting-api/issues/)
                                  • 
+        
                                • An explicit API for adding and removing 
+          Property, Action and Event
+          definitions on ExposedThing (it was present in
+          earlier versions, but removed for complexity and a
+          simpler way to do it.
+        
                                  • 
+      
                                
+    
                                
+  
                                
+  
                                
+    
                                D. Full Web
+    IDL
                                
+    
                                typedef object ThingDescription;
 
@@ -6003,134 +6755,193 @@ 
                                D. Full Web
 "https://heycam.github.io/webidl/#idl-object">object? fragment;
-};
                                
-
                                
-
                                E.
-Acknowledgements
                                
-
                                Special thanks to former editor Johannes Hund (until August
-2017, when at Siemens AG) and Kazuaki Nimura (until December 2018)
-for developing this specification. Also, the editors would like to
-thank Dave Raggett, Matthias Kovatsch, Michael Koster, Elena
-Reshetova, Michael McCool as well as the other WoT WG members for
-their comments, contributions and guidance.
                                
-
                                
-
                                
-
                                F.
-References
                                
-
                                
-
                                F.1
-Normative references
                                
-
                                
-
                                [ECMASCRIPT]
                                
-
                                ECMAScript
-Language Specification. Ecma International. URL:
-https://tc39.github.io/ecma262/
                                
-
                                [ENCODING]
                                
-
                                Encoding
-Standard. Anne van Kesteren. WHATWG. Living Standard.
-URL: https://encoding.spec.whatwg.org/
                                
-
                                [HTML]
                                
-
                                HTML
-Standard. Anne van Kesteren; Domenic Denicola; Ian
-Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard.
-URL: https://html.spec.whatwg.org/multipage/
                                
-
                                [HTML5]
                                
-
                                HTML5.
-Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika
-Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. W3C. 27 March
-2018. W3C Recommendation. URL: https://www.w3.org/TR/html5/
                                
-
                                [INFRA]
                                
-
                                Infra
-Standard. Anne van Kesteren; Domenic Denicola. WHATWG.
-Living Standard. URL: https://infra.spec.whatwg.org/
                                
-
                                [JSON-LD]
                                
-
                                JSON-LD
-1.0. Manu Sporny; Gregg Kellogg; Markus Lanthaler. W3C.
-16 January 2014. W3C Recommendation. URL: https://www.w3.org/TR/json-ld/
                                
-
                                [MIMESNIFF]
                                
-
                                MIME
-Sniffing Standard. Gordon P. Hemsley. WHATWG. Living
-Standard. URL: https://mimesniff.spec.whatwg.org/
                                
-
                                [RFC2119]
                                
-
                                Key words
-for use in RFCs to Indicate Requirement Levels. S.
-Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
                                
-
                                [RFC8174]
                                
-
                                Ambiguity
-of Uppercase vs Lowercase in RFC 2119 Key Words. B.
-Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174
                                
-
                                [TYPESCRIPT]
                                
-
                                
-TypeScript Language Specification. Microsoft. 1 October
-2012. URL: https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md
                                
-
                                [URL]
                                
-
                                URL
-Standard. Anne van Kesteren. WHATWG. Living Standard.
-URL: https://url.spec.whatwg.org/
                                
-
                                [WEBAPPSEC]
                                
-
                                Secure
-Contexts. W3C. 17 July 2015. URL: https://w3c.github.io/webappsec/specs/powerfulfeatures
                                
-
                                [WEBIDL]
                                
-
                                Web
-IDL. Boris Zbarsky. W3C. 15 December 2016. W3C Editor's
-Draft. URL: https://heycam.github.io/webidl/
                                
-
                                [WOT-ARCHITECTURE]
                                
-
                                Web of
-Things Architecture. W3C. 20 August 2017. URL: https://w3c.github.io/wot-architecture/
                                
-
                                [WOT-PROTOCOL-BINDINGS]
                                
-
                                Web of Things
-Protocol Binding Templates. W3C. 20 August 2017. URL:
-https://w3c.github.io/wot-binding-templates/
                                
-
                                
-[WOT-SECURITY-BEST-PRACTICES]
                                
-
                                
-Web of Things Security and Privacy Best Practices.
-W3C. WIP. URL: 
-https://github.com/w3c/wot-security/blob/master/wot-security-best-practices.md
                                
-
                                [WOT-SECURITY-GUIDELINES]
                                
-
                                Web of
-Things Security and Privacy Guidelines. W3C. 28 August
-2017. URL: https://w3c.github.io/wot-security/
                                
-
                                [WOT-SECURITY-TESTING]
                                
-
                                
-Web of Things Security Testing and Validation.
-W3C. WIP. URL: 
-https://github.com/w3c/wot-security/blob/master/wot-security-testing.md
                                
-
                                [WOT-TD]
                                
-
                                WoT Thing
-Description . W3C. 20 August 2017. URL: https://w3c.github.io/wot-thing-description/
                                
-
                                
-
                                
-
                                
-
-
+};
                                +
                                +
                                +

                                E. + Acknowledgements

                                +

                                Special thanks to former editor Johannes Hund (until August + 2017, when at Siemens AG) and Kazuaki Nimura (until December + 2018) for developing this specification. Also, the editors + would like to thank Dave Raggett, Matthias Kovatsch, Michael + Koster, Elena Reshetova, Michael McCool as well as the other + WoT WG members for their comments, contributions and + guidance.

                                +
                                +
                                +

                                F. + References

                                +
                                +

                                F.1 Normative references

                                +
                                +
                                [ECMASCRIPT]
                                +
                                + ECMAScript + Language Specification. Ecma International. + URL: https://tc39.github.io/ecma262/ +
                                +
                                [ENCODING]
                                +
                                + Encoding + Standard. Anne van Kesteren. WHATWG. Living + Standard. URL: https://encoding.spec.whatwg.org/ +
                                +
                                [HTML]
                                +
                                + HTML + Standard. Anne van Kesteren; Domenic Denicola; + Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. + Living Standard. URL: https://html.spec.whatwg.org/multipage/ +
                                +
                                [HTML5]
                                +
                                + HTML5. + Ian Hickson; Robin Berjon; Steve Faulkner; Travis + Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia + Pfeiffer. W3C. 27 March 2018. W3C Recommendation. URL: + https://www.w3.org/TR/html5/ +
                                +
                                [INFRA]
                                +
                                + Infra + Standard. Anne van Kesteren; Domenic Denicola. + WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/ +
                                +
                                [JSON-LD]
                                +
                                + JSON-LD + 1.0. Manu Sporny; Gregg Kellogg; Markus + Lanthaler. W3C. 16 January 2014. W3C Recommendation. URL: + https://www.w3.org/TR/json-ld/ +
                                +
                                [MIMESNIFF]
                                +
                                + MIME + Sniffing Standard. Gordon P. Hemsley. WHATWG. + Living Standard. URL: https://mimesniff.spec.whatwg.org/ +
                                +
                                [RFC2119]
                                +
                                + Key + words for use in RFCs to Indicate Requirement + Levels. S. Bradner. IETF. March 1997. Best + Current Practice. URL: https://tools.ietf.org/html/rfc2119 +
                                +
                                [RFC8174]
                                +
                                + Ambiguity of + Uppercase vs Lowercase in RFC 2119 Key Words. + B. Leiba. IETF. May 2017. Best Current Practice. URL: + https://tools.ietf.org/html/rfc8174 +
                                +
                                [TYPESCRIPT]
                                +
                                + + TypeScript Language Specification. + Microsoft. 1 October 2012. URL: + https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md +
                                +
                                [URL]
                                +
                                + URL + Standard. Anne van Kesteren. WHATWG. Living + Standard. URL: https://url.spec.whatwg.org/ +
                                +
                                [WEBAPPSEC]
                                +
                                + + Secure Contexts. W3C. 17 July 2015. URL: + https://w3c.github.io/webappsec/specs/powerfulfeatures +
                                +
                                [WEBIDL]
                                +
                                + Web + IDL. Boris Zbarsky. W3C. 15 December 2016. W3C + Editor's Draft. URL: https://heycam.github.io/webidl/ +
                                +
                                [WOT-ARCHITECTURE]
                                +
                                + Web of + Things Architecture. W3C. 20 August 2017. URL: + https://w3c.github.io/wot-architecture/ +
                                +
                                + [WOT-PROTOCOL-BINDINGS]
                                +
                                + Web + of Things Protocol Binding Templates. W3C. 20 + August 2017. URL: https://w3c.github.io/wot-binding-templates/ +
                                +
                                + [WOT-SECURITY-BEST-PRACTICES]
                                +
                                + + Web of Things Security and Privacy Best + Practices. W3C. WIP. URL: + https://github.com/w3c/wot-security/blob/master/wot-security-best-practices.md +
                                +
                                + [WOT-SECURITY-GUIDELINES]
                                +
                                + Web + of Things Security and Privacy Guidelines. + W3C. 28 August 2017. URL: https://w3c.github.io/wot-security/ +
                                +
                                + [WOT-SECURITY-TESTING]
                                +
                                + + Web of Things Security Testing and + Validation. W3C. WIP. URL: + https://github.com/w3c/wot-security/blob/master/wot-security-testing.md +
                                +
                                [WOT-TD]
                                +
                                + WoT + Thing Description . W3C. 20 August 2017. URL: + https://w3c.github.io/wot-thing-description/ +
                                +
                                +
                                +
                                + + From ae05a74c035dc00aaa634127a1ebd9ba5073c6cb Mon Sep 17 00:00:00 2001 From: ashimura Date: Mon, 21 Oct 2019 17:41:03 +0900 Subject: [PATCH 358/464] fix This version and add Previous version --- releases/wd4/Overview.html | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/releases/wd4/Overview.html b/releases/wd4/Overview.html index c2ba5bf6..3feacfb8 100644 --- a/releases/wd4/Overview.html +++ b/releases/wd4/Overview.html @@ -1062,7 +1062,8 @@

                                W3C Editor's Draft

                                This section is non-normative.

                                + +

                                +

                                The following scripting @@ -3052,7 +3819,8 @@

                                in this specification: -

                                2.1 +

                                +2.1 Discovery Discover all @@ -3136,12 +3904,21 @@

                                it is stopped/suppressed. -

                                2.1 + +
                                +

                                +2.2 + + +2.1 + Consuming a Thing -

                                2.2 -

                                + -

                                2.2 + +

                                +
                                +

                                +2.3 + + +2.2 + Exposing a Thing -

                                2.3 -

                                + -

                                3. + +
                                +3. The WoT -object -

                                2.3 -Discovery -

                                • -Discover - -Thing - + +
                                  +

                                  +object + + +2.3 + +Discovery + The WoT @@ -3633,7 +4425,14 @@

                                  is exposed -s +

                                  +
                                    +
                                  • +Discover + +Thing + +s in a network @@ -3658,7 +4457,7 @@

                                    the local - + WoT Runtime . @@ -3686,6 +4485,7 @@

                                    consuming and exposing +a instance connected @@ -3695,14 +4495,30 @@

                                    Bluetooth.

                                  • Discover - + + Thing - -s +. +Note +Browser +implementations +SHOULD +use + + +s by sending a +namespace +object +such +as +navigator.wot +. +Node.js + discovery request to @@ -3711,11 +4527,21 @@

                                    registry.

                                  • Discover - + Thing -. - + +-like +runtimes +MAY +provide +the +API +object +through +the +require() + s filtered by @@ -3725,14 +4551,176 @@

                                    Thing Description - -s + + +or +import + +s

                                  • Discover Thing - -s + + +mechanism. +<span class="idlInterface" id="idl-def-wot" +data-idl="" data-title="WoT"><span class= +"idlSectionComment">// [SecureContext] +// [NamespaceObject] +<a data-no-default="" +data-link-for="" data-lt="" href="#dom-wot" class="internalDFN" +data-link-type="dfn"> {<span class= +"idlMethod" id="idl-def-wot-discover-filter" data-idl="" +data-title="discover" data-dfn-for="wot"> + <a data-link-for="" href="#dom-observable" class="internalDFN" +data-link-type= +"dfn"><a data-no-default="" +data-link-for="wot" data-lt= +"wot.discover()|wot.discover|discover()|discover" href= +"#dom-wot-discover" class="internalDFN" data-link-type= +"dfn">(<span class= +"idlParam">optional <a data-link-for="" +href="#dom-thingfilter" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlParamName">filter<span class="idlMethod" +id="idl-def-wot-fetch-url" data-idl="" data-title="fetch" +data-dfn-for="wot"> + <a href= +"https://heycam.github.io/webidl/#idl-promise">Promise<<a data-link-for="" +href="#dom-thingdescription" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="wot" data-lt= +"wot.fetch()|wot.fetch|fetch()|fetch" href="#dom-wot-fetch" class= +"internalDFN" data-link-type= +"dfn">(<span class= +"idlParam"><a href= +"https://heycam.github.io/webidl/#idl-USVString">USVString<span class="idlMethod" +id="idl-def-wot-consume-td" data-idl="" data-title="consume" +data-dfn-for="wot"> + <a data-link-for="" href="#dom-consumedthing" class="internalDFN" +data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="wot" data-lt= +"wot.consume()|wot.consume|consume()|consume" href= +"#dom-wot-consume" class="internalDFN" data-link-type= +"dfn">(<span class= +"idlParam"><a data-link-for="" href= +"#dom-thingdescription" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlParamName">td<span class="idlMethod" id= +"idl-def-wot-produce-model" data-idl="" data-title="produce" +data-dfn-for="wot"> + <a data-link-for="" href="#dom-exposedthing" class="internalDFN" +data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="wot" data-lt= +"wot.produce()|wot.produce|produce()|produce" href= +"#produce-method" class="internalDFN" data-link-type= +"dfn">(<span class= +"idlParam"><a data-link-for="" href= +"#dom-thingmodel" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlParamName">model<span class="idlMethod" +id="idl-def-wot-register-directory-thing" data-idl="" data-title= +"register" data-dfn-for="wot"> + <a href= +"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default="" +data-link-for="wot" data-lt= +"wot.register()|wot.register|register()|register" href= +"#dom-wot-register" class="internalDFN" data-link-type= +"dfn">(<span class= +"idlParam"><a href= +"https://heycam.github.io/webidl/#idl-USVString">USVString <a data-link-for="" +href="#dom-exposedthing" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlParamName">thing<span class="idlMethod" +id="idl-def-wot-unregister-directory-thing" data-idl="" data-title= +"unregister" data-dfn-for="wot"> + <a href= +"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default="" +data-link-for="wot" data-lt= +"wot.unregister()|wot.unregister|unregister()|unregister" href= +"#dom-wot-unregister" class="internalDFN" data-link-type= +"dfn">(<span class= +"idlParam"><a href= +"https://heycam.github.io/webidl/#idl-USVString">USVString <a data-link-for="" +href="#dom-exposedthing" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlParamName">thing +};<span class="idlTypedef" id="idl-def-thingfragment" +data-idl="" data-title="ThingFragment"> +typedef <a href= +"https://heycam.github.io/webidl/#idl-object">object<a data-no-default="" +data-link-for="" data-lt="" href="#dom-thingfragment" class= +"internalDFN" data-link-type= +"dfn"><span class= +"idlTypedef" id="idl-def-propertyfragment" data-idl="" data-title= +"PropertyFragment"> +typedef <a href= +"https://heycam.github.io/webidl/#idl-object">object<a data-no-default="" +data-link-for="" data-lt="" href="#dom-propertyfragment" class= +"internalDFN" data-link-type= +"dfn"><span class= +"idlTypedef" id="idl-def-actionfragment" data-idl="" data-title= +"ActionFragment"> +typedef <a href= +"https://heycam.github.io/webidl/#idl-object">object<a data-no-default="" +data-link-for="" data-lt="" href="#dom-actionfragment" class= +"internalDFN" data-link-type= +"dfn"><span class= +"idlTypedef" id="idl-def-eventfragment" data-idl="" data-title= +"EventFragment"> +typedef <a href= +"https://heycam.github.io/webidl/#idl-object">object<a data-no-default="" +data-link-for="" data-lt="" href="#dom-eventfragment" class= +"internalDFN" data-link-type= +"dfn"><span class= +"idlTypedef" id="idl-def-dataschema" data-idl="" data-title= +"DataSchema"> +typedef <a href= +"https://heycam.github.io/webidl/#idl-object">object<a data-no-default="" +data-link-for="" data-lt="" href="#dom-dataschema" class= +"internalDFN" data-link-type= +"dfn"><span class= +"idlTypedef" id="idl-def-securityscheme" data-idl="" data-title= +"SecurityScheme"> +typedef <a href= +"https://heycam.github.io/webidl/#idl-object">object<a data-no-default="" +data-link-for="" data-lt="" href="#dom-securityscheme" class= +"internalDFN" data-link-type= +"dfn"><span class= +"idlTypedef" id="idl-def-link" data-idl="" data-title="Link"> +typedef <a href= +"https://heycam.github.io/webidl/#idl-object">object<a data-no-default="" +data-link-for="" data-lt="" href="#dom-link" class="internalDFN" +data-link-type= +"dfn"><span class="idlTypedef" +id="idl-def-form" data-idl="" data-title="Form"> +typedef <a href= +"https://heycam.github.io/webidl/#idl-object">object<a data-no-default="" +data-link-for="" data-lt="" href="#dom-form" class="internalDFN" +data-link-type= +"dfn"><span class="idlTypedef" +id="idl-def-thingdescription" data-idl="" data-title= +"ThingDescription"> +typedef <a href= +"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default="" +data-link-for="" data-lt="" href="#dom-thingdescription" class= +"internalDFN" data-link-type= +"dfn"><span class= +"idlTypedef" id="idl-def-thingmodel" data-idl="" data-title= +"ThingModel"> +typedef (<a data-link-for="" href= +"#dom-thingfragment" class="internalDFN" data-link-type= +"dfn"> or <a data-link-for="" href= +"#dom-thingdescription" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlTypedefID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-thingmodel" class="internalDFN" data-link-type= +"dfn"> + +s filtered by semantic @@ -3752,26 +4740,133 @@

                                    timeout to the -discovery -process -after -which -it -is -stopped/suppressed. -

                                3. Conformance

                                - As well as sections marked as non-normative, all authoring guidelines, - diagrams, examples, and notes in this specification are non-normative. - Everything else in this specification is normative. -

                                - The key words MAY, MUST, SHOULD, and SHOULD NOT in this document - are to be interpreted as described in - BCP 14 - [RFC2119] - [RFC8174] when, and only when, they appear - in all capitals, as shown here. -

                                -This +discovery +process +after +which +it +is +stopped/suppressed. +

                                +ThingModel + + +3. + +Conformance + + +; + +

                                +

                                +As +well +as +sections +marked +as +non-normative, +all +authoring +guidelines, +diagrams, +examples, +and +notes +in +this +specification +are +non-normative. +Everything +else +in +this +specification +is +normative. +

                                +The +key +words + +MAY +, +MUST +, +and + +SHOULD + +in +this +document +are +to +be +interpreted +as +described +in + +BCP +14 + +[ + + +RFC2119 + + +] +[ + +Editor's +note + + +RFC8174 + +The +algorithms +for +the +WoT +methods +will +be +specified +later, +including +error +handling + + +] +when, + +and +security +considerations. + +only +when, +they +appear +in +all +capitals, +as +shown +here. + +

                                +

                                +The +ThingModel + +This specification describes the @@ -3782,23 +4877,22 @@

                                following classes of - + user agent - -( - + + +type +represents +either + +( + UA ). - -

                                Note -Browser -implementations -SHOULD -use -

                                -Due +

                                +Due to requirements of @@ -3818,13 +4912,9 @@

                                is a -namespace -object -such -as -navigator.wot -. -Node.js +ThingFragment +, +or distributed application, @@ -3835,8 +4925,9 @@

                                been covered by + a -generic +generic discovery API in @@ -3851,17 +4942,10 @@

                                classes for a - + UA - - --like -runtimes -MAY -provide -the - -that + +that implements this API, @@ -3880,88 +4964,40 @@

                                that uses this - API -object -through - -can +can introspect for the presence of - the -require() -or -import -mechanism. -// [SecureContext] -// [NamespaceObject] -

                                }; -typedef -typedef -typedef -typedef -typedef -typedef -typedef -typedef -typedef -typedef -( - - -ThingFragment -or - -consume() -, + ThingDescription -produce() +consume() +, +produce() -) +. +3.1 +The and -ThingModel - -discover() - +discover() -; -Editor's -note -The -algorithms -for - -methods +methods on - the - + WoT -methods -will -be -specified -later, -including -error -handling -and -security -considerations. - -API +API object - + in order to @@ -3970,78 +5006,14 @@

                                conformance class the - + UA - + implements. - -

                                -
                                +

                                -WoT +WoT Consumer - -UA -
                                -

                                -The - -Implementations -of -this -conformance -class -MUST -implement -the - - -ThingModel - -type -represents -either -a - - -ConsumedThing - -ThingFragment - - -, -or -a - -interface -and -the - - -ThingDescription - -consume() - - -method -on -the - -WoT -API -object - -. -

                                -3.1 -The -discover() - -
                                -
                                - -WoT -Producer method @@ -4077,15 +5049,20 @@

                                this conformance class -MUST + +MUST + implement +the + + ThingFilter - -ExposedThing +ConsumedThing + . Returns @@ -4123,14 +5100,14 @@

                                argument of type - - -USVString +USVString representing a -ThingDescription -produce() + +ThingDescription + +consume() method @@ -4149,71 +5126,118 @@

                                + +WoT +Producer + + +enumeration + + +UA + + +<span class="idlTypedef" id= +"idl-def-discoverymethod" data-idl="" data-title= +"DiscoveryMethod">typedef <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" +data-link-for="" data-lt="" href="#dom-discoverymethod" class= +"internalDFN" data-link-type= +"dfn"> + +
                                +
                                +

                                +Implementations +of +this +conformance +class + +MUST + +implement + + +DiscoveryMethod + +ExposedThing + + + +; + + +interface +and +the + +produce() + +method +on +the + +WoT +API +object +.

                                WoT Discovery - - -enumeration -typedef -DOMString - - -UA - - + +UA +

                                -Implementations +Implementations of this conformance class -MUST + +MUST + implement the - + + DiscoveryMethod - -ThingDiscovery +ThingDiscovery + -; +represents interface and -the - - -DiscoveryMethod - -discover() - - -represents - -method -on the discovery type to - -WoT + +discover() + +method +on +the + +WoT API object .

                                These conformance classes -MAY - + +MAY + be used: @@ -4221,28 +5245,18 @@

                                in a single - + UA . -

                                "any" -does -not -provide -any -restriction -"local" -

                                +

                                +

                                This specification can be used - for -discovering -Thing - -implementing +implementing the WoT Scripting @@ -4257,10 +5271,28 @@

                                are specified in -[WEBIDL]. +[ + +"any" +does +not +provide +any +restriction + + +WEBIDL + +"local" +for +discovering +Thing + + +].

                                The - + UA @@ -4280,6 +5312,11 @@

                                or connected +to +the +device +by +wired in a @@ -4288,11 +5325,19 @@

                                environment, such as - + Node.js - + or -in +wireless +means. +"directory" +for +discovery +based +on + +in small embedded runtimes. @@ -4303,28 +5348,34 @@

                                ECMAScript executed in -a -browser - -to -implement -the -device +a +service +provided by -wired -APIs +browser +to +implement +the +APIs defined in this document -MUST + +MUST + implement them in + a -manner +Thing +Directory +. + +manner consistent with the @@ -4336,53 +5387,57 @@

                                Web IDL specification -[WEBIDL]. +[ + +"multicast" +for +discovering +Thing + + +WEBIDL + + +s + + +].

                                Implementations that use TypeScript - or -wireless -means. -"directory" -for -discovery -based -on - -ECMAScript -in +ECMAScript -a -service -provided -by - -runtime +in +a +runtime to implement + the -APIs +device's +network +by +using + +APIs defined in this document -MUST + +MUST + implement them in a -Thing -Directory -. -"multicast" -for -discovering -Thing -s +supported +multicast +protocol. manner consistent @@ -4391,119 +5446,312 @@

                                TypeScript Bindings defined - in the -device's -network -by -using -a -supported -multicast -protocol. - -TypeScript +TypeScript specification -[TYPESCRIPT]. -

                                3.1.2 -

                                4. +[ + +TYPESCRIPT + +]. +

                                +

                                +
                                +

                                +3.1.2 + + +4. + The + + ThingFilter - ThingDescription + dictionary type -

                                typedef object ThingDescription;

                                + + +The + + +

                                "idl-def-thingdescription" data-title=
+"ThingDescription">typedef object 
+
+
+ThingFilter
+
+ThingDescription
+
+
+
+dictionary
+that
+represents
+the
+constraints
+for
+discovering
+Thing
+s
+as
+key-value
+pairs.
+<span class="idlDictionary" id=
+"idl-def-thingfilter" data-idl="" data-title=
+"ThingFilter">dictionary <span class=
+"idlDictionaryID"><a data-no-default="" data-link-for="" data-lt=""
+href="#dom-thingfilter" class="internalDFN" data-link-type=
+"dfn"> {<span class="idlMember"
+id="idl-def-thingfilter-method" data-idl="" data-title="method"
+data-dfn-for="thingfilter">
+  (<a data-link-for="" href="#dom-discoverymethod" class=
+"internalDFN" data-link-type=
+"dfn"> or <a href=
+"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default=""
+data-link-for="thingfilter" data-lt="" href=
+"#dom-thingfilter-method" class="internalDFN" data-link-type=
+"dfn"> = <span class=
+"idlMemberValue">"any"<span class="idlMember" id=
+"idl-def-thingfilter-url" data-idl="" data-title="url"
+data-dfn-for="thingfilter">
+  <a href=
+"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default=""
+data-link-for="thingfilter" data-lt="" href="#dom-thingfilter-url"
+class="internalDFN" data-link-type=
+"dfn"><span class="idlMember"
+id="idl-def-thingfilter-query" data-idl="" data-title="query"
+data-dfn-for="thingfilter">
+  <a href=
+"https://heycam.github.io/webidl/#idl-USVString">USVString<a data-no-default=""
+data-link-for="thingfilter" data-lt="" href=
+"#dom-thingfilter-query" class="internalDFN" data-link-type=
+"dfn"><span class="idlMember"
+id="idl-def-thingfilter-fragment" data-idl="" data-title="fragment"
+data-dfn-for="thingfilter">
+  <a data-link-for="" href="#dom-thingfragment" class="internalDFN"
+data-link-type=
+"dfn"> <span class=
+"idlMemberName"><a data-no-default="" data-link-for="thingfilter"
+data-lt="" href="#dom-thingfilter-fragment" class="internalDFN"
+data-link-type="dfn">
+};
+
+;
+
+
+
                                +

                                The -ThingFilter +method +property +represents +the +discovery +type +that +should +be +used +in +the +discovery +process. +The +possible +values +are Represents a - + Thing Description ( - + TD ) as -defined -in -[WOT-TD]. -It -is -expected -to -be + +defined +by +the +DiscoveryMethod + +in +[ + + +WOT-TD + + +enumeration +that +MAY + + +]. +It +is +expected +to + +be +extended +by +string +values +defined +by +solutions +(with +no +guarantee +of +interoperability). +The +url +property +represents +additional +information +for +the +discovery +method, +such +as +the +URL +of +the +target +entity +serving +the +discovery +request, +for +instance + a - -parsed +Thing +Directory + + +parsed JSON object -dictionary +(if +method -that -represents -the -constraints -for -discovering +that + +is +"directory" +) +or -is -validated +validated using - + JSON schema validation -.

                                4.1 +.

                                +4.1 + Fetching -a -Thing -Description -

                                -Fetching a - -TD - +Thing +(otherwise). +The + +Description + +query + -s +property +represents -given +

                                +

                                +Fetching + a -URL +query +string +accepted +by +the +implementation, +for +instance + + +TD + +given + +a +SPARQL +or +JSON +query. +Support +may + +URL should + be -done +implemented +locally +in + +done with an external method, such - as -key-value -pairs. + +the +WoT +Runtime -the - -Fetch + +Fetch API - + + or +remotely +as + a -HTTP +service +in + +HTTP client library, which @@ -4515,70 +5763,100 @@

                                specifying fetch details. +

                                +Example + +1 +: +Fetching -

                                -( - - - -

                                }; -

                                -
                                -
                                - Example 1: Fetching a Thing Description - 
                                        try {
-          let res = await fetch('https://tds.mythings.biz/sensor11');
-          // ... additional checks possible on res.headers
-          let td = await res.json();
-          let thing = new ConsumedThing(td);
-          console.log("Thing name: " + thing.getThingDescription().title);
-        } catch (err) {
-          console.log("Fetching TD failed", err.message);
-        }
-
                                -
                                -

                                4.2 -Expanding a Thing -Description -

                                -The -method -property +Directory +. +The + +Description + +fragment + + +

                                "hljs-keyword">try {
+  let res = 
+"hljs-keyword">await fetch('https://tds.mythings.biz/sensor11');
+  
+"hljs-comment">// ... additional checks possible on res.headers
+  let td = 
+"hljs-keyword">await res.json();
+  let thing = 
+"hljs-keyword">new ConsumedThing(td);
+  console.log(
+"hljs-string">"Thing name: " + thing.getThingDescription().title);
+} catch (err) {
+  console.log(
+"hljs-string">"Fetching TD failed", err.message);
+}
+
+
+property
 represents
-the
-discovery
-type
 
-Note
+
                                + +
                                +
                                +

                                + +4.2 + +Expanding +a +Thing +Description + +ThingFragment + + +

                                +

                                +Note that -should -be +[ + +WOT-TD + + +dictionary used -in +for +matching +property +by +property +against +discovered -[WOT-TD] + +] allows using a shortened - + Thing -Description - -by +Description -the -discovery -process. -The -possible + +s. -means +by +the +means of - + defaults and @@ -4589,30 +5867,37 @@

                                them with default - values -specified +specified in -[WOT-TD] +[ + +WOT-TD + +] for the properties that - are -not +not explicitly - defined -by - -in +in a given - + TD -.

                                -To +. +

                                +
                                +

                                +The +discover(filter) +method +MUST + +To expand a @@ -4621,58 +5906,66 @@

                                given td -, +, run - the -DiscoveryMethod -enumeration -that -MAY -be -extended -by -string - -following +following steps: -
                                1. -For +

                                  +
                                    +
                                  1. +If +invoking +discover() + +For each item in the - + TD default - values - -table + +table from -[WOT-TD], +[ + +WOT-TD + +], if the term + is not - -defined -by -solutions -(with -no -guarantee -of -interoperability). +allowed +for -in - +defined +in + td , add + the -term +current +scripting +context +for +security +reasons, +throw +SecurityError +and +terminate +these +steps. + +term definition with the @@ -4680,22 +5973,46 @@

                                    value specified in -[WOT-TD]. -

                                4.3 +[ + +WOT-TD + +]. + + +Return +an + + + +

                                +
                                +

                                + +4.3 + Validating a Thing Description -

                                -The -url -property -represents -additional -information -for + +Observable + + + +

                                +The +[ + +WOT-TD + + +obs +and +execute -[WOT-TD] + +] specification defines how @@ -4712,1088 +6029,1268 @@

                                expects the -discovery -method, -such +next +steps +in +parallel +. +If + + + +obs.subscribe(handler, +errorHandler, +complete) - ThingDescription - -objects + + +is +called, +execute + + +objects be validated before used - as -parameters. +parameters. This specification defines a basic - + TD - + validation as follows. -

                                +

                                To - + validate a TD - + given - + td -, +, run the -URL +following +sub-steps: -following -steps: -

                                1. +steps: +

                                  +
                                    +
                                  1. If - -td - +the +first +argument + + +handler + +td + + is not -an +defined +or +it +is +not +a +function, + +an object, + throw - -"TypeError" - + +TypeError + +"TypeError" + + and terminate -these +the +algorithm. +Otherwise +configure +handler +to +be +invoked +when +a +discovery +hit +happens. + +these steps. -
                                  2. -If -any +
                                    3. +
                                  3. +If +any of + the -target -entity -serving -the -discovery -request, +second +argument mandatory properties defined in -[WOT-TD] - +[ + +WOT-TD + +] for -instance -a - - + Thing -Directory - - -(if - -that + +that don't have - + default definitions are missing from - -td -, -throw + +errorHandler +is +defined, +but +it +is +not +a +function, + +td +, +throw -method +TypeError "TypeError" -is - -and +and terminate these steps. -
                                  4. +Otherwise +if +defined, +save +it +to +be +invoked +in +error +conditions. + +
                                    5. +
                                  5. If - -JSON +the +third +argument + + +JSON schema validation fails on - -td -, -throw + +onComplete +is +defined, +but +it +is +not +a +function, + +td +, +throw -"directory" +TypeError + +"TypeError" + + +and +terminate +these +steps. +Otherwise +if +defined, +save +it +to +be +invoked +when +the +discovery +process +finished +for +other +reasons +than +having +been +canceled. + +
                                    6. +If +filter.query +is +defined, +pass +it +as +an +opaque +string +to +the +underlying +implementation +to +be +matched +against +discovered +items. -"TypeError" - - -) -or +
                                  +
                                +

                                +
                                +
                                +

                                + +5. + +The +underlying +implementation +is +responsible +to +parse +it +e.g. +as a +SPARQL +or +JSON +query +and +match +it +against +the Thing -(otherwise). - -and -terminate -these -steps. -

                                5. -The -query +Description WoT API object - - -property -represents + + +s +found +during -

                                + +

                                Defines + the -API +discovery +process. +If +queries +are +not +supported, +implementations +SHOULD +throw + +API entry point exposed as a -query -string -accepted -by - -singleton +NotSupported +error and -contains - -the -implementation, -for -instance +terminate +these +steps. +If +filter.fragment +is +defined, -API -methods. -

                                5.1 -The - -WOT - -interface -

                                      [SecureContext, Exposed=(Window,Worker)]
-      interface WOT {
-        // methods defined in UA conformance classes
-      };
                                Note

                                -Browser -implementations -should -use +singleton -a -SPARQL -or -JSON -query. -Support +and +if +it -namespace -object -such -as - -navigator.wot -. -Standalone -runtimes - -may -be -implemented -locally -in +contains +other +properties +than -expose - the -WoT -Runtime - -API -object -through -mechanisms -like - -require() - - -or -remotely -as -a -service +ones +defined in -a -Thing -Directory - -import - -. -

                                5.2 +API +methods. +

                                +5.1 + The -fragment - - -consume() - - -property -represents - -method -

                                      partial interface WOT {
-        Promise<ConsumedThing> consume(ThingDescription td);
-      };
                                -Belongs -to -the - -WoT -Consumer - -conformance -class. -Expects -an - -td - -argument -and -returns - -a + + ThingFragment - -Promise - - -dictionary -used -for -matching -property -by -property -against -discovered -Thing - -that -resolves -with -a - -ConsumedThing - - -s. - -object -that -represents -a -client -interface -to -operate -with -the - -Thing -. -The -discover(filter) - -method -MUST -run -the -following -steps: -
                                  -
                                1. -Return -a - -Promise - -promise - -and -execute -the -next -steps - -in -parallel -.
                                2. -If -invoking -discover() - -this -method +WOT -is -not -allowed -for -the -current -scripting -context -for -security -reasons, -throw - -reject - -promise - -with + +, +throw + + +interface +

                                
+"idl-def-wot" data-title="WOT">[SecureContext, Exposed=(Window,Worker)]
+interface WOT {
+  // methods defined in UA conformance classes
+
+};
+
                                +Note +

                                +Browser +implementations +should +use +a +namespace +object +such +as -SecurityError - +TypeError and terminate these steps. - -

                              8. -Return -an -Observable +Otherwise +save -Run +navigator.wot +. +Standalone +runtimes +may +expose + the - -validate -a -TD +API +object +for +matching +the +discovered +items +against +it. +Request +the +underlying +platform +to +start +the +discovery +process, +with +the +following +parameters: +If +filter.method +is +not +defined + +through +mechanisms +like + +require() + +or +the +value +is + + +import +.

                                9. +5.2 + +The + + +"any" +, +use +the +widest +discovery + +consume() + +method +supported +by + + -steps -on +

                                +
                                "idl-def-wot-partial-1" data-title=
+"WOT">partial interface WOT {
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<ConsumedThing> consume(ThingDescription td);
+};
+

                                +Belongs +to + +the +underlying +platform. +Otherwise +if + + +WoT +Consumer + +conformance +class. +Expects +an -obs +filter.method td -. -If -that -throws, -reject - -promise -with +is +"local" +, +use the -error - -and -execute +local +Thing +Directory -terminate -these -steps. -

                              9. -Let - -thing - -be +argument +and +returns a -new - -ConsumedThing - -object -constructed -from - -td -.
                              10. -Set -up + +Promise -the -next -steps + +for +discovery. +Usually - -WoT -Interactions - -based -on -introspecting - -td - -as -explained - +that +defines +Thing +s +deployed in -parallel - -[WOT-TD] -and -[WOT-PROTOCOL-BINDINGS]. -Make -a -request -to the -underlying -platform +same +device, +or +connected to -initialize the - -Protocol -Bindings +device +in +slave +mode +(e.g. +sensors +connected +via +Bluetooth +or + +resolves +with -. -The -details -are -private -to +a +serial +connection). +Otherwise +if +filter.method +is + + + +"directory" +, +use the -implementations -and -out -of -scope -of -this -specification. - -
                                11. -
                              11. -If +remote +Thing +Directory -Resolve - -promise - -with - -thing -.

                                12. 5.3 -The - -produce() - -method -

                                      partial interface WOT {
-        Promise<ExposedThing> produce(ThingDescription td);
-      };
                                -Belongs -to +ConsumedThing + + +specified +in +filter.url +. +Otherwise +if +filter.method +is +"multicast" +, +use +all the - -WoT -Producer - -conformance -class. -Expects -a - - -obs.subscribe(handler, -errorHandler, -complete) +multicast +discovery +protocols +supported +by +the +underlying +platform. +Whenever -td +object +that +represents - -is -called, -execute - -argument -and -returns a - -Promise - -that -resolves -with -an - -ExposedThing - -object -that -extends - -ConsumedThing - +new +item +td +is +discovered +by + +client +interface +to +operate with -a -server -interface, -i.e. + the -ability -to -define -request -handlers. +underlying +platform, + + +Thing +. The method -MUST + +MUST + run - the following sub-steps: steps: - +

                                1. If -the -first -argument +filter.query +is +defined, +check +if +td +is Return + a - -Promise +match +for +the +query. +The +matching +algorithm +is +encapsulated +by +implementations. +If +that +returns +false +, +discard + + +Promise -handler +td promise -is -not -defined -or -it -is -not -a -function, -throw -TypeError - and -terminate +continue execute the -algorithm. -Otherwise -configure -handler -to -be -invoked -when -a -discovery -hit -happens. +discovery +process. next steps - + in parallel .
                                2. If -the -second -argument -errorHandler +filter.fragment + +invoking +this +method + is -defined, -but -it +defined, + +not +allowed + +for +each +property +defined +in +it, +check +if +that +property +exists +in + +the +current +scripting +context +for +security +reasons, +reject + + +td + +promise + + +and +has +the +same +value. +If +this +is + +with + + +false + +SecurityError + + +in +any +checks, +discard +td + +and +continue +the +discovery +process. + +terminate +these +steps. + +
                                  3. +
                                3. +Otherwise +if + +Run +the + +validate +a +TD + +steps +on + + +td +has +not +been +discarded +in +the +previous +steps, +invoke +the + +. +If +that +throws, +reject + + +handler -invoking -this -method +promise -is -not -a -function, -throw + +function -allowed -for -the -current -scripting -context -for -security -reasons, -reject - -promise - with - - -TypeError +td +as +parameter. +Whenever +an +error +occurs +during -SecurityError +the +discovery +process, + +error - and -terminate +if + +terminate these steps. -Otherwise -if +
                                4. +Let + + +errorHandler + +thing + + +is defined, -save +invoke it +with +an +argument +of +type +Error +whose +message +property +is +set to -
                                  5. -
                                5. -Let - -thing - -be -invoked -in +be +a +new + + +UnknownError + +ConsumedThing + + +unless +there +was +an error -conditions. +code +provided +by +the +Protocol +Bindings +, +in +which +case +set +it +to +that +value. -a -new - -ExposedThing - -object + +object constructed -with +from td .
                                6. -If +When -Resolve - -promise - -with - -thing -.

                                5.4 -The - -discover() - -method -

                                      partial interface WOT {
-        ThingDiscovery discover(optional ThingFilter filter = null);
-      };
                                -Belongs -to +Set +up the -third -argument +discovery +process +is +finished, - + WoT -Discovery - -conformance -class. -Starts -the -discovery -process -that -will -provide - -ThingDescription +Interactions -objects -for - -Thing -Description +based +on +introspecting + +td -s -that -match -an -optional - - -onComplete - -filter +as +explained +in +[ + +WOT-TD + +] - -is +and +if +onComplete +is defined, -but +invoke it +run +the +cancel +discovery -argument. -The +[ + +WOT-PROTOCOL-BINDINGS + + +steps. +When +the +obs.unsubscribe() method -MUST +is +called, run the following +cancel +discovery steps: -
                                1. -If -invoking -this -method - -is -not -a -function, +Request -allowed -for -the -current -scripting -context -for -security -reasons, + +]. +Make +a +request +to -throw - -TypeError +the +underlying +platform +to +stop -SecurityError +initialize - -and -terminate -these -steps. -Otherwise +the +discovery +process. +If +this +returns +an +error, +or if -defined, -save it -to -be -invoked +is +not +possible, +for +instance when -the discovery -process -finished -for -other -reasons -than -having -been -canceled. +is +based +on +open +ended +multicast +requests, + + +Protocol +Bindings +. +The +details +are +private +to + +the +implementation +SHOULD +discard +subsequent +discovered +items. +implementations +and +out +of +scope +of +this +specification. +
                                2. -If +Set -Construct -a - -ThingDiscovery - -object +Resolve -filter.query +obs.closed -discovery +promise -is -defined, -pass -it -as -an -opaque -string -to +to +false +. with -filter -.
                                3. -Invoke - -the -underlying -implementation +thing +. +
                                  4. +
                                +
                                +
                                +
                                +

                                +3.2 + + +5.3 + +The + + +fetch() - -discovery.start() - -method. -
                              12. -Return - -discovery -.

                                13. -Refer +produce() + + +method + + +

                                +
                                "idl-def-wot-partial-2" data-title=
+"WOT">partial interface WOT {
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<ExposedThing> produce(ThingDescription td);
+};
+
                                +

                                +Accepts +an +url +argument +of +type +USVString +that +represents + +Belongs to -the - -ThingDiscovery - -section -for -how -discovery -should +the + +WoT +Producer + +conformance +class. +Expects -be -matched -against -discovered -items. +a +URL +(e.g. +"file://..." +or -implemented. -

                                6. -The -underlying -implementation -is -responsible + +"https://..." - -ConsumedThing - -interface -

                                -Represents -a -client -API +td -to -parse -it -e.g. -as + +) -operate +argument -a -SPARQL -or -JSON -query and -match -it -against +returns +a + +Promise + +that +resolves +with +a - -Thing -. -Belongs -to +an + + +ThingDescription + +ExposedThing -the - -WoT -Consumer - -conformance -class. -

                                      [SecureContext, Exposed=(Window,Worker)]
-      interface ConsumedThing {
-        constructor(ThingDescription td);
-        Promise<any> readProperty(DOMString propertyName,
-                                  optional InteractionOptions options = null);
-        Promise<PropertyMap> readAllProperties(optional InteractionOptions options = null);
-        Promise<PropertyMap> readMultipleProperties(
-                                  sequence<DOMString> propertyNames,
-                                  optional InteractionOptions options = null);
-        Promise<void> writeProperty(DOMString propertyName,
-                                    any value,
-                                    optional InteractionOptions options = null);
-        Promise<void> writeMultipleProperties(PropertyMap valueMap,
-                                    optional InteractionOptions options = null);
-        Promise<any> invokeAction(DOMString actionName,
-                                    optional any params = null,
-                                    optional InteractionOptions options = null);
-        Promise<void> observeProperty(DOMString name,
-                                    WotListener listener,
-                                    optional InteractionOptions options = null);
-        Promise<void> unobserveProperty(DOMString name);
-        Promise<void> subscribeEvent(DOMString name,
-                                    WotListener listener,
-                                    optional InteractionOptions options = null);
-        Promise<void> unsubscribeEvent(DOMString name);
-        ThingDescription getThingDescription();
-      };
-      dictionary InteractionOptions {
-        object uriVariables;
-      };
-      typedef object PropertyMap;
-      callback WotListener = void(any data);

                                6.1 -Constructing - -ConsumedThing -

                                -After - -fetching - -a - -Thing -Description + -s -found -during +(a +serialized +JSON-LD +document +of +type -as -a -JSON -object, -one -can -create -a - -ConsumedThing - -object. -

                                -To -create - -ConsumedThing - -with +object +that +extends + + +USVString + +ConsumedThing -the -discovery -process. -If -queries -are -not -supported, -implementations -SHOULD -throw + +). - -ThingDescription - -td -, + +with +a +server +interface, +i.e. +the +ability +to +define +request +handlers. + +The +fetch(url) + +method + +MUST + run the following steps: -
                                1. -Run -the - -expand - +

                                  +
                                    +
                                  1. +Return a -NotSupported - -TD - + +Promise + + +promise + +and +execute +the +next steps -on - -td -. + +in +parallel +. +
                                    2. +
                                  2. If -that -fails, -re-throw -the +invoking +fetch() + +this +method -error +is +not +allowed +for +the +current +scripting +context +for +security +reasons, +reject + +promise + +with + +SecurityError + and terminate these @@ -5801,1090 +7298,1407 @@

                                  3. If +the +argument Let -filter.fragment +url thing - -be -a -new - -ConsumedThing - -object. -
                                  4. -Let -|td| -be -an -internal -slot -of - -thing is -defined, +not -and -if -it -contains -other -properties -than +be + +a +URL, +reject -let +new + +ExposedThing + +object +constructed +with td - -be -its -value. -
                                  5. -Return - -thing -.

                                6.2 +.
                              13. +Resolve + + +promise + +with + +thing +.

                                14. +5.4 + The - -getThingDescription() - -method -

                                -Returns + + +TypeError + +discover() -the -ones -defined -in -ThingFragment -, -throw -TypeError -and + +and terminate these steps. -Otherwise -save - -internal -slot -|td| -of - -the - -ConsumedThing - -object -for -matching +Make +a +request -that -represents + +method +

                                
+"idl-def-wot-partial-3" data-title=
+"WOT">partial interface WOT {
+  
+"internalDFN" data-link-type=
+"idl">ThingDiscovery discover(optional ThingFilter filter = null);
+};
+

                                +Belongs -the -discovered -items -against - - -Thing -Description - -of -the - -ConsumedThing -. -Applications -may -consult -the - -Thing - -metadata -stored -in -|td| -in -order to -introspect -its -capabilities -before -interacting -with - -it. -Request - -

                                6.3 -The - -InteractionOptions - -dictionary -

                                -Holds - +fetch the -underlying -platform - -interaction -options -that -need -to -be -exposed -for -application -scripts -according - -to -start +content +of +url +as +described +by the -discovery -process, -with +Protocol +Bindings - -Thing -Description -. -In -this -version -of + +WoT +Discovery + +and +wait +for the -following -parameters: -If -filter.method -is -not - -specification -only -URI -template -variables -are -used, -represented -as - -parsed -JSON -objects - -defined -or -the -value -is -"any" -, -use +reply. +Implementations +encapsulate -in -[WOT-TD]. -

                                Editor's note

                                -The -support -for -URI -variables -comes -from +conformance +class. +Starts the -widest -discovery -method -supported +fetching -need -exposed +discovery -by -the -underlying -platform. -Otherwise -if -filter.method -is -"local" -, +process +and +the +accepted +media +types +(such +as -[WOT-TD] -to -be -able -to -describe -existing - -TD - -s -that - -use -the -local +that +will +provide + + +application/td+json -them, -but -it -should -be -possible -to -write +ThingDescription + + +), +as +far +as a - -Thing -Directory +valid -Description + +objects +for + +Thing +Description -for -discovery. -Usually +can +be +obtained +as +defined +in +[ +WOT-TD +]. +Let +s that -defines -Thing - -would -use - -Action +match +an +optional - -s -deployed -in + +td -for -representing +filter + +be the -same -device, -or -connected -to +Thing +Description +string-serialized +from +the +returned +content, +as +specified +in -interactions -that -need -URI -variables -and -represent +argument. +The +method + +MUST + +run the -device -in -slave -mode -(e.g. -sensors -connected -via -Bluetooth -or -a -serial -connection). -Otherwise -if -filter.method -is -"directory" -, -use +Thing +Description +serialization +. -URI -variables -as -parameters -to +following +steps: +

                                  +
                                1. +If +there +was +an +error +during + +invoking +this +method +is +not +allowed +for the -remote -Thing -Directory +request, +reject +promise +with +an +Error +object +error +with - -Action +current +scripting +context +for +security +reasons, +throw - -specified + +error.message -and +SecurityError -in -that -case -that -could -be -encapsulated + +set +to +the +error +code +seen by the -implementations +Protocol +Bindings + and -the - - -filter.url -. -Otherwise -if -filter.method +terminate +these +steps. +
                                  2. +
                                2. +Otherwise +resolve + +Construct +a + +ThingDiscovery + +object + + +promise -options +discovery -is -"multicast" -, -use -all +with + +td +and +terminate +these +steps. -parameter -could -be -dismissed -from - +filter +.
                                3. +Invoke the -multicast + +discovery.start() + +method. +
                                4. +Return + discovery -protocols -supported - -methods -exposed - -by -this -API. -

                                6.4 -The - -PropertyMap - -type -

                                -Represents -a -map -of - -Property - -names -as -strings +. + + + +

                                +Refer to -a -value -that - the -underlying -platform. -Whenever + +ThingDiscovery + +section +for +how +discovery +should +be +implemented. +

                                +
                                +
                                +
                                +

                                +3.3 + + +6. + +The + + +consume() - -Property - -can -take. -It -is -used -as +ConsumedThing -a -new -item + + +method -property -bag -for -interactions -that -involve -multiple - -Properties - -at -once. -

                                Editor's note

                                -It -could -be -defined -in -Web -IDL -(as -well -as - -ThingDescription - -) -as +interface + + +

                                +

                                +Accepts +an + +Represents a - -maplike - -interface -from - -string - +client +API to - -any -.

                                6.5 -The - -readProperty() - -method -

                                -Reads +operate a - -Property + +Thing +. +Belongs +to +the + +WoT +Consumer -value. -Takes -a -string -argument +conformance +class. +

                                
+"idl-def-consumedthing" data-title="ConsumedThing">[SecureContext, Exposed=(Window,Worker)]
+interface ConsumedThing {
+  
+"dom-consumedthing-constructor" data-idl="constructor" data-title=
+"constructor" data-dfn-for="ConsumedThing" data-lt=
+"ConsumedThing.constructor()|ConsumedThing.constructor|constructor()|constructor">constructor(ThingDescription td);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<any> readProperty(DOMString propertyName,
+                            optional InteractionOptions options = null);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<PropertyMap> readAllProperties(optional InteractionOptions options = null);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<PropertyMap> readMultipleProperties(
+                            
+"" data-type="dfn" href=
+"https://heycam.github.io/webidl/#idl-sequence">sequence<DOMString> propertyNames,
+                            optional InteractionOptions options = null);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> writeProperty(DOMString propertyName,
+                              
+data-link-type="dfn" href=
+"https://heycam.github.io/webidl/#idl-any">any value,
+                              optional InteractionOptions options = null);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> writeMultipleProperties(PropertyMap valueMap,
+                              optional InteractionOptions options = null);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<any> invokeAction(DOMString actionName,
+                              optional any params = null,
+                              optional InteractionOptions options = null);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> observeProperty(DOMString name,
+                              
+"#dom-wotlistener" class="internalDFN" data-link-type=
+"idl">WotListener listener,
+                              optional InteractionOptions options = null);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> unobserveProperty(DOMString name);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> subscribeEvent(DOMString name,
+                              
+"#dom-wotlistener" class="internalDFN" data-link-type=
+"idl">WotListener listener,
+                              optional InteractionOptions options = null);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> unsubscribeEvent(DOMString name);
+  
+"internalDFN" data-link-type=
+"idl">ThingDescription getThingDescription();
+};
+dictionary InteractionOptions {
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-object">object uriVariables;
+};
+typedef object PropertyMap;
+callback WotListener = void(
 
-
+
 td
 
-propertyName
+any
 
-
-is
-discovered
-by
-the
-underlying
-platform,
+
+argument
+of
+type
 
-and
-and
-an
-optional
-
-InteractionOptions
-
-options
-
-argument.
-It
+
+
+
+data
+
+);
+

                                + +6.1 + +Constructing + + +ThingDescription + +ConsumedThing + + + + +and returns + +

                                +

                                +After + +fetching + a - -Property + +Thing +Description -value -represented as - -any - -type. -The -method -MUST +a +JSON +object, +one +can +create +a + + +ConsumedThing + + +object +instantiated +based +on +parsing +that +description. + +object. + +

                                +
                                +

                                +The + +To +create + + +consume(td) + +ConsumedThing + +method +must + + +with +the + +ThingDescription + +td +, run the following -sub-steps: - -steps: - +steps: +

                                1. If -filter.query -is -defined, -check -if + +Run + +the +argument td is +not +a +string, +throw -Return + +expand a -match -for +TypeError +and +terminate +these +steps. +Let +stub +be the -query. -The -matching +result +of +running +the + +TD +parsing algorithm -is -encapsulated -by -implementations. -If -that -returns -false -, -discard - -Promise - - -td + +with -promise +steps +on - -and -continue + +td +as +argument. -execute +. +If +that +throws +an +error, + +fails, +re-throw the -discovery -process. - -next -steps - -in -parallel -. +error +and +terminate +these +steps.
                                2. -If -filter.fragment +If -invoking -this -method +Let -is -defined, + +stub -not -allowed +thing -for -each + +does +not +have +an +own property +that +is defined in -it, -check -if +ThingFragment +with +a +default +value, +add that property -exists -in +and +value +to +stub +. +Create -the -current -scripting -context -for -security -reasons, -reject +be + +a +new + + +ConsumedThing + + +object + +object. +
                                3. +Let +| + +td + +| +be +an +internal +slot +of -td +thing + +initialized +from -promise +and +let + + +stub + +td -and -has -the -same +that +implements + +be +its value. -If -this -is +
                                4. +Return + +thing +.

                                + +6.2 + +The + + +Observable -with +getThingDescription() + + +. +Add + + +method +

                                +Returns + +the +read() +and +write() +methods +to + +internal +slot +| + +td + +| +of + +the + + +ThingProperty + +ConsumedThing + + + +elements +so + +object + +that +they +make +requests +to +access + +represents + +the +remote + + +Thing +Description + + +s +and +wait +for +the +reply, +as +defined +by + +of +the +Protocol +Bindings +. +Also, +all + + -false +ThingProperty -SecurityError +ConsumedThing -in -any -checks, -discard -td - -and -continue +. +Applications +may +consult the -discovery -process. - -terminate -these -steps. + +Thing - -

                              14. -Otherwise -if + +elements +SHOULD +implement + +metadata +stored +in +| + td -has -not -been -discarded + +| in +order +to +introspect +its +capabilities +before +interacting +with +it. +

                                15. +Observable -Make + +6.3 + +The + +, +i.e. +define a -request -to - -the -previous -steps, -invoke -underlying -platform -(via -the - -Protocol -Bindings - -) -to -retrieve -the -value -of + +subscribe() + +InteractionOptions + +method + + +dictionary +

                                +Holds the - -Property - -given -by +interaction +options - -handler +that +should +make +request -propertyName +need +to +be +exposed +for +application +scripts +according - -function - -with -optional -URI -templates +to +observe +the given -in - - -td +Properties as -parameter. - -options.uriVariables -. - -

                              15. -Whenever -an -error -occurs -during +defined +by -If - the -discovery -process, -and -if - -request -fails, -reject - - -errorHandler +Protocol +Bindings -promise + +Thing +Description - -is -defined, -invoke -it +. +Add -with -an -argument +In +this +version of -type -Error -whose -message -property -is -set -to -UnknownError -unless -there -was -an - -the -error -code -provided -by +the +invoke() +methods +to -received +specification +only +URI +template +variables +are +used, +represented +as + +parsed +JSON +objects + +defined +in +[ + +WOT-TD + +]. +

                                +Editor's +note +

                                +The +support +for +URI +variables +comes from the - -Protocol -Bindings -, -in -which -case -set -it -to -that -value. +need +exposed +by +[ + +ThingAction - -and -terminate -these -steps. + +WOT-TD + + +] +to +be +able +to +describe +existing + +TD -

                                16. -
                              16. -When -the -discovery -process -is -finished, -and -if + +elements +so -Let +s - -onComplete +that +they +make +requests -value +use +them, +but +it +should +be +possible - -is -defined, +to +the +remote + +write +a + +Thing +Description + + +to invoke -it -run +its +actions, +as +defined +by -be +that +would +use + +Action + +s +for +representing the -cancel -discovery -steps. +Protocol +Bindings +. +Add -result -of -the -request. +interactions +that +need +URI +variables +and +represent -
                                17. -
                              17. -When the -obs.unsubscribe() +subscribe() method -is -called, -run -Run +URI +variables +as +parameters -the -following -cancel -discovery +to +all +ThingEvent - -validate -Property -value +the + +Action - -steps: - -sub-steps -on - -value -: -
                                  -
                                1. -Request + +elements +so -Based -on +and +in +that +they +make +requests +to +subscribe +to the -underlying -platform +events +defined - -DataSchema -definition -, -value - -MUST +case +that +could be -a -JSON -value -and -comply +encapsulated -to -stop - +by the -discovery -process. -If -this -returns -an -error, -or -if -it -is -not -possible, - -data -schema +remote +Thing +, +as defined - -for -instance -when -discovery -is -based -on -open -ended -multicast -requests, +by +implementations +and + the -implementation -SHOULD -discard -subsequent -discovered -items. -Set +Protocol +Bindings +. +Return - -Property - -that -is -found -in - -this.getThingDescription().properties[ - -obs.closed - -propertyName - - -to - - -false +thing +. -] - -. -
                                  2. -
                                2. -If +options + +parameter +could +be +dismissed +from +the +methods +exposed +by this -fails, -throw - -SyntaxError -, -otherwise -return - -value -.
                                  3. -
                                -
                              18. -If -these -above -steps -failed, -reject - -promise - -with - -SyntaxError - -and -terminate -these -steps. -
                              19. -Otherwise -resolve - -promise - -with - -value -. -
                                20. - -
                                3.2 -

                                6.6 +API. +

                                +

                                +
                                +

                                +3.4 + + +6.4 + The -fetch() + + +produce() - -readMultipleProperties() +PropertyMap - -method -

                                Accepts -an -url -

                                Reads -multiple + + +method + +type + + + +

                                +Accepts + +Represents + +a +model +argument + +map + +of +type + + +Property + +names +as +strings +to +a +value +that +the Property -values -with -one -or -multiple -requests. -Takes -the - -propertyNames - -argument -of -type -USVString +can +take. +It +is +used +as +a +property +bag +for +interactions that -represents +involve +multiple + +Properties + +at +once. +

                                + +Editor's +note +

                                +It +could +be +defined +in +Web +IDL +(as +well +as + + +ThingModel -as +ThingDescription + + +) +as a -URL -(e.g. -"file://..." -or -"https://..." -) - -sequence -of -strings + +maplike + +interface +from + +string + +to + +any +.

                                + +6.5 + +The + +readProperty() + + + +method +

                                +Reads +a + +Property + +value. +Takes +a +string +argument + +propertyName + +and and returns -a -Promise -an -optional - -InteractionOptions +an +optional + + +ExposedThing + +InteractionOptions + -that -resolves +object. +The options @@ -6892,520 +8706,460 @@

                                argument. It returns -an -object +a + +Property + +value +represented +as -with -a -ThingDescription -(a -serialized -JSON-LD -document -of -type -USVString -). + +produce(model) -keys -from - -propertyNames - -and -values -returned -by -this -algorithm. +any + +type. The -fetch(url) - + method -MUST + +MUST + run the following -steps:

                                +steps: +

                                1. -Return +Return a - + Promise - - + promise - + and execute the next steps - -in -parallel -. -
                                  2. -
                                2. -If -invoking -fetch() - -this -method - -is -not -allowed -for -the -current -scripting -context -for -security -reasons, -reject - -promise - -with - -SecurityError - -and -terminate -these -steps. -
                                  3. -
                                3. -If -the -argument - -Let - - -url - -result - - -is -not -a -URL, -reject - -be -an -object -and -for -each -string - - -promise - -name - - -in - -propertyNames - -add -a -property + +in +parallel +.
                                4. +If +invoking +produce() + +this +method -with -TypeError +is +not +allowed +for +the +current +scripting +context +for +security +reasons, +throw -key +reject -name - +promise + +with + + +SecurityError + and -terminate +terminate these steps. - -the -value - -null -.
                                5. -Make +If + +Make a request to -fetch - + the -content -of -url -as -described -by +argument underlying platform (via - the - + Protocol Bindings - -and -wait -for - -) + +) to retrieve - the -reply. -Implementations -encapsulate - - -Property +value +of +the + +Property -values given by - -propertyNames - + + +model + +propertyName + + +is +a +string, +then +run +the +TD +parsing +algorithm + with -optional +optional URI templates given in - -options.uriVariables -.
                                6. -If -this -cannot -be -done -with -a -single -request -with - -the -fetching -process -and - - -Protocol -Bindings - -of -the -accepted -media -types -(such + +model +passed as +parameter. - -Thing -, -then +options.uriVariables +.
                                7. +If +it +throws +an +error, +re-throw +that + +the +request +fails, reject promise with +the - -application/td+json - -NotSupportedError - - -), -as -far -as -a -valid -Thing -Description -can -be -obtained -as -defined - -and +error +received +from +the + +Protocol +Bindings + +and terminate -these +this +algorithm. +Otherwise +let + +these steps.
                                8. -Process -the -reply -and -update -all -properties - -in -[ -WOT-TD -]. Let - + -td +model -result +value -be +be the -Thing -Description -string-serialized -from +returned +value. -with +result +of +the +request. +
                                  9. +
                                9. +If + +Run the -returned -content, -as -specified + +validate +Property +value + +sub-steps +on + + +model -values -obtained +value +:
                                  1. +Based +on +the + +DataSchema +definition +, +value -in + + +MUST + +be +a +JSON +value +and +comply +to the -Thing -Description -serialization -. - -reply. +data +schema +defined +for +the + +Property + +that -
                                    2. -
                                  2. -If -there -was +is +not an -error -during - -the -request, +object, -above -step -fails -at -any -point, +found +in + +this.getThingDescription().properties[ + +propertyName + +] +.
                                  3. +If +this +fails, -reject - -promise - -with -an -Error -object -error -with - +throw -error.message +TypeError SyntaxError +, +otherwise +return + +value +.
                                10. +If +these +above +steps +failed, +reject + +promise + +with + +SyntaxError -set -to -the -error -code -seen -by -the -Protocol -Bindings - and terminate these steps.
                                11. -Otherwise -resolve +If -Resolve +Otherwise +resolve -promise +model + +promise + -with - -td -and -terminate -these -steps. +does +not +have +an +own +property +that +is +defined +in -result -. -
                                  12. -
                                -

                                3.3 -

                                6.7 +with + +value +.

                                + +6.6 + The -consume() + + +ThingFragment - -readAllProperties() - - -method -

                                Accepts -an -td -argument -

                                Reads -all -properties +readMultipleProperties() -of -type -ThingDescription - -the - -Thing + + +method +

                                +Reads +multiple + +Property -and -returns -a -ConsumedThing - -with -one +values + +with +one or multiple requests. Takes +the + +propertyNames + +argument +as + +a +default +value, +add +that +property + +sequence +of +strings + +and +value +to +model +. +Create + an -optional - -InteractionOptions +optional + + +ExposedThing + +InteractionOptions + +object + -options - -argument. +thing + +options + + +initialized + +argument. It returns an - object -instantiated -based -on -parsing -that -description. - -with +with keys + from - -Property - -names + +model +. + +propertyNames + and values returned by this algorithm. - The -consume(td) - method -must - -MUST - + +MUST + run the following -steps:

                                -
                                  -
                                1. -If -the -argument - -Return +steps: +

                                  1. +Return a - + Promise - - -td - -promise - - -and + +promise + +and execute the next steps - + in parallel -.
                                  2. -If +. +
                                    3. +
                                  3. +For +each +property +of + +If invoking this method - is not -a -string, -throw -a - -allowed +allowed for the current @@ -7421,344 +9175,221 @@

                                    with -TypeError +ExposedThing SecurityError -and +defined + +and terminate these steps. -

                                    4. -
                                  4. +
                                  5. Let - -stub - -result - - + +result + be -an +an object and for each string - + name - + in - -propertyNames - + +propertyNames + add a property with key - + name - + and - the -result +value + + +ThingFragment +, +initialize -value - -null +null .
                                  6. Make a request to + the -underlying +property +based +on + +underlying platform (via + the - -Protocol +provided +initial +or +default +values +provided + + +Protocol Bindings ) + to -retrieve -the -value +retrieve -of -running - -the -all -the - -Property - -definitions -from the - -TD -parsing -algorithm +local +WoT +Runtime + +Property + +implementation, +for +instance +initialize: + +values +given +by + +propertyNames + with -optional +optional URI templates given in - - -td - -options.uriVariables -.
                                  7. -If -this -cannot -be -done -with -a -single -request -with -the - -Protocol -Bindings - -of -the - -Thing -, -then -reject - -promise - - -as -argument. - -with - -NotSupportedError - -and -terminate -these -steps. -
                                  8. -If -that -throws -an -error, -re-throw - -the -request -fails, -reject -promise - -with - -the -error -received -from -the - -Protocol -Bindings - -and -terminate -these -steps. -
                                    9. +options.uriVariables +.
                                  9. -If - -Process -the -reply -and -update -all -properties -in - - -stub - -result - - -does -not -have -an -own -property -that -is -defined - -with -the -values -obtained - -in -ThingFragment - -the -reply. -
                                  10. -Resolve - -promise - -with -a -default -value, -add -that +the +id property -and -value to - -stub - -result - -. -
                                    11. -Create - -
                                  -

                                6.8 -The - -writeProperty() - -method -

                                -Writes +If +this +cannot +be +done +with a -ConsumedThing - -single - -Property -. -Takes -a -string -argument - -propertyName -, -a -value -argument +single +request +with + +the +final +unique +identifier + + +Protocol +Bindings + +of +the + +Thing +, +the +security +object +of +type + +then +reject -value +promise -and -an -optional - -InteractionOptions +with - -object - - -thing + +SecurityScheme -options +NotSupportedError - -initialized -from + +to +represent -argument. -It -returns -success -or -failure. -The -method -MUST -run +and +terminate +these +steps. +
                              20. +Process + the -following -steps: -
                                1. -Return -a - -Promise - - -stub +actual +security +scheme -promise +reply - -that -implements -Observable +and +its -and -execute +update +all + +properties +as +set +up +by + +in + +result + +with + the -next -steps - +implementation, + +values +obtained in -parallel +the +reply. -.
                                2. -Add - -If -invoking -this -method -is -not -allowed -for +If the -current -scripting -context -for -security -reasons, +above +step +fails +at +any +point, reject promise @@ -7766,172 +9397,278 @@

                                  with -read() +properties -SecurityError +SyntaxError -and -write() -methods +property to +be +an +object -terminate +and +terminate these steps.

                                3. -Run - -the +Resolve + +promise + +with +all +properties +being + + +result +.

                                21. + +6.7 + +The + + ThingProperty - -validate -Property -value +readAllProperties() + + +method + -elements -so +objects +in +which -steps -on - -value -. -If +

                                +
                                +

                                +Reads +all +properties +of -that -they -make -requests +the + +Thing + +with +one +or +multiple +requests. +Takes +an +optional + + +read() +and +write() + +InteractionOptions + + +methods +are +provided to -access +define +local +methods +to +get +and +set the -remote -Thing -s + + + +options + +argument. +It +returns +an +object +with +keys +from + + +Property + +values, + +names +and +values +returned +by +this +algorithm. +The +method + +MUST + +run +the +following +steps: +

                                1. +Return +a + +Promise + +promise + and -wait -for +execute the -reply, -as -defined -by +next +steps + +in +parallel +. +
                                  2. +
                                2. +If +invoking +this +method +is +not +allowed +for + the -Protocol -Bindings -. -Also, -all -ThingProperty - -fails, +current +scripting +context +for +security +reasons, reject - + promise - - -elements -SHOULD -implement - -with + +with -Observable +actions -SyntaxError +SecurityError -, -i.e. -define +property +to and terminate these steps.
                                3. +Let + +result + +be +an +object +with +all +properties +being +ThingAction +objects + +and +for +each +string + +name + +in +which + + +propertyNames + +add +a +property +with +key + +name + +and + +the +value + + +invoke() +method +is +provided +to +define + +null +.
                                4. Make a -subscribe() +local method -that -should -make -request +request + to -observe +run the -given -Properties -as -defined -by +defined +Action underlying platform (via - the - + Protocol Bindings -. -Add -the -invoke() -methods -to -the -ThingAction - + -elements -so -that -they -make -requests +s, ) to -write - +retrieve +the value - -to +of the -remote -Thing - - -Property - - -to -invoke -its -actions, -as -defined - -given - -by -the -Protocol -Bindings -. - - -propertyName - +all +the + +Property + +definitions +from +the + +TD + with optional URI @@ -7943,148 +9680,213 @@

                                  .

                                5. -Add +the +events +property +to + +If +this +cannot + +be +an +object + +done + +with +all +properties +being +ExposedEvent + +a +single +request +with the -subscribe() -method + +Protocol +Bindings + + +objects +in +which + +of + +the + +Thing +, +then +reject + +promise + +with + + +emit() + +NotSupportedError + + +method +is +provided to -all -ThingEvent -elements -so -that -they -make -requests +define +a +local +way to -subscribe +trigger +sending +notifications to +all +subscribed +clients, -If +and +terminate +these +steps. +
                                  6. +
                                6. +If the -events -defined -by - -request +request fails, reject - + promise - + with - the -remote -Thing -, -as -defined -by - -error +error received from - the - + Protocol Bindings -. + +and +initialize - -and -terminate +terminate these steps. +
                                7. +Process + +the +other + +reply +and +update +all + +properties +as +initialized +from + +in + + +model +. + +result + +with +the +values +obtained +in +the +reply.
                                8. Return -Otherwise -resolve +Resolve thing promise + +with + +result .
                                -
                                3.4 -

                                6.9 + +

                                +
                                +

                                + +6.8 + The -produce() +TD +parsing +algorithm - -writeMultipleProperties() - - -method -

                                Accepts -

                                Writes - -a -model + + +writeProperty() + + +takes -multiple +method +

                                +Writes +a +single Property - -values -with -one -request. +. Takes + a - -properties - -argument -of -type -ThingModel - -as -an -object -with -keys -being - -Property +string +argument - -names -and -values + +td as - -Property - -values + +propertyName +, +a +value +argument + +value + and -returns - -an -ExposedThing +runs -optional - +an +optional + InteractionOptions - - -object. - - -options + +options argument. It @@ -8092,595 +9894,410 @@

                                success or failure. - The -produce(model) - -method -MUST -run -the -following -steps:

                                -
                                  -
                                1. -Return -a - -Promise - -promise - -and -execute -the -next -steps - -in -parallel -.
                                2. -If -invoking -produce() - -this method - -is -not -allowed -for -the -current -scripting -context -for -security -reasons, -throw - -reject - -promise - -with - - -SecurityError - -and -terminate -these -steps. -
                                  3. -
                                3. -If -the -argument - -For -each -key - - -model - -name - - -is -a -string, -then + +MUST + run -the -TD -parsing -algorithm -with - -on - - -model -passed - -properties -, -take -its -value -as -parameter. -If -it -throws -an -error, -re-throw -that -error -and -terminate -this -algorithm. -Otherwise -let +the +following +steps: +

                                  +
                                    +
                                  1. +Parse +Return +a + +Promise + -model +td -value +promise -be +according +to and -run +execute the -returned -value. +WoT +Thing +Description - -validate -Property -value - +next steps -on - -value -. -If -that -fails + in -for -any - - -model +order +to +produce +a +JSON +object + +parallel +.
                                  2. +If +invoking +this +method is not -an -object, -throw - -name -, +allowed +for +the +current +scripting +context +for +security +reasons, reject - + promise - + with - - -TypeError - -SyntaxError - - + +SecurityError + and terminate these steps. -
                                    3. -
                                  3. -If -model -does -not -have -an -own -property -that -is -defined -in -ThingFragment -with +
                                  4. +Run +the + +validate +Property +value + + +steps +on + + +json -Make +value -a -default -value, -add +. +Update + +If that -property +fails, +reject + +promise + +with + +SyntaxError + and -value - -single +terminate +these +steps. +
                                  5. +Make +a request - to -model -. -Create -an -ExposedThing - -the +the underlying platform (via the - + Protocol Bindings - - -object - -) + +) to write -the -each - -Property - -provided -in thing -properties +value -initialized -from - -with -optional -URI -templates -given -in - - -model - -options.uriVariables - -. -
                                    6. -
                                  6. -For -each -property -of -ExposedThing -defined -in -ThingFragment -, -initialize -the -property -based -on -the -provided -initial -or -default -values -provided -to -the -local -WoT -Runtime -implementation, -for -instance -initialize: -the -id -property -to - -If -this -cannot - -be -done -with -a -single -request -with - -the -final -unique -identifier - - -Protocol -Bindings - -of -the - -Thing -, -the -security -object -of -type - -then -reject - -promise - -with - - -SecurityScheme +with -NotSupportedError +to - -to -represent the -actual -security -scheme - +properties and -its -properties -as -set -up +values +defined + + +Property + +given by -the -implementation, + +propertyName + +with +optional +URI +templates +given + +in + +json -terminate -these -steps. +options.uriVariables +.
                                  7. -If - -the -properties -property -to -be +If +there +was an -object -with -all -properties -being -ThingProperty -objects -in -which +error +during + +the +parsing, +throw +that request fails, -return - +reject + +promise + +with the -read() -and -write() -methods -are -provided -to -define -local -methods -to -get -and -set - -error -received -from +error +received +from the -Property - - -Protocol + +Protocol Bindings - - -values, - -and + +and terminate these steps. -
                                  8. -the +Otherwise +return -Otherwise -resolve - -promise -.

                                6.10 -The - -WotListener - -callback -

                                -User -provided -callback -that -takes +resolve + + +json + +promise +. + + + +

                                +
                                +

                                +3.5 + + +6.9 + +The + -actions +register() -any +writeMultipleProperties() -property - -argument -and -is -used -for -observing - + +method + + +

                                +
                                +

                                +Writes +a +multiple + Property - -changes + +values +with +one +request. + +Takes +two +mandatory +arguments: +directory +denoting + +a +Thing +Directory +, and -handling - -Event - -notifications. -Since -subscribing +thing +denoting + + +properties + +argument +as -to -be an -object +ExposedThing +object. +Generate +the +Thing +Description -these -are -WoT -interactions, -they -are -not -modelled - +object with -all -properties +keys being -ThingAction -objects -in -which + +Property + + +names +and +values + +as +td +, +given the -invoke() +Properties +, +Action -software -events. -

                                6.11 -The - -observeProperty() - -method -is -provided + +Property + + +s + +values + +and +Event +s +defined +for +this + +an +optional + + +ExposedThing + +InteractionOptions + + + +object. +Then +make +a +request to -define +register + + +td -

                                Makes +options -a -local + +to +the +given +WoT +Thing +Directory +. +3.6 -request -for - -Property - -value -change -notifications. -Takes -a -string -argument - -propertyName -, -a - -WotListener - -callback -function - -listener - -and -an -optional - -InteractionOptions - -options - -argument. +argument. It returns success or failure. -The +The +unregister() + method -to +Takes +two +mandatory +arguments: -MUST - + +MUST + run the -defined -Action - -following +following steps: -

                                1. -Return -a - -Promise - -s, +

                                  +
                                    +
                                  1. +directory +denoting - -promise - +Return + +a +Thing +Directory +, + + +Promise + +promise + and -execute +execute the next steps - + in parallel .
                                  2. -If +If invoking this method @@ -8688,16 +10305,8 @@

                                    not allowed for - the -events -property -to -be -an -object - -current +current scripting context for @@ -8706,425 +10315,682 @@

                                    reject promise - + with -all -properties -being - + -ExposedEvent -objects -in -which -the -emit() +thing SecurityError -method -is -provided -to -define -a -local -way -to -trigger -sending -notifications -to -all -subscribed -clients, - -and -initialize -the -other -properties -as -initialized -from -model -. +denoting +an -terminate +and +terminate these steps. - -

                                    3. -
                                  3. -Return - -If - - -thing -. -The -TD -parsing -algorithm -takes - -listener +
                                  4. +For +each +key + +name -is -not - -a -string - -function, +on + +properties +, +take +its +value +as + +value + +and +run +the + +validate +Property +value + +steps +on + +value +. +If +that +fails +in +for +any + +name +, reject + +promise + +with - -td + +ExposedThing -promise +SyntaxError - -as -argument - -with - -"TypeError" - -and -runs -the -following -steps: + +object. -terminate +and +terminate these steps. -
                                    5. -
                                  5. -Parse -td -according + +
                                    6. +Makes +
                                  6. Make + a -request +single +request to +unregister + the -WoT -Thing -Description +thing +from underlying platform (via + the - -Protocol +given +WoT +Thing +Directory +. +3.7 +Examples +Example +1 + + +Protocol Bindings -in -order +: +Discover +Things +via +directory +<span class= +"hljs-keyword">let discoveryFilter = { + : <span class= +"hljs-string">"directory", + : <span class= +"hljs-string">"http://directory.wotservice.org" +}; +<span class= +"hljs-keyword">let subscription = wot.discover(discoveryFilter).subscribe( + <span class= +"hljs-params">td { + .log(<span class= +"hljs-string">"Found Thing " + td.name); + <span class= +"hljs-comment">// fetch the TD and create a ConsumedThing + thing = wot.consume(td); + }, + error => { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Discovery finished because an error: " + error.message); }, + () => { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Discovery finished successfully");} +); +setTimeout( <span class= +"hljs-params">() { + subscription.unsubscribe(); + .log(<span class= +"hljs-string">"Discovery timeout"); + }, +5000 +); +Example +2 ) - to -produce -a -JSON -object - -observe - +write +the +each + Property -identified +: +Discover +Things +exposed by - - -json -. -Update -thing +local +hardware +<span class= +"hljs-keyword">let }).subscribe( + <span class= +"hljs-params">td { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Found local Thing " + td.name); }, + error => { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Discovery error: " + error.message); }, + () => { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Discovery finished successfully");} +); +Example +3 -propertyName - - -with -the +provided +in + properties -and -values -defined - -optional + +with +optional URI templates given - in - -json - -options.uriVariables - -. -
                                    7. -
                                  7. + +options.uriVariables +.
                                  8. If -there -was -an -error -during - +this +cannot +be +done +with +a +single +request +with the -parsing, -throw -that + +Protocol +Bindings + + +: +Same +as +above +but -request -fails, +of +the + +Thing +, +then reject promise - + with +different +Observable +syntax +<span class= +"hljs-keyword">let }).subscribe({ + td => { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Found local Thing " + td.name); }, + : <span class= +"hljs-function"><span class= +"hljs-params">err { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Discovery error: " + err.message); }, + : <span class= +"hljs-function"><span class= +"hljs-params">() { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Discovery finished successfully");} +}); + + +NotSupportedError + +and +terminate +these +steps. +
                                  9. +If +the +request +fails, +return the - error -received +received from the - + Protocol Bindings - + and terminate these steps. -
                                    10. -
                                  10. +
                                  11. Otherwise -return - -resolve - - -json +resolve + +promise +.
                                  +
                                +
                                +
                                +

                                +4. + + +6.10 + +The + + +ConsumedThing -promise +WotListener -. - -3.5 -The -register() -method -Takes -two -mandatory -arguments: -directory -denoting -a -Thing -Directory -, -and + + +interface -
                              21. -thing -denoting +callback + + +

                                22. +

                                +Represents an -ExposedThing -object. -Generate +object -Whenever +User +provided +callback -the -Thing -Description - -underlying -platform -receives +that +extends a -notification -for -this -subscription -with -new - -Property - - -as -value +takes - -td + +ThingFragment -value +any -, -given + +with +methods +for +client +interactions +(send +request +for +reading +and +writing +Properties +), +invoke +Action +s, +subscribe -run +argument -the -Properties -, -Action -s and -Event -s -defined +unsubscribe + +is +used + for -this -ExposedThing - -following -sub-steps: -

                                • -If -running -the - -validate -Property -value +observing + +Property -object. -Then -make -a -request -to -register +changes +and +handling + +Event + +s. -steps -on +notifications. +Since +subscribing +to +these +are +WoT +interactions, +they +are +not +modelled +with +software +events. - -td +

                                  +<span class="idlInterface" id= +"idl-def-consumedthing" data-idl="" data-title= +"ConsumedThing">interface <span class= +"idlInterfaceID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-consumedthing" class="internalDFN" data-link-type= +"dfn"> : <span class= +"idlSuperclass"><a href="#dom-thingfragment" class="internalDFN" +data-link-type= +"dfn"> {<span class= +"idlAttribute" id="idl-def-consumedthing-id" data-idl="" +data-title="id" data-dfn-for="consumedthing"> + readonly attribute <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" +data-link-for="consumedthing" data-lt="consumedthing.id|id" href= +"#dom-consumedthing-id" class="internalDFN" data-link-type= +"dfn"><span class="idlAttribute" +id="idl-def-consumedthing-name" data-idl="" data-title="name" +data-dfn-for="consumedthing"> + readonly attribute <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" +data-link-for="consumedthing" data-lt="consumedthing.name|name" +href="#dom-consumedthing-name" class="internalDFN" data-link-type= +"dfn"><span class= +"idlAttribute" id="idl-def-consumedthing-base" data-idl="" +data-title="base" data-dfn-for="consumedthing"> + readonly attribute <a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<a data-no-default="" +data-link-for="consumedthing" data-lt="consumedthing.base|base" +href="#dom-consumedthing-base" class="internalDFN" data-link-type= +"dfn"><span class= +"idlAttribute" id="idl-def-consumedthing-properties" data-idl="" +data-title="properties" data-dfn-for="consumedthing"> + readonly attribute <a data-link-for="" +href="#dom-propertymap" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlAttrName"><a data-no-default="" data-link-for="consumedthing" +data-lt="consumedthing.properties|properties" href= +"#dom-consumedthing-properties" class="internalDFN" data-link-type= +"dfn"><span class= +"idlAttribute" id="idl-def-consumedthing-actions" data-idl="" +data-title="actions" data-dfn-for="consumedthing"> + readonly attribute <a data-link-for="" +href="#dom-actionmap" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlAttrName"><a data-no-default="" data-link-for="consumedthing" +data-lt="consumedthing.actions|actions" href= +"#dom-consumedthing-actions" class="internalDFN" data-link-type= +"dfn"><span class= +"idlAttribute" id="idl-def-consumedthing-events" data-idl="" +data-title="events" data-dfn-for="consumedthing"> + readonly attribute <a data-link-for="" +href="#dom-eventmap" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlAttrName"><a data-no-default="" data-link-for="consumedthing" +data-lt="consumedthing.events|events" href= +"#dom-consumedthing-events" class="internalDFN" data-link-type= +"dfn"><span class="idlMethod" +id="idl-def-consumedthing--name" data-idl="" data-title="" +data-dfn-for="consumedthing"> + // getter for ThingFragment properties + <a href= +"https://heycam.github.io/webidl/#idl-any">any +};<span class="idlInterface" id="idl-def-propertymap" +data-idl="" data-title="PropertyMap"> +[<a href= +"https://heycam.github.io/webidl/#NoInterfaceObject">NoInterfaceObject] +interface <a data-no-default="" +data-link-for="" data-lt="" href="#dom-propertymap" class= +"internalDFN" data-link-type= +"dfn"> {<span class="idlMaplike" +id="idl-def-propertymap-maplike" data-idl="" data-title="iterable" +data-dfn-for="propertymap"> + readonly maplike<<a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString, <a data-link-for="" +href="#dom-thingproperty" class="internalDFN" data-link-type= +"dfn"> +};<span class="idlInterface" id="idl-def-actionmap" +data-idl="" data-title="ActionMap"> +[<a href= +"https://heycam.github.io/webidl/#NoInterfaceObject">NoInterfaceObject] +interface <a data-no-default="" +data-link-for="" data-lt="" href="#dom-actionmap" class= +"internalDFN" data-link-type= +"dfn"> {<span class="idlMaplike" +id="idl-def-actionmap-maplike" data-idl="" data-title="iterable" +data-dfn-for="actionmap"> + readonly maplike<<a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString, <a data-link-for="" +href="#dom-thingaction" class="internalDFN" data-link-type= +"dfn"> +};<span class="idlInterface" id="idl-def-eventmap" data-idl= +"" data-title="EventMap"> +[<a href= +"https://heycam.github.io/webidl/#NoInterfaceObject">NoInterfaceObject] +interface <a data-no-default="" +data-link-for="" data-lt="" href="#dom-eventmap" class= +"internalDFN" data-link-type= +"dfn"> {<span class="idlMaplike" +id="idl-def-eventmap-maplike" data-idl="" data-title="iterable" +data-dfn-for="eventmap"> + readonly maplike<<a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString, <a data-link-for="" +href="#dom-thingevent" class="internalDFN" data-link-type= +"dfn"> +}; +<a href="#dom-consumedthing" class="internalDFN" data-link-type= +"dfn"> includes <a href= +"#dom-observable" class="internalDFN" data-link-type= +"dfn"><span class= +"idlSectionComment"> +// +for +TD +changes -value +
                                +
                                +

                                + +6.11 + +The + + +id + +observeProperty() - -to + + +attribute +represents +the +unique +identifier +of the -given -WoT Thing -Directory +instance, +typically +a +URI, +IRI, +or +URN +as +USVString . +The +name -fails, -terminate -these -steps. -
                              22. -Invoke - -listener - -with - -value - -as -parameter. -

                                23. 3.6 -

                                6.12 +method + +attribute +represents +the +name +of +the +Thing + + +as +DOMString +. The -unregister() - -unobserveProperty() +base +attribute +represents +the +base +URI +that +is +valid +for +all +defined +local +interaction +resources. + +

                                +
                                +

                                +The +properties +attribute +represents + +Makes - -method -

                                Makes a -request +dictionary +of +ThingProperty + +request for -unsubscribing -from - + Property - -value + + +items. +The + +value change notifications. - Takes -two -mandatory -arguments: - -a +a string argument propertyName +, +a + + +PropertyMap + +WotListener + + +interface +represents +a +maplike +dictionary +where +all +values +are + + +callback +function + +listener and +an +optional + + +ThingProperty + +InteractionOptions + + + +objects. + + +options + +argument. +It returns success or failure. + The -method -MUST +method + +MUST + run the following steps: -

                                  -
                                1. -directory -denoting - -Return - +

                                  1. +Return a -Thing -Directory -, - - -Promise - + +Promise + promise - + and -execute +execute the next steps - + in parallel -. -
                                    2. -
                                  2. -If +.
                                  3. +If invoking this method @@ -9146,147 +11012,113 @@

                                    with -thing -denoting -an -ExposedThing +read() SecurityError -object. +and +terminate +these +steps. +

                                  4. +If + +listener + +is +not +a +function, +reject + +promise + +with + + +write() + +"TypeError" + + +methods +make and terminate these steps. - -
                                    5. -Makes - -
                                  5. -Make +
                                  6. +Make a request to -unregister +access the -thing -from - -underlying +underlying platform (via - the -given -WoT -Thing -Directory -. -3.7 -Examples -Example -1 - - -Protocol + +Protocol Bindings - - -: -Discover -Things -via -directory -discoveryFilter = { -, - -

                                    }; -subscription = wot.discover(discoveryFilter).subscribe( -{

                                    -
                                      -
                                    • td.name);
                                      • -
                                    -

                                    thing = wot.consume(td); -}, -error => { + error.message); }, -() => { );} -); -setTimeout( { -subscription.unsubscribe(); -); -}, -5000 -); -Example -2 -

                                    ) + +) to -stop -observing -the - -Property +observe + + +Properties + +Property -: -Discover -Things -exposed +on identified - by -local -hardware -}).subscribe(

                                    - -
                                      -
                                    • td.name); }, -error => { + error.message); }, -() => { );} -); -Example -3 -: -Same -as -above -but - -propertyName -. -
                                    • + +propertyName + +with +optional +URI +templates +given +in + +options.uriVariables +.
                                    • If + the -request +remote +Thing + +request fails, reject promise - + with -different -Observable -syntax -}).subscribe({ -td => { + td.name); },
                                      • -
                                    • err.message); }, -);} -}); -the +the error received from the - + Protocol Bindings - -and + + +represented +by + +and terminate these steps. @@ -9295,215 +11127,194 @@

                                      resolve promise -.

                                      • -
                                     -
                                    7. -
                                  -
                                4. -

                                6.13 -The -ConsumedThing - - -invokeAction() - - -interface -Represents -an -object -that -extends - -method -

                                -Makes - +.
                              23. +Whenever +the +underlying +platform +receives a -ThingFragment -with -methods -for -client -interactions -(send - -request +notification for -reading -and -writing -Properties -), -invoke + +this +ConsumedThing -invoking -an - -Action +subscription +with +new + +Property + -s, -subscribe +proxy +object. +The -and -unsubscribe -for -Property -changes -and -Event -s. - -

                                readonly attribute -readonly attribute -readonly attribute -readonly attribute -readonly attribute -readonly attribute -// getter for ThingFragment properties

                                -

                                }; -[] -interface -readonly maplike< -}; -[] -interface -readonly maplike< -}; -[] -interface -readonly maplike< -}; -ConsumedThing -includes -

                                return -the -result. -Takes -a -string -argument +value -actionName +value , -an -optional -argument +run +the +following +sub-steps: +

                                • +If +running +the + +validate +Property +value + +steps +on -params +value -of -type - +fails, +terminate +these +steps. +
                                • +Invoke + +listener + +with + +value + +as +parameter. +

                                24. + +6.12 + +The + -Observable +actions -any +unobserveProperty() -and -an -optional - -InteractionOptions - - -; -// -for -TD -changes -The -id -attribute + +attribute represents +a +dictionary +of +ThingAction - -options - -argument. -It -returns - -the -unique -identifier +method + + +items. +The -result +ActionMap +interface +represents + +

                                +
                                +

                                +Makes -of -the -Thing +a +maplike +dictionary +where +all +values +are +ThingAction - -Action +request +for +unsubscribing +from + +Property -instance, -typically -a -URI, -IRI, +objects. +value +change +notifications. +Takes +a +string +argument + +propertyName + +and +returns +success or -URN -as -USVString -. - -an -error. +failure. The -name -attribute -represents +invoke() + +method +represents +a +request +to +invoke the -name -of +Action +on -method -MUST + +MUST + run the -Thing +remote +Thing +. following steps: -

                                -
                                1. -Return + +

                                  +The +events +attribute +represents + +
                                    +
                                  1. +Return + a - -Promise +dictionary +of +ThingEvent + + +Promise -as -DOMString -. +items. The -base -attribute -represents promise and execute - the -base -URI -that - -next +next steps - + in parallel .
                                  2. @@ -9511,44 +11322,11 @@

                                    invoking this method - is -valid - -not +not allowed - for -all -defined -local -interaction -resources. -The -properties -attribute -represents -a -dictionary -of -ThingProperty -items. -The -PropertyMap -interface -represents -a -maplike -dictionary -where -all -values -are -ThingProperty -objects. -The - -the +the current scripting context @@ -9562,223 +11340,224 @@

                                    with -read() +EventMap SecurityError -and -write() -methods -make +interface +represents -terminate +and +terminate these steps.

                                  3. Make a -request -to -access - -the -Properties -on - -underlying -platform -(via - -the -remote -Thing -represented -by -this -ConsumedThing -proxy -object. -The -actions -attribute -represents -a -dictionary -of -ThingAction -items. -The -ActionMap -interface -represents -a -maplike -dictionary -where -all -values -are -ThingAction - - -Protocol -Bindings - - -objects. -The -invoke() -method -represents -a -request - -) - -to -invoke -the - -Action - -on -the -remote -Thing -. -The -events -attribute -represents -a -dictionary -of -ThingEvent -items. -The -EventMap -interface -represents -a -maplike +maplike dictionary where all values are -ThingEvent -objects. -Subscribing -to - -identified -by - -actionName - -with -parameters -provided -in - -params - -with -optional -URI -templates -given -in - -options.uriVariables -.
                                  4. -If +ThingEvent +objects. +Subscribing + +request +to the events involves setting up - -request -fails -locally -or -returns - an -observation +observation (subscription) mechanism on + +underlying +platform +(via + the -remote +remote object. 4.1 Examples -Below + + +Protocol +Bindings + + +Below a ConsumedThing -interface + +) +to +stop +observing +the + +Property + + +interface example is given. Example 4 -: + +identified +by + +propertyName +.
                                  5. +If +the +request +fails, +reject + +promise + +with +the +error +received +from +the + +Protocol +Bindings + + +: Consume a Thing -{ -}).subscribe( -{ -thing = wot.consume(td); -); -{ -
                                      -
                                    • value); -}); -thing.actions[ }) -.then(); }) -.catch( { -); -subscription.unsubscribe(); -}) -}, -error => { + error.message); }, -() => { );} -); -} (error) {
                                        -
                                      • error.message); -};
                                        • -
                                      -5. -The -ExposedThing -interface +<span class= +"hljs-keyword">try { + <span class= +"hljs-keyword">let }).subscribe( + <span class= +"hljs-params">td { + <span class= +"hljs-keyword">let thing = wot.consume(td); + .log(<span class= +"hljs-string">"Thing " + thing.name + <span class= +"hljs-string">" has been consumed."); + <span class= +"hljs-keyword">let subscription = thing[<span class= +"hljs-string">"temperature"].subscribe(<span class= +"hljs-function"><span class= +"hljs-keyword">function(<span class= +"hljs-params">value{ + <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Temperature: " + value); + }); + thing.actions[<span class= +"hljs-string">"startMeasurement"].invoke({ <span class= +"hljs-attr">units: <span class= +"hljs-string">"Celsius" }) + .then(<span class= +"hljs-params">() { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Temperature measurement started."); }) + .catch(<span class= +"hljs-params">e { + <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Error starting measurement."); + subscription.unsubscribe(); + }) + }, + error => { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Discovery error: " + error.message); }, + () => { <span class= +"hljs-built_in">console.log(<span class= +"hljs-string">"Discovery finished successfully");} + ); +} (error) { + .log(<span class= +"hljs-string">"Error: " + error.message); +}; + +and +terminate +these +steps. +
                                    • +Otherwise +resolve + +promise +.
                                  +
                                +
                                +
                                +

                                +5. + + +6.13 + The + + +ExposedThing + +invokeAction() + + + +interface + +method + + +

                                +
                                +

                                +The ExposedThing interface is -error -over - the -server +server API that allows defining + +Makes +a + request -handlers, +handlers, properties, Actions , and Events -to + +for +invoking +an + +Action + + +to a Thing . @@ -9786,80 +11565,408 @@

                                also implements -network, -reject +and +return + +the +result. +Takes +a +string +argument -promise +actionName +, +an +optional +argument + +params -with +of +type -the + Observable -interface. + +any + + +interface. An -ExposedThing -is + +and +an +optional + + +ExposedThing + +InteractionOptions + + + +is created by -error -received -from + +options + +argument. +It +returns the produce() method. - - -

                                readonly attribute -readonly attribute -readonly attribute -// getter for ThingFragment properties

                                -

                                // setter for ThingFragment properties

                                -

                                // methods to expose and destroy the Thing

                                -

                                // define Properties

                                -

                                // define Actions

                                -

                                // define Events

                                -

                                }; -[] -interface -maplike< -}; -callback -callback -callback -ActionHandler -= +<span class="idlInterface" id= +"idl-def-exposedthing" data-idl="" data-title= +"ExposedThing">interface <span class= +"idlInterfaceID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-exposedthing" class="internalDFN" data-link-type= +"dfn"> : <span class= +"idlSuperclass"><a href="#dom-thingfragment" class="internalDFN" +data-link-type= +"dfn"> {<span class= +"idlAttribute" id="idl-def-exposedthing-properties" data-idl="" +data-title="properties" data-dfn-for="exposedthing"> + readonly attribute <a data-link-for="" +href="#dom-propertymap" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlAttrName"><a data-no-default="" data-link-for="exposedthing" +data-lt="exposedthing.properties|properties" href= +"#dom-exposedthing-properties" class="internalDFN" data-link-type= +"dfn"><span class= +"idlAttribute" id="idl-def-exposedthing-actions" data-idl="" +data-title="actions" data-dfn-for="exposedthing"> + readonly attribute <a data-link-for="" +href="#dom-actionmap" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlAttrName"><a data-no-default="" data-link-for="exposedthing" +data-lt="exposedthing.actions|actions" href= +"#dom-exposedthing-actions" class="internalDFN" data-link-type= +"dfn"><span class= +"idlAttribute" id="idl-def-exposedthing-events" data-idl="" +data-title="events" data-dfn-for="exposedthing"> + readonly attribute <a data-link-for="" +href="#dom-exposedevents" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlAttrName"><a data-no-default="" data-link-for="exposedthing" +data-lt="exposedthing.events|events" href= +"#dom-exposedthing-events" class="internalDFN" data-link-type= +"dfn"><span class="idlMethod" +id="idl-def-exposedthing--name" data-idl="" data-title="" +data-dfn-for="exposedthing"> + // getter for ThingFragment properties + <a href= +"https://heycam.github.io/webidl/#idl-any">any<span class="idlMethod" +id="idl-def-exposedthing--name-value" data-idl="" data-title="" +data-dfn-for="exposedthing"> + // setter for ThingFragment properties + (<span class= +"idlParam"><a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<span class="idlMethod" +id="idl-def-exposedthing-expose" data-idl="" data-title="expose" +data-dfn-for="exposedthing"><span class= +"idlSectionComment"> + // methods to expose and destroy the Thing + <a href= +"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default="" +data-link-for="exposedthing" data-lt= +"exposedthing.expose()|exposedthing.expose|expose()|expose" href= +"#dom-exposedthing-expose" class="internalDFN" data-link-type= +"dfn"><span class= +"idlMethod" id="idl-def-exposedthing-destroy" data-idl="" +data-title="destroy" data-dfn-for="exposedthing"><span class= +"idlMethType"> + <a href= +"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default="" +data-link-for="exposedthing" data-lt= +"exposedthing.destroy()|exposedthing.destroy|destroy()|destroy" +href="#dom-exposedthing-destroy" class="internalDFN" +data-link-type="dfn"><span class="idlMethod" +id="idl-def-exposedthing-addproperty-name-property-initvalue" +data-idl="" data-title="addProperty" data-dfn-for= +"exposedthing"><span class= +"idlSectionComment"> + // define Properties + <a data-link-for="" href="#dom-exposedthing" class= +"internalDFN" data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="exposedthing" +data-lt= +"exposedthing.addproperty()|exposedthing.addproperty|addproperty()|addproperty" +href="#dom-exposedthing-addproperty" class="internalDFN" +data-link-type= +"dfn">(<span class= +"idlParam"><a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString <a data-link-for="" +href="#dom-propertyfragment" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlParamName">property,<span class= +"idlParam"> optional <a href= +"https://heycam.github.io/webidl/#idl-any">any<span class="idlMethod" +id="idl-def-exposedthing-setpropertyreadhandler-name-readhandler" +data-idl="" data-title="setPropertyReadHandler" data-dfn-for= +"exposedthing"> + <a data-link-for="" href="#dom-exposedthing" class="internalDFN" +data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="exposedthing" +data-lt= +"exposedthing.setpropertyreadhandler()|exposedthing.setpropertyreadhandler|setpropertyreadhandler()|setpropertyreadhandler" +href="#dom-exposedthing-setpropertyreadhandler" class="internalDFN" +data-link-type= +"dfn">(<span class= +"idlParam"><a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString <a data-link-for="" +href="#dom-propertyreadhandler" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlParamName">readHandler<span class= +"idlMethod" id= +"idl-def-exposedthing-setpropertywritehandler-name-writehandler" +data-idl="" data-title="setPropertyWriteHandler" data-dfn-for= +"exposedthing"> + <a data-link-for="" href="#dom-exposedthing" class="internalDFN" +data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="exposedthing" +data-lt= +"exposedthing.setpropertywritehandler()|exposedthing.setpropertywritehandler|setpropertywritehandler()|setpropertywritehandler" +href="#dom-exposedthing-setpropertywritehandler" class= +"internalDFN" data-link-type= +"dfn">(<span class= +"idlParam"><a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString <a data-link-for="" +href="#dom-propertywritehandler" class="internalDFN" +data-link-type="dfn"><span class="idlMethod" +id="idl-def-exposedthing-removeproperty-name" data-idl="" +data-title="removeProperty" data-dfn-for= +"exposedthing"> + <a data-link-for="" href="#dom-exposedthing" class="internalDFN" +data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="exposedthing" +data-lt= +"exposedthing.removeproperty()|exposedthing.removeproperty|removeproperty()|removeproperty" +href="#dom-exposedthing-removeproperty" class="internalDFN" +data-link-type= +"dfn">(<span class= +"idlParam"><a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<span class="idlMethod" +id="idl-def-exposedthing-addaction-name-init-action" data-idl="" +data-title="addAction" data-dfn-for="exposedthing"><span class= +"idlMethType"> + // define Actions + <a data-link-for="" href="#dom-exposedthing" class= +"internalDFN" data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="exposedthing" +data-lt= +"exposedthing.addaction()|exposedthing.addaction|addaction()|addaction" +href="#dom-exposedthing-addaction" class="internalDFN" +data-link-type="dfn">(<span class= +"idlParam"><a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString <a data-link-for="" +href="#dom-actionfragment" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlParamName">init,<span class= +"idlParam"> <a data-link-for="" href= +"#dom-actionhandler" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlParamName">action<span class="idlMethod" +id="idl-def-exposedthing-removeaction-name" data-idl="" data-title= +"removeAction" data-dfn-for="exposedthing"><span class= +"idlMethType"> + <a data-link-for="" href="#dom-exposedthing" class="internalDFN" +data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="exposedthing" +data-lt= +"exposedthing.removeaction()|exposedthing.removeaction|removeaction()|removeaction" +href="#dom-exposedthing-removeaction" class="internalDFN" +data-link-type= +"dfn">(<span class= +"idlParam"><a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString<span class="idlMethod" +id="idl-def-exposedthing-setactionhandler-name-action" data-idl="" +data-title="setActionHandler" data-dfn-for= +"exposedthing"> + <a data-link-for="" href="#dom-exposedthing" class="internalDFN" +data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="exposedthing" +data-lt= +"exposedthing.setactionhandler()|exposedthing.setactionhandler|setactionhandler()|setactionhandler" +href="#dom-exposedthing-setactionhandler" class="internalDFN" +data-link-type= +"dfn">(<span class= +"idlParam"><a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString <a data-link-for="" +href="#dom-actionhandler" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlParamName">action<span class="idlMethod" +id="idl-def-exposedthing-addevent-name-event" data-idl="" +data-title="addEvent" data-dfn-for="exposedthing"><span class= +"idlMethType"> + // define Events + <a data-link-for="" href="#dom-exposedthing" class= +"internalDFN" data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="exposedthing" +data-lt= +"exposedthing.addevent()|exposedthing.addevent|addevent()|addevent" +href="#dom-exposedthing-addevent" class="internalDFN" +data-link-type="dfn">(<span class= +"idlParam"><a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString <a data-link-for="" +href="#dom-eventfragment" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlParamName">event<span class="idlMethod" +id="idl-def-exposedthing-removeevent-name" data-idl="" data-title= +"removeEvent" data-dfn-for="exposedthing"><span class= +"idlMethType"> + <a data-link-for="" href="#dom-exposedthing" class="internalDFN" +data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="exposedthing" +data-lt= +"exposedthing.removeevent()|exposedthing.removeevent|removeevent()|removeevent" +href="#dom-exposedthing-removeevent" class="internalDFN" +data-link-type= +"dfn">(<span class= +"idlParam"><a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString +};<span class="idlInterface" id="idl-def-exposedevents" +data-idl="" data-title="ExposedEvents"> +[<a href= +"https://heycam.github.io/webidl/#NoInterfaceObject">NoInterfaceObject] +interface <a data-no-default="" +data-link-for="" data-lt="" href="#dom-exposedevents" class= +"internalDFN" data-link-type= +"dfn"> {<span class= +"idlMaplike" id="idl-def-exposedevents-maplike" data-idl="" +data-title="iterable" data-dfn-for="exposedevents"> + maplike<<a href= +"https://heycam.github.io/webidl/#idl-DOMString">DOMString, <a data-link-for="" +href="#dom-exposedevent" class="internalDFN" data-link-type= +"dfn"> +};<span class="idlCallback" id="idl-def-propertyreadhandler" +data-idl="" data-title="PropertyReadHandler"> +callback <a data-no-default="" +data-link-for="" data-lt="" href="#dom-propertyreadhandler" class= +"internalDFN" data-link-type= +"dfn"> =<span class= +"idlCallbackType"> <a href= +"https://heycam.github.io/webidl/#idl-promise">Promise<span class="idlCallback" +id="idl-def-propertywritehandler" data-idl="" data-title= +"PropertyWriteHandler"> +callback <a data-no-default="" +data-link-for="" data-lt="" href="#dom-propertywritehandler" class= +"internalDFN" data-link-type= +"dfn"> =<span class= +"idlCallbackType"> <a href= +"https://heycam.github.io/webidl/#idl-promise">Promise<span class="idlCallback" +id="idl-def-actionhandler" data-idl="" data-title="ActionHandler"> +callback <a data-no-default="" +data-link-for="" data-lt="" href="#dom-actionhandler" class= +"internalDFN" data-link-type= +"dfn"> =<span class= +"idlCallbackType"> <a href= +"https://heycam.github.io/webidl/#idl-promise"> Promise < +<a +href="https://heycam.github.io/webidl/#idl-any"> any -

                                -
                                -
                                -

                                ( +> +( any -parameters + +result +of +the + +Action + + +parameters ); + +or +an +error. + The -properties +properties attribute represents + +method + +MUST + +run +the +following +steps: +

                                1. +Return + a -dictionary +dictionary of ThingProperty - - -Protocol -Bindings + + +Promise items + + +promise + +and +execute +the +next +steps + in -which +which + +parallel +.
                                2. +If +invoking +this +method +is +not +allowed +for + the -read() +current +scripting +context +for +security +reasons, +reject + +promise + +with + + +read() +SecurityError + + and write() methods @@ -9868,24 +11975,24 @@

                                  methods that access -the -physical -representations -of terminate these steps. +

                                3. +Make +a +request +to -

                                  +the +physical +representations +of -
                                4. -Otherwise -let - -value - -be +underlying +platform +(via the Properties @@ -9898,31 +12005,31 @@

                                  dictionary of ThingAction -items -result -returned + +Protocol +Bindings + +items in -which - +which the -invoke() +invoke() method represents a local method -to -invoke -reply -and -run +) +to +invoke the -Action -. + +Action +. The events attribute @@ -9932,28 +12039,68 @@

                                  of ExposedEvent - -validate -Property -value - items +that +add -steps -on -it. +identified +by + +actionName + +with +parameters +provided +in + +params + +with +optional +URI +templates +given +in + +options.uriVariables +.

                                5. If -that -add the -emit() +emit() method to + +request +fails +locally +or +returns +an +error +over + the -ThingEvent -definition. +ThingEvent + +network, +reject + +promise + +with +the +error +received +from +the + +Protocol +Bindings + + +definition. The ExposedEvents interface @@ -9966,7 +12113,37 @@

                                  values are -fails, +and +terminate +these +steps. +

                                6. +Otherwise +let + +value + +be +the +result +returned +in +the +reply +and +run +the + +validate +Property +value + +steps +on +it. +If +that +fails, reject promise @@ -9979,41 +12156,46 @@

                                  SyntaxError -objects. -5.1 - -and +and terminate these steps. -

                                7. +
                                8. Reject - + promise - + with - + value -.
                                  9. -
                                +.

                                +objects. +5.1 -

                                6.14 + +6.14 + The + + expose() - subscribeEvent() - + + method -

                                Start + + + +
                                +

                                +Start serving external requests -

                                Makes + +Makes a request @@ -10028,7 +12210,7 @@

                                subscribing to - + Event @@ -10046,9 +12228,9 @@

                                eventName , a - + WotListener - + s @@ -10059,42 +12241,47 @@

                                and Event +s +will +be +possible. +The an optional - -InteractionOptions + + +expose() + +InteractionOptions + -s -will -be -possible. - -options - +options + argument. It returns success or failure. - The -expose() - + method -MUST + +MUST + run the following -steps:

                                +steps: +

                                1. Return a - + Promise @@ -10105,7 +12292,7 @@

                                  the next steps - + in parallel . @@ -10191,32 +12378,36 @@

                                  , invoke Action -s -and -manage -Event -subscriptions), -based -on (via - the - + Protocol Bindings -. - + +s +and +manage + ) to subscribe to an - + + Event - -identified + +subscriptions), +based +on +the +Protocol +Bindings +. + +identified by eventName @@ -10269,7 +12460,7 @@

                                  from the - + Protocol Bindings @@ -10297,12 +12488,14 @@

                                  notification for this - + Event subscription, implementations -SHOULD + +SHOULD + invoke @@ -10328,24 +12521,36 @@

                                -

                                5.2 -

                                6.15 + +

                                +
                                +

                                +5.2 + + +6.15 + The + + destroy() - unsubscribeEvent() - + + method -

                                Stop + + + +
                                +

                                +Stop serving external requests -

                                Makes + +Makes a request @@ -10392,16 +12597,19 @@

                                destroy() method -MUST + +MUST + run the following -steps:

                                +steps: +

                                1. Return a - + Promise @@ -10412,7 +12620,7 @@

                                  the next steps - + in parallel . @@ -10472,7 +12680,7 @@

                                  (via the - + Protocol Bindings . @@ -10483,7 +12691,7 @@

                                  unsubscribe from the - + Event identified @@ -10530,7 +12738,7 @@

                                  from the - + Protocol Bindings @@ -10554,14 +12762,25 @@

                                  .

                                -

                                5.3 + +
                                +5.3 The addProperty() -method -

                                6.16 -ConsumedThing + +
                                +

                                +method + + +6.16 + +ConsumedThing Examples -

                                + + +

                                +

                                Adds The @@ -10597,14 +12816,17 @@

                                argument of type -PropertyFragment URL, create a - -ConsumedThing + + +PropertyFragment + +ConsumedThing + , and optionally @@ -10649,14 +12871,14 @@

                                not provided, it -SHOULD +SHOULD be initialized as undefined . Implementations -SHOULD +SHOULD update the Thing @@ -10686,69 +12908,116 @@

                                event, unsubscribe. -

                                -
                                - Example 2: Thing Client API example - 
                                        try {
-          let res = await fetch("https://tds.mythings.org/sensor11");
-          let td = res.json();
-          let thing = new ConsumedThing(td);
-          console.log("Thing " + thing.getThingDescription().title + " consumed.");
-        } catch(e) {
-          console.log("TD fetch error: " + e.message); },
-        };
-        try {
-          // subscribe to property change for “temperature”
-          await thing.observeProperty("temperature", value => {
-            console.log("Temperature changed to: " + value);
-          });
-          // subscribe to the “ready” event defined in the TD
-          await thing.subscribeEvent("ready", eventData => {
-            console.log("Ready; index: " + eventData);
-            // run the “startMeasurement” action defined by TD
-            await thing.invokeAction("startMeasurement", { units: "Celsius" });
-            console.log("Measurement started.");
-          });
-        } catch(e) {
-          console.log("Error starting measurement.");
-        }
-        setTimeout( () => {
-          console.log(“Temperature: “ + await thing.readProperty(“temperature”));
-          await thing.unsubscribe(“ready”);
-          console.log("Unsubscribed from the ‘ready’ event.");
-        },
-        10000);
-
                                -

                                5.4 -

                                7. +

                                +
                                +
                                +5.4 + + +Example + +2 +: +Thing +Client +API +example +
                                
+"hljs-keyword">try {
+  let res = 
+"hljs-keyword">await fetch("https://tds.mythings.org/sensor11");
+  let td = res.json();  let thing = 
+"hljs-keyword">new ConsumedThing(td);
+  console.log(
+"hljs-string">"Thing " + thing.getThingDescription().title + " consumed.");
+} catch(e) {
+  console.log(
+"hljs-string">"TD fetch error: " + e.message); },
+};
+try {  
+"hljs-comment">// subscribe to property change for “temperature”
+  
+"hljs-keyword">await thing.observeProperty("temperature", value => {
+    console.log(
+"hljs-string">"Temperature changed to: " + value);
+  });
+  
+"hljs-comment">// subscribe to the “ready” event defined in the TD
+  
+"hljs-keyword">await thing.subscribeEvent("ready", eventData => {
+    console.log(
+"hljs-string">"Ready; index: " + eventData);
+    
+"hljs-comment">// run the “startMeasurement” action defined by TD
+    
+"hljs-keyword">await thing.invokeAction("startMeasurement", { units: "Celsius" });
+    console.log(
+"hljs-string">"Measurement started.");
+  });
+} catch(e) {
+  console.log(
+"hljs-string">"Error starting measurement.");
+}
+setTimeout( () => {
+  
+"hljs-built_in">console.log(“Temperature: “ + await thing.readProperty(“temperature”));
+  
+"hljs-keyword">await thing.unsubscribe(“ready”);
+  console.log(
+"hljs-string">"Unsubscribed from the ‘ready’ event.");
+},
+
+10000
+
+
+);
+

                                +7. + The + + removeProperty() - ExposedThing + method interface -

                                + + + +

                                Removes the -Property +Property +specified +by +the The - -ExposedThing + + +name + +ExposedThing - -specified -by -the -name -argument + +argument and updates + interface is @@ -10786,34 +13055,166 @@

                                handlers, Property -, +, Action , and - + Event interactions. -

                                5.5 -The -
                                      [SecureContext, Exposed=(Window,Worker)]
-      interface ExposedThing: ConsumedThing {
-        ExposedThing setPropertyReadHandler(DOMString name,
-                PropertyReadHandler readHandler);
-        ExposedThing setPropertyWriteHandler(DOMString name,
-                PropertyWriteHandler writeHandler);
-        ExposedThing setActionHandler(DOMString name, ActionHandler action);
-        void emitEvent(DOMString name, any data);
-        Promise<void> expose();
-        Promise<void> destroy();
-      };
-      callback PropertyReadHandler = Promise<any>(
-              optional InteractionOptions options = null);
-      callback PropertyWriteHandler = Promise<void>(any value,
-              optional InteractionOptions options = null);
-      callback ActionHandler = Promise<any>(any params,
-              optional InteractionOptions options = null);

                                7.1 +

                                +5.5 + +
                                "idl-def-exposedthing" data-title="ExposedThing">[SecureContext, Exposed=(Window,Worker)]
+interface ExposedThing: ConsumedThing {
+  
+"internalDFN" data-link-type=
+"idl">ExposedThing setPropertyReadHandler(DOMString name,
+          
+class="internalDFN" data-link-type=
+"idl">PropertyReadHandler readHandler);
+  
+"internalDFN" data-link-type=
+"idl">ExposedThing setPropertyWriteHandler(DOMString name,
+          
+"#dom-propertywritehandler" class="internalDFN" data-link-type=
+"idl">PropertyWriteHandler writeHandler);
+  
+"internalDFN" data-link-type=
+"idl">ExposedThing setActionHandler(DOMString name, ActionHandler action);
+  
+href=
+"https://heycam.github.io/webidl/#idl-void">void emitEvent(DOMString name, any data);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> expose();
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> destroy();
+};
+callback PropertyReadHandler = Promise<any>(
+        optional InteractionOptions options = null);
+callback PropertyWriteHandler = Promise<void>(any value,
+        optional InteractionOptions options = null);
+callback ActionHandler = Promise<any>(any params,
+        optional InteractionOptions 
+options
+
+
+The
+
+=
+null);
+

                                +7.1 + Constructing @@ -10824,7 +13225,10 @@

                                method -

                                + + +

                                +

                                Adds to the @@ -10842,9 +13246,9 @@

                                interface extends - + ConsumedThing -. +. It is constructed @@ -10856,14 +13260,16 @@

                                full or partial - + ThingDescription - + object object. -

                                Note

                                +

                                +Note +

                                Note that @@ -10871,9 +13277,9 @@

                                Action existing - + ThingDescription - + with name @@ -10925,52 +13331,55 @@

                                argument of type -ActionFragment -, internal properties) - and -adds - the -function -provided -in - -resulting +resulting object can used for constructing an - -ExposedThing - -object. + + +ActionFragment + +ExposedThing + + + +object. This is - the -action -argument - -current +current way of adding and removing - + Property -, -Action - + +, + +Action + and - -Event +adds +the +function +provided +in +the +action +argument + + +Event definitions, @@ -10987,7 +13396,7 @@

                                Thing Description - + examples . @@ -10998,25 +13407,69 @@

                                a reference to +the +same +object +for +supporting +chaining. -

                                Note

                                -Before +

                                +The +provided +action +callback +function +will +implement invoking - -expose() +an +Action +and +SHOULD +be +called +by +implementations +when +a +request +for + +
                                +
                                +
                                + +Note +

                                +Before + +invoking + +expose() , the -same +Action - + + ExposedThing - -object -for -supporting -chaining. + + +is +received +from +the +underlying +platform. +The +callback +will +receive +a -does +object +does not serve any @@ -11025,14 +13478,48 @@

                                allows first constructing - -ExposedThing - + + +parameters + +ExposedThing + + +dictionary +argument +according +to +the +definition +in +the +init.input +argument + + and -then +will +return +a +value +of +type +defined +by +the +init.output +argument +according +to +the +value-matching +algorithm +. + +then initialize its - + Properties and @@ -11043,76 +13530,88 @@

                                serving requests. -

                                The -provided -action -callback -function -will -implement -invoking -

                                To +

                                +
                                +
                                +

                                +There +SHOULD +be +exactly +one +handler +for +any +given +Action +. +If +no +handler +is +initialized +for +any +given +Action +, +implementations +SHOULD +throw +a +TypeError +. + +To construct - an -Action + +5.6 +The + + +removeAction() - ExposedThing + +method + -and -SHOULD -be -called -by -implementations -when -a -request -for -invoking +Removes with the Action - + + ThingDescription - + +specified +by + -td -, +td +, run the following steps: -

                                1. +

                                  1. If invoking this method - is -received -from - -not +not allowed for the -underlying -platform. -The -callback -will -receive -a - -current +current scripting context for @@ -11121,31 +13620,39 @@

                                    throw -parameters +name SecurityError -dictionary -argument -according -to +argument -and -terminate +and +updates + +terminate these steps.

                                  2. Run the -definition -in +Thing +Description +. +Throws +on +error. +Returns expand + a -TD +reference +to + +TD steps on @@ -11158,119 +13665,148 @@

                                    re-throw the -error +same +object +for +supporting +chaining. + +error and terminate these steps. -

                                  3. +
                                  4. Let - - -init.input + +thing + +be +a +new + +5.7 +The -thing - - -argument -and -will -return + +addEvent() -be +ExposedThing -a -value + +method -new - -ExposedThing - -object. + +Adds + +object.
                                  5. Let -|td| +| + +td + +| be -an -internal -slot -of -type +an +event +with +name defined by the +internal +slot +of + -init.output +name thing - -and -let - -td argument -according -to + +and +qualifiers +and +initialization +value +provided +by the -value-matching -algorithm -. -There -SHOULD -be -exactly -one -handler -for -any -given -Action -. -If -no -handler -is -initialized -for -any -given -Action -, -implementations -SHOULD -throw -a -TypeError -. +let + + +event + +td + + +argument +of +type -its +be +its value.
                                  6. Return thing -.
                                  -

                                5.6 -The -removeAction() -method -

                                7.2 -Methods +.

                                +7.2 + +Methods inherited from - -ConsumedThing + + +EventFragment + +ConsumedThing + + +to +the +Thing +object +and +updates +the +Thing +Description +. +Throws +on +error. +Returns +a +reference +to +the +same +object +for +supporting +chaining. +5.8 +The +removeEvent() + +method + + -

                                +

                                +

                                Removes the -Action +event specified by @@ -11298,7 +13834,7 @@

                                as described in - + name @@ -11316,9 +13852,6 @@

                                Thing Description . -Throws -on -error. Returns difference @@ -11340,7 +13873,9 @@

                                underlying platform -MAY + +MAY + be implemented with @@ -11357,129 +13892,131 @@

                                network operations. -

                                5.7 -

                                -The -addEvent() -method +

                                +5.9 +

                                +The implementation of - -ConsumedThing + + +PropertyReadHandler + +ConsumedThing - -Adds + +callback + interface in - an -event - - -ExposedThing - -provide + +ExposedThing + + +provide the - + default - + methods to interact - with -name -defined -by - the -name -argument - - + + ExposedThing -.

                                -After +.

                                +

                                +A +function +that +is +called +when + +After constructing + an - -ExposedThing -, +external +request +for +reading + + + +ExposedThing +, a -script +Property + +script can initialize its - + Properties - + + +is +received. +It +should +return +a +Promise + and -qualifiers +resolves +it +with can set up + the -optional +value +of + +optional read, write - and -initialization -value - -action +action request handlers (the default ones are - provided by + the -event -argument -of -type -EventFragment -to +Property +matching implementation). The script provided handlers -MAY + +MAY + use - the -Thing -object -and -updates - -default +default handlers, thereby extending - the -Thing -Description -. -Throws -on -error. -Returns -a -reference -to - -default +default behavior, but they @@ -11490,142 +14027,35 @@

                                overriding the -same -object -for -supporting -chaining. - -default +default behavior. Finally, the script would call - -5.8 -The - + -removeEvent() +name expose() -method +argument +to -Removes -the -event -specified -by -the -name -argument -and -updates - on the -Thing -Description -. -Returns -a -reference + + +setPropertyReadHandler - ExposedThing - -in -order - -to -the -same -object -for -supporting -chaining. - -start -serving -external -requests. - -

                                5.9 -

                                7.3 -The - -PropertyReadHandler - -callback -

                                -A -function -that -is -called -when -an -external -request -for -reading -a - -Property - -is -received. - -received -and -defines -what -to -do -with -such -requests. - -It -should -return - -returns - -a - -Promise - -and -resolves -it -with - -when -the -value -of -the - -Property - -matching -the - -name -argument -to -the -setPropertyReadHandler -function, +function, or rejects with @@ -11643,10 +14073,39 @@

                                cannot be retrieved. -5.10 + + +in +order +to +start +serving +external +requests. + +

                                +

                                +
                                +

                                +5.10 + + +7.3 + The -PropertyWriteHandler + + +PropertyWriteHandler + +PropertyReadHandler + + + callback + + +

                                +

                                A function that @@ -11657,11 +14116,16 @@

                                external request for -writing +writing + +reading + a + Property + is -received. +received. It is given @@ -11671,34 +14135,62 @@

                                value as argument + +received + and -should +should return + +defines +what +to +do +with +such +requests. +It +returns + a + Promise -which - +which is -resolved +resolved + + +and +resolves +it + when the value of the + Property -that + +that matches + +matching + the + name + argument -has +has been updated with value , -obtained, +is +obtained, or rejects @@ -11847,16 +14339,26 @@

                                retrieved. -

                                5.12 -

                                7.4 +

                                +

                                +
                                +

                                +5.12 + + +7.4 + The - + + setPropertyReadHandler() - + + method -

                                + + +

                                +

                                Takes name @@ -11872,8 +14374,10 @@

                                argument of type - + + PropertyReadHandler + . Sets the @@ -11886,7 +14390,7 @@

                                reading the specified - + Property matched @@ -11911,7 +14415,8 @@

                                for supporting chaining. -

                                +

                                +

                                The readHandler @@ -11929,7 +14434,9 @@

                                Property and -SHOULD + +SHOULD + be called by @@ -11949,12 +14456,15 @@

                                the underlying platform. -

                                +

                                +

                                There -SHOULD +SHOULD -MUST + +MUST + be at most @@ -11963,7 +14473,7 @@

                                for any given - + Property and @@ -11973,8 +14483,9 @@

                                newly added handlers -MUST - + +MUST + replace the old @@ -11990,11 +14501,13 @@

                                for any given - + Property , implementations -SHOULD + +SHOULD + implement a default @@ -12010,14 +14523,22 @@

                                Thing Description . -

                                7.5 -Handling - +

                                +

                                +
                                +

                                + +7.5 + +Handling + Property - + read requests -

                                When +

                                +

                                +When an external @@ -12041,7 +14562,7 @@

                                the runtime -SHOULD +SHOULD execute implementation, @@ -12049,7 +14570,8 @@

                                the following -steps:

                                +steps: +

                                1. Return @@ -12090,66 +14612,36 @@

                                  in the reply - and terminate these steps. -

                                  2. -
                                2. -Otherwise, -if -no - -If +
                                3. +If there is a user provided - read handler -has -been -defined -for - -registered +registered with - + setPropertyReadHandler() -, +, invoke that wih - - + propertyName -, -resolve -promise -with - -return - +, +return the value -of -the -Property -named -propertyName -provided -by - -with - +with the -runtime -implementation - -reply +reply and terminate @@ -12158,31 +14650,43 @@

                                4. Otherwise, -if -there +if +no + +there is a default + read handler -provided +has +been +defined +for + +provided by the implementation, - invoke -it +it with - + + propertyName -, -return +, +resolve +promise +with + +return the -read +value +of -value -with +with the reply and @@ -12195,33 +14699,33 @@

                                  is no default - handler -associated - -defined +defined by the implementation, return - + NotSupportedError - + with -the -reply + +the +reply and terminate these steps. -

                                7.6 +

                                +7.6 + Handling - + Property observe requests -

                                +

                                When a network @@ -12229,93 +14733,94 @@

                                for observing a - + + Property - + +named + propertyName -. - +provided + is received + by the -implementation, +runtime +implementation + +implementation, run the following steps: -
                                1. +

                                  1. If -it -rejects, -then -reject - -a +a Property with - - -promise - -propertyName - - -with - -does + +propertyName + +does not exist, return an error in - the -same -error, -and -resolve -promise - -reply +reply (as defined in the - + Thing Description + +) - -with - -) and terminate these steps. -
                                  2. -Save +
                                    3. +
                                  3. +Otherwise, +invoke + +Save the -same -value. +read +handler +associated +with +propertyName +. +If +it +rejects, +then +reject +promise request sender information to the - + Property 's - + internal observer list @@ -12328,22 +14833,20 @@

                                    to notify about - + Property value changes. - -

                                    4. -
                                  -

                                5.13 -

                                7.7 +

                                +7.7 + The - -PropertyWriteHandler - + +PropertyWriteHandler + callback -

                                +

                                A function that @@ -12356,7 +14859,7 @@

                                for writing a - + Property is @@ -12366,27 +14869,32 @@

                                what to do + with -such +such requests. It expects -the -requested -new - -setPropertyWriteHandler() +the +same +error, -value - - -as +requested +new + +value + +as argument + and -returns +resolve +promise + +returns a - + Promise which @@ -12399,29 +14907,35 @@

                                the Property - -that + + +that matches the - + name - + argument has been updated with - + value -, +, or rejects + with -an +an error if + the -property +same +value. + +property is not found @@ -12431,7 +14945,10 @@

                                cannot be updated. -

                                Editor's note

                                +

                                +Editor's +note +

                                Note that the @@ -12467,17 +14984,26 @@

                                to this function. -

                                7.8 +

                                +

                                +
                                +

                                +5.13 + + +7.8 + The - + + setPropertyWriteHandler() - - + + method -

                                + + + +

                                Takes name @@ -12493,8 +15019,10 @@

                                argument of type - + + PropertyWriteHandler + . Sets the @@ -12507,7 +15035,7 @@

                                writing the specified - + Property matched @@ -12532,12 +15060,15 @@

                                for supporting chaining. -

                                +

                                +

                                There -SHOULD +SHOULD -MUST + +MUST + be at most @@ -12547,7 +15078,7 @@

                                for any given - + Property and @@ -12557,8 +15088,9 @@

                                newly added handlers -MUST - + +MUST + replace the old @@ -12575,11 +15107,13 @@

                                for any given - + Property , implementations -SHOULD + +SHOULD + implement default property @@ -12594,18 +15128,26 @@

                                based on the - + Thing Description . -

                                7.9 -Handling - +

                                +

                                +
                                +

                                + +7.9 + +Handling + Property - + write requests -

                                When +

                                +

                                +When an external @@ -12636,7 +15178,9 @@

                                implementations -SHOULD + +SHOULD + execute run @@ -12644,26 +15188,13 @@

                                the following steps: -Return -a -Promise -promise -and -execute -the -next - + update property - steps -in -parallel -. - -, -given +, +given propertyName , @@ -12677,8 +15208,23 @@

                                to "single" -:

                                  +: +

                                  +
                                  1. +Return +a +Promise +promise +and +execute +the +next +steps +in +parallel +. + If a @@ -12763,7 +15309,7 @@

                                    the runtime implementation -SHOULD +SHOULD update error @@ -12796,7 +15342,7 @@

                                    following to the - + Protocol Bindings .

                                  2. @@ -12806,7 +15352,7 @@

                                    stored in the - + internal observer list @@ -12848,9 +15394,9 @@

                                    the request, return - + NotSupportedError - + in the reply @@ -12864,16 +15410,17 @@

                                    invoke

                                  -

                                > -
                                -When +
                                +
                                +

                                +When a network request for writing multiple - + Properties given @@ -12894,7 +15441,7 @@

                                following steps: -
                                1. +

                                  1. For each property @@ -12942,7 +15489,7 @@

                                    resolve promise - + update property steps @@ -12981,7 +15528,7 @@

                                    according to the - + Protocol Bindings @@ -12993,14 +15540,19 @@

                                    .

                                  -

                                5.14 -

                                7.10 + +

                                +
                                +

                                + +7.10 + The - -ActionHandler - + +ActionHandler + callback -

                                +

                                A function that @@ -13013,9 +15565,9 @@

                                for invoking an - + Action - + is received and @@ -13031,21 +15583,17 @@

                                invoked with a - - -setActionHandler() - -params - - -dictionary + +params + +dictionary argument. It returns a - + Promise - + that rejects with @@ -13058,17 +15606,26 @@

                                action is successful. -

                                7.11 +

                                +

                                +
                                +

                                +5.14 + + +7.11 + The - + + setActionHandler() - - + + method -

                                + + + +

                                Takes name @@ -13084,8 +15641,10 @@

                                argument of type - + + ActionHandler + . Sets the @@ -13119,7 +15678,8 @@

                                for supporting chaining. -

                                +

                                +

                                The action @@ -13129,11 +15689,13 @@

                                will implement an - + Action and -SHOULD + +SHOULD + be called by @@ -13144,7 +15706,7 @@

                                for invoking the - + Action is @@ -13153,12 +15715,15 @@

                                the underlying platform. -

                                +

                                +

                                There -SHOULD +SHOULD -MUST + +MUST + be at most @@ -13167,7 +15732,7 @@

                                for any given - + Action and @@ -13177,8 +15742,9 @@

                                newly added handlers -MUST - + +MUST + replace the old @@ -13186,13 +15752,21 @@

                                previous handlers. -

                                7.12 -Handling - +

                                +

                                +
                                +

                                + +7.12 + +Handling + Action - + requests -

                                When +

                                +

                                +When an external @@ -13215,11 +15789,14 @@

                                received, the runtime -SHOULD + +SHOULD + execute the following -steps:

                                +steps: +

                                1. Return @@ -13305,315 +15882,74 @@

                                  the resulting value - with -a -ReferenceError - -the +the reply - and terminate these steps. -

                                  2. -
                                2. -Otherwise, -invoke -the -Action -handler -associated -with -name -. -If -it -rejects -with -error -, -then -reject -promise -with -the -same -error -, -otherwise -if -it -resolves -with -value -, -then -resolve -promise - -Otherwise +
                                3. +Otherwise return - + NotSupportedError - + with -the -same -value -. - -reply +the +reply and terminate these steps. - -
                                  4. -
                                -

                                5.15 -Examples -

                                7.13 -The - +

                                +7.13 + +The + emitEvent() - + method - -

                                Below -some -ExposedThing -interface -examples -are -given. -Example -5 -: -Create -a -new -exposed -Thing -with -a -simple -property -{ -temperatureValueDefinition = { -, -, - -

                                }; -temperaturePropertyDefinition = temperatureValueDefinition;

                                -

                                temperaturePropertyDefinition.forms = [ ... ]; -thing = WoT.produce({ -, -: { -: temperaturePropertyDefinition -}, -: { -: { -, -: { -: temperatureValueDefinition -}, -, -: [] -}, -}, -: { -: temperatureValueDefinition -}, -: [] -}); -thing.expose(); -, thing);

                                -

                                setInterval( () => { -; -].read(); -(old < mock) { -].write(mock); -thing.emitEvent(, mock); -} -}, ); -} (err) {

                                -
                                  -
                                • err); -} -Example -6 -: -Create -a -new -exposed -Thing -with -object -property -{ -statusValueDefinition = { -, -: { -: { -, -, -,
                                  • -
                                -

                                }, -: { -, -, -, -: { -, -,

                                -

                                } -} -}; -statusPropertyDefinition = statusValueDefinition;

                                -

                                statusPropertyDefinition[] = []; -thing = WoT.produce({ -, -: { -: { -, -, -, -, -}, -: statusPropertyDefinition -}, -: { -: { -, -, -: { -: statusValueDefinition; -}, -: [] -}, -}, -: { -: statusValueDefinition; -}, -: [] -}); -thing.expose().then( { -thing.register(); -}); -} (err) {

                                -
                                  -
                                • err); -} -Example -7 -: -Create -a -new -exposed -Thing -from -a -Thing -Description -'{
                                  "name": "mySensor",
                                  "@context": [ "http://www.w3.org/ns/td",\ -"https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ],
                                  "@type": [ "Thing", "Sensor" ],
                                  "geo:location": "testspace",
                                  "properties": {
                                  "prop1": {
                                  "type": "number",
                                  "@type": [ "Property", "Temperature" ],
                                  "saref:TemperatureUnit": "degree_Celsius"
                                  } } }'; -{
                                  • -
                                -

                                thing = WoT.produce(thingDescription);

                                -

                                ; -thing.setPropertyReadHandler(name, () => {

                                -
                                  -
                                • name); -{ -; -resolve(examplePropertyValue); -}, -e => { -); -}); -}); -thing.expose(); -} (err) {
                                  • -
                                • err); -} -Example -8 -

                                  Takes - +

                                  +Takes + name - + as string argument denoting an - + Event + +name, +and - -: -Create a -new -exposed -Thing -from -a -TD -URI

                                  -

                                  WoT.fetch( {

                                  -

                                  thing = WoT.produce(td);

                                  -

                                  });

                                  • -
                                -

                                6. -Data -types

                                -

                                name, - -and -structures - -a - -data - + +data + argument of - -any - -type. -The -[ -WOT-TD -] -specification -defines + +ReferenceError -method -MUST +any + +type. +The +method + +MUST + run - the -WoT -information -model -, -i.e. - -following +following steps: -

                                -
                                1. +

                                  1. If invoking this @@ -13622,12 +15958,8 @@

                                    not allowed for - the -data -types - -current +current scripting context for @@ -13636,339 +15968,157 @@

                                    throw SecurityError - -and -data -structures -used -in -WoT -Interactions -. -In -this -API - -terminate + +and +terminate these -definitions -translate -to -dictionary -objects -that -are -extended +steps. +

                                    2. +
                                  2. +Otherwise, +invoke +the +Action -steps. -
                                  3. -If +If an - + Event - -with -methods -by - -the -interfaces -defined + + +handler +associated -name - +with +the name - -is + + +name +. +If +it +rejects +with + + +is not found - in -this -specification. -In -order - + +error + this.getThingDescription().events -, -throw - + +, +throw + NotFoundError - + and terminate these steps. -
                                  4. +
                                  5. Make a request - to -avoid -duplication -of -definitions, -references - -the +the underlying platform - to -these - -send +send an - + Event - + with - + data -types -and -structures -is -defined -in -this -section, -but -for -their -full -description -please -refer -to - - -attached + +attached as property, using - the -Thing -Description -specification -. -6.1 - - -Protocol + +Protocol Bindings -, +, then -terminate +terminate these steps. -
                                  -

                                7.14 +

                                +7.14 + The -DataSchema - - expose() - -" data-dfn-for="ExposedThing" data-type="Promise" data-lt="ExposedThing.expose()|ExposedThing.expose|expose()|expose"> -expose() - - -dictionary -and -its -subclasses - -method - -

                                Value -types -basically -represent -types -

                                Start + +method +

                                +Start serving external requests for the - + Thing -, +, so - that -may -be -used -in -JSON -object -definitions -and -are -used -in -ThingFragment - - -WoT + +WoT Interactions - - -to -define - -using - + +using + Properties -, -Event -s -and - - +, Action - -parameters. -Value -types -are -represented -as -dictionary -objects -whose -properties - -s - + +s and -possible -sub-classes -are -defined -in -the -DataSchema -section -of -[ -WOT-TD -]. -One -property -of -all -DataSchema - - -Event - - -dictionary -is - -s + +Event + +s will be possible. The method -MUST + +MUST + run - the -type -property -whose -value -is -from - -following +following steps: -

                                1. +

                                  1. Return - a -set -of -enumerated -strings -defined -in -the -DataSchema -section -of -[ -WOT-TD - - -Promise - - -] - - -promise - + +Promise + +promise + and -is -referred -as -DataType -in -this -specification. -Based -on -type -, - -execute - +execute the -following -sub-classes -of -DataSchema -are -defined - -next +next steps - + in -[ -WOT-TD -]: -BooleanSchema -, -NumberSchema -, -IntegerSchema -, -StringSchema -, -ObjectSchema -, -ArraySchema - -parallel - -. -6.2 -The - -
                                    2. -
                                  2. -If +parallel +.
                                  3. +If invoking this method @@ -13983,197 +16133,102 @@

                                    for security reasons, + reject - + promise - + with - -SecurityScheme - -SecurityError - - -dictionary - -and -its -subclasses -Security -metadata -is -represented -as -dictionary -objects -whose -properties +SecurityError + and -sub-classes -are -defined -in - -terminate +terminate these steps. -

                                  4. +
                                  5. Run the -SecurityScheme -section -of -[ -WOT-TD +same expand a TD - - -]. -One -property -of - -steps + +steps on - the -SecurityScheme -dictionary -is - -internal +internal slot -|td|. +| + + +error +, +otherwise +if +it +resolves + +td + +|.
                                  6. Run - the -scheme -property -whose -value -is -from - - -validate - + +validate a -set -of -enumerated -strings -defined -in -the -SecurityScheme -section -of -[ -WOT-TD - -TD - - -]. -Based - +TD + on -|td|. +| + +td + +|. If that fails, reject - + promise - + with - -type -, -multiple -subclasses -of -SecurityScheme -are -defined. -6.3 -The -Link - -"TypeError" - - -dictionary -Represents -a -Web -Link - -and +"TypeError" + +and terminate these steps. -
                                  7. +
                                  8. For each - + Property - - -with -properties -defined - -definition - + +definition in -the -Link -section -of -[ -WOT-TD -]. -6.4 -The -Form - + -this.instance.properties - +this.instance.properties + initialize an | - -internal -observer -list - - -dictionary -Represents -metadata -describing -service -details, -with -properties -defined - -| + +internal +observer +list + +| internal slot - in -order +order to store observe @@ -14182,382 +16237,180 @@

                                    needed to notify - the -Form -section -of -[ -WOT-TD -]. -6.5 -The -InteractionFragment -dictionary -Represents - -observers +observers on + value -changes. +, + +changes.

                                  9. Set up - the -common -properties -of - - + WoT Interactions -, -one -of -Property -, -Action - - -or -Event -, - -based + +based on introspecting td - + as -defined - -explained - +explained in -[WOT-TD] +[ + +WOT-TD + +] and -[WOT-PROTOCOL-BINDINGS]. +[ + +WOT-PROTOCOL-BINDINGS + +]. Make a request to - the -InteractionPattern - -underlying +underlying platform to initialize the - + Protocol Bindings + +and - -section -of -[ -WOT-TD - -and then -start +start serving external requests for - + WoT Interactions - - -]. -Its -subclasses -are -referred -as -PropertyFragment - -(read, + +(read, write and observe - + Properties - -, -ActionFragment - -invoke - +, +invoke + Action - - -s - + +s and -EventFragment -. -6.6 -The -PropertyFragment -dictionary - -manage - +manage + Event - - -Represents - -subscriptions), + +subscriptions), based on - the -Property -interaction -data -that -initializes -a -ThingProperty -object. -Its -properties - - -Protocol + +Protocol Bindings -. +. The details - are -defined -in - -private +private to - the -Property - -implementations - +implementations and -InteractionPattern -sections - -out - +out of -[ -WOT-TD -]. -6.7 -The -ActionFragment -dictionary -Represents - -scope +scope of this specification. -
                                  10. +
                                  11. If there was an error during - the -Action -interaction -data -that -initializes -a - -request, +request, reject - + promise - + with an - - -ThingAction - -Error - - -object. -Its -properties -are -defined -in -the -Action -and -InteractionPattern -sections -of -[ -WOT-TD -]. -6.8 -The - -object - + +Error + +object + error - + with - - -EventFragment - -error.message - - -dictionary -Represents - -set + +error.message + +set to - the -Event -interaction -data -that -initializes -a -ThingEvent -object. -Its -properties -are -defined -in - -error +error code seen by - the -Event -section -of -[ -WOT-TD - - -Protocol + +Protocol Bindings - - -]. - -and + +and terminate these steps. -
                                  12. +
                                  13. Otherwise + resolve - + promise - -and + +and terminate these steps. -
                                6.9 -

                                7.15 +

                                +7.15 + The -ThingFragment - - destroy() - -" data-dfn-for="ExposedThing" data-type="Promise" data-lt="ExposedThing.destroy()|ExposedThing.destroy|destroy()|destroy"> -destroy() - - -dictionary - -method - -

                                The -ThingFragment -dictionary -is -defined -as -Thing -in -[ -WOT-TD -]. -It -is -a -dictionary -that -contains -properties -representing -semantic -metadata -and -interactions -( -Properties -, -Action -s -and -Event -s). -It -is -used -

                                Stop + +method +

                                +Stop serving external requests - for -initializing -an -internal -representation -of -a - -the - +the + Thing -Description - - + and -its -properties -may - -destroy +destroy the object. Note @@ -14565,147 +16418,75 @@

                                eventual unregistering should - be -used -in -ThingFilter -. -6.10 - -done +done before invoking this method. - The -ThingDescription -type -Serialized -representation -of - -method -MUST +method + +MUST + run - the -Thing -Description -(a -JSON-LD - -following +following steps: -

                                1. +

                                  1. Return a - + Promise -document). -Note -In - -promise - +promise + and execute the next steps - + in parallel -.
                                  2. +.
                                  3. If invoking - this -version -of - -method +method is not allowed for - the -API, -Thing -Description -s -are -represented -as -an -opaque - -current +current scripting context for security reasons, reject - + promise - + with - -USVString - -SecurityError - - -that -can -be -transmitted -between -devices. -7. -Interfaces -for -WoT -Interactions -The -data -types - +SecurityError + and -structures -imported -from -[ -WOT-TD -] -are -extended -by -this -specification -in -order - -terminate +terminate these steps. -
                                  4. +
                                  5. Make a request - to -provide - + the -interfaces +same underlying platform @@ -14714,48 +16495,12 @@

                                    serving external requests - for - + WoT Interactions -. -Every -Thing -describes -its -metadata -as -defined -in -ThingFragment -, -and -basic -interactions -defined -as -Properties - -, -Action -s -and -Event -s. -The -following -interfaces -are -used -for -representing -these -interactions. -7.1 -The - -based +, +based on the @@ -14771,65 +16516,40 @@

                                    the request, reject - -promise + + +value +. + +promise with an - - -Interaction - -Error - - -interface -The - -object + +Error + +object error with - - -Interaction - -error.message - - -interface -is -an -abstract -class - -set - -to -represent -Thing -interactions: -Properties -, -Actions - -the + +error.message + +set +to +the error code seen by the - + Protocol Bindings - - + and -Events -. - -terminate +terminate these steps.

                                  6. @@ -14842,32 +16562,30 @@

                                    terminate these steps. -

                                  -

                                7.16 + + + + +

                                +
                                +

                                +5.15 + + +7.16 + ExposedThing + Examples -

                                -The -InteractionFragment -dictionary -holds -the -common -properties -of -PropertyFragment -, -ActionFragment -and -EventFragment -dictionaries -used -for -initializing -ThingProperty -, + + + +

                                +Below +some -next +The +next example illustrates how @@ -14876,73 +16594,149 @@

                                an -ThingAction - - -ExposedThing - + + +ExposedThing + -and - -ThingEvent - +interface +examples +are +given. + based on a partial TD + +object +constructed +beforehands. +

                                +
                                +
                                + +Example +5 + + +3 + -objects -in +: +Create +a +new +exposed +Thing -object -constructed -beforehands. -

                                -
                                - Example 3: 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 +ExposedThing + +with +a +simple +property + +Property + + +

                                + { + +
                                "hljs javascript">try {
+
+  "hljs-keyword">var temperatureValueDefinition = {
+
+"hljs-keyword">let temperaturePropertyDefinition = {
+
+    type: "number",
+    minimum: -50,
+    maximum: 10000
+  };
+  <span class=
+"hljs-keyword">var temperaturePropertyDefinition = temperatureValueDefinition;
+  
+  temperaturePropertyDefinition.forms = [ ... ];
+   thing = WoT.produce({
+    : <span class=
+"hljs-string">"tempSensor",
+
+  let tdFragment = {
+    properties: {
+      temperature: temperaturePropertyDefinition
+    },
+    actions: {
+      reset: {
+        description: "Reset the temperature sensor",
+        input: {
+          temperature: temperatureValueDefinition
+        },
+        output: null,
+        forms: []
+      },
+    },
+    events: {
+      onchange: temperatureValueDefinition
+    },
+    : []
+  });
+   thing.expose();
+   wot.register(<span class=
+"hljs-string">"https://mydirectory.org", thing);
+  
+  setInterval(  () => {
+     mock = <span class=
+"hljs-built_in">Math.random()*<span class=
+"hljs-number">100;
+     old = <span class=
+"hljs-keyword">await thing[<span class=
+"hljs-string">"temperature"].read();
+     (old < mock) {
+       thing[<span class=
+"hljs-string">"temperature"].write(mock);
+      thing.emitEvent(<span class=
+"hljs-string">"onchange", mock);
+
+    }
+  }, );
+
+  };
+  let thing1 = 
+"hljs-keyword">await WOT.produce(tdFragment);
+  // initialize Properties  
+"hljs-keyword">await thing1.writeProperty("temperature", 0);
+  // add service handlers
+  thing1.setPropertyReadHandler("temperature", () => {
+     
+"hljs-keyword">return readLocalTemperatureSensor();  // Promise
+  });
+  // start serving requests  await thing1.expose();
+} catch (err) {
+   console.log("Error creating ExposedThing: " + err);
+}
+
+
                                +
                                +

                                +The next example illustrates @@ -14951,45 +16745,22 @@

                                add or modify - a -ThingFragment - - -Property - - -dictionary -used -for -creating - -definition + +Property + +definition on - an -ExposedThing -object. -

                                readonly attribute -}; -

                                existing - - -Interaction - - -ExposedThing - - -includes -InteractionFragment - -: -take +existing + +ExposedThing +: +take its - + td - + property, add or @@ -14998,100 +16769,423 @@

                                then create another - + ExposedThing - + +with +that. +

                                +
                                + +Example +6 + + +4 + -; +: +Create +a +new +exposed +Thing +with + +Add +an + +object +property + +Property + + +
                                + { + statusValueDefinition = { + +
                                "hljs javascript">try {
+  
+"hljs-comment">// create a deep copy of thing1's TD
+  let instance = 
+"hljs-built_in">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
+        }
+      }
+  };
+  <span class=
+"hljs-keyword">var statusPropertyDefinition = statusValueDefinition;
+  
+  statusPropertyDefinition[<span class=
+"hljs-string">"forms"] = [];
+   thing = WoT.produce({
+    : <span class=
+"hljs-string">"mySensor",
+    : {
+      : {
+        : <span class=
+
+  instance["name"] = "mySensor";
+  instance.properties["brightness"] = {
+    type: "number",
+        : <span class=
+
+    minimum: 0.0,
+        : <span class=
+
+    maximum: 100.0,
+        : <span class=
+
+    required: true,
+      },
+      <span class=
+"hljs-attr">status: statusPropertyDefinition
+    },
+    : {
+      : {
+        : <span class=
+
+  };
+  instance.properties["status"] = statusValueDefinition;
+  instance.actions["getStatus"] = {
+    description: "Get status object",
+        : <span class=
+
+    input: null,
+        : {
+          <span class=
+"hljs-attr">status : statusValueDefinition;
+        },
+        : []
+      },
+    },
+    : {
+
+    output: {
+      "hljs-attr">onstatuschange: statusValueDefinition;
+
+"hljs-attr">status : statusValueDefinition;
+
+    },
+    : []
+  });
+  thing.expose().then(<span class=
+"hljs-params">() {
+      thing.register();
+
+    forms: [...]
+  };
+  instance.events["onstatuschange"] = statusValueDefinition;
+  instance.forms = [...];  // update
+  var thing2 = 
+"hljs-keyword">new ExposedThing(instance);
+  // 
+"hljs-doctag">TODO: add service handlers
+  await thing2.expose();
+  });
+} catch (err) {
+   console.log("Error creating ExposedThing: " + err);
+}
+Example
+7
+:
+Create
+a
+new
+exposed
+Thing
+from
+a
+Thing
+Description
+        <span class=
+"hljs-keyword">let thingDescription = <span class=
+"hljs-string">'{ \
+  "name": "mySensor", \
+  "@context": [ "http://www.w3.org/ns/td",\
+     "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ],\
+  "@type": [ "Thing", "Sensor" ], \
+  "geo:location": "testspace", \
+  "properties": { \
+    "prop1": { \
+      "type": "number",\
+      "@type": [ "Property", "Temperature" ], \
+      "saref:TemperatureUnit": "degree_Celsius" \
+  } } }';
+ {
+  <span class=
+"hljs-comment">// note that produce() fails if thingDescription contains error
+  <span class=
+"hljs-keyword">let thing = WoT.produce(thingDescription);
+  <span class=
+"hljs-comment">// Interactions were added from TD
+  <span class=
+"hljs-comment">// WoT adds generic handler for reading any property
+  <span class=
+"hljs-comment">// define a specific handler for one property
+   name = <span class=
+"hljs-string">"examplePropertyName";
+  thing.setPropertyReadHandler(name, () => {
+    .log(<span class=
+"hljs-string">"Handling read request for " + name);
+     <span class=
+"hljs-keyword">new <span class=
+"hljs-built_in">Promise(<span class=
+"hljs-function">(<span class=
+"hljs-params">resolve, reject {
+        <span class=
+"hljs-keyword">let examplePropertyValue = <span class=
+"hljs-number">5;
+        resolve(examplePropertyValue);
+      },
+      e => {
+        .log(<span class=
+"hljs-string">"Error");
+      });
+  });
+  thing.expose();
+} (err) {
+   .log(<span class=
+"hljs-string">"Error creating ExposedThing: " + err);
+}
+Example
+8
+:
+Create
+a
+new
+exposed
+Thing
+from
+a
+TD
+URI
+
+
+        <span class=
+"hljs-comment">// fetch an external TD, e.g., to set up a proxy for that Thing
+WoT.fetch(<span class=
+"hljs-string">"http://myservice.org/mySensor/description" {
+  <span class=
+"hljs-comment">// WoT.produce() ignores instance-specific metadata (security, form)
+   thing = WoT.produce(td);
+  <span class=
+"hljs-comment">// Interactions were added from TD
+  
+  
+});
+
+
                                +
                                +

                                + +6. +Data +types +and +structures +The +[ +WOT-TD + +
                                +

                                +] +specification +defines +the +WoT +information +model +, +i.e. +the +data +types +and +data +structures +used +in +WoT +Interactions +. +In +this +API +these +definitions +translate +to +dictionary +objects +that +are +extended +with +methods +by +the +interfaces +defined +in +this +specification. +In +order +to +avoid +duplication +of +definitions, +references +to +these +data +types +and +structures +is +defined +in +this +section, +but +for +their +full +description +please +refer +to +the +Thing +Description +specification +. +6.1 -with -that. -

                                -
                                - Example 4: 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);
-        }
-
                                -

                                8. + +8. + The -forms + + +DataSchema - ThingDiscovery + -read-only -property -represents -the -protocol -bindings -initialization -data +dictionary and +its +subclasses interface -

                                -Discovery - -is -initialized -by + + + +

                                +Value +types +basically +represent +types -a +Discovery +is +a distributed application + that -requires +may +be +used +in +JSON +object +definitions +and +are +used +in +ThingFragment +to +define +Properties +, +Event +s +and +Action +parameters. +Value +types +are +represented +as +dictionary +objects +whose +properties + +requires provisioning + and -support +possible +sub-classes +are +defined +in + +support from participating network @@ -15105,14 +17199,18 @@

                                models the -WoT -Runtime -. +DataSchema +section client side + of -typical +[ +WOT-TD +]. + +typical discovery schemes supported @@ -15121,82 +17219,244 @@

                                IoT deployments. -

                                7.2 -

                                -The -ThingProperty -interface +

                                +

                                +One +property +of +all + +The + + +DataSchema - ThingDiscovery + +dictionary +is +the +type +property +whose +value + object + is -constructed +from + +constructed given + a -filter +set +of +enumerated +strings +defined +in + +filter and provides + the -properties +DataSchema +section +of +[ +WOT-TD +] + +properties + and -methods +is +referred +as +DataType +in +this +specification. +Based +on +type +, + +methods controlling + the -discovery +following +sub-classes +of +DataSchema +are +defined +in +[ +WOT-TD +]: +BooleanSchema +, +NumberSchema +, +IntegerSchema +, +StringSchema +, +ObjectSchema + +discovery process. -

                                      [SecureContext, Exposed=(Window,Worker)]
-      interface ThingDiscovery {
-        constructor(optional ThingFilter filter = null);
-        readonly attribute ThingFilter? filter;
-        readonly attribute boolean active;
-        readonly attribute boolean done;
-        readonly attribute Error? error;
-        void start();
-        Promise<ThingDescription> next();
-        void stop();
-      };
                                Editor's note

                                -The -ThingProperty +

                                
+"idl-def-thingdiscovery" data-title="ThingDiscovery">[SecureContext, Exposed=(Window,Worker)]
+interface ThingDiscovery {
+  
+"dom-thingdiscovery-constructor" data-idl="constructor" data-title=
+"constructor" data-dfn-for="ThingDiscovery" data-lt=
+"ThingDiscovery.constructor()|ThingDiscovery.constructor|constructor()|constructor">constructor(optional ThingFilter filter = null);
+  readonly attribute ThingFilter? filter;
+  readonly attribute boolean active;
+  readonly attribute boolean done;
+  readonly attribute Error? error;
+  
+href=
+"https://heycam.github.io/webidl/#idl-void">void start();
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<ThingDescription> next();
+  
+href=
+"https://heycam.github.io/webidl/#idl-void">void stop();
+};
+
+,
+ArraySchema
 
-
-ThingDiscovery
-
-
-interface
-is
-used
-in
+
                                +
                                +
                                +. +6.2 -has -a + +Editor's +note + +
                                +

                                +The + -ConsumedThing +SecurityScheme -next() +ThingDiscovery -method - +dictionary and -a - - -ExposedThing +its +subclasses -done + +Security +metadata +is +represented +as +dictionary +objects +whose +properties + +interface +has +a + +next() + +method - -objects -to -represent -Thing -Property +and +sub-classes +are +defined +in +the +SecurityScheme +section +of +[ +WOT-TD -property, +a + +done + +property, but it is @@ -15207,109 +17467,109 @@

                                . Look into - + Issue 177 -interactions. +]. for -rationale. - -

                                -The -PropertyFragment -dictionary +rationale. + +

                                +
                                +

                                +One +property +of - -discovery +The + +discovery results internal slot - is -used - -an +an internal queue - for -initializing -Property - -temporarily +temporarily storing + the -found - -ThingDescription +found + + +SecurityScheme + +ThingDescription + -objects -in -a -ThingFragment -dictionary -used -for -creating -an -ExposedThing -object. -It -MUST -implement -one -of +dictionary +is -until +objects +until they are consumed by the -DataSchema -dictionaries. -

                                // getter for PropertyFragment properties

                                // get and set interface for the Property

                                }; -ThingProperty -includes -Observable -; -The -ThingProperty - -

                                application +scheme +property +whose +value +is +from +a +set +of +enumerated +strings +defined +in + +application using + the - -next() +SecurityScheme + + +next() -interface -contains -all +section method. Implementations -MAY + +MAY + optimize - the -properties -defined - -size +size + of -this +[ +WOT-TD +]. +Based + +this queue based on -PropertyFragment +type +, +multiple +subclasses e.g. the @@ -15318,214 +17578,228 @@

                                and the frequency + of -invoking +SecurityScheme + +invoking the next() -as -read-only -properties. +are +defined. method. -

                                + +

                                +6.3 + +

                                The -type + + +Link - filter - -read-only + + +dictionary +Represents +a +Web +Link +with +properties +defined +in -property +property represents + the -discovery +Link +section + +discovery filter -of -type -definition +of +[ +WOT-TD +]. +6.4 +The + +type + + +Form - ThingFilter - -specified + +dictionary + + +Represents +metadata +describing +service +details, +with +properties +defined +in + +specified for + the -Property -as -a -DataSchema -dictionary -object. +Form +section +of +[ +WOT-TD +]. discovery. -

                                +

                                +6.5 The -writable - - -active - - -read-only +InteractionFragment +dictionary -property -tells -whether +

                                +Represents the +common +properties +of +WoT +Interactions +, +one +of Property -value -can -be -updated. -If -it - -is - -false , -then +Action +or +Event +, +as +defined +in the -set(value) +InteractionPattern +section +of +[ +WOT-TD +]. +Its +subclasses +are +referred +as -true - - -method -SHOULD -always -reject. -The -observable -read-only -property -tells -whether +The + + +PropertyFragment -when +active -the -Property -supports -subscribing -to -value -change -notifications. -If -it + +, -discovery + +property +is + + +ActionFragment + +true + +when +the +discovery is -actively +actively ongoing on protocol level (i.e. new - + TD - -s + + +s may still arrive) -and +and -false -, -then -the -subscribe() +EventFragment +false + -method -SHOULD -always -fail. +. otherwise. -

                                +

                                +6.6 + +

                                The -constant -read-only + + +PropertyFragment - done - -property -- -defined -in -DataSchema -- -tells -whether + + + +dictionary +Represents the Property -value +interaction +data +that +initializes +a +property is -a -constant. -If - + -true -, -the -set() -and -subscribe() -methods -SHOULD -always -fail. -The -required -read-only -property -- -defined -in -DataSchema +ThingProperty +true + -- -tells -whether -the -Property -should -be -always -present -on +object. +Its +properties +are +defined +in if the -ExposedThing +Property discovery has @@ -15537,63 +17811,75 @@

                                results to report + and - -discovery +InteractionPattern +sections +of +[ +WOT-TD + + +discovery results -object. +]. is also empty. -

                                +

                                +6.7 + +

                                The -read() + + +ActionFragment - error - -method -will -fetch -the -value -of + + +dictionary +Represents property represents the -Property -. -Returns -a -Promise +Action +interaction +data last error that -resolves -with +initializes +a +ThingAction +object. +Its +properties +are +defined +in occured during the -value, -or -rejects -with -an -error. +Action +and +InteractionPattern +sections +of +[ +WOT-TD +]. discovery process. @@ -15606,86 +17892,160 @@

                                stop discovery. -

                                The -

                                8.1 -Constructing +

                                +6.8 +The + +
                                +

                                + +8.1 + +Constructing -write() +EventFragment ThingDiscovery -method -will -attempt -to -set +dictionary + + + +

                                +
                                +

                                +Represents the -value -of +Event +interaction +data +that +initializes +a -

                                To +To create - -ThingDiscovery - -with + + +ThingEvent + +ThingDiscovery + + + +object. +Its +properties +are +defined +in + +with the -Property +Event +section +of +[ +WOT-TD +]. +6.9 +The +ThingFragment +dictionary +The + + + +ThingFragment - ThingFilter + -specified +dictionary +is +defined +as +Thing in +[ +WOT-TD +]. +It +is +a +dictionary +that +contains +properties +representing +semantic +metadata +and +interactions +( +Properties +, +Action +s +and +Event +s). +It filter , run - the -following +following steps: -

                                1. +

                                  1. If - + filter - + is -not +used +for +initializing + +not + an -object +internal +representation +of +a +Thing +Description +and +its +properties +may +be +used +in + +object or -value -argument -whose -type -SHOULD -match -the -one -specified -by -the +ThingFilter null , throw - - -type - -"TypeError" + +"TypeError" -property. -Returns +. +6.10 +The and terminate @@ -15697,64 +18057,85 @@

                                    discovery be - a -Promise +new + + +ThingDescription -new - -ThingDiscovery +ThingDiscovery + +type + -that -resolves -on -success, -or -rejects -on -an -error. -7.3 -The -ThingAction -interface +Serialized +representation +of object.

                                  2. Set + the - -filter +Thing +Description + + +filter - - -

                                    }; -ThingAction -

                                    property +(a +JSON-LD + +property to filter -.

                                    - -                                     -
                                  3. +.
                                  4. Set active -includes +document). +Note +In +this +version +of +the +API, +Thing +Description and done - -to + + +s +are +represented +as +an +opaque + +to -ActionFragment +USVString +that +can +be +transmitted +between +devices. +7. +Interfaces +for +WoT +Interactions false . @@ -15763,8 +18144,6 @@

                                    error -; - to null @@ -15772,60 +18151,101 @@

                                    Return discovery -.

                                    5. -
                                  -

                                +. +

                                The +data +types +and +structures +imported +from +[ +WOT-TD + start() - -method + + +] +are +extended +by +this +specification +in +order +to +provide +the +interfaces +for +WoT +Interactions +. +Every +Thing + +method sets - + active - -to + + +describes +its +metadata +as +defined +in + +to -invoke() +ThingFragment +, +and +basic +interactions +defined +as +Properties +, +Action true . The stop() - -method -when -invoked, -starts -the -Action + + +s +and +Event -sets - +method +sets + active -interaction -with -the -input -value -provided -by -the -inputValue -argument. -If +s. +The +following +interfaces +are +used +for +representing +these +interactions. +7.1 +The to - - -inputValue -is - -false + +false , but @@ -15836,143 +18256,132 @@

                                still -null -, -the -action -does -not -take -any -arguments -and -rejects +Interaction false - -if -any -arguments - -there + +interface +The + +if +there are -provided. -If -the -value -is -undefined -, -the -action -will -ignore -any -arguments -provided. -Otherwise -the -type -of -inputValue -SHOULD -match -the -DataSchema + + +Interaction - ThingDescription + -definition +interface +is +an +abstract +class +to +represent +Thing +interactions: +Properties +, +Actions objects - in the -input -property. -Returns -a -Promise - - -discovery + +discovery results -that -will -reject -with -an -error -or -will -resolve +and +Events not yet consumed - with -a -value + +next() + +. +

                                +

                                +The +InteractionFragment +dictionary +holds +the +common +properties - -next() -.

                                -During +During successive calls of -type -defined -by -the +PropertyFragment +, +ActionFragment +and +EventFragment +dictionaries +used +for +initializing +ThingProperty next() -, -active - -may + +, +ThingAction + + +active + + +and + +may be -output +ThingEvent true -property. -7.4 -The +objects +in +a or -ThingEvent -interface +ThingFragment false , but - + done -{ -}; +dictionary +used +for +creating +an is set to -ThingEvent +ExposedThing false @@ -15982,168 +18391,261 @@

                                next() -includes +object. +<span class="idlInterface" id= +"idl-def-interaction" data-idl="" data-title= +"Interaction">interface <span class= +"idlInterfaceID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-interaction" class="internalDFN" data-link-type= +"dfn"> {<span class= +"idlAttribute" id="idl-def-interaction-forms" data-idl="" +data-title="forms" data-dfn-for="interaction"> + readonly attribute (<a data-link-for="" +href="#dom-form" class="internalDFN" data-link-type= +"dfn"> or <a href= +"https://heycam.github.io/webidl/#idl-frozen-array">FrozenArray<<a data-link-for="" +href="#dom-form" class="internalDFN" data-link-type= +"dfn"> <span class= +"idlAttrName"><a data-no-default="" data-link-for="interaction" +data-lt="interaction.forms|forms" href="#dom-interaction-forms" +class="internalDFN" data-link-type= +"dfn"> +}; +<a href="#dom-interaction" class="internalDFN" data-link-type= +"dfn"> includes <a href= +"#dfn-interactionfragment" class="internalDFN" data-link-type= +"dfn"> +InteractionFragment only when both - + active - -is + + +; +The + +is -ThingProperty +forms false -and - -discovery +read-only +property +represents +the +protocol +bindings +initialization +data + +and + +discovery results - - -; + +is +initialized +by +the +WoT +Runtime +. -is -empty. -

                                8.2 +empty. + +

                                +

                                +
                                +

                                +7.2 + + +8.2 + The - -DiscoveryMethod - -enumeration -

                                typedef DOMString DiscoveryMethod;

                                -Since -ThingEvent -implements -Observable -through + + +ThingProperty -Represents +DiscoveryMethod -the + + +interface + +enumeration + + +

                                +The + +
                                "idl-def-discoverymethod" data-title=
+"DiscoveryMethod">typedef DOMString 
+
+
 ThingProperty
 
-discovery
+DiscoveryMethod
+
+
+
+interface
+is
+used
+in
+ConsumedThing
+
+;
+
+and
+
+
                                +

                                +Represents +the +discovery type to be used:

                                • +ExposedThing + -"any" - +"any" + does not provide any restriction -
                                • -"local" - +
                                • +objects +to +represent + + +"local" + for discovering - + Thing - -interface, -event -subscription -is -done -by -invoking +Property +interactions. +The s defined in - the -subscribe() -method -on - -same +same device or connected to - the -event -object -that -returns - -device +device by wired or wireless means. -
                                • -"directory" +
                                • +PropertyFragment + + +"directory" for discovery based on - a -cancelable -Subscription - -service +service provided by a - + Thing Directory - -. -
                                  • -
                                • +.
                                • +dictionary +is +used + "multicast" - + for -discovering +initializing +Property + +discovering Thing - -s + + +objects + +s + in -the +the device's network by using + a -supported +supported multicast protocol. -

                                7.5 -

                                8.3 +

                                +8.3 + The -ExposedEvent + + +ThingFragment - ThingFilter + -interface +dictionary +used +for +creating +an +ExposedThing -dictionary - -

                                -void -}; -

                                -Represents + + +object. +It +MUST +implement +one +of +the +DataSchema + + +

                                +Represents an object containing @@ -16151,72 +18653,284 @@

                                constraints for discovering - + Thing - -s + + +dictionaries. + +s as key-value pairs. -

                                        dictionary ThingFilter {
-          (DiscoveryMethod or DOMString) method = "any";
-          USVString? url;
-          USVString? query;
-          object? fragment;
-        };
                                7.5.1 -

                                + +

                                +<span class="idlInterface" id= +"idl-def-thingproperty" data-idl="" data-title= +"ThingProperty">interface <span class= +"idlInterfaceID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-thingproperty" class="internalDFN" data-link-type= +"dfn"> : <span class= +"idlSuperclass"><a href="#dom-interaction" class="internalDFN" +data-link-type= +"dfn"> {<span class="idlMethod" +id="idl-def-thingproperty--name" data-idl="" data-title="" +data-dfn-for="thingproperty"> + // getter for PropertyFragment properties + <a href= +"https://heycam.github.io/webidl/#idl-any">any<span class="idlMethod" +id="idl-def-thingproperty-read" data-idl="" data-title="read" +data-dfn-for="thingproperty"><span class= +"idlSectionComment"> + // get and set interface for the Property + <a href= +"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default="" +data-link-for="thingproperty" data-lt= +"thingproperty.read()|thingproperty.read|read()|read" href= +"#dom-thingproperty-read" class="internalDFN" data-link-type= +"dfn"><span class="idlMethod" +id="idl-def-thingproperty-write-value" data-idl="" data-title= +"write" data-dfn-for="thingproperty"> + <a href= +"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default="" +data-link-for="thingproperty" data-lt= +"thingproperty.write()|thingproperty.write|write()|write" href= +"#dom-thingproperty-write" class="internalDFN" data-link-type= +"dfn">(<span class= +"idlParam"><a href= +"https://heycam.github.io/webidl/#idl-any">any +}; +<a href="#dom-thingproperty" class="internalDFN" data-link-type= +"dfn"> includes <a href= +"#dom-propertyfragment" class="internalDFN" data-link-type= +"dfn"><span class= +"idlIncludes"> +<a href="#dom-thingproperty" class="internalDFN" data-link-type= +"dfn"> includes <a href= +"#dom-observable" class="internalDFN" data-link-type= +"dfn"> +Observable +; + +
                                "idl-def-thingfilter" data-title="ThingFilter">dictionary ThingFilter {
+  (DiscoveryMethod or DOMString) method = "any";
+  
+href=
+"https://heycam.github.io/webidl/#idl-USVString">USVString? url;
+  
+href=
+"https://heycam.github.io/webidl/#idl-USVString">USVString? query;
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-object">object? fragment;
+};
+
+
+
                                +

                                The -emit() +ThingProperty +interface +contains +all +the +properties +defined +on - -method -Emits -an -event + + +PropertyFragment + +method + + +as +read-only +properties. +The +type -property +read-only + +property represents the -discovery -type +discovery -that -carries -data -specified +type +definition +for +the +Property +as +a +DataSchema +dictionary +object. +The +writable +read-only +property +tells +whether +the +Property +value +can -should +that +should + be -used +updated. +If +it +is +false +, +then +the +set(value) +method +SHOULD +always +reject. +The +observable +read-only +property +tells +whether +the +Property +supports +subscribing +to +value +change +notifications. +If +it +is +false +, +then + +used in + the -discovery +subscribe() +method +SHOULD +always +fail. + +discovery process. + The -possible +constant +read-only +property +- + +possible values are + defined +in +DataSchema +- +tells +whether +the +Property +value +is +a +constant. +If +true +, + +by -by the -payload -argument. -7.6 +set() +and +subscribe() +methods +SHOULD +always +fail. The -value-matching -algorithm +required + +read-only +property +- +defined +in - -DiscoveryMethod + + +DataSchema + +DiscoveryMethod + +- +tells +whether +the +Property +should +be +always +present +on +the + +ExposedThing + +object. + enumeration that -MAY + +MAY + be extended by @@ -16230,34 +18944,32 @@

                                guarantee of interoperability). -

                                + +

                                +

                                The -value-matching -algorithm -is -applied -to -a -value -input -in -relation -to -a -valueType + + +read() + +url + + + +method +will +fetch - -url - -property -represents +property +represents additional information for + the -discovery +value + +discovery method, such as @@ -16265,29 +18977,60 @@

                                URL of -type -DataSchema -, +the +Property +. +Returns +a +Promise +that +resolves +with -the -target +target entity serving + the -discovery +value, +or +rejects +with +an +error. +The +write() +method +will +attempt +to +set + +discovery request, - for instance + the -URL +value + +URL + of -a - +the +Property + +a + Thing Directory - -(if + + +specified +in +the + +(if value @@ -16295,7 +19038,16 @@

                                method -and +argument +whose +type +SHOULD +match +the +one +specified +by +the is @@ -16305,56 +19057,147 @@

                                "directory" -properties +property. +Returns ) or that - of + a -PropertyFragment +Promise - + Thing -object, +that +resolves +on +success, or -the -inputValue -parameter -to +rejects +on +an +error. (otherwise). -

                                + +

                                +7.3 The - -query - -property +ThingAction +interface +<span class="idlInterface" id= +"idl-def-thingaction" data-idl="" data-title= +"ThingAction">interface <span class= +"idlInterfaceID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-thingaction" class="internalDFN" data-link-type= +"dfn"> : <span class= +"idlSuperclass"><a href="#dom-interaction" class="internalDFN" +data-link-type= +"dfn"> {<span class="idlMethod" +id="idl-def-thingaction-invoke-inputvalue" data-idl="" data-title= +"invoke" data-dfn-for="thingaction"> + <a href= +"https://heycam.github.io/webidl/#idl-promise">Promise<a data-no-default="" +data-link-for="thingaction" data-lt= +"thingaction.invoke()|thingaction.invoke|invoke()|invoke" href= +"#dom-thingaction-invoke" class="internalDFN" data-link-type= +"dfn">(<span class= +"idlParam">optional <a href= +"https://heycam.github.io/webidl/#idl-any">any +}; +<a href="#dom-thingaction" class="internalDFN" data-link-type= +"dfn"> includes <a href= +"#dom-actionfragment" class="internalDFN" data-link-type= +"dfn"> +ActionFragment +; + +

                                +The + + +invoke() + +query + + + +method +when +invoked, +starts +the +Action +interaction +with +the +input +value +provided + +property represents a query string accepted -by +by the -invoke() -method +inputValue +argument. +If +inputValue +is +null +, +the +action +does +not +take +any +arguments +and +rejects +if +any +arguments +are +provided. +If +the +value +is +undefined +, +the +action +will +ignore +any +arguments +provided. +Otherwise +the +type of +inputValue +SHOULD +match +the +DataSchema +definition implementation, for instance - a -ThingAction - -SPARQL +SPARQL or JSON query. @@ -16363,40 +19206,119 @@

                                be implemented locally + in the - -WoT +input +property. +Returns +a +Promise + + +WoT Runtime -object +that +will +reject +with +an +error -or -remotely +or +will +resolve +with + +remotely as -a -service -in -relation -to +a +value +of +type +defined +by +the +output +property. -a - +service +in +a + Thing Directory -.

                                +. +

                                +7.4 + +

                                The - -fragment - -property + + +ThingEvent + +fragment + + + +interface +<span class="idlInterface" id= +"idl-def-thingevent" data-idl="" data-title= +"ThingEvent">interface <span class= +"idlInterfaceID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-thingevent" class="internalDFN" data-link-type= +"dfn"> : <span class= +"idlSuperclass"><a href="#dom-interaction" class="internalDFN" +data-link-type="dfn"> { +}; +<a href="#dom-thingevent" class="internalDFN" data-link-type= +"dfn"> includes <a href= +"#dom-eventfragment" class="internalDFN" data-link-type= +"dfn"><span class= +"idlIncludes"> +<a href="#dom-thingevent" class="internalDFN" data-link-type= +"dfn"> includes <a href= +"#dom-thingproperty" class="internalDFN" data-link-type= +"dfn"> +ThingProperty +; +Since +ThingEvent +implements +Observable +through +the +ThingProperty +interface, +event +subscription +is +done +by +invoking +the +subscribe() +method +on +the +event +object +that +returns + +property represents + a -template +cancelable +Subscription +. + +template object used for @@ -16406,63 +19328,111 @@

                                property against discovered - + Thing s. -

                                8.4 + +

                                +

                                +
                                +

                                +7.5 + + +8.4 + The - -start() - -method -

                                -Starts + + +ExposedEvent + +start() -the -same -object. -It -executes + + +interface -discovery +method + + + +
                                +<span class="idlInterface" id= +"idl-def-exposedevent" data-idl="" data-title= +"ExposedEvent">interface <span class= +"idlInterfaceID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-exposedevent" class="internalDFN" data-link-type= +"dfn"> : <span class= +"idlSuperclass"><a href="#dom-thingevent" class="internalDFN" +data-link-type= +"dfn"> {<span class="idlMethod" +id="idl-def-exposedevent-emit-payload" data-idl="" data-title= +"emit" data-dfn-for="exposedevent"> + void<a data-no-default="" +data-link-for="exposedevent" data-lt= +"exposedevent.emit()|exposedevent.emit|emit()|emit" href= +"#dom-exposedevent-emit" class="internalDFN" data-link-type= +"dfn">(<span class= +"idlParam"><a href= +"https://heycam.github.io/webidl/#idl-any">any +}; +7.5.1 + +

                                +Starts +the +discovery process. + The +emit() + method -MUST +Emits +an +event +that +carries +data +specified +by + + +MUST + run the -following +payload +argument. + +following steps: + +

                                +7.6 +The +value-matching +algorithm +The +value-matching +algorithm +
                                1. -If -valueType.type - -invoking +If +invoking this method is -not -defined, -or -does -not -fully -match +applied +to a -string -enumerated -in -DataType -, -return -allowed +not +allowed for the current @@ -16472,160 +19442,100 @@

                                  security reasons, set - -this.error - -to + +value + +this.error + + +input +in +relation + +to +a +valueType +property +of +type + -false -. +DataSchema SecurityError - -and + + +, +for +instance + +and terminate these steps. - -

                                  2. -
                                2. -Otherwise, -if -valueType.type - -If +
                                3. +If discovery - is -"null" -: -if - -not +not supported by + the -implementation, +implementation, set - - -value - -this.error - - -is -null -, -return -true -, -otherwise -return - -to + +this.error + +to -false -. +value NotSupportedError - + + and -terminate +type +properties +of + +terminate these steps. - -
                                  4. -
                                4. -Otherwise, -if - -If - - -valueType.type - -this.filter - - +
                                5. +If + +this.filter + is -"boolean" -: -if - -defined, +defined,
                                  • Let - - -value - -filter - - -is -either -true -or -false -, -then -return -true -, -otherwise -return -false -. - -denote + +filter + +denote this.filter -. -
                                    • -
                                  • -Otherwise, -if -valueType.type -is -"integer" -: -if - -If - - -value - -filter.query - - +.
                                  • +If + +filter.query + is -not - -defined, +defined, pass it as - an -integer -type -defined -by - -opaque +opaque string to - the underlying -platform -(such - -implementation +implementation to be matched @@ -16641,12 +19551,13 @@

                                    parse it e.g. - as -long + +a +PropertyFragment +object, -a -SPARQL +SPARQL or JSON @@ -16663,8 +19574,9 @@

                                    s found during + the -discovery +discovery process. If queries @@ -16672,25 +19584,27 @@

                                    not supported, set - -this.error - -to + +inputValue + +this.error + + +parameter + +to +the + -long -long +invoke() NotSupportedError -), -then -return -false -, -otherwise -execute +method +of +a and terminate @@ -16708,62 +19622,99 @@

                                    for storing discovered - -ThingDescription - -objects. + + +ThingAction + +ThingDescription + + + +object +in +relation + +objects.

                                  • Request the underlying platform + to -start +start + the -discovery +same +object. +It +executes + +discovery process, with the following -sub-steps: +steps: parameters:
                                    • If -valueType.minimum +valueType.type filter.method is -not - -defined -and +not +defined, -or -the +defined -value -is -not -greater or -equal -than -that -value, +does +not +fully +match +a +string +enumerated +in +DataType +, return false . +Otherwise, +if +valueType.type +is +"null" +: +if +the + +value +is +null +, +return +true + "any" -, -use + +, +otherwise +return +false +. + +use the widest discovery @@ -16776,6 +19727,165 @@

                                    • +Otherwise, +if +valueType.type +is +"boolean" +: + +Otherwise + +if + +value + +filter.method + + +is +either +true +or +false +, +then +return + + +true + +"local" + +, +otherwise +return +false +. + +use +the +local + +Thing +Directory + +for +discovery. +Usually +that +defines + +Thing + +s +deployed +in +the +same +device, +or +connected +to +the +device +in +slave +mode +(e.g. +sensors +connected +via +Bluetooth +or +a +serial +connection). + +
                                      • +
                                    • +Otherwise, +if +valueType.type +is +"integer" +: + +Otherwise + +if + +value + +filter.method + + +is +not +an +integer +type +defined +by +the +underlying +platform +(such +as +long +or +long +long +), +then +return + + +false + +"directory" + +, +otherwise +execute + +use + +the +following +sub-steps: +If +valueType.minimum +is +defined +and +value +is +not +greater +or +equal +than +that +value, +return + +remote + +Thing +Directory + +specified +in + + +false + +filter.url + +. +
                                      • +
                                    • If valueType.maximum is @@ -16802,92 +19912,67 @@

                                      return false . -Return -true -. - -"local" +"multicast" , use +all the -local - -Thing -Directory - -for -discovery. -Usually -that -defines - -Thing - -s -deployed -in +multicast +discovery +protocols +supported +by the -same -device, -or -connected -to +underlying +platform. +

                                    +
                                    • +
                                  • +Return + +When the -device -in -slave -mode -(e.g. -sensors -connected -via -Bluetooth -or -a -serial -connection). +underlying +platform +has +started +the +discovery +process, +set +the + +active + +property +to + +true +.
                                  • Otherwise, - -Otherwise - if - -valueType.type - -filter.method - - +valueType.type is - -"number" +"number" +, +if -"directory" - -, -use -the -remote - +Whenever +a +new + Thing -Directory - -specified -in - -filter.url -.
                                  • -Otherwise - -if +Description + value -filter.method +td is @@ -16900,80 +19985,30 @@

                                    type defined - -"multicast" -, -use -all -the -multicast -discovery -protocols -supported +discovered by the underlying -platform. -

                                6. -When -the -underlying - -platform -(such +platform +(such as long or long long or - -has -started -the -discovery -process, -set -the - - -double - -active - - -), +double +), then return - -property -to - - -false +false , otherwise otherwise execute -true -.
                                7. -Whenever -a -new - -Thing -Description - -td - -is -discovered -by -the -underlying -platform, +platform, run the @@ -17252,7 +20287,7 @@

                                  to the - + discovery results . @@ -17264,7 +20299,9 @@

                                  this point implementations -MAY + +MAY + control the flow @@ -17393,7 +20430,7 @@

                                  provided by the - + Protocol Bindings , @@ -17542,88 +20579,104 @@

                                  .

                                -

                                8.5 -The - -next() +Otherwise, +if +type +is + + +

                                +
                                +

                                + +8.5 + +The + + +"object" +, +execute + +next() method -

                                +

                                Provides the next discovered - + ThingDescription - + object. The method -MUST + +MUST + run + the following -steps: -

                                  +sub-steps: + +steps: +

                                  +
                                  1. -Otherwise, -if +If Return a - + Promise -type +value promise is -"object" +not +an +Object , +return +false +. and - execute the -following -sub-steps: - -next +next steps - + in parallel -.
                                    2. +. +
                                  2. If -value +valueType.properties this.active is not -an +defined, +return -Object - -true - -, -return -false +false . -If -valueType.properties -wait +true +, +wait until the @@ -17632,15 +20685,9 @@

                                    internal slot - is not -defined, -return -false -. - -empty. +empty.

                                  3. @@ -17713,9 +20760,9 @@

                                    value.properties first - + ThingDescription - + object or in @@ -17804,29 +20851,39 @@

                                  -
                                8. + + +
                                +

                                +8. Observables -This + + +8.6 + +The + + +stop() + + +method + +This section is non-normative. -Observables -

                                8.6 -The - -stop() - - -are + + +

                                +
                                +

                                +Observables +are proposed to -method -

                                -Stops +Stops or suppresses the @@ -17904,23 +20961,82 @@

                                support for interoperability. - - -
                                               optional
-               optional

                                }; -

                                interface -void -readonly attribute -}; -callback -callback -callback -OnComplete -= +<span class="idlInterface" id= +"idl-def-observable" data-idl="" data-title= +"Observable">interface <span class= +"idlInterfaceID"><a data-no-default="" data-link-for="" data-lt="" +href="#dom-observable" class="internalDFN" data-link-type= +"dfn"> {<span class="idlMethod" +id="idl-def-observable-subscribe-handler-errorhandler-oncomplete" +data-idl="" data-title="subscribe" data-dfn-for= +"observable"> + <a data-link-for="" href="#dom-subscription" class="internalDFN" +data-link-type= +"dfn"> <span class= +"idlMethName"><a data-no-default="" data-link-for="observable" +data-lt="subscribe|subscribe()" href="#dom-observable-subscribe" +class="internalDFN" data-link-type= +"dfn">(<span class= +"idlParam"><a href= +"https://www.w3.org/TR/html52/single-page.html#typedefdef-eventhandler">EventHandler + optional<span class= +"idlParamType"> <a data-link-for="" href="#dom-errorhandler" class= +"internalDFN" data-link-type= +"dfn"> <span class= +"idlParamName">errorHandler + optional<span class= +"idlParamType"> <a data-link-for="" href="#dom-oncomplete" class= +"internalDFN" data-link-type= +"dfn"> <span class= +"idlParamName">onComplete +};<span class="idlInterface" id="idl-def-subscription" +data-idl="" data-title="Subscription"> +interface <a data-no-default="" +data-link-for="" data-lt="" href="#dom-subscription" class= +"internalDFN" data-link-type= +"dfn"> {<span class="idlMethod" +id="idl-def-subscription-unsubscribe" data-idl="" data-title= +"unsubscribe" data-dfn-for="subscription"><span class= +"idlMethType"> + void<a data-no-default="" +data-link-for="subscription" data-lt="unsubscribe|unsubscribe()" +href="#dom-subscription-unsubscribe" class="internalDFN" +data-link-type= +"dfn"><span class= +"idlAttribute" id="idl-def-subscription-closed" data-idl="" +data-title="closed" data-dfn-for="subscription"> + readonly attribute <a href= +"https://heycam.github.io/webidl/#idl-boolean">boolean<a data-no-default="" +data-link-for="subscription" data-lt="subscription.closed|closed" +href="#dom-subscription-closed" class="internalDFN" data-link-type= +"dfn"> +};<span class="idlCallback" id="idl-def-eventhandler" +data-idl="" data-title="EventHandler"> +callback <a data-no-default="" +data-link-for="" data-lt="" href="#dom-eventhandler" class= +"internalDFN" data-link-type= +"dfn"> =<span class= +"idlCallbackType"> void<span class= +"idlParamType"><a href= +"https://heycam.github.io/webidl/#idl-any">any<span class="idlCallback" +id="idl-def-errorhandler" data-idl="" data-title="ErrorHandler"> +callback <a data-no-default="" +data-link-for="" data-lt="" href="#dom-errorhandler" class= +"internalDFN" data-link-type= +"dfn"> =<span class= +"idlCallbackType"> void<span class= +"idlParamType"><a href= +"https://heycam.github.io/webidl/#idl-Error">Error<span class="idlCallback" +id="idl-def-oncomplete" data-idl="" data-title="OnComplete"> +callback <a data-no-default="" +data-link-for="" data-lt="" href="#dom-oncomplete" class= +"internalDFN" data-link-type= +"dfn"> =<span class= +"idlCallbackType"> void (); -

                                -

                                the + +the discovery is marked @@ -17928,7 +21044,9 @@

                                The method -MUST + +MUST + run the @@ -17945,7 +21063,8 @@

                                : steps: -

                                + +

                                1. The @@ -18028,7 +21147,9 @@

                                  about. implementation -SHOULD + +SHOULD + discard subsequent discovered @@ -18064,35 +21185,44 @@

                                  Subscription -interface false -.

                                +.

                                +interface -

                                8.7 + +8.7 + Discovery Examples - -

                                + + + +

                                Contains the -closed -property The following example finds - -ThingDescription - -objects + + +closed + +ThingDescription + + +property + + +objects of type boolean - + Thing s @@ -18113,7 +21243,7 @@

                                many instances of - + WoT Runtime @@ -18156,7 +21286,7 @@

                                platform internal - + discovery results @@ -18174,13 +21304,26 @@

                                from the source, +and +sets +the continue reading - -ThingDescription - -objects + + +closed + +ThingDescription + + +property +to +false +. + + +objects until done. This @@ -18188,45 +21331,70 @@

                                typical with local - and -sets -the -closed -property -to -false -. - -directory +directory type discoveries. -

                                8.2 -The -Observable -interface -
                                -
                                - Example 5: Discover Things exposed by local hardware - 
                                        let discovery = new ThingDiscovery({ method: "local" });
-        do {
-          let td = await discovery.next();
-          console.log("Found Thing Description for " + td.title);
-          let thing = new ConsumedThing(td);
-          console.log("Thing name: " + thing.getThingDescription().title);
-        } while (!discovery.done);
-
                                -

                                -The +

                                +
                                +
                                +8.2 + + +Example + +5 +: +Discover +Things +exposed +by +local +hardware + + +The + Observable +
                                +
                                "hljs-keyword">let discovery = new ThingDiscovery({ method: "local" });
+do {  let td = 
+"hljs-keyword">await discovery.next();
+  console.log(
+"hljs-string">"Found Thing Description for " + td.title);
+  let thing = 
+"hljs-keyword">new ConsumedThing(td);
+  console.log(
+"hljs-string">"Thing name: " + thing.getThingDescription().title);
+} 
+while
+
+(!discovery.done);
+
+
+interface
+
+
                                +
                                +

                                +The next example finds - -ThingDescription + + +Observable + +ThingDescription + interface enabled @@ -18237,13 +21405,10 @@

                                notifications by the -subscribe -() -method: objects of - + Thing s @@ -18261,8 +21426,50 @@

                                timeout for safety. +

                                +subscribe + + +Example + +6 +: +Discover +Things +via +directory +
                                
+"hljs-keyword">let discoveryFilter = {
+  method: 
+"hljs-string">"directory",
+  url: 
+"hljs-string">"http://directory.wotservice.org"
+};
+let discovery = 
+"hljs-keyword">new ThingDiscovery(discoveryFilter);
+setTimeout( () => {
+    discovery.stop();
+    console.log(
+"hljs-string">"Discovery stopped after timeout.");
+  },
+  3000);do {  let td = 
+"hljs-keyword">await discovery.next();
+  console.log(
+"hljs-string">"Found Thing Description for " + td.title);
+  let thing = 
+"hljs-keyword">new ConsumedThing(td);
+  console.log(
+"hljs-string">"Thing name: " + thing.getThingDescription().title);
+} while (!discovery.done);
+if (discovery.error) {  console.log(
+"hljs-string">"Discovery stopped because of an error: " + error.message);
+}
 
-
                                Initialize
+                                
+()
+method:
+Initialize
 the
 data
 handler
@@ -18274,31 +21481,11 @@ 
                                
 argument.
 If
 the
-
                                
-          
                                
-      Example 6: Discover Things via directory
-    
                                 
                                        let discoveryFilter = {
-          method: "directory",
-          url: "http://directory.wotservice.org"
-        };
-        let discovery = new ThingDiscovery(discoveryFilter);
-        setTimeout( () => {
-            discovery.stop();
-            console.log("Discovery stopped after timeout.");
-          },
-          3000);
-        do {
-          let td = await discovery.next();
-          console.log("Found Thing Description for " + td.title);
-          let thing = new ConsumedThing(td);
-          console.log("Thing name: " + thing.getThingDescription().title);
-        } while (!discovery.done);
-        if (discovery.error) {
-          console.log("Discovery stopped because of an error: " + error.message);
-        }
-
                                
-        
                                
-The
+
+
                                +
                                +

                                +The next argument @@ -18401,28 +21588,53 @@

                                one by one. -

                                -
                                - Example 7: Discover Things in a network - 
                                        let discovery = new ThingDiscovery({ method: "multicast" });
-        setTimeout( () => {
-            discovery.stop();
-            console.log("Stopped open-ended discovery");
-          },
-          10000);
-        do {
-          let td = await discovery.next();
-          let thing = new ConsumedThing(td);
-          console.log("Thing name: " + thing.getThingDescription().title);
-        } while (!discovery.done);
-
                                -

                                9. -9. - +

                                +Example + +7 +: +Discover +Things +in +a +network +
                                
+"hljs-keyword">let discovery = new ThingDiscovery({ method: "multicast" });
+setTimeout( () => {
+    discovery.stop();
+    console.log(
+"hljs-string">"Stopped open-ended discovery");
+  },
+  10000);do {  let td = 
+"hljs-keyword">await discovery.next();
+  let thing = 
+"hljs-keyword">new ConsumedThing(td);
+  console.log(
+"hljs-string">"Thing name: " + thing.getThingDescription().title);
+} 
+while
+
+(!discovery.done);
+
                                +

                                + +
                                +

                                + +9. + Security and Privacy -

                                + + + +

                                In general the @@ -18485,12 +21697,16 @@

                                the informative document -[ -WOT-SECURITY-CONSIDERATIONS -]. +[ + +WOT-SECURITY-CONSIDERATIONS -[WOT-SECURITY-GUIDELINES]. + +WOT-SECURITY-GUIDELINES + + +]. This section includes @@ -18523,7 +21739,8 @@

                                Scripting API. -

                                +

                                +

                                When designing new @@ -18560,17 +21777,21 @@

                                documented in -[ +[ + + WOT-SECURITY-BEST-PRACTICES -] + + +] that -SHOULD +SHOULD be followed. This best-practices -[WOT-SECURITY-BEST-PRACTICES]. +]. That document @@ -18608,13 +21829,17 @@

                                vulnerabilities. -

                                Below +

                                +
                                +

                                +Below are specific recommendations related to -

                                The + +The WoT runtime @@ -18630,7 +21855,8 @@

                                the following groups: -

                                + +

                                9.1 +

                                +9.1 + Scripting Runtime Security and Privacy Risks -

                                +

                                This section @@ -18899,7 +22131,7 @@

                                the WoT runtime -SHOULD +SHOULD perform isolation of @@ -18909,7 +22141,9 @@

                                Scripting Runtime. -

                                9.1.1 +

                                +9.1.1 + Corrupted Input Security @@ -18921,7 +22155,7 @@

                                Privacy Risk -

                                +

                                A typical way @@ -18963,33 +22197,6 @@

                                the WoT Runtime -using -platform -security -mechanisms -available -on -the -device. -For -more -information -see -Section -"WoT -Servient -Single-Tenant" -and -"WoT -Servient -Multi-Tenant" -of -[ -WOT-SECURITY-CONSIDERATIONS -]. -WoT -scripts -are done to @@ -18998,10 +22205,13 @@

                                instance using -WoT -Scripting +platform +security +mechanisms +available -interface +WoT +interface it exposes.

                                @@ -19010,36 +22220,25 @@

                                Implementors of this - API -to -implement -the -functionality -and -logic -for -WoT -Things. - -SHOULD + +SHOULD + perform validation + on -all +all script inputs. - In addition to -providing - -input +input validation, - + fuzzing - + should be used @@ -19048,9 +22247,15 @@

                                that the -isolation -between -script +device. +For +more +information +see +Section +"WoT +Servient +Single-Tenant" input processing @@ -19063,21 +22268,16 @@

                                tools and -runtime -instances, -the -WoT -runtime -needs +"WoT +Servient +Multi-Tenant" +of techniques in existence - to -protect - -do +do such validation. More @@ -19086,22 +22286,75 @@

                                be found in -[WOT-SECURITY-TESTING]. -

                                9.1.2 + +[ + +WOT-SECURITY-CONSIDERATIONS + + +WOT-SECURITY-TESTING + + + +]. +WoT +scripts +are +using +WoT +Scripting +API +to +implement +the +functionality + + + +

                                +
                                +

                                + +9.1.2 + Physical Device Direct Access Security + and -Privacy +logic +for +WoT +Things. + +Privacy Risk -

                                +

                                In -case +addition +to +providing +the +isolation +between + +case a + script -is +and +runtime +instances, +the +WoT +runtime +needs +to +protect + +is compromised or misbehaving, @@ -19172,7 +22425,9 @@

                                Scripting Runtime -SHOULD + +SHOULD + avoid directly exposing @@ -19264,17 +22519,16 @@

                                a particular WoT - script based on its functionality. -Therefore +Therefore the WoT Runtime -SHOULD +SHOULD only expose a @@ -19285,20 +22539,28 @@

                                to a WoT + script based on its -intended -functionality. +intended -

                                9.1.3 -Provisioning +functionality. + + +

                                +
                                +

                                + +9.1.3 + +Provisioning and Update Security Risk -

                                +

                                If the WoT @@ -19373,7 +22635,8 @@

                                supports post-manufacturing -

                                +

                                +
                                Mitigation:
                                @@ -19398,7 +22661,7 @@

                                data, such operations -SHOULD +SHOULD data should @@ -19423,12 +22686,24 @@

                                be found in -[ -WOT-SECURITY-BEST-PRACTICES -]. +[ + +WOT-SECURITY-BEST-PRACTICES -[WOT-SECURITY-GUIDELINES]. -

                                9.1.4 + +WOT-SECURITY-GUIDELINES + + + +]. + + +

                                +
                                +

                                + +9.1.4 + Security Credentials Storage @@ -19436,7 +22711,7 @@

                                and Privacy Risk -

                                +

                                Typically the WoT @@ -19495,7 +22770,7 @@

                                the WoT runtime -SHOULD +SHOULD assets, impersonate @@ -19546,7 +22821,7 @@

                                Scripting Runtime -SHOULD +SHOULD should @@ -19594,7 +22869,8 @@

                                the WoT Runtime -SHOULD NOT +SHOULD +NOT expose any @@ -19609,18 +22885,33 @@

                                provisioned security credentials. -

                                9.2 -Script + + +

                                + +
                                +

                                + +9.2 + +Script Security and Privacy Risks -

                                This section is non-normative.

                                + +

                                Some additional + This section +is +non-normative. +

                                +This +section describes specific @@ -19637,15 +22928,20 @@

                                developers. -

                                9.2.1 -Corrupted +

                                +
                                +

                                + +9.2.1 + +Corrupted Script Input Security and Privacy Risk -

                                +

                                A typical way @@ -19659,6 +22955,10 @@

                                it a corrupted +input +via +one +of script instance @@ -19668,8 +22968,14 @@

                                formats defined by + the -TD, +exposed +interfaces. +Therefore +developers + +TD, or data formats @@ -19682,27 +22988,22 @@

                                WoT Scripting Runtime -SHOULD + + +SHOULD + perform validation on all - -input -via -one -of +WoT -fields +input +fields defined by - the -exposed -interfaces. -Therefore - -TD, +TD, scripts may be @@ -19715,19 +23016,13 @@

                                Mitigation:
                                Script - developers -SHOULD - -should - +should perform validation on all -WoT - -application +application defined script @@ -19741,7 +23036,7 @@

                                input validation, - + fuzzing . @@ -19780,10 +23075,14 @@

                                be found in -[ +[ + + WOT-SECURITY-TESTING + + ]. -As +As any software, complex @@ -19822,14 +23121,20 @@

                                WoT scripts. -[WOT-SECURITY-TESTING]. -

                                9.2.2 + + +

                                +
                                +

                                + +9.2.2 + Denial Of Service Security Risk -

                                +

                                If a WoT @@ -19860,9 +23165,10 @@

                                Therefore WoT scripts -SHOULD +SHOULD -

                                +

                                +
                                Mitigation:
                                @@ -19889,17 +23195,26 @@

                                be found in -[ +[ + + WOT-SECURITY-BEST-PRACTICES + + ]. - -[WOT-SECURITY-BEST-PRACTICES]. -

                                9.2.3 + + +

                                +
                                +

                                + +9.2.3 + Stale TD Security Risk -

                                +

                                During the lifetime @@ -19947,7 +23262,7 @@

                                Therefore WoT scripts -SHOULD +SHOULD one and @@ -19989,8 +23304,14 @@

                                to remain persistent. -
                                Editor's note

                                -While +

                                +Editor's +note + + +
                                +

                                +While stale TDs can @@ -20009,12 +23330,20 @@

                                a security risk. -

                                10. -

                                10. +

                                + +
                                +

                                + +10. + Terminology and conventions -

                                + + + +

                                The generic WoT @@ -20022,15 +23351,17 @@

                                is defined in -[ +[ + + WOT-ARCHITECTURE + + ]: - -[WOT-ARCHITECTURE]: - + Thing , - + Thing Description @@ -20040,7 +23371,7 @@

                                TD ), - + Web of Things @@ -20053,7 +23384,7 @@

                                ), - + WoT Interface , @@ -20067,7 +23398,7 @@

                                interface ), - + Protocol Bindings , @@ -20075,43 +23406,45 @@

                                WoT Runtime , - + Consuming a Thing Description , - + Thing Directory , - + WoT Interactions , Property , - + Action , - + Event etc. -

                                +

                                +

                                JSON-LD is defined in -[ +[ + + JSON-LD + + ] - -[JSON-LD] - as a JSON @@ -20124,76 +23457,93 @@

                                for Linked Data. -

                                +

                                +

                                The terms - + + URL + +, + + +URL +scheme + + and -, - +, + + URL -scheme -, -URL host -, +, URL path -, - -URL + +, + + +URL record -, +, parse a URL -, +, absolute-URL string -, +, path-absolute-URL string -, -basic + +, + + +basic URL parser - + + are defined in -[ +[ + + URL + + ]. - -[URL]. - -

                                +

                                +

                                The following terms - + + MIME type -, +, Parsing a MIME type -, +, Serializing a MIME type -, +, valid MIME type string -, +, JSON MIME type @@ -20201,24 +23551,31 @@

                                are defined in -[ -HTML52 -] +[ + +HTML52 + + +MIMESNIFF + + + +] and -[MIMESNIFF]. +].

                                The terms - + UTF-8 encoding -, +, UTF-8 decode -, +, encode -, +, decode are @@ -20232,133 +23589,178 @@

                                of browser implementations: -browsing + +[ + +browsing context -, + + +ENCODING + +, top-level browsing context -, -global + + +]. +

                                +, + + +global object -[ENCODING]. -

                                -string -, -parse -JSON -from -bytes - - -and - -serialize -JSON -to -bytes -, -are -defined -in -[INFRA]. -

                                -The -terms - + +string + , incumbent settings object - -throw - +, + , -Document -, - + +parse +JSON +from +bytes + +Document + + +and + , -document + + +serialize +JSON +to +bytes + +document base URL - -creating - +, +are +defined +in +[ + , -Window -, - + +INFRA + +Window + + +]. +

                                +The +terms + , -WindowProxy + + +WindowProxy -DOMString +throw , -origin -, - + +origin + +, + , ASCII serialized origin - -Dictionary - + , executing algorithms -in + + +creating + +in parallel -, - + , -queue + +, + +queue a task + +, + -ArrayBuffer +DOMString -, -task +task source -, - + +, + +, + +iframe + + , -iframe -BufferSource +Dictionary -, -valid +valid MIME type -, - + +, + + + +ArrayBuffer + . A browsing context -refers + + +refers to the environment in which Document -objects + +, + + + +BufferSource + + +objects are presented to @@ -20368,20 +23770,37 @@

                                given browsing context -has + +, + + + +any + + +has a single +, + + +not +present +, -any +DOMException WindowProxy -, - -not -present -, + +, + + + +AbortError + + object, but it @@ -20389,27 +23808,43 @@

                                have many + +, + + -DOMException +SyntaxError Document -, - + +, + + + +NotSupportedError + + objects, with their associated + +, + + -AbortError +NetworkError Window -, - + +, + + -SyntaxError +TypeError objects. @@ -20417,7 +23852,9 @@

                                script execution context -associated + + +associated with the browsing @@ -20449,25 +23886,42 @@

                                secure context +, + + + +NotReadableError + + is + +, + + + +TimeoutError +, +NoModificationAllowedError +, +SecurityError +, +are + defined in [ - -, - + WEBAPPSEC - -NotSupportedError - -]. - -, - - -NetworkError - + +WEBIDL + + + +]. +

                                +

                                + Error , EvalError @@ -20477,144 +23931,141 @@

                                ReferenceError , SyntaxError - -, - - +, TypeError - -, -URIError +, +URIError - + + , - -NotReadableError - script execution context +, -, - -, + Promise - - -TimeoutError - + , -JSON -, - +, + + +Error +, +JSON + , JSON.stringify - -NoModificationAllowedError - -and -JSON.parse - -, - - -SecurityError -, -are -defined -in -[ -ECMASCRIPT -]. - -[WEBIDL]. +, + + +JSON.stringify -

                                - -DOMString -, -USVString -, -ArrayBuffer -, - - -Promise - -BufferSource + +and -, - -Error -, -JSON -, -JSON.stringify -, +, + + JSON.parse - - -and -any - - -internal + + +and + + +internal slots - + + are defined in -[ -WEBIDL +[ + + +ECMASCRIPT + + ]. - -[ECMASCRIPT]. - -

                                -The -terms - -browsing +

                                +

                                +The +terms + + +browsing context -, -top-level + +DOMString + +, + +, + + +top-level browsing context -, -global + +USVString + +, + +, + + +global object -, -current + +ArrayBuffer + +, + +, + + +current settings object -, -executing - -algorithms -utf-8 -encode + +BufferSource - -in +, +executing +algorithms + + +in parallel - -, + +and -are +any + + +are defined in -[HTML5] +[ + +WEBIDL + + +HTML5 -and -utf-8 -decode + + +]. -are +] +and +are used in the @@ -20622,10 +24073,20 @@

                                of browser implementations. -

                                + +

                                +

                                The -term - +algorithms +utf-8 +encode +, +and +utf-8 +decode + +term + secure context @@ -20637,13 +24098,18 @@

                                defined in -[ -ENCODING -]. +[ + +ENCODING -[WEBAPPSEC]. + +WEBAPPSEC -

                                + + +]. +

                                +

                                IANA media @@ -20658,13 +24124,14 @@

                                are defined in - + RFC2046 . -

                                +

                                +

                                The terms - + hyperlink reference @@ -20676,24 +24143,37 @@

                                are defined in -[ -HTML52 -] +[ + +HTML52 -[HTML5] + +HTML5 + + +] and - + RFC8288 . -

                                11. +

                                + +
                                +

                                +11. Conformance -

                                A. -API + + +A. + +API design rationale - -

                                + + +

                                +

                                As well as @@ -20746,21 +24226,26 @@

                                rationale here. -

                                A.1 -Approaches +

                                +
                                +

                                + +A.1 + +Approaches to WoT application development -

                                +

                                The key words -MAY +MAY , -MUST +MUST , -SHOULD +SHOULD , WoT @@ -20768,7 +24253,8 @@

                                Group and -SHOULD NOT +SHOULD +NOT are Working @@ -20789,11 +24275,13 @@

                                implemented and tested. -

                                A.1.1 +

                                +A.1.1 + No Scripting API -

                                +

                                It is possible @@ -20840,18 +24328,20 @@

                                implementation is the - + Mozilla WebThings platform. -

                                A.1.2 +

                                +A.1.2 + Simple Scripting API -

                                +

                                WoT - + Thing s @@ -20863,7 +24353,7 @@

                                objects, so a - + Thing can @@ -20880,14 +24370,14 @@

                                software object, with - + Properties represented as object properties, - + Action s @@ -20907,10 +24397,7 @@

                                stored in -[ -RFC2119 - -special +special properties. Consuming and @@ -20930,13 +24417,10 @@

                                represents a remote - + Thing - - -]. - -and + +and its interactions. One @@ -20944,68 +24428,42 @@

                                implementation is the - + Arena Web Hub - + project. - -

                                -This -document -defines -conformance -criteria - -In +

                                +In the next example, a - + Thing - -that -apply -to - -represents + +that +represents interactions with - a -single -product: - -lock +lock would look like - the -UA -(user -agent) -that -implements - -following: - +following: the -interfaces -it -contains. - - -status - + +status + property and the - + open() - + method are directly @@ -21013,29 +24471,64 @@

                                on the object. - -

                                -
                                - Example 8: Open a lock with a simple API - 
                                          let lock = await WoT.consume(‘https://td.my.com/lock-00123’);
-          console.log(lock.status);
-          lock.open('withThisKey');
-
                                -

                                A.1.3 +

                                +Example + +8 +: +Open +a +lock +with +a +simple +API +
                                
+"hljs-keyword">let lock = await WoT.consume(‘https://td.my.com/lock-00123’);
+console.log(lock.status);
+lock.open(
+'withThisKey'
+
+);
+

                                +A.1.3 + This -API, +API, aligned with -[WOT-TD] -

                                -Since + +[ + +RFC2119 + + +WOT-TD + + + +]. + +] +

                                +

                                +This +document +defines +conformance +criteria + +Since the direct mapping of - + Thing - + s to software @@ -21045,26 +24538,34 @@

                                some challenges, this - specification -can -be -used -for -implementing - -takes +takes another approach + that -exposes +apply + +exposes software objects + to -represent +a +single +product: + +represent + the - -Thing +UA +(user +agent) +that +implements + + +Thing metadata as @@ -21073,16 +24574,18 @@

                                and the -WoT -Scripting +interfaces +it +contains. -interactions +WoT +interactions as methods. One implementation is - + node-wot in @@ -21101,23 +24604,19 @@

                                implementation of the - API -specified - +specified in -multiple -programming -languages. - -this +this document. -

                                -The -interface -definitions + +

                                +

                                +This +specification -same +The +same example now would @@ -21136,22 +24635,33 @@

                                open() method - are -specified - -represented +represented indirectly. -

                                -
                                - Example 9: Open a lock - 
                                          let res = await fetch(‘https://td.my.com/lock-00123’);
-          let td = await res.json();
-          let lock = new ConsumedThing(td);
-          console.log(lock.readProperty(‘status’));
-          lock.invokeAction(‘open’, 'withThisKey');
-
                                -

                                +

                                +Example + +9 +: +Open +a +lock +
                                
+"hljs-keyword">let res = await fetch(‘https://td.my.com/lock-00123’);
+let td = 
+"hljs-keyword">await res.json();
+let lock = 
+"hljs-keyword">new ConsumedThing(td);
+
+"hljs-built_in">console.log(lock.readProperty(‘status’));
+lock.invokeAction(‘open’, 
+'withThisKey'
+
+);
+

                                In conclusion, the @@ -21167,7 +24677,11 @@

                                closely follows the -[WOT-TD] +[ + +WOT-TD + +] specification. Based on @@ -21175,46 +24689,73 @@

                                a simple API + can -also +also + be -implemented. +used + +implemented. Since Scripting is an optional module - in -[ -WEBIDL -]. - -WoT, +WoT, this leaves room + for -applications +implementing + +applications that only use + the WoT -network +Scripting +API +in +multiple +programming +languages. +The +interface +definitions + +network interface. Therefore all three approaches above + are -supported +specified +in + +supported by -[WOT-TD]. -

                                +[ + +WEBIDL + + +WOT-TD + + + +]. +

                                +

                                The user agent @@ -21259,7 +24800,9 @@

                                API for WoT. -

                                A.2 +

                                +A.2 + Fetching and validating @@ -21290,7 +24833,7 @@

                                runtime environment, - + TD given @@ -21309,7 +24852,7 @@

                                Node.js the - + Fetch API @@ -21388,7 +24931,7 @@

                                in this document -MUST +MUST implement them in @@ -21414,7 +24957,7 @@

                                scoped out, and - + TD validation @@ -21428,7 +24971,11 @@

                                Web IDL -[WOT-TD], +[ + +WOT-TD + +], that is scoped @@ -21437,23 +24984,17 @@

                                This specification -[ -WEBIDL - -expects +expects a - + TD - - -]. - -as - + +as + parsed JSON object - + that has been @@ -21461,14 +25002,33 @@

                                according to the -[WOT-TD] + +[ + +WEBIDL + + +WOT-TD + + + +]. + +] specification. -

                                A.3 -Factory +

                                +

                                +
                                +

                                + +A.3 + +Factory vs constructors -

                                +

                                +

                                Implementations The @@ -21478,7 +25038,7 @@

                                consuming and exposing - + Thing s @@ -21498,20 +25058,20 @@

                                can also construct - + ConsumedThing - + and - + ExposedThing - + by providing a parsed and validated - + TD . Platform @@ -21540,6 +25100,8 @@

                                a runtime +to +implement TD @@ -21547,35 +25109,34 @@

                                themselves, may use + the -constructors, +APIs +defined +in +this +document +MUST + +constructors, whereas applications that leave validation - to -implement - -implementations +implementations and prefer interactions initialized up front -SHOULD -use + +SHOULD -the -APIs -defined -in -this -document -MUST -implement + +implement them in a @@ -21583,9 +25144,7 @@

                                consistent with -factory -methods -on +use the TypeScript @@ -21593,30 +25152,39 @@

                                defined in - -WoT -API -object -.

                                A.4 -Observers -

                                -Earlier -drafts -used +factory +methods +on the TypeScript specification [ -TYPESCRIPT - -Observer - + +WoT +API +object +.

                                +A.4 + +Observers + +TYPESCRIPT + ]. -construct, +

                                +

                                +Earlier +drafts +used +the + +Observer + +construct, but since it @@ -21645,7 +25213,7 @@

                                and handling WoT - + Event s @@ -21655,10 +25223,18 @@

                                callback registrations. -

                                A.5 -Using +

                                +

                                +
                                +

                                + +A.5 + +Using Events -

                                This +

                                +

                                +This document serves a @@ -21755,7 +25331,7 @@

                                and handling WoT - + Event s @@ -21765,11 +25341,12 @@

                                the solution above. - -

                                A.6 +

                                +A.6 + Polymorphic functions -

                                +

                                The reason to @@ -21811,17 +25388,34 @@

                                vocabulary from the - + Form definition in -[WOT-TD]. +[ + +WOT-TD + +]. -

                                B. +

                                +

                                + +
                                +

                                +A. + + +B. + Changes -

                                A. -

                                The + + +

                                +
                                +

                                +The following is a @@ -21845,19 +25439,19 @@

                                Public Working Draft - + September 2017 .
                              24. Working Draft - + April 2018 .
                              25. Working Draft - + November 2018 .
                              26. @@ -21890,8 +25484,9 @@

                                and use - -W3C + +W3C + TAG recommended design @@ -21907,8 +25502,9 @@

                                APIs (such as - -W3C + +W3C + Generic Sensor API @@ -21923,16 +25519,16 @@

                                API for constructing - + TD s and leverage using - + ThingDescription - + instead.

                              27. Add @@ -21947,13 +25543,13 @@

                                Allow constructors for - + ConsumedThing - + and - + ExposedThing -.

                              28. +.
                              29. Add API rationale @@ -21963,8 +25559,7 @@

                                to this document. -

                                30. -

                                +

                                For a complete @@ -21973,7 +25568,7 @@

                                changes, see the - + github change log @@ -21983,12 +25578,13 @@

                                also view the - + recently closed issues . -

                                Make +

                                +Make the Scripting API @@ -22008,11 +25604,23 @@

                                Description specification . -

                                C. + +

                                +
                                +

                                +B. + + +C. + Open issues -

                                B. -

                                The + + +

                                +
                                +

                                +The following problems are @@ -22021,51 +25629,59 @@

                                and need most -attention:

                                +attention: +

                                • Security -related -metadata -(https://github.com/w3c/wot-scripting-api/issues/91). -Providing -Protocol -Binding -for -ExposedThing -(https://github.com/w3c/wot-scripting-api/issues/45). -Script +Script management and runtime + related -issues +metadata +(https://github.com/w3c/wot-scripting-api/issues/91). + +issues (https://github.com/w3c/wot-scripting-api/issues/) +
                                • -An +Providing +Protocol +Binding + +An explicit API + for -adding +adding and removing - + Property -, +, Action - + and - + Event - + definitions on - + + ExposedThing - -(it + + +(https://github.com/w3c/wot-scripting-api/issues/45). +Script +management + +(it was present in @@ -22075,114 +25691,602 @@

                                  removed for complexity + and -a +runtime +related +issues +(https://github.com/w3c/wot-scripting-api/issues/) + +a simpler way to do it. -

                                  • + +
                                -

                                C. -Acknowledgments -

                                D. -Full + +

                                +
                                +

                                +C. + + +D. + +Full Web IDL -

                                typedef object ThingDescription;
-
-      [SecureContext, Exposed=(Window,Worker)]
-      interface WOT {
-        // methods defined in UA conformance classes
-      };
-
-      partial interface WOT {
-        Promise<ConsumedThing> consume(ThingDescription td);
-      };
-
-      partial interface WOT {
-        Promise<ExposedThing> produce(ThingDescription td);
-      };
-
-      partial interface WOT {
-        ThingDiscovery discover(optional ThingFilter filter = null);
-      };
-
-      [SecureContext, Exposed=(Window,Worker)]
-      interface ConsumedThing {
-        constructor(ThingDescription td);
-        Promise<any> readProperty(DOMString propertyName,
-                                  optional InteractionOptions options = null);
-        Promise<PropertyMap> readAllProperties(optional InteractionOptions options = null);
-        Promise<PropertyMap> readMultipleProperties(
-                                  sequence<DOMString> propertyNames,
-                                  optional InteractionOptions options = null);
-        Promise<void> writeProperty(DOMString propertyName,
-                                    any value,
-                                    optional InteractionOptions options = null);
-        Promise<void> writeMultipleProperties(PropertyMap valueMap,
-                                    optional InteractionOptions options = null);
-        Promise<any> invokeAction(DOMString actionName,
-                                    optional any params = null,
-                                    optional InteractionOptions options = null);
-        Promise<void> observeProperty(DOMString name,
-                                    WotListener listener,
-                                    optional InteractionOptions options = null);
-        Promise<void> unobserveProperty(DOMString name);
-        Promise<void> subscribeEvent(DOMString name,
-                                    WotListener listener,
-                                    optional InteractionOptions options = null);
-        Promise<void> unsubscribeEvent(DOMString name);
-        ThingDescription getThingDescription();
-      };
-      dictionary InteractionOptions {
-        object uriVariables;
-      };
-      typedef object PropertyMap;
-      callback WotListener = void(any data);
-
-      [SecureContext, Exposed=(Window,Worker)]
-      interface ExposedThing: ConsumedThing {
-        ExposedThing setPropertyReadHandler(DOMString name,
-                PropertyReadHandler readHandler);
-        ExposedThing setPropertyWriteHandler(DOMString name,
-                PropertyWriteHandler writeHandler);
-        ExposedThing setActionHandler(DOMString name, ActionHandler action);
-        void emitEvent(DOMString name, any data);
-        Promise<void> expose();
-        Promise<void> destroy();
-      };
-      callback PropertyReadHandler = Promise<any>(
-              optional InteractionOptions options = null);
-      callback PropertyWriteHandler = Promise<void>(any value,
-              optional InteractionOptions options = null);
-      callback ActionHandler = Promise<any>(any params,
-              optional InteractionOptions options = null);
-
-      [SecureContext, Exposed=(Window,Worker)]
-      interface ThingDiscovery {
-        constructor(optional ThingFilter filter = null);
-        readonly attribute ThingFilter? filter;
-        readonly attribute boolean active;
-        readonly attribute boolean done;
-        readonly attribute Error? error;
-        void start();
-        Promise<ThingDescription> next();
-        void stop();
-      };
-
-typedef DOMString DiscoveryMethod;
-
-        dictionary ThingFilter {
-          (DiscoveryMethod or DOMString) method = "any";
-          USVString? url;
-          USVString? query;
-          object? fragment;
-        };

                                E. +

                                
+"idlTypedef" data-title="ThingDescription">typedef object ThingDescription;
+
+"WOT">[SecureContext, Exposed=(Window,Worker)]
+interface WOT {
+  // methods defined in UA conformance classes
+};
+"WOT">partial interface WOT {
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<ConsumedThing> consume(ThingDescription td);
+};
+
+"WOT">partial interface WOT {
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<ExposedThing> produce(ThingDescription td);
+};
+
+"WOT">partial interface WOT {
+  
+"internalDFN" data-link-type=
+"idl">ThingDiscovery discover(optional ThingFilter filter = null);
+};
+
+"ConsumedThing">[SecureContext, Exposed=(Window,Worker)]
+interface ConsumedThing {
+  
+"constructor" data-title="constructor" data-dfn-for="ConsumedThing"
+data-lt=
+"ConsumedThing.constructor()|ConsumedThing.constructor|constructor()|constructor">constructor(ThingDescription td);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<any> readProperty(DOMString propertyName,
+                            optional InteractionOptions options = null);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<PropertyMap> readAllProperties(optional InteractionOptions options = null);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<PropertyMap> readMultipleProperties(
+                            
+"" data-type="dfn" href=
+"https://heycam.github.io/webidl/#idl-sequence">sequence<DOMString> propertyNames,
+                            optional InteractionOptions options = null);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> writeProperty(DOMString propertyName,
+                              
+data-link-type="dfn" href=
+"https://heycam.github.io/webidl/#idl-any">any value,
+                              optional InteractionOptions options = null);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> writeMultipleProperties(PropertyMap valueMap,
+                              optional InteractionOptions options = null);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<any> invokeAction(DOMString actionName,
+                              optional any params = null,
+                              optional InteractionOptions options = null);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> observeProperty(DOMString name,
+                              
+"#dom-wotlistener" class="internalDFN" data-link-type=
+"idl">WotListener listener,
+                              optional InteractionOptions options = null);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> unobserveProperty(DOMString name);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> subscribeEvent(DOMString name,
+                              
+"#dom-wotlistener" class="internalDFN" data-link-type=
+"idl">WotListener listener,
+                              optional InteractionOptions options = null);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> unsubscribeEvent(DOMString name);
+  
+"internalDFN" data-link-type=
+"idl">ThingDescription getThingDescription();
+};
+dictionary InteractionOptions {
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-object">object uriVariables;
+};
+typedef object PropertyMap;
+callback WotListener = void(any data);
+
+"ExposedThing">[SecureContext, Exposed=(Window,Worker)]
+interface ExposedThing: ConsumedThing {
+  
+"internalDFN" data-link-type=
+"idl">ExposedThing setPropertyReadHandler(DOMString name,
+          
+class="internalDFN" data-link-type=
+"idl">PropertyReadHandler readHandler);
+  
+"internalDFN" data-link-type=
+"idl">ExposedThing setPropertyWriteHandler(DOMString name,
+          
+"#dom-propertywritehandler" class="internalDFN" data-link-type=
+"idl">PropertyWriteHandler writeHandler);
+  
+"internalDFN" data-link-type=
+"idl">ExposedThing setActionHandler(DOMString name, ActionHandler action);
+  
+href=
+"https://heycam.github.io/webidl/#idl-void">void emitEvent(DOMString name, any data);
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> expose();
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<void> destroy();
+};
+callback PropertyReadHandler = Promise<any>(
+        optional InteractionOptions options = null);
+callback PropertyWriteHandler = Promise<void>(any value,
+        optional InteractionOptions options = null);
+callback ActionHandler = Promise<any>(any params,
+        optional InteractionOptions options = null);
+
+"ThingDiscovery">[SecureContext, Exposed=(Window,Worker)]
+interface ThingDiscovery {
+  
+"constructor" data-title="constructor" data-dfn-for=
+"ThingDiscovery" data-lt=
+"ThingDiscovery.constructor()|ThingDiscovery.constructor|constructor()|constructor">constructor(optional ThingFilter filter = null);
+  readonly attribute ThingFilter? filter;
+  readonly attribute boolean active;
+  readonly attribute boolean done;
+  readonly attribute Error? error;
+  
+href=
+"https://heycam.github.io/webidl/#idl-void">void start();
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-promise">Promise<ThingDescription> next();
+  
+href=
+"https://heycam.github.io/webidl/#idl-void">void stop();
+};
+
+"DiscoveryMethod">typedef DOMString DiscoveryMethod;
+
+"ThingFilter">dictionary ThingFilter {
+  (DiscoveryMethod or DOMString) method = "any";
+  
+href=
+"https://heycam.github.io/webidl/#idl-USVString">USVString? url;
+  
+href=
+"https://heycam.github.io/webidl/#idl-USVString">USVString? query;
+  
+"interface" href=
+"https://heycam.github.io/webidl/#idl-object">object? fragment;
+};
+
+
+Acknowledgments
+
+
                                +
                                +
                                +

                                + +E. + Acknowledgements -

                                + + +

                                +

                                Special thanks to @@ -22247,87 +26351,241 @@

                                and guidance. -

                                D. +

                                + +
                                +

                                +D. + + +F. + References -D.1 + + +

                                +
                                +

                                +D.1 + + +F.1 + Normative references + + +

                                +
                                +
                                [ECMASCRIPT] +
                                +
                                + + ECMAScript Language Specification -. + +. Ecma International. URL: + https://tc39.github.io/ecma262/ + +
                                +
                                [ENCODING] +
                                +
                                + + Encoding -. +Standard + + +. Anne van -Kesteren; +Kesteren; Joshua Bell; Addison Phillips. -W3C. +W3C. 15 December 2016. -W3C +W3C Candidate Recommendation. + +Kesteren. +WHATWG. +Living +Standard. + URL: -https://www.w3.org/TR/encoding/ -[HTML52] +https://www.w3.org/TR/encoding/ + + +https://encoding.spec.whatwg.org/ + + +
                                +[HTML52] + +
                                +[HTML] + +
                                +
                                + + HTML -5.2 -. +5.2 + +Standard +. +Anne +van +Kesteren; +Domenic +Denicola; +Ian +Hickson; +Philip +Jägenstedt; +Simon +Pieters. +WHATWG. +Living +Standard. +URL: + +https://html.spec.whatwg.org/multipage/ +
                                +[HTML5] +
                                +HTML5 + + +. +Ian +Hickson; +Robin +Berjon; + Steve Faulkner; -Arron +Arron Eicholz; + Travis Leithead; -Alex +Alex Danilo; Sangwhan Moon; + Erika Doyle Navara; Theresa O'Connor; -Robin +Robin Berjon. -W3C. -14 + +Silvia +Pfeiffer. + +W3C. +14 December 2017. -W3C + +27 +March +2018. + +W3C Recommendation. URL: -https://www.w3.org/TR/html52/ +https://www.w3.org/TR/html52/ + + +https://www.w3.org/TR/html5/ +
                                +[INFRA] +
                                +Infra +Standard +. +Anne +van +Kesteren; +Domenic +Denicola. +WHATWG. +Living +Standard. +URL: + +https://infra.spec.whatwg.org/ + + +
                                +
                                [JSON-LD] +
                                +
                                + + JSON-LD 1.0 -. + +. Manu Sporny; Gregg Kellogg; Markus Lanthaler. -W3C. +W3C. 16 January 2014. -W3C +W3C Recommendation. URL: + https://www.w3.org/TR/json-ld/ + +
                                +
                                +[MIMESNIFF] +
                                +MIME +Sniffing +Standard +. +Gordon +P. +Hemsley. +WHATWG. +Living +Standard. +URL: + +https://mimesniff.spec.whatwg.org/ +
                                +
                                [RFC2119] +
                                +
                                + + Key words for @@ -22338,7 +26596,8 @@

                                Indicate Requirement Levels -. + +. S. Bradner. IETF. @@ -22348,22 +26607,66 @@

                                Current Practice. URL: + https://tools.ietf.org/html/rfc2119 + +

                                +
                                +[RFC8174] +
                                +Ambiguity +of +Uppercase +vs +Lowercase +in +RFC +2119 +Key +Words +. +B. +Leiba. +IETF. +May +2017. +Best +Current +Practice. +URL: + +https://tools.ietf.org/html/rfc8174 +
                                +
                                [TYPESCRIPT] +
                                +
                                + + TypeScript Language Specification -. + +. Microsoft. 1 October 2012. URL: + https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md + +
                                +
                                [URL] +
                                +
                                + + URL Standard -. + +. Anne van Kesteren. @@ -22371,49 +26674,106 @@

                                Living Standard. URL: + https://url.spec.whatwg.org/ + +

                                +
                                [WEBAPPSEC] +
                                +
                                + + Secure Contexts -. -W3C. + +. +W3C. 17 July 2015. URL: + https://w3c.github.io/webappsec/specs/powerfulfeatures + +
                                +
                                [WEBIDL] +
                                +
                                + + Web IDL -. -Cameron + +. +Cameron McCormack; + Boris -Zbarsky; +Zbarsky; Tobie Langel. -W3C. + +Zbarsky. + +W3C. 15 December 2016. -W3C +W3C Editor's Draft. URL: + https://heycam.github.io/webidl/ + +
                                +
                                [WOT-ARCHITECTURE] +
                                +
                                + + Web of Things Architecture -. -W3C. + +. +W3C. 20 August 2017. URL: + https://w3c.github.io/wot-architecture/ + +
                                +
                                +[WOT-PROTOCOL-BINDINGS] +
                                +Web +of +Things +Protocol +Binding +Templates +. +W3C. +20 +August +2017. +URL: + +https://w3c.github.io/wot-binding-templates/ +
                                +
                                [WOT-SECURITY-BEST-PRACTICES] +
                                +
                                + + Web of Things @@ -22422,28 +26782,53 @@

                                Privacy Best Practices -(WIP) -. -W3C. +(WIP) + + +. +W3C. WIP. URL: + https://github.com/w3c/wot-security/blob/master/wot-security-best-practices.md -[WOT-SECURITY-CONSIDERATIONS] + +

                                +[WOT-SECURITY-CONSIDERATIONS] + +
                                +[WOT-SECURITY-GUIDELINES] + +
                                +
                                + + Web of Things Security and Privacy -Considerations -. -W3C. +Considerations + +Guidelines + + +. +W3C. 28 August 2017. URL: + https://w3c.github.io/wot-security/ + +
                                +
                                [WOT-SECURITY-TESTING] +
                                +
                                + + Web of Things @@ -22451,18 +26836,29 @@

                                Testing and Validation -. -W3C. + +. +W3C. WIP. URL: + https://github.com/w3c/wot-security/blob/master/wot-security-testing.md + +

                                +
                                [WOT-TD] +
                                +
                                + + WoT Thing Description + + . -W3C. -21 +W3C. +21 October 2018. URL: @@ -22488,14 +26884,30 @@

                                WHATWG. Living Standard. + +20 +August +2017. + URL: -https://html.spec.whatwg.org/multipage/ +https://html.spec.whatwg.org/multipage/ + + +https://w3c.github.io/wot-thing-description/ + + +

                                +
                                +
                                +
                                +
                                -

                                F. References

                                - -
                                -

                                F.1 Normative references

                                -
                                -
                                [ECMASCRIPT]
                                ECMAScript Language Specification. Ecma International. URL: https://tc39.github.io/ecma262/
                                [ENCODING]
                                Encoding Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://encoding.spec.whatwg.org/
                                [HTML]
                                HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
                                [HTML5]
                                HTML5. Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. W3C. 27 March 2018. W3C Recommendation. URL: https://www.w3.org/TR/html5/
                                [INFRA]
                                Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
                                [JSON-LD]
                                JSON-LD 1.0. Manu Sporny; Gregg Kellogg; Markus Lanthaler. W3C. 16 January 2014. W3C Recommendation. URL: https://www.w3.org/TR/json-ld/
                                [MIMESNIFF]
                                MIME Sniffing Standard. Gordon P. Hemsley. WHATWG. Living Standard. URL: https://mimesniff.spec.whatwg.org/
                                [RFC2119]
                                Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
                                [RFC8174]
                                Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174
                                [TYPESCRIPT]
                                TypeScript Language Specification. Microsoft. 1 October 2012. URL: https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md
                                [URL]
                                URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/
                                [WEBAPPSEC]
                                Secure Contexts. W3C. 17 July 2015. URL: https://w3c.github.io/webappsec/specs/powerfulfeatures
                                [WEBIDL]
                                Web IDL. Boris Zbarsky. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/
                                [WOT-ARCHITECTURE]
                                Web of Things Architecture. W3C. 20 August 2017. URL: https://w3c.github.io/wot-architecture/
                                [WOT-PROTOCOL-BINDINGS]
                                Web of Things Protocol Binding Templates. W3C. 20 August 2017. URL: https://w3c.github.io/wot-binding-templates/
                                [WOT-SECURITY-BEST-PRACTICES]
                                Web of Things Security and Privacy Best Practices. W3C. WIP. URL: https://github.com/w3c/wot-security/blob/master/wot-security-best-practices.md
                                [WOT-SECURITY-GUIDELINES]
                                Web of Things Security and Privacy Guidelines. W3C. 28 August 2017. URL: https://w3c.github.io/wot-security/
                                [WOT-SECURITY-TESTING]
                                Web of Things Security Testing and Validation. W3C. WIP. URL: https://github.com/w3c/wot-security/blob/master/wot-security-testing.md
                                [WOT-TD]
                                WoT Thing Description . W3C. 20 August 2017. URL: https://w3c.github.io/wot-thing-description/
                                -
                                \ No newline at end of file + + +

                                + + + From fc471dea3cdaf8cc2d27db445b0efcbc5002f883 Mon Sep 17 00:00:00 2001 From: ashimura Date: Mon, 21 Oct 2019 18:10:48 +0900 Subject: [PATCH 364/464] add Editor IDs by w3cid --- releases/wd4/Overview.html | 4 ++++ releases/wd4/diff.html | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/releases/wd4/Overview.html b/releases/wd4/Overview.html index 4cdb49cd..60c495d7 100644 --- a/releases/wd4/Overview.html +++ b/releases/wd4/Overview.html @@ -930,20 +930,24 @@ "editors": [ { "name": "Zoltan Kis", + "w3cid": "57789", "company": "Intel", "companyURL": "https://www.intel.com/" }, { "name": "Daniel Peintner", + "w3cid": "39497", "company": "Siemens AG", "companyURL": "https://www.siemens.com/" }, { "name": "Johannes Hund", + "w3cid": "74472", "note": "Former Editor, when at Siemens AG" }, { "name": "Kazuaki Nimura", + "w3cid": "59208", "note": "Former Editor, at Fujitsu Ltd." } ], diff --git a/releases/wd4/diff.html b/releases/wd4/diff.html index ab459b3e..5c009e1c 100644 --- a/releases/wd4/diff.html +++ b/releases/wd4/diff.html @@ -957,20 +957,24 @@ "editors": [ { "name": "Zoltan Kis", + "w3cid": "57789", "company": "Intel", "companyURL": "https://www.intel.com/" }, { "name": "Daniel Peintner", + "w3cid": "39497", "company": "Siemens AG", "companyURL": "https://www.siemens.com/" }, { "name": "Johannes Hund", + "w3cid": "74472", "note": "Former Editor, when at Siemens AG" }, { "name": "Kazuaki Nimura", + "w3cid": "59208", "note": "Former Editor, at Fujitsu Ltd." } ], From f4862b7ddadc942f5fcb55b4f8d38bcd4f9820f3 Mon Sep 17 00:00:00 2001 From: ashimura Date: Mon, 21 Oct 2019 18:16:57 +0900 Subject: [PATCH 365/464] add the link to public list of disclosures --- releases/wd4/Overview.html | 4 ++- releases/wd4/diff.html | 68 +++++++++++++++++++++----------------- 2 files changed, 40 insertions(+), 32 deletions(-) diff --git a/releases/wd4/Overview.html b/releases/wd4/Overview.html index 60c495d7..a345e09d 100644 --- a/releases/wd4/Overview.html +++ b/releases/wd4/Overview.html @@ -1255,7 +1255,9 @@

                                Status of This Document

                                "https://www.w3.org/Consortium/Patent-Policy/">W3C Patent Policy. W3C maintains a - public list of any patent + public list + of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent diff --git a/releases/wd4/diff.html b/releases/wd4/diff.html index 5c009e1c..8db2a95b 100644 --- a/releases/wd4/diff.html +++ b/releases/wd4/diff.html @@ -1986,7 +1986,7 @@

                                maintains a - + public list of @@ -3319,21 +3319,23 @@

                                ] -
                              30. -A.2 + + +
                                31. + + +
                              31. + + +A.2 Fetching and validating a TD - - -
                                32. -
                              32. - - -A.3 +
                              33. +A.3 Factory vs @@ -4299,8 +4301,9 @@

                                notify all listeners + subscribed -to +to that Event . @@ -4311,9 +4314,8 @@

                                changes to clients - subscribed -to +to that. Mark/unmark the @@ -5826,11 +5828,12 @@

                                -Note +Note that [ - -WOT-TD + + +WOT-TD dictionary @@ -7171,11 +7174,11 @@

                                a URL (e.g. -"file://..." -or -"https://..." +"file://..." +or +"https://..." td @@ -7384,16 +7387,16 @@

                                to fetch + the -content +content of url as described by - the -Protocol +Protocol Bindings @@ -7931,7 +7934,10 @@

                                data ); -

                                + + +
                                +

                                6.1 @@ -11217,9 +11223,9 @@

                                items. The +ActionMap -ActionMap -interface +interface represents

                                @@ -13732,11 +13738,11 @@

                                argument - and -qualifiers +qualifiers + and -initialization +initialization value provided by @@ -14014,8 +14020,9 @@

                                MAY use + the -default +default handlers, thereby extending @@ -14029,9 +14036,8 @@

                                bypass them, overriding - the -default +default behavior. Finally, the From 0a62d464b32beb52c251ad1d73fc6856ebe7db80 Mon Sep 17 00:00:00 2001 From: ashimura Date: Mon, 21 Oct 2019 18:23:38 +0900 Subject: [PATCH 366/464] add Edito IDs by data-editor-id --- releases/wd4/Overview.html | 8 +-- releases/wd4/diff.html | 114 ++++++++++++++++++------------------- 2 files changed, 61 insertions(+), 61 deletions(-) diff --git a/releases/wd4/Overview.html b/releases/wd4/Overview.html index a345e09d..56cf3cdf 100644 --- a/releases/wd4/Overview.html +++ b/releases/wd4/Overview.html @@ -1086,20 +1086,20 @@

                                W3C Working Draft

                                Return discovery.

                                34. -

                                The start() method sets +

                                The start() method sets active to - true. The stop() + true. The stop() method sets active to false, but done may be still diff --git a/releases/wd4/diff.html b/releases/wd4/diff.html index 4cca0524..0102913e 100644 --- a/releases/wd4/diff.html +++ b/releases/wd4/diff.html @@ -18172,7 +18172,7 @@

                                [ WOT-TD - + start() @@ -18225,7 +18225,7 @@

                                true . The - + stop() From 4bda1b37514ca9b32ca06db69566d99e521d02fd Mon Sep 17 00:00:00 2001 From: ashimura Date: Mon, 21 Oct 2019 18:37:46 +0900 Subject: [PATCH 369/464] fix broken link of the-next-method as file by adding # and make it #the-next-method --- releases/wd4/Overview.html | 10 +++++----- releases/wd4/diff.html | 14 +++++++------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/releases/wd4/Overview.html b/releases/wd4/Overview.html index d107f06e..f51129c4 100644 --- a/releases/wd4/Overview.html +++ b/releases/wd4/Overview.html @@ -4818,10 +4818,10 @@

                                ThingDescription objects until they are consumed by the application using the next() method. Implementations next() method. Implementations MAY optimize the size of this queue based on e.g. the available resources and the frequency of - invoking the next() method.

                                + invoking the next() method.

                                The ThingDescription objects in the discovery results not yet consumed - with next().

                                + with next().

                                During successive calls of next(), next(), active may be true or false, but done is set to - false by next() + false by next() only when both active is false and the SecurityScheme - + next() @@ -17593,7 +17593,7 @@

                                invoking the - + next() @@ -18312,7 +18312,7 @@

                                yet consumed with - + next() . @@ -18342,13 +18342,13 @@

                                initializing ThingProperty - + next() , ThingAction - + active @@ -18375,7 +18375,7 @@

                                false , but - + done @@ -18396,7 +18396,7 @@

                                by - + next() From 4b042524913d608fc2c24c8d0830dc189678838d Mon Sep 17 00:00:00 2001 From: ashimura Date: Tue, 29 Oct 2019 00:06:19 +0900 Subject: [PATCH 370/464] use CR version URL for TD --- releases/wd4/Overview.html | 28 +++++++++++------------ releases/wd4/diff.html | 46 +++++++++++++++++++------------------- 2 files changed, 37 insertions(+), 37 deletions(-) diff --git a/releases/wd4/Overview.html b/releases/wd4/Overview.html index f51129c4..0a8a4491 100644 --- a/releases/wd4/Overview.html +++ b/releases/wd4/Overview.html @@ -989,10 +989,10 @@ "id": "wot-architecture" }, "WOT-TD": { - "href": "https://w3c.github.io/wot-thing-description/", + "href": "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/", "title": "WoT Thing Description ", "publisher": "W3C", - "date": "20 August 2017", + "date": "16 May 2019", "id": "wot-td" }, "WOT-PROTOCOL-BINDINGS": { @@ -1179,7 +1179,7 @@

                                Abstract

                                data-link-type="dfn">WoT Interactions specified by a script.

                                The specification deliberately follows the WoT Thing + "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/">WoT Thing Description specification closely. It is possible to implement simpler APIs on top of this API, or implementing directly the WoT network facing interface (i.e. the WOT-TD]. It is expected to be a parsed JSON object that is validated using + "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/#json-schema-4-validation"> JSON schema validation.

                                WOT-TD] allows using a shortened Thing Description by the means of + "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/#sec-default-values"> defaults and requiring clients to expand them with default values specified in [
                                1. For each item in the + "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/#sec-default-values"> TD default values table from [WOT-TD] for Thing + "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/#thing">Thing that don't have + "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/#sec-default-values"> default definitions are missing from td, throw "TypeError" and terminate these steps.
                                2. If + "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/#json-schema-4-validation"> JSON schema validation fails on td, throw "TypeError" and terminate these steps. @@ -3067,7 +3067,7 @@

                                  sub-steps on value:
                                  1. Based on the + "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/#dataschema"> DataSchema definition, value MUST be a JSON value and comply to the data schema defined @@ -6112,7 +6112,7 @@

                                    read() function is that the current names map exactly to the "op" vocabulary from the Form + "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/#form">Form definition in [WOT-TD].

                                    @@ -6945,10 +6945,10 @@

                                    [WOT-TD]
                                    WoT - Thing Description . W3C. 20 August 2017. URL: + "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/">WoT + Thing Description . W3C. 16 May 2019. URL: https://w3c.github.io/wot-thing-description/ + "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/">https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/

                                diff --git a/releases/wd4/diff.html b/releases/wd4/diff.html index ad98d155..b739510e 100644 --- a/releases/wd4/diff.html +++ b/releases/wd4/diff.html @@ -1016,10 +1016,10 @@ "id": "wot-architecture" }, "WOT-TD": { - "href": "https://w3c.github.io/wot-thing-description/", + "href": "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/", "title": "WoT Thing Description ", "publisher": "W3C", - "date": "20 August 2017", + "date": "16 May 2019", "id": "wot-td" }, "WOT-PROTOCOL-BINDINGS": { @@ -1580,7 +1580,7 @@

                                deliberately follows the - + WoT Thing Description @@ -1609,7 +1609,7 @@

                                interface (i.e. the - + WoT Interface @@ -5675,7 +5675,7 @@

                                validated using - + JSON schema validation @@ -5862,7 +5862,7 @@

                                the means of - + defaults and @@ -5877,7 +5877,7 @@

                                specified in [ - + WOT-TD ] @@ -5892,7 +5892,7 @@

                                in a given - + TD .

                                @@ -5929,7 +5929,7 @@

                                item in the - + TD default values @@ -6165,13 +6165,13 @@

                                ] for - + Thing that don't have - + default definitions @@ -6222,7 +6222,7 @@

                                third argument - + JSON schema validation @@ -8929,14 +8929,14 @@

                                Based on the - + DataSchema definition , value - + MUST be @@ -8952,7 +8952,7 @@

                                defined for the - + Property that @@ -25395,13 +25395,13 @@

                                vocabulary from the - + Form definition in [ - + WOT-TD ]. @@ -26856,7 +26856,7 @@

                                [WOT-TD]
                                - + WoT Thing @@ -26892,15 +26892,15 @@

                                Living Standard. -20 -August -2017. +16 +May +2019. URL: https://html.spec.whatwg.org/multipage/ - -https://w3c.github.io/wot-thing-description/ + +https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/

                                From 4143bc5ff5ead2cd324ac18b31a1036ed172a1a7 Mon Sep 17 00:00:00 2001 From: ashimura Date: Tue, 29 Oct 2019 00:12:17 +0900 Subject: [PATCH 371/464] use CR version URL for Architecture --- releases/wd4/Overview.html | 38 ++++---- releases/wd4/diff.html | 177 +++++++++++++++++++------------------ 2 files changed, 111 insertions(+), 104 deletions(-) diff --git a/releases/wd4/Overview.html b/releases/wd4/Overview.html index 0a8a4491..66e4a03d 100644 --- a/releases/wd4/Overview.html +++ b/releases/wd4/Overview.html @@ -982,14 +982,14 @@ ], "localBiblio": { "WOT-ARCHITECTURE": { - "href": "https://w3c.github.io/wot-architecture/", + "href": "https://www.w3.org/TR/2019/CR-wot-architecture-20190516/", "title": "Web of Things Architecture", "publisher": "W3C", - "date": "20 August 2017", + "date": "16 May 2019", "id": "wot-architecture" }, "WOT-TD": { - "href": "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/", + "href": "https://w3c.github.io/wot-thing-description/", "title": "WoT Thing Description ", "publisher": "W3C", "date": "16 May 2019", @@ -1142,7 +1142,7 @@

                                Abstract

                                The main Web of Things (WoT) concepts are described in the WoT Architecture + "https://www.w3.org/TR/2019/CR-wot-architecture-20190516/">WoT Architecture document. The Web of Things is made of entities (Things) that can describe their capabilities in a @@ -1179,7 +1179,7 @@

                                Abstract

                                data-link-type="dfn">WoT Interactions specified by a script.

                                The specification deliberately follows the WoT Thing + "https://w3c.github.io/wot-thing-description">WoT Thing Description specification closely. It is possible to implement simpler APIs on top of this API, or implementing directly the WoT network facing interface (i.e. the 1.

                                WoT provides layered interoperability based on how Things are used: "consumed" and "exposed", as - defined + defined in [WOT-ARCHITECTURE].

                                @@ -2249,7 +2249,7 @@

                                WOT-TD]. It is expected to be a parsed JSON object that is validated using + "https://w3c.github.io/wot-thing-description/#json-schema-4-validation"> JSON schema validation.

                                WOT-TD] allows using a shortened Thing Description by the means of + "https://w3c.github.io/wot-thing-description/#sec-default-values"> defaults and requiring clients to expand them with default values specified in [
                                1. For each item in the + "https://w3c.github.io/wot-thing-description/#sec-default-values"> TD default values table from [WOT-TD] for Thing + "https://w3c.github.io/wot-thing-description/#thing">Thing that don't have + "https://w3c.github.io/wot-thing-description/#sec-default-values"> default definitions are missing from td, throw "TypeError" and terminate these steps.
                                2. If + "https://w3c.github.io/wot-thing-description/#json-schema-4-validation"> JSON schema validation fails on td, throw "TypeError" and terminate these steps. @@ -3067,7 +3067,7 @@

                                  sub-steps on value:
                                  1. Based on the + "https://w3c.github.io/wot-thing-description/#dataschema"> DataSchema definition, value MUST be a JSON value and comply to the data schema defined @@ -6112,7 +6112,7 @@

                                    read() function is that the current names map exactly to the "op" vocabulary from the Form + "https://w3c.github.io/wot-thing-description/#form">Form definition in [WOT-TD].

                                    @@ -6900,10 +6900,10 @@

                                    [WOT-ARCHITECTURE]
                                    Web of - Things Architecture. W3C. 20 August 2017. URL: + "https://www.w3.org/TR/2019/CR-wot-architecture-20190516/">Web of + Things Architecture. W3C. 16 May 2019. URL: https://w3c.github.io/wot-architecture/ + "https://www.w3.org/TR/2019/CR-wot-architecture-20190516/">https://www.w3.org/TR/2019/CR-wot-architecture-20190516/
                                    [WOT-PROTOCOL-BINDINGS]
                                    @@ -6945,10 +6945,10 @@

                                    [WOT-TD]
                                    WoT + "https://w3c.github.io/wot-thing-description/">WoT Thing Description . W3C. 16 May 2019. URL: https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/ + "https://w3c.github.io/wot-thing-description/">https://w3c.github.io/wot-thing-description/

                                diff --git a/releases/wd4/diff.html b/releases/wd4/diff.html index b739510e..434fa464 100644 --- a/releases/wd4/diff.html +++ b/releases/wd4/diff.html @@ -1009,14 +1009,14 @@ ], "localBiblio": { "WOT-ARCHITECTURE": { - "href": "https://w3c.github.io/wot-architecture/", + "href": "https://www.w3.org/TR/2019/CR-wot-architecture-20190516/", "title": "Web of Things Architecture", "publisher": "W3C", - "date": "20 August 2017", + "date": "16 May 2019", "id": "wot-architecture" }, "WOT-TD": { - "href": "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/", + "href": "https://w3c.github.io/wot-thing-description/", "title": "WoT Thing Description ", "publisher": "W3C", "date": "16 May 2019", @@ -1339,7 +1339,7 @@

                                described in the - + WoT Architecture @@ -1580,7 +1580,7 @@

                                deliberately follows the - + WoT Thing Description @@ -1609,7 +1609,7 @@

                                interface (i.e. the - + WoT Interface @@ -3457,12 +3457,12 @@

                                "exposed", as - + defined in [ - + WOT-ARCHITECTURE ]. @@ -5675,7 +5675,7 @@

                                validated using - + JSON schema validation @@ -5862,7 +5862,7 @@

                                the means of - + defaults and @@ -5877,7 +5877,7 @@

                                specified in [ - + WOT-TD ] @@ -5892,7 +5892,7 @@

                                in a given - + TD .

                                @@ -5929,7 +5929,7 @@

                                item in the - + TD default values @@ -6007,10 +6007,11 @@

                                -The +The [ - -WOT-TD + + +WOT-TD obs @@ -6165,13 +6166,13 @@

                                ] for - + Thing that don't have - + default definitions @@ -6222,7 +6223,7 @@

                                third argument - + JSON schema validation @@ -7933,7 +7934,10 @@

                                data ); -

                                + + +
                                +

                                6.1 @@ -8929,14 +8933,14 @@

                                Based on the - + DataSchema definition , value - + MUST be @@ -8952,7 +8956,7 @@

                                defined for the - + Property that @@ -13737,11 +13741,11 @@

                                argument -and -qualifiers and -initialization +qualifiers +and +initialization value provided by @@ -14019,9 +14023,8 @@

                                MAY use - the -default +default handlers, thereby extending @@ -14039,8 +14042,9 @@

                                default behavior. Finally, + the -script +script would call @@ -16479,10 +16483,10 @@

                                reject promise - + with - -SecurityError + +SecurityError and terminate @@ -16493,11 +16497,8 @@

                                a request to - the -same - -underlying +underlying platform to stop @@ -16505,17 +16506,17 @@

                                external requests for - + WoT Interactions -, +, based on the - + Protocol Bindings -.
                              34. +.
                              35. If there was @@ -16525,30 +16526,29 @@

                                the request, reject - - -value -. - -promise - + +promise + with an - + Error - + object - + error - + with - -error.message - + +error.message + set to + the -error +same + +error code seen by @@ -16564,8 +16564,12 @@

                              36. Otherwise resolve - -promise + + +value +. + +promise and terminate @@ -19575,17 +19579,17 @@

                                match it against + the - -Thing + +Thing Description s found during - the -discovery +discovery process. If queries @@ -22071,15 +22075,15 @@

                                on a single + WoT -device. +device. In this case each - WoT -runtime +runtime instance will be @@ -23946,11 +23950,11 @@

                                , - -script +script execution context -, + +, Promise @@ -25395,13 +25399,13 @@

                                vocabulary from the - + Form definition in [ - + WOT-TD ]. @@ -26740,7 +26744,7 @@

                                [WOT-ARCHITECTURE]
                                - + Web of @@ -26749,16 +26753,14 @@

                                . W3C. -20 -August -2017. +16 +May +2019. URL: - -https://w3c.github.io/wot-architecture/ - -

                                -
                                -[WOT-PROTOCOL-BINDINGS] + +https://www.w3.org/TR/2019/CR-wot-architecture-20190516/ +
                                +[WOT-PROTOCOL-BINDINGS]
                                Web of @@ -26768,13 +26770,18 @@

                                Templates . W3C. + 20 August 2017. URL: - -https://w3c.github.io/wot-binding-templates/ -

                                +https://w3c.github.io/wot-architecture/ + + +https://w3c.github.io/wot-binding-templates/ + + +
                                [WOT-SECURITY-BEST-PRACTICES]
                                @@ -26856,7 +26863,7 @@

                                [WOT-TD]
                                - + WoT Thing @@ -26899,8 +26906,8 @@

                                URL: https://html.spec.whatwg.org/multipage/ - -https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/ + +https://w3c.github.io/wot-thing-description/

                                From 2123e5dbb493e6b5a163abcc8eda520fa656ab22 Mon Sep 17 00:00:00 2001 From: ashimura Date: Tue, 29 Oct 2019 00:14:30 +0900 Subject: [PATCH 372/464] updated pubdate Oct 28 --- releases/wd4/Overview.html | 12 ++++++------ releases/wd4/diff.html | 14 +++++++------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/releases/wd4/Overview.html b/releases/wd4/Overview.html index 66e4a03d..8382b60d 100644 --- a/releases/wd4/Overview.html +++ b/releases/wd4/Overview.html @@ -919,7 +919,7 @@ "shortName": "wot-scripting-api", "copyrightStart": 2017, "noLegacyStyle": true, - "publishDate": "2019-10-22", + "publishDate": "2019-10-28", "previousPublishDate": "2018-11-29", "previousMaturity": "", "edDraftURI": "https://w3c.github.io/wot-scripting-api/", @@ -1044,8 +1044,8 @@ "id": "webappsec" } }, - "publishISODate": "2019-10-22T00:00:00.000Z", - "generatedSubtitle": "WOrking Draft 22 October 2019" + "publishISODate": "2019-10-28T00:00:00.000Z", + "generatedSubtitle": "WOrking Draft 28 October 2019" } Web of Things (WoT) Scripting API

                                W3C Working Draft

                                + "2019-10-28">28 October 2019

                                This version:
                                - https://www.w3.org/TR/2019/WD-wot-scripting-api-20191022/ + "https://www.w3.org/TR/2019/WD-wot-scripting-api-20191028/"> + https://www.w3.org/TR/2019/WD-wot-scripting-api-20191028/
                                Latest published version:
                                diff --git a/releases/wd4/diff.html b/releases/wd4/diff.html index 434fa464..09e6f7b4 100644 --- a/releases/wd4/diff.html +++ b/releases/wd4/diff.html @@ -946,7 +946,7 @@ "shortName": "wot-scripting-api", "copyrightStart": 2017, "noLegacyStyle": true, - "publishDate": "2019-10-22", + "publishDate": "2019-10-28", "previousPublishDate": "2018-11-29", "previousMaturity": "", "edDraftURI": "https://w3c.github.io/wot-scripting-api/", @@ -1071,8 +1071,8 @@ "id": "webappsec" } }, - "publishISODate": "2019-10-22T00:00:00.000Z", - "generatedSubtitle": "WOrking Draft 22 October 2019" + "publishISODate": "2019-10-28T00:00:00.000Z", + "generatedSubtitle": "WOrking Draft 28 October 2019" } ]]> @@ -1121,8 +1121,8 @@

                                November 2018 -

                                37. diff --git a/releases/wd4/diff.html b/releases/wd4/diff.html index 09e6f7b4..5fd09303 100644 --- a/releases/wd4/diff.html +++ b/releases/wd4/diff.html @@ -1016,7 +1016,7 @@ "id": "wot-architecture" }, "WOT-TD": { - "href": "https://w3c.github.io/wot-thing-description/", + "href": "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/", "title": "WoT Thing Description ", "publisher": "W3C", "date": "16 May 2019", @@ -1580,7 +1580,7 @@

                                deliberately follows the - + WoT Thing Description @@ -1609,7 +1609,7 @@

                                interface (i.e. the - + WoT Interface @@ -5675,7 +5675,7 @@

                                validated using - + JSON schema validation @@ -5862,7 +5862,7 @@

                                the means of - + defaults and @@ -5877,7 +5877,7 @@

                                specified in [ - + WOT-TD ] @@ -5892,7 +5892,7 @@

                                in a given - + TD .

                                @@ -5929,7 +5929,7 @@

                                item in the - + TD default values @@ -6166,13 +6166,13 @@

                                ] for - + Thing that don't have - + default definitions @@ -6223,7 +6223,7 @@

                                third argument - + JSON schema validation @@ -8933,14 +8933,14 @@

                                Based on the - + DataSchema definition , value - + MUST be @@ -8956,7 +8956,7 @@

                                defined for the - + Property that @@ -25399,13 +25399,13 @@

                                vocabulary from the - + Form definition in [ - + WOT-TD ]. @@ -26863,7 +26863,7 @@

                                [WOT-TD]
                                - + WoT Thing @@ -26906,8 +26906,8 @@

                                URL: https://html.spec.whatwg.org/multipage/ - -https://w3c.github.io/wot-thing-description/ + +https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/

                                From a73efc1a89abc38b24975ff36dcd2abb3a977d55 Mon Sep 17 00:00:00 2001 From: ashimura Date: Tue, 29 Oct 2019 00:39:51 +0900 Subject: [PATCH 374/464] not json-schema-4-validation but json-schema-for-validation --- releases/wd4/Overview.html | 4 ++-- releases/wd4/diff.html | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/releases/wd4/Overview.html b/releases/wd4/Overview.html index 968b59f3..c0269318 100644 --- a/releases/wd4/Overview.html +++ b/releases/wd4/Overview.html @@ -2249,7 +2249,7 @@

                                WOT-TD]. It is expected to be a parsed JSON object that is validated using + "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/#json-schema-for-validation"> JSON schema validation.

                              37. If + "https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/#json-schema-for-validation"> JSON schema validation fails on td, throw "TypeError" and terminate these steps. diff --git a/releases/wd4/diff.html b/releases/wd4/diff.html index 5fd09303..f9ea198e 100644 --- a/releases/wd4/diff.html +++ b/releases/wd4/diff.html @@ -5675,7 +5675,7 @@

                                validated using - + JSON schema validation @@ -6223,7 +6223,7 @@

                                third argument - + JSON schema validation From bc6c76647302532f06bbd00bf6ff3935b823ecc6 Mon Sep 17 00:00:00 2001 From: ashimura Date: Tue, 29 Oct 2019 01:02:52 +0900 Subject: [PATCH 375/464] publish only Overview.html --- releases/wd4/manifest.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/releases/wd4/manifest.txt b/releases/wd4/manifest.txt index 578b5801..b251fbe6 100644 --- a/releases/wd4/manifest.txt +++ b/releases/wd4/manifest.txt @@ -1,2 +1 @@ Overview.html -diff.html From 60bbd87306ec09de45cf537cb47be39dbf120090 Mon Sep 17 00:00:00 2001 From: ashimura Date: Tue, 29 Oct 2019 02:09:49 +0900 Subject: [PATCH 376/464] feedback from wd4 --- index.html | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/index.html b/index.html index 6059e014..e7a5832e 100644 --- a/index.html +++ b/index.html @@ -20,10 +20,10 @@ noIDLIn: true, format: 'markdown', editors: [ - { name: "Zoltan Kis", company: "Intel", companyURL: "https://www.intel.com/" }, - { name: "Daniel Peintner", company: "Siemens AG", companyURL: "https://www.siemens.com/" }, - { name: "Johannes Hund", note: "Former Editor, when at Siemens AG" }, - { name: "Kazuaki Nimura", note: "Former Editor, at Fujitsu Ltd." }, + { name: "Zoltan Kis", w3cid: "57789", company: "Intel", companyURL: "https://www.intel.com/" }, + { name: "Daniel Peintner", w3cid: "39497", company: "Siemens AG", companyURL: "https://www.siemens.com/" }, + { name: "Johannes Hund", w3cid: "74472", note: "Former Editor, when at Siemens AG" }, + { name: "Kazuaki Nimura", w3cid: "59208", note: "Former Editor, at Fujitsu Ltd." }, ], wg: "Web of Things Working Group", wgURI: "https://www.w3.org/WoT/WG/", @@ -54,16 +54,16 @@ ], localBiblio: { "WOT-ARCHITECTURE" : { - href:"https://w3c.github.io/wot-architecture/", + href:"https://www.w3.org/TR/2019/CR-wot-architecture-20190516/", title: "Web of Things Architecture", publisher: "W3C", - date: "20 August 2017" + date: "16 May 2019" }, "WOT-TD" : { - href:"https://w3c.github.io/wot-thing-description/", + href:"https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/", title: "WoT Thing Description ", publisher: "W3C", - date: "20 August 2017" + date: "16 May 2019" }, "WOT-PROTOCOL-BINDINGS" : { href:"https://w3c.github.io/wot-binding-templates/", @@ -115,7 +115,7 @@

                                - The main Web of Things (WoT) concepts are described in the WoT Architecture document. The Web of Things is made of entities (Things) that can describe their capabilities in a machine-interpretable 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 WoT Architecture document. 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).

                                Scripting is an optional "convenience" building block in WoT and it is typically used in gateways that are able to run a WoT Runtime and script management, providing a convenient way to extend WoT support to new types of endpoints and implement WoT applications such as Thing Directory. @@ -124,7 +124,7 @@ This specification describes a programming interface 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 specification deliberately follows the WoT Thing Description specification closely. It is possible to implement simpler APIs on top of this API, or implementing directly the WoT network facing interface (i.e. the WoT Interface). + The specification deliberately follows the WoT Thing Description specification closely. It is possible to implement simpler APIs on top of this API, or implementing directly the WoT network facing interface (i.e. the WoT Interface).

                                This specification is implemented at least by the Thingweb project also known as node-wot, which is considered the reference open source implementation at the moment. Check its source code, including examples. Other, closed source implementations have been made by WG member companies and tested against node-wot in plug-fests. @@ -144,7 +144,7 @@

                                Introduction

                                WoT provides layered interoperability based on how Things are used: - "consumed" and "exposed", as defined in [[WOT-ARCHITECTURE]]. + "consumed" and "exposed", as defined in [[WOT-ARCHITECTURE]].

                                By consuming a TD, a client Thing creates a local runtime resource model that allows accessing the Properties, Actions and Events exposed by the server Thing on a remote device. @@ -302,7 +302,7 @@

                                The ThingDescription type

                                Represents a Thing Description (TD) as defined in [[!WOT-TD]]. It is expected to be - a parsed JSON object that is validated using JSON schema validation. + a parsed JSON object that is validated using JSON schema validation.

                                Fetching a Thing Description

                                @@ -325,7 +325,7 @@

                                The ThingDescription type

                                Expanding a Thing Description

                                Note that [[WOT-TD]] allows using a shortened Thing Description - by the means of defaults and requiring clients to expand them with default values specified in + by the means of defaults and requiring clients to expand them with default values specified in [[WOT-TD]] for the properties that are not explicitly defined in a given TD.

                                @@ -333,7 +333,7 @@

                                The ThingDescription type

                                To expand a TD given td, run the following steps:
                                1. - For each item in the TD default values table from [[!WOT-TD]], if the term is not defined in td, add the term definition with the default value specified in [[!WOT-TD]]. + For each item in the TD default values table from [[!WOT-TD]], if the term is not defined in td, add the term definition with the default value specified in [[!WOT-TD]].
                                @@ -353,12 +353,12 @@

                                The ThingDescription type

                              38. If any of the mandatory properties defined in [[!WOT-TD]] for - Thing - that don't have default definitions + Thing + that don't have default definitions are missing from td, throw "TypeError" and terminate these steps.
                              39. - If JSON schema validation fails on td, throw "TypeError" and terminate these steps. + If JSON schema validation fails on td, throw "TypeError" and terminate these steps.
                                40. @@ -588,7 +588,7 @@

                                The readProperty() method

                                Run the validate Property value sub-steps on value:
                                1. - Based on the DataSchema definition, value MUST be a JSON value and comply to the data schema defined for the Property that is found in this.getThingDescription().properties[propertyName]. + Based on the DataSchema definition, value MUST be a JSON value and comply to the data schema defined for the Property that is found in this.getThingDescription().properties[propertyName].
                                2. If this fails, throw SyntaxError, otherwise return value. @@ -1355,7 +1355,7 @@

                                  The ThingDiscovery interface

                                  The ThingDiscovery interface has a next() method and a done property, but it is not an Iterable. Look into Issue 177 for rationale.

                                  - The discovery results internal slot is an internal queue for temporarily storing the found ThingDescription objects until they are consumed by the application using the next() method. Implementations MAY optimize the size of this queue based on e.g. the available resources and the frequency of invoking the next() method. + The discovery results internal slot is an internal queue for temporarily storing the found ThingDescription objects until they are consumed by the application using the next() method. Implementations MAY optimize the size of this queue based on e.g. the available resources and the frequency of invoking the next() method.

                                  The filter property represents the discovery filter of type ThingFilter specified for the discovery. @@ -1394,10 +1394,10 @@

                                  The ThingDiscovery interface

                                - The start() method sets active to true. The stop() method sets active to false, but done may be still false if there are ThingDescription objects in the discovery results not yet consumed with next(). + The start() method sets active to true. The stop() method sets active to false, but done may be still false if there are ThingDescription objects in the discovery results not yet consumed with next().

                                - During successive calls of next(), active may be true or false, but done is set to false by next() only when both active is false and discovery results is empty. + During successive calls of next(), active may be true or false, but done is set to false by next() only when both active is false and discovery results is empty.

                                @@ -1998,7 +1998,7 @@

                                API design rationale

                                Polymorphic functions

                                - The reason to use function names like readProperty(), readMultipleProperties() etc. instead of a generic polymorphic read() function is that the current names map exactly to the "op" vocabulary from the Form definition in [[WOT-TD]]. + The reason to use function names like readProperty(), readMultipleProperties() etc. instead of a generic polymorphic read() function is that the current names map exactly to the "op" vocabulary from the Form definition in [[WOT-TD]].

                                From 06439919428dbf11f5b20125e5dc8380cd358d04 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 30 Oct 2019 15:42:31 +0100 Subject: [PATCH 377/464] chore: label as final version for recent Scripting API publication https://www.w3.org/TR/2019/WD-wot-scripting-api-20191028/ --- typescript/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/typescript/package.json b/typescript/package.json index bf3d7bc5..3936ce0a 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.7.0-NEXT-SNAPSHOT.16", + "version": "0.7.0", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From 285cb8132bae12265020ed15428e1d5a45a9b98a Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Fri, 22 Nov 2019 14:31:18 +0100 Subject: [PATCH 378/464] fix: typescript issue see https://github.com/eclipse/thingweb.node-wot/issues/143 --- typescript/index.d.ts | 2 +- typescript/package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/typescript/index.d.ts b/typescript/index.d.ts index 75c20ca0..0661ad43 100644 --- a/typescript/index.d.ts +++ b/typescript/index.d.ts @@ -78,7 +78,7 @@ export interface ThingDiscovery { * WoT provides a unified representation for data exchange between Things, standardized in the Wot Things Description specification. * In this version of the API, Thing Descriptions is expected to be a parsed JSON object. */ -export declare type ThingDescription = object | { [key: string]: any; }; +export declare type ThingDescription = { [key: string]: any; }; /** diff --git a/typescript/package.json b/typescript/package.json index 3936ce0a..b1acdf32 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "wot-typescript-definitions", - "version": "0.7.0", + "version": "0.7.1-SNAPSHOT.1", "description": "TypeScript definitions for the W3C WoT Scripting API", "author": "W3C Web of Things Working Group", "license": "W3C-20150513", From 6f24b4e1edb82e21097d65b82b276cddee1ec5ce Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Tue, 18 Feb 2020 10:48:41 +0200 Subject: [PATCH 379/464] Remove markdown from header Signed-off-by: Zoltan Kis --- index.html | 1 - 1 file changed, 1 deletion(-) diff --git a/index.html b/index.html index e7a5832e..d90b04c7 100644 --- a/index.html +++ b/index.html @@ -18,7 +18,6 @@ crEnd: "", inlineCSS: true, noIDLIn: true, - format: 'markdown', editors: [ { name: "Zoltan Kis", w3cid: "57789", company: "Intel", companyURL: "https://www.intel.com/" }, { name: "Daniel Peintner", w3cid: "39497", company: "Siemens AG", companyURL: "https://www.siemens.com/" }, From f07d827375227f736096cb3f044f30b7668b8e5b Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 19 Feb 2020 17:43:16 +0200 Subject: [PATCH 380/464] Fix #202: add formIndex to InteractionOptions Signed-off-by: Zoltan Kis --- index.html | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/index.html b/index.html index d90b04c7..e4ee4204 100644 --- a/index.html +++ b/index.html @@ -300,10 +300,11 @@

                                The ThingDescription type

                                - Represents a Thing Description (TD) as defined in [[!WOT-TD]]. It is expected to be + Represents a Thing Description (TD) as + defined in + [[!WOT-TD]]. It is expected to be a parsed JSON object that is validated using JSON schema validation.

                                -

                                Fetching a Thing Description

                                Fetching a TD given a URL should be done with an external method, such as the Fetch API or a HTTP client library, which offer already standardized options on specifying fetch details. @@ -502,6 +503,7 @@

                                The ConsumedThing interface

                                ThingDescription getThingDescription(); }; dictionary InteractionOptions { + unsigned long formIndex; object uriVariables; }; typedef object PropertyMap; @@ -544,9 +546,29 @@

                                The getThingDescription() method

                                -

                                The InteractionOptions dictionary

                                +

                                + The InteractionOptions + dictionary +

                                +

                                + Holds the interaction options that need to be exposed for application scripts according to the Thing Description. +

                                +

                                + The formIndex property, if defined, represents an application + hint for which Form definition, identified by this index, + of the TD to use for the given WoT interaction. + Implementations SHOULD use the Form with this index for + making the interaction, but MAY override this value if the index is not + found or not valid. + If not defined, implementations SHOULD attempt to use the + Form definitions in order of appearance as listed in the + TD for the given Wot Interaction. +

                                - Holds the interaction options that need to be exposed for application scripts according to the Thing Description. In this version of the specification only URI template variables are used, represented as parsed JSON objects defined in [[!WOT-TD]]. + The uriVariables property if defined, represents the URI + template variables to be used with the WoT Interaction that are represented + as + parsed JSON objects defined in [[!WOT-TD]].

                                The support for URI variables comes from the need exposed by [[WOT-TD]] to be able to describe existing TDs that use them, but it should be possible to write a Thing Description that would use Actions for representing the interactions that need URI variables and represent the URI variables as parameters to the Action and in that case that could be encapsulated by the implementations and the options parameter could be dismissed from the methods exposed by this API. From 2c8801a1c98c531930081880f3f4325d6b635ad2 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 19 Feb 2020 18:11:29 +0200 Subject: [PATCH 381/464] Fix #199: improve explanation for setting property write handlers Signed-off-by: Zoltan Kis --- index.html | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/index.html b/index.html index e4ee4204..5f0f0f80 100644 --- a/index.html +++ b/index.html @@ -1088,16 +1088,31 @@

                                The PropertyWriteHandler callback

                                The setPropertyWriteHandler() method

                                - Takes name as string argument and writeHandler as argument of type PropertyWriteHandler. Sets the service handler for writing the specified Property matched by name. Throws on error. Returns a reference to this object for supporting chaining. + Takes name as string argument and writeHandler + as argument of type PropertyWriteHandler. Sets the service handler + that will be used for serving write requests for writing the specified + Property matched by name. Throws on error. + Returns a reference to this object for supporting chaining. +

                                +

                                + 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 and notifying observers on change, based on the Thing Description. + There MUST be at most one write handler for any given Property, so newly added handlers MUST replace the previous handlers. If no write handler is initialized for any given Property, implementations SHOULD implement default property update if the Property is + writeable and notifying observers on change if the Property is + observeable, based on the Thing Description.

                                Handling Property write requests

                                - When a network request for writing a Property propertyName with a new value value is received, implementations SHOULD run the following update property steps, given propertyName, value and mode set to "single": + When a network request for writing a Property propertyName + with a new value value is received, implementations SHOULD run + the following update property steps, given + propertyName, value and mode set to + "single":
                                1. If a Property with propertyName does not exist, return ReferenceError in the reply and terminate these steps. @@ -1120,7 +1135,7 @@

                                  The PropertyWriteHandler callback

                                  If there is no handler to handle the request, return NotSupportedError in the reply and terminate these steps.
                                -
                                > +
                                When a network request for writing multiple Properties given in an object propertyNames is received, run the following steps:
                                  From cd2f7eea1e130050c40ff8d0b7ee8a8364ae3c58 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Fri, 21 Feb 2020 14:44:08 +0200 Subject: [PATCH 382/464] use jquery-less ReSpec as it's lighter, see also https://github.com/w3c/wot-thing-description/pull/872/files --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 5f0f0f80..d0be429f 100644 --- a/index.html +++ b/index.html @@ -3,7 +3,7 @@ Web of Things (WoT) Scripting API - + +