Should it be possible to indicate whether writing a property returns set value?

[danielpeintner]

This issue relates to https://github.com/w3c/wot-scripting-api/issues/193.

In summary: in some use-cases it might be possible to return a value that has been set internally (e.g., writing a number 1.2345 rounds to 1.23 by limiting digits).

At the moment to be sure about the value that has been actually set one needs to read the property again after writing. Having said that, in some cases the application might be able to return the written value right away.

I wonder whether the TD could flag certain properties so that scripts could make use of it. (i.e. the "default" assumption could be false). Maybe as part of ExpectedResponse in TD?

[sebastiankb]

lets discuss this in more detail in tomorrow's TD call

[sebastiankb]

Theoretically, it is already kind of expected that a writable property will respond with data when writing, e.g., with PUT. This is explained indirectly in the specification here:

The optional response name-value pair can be used to provide metadata for the expected response message. With the core vocabulary, it only includes content type information, but TD Context Extensions could be applied. If no response name-value pair is provided, it MUST be assumed that the content type of the response is equal to the content type assigned to the Form instance.

For example, a WoT runtime would interpret a TD in the following way (for the case "op": "writeproperties").

{
    "properties": {
        "value": {
            "type": "number",
            "forms": [
         {
        "op": "writeproperties",
        "href": "https://example.com/value",
        "contentType": "application/json",
        "htv:methodName": "PUT",
        "response" : 
        {
          "contentType": "application/json"
        }
    },
  {
        "op": "readproperties",
        ...
]
}

What is missing is to be concrete what kind of data responded when writing (which should be the set value of the property). This kind of explanation can be provided then in TD 1.1.

What do you think?

[danielpeintner]

The current assumption of the scripting API is that writing a property does not return any value (this needs to be fixed. @zolkis do you agree?).

Having said that, the response field could be indeed used for indicating any response. What seems to be missing though is that the response could be of a different type, e.g.,

"response" : 
        {
          "contentType": "application/json",
          "type": "boolean"
        }

[sebastiankb]

Having said that, the response field could be indeed used for indicating any response. What seems to be missing though is that the response could be of a different type, e.g.,

If there is this kind of intention to respond with a different data model, why not define an action for it?

[zolkis]

I agree with @sebastiankb that a Property definition makes sense if the data can be described in the op Forms in a single consistent way, i.e. we can expect the same type result returned. Otherwise indeed an Action should be rather used.

And yes, I agree with @danielpeintner that we could add an optional return value in the Scripting API for the write operations. If any data is returned, it denotes the value actually written (as a read operation would return it) and it should be parsed according to the selected Form's contentType and the given DataSchema (if any).

[egekorkan]

I think this is one of the aspects where it is difficult to separate whether something is an action or a property write from the point of view of interaction semantics. I think this needs some guidance from our side when an implementer is going to write a TD for an existing implementation or develop a Thing from scratch.

why not define an action for it?

There are cases where the Consumer can read the brightness value of a lamp with a readproperty which returns an integer but once the Consumer does a writeproperty request the Thing responds with an object with something like "status":"success","newValue":123". A readproperty to the brightness then returns this newly set value, so it indeed looks like a writeproperty operation.

Another example: Philips HUE lights are annoyingly difficult to model with a TD (see TD). You can see that there is one property where the Consumer can actually see that it is possible to write to the name key of the property (changing the name of the light). However, since there are so many other keys to understand and that it returns a completely different payload than the property value, we had to define a rename action. It cannot be described in the property but it could be described with @danielpeintner 's comment above. So the question would be whether renaming a light is an action in the first place. Architecture spec says that changing configurations are done via property affordances (see here) so the answer would be that renaming a light is writing to a property. In this case, we cannot describe this renaming operation with a property in a TD with the current spec. All this would be solved if we define a subprotocol for Philips Hue.

P.S. I think that similar guidance is also needed to differentiate observing a property and listening to an event. For example, let's say I am getting a robot arm's position every 100ms with an event-based protocol. Only with this information, the general approach would be to model it as an event but if I can also read the same resource, should it be a property? (or the event decision was wrong in the first place?). From the semantics of the resource (a position), I think it should be described as a property even if we can only observe it, thus requiring an observeOnly option.

[takuki]

As @egekorkan mentioned in scripting api issue 193, HTTP PUT cannot contain a value in the payload. It can contain a payload when POST was used instead.

So, even when a TD instance indicate property A returns the set value upon writeproperty access, depending on how it is bound to protocol (e.g. PUT vs. POST), the writeproperty return can/cannot contain a set value.

We need to be aware of this when addressing the issue in TD spec.

[sebastiankb]

from today's TD call:

• WoT Profile decided not to echo the payload
• in general, there can be 3 variations: the write operation will response nothing (<- default), will response the identical payload (<- based on default schema), or will response with a different schema (<- needs additional schema)
• those 3 variations may be reflected when we introduce the schema term in ExpectedResponse, similar as done in AdditionalExpectedResponse
• we have to evaluate the complexity of such approach (e.g., human readability, API impact?)
• group decision: introducing schema in ExpectedResponse, decleare it as "at risk" and asking for implementation
• we should provide a good guideline how to use this new feature
• @relu91 will provide a PR

[egekorkan]

I have done small work on this at https://w3c.github.io/wot-thing-description/#sec-op-data-schema-mapping. You can use additionalResponses field

[sebastiankb]

from today's TD call:

• group decided to keep the definition as is, maybe there is an impact of existing implementations
• however, we should be more clear in the next version (TD 2.0)