Review of 5.3.4.2.1 Mapping op Values to Data Schemas

[benfrancis]

@egekorkan Apologies for the late review on #1493 after landing, but some issues have recently come up that led me to review this useful new section.

Properties

Operation Type	Consumer to Thing DataSchema Correlation	Thing to Consumer DataSchema Correlation
observeproperty	No correlation.	All fields in the Property Affordance without "writeOnly":true.

Does the Thing to Consumer correlation here refer to a response to an observeproperty request, or to all the instances of property readings pushed from a Thing to a Consumer after it starts observing the property?

• If it's the former then I wouldn't have thought the observe response would contain the property value in most protocol bindings (e.g. see the HTTP SSE Profile). If it's the latter then I would expect the subscribeevent Thing to Consumer correlation below to use the data schema of an EventAffordance for consistency.

(Having a mixture of readOnly and writeOnly members of an object within the same property sounds complicated! It could be problematic for nested objects and arrays.)

Actions

Operation Type	Consumer to Thing DataSchema Correlation	Thing to Consumer DataSchema Correlation
invokeaction	Value of the input key.	Value of the output key.

Issue w3c/wot-profile#259 re-raised the question about whether the response to an action invocation request can be different to the action's output. One special case here I think may need clarification is that the output data schema should only be assumed to map onto the response of invokeaction when synchronous: true. An action with synchronous: false implies that the response will not contain the output of the action (if any), which may instead be retrieved as the response to a queryaction operation.

This then raises the question of what the "Thing to Consumer" data schema should be for the response to an asynchronous action. Could it be contained in additionalResponses as in other operations?

• If so, this row of the table could be changed to:

Operation Type	Consumer to Thing DataSchema Correlation	Thing to Consumer DataSchema Correlation
invokeaction	Value of the input key.	Value of the output key when synchronous: true, otherwise additionalResponses may be used at the form level.

Events

Operation Type	Consumer to Thing DataSchema Correlation	Thing to Consumer DataSchema Correlation
subscribeevent	Value of the subscription key with all fields without "readOnly":true	Value of the subscription key with all fields without "writeOnly":true

As above with observeproperty, does the Thing to Consumer correlation here refer to a response to a subscription request, or to the event payloads themselves?

• If it's the former then I wouldn't have thought it would usually include the subscription payload (e.g. see the HTTP SSE Profile and HTTP Webhook Profile). The readOnly/writeOnly distinction feels like a bit of hack to me, although I see that it's used in Example 71. Would it make more sense for the Thing to Consumer payload to use additionalResponses (since ExpectedResponse lacks a schema member)?

If it's the latter, then the Thing the Consumer correlation should surely use the data schema from the EventAffordance.

Operation Type	Consumer to Thing DataSchema Correlation	Thing to Consumer DataSchema Correlation
unsubscribeevent	Value of the subscription key with all fields without "readOnly":true	Value of the subscription key with all fields without "writeOnly":true

• Shouldn't this use the cancellation member rather than subscription?

I note that the data schemas of meta operations are still unclear.

Edit:

I note that the data schemas of meta operations are still unclear.

Following up on this since I see there's an Editor's Note about this but I can't find an issue tracking it.

• readallproperties - data schema defined in section 5.3.1.1 as a map of PropertyAffordance data schemas
• readmultipleproperties - data schema defined in section 5.3.1.1 as an array of property names
• writeallproperties - My interpretation of section 5.3.1.1 would be that this follows the same data schema as readallproperties, but this could be more explicit
• writemultipleproperties - Same as with writeallproperties but this is one is arguably even more ambiguous
• observeallproperties - Depending on the protocol binding it's possible that this operation doesn't require a data schema. The subscription itself might not contain a payload and the individual property readings may be sent separately and therefore just follow the data schema of the corresponding PropertyAffordance. But these are just assumptions on my part and none of this is made explicit.
• unobserveallproperties - Again, probably doesn't require a data schema but this is not made explicit.
• subscribeallevents - If a subscribevent operation has a subscription data schema, it's not clear what the payload of a subscribeallevents operation should be
• unsubscribeallevents - If an unsubscribe operation has a cancellation data schema, it's not clear what the payload of a unsubscribeallevents operation should be
• queryallactions - data schema currently undefined. This could be a map of queryaction responses keyed by the action name. However, given that the table says that data schema for queryaction comes from additionalResponses (of which there can be multiple), it may be ambiguous which data schema to use.

[egekorkan]

There are quite a bit to answer here :)

Does the Thing to Consumer correlation here refer to a response to an observeproperty request, or to all the instances of property readings pushed from a Thing to a Consumer after it starts observing the property?

The second one. I agree that we are not clear about this in this table but also in general in the spec. I can add this.

An action with synchronous: false implies that the response will not contain the output of the action (if any), which may instead be retrieved as the response to a queryaction operation.

I think that we have to find a proper solution to this. A valid point though. Regarding the change to table, it could also be that one does not provide synchronous true or false. I think that output corresponds to response if there is no queryaction in another form or if the action is not marked with synchronous:false (lack of the keyword or the value being true). This is getting complicated though....

[benfrancis]

There are quite a bit to answer here :)

Yes, sorry :) I actually think that despite the fact it's non-normative, this new table is one of the most important parts of the specification because it's basically a guide on how to write declarative protocol bindings. And my takeaway so far is that for non-trivial examples it's very complicated!

[egekorkan]

Indeed it gets messy. For TD 2.0, I have some ideas that are result of offline discussions.

It might be an idea to include a "new" keyword in the affordance level called operations that contains the available operations in the forms. This would mean removing writeOnly, readOnly, observable .

We would still have the issue about going further to say that in cases where the payloads different per operation, a new data schema construct needs to be used. Maybe introducing a map of operations to data schemas.