API improvements

[zolkis]

This issue is for discussing API improvements.

Let's start the discussion on observing functionality on the ConsumedThing interface.

There we have

Observable observe(DOMString name, RequestType requestType);

enum RequestType {  "property", "action", "event", "td" };

It allows subscribing and unsubscribing to notifications like:

• property change made by others
• action invoked by others
• any event supported by the target Thing
• changes to the Thing Description (TD) of the Thing.

Note that these could be also modeled with default events on ExposedThing, one being dedicated to 'descriptionchange', one for 'propertychange', one for 'actioninvocation' and then the signature would change to:

Observable observe(DOMString eventName);

but the functionality would be implicit.

I wonder which would be more developer-friendly.

[mkovatsc]

Where does the assumption come from that arbitrary Things do emit a notification when an Action was invoked? Is there any existing device already doing this?

[zolkis]

It comes from the early WoT scripting API. We also discussed it in calls. @knimura, IIRC you needed it?

[zolkis]

Apart from 'onactioninvoked', which design do you prefer?

[zolkis]

A simplified ConsumedThing interface based on the FPWD version, but taking into account also #68:

interface ConsumedThing {
    readonly attribute DOMString name;
    readonly attribute ThingDescription description;
    Promise<any>  invokeAction(DOMString name, any parameters);
    Promise<void> setProperty(DOMString name, any value);
    Promise<any>  getProperty(DOMString name);
    Observable    observe(DOMString name, optional ObserveOptions options);
};

callback ThingEventListener = void (ThingEvent event);

dictionary ObserveOptions {  // for conditional events
    callback filter = boolean (optional any value);
    // property-value pairs for constraints, defined by the TD
};

interface ThingEvent: Event {
    readonly attribute any data;
};

[zolkis]

Alternatively, taking into account #64, ConsumedThing can provide an object representation of a Thing where Thing properties are mapped as object properties, Thing actions are mapped as functions, Thing Events are mapped as object events. In addition, Events can also be handled by observe() in order to support complex events such as conditional events, but this can be optional.

interface ConsumedThing {
    readonly attribute DOMString name;
    readonly attribute ThingDescription description;
    Promise<object> renderAsObject();
    Observable observe(DOMString name, optional ObserveOptions options);
};

On WoT object level we'd have (taking into account #69):

interface WoT {
    Observable<ConsumedThing> discover(optional ThingFilter filter);
    Promise<ThingDescription> fetchDescription(USVString url);
    Promise<ConsumedThing> consume(ThingDescription description); 
    Promise<ExposedThing>     expose(ThingInit init);  // to be discussed later
};

@draggett , @danielpeintner, @knimura , @mkovatsc : opinions?

[mkovatsc]

Thank you for laying out these alternatives!

Overall, I see the assumption that the Scripting API, and in this case even the client API, can define which Interactions Things will offer as highly critical. This is leading to a Scripting API that is detached from the TD model and the reality of existing platforms (e.g., most devices do not provide notifications when an Action is invoked; if they do, it would become an Event in the TD). You are going down the path of a prescriptive standard that just becomes yet another standard out there.

---

Starting from the TD model, I would expect the following interface (here with Promises to deal with the distributed system aspects):

interface ConsumedThing {
    readonly attribute DOMString name;
    readonly attribute ThingDescription description;
    Promise<any>  readProperty(DOMString name); // aligned with 'writable'
    Observable    observeProperty(DOMString name);
    Promise<void> writeProperty(DOMString name, any value); // aligned with 'writable'
    Promise<any>  invokeAction(DOMString name, any parameters);
    Observable    subscribeEvent(DOMString name);
};

I am missing how the ObserveOptions should work, because the TD cannot define any constraints (so far).

---

For the WoT object, I would see this as simple:

interface WoT {
    Observable<ConsumedThing> discover(optional ThingFilter filter);
    Promise<ThingDescription> fetchDescription(USVString url);
    Promise<ConsumedThing>    consume(ThingDescription description); 
    Promise<ExposedThing>     expose(ThingDescription description); // maybe expose(ThingTemplate description)
};

The ThingInit basically had either only a name or already a description template. What we still need to figure out is the type ThingDescription. Having it as a string is pretty poor. Having it as object would need our famous pure JSON serialization, as JSON-LD does not work as JS object.

Also, ThingDescription would need to be a super type for either a TD instance (all links with network addresses etc.) for consume or a TD template (no links and bindings at all). Or we make Promise<ExposedThing> expose(ThingTemplate description);. The ThingDescription would correspond to HTML, the ThingTemplate to PHP/JSP/etc., maybe even with server-side code included.

Overall, I would like to get a programmatic way to construct TDs with the Scripting API (like we have with addProperty() etc., see #71 for the declaration problem).

---

Promise<object> renderAsObject();

The actual problem is then only delegated to that object: how should it work? We cannot use plain object properties and functions for distributed Things. Ideally, the ConsumedThing itself should already be that object. Maybe we can see how far we get with JavaScript's async/await?

[zolkis]

Overall, I see the assumption that the Scripting API, and in this case even the client API, can define which Interactions Things will offer as highly critical.

No, it just follows the already agreed representation and interactions: Thing, properties, actions, events. I don't see what do you fear and from where did you draw your conclusion.

This is leading to a Scripting API that is detached from the TD model and the reality of existing platforms (e.g., most devices do not provide notifications when an Action is invoked; if they do, it would become an Event in the TD).

What makes it detached from TD model? It provides a mechanism that is optional to use by scripts if the TD defines them and the policy how to use it. I agree that all notifications could be modeled by events, but that includes property changes as well...

You are going down the path of a prescriptive standard that just becomes yet another standard out there.

Another far fetched conclusion, would you please take the time to explain with concrete terms? What is prescriptive here? And what is the difference between "normative" (as per W3C specification) and your term "prescriptive"?

Observable subscribeEvent(DOMString name);

The name is wrong, Observable already has a subscribe() method. Let's stick to observe().

Observable    observeProperty(DOMString name);

Why prescribe that you can observe a property when the TD eventually hasn't defined that interaction? :) Isn't this leading to just another standard that is detached from the TD? And why cannot this be modeled as an event?

To be clear, I didn't ask for watching action invocation, it was raised by others (and IIRC actually I had to put it back after once I removed it from the spec), but I can see why a business logic would want that information. If you say then the TD should define it as an event I would say okay, but then let's also model other notifications as TD events as well. The way you've put it doesn't seem consistent.

Promise<ExposedThing>     expose(ThingDescription description); 

As I mentioned, this is postponed to a later discussion. Let's fix ConsumedThing first. That is why I left it with the FPWD signature. However, I agree with this signature.

Having it as a string is pretty poor. Having it as object would need our famous pure JSON serialization, as JSON-LD does not work as JS object.

I agree. But we have discussed during the past calls that at the moment we can't do better than representing it as a string(-serialized form). Should this change (with TD getting more maturity), we will change the representation. At this moment the apps don't care how the TD is written, it is the implementation's problem.

Or we make Promise expose(ThingTemplate description);

This is fine, if you want to make a distinction between a ThingTemplate that may contain [links to] scripts vs ThingDescription. We should document TD vs TT very well. Any links?

I would like to get a programmatic way to construct TDs with the Scripting API

That is also a valid requirement, however, we should not mix declarative and programmatic definition of a TD. The way I see it we should first do the simpler API above, and define a separate interface for programmatic definition of a TD (actually ThingTemplate).

The actual problem is then only delegated to that object: how should it work? We cannot use plain object properties and functions for distributed Things.

Why not? There is quite direct mapping between Thing and object. Just mentioning this topic has also been discussed in #64.

Ideally, the ConsumedThing itself should already be that object.

Then we run into namespacing problems, as mentioned in #64.

Maybe we can see how far we get with JavaScript's async/await?

Hmm.. I don't get what this has to do with the above discussion?

[mkovatsc]

No, it just follows the already agreed representation and interactions: Thing, properties, actions, events. I don't see what do you fear and from where did you draw your conclusion.

Actions are not able to emit Events when invoked. It is not modeled in the TD, nor implemented on a range of existing platform. You cannot add this feature on the client side; it would have to be implemented on the server side, which is not necessarily an ExposedThing, but an actual device augmented with a TD.

What makes it detached from TD model? It provides a mechanism that is optional to use by scripts if the TD defines them and the policy how to use it.

You are adding a lot of features that are not part of the TD. The Scripting API should have a stable core first before we open up that much exploration. Moreover, the charter explicitly states that the Scripting API must follow the TD; I now can see why some Members were so eager about this.

Another far fetched conclusion, would you please take the time to explain with concrete terms? What is prescriptive here? And what is the difference between "normative" (as per W3C specification) and your term "prescriptive"?

By presecriptive the WoT WG means that many platforms standardize what must be implement on the devices and how. To not become yet another standard, W3C WoT sees devices as fixed black boxes that can be described by a TD. When you start expecting a message from a device when a client called an Action, then this will only work by prescribing the device to implement this. This is all nice when you define your world only by Consumed- and ExposedThings. But not all Things will be ExposedThing software objects.

Why prescribe that you can observe a property when the TD eventually hasn't defined that interaction? :)

And there being a definion for setProperty() is working for you, although TDs might have all 'writable' flags set to false?

The name is wrong, Observable already has a subscribe() method. Let's stick to observe().

You still have not understood the point about Change-of-Value notifications of Properties vs stand-alone Event notifications of Events. The different words "observe" and "subscribe" shall express the different philosophies of Change-of-Value notifications like CoAP Observe and stand-alone Events of PubSub, respectively. The give you different behavior and guarantees that a developer of a distributed system has to be aware of.

Maybe we can see how far we get with JavaScript's async/await?

Hmm.. I don't get what this has to do with the above discussion?

This is an API for a distributed system. Naively assigning a value to an object property, expecting it to have crossed the Internet and at any point reading it out again just does not work in JavaScript. This is the reason why the first approach uses get/setProperty() and Promises. With async/await we might get a bit closer to the holy grail of distributed systems APIs.

[zolkis]

Actions are not able to emit Events when invoked.

I was not aware of that requirement. Can you quote the source? (I am not against it, just wondering about WoT requirement management).
Why did node-wot have the emitEvent() function then?

It is not modeled in the TD,

Well, it may be modeled in the TD. The API just provided a closure.

nor implemented on a range of existing platform.

Well, actions are not implemented on a range of existing platform, either.

You cannot add this feature on the client side; it would have to be implemented on the server side,

Of course. All the time we've been discussing server API here.

which is not necessarily an ExposedThing, but an actual device augmented with a TD.

Currently I am not aware of any solution or even mechanism for that outside of ExposedThing - or please provide references. The whole purpose of ExposedThing was to enable augmenting a device with a TD... for instance by representing a device in a WoT runtime and exposing it with a TD.

You are adding a lot of features that are not part of the TD.

It's not me: these features were there in the original IG API under your watch...

By presecriptive the WoT WG means that many platforms standardize what must be implement on the devices and how.

Ok, we agree on that point then. However, having a mechanism in scripting API is not prescriptive, since it can fail and notifies the script about that.

That of course doesn't mean we should not clean up the API, just mentioning it is not prescriptive.

But not all Things will be ExposedThing software objects.

Of course not, but when they are, they could actually be represented as objects.

Naively assigning a value to an object property, expecting it to have crossed the Internet and at any point reading it out again just does not work in JavaScript. This is the reason why the first approach uses get/setProperty() and Promises.

In principle I agree if it was for live objects. I don't exactly know what @draggett had in mind - but also don't forget implementations can actually start a transaction and block until completion (there is no UI), or could use shard sync on that property, recording the change intents and resolving them in the background, while providing confirmed values on reads. I'd agree it would be too much twisting for the simplicity, and I have no problem writing a few more characters for calling an asynchronous setter instead of just assigning an object property.

What the object representation would solve is more like introspection of the represented TD, for which we don't yet have a solution (see #38). Of course that can be solved in another way - in the future.

[mkovatsc]

Actions are not able to emit Events when invoked.

I was not aware of that requirement. Can you quote the source? (I am not against it, just wondering about WoT requirement management).
Why did node-wot have the emitEvent() function then?

emitEvent() has been the stub to implement the Event Interaction Pattern.

If a Thing wants notify other Things that an Action was invoked, it has to implement this explicitly by adding an Event Interaction and connecting the two Interactions through application code. By having an Action Interaction alone, it cannot do it. Actions are not subscribable.

Well, actions are not implemented on a range of existing platform, either.

Action is an abstract interaction concept for invoking some activity on the target. All RPC-style platforms implement Actions.

It feels like you are to fixated on the implementation through the Scripting API. The Scripting API is optional. The concepts must come from our Thing abstraction and the TD, and not from what is possible in JavaScript when programming a green field.

[zolkis]

Except that one cannot be sure what the TD will support in the future, and while you can break a TD, it is best to be avoided in scripting API.

Again, action notifications are not my idea, they've been present before the WG, and I am not sure if the above is group decision or your opinion. We need to clarify that during the next F2F.

However, the best test for whether do we really need a feature is dropping it...

So the current assumption on the simplified ConsumeThing interface:

interface ConsumedThing {
    readonly attribute DOMString name;
    readonly attribute ThingDescription description;
    Promise<any>  readProperty(DOMString name); // aligned with 'writable'
    Promise<void> writeProperty(DOMString name, any value); // aligned with 'writable'
    Promise<any>  invokeAction(DOMString name, any parameters);
    Observable    observe(DOMString name);  // event / property change notifications
};

Why can observe() handle both WoT Events and WoT Property Change: subscribing to an Observable requires callbacks for handling next value, error and completion. They can model events, a stream of values with various constraints, or simple changes, including the (claimed) differences between WoT Events and WoT Property Change. Differentiation is by name: if name matches a property on the Thing, then it is a value change notification. If it matches an event defined in the TD, then it is an event notification. The implementation will use the appropriate error handling policy specified in the algorithm (coming in the near future).

Before you equate observe() with CoAP observe, let me say they are NOT the same thing :).

We should discuss in the F2F whether the API should split property change notifications and WoT Event handling.

[mkovatsc]

There have not been any Action notifications. Good that we can now keep it this way :)

[mkovatsc]

interface ConsumedThing {
    readonly attribute DOMString name;
    readonly attribute ThingDescription description;
    Promise<any>    readProperty(DOMString name); // aligned with 'writable'
    Promise<void>   writeProperty(DOMString name, any value); // aligned with 'writable'
    Promise<any>    invokeAction(DOMString name, any parameters);
    Observable<any> observe(DOMString name);  // event / property change notifications
};

+1 for its simplicity. Let's discuss this proposal at TPAC, I guess including:

interface WoT {
    Observable<ConsumedThing> discover(optional ThingFilter filter);
    Promise<ThingDescription> fetchDescription(USVString url);
    Promise<ConsumedThing> consume(ThingDescription description); 
//  Promise<ExposedThing>     expose(...);  // t.b.d.
};

[zolkis]

Yes, that is the proposal for ConsumedThings and let's see on the F2F if anyone will want action notifications and how the group decides about it.

About the WoT interface, IMHO we should start with

interface WoT {
    Observable<ConsumedThing> discover(optional ThingFilter filter);
    Promise<ThingDescription> fetchDescription(USVString url);
    Promise<ConsumedThing> consume(ThingDescription description); 
    Promise<ExposedThing> expose(ThingTemplate description);
};

ThingTemplate to be defined...

and ExposedThing concept with building and running interface defined by different interfaces, but used on the same object when implemented.

interface ExposedThing {
    // define how to expose and run the Thing
    Promise<void> register(optional USVString url);
    Promise<void> unregister(optional USVString url);
    Promise<void> start();
    Promise<void> stop();
    Promise<void> emitEvent(DOMString eventName, any payload);
};

interface ThingBuilder {
    readonly attribute ThingDescription description;
    // define Thing Description modifiers, return itself for chainability
    ThingBuilder  addProperty(ThingPropertyInit property);  // throws on error
    ThingBuilder  removeProperty(DOMString name);  // throws on error
    ThingBuilder  addAction(ThingActionInit action);  // throws on error
    ThingBuilder  removeAction(DOMString name);  // throws on error
    ThingBuilder  addEvent(ThingEventInit event);  // throws on error
    ThingBuilder  removeEvent(DOMString name);  // throws on error
};

ExposedThing implements ConsumedThing;
ExposedThing implements ThingBuilder;  // can be optional in the beginning
};

dictionary ThingPropertyInit {
    DOMString name;
    boolean writable;
    boolean observable;
    PropertyType type;
    sequence<SemanticType> semanticTypes;
    any value;
    callback onwrite = Promise<void> (any value);
};

The onwrite callback could also be optional parameter to the addProperty function instead of being dictionary member.

We need to define PropertyType and work more on ThingActionInit (arg and return types) in order to avoid using TD fragments (that defy the purpose of ExposedThing, namely to programmatically define a TD, and not just assemble from TD fragments).

[mkovatsc]

What is PropertyType type;? The data type? The type of that object would be the same as for inputData and outputData of Actions...

I would have expected a boolean observable;.

callback onread is not required. We only need to act upon changes. Ideally, Property state can be served directly from the runtime implementation without calling the script.