Should writeProperty() return a value

[danielpeintner]

We currently have the following definition for writeProperty()

  Promise<void> writeProperty(DOMString propertyName,
                              any value,
                              optional InteractionOptions options = null);

I wonder whether the return value should be Promise<any> instead of Promise<void> ?

There may be different use-cases were a server might modify the value initially provided (e.g., round a number 1.2345 to 1.23 by limiting digits) and returning the actually set value would be helpful. No additional readProperty() needed.

What are the consequences of such a change?

[zolkis]

IMHO it looks difficult to make a consistent API contract/semantics here.

1. If the semantics is "return the actually written value"

• Some protocols/devices will just support an ack/error, not the value they have actually written.
• So the implementation cannot promise to know the exact value written, unless read again, which is an extra roundtrip and then it's best done by the application script.
• Returning the same value from implementation if there is no support to know the actual written value does not fulfil the semantics "return the written value".

2. If the semantics is "return either the same value or the written value"
   That's worse than re-reading the value, so I would not go here.

3. If the semantics is "return either the written value or undefined if not supported", (where undefined is represented as a special object reference in ECMAScript that denotes undefined).
   I guess in most of the cases this could be implemented., but this might lead to inefficient implementations for some of the unsupported cases and then the app scripts should have the control to manage that themselves and don't rely on implementation smartness.

This is mainly why the current spec just writes the value, reports success/error and if a script is interested in the real value written, would need to call a read again.
Note that if there is protocol support for returning the actual (potentially modified) written value, implementations could cache the actually written value and provide that without roundtrip on the next read request if certain conditions apply.

Speaking about that, we could have scripting-specific InteractionOption entries for reads, e.g.

• making a new read request or cached value is fine within given reporting rate (or validity period)
• ones that would support high frequency reads (e.g. sampling rate, reporting rate, buffer size etc), solving Very high frequency updates #107.

Then if we go there, we could have scripting-specific InteractionOption entries for writes, e.g.

• preference to provide the actual written value if supported; if not supported, then null is returned.

So I'd go with the following solution: define a write InteractionOption flag the apps can set, but the default should be off, for efficiency. If the option is not supported for given device or protocol, instead of a write error, the write would succeed but it would return undefined for the written value. Then the app will know that an explicit read is needed.

However, the extra check needed for undefined makes this impractical in scripts, so IMHO it would be both simpler and more efficient to leave it the current way, requiring apps to re-read, eventually adding some read options outlined above.

[zolkis]

We could indeed modify the writeProperty() signature to return any. But what would be the algorithm?

Ideally we'd need a parameter or an interaction option for telling "please return the written value if possible", with the default being false, in order to avoid unnecessary network round-trips.

That interaction option could (should?) come from the TD. Since the TD "owns" interaction descriptions, IMHO the Scripting API should not invent extra interaction options that are not supported by the TD.

As for the algorithm -- assuming there was that interaction option --: if the other end doesn't support returning the written value, it should return null, meaning the client has to make an explicit readProperty() request.

Corner cases:

• if the Property was write-only, write_with_return would return null
• if the Property was read-only, write would return error anyway.

[egekorkan]

I think it can help to think from the perspective where the write request is actually responded with a payload, how would the Scriping API handle it.

• HTTP: Server shouldn't return anything in the body but it can indicate that the value hasn't changed, is not allowed or is successful IF writeproperty is done as a PUT request ( https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT). If it is done as a POST, then it can return a body. (I think all these apply to CoAP as well)
• MQTT: With MQTT 5 it is possible to indicate a topic to respond to (by publishing) for a publish request. So technically an MQTT Thing can also reply to a writeproperty request with a specific payload.

For the case of node-wot http binding, an Exposed Thing can reject the writeproperty and supply a string (like an error message) which will be automatically returned to the client. At the moment, if something like this happens, there is no way to describe it in the TD or intrepret it in the scripting level. This was the reason behind issue #200 .

[zolkis]

Well, if a WoT implementation adds something to the interaction that has been defined in the TD, that is thin ice territory and subject of eventual future breaks, since the TD is supposed to be able to define the whole interaction, including error handling (and sensible defaults for the non-defined cases).

Of course, the Scripting API should be generic enough to allow that - we agree there.

The error path is already almost covered, since the data returned with an error could be conveyed in an Error object on the reject promise path. What we've been discussing in #200 was the error representation (mapping of error names, not the data). The error data could already been transmitted in my understanding.

The open thing (to me) is this issue, i.e. allowing a return value from writes, which it seems we could do anyway, based on your comment. What remains open (and discussed in TD issue 875 is the algorithm: what does the TD define and how Scripting should implement it.

[mmccool]

If the implementation does something that is incorrectly described in the TD, then the TD is incorrect, not the implementation. The TD describes the implementation, whatever it does. So, if for example, we generate tests using the TD and find that we CAN write to a readonly property, then the test should indicate that the TD is an incorrect description.

[mmccool]

Also, to follow up on "should a value be returned from a write": if we want to describe pre-existing implementations, we need to allow for the fact that some implementations may have writes that do NOT return the new value. In fact this might be done to save bandwidth; or the device might do something else entirely, like send a simple acknowledgement.

I think it's ok to say that the default behaviour is to echo the written value. However, we probably need a way to override that in the protocol binding (and this should be some normative attribute, which we currently don't have, so... probably need to think about adding this to TD-next; maybe "writeEcho" with a default value of "true". The other thing we can do in the meantime is just say that anything that does NOT echo data written should be described as an "action"... and this is fine in the short term, and maybe in the long term, too... but we should discuss further, maybe in the TD call).

[mmccool]

Based on the discussion, returning "void" from writeProperty is also fine, and in fact is better, since it covers all cases (although it might ignore data from the protocol). If you WANT to look at the return data... then use an action.

[danielpeintner]

In the Scripting API call on 2/24 we discussed the topic and the consensus was to stay with the current form of returning void in case of writeProperty() because it is

• more consistent
• simpler and
• safer.

Moreover, for the case (or the need) of returning a value the action interaction is a better fit.

Note: We also plan to collect/log such design decisions in Github, the spec or an auxiliary document.

[danielpeintner]

Note: We also plan to collect/log such design decisions in Github, the spec or an auxiliary document.

see #205

[egekorkan]

Actually, what is the expected behavior when a writeproperty indeed returns something? It could be that the TD is designed for an existing device and the TD cannot be changed due to some reason. Is it hidden to a Scripting API Consumer? There could be an issue (albeit a small one) if one interacts with that (weirdly designed) Thing via a REST Client and then with a Scripting API implementation and observe different behavior.

[zolkis]

Actually, what is the expected behavior when a writeproperty indeed returns something?

Right now the Scripting API can handle it only if it that something is an error.
For positive payload returns an Action can describe the interaction, hence and action should be modeled in the TD.

If we want to blur the semantics between writes and actions, writeProperty() could return Promise<InteractionOutput> instead of Promise<undefined>.

But then why don't we simplify things (following the logic of the question) and just support a generic interaction API, that can be a read, write or action, depending on a parameter or context and/or a name-resolving algorithm? (e.g. if name resolves to a single interaction, use that, otherwise if there are conflicts, an extra InteractionOption would tell what the interaction was meant to be. One can already pass data in an InteractionOption, so inputs are covered. Then, we'd need a way to do multiple interactions in a single request: that could be told the implementation by a start- and end-transaction function, or by a signature for multiple inputs/outputs like we do now).

Promise<InteractionOutput> interaction(DOMString name,  optional InteractionOptions options = null);

partial dictionary InteractionOptions {
    InteractionInput input;
    boolean observe;
    InteractionType interaction;
};

enum InteractionType { "property", "action", "event" };

But we have already discussed this idea many times in F2F meetings and after, so let's draw a line somewhere :).

[zolkis]

Even more simple: why don't we use a generic Request object, a Response object and the Fetch API and call it a day?
This has been suggested earlier many times. We could spare a lot of duplicated/WoTified algorithms and be more aligned with REST in the same time :).
But wait, that is already possible to do, and since Scripting API is optional in WoT, there are no conflicts :).