Add detailed discovery use cases. Add future use cases for TD changes in local runtimes. Remove semantic translators. Remove handlers for adding and removing property. Add options to property requests. Add discovery type for 'other' extensions.

Signed-off-by: Zoltan Kis <[email protected]>

Author: zolkis

index.html

@@ -256,8 +256,13 @@
   <p>
     The following scripting use cases are covered in this specification:
     <ul>
+      <li>Discover all <a>Things</a> in the WoT network by sending a broadcast request.</li>
+      <li>Discover <a>Things</a> running in the local <a>WoT Runtime</a>.</li>
+      <li>Discover nearby <a>Things</a>, for instance by NFC or Bluetooth.</li>
+      <li>Discover <a>Things</a> by sending a discovery request to a given registry.</li>
       <li>Discover <a>Thing</a>s by filters defined on <a>Thing Description</a>s</li>
-      <li>Discover <a>Thing</a>s by semantic filters</li>
+      <li>Discover <a>Thing</a>s by semantic filters.</li>
+      <li>Stop or suppress an ongoing discovery process.</li>
       <li>Fetch and <a>consume a TD</a> of a remote <a>Thing</a>.</li>
       <li>On a consumed <a>Thing</a>,
         <ul>
@@ -269,18 +274,18 @@
             <ul>
               <li>Add a listener to an event.</li>
               <li>Remove a listener from an event.</li>
+              <li>Remove all listeners.</li>
             </ul>
             Default events are the following:
             <ul>
               <li>A property has changed.</li>
               <li>An action has been invoked.</li>
-              <li>Other Things have added an event listener.</li>
               <li><a>Thing Description</a> has changed, i.e. properties, events or actions have been defined, removed, or the definition has changed.</li>
             </ul>
           </li>
         </ul>
       </li>
-      <li>Retrieve a thing that is exposed by the local runtime</li>
+      <li>Retrieve a thing.</li>
       <li>Create and expose a local <a>Thing</a> based on a <a>Thing Description</a>.</li>
       <li>Programmatically create and expose a local <a>Thing</a>. This may include the following use cases:
         <ul>
@@ -294,19 +299,28 @@
           <li>Emit an event, i.e. notify all listeners subscribed to that event.</li>
           <li>Register handlers for external requests:
             <ul>
-              <li>to fetch the <a>Thing Description</a>;</li>
+              <li>to retrieve a property value;</li>
+              <li>to update a property value;</li>
               <li>to run an action: take the parameters from the request, execute the defined action, and return the result;</li>
               <li>to add a listener to an event;</li>
               <li>to remove an event listener.</li>
+              <li>to fetch the <a>Thing Description</a>;</li>
             </ul>
           </li>
-          <li>Register handler for semantic translation of property values.</li>
-          <li>Register the Thing.</li>
-          <li>Unregister the Thing.</li>
-          <li>Start the exposed <a>Thing</a> in order to process external requests.</li>
-          <li>Stop the exposed <a>Thing</a>.
         </ul>
       </li>
+      <li>Register the Thing.</li>
+      <li>Unregister the Thing.</li>
+      <li>Start the exposed <a>Thing</a> in order to process external requests.</li>
+      <li>Stop the exposed <a>Thing</a>.</li>
+    </ul>
+  </p>
+  <p>
+    The following use cases are being considered for next versions:
+    <ul>
+      <li>Add, remove and update the definition of a property on a Thing that runs in the same the WoT Runtime.</li>
+      <li>Add, remove and update the definition of an action on a Thing that runs in the same the WoT Runtime.</li>
+      <li>Add, remove and update the definition of an event on a Thing that runs in the same the WoT Runtime.</li>
     </ul>
   </p>
   </section>
@@ -342,7 +356,7 @@
     };
 
     // TBD: if extensible by applications
-    enum DiscoveryType { "any", "local", "nearby", "directory", "broadcast" };
+    enum DiscoveryType { "any", "local", "nearby", "directory", "broadcast", "other" };
 
     dictionary ThingFilter: ThingInit {
       DiscoveryType type = "any";
@@ -382,8 +396,6 @@
       ExposedThing addEvent(ThingEventInit event);
       ExposedThing removeEvent(DOMString name);
 
-      ExposedThing addSemanticTranslator(SemanticTranslator handler);
-
       Promise&lt;void&gt; register(optional USVString directory);
       Promise&lt;void&gt; unregister();
 
@@ -393,8 +405,6 @@
       Promise&lt;void&gt; emitEvent(DOMString eventName, any payload);
 
       // define request handlers (one per request type, so no events here)
-      // TBD: ExposedThing onAddProperty(PropertyRequestHandler handler);
-      // TBD: ExposedThing onRemoveProperty(PropertyRequestHandler handler);
 
       ExposedThing onRetrieveProperty(PropertyRequestHandler handler);
       ExposedThing onUpdateProperty(PropertyRequestHandler handler);
@@ -409,11 +419,11 @@
     callback PropertyRequestHandler = void (PropertyRequest request);
     callback ActionRequestHandler = void (ActionRequest request);
     callback ObserveRequestHandler = void (ObserveRequest request);
-    callback SemanticTranslator = any (DOMString propertyName, SemanticType type);
 
     dictionary PropertyRequest {
         USVString from;
         ThingPropertyInit property;
+        Dictionary options;
     };
 
     dictionary ActionRequest {
@@ -430,7 +440,7 @@
 
     enum ObserveType { "property", "action", "event", "td" };
 
-    dictionary SemanticType {
+    dictionary SemanticType {  // TBD what is the use case?
       DOMString name;
       DOMString context;
     };

rationale.md

@@ -28,3 +28,11 @@ Based on [issue 16](https://github.com/w3c/wot-scripting-api/issues/16) there is
 Resolutions:
 - Use [Observables](https://github.com/tc39/proposal-observable) for controlling the discovery process (subscribe, unsubscribe).
 - Use a single filter definition that also contains a property for discovery type, defaulting to `"any"`. It is simpler and more intuitive to use than having a separate parameter for discovery type. Some of the discovery types, such as registry/directory based discovery also require another parameter for the address of the directory. This can be provided as a required property in the discovery filter, described in the discovery algorithm.
+
+## Server API (`ExposedThing`)
+Scripts that define Exposed Things should ensure the following:
+1. define properties, actions and events according to the Thing Description.
+2. define request handler functions to implement the serving end for the Client API.
+
+## Client API (`ConsumedThing`)
+Scripts that use the Client API are basically sending requests to servers in order to retrieve or update properties, invoke actions, and observe properties, actions and events. When the `ConsumedThing` is fetched, its Thing Description is also fetched, then client scripts can track changes by subscribing to events that signal TD changes.