search

w3c / wot-thing-description

Web of Things (WoT) Thing Description
http://w3c.github.io/wot-thing-description/
Other
131 stars 63 forks source link

EventAffordance - unclear alignment of Data Schemas with response messages #817

Open hrennau opened 4 years ago

hrennau commented 4 years ago

EventAffordances have three name-value pairs providing Data Schemas:

The descriptions given in "5.3.1.5 EventAffordance" seem to make it clear that subscription and cancellation refer to the respective request messages:

However, Example 35 (A.3 Webhook Event Example) suggests a different use of subscription: the Data Schema describes an object with two properties, one marked as "writeOnly" and one marked as "readOnly", with the obvious intention to kill two birds with one stone - to provide a single object schema describing both, request and response message, using the adhoc rule that "Data Schema minus readOnly-properties" describes the request message and "Data Schema minus writeOnly-properties" describes the response message. There are several issues here.

ISSUE1: The use of readOnly and writeOnly name-value pairs for mapping a single Data Schema to two Data Schemas for request and response message has been mentioned (but not formally defined) in 5.3.2.1, referring to "Property interactions":

"Boolean value that is a hint to indicate whether a property interaction / value is read only (=true) or not (=false)."

If such use is conformant also in the context of EventAffordances, the specification has to describe it. I would expect a precise, formal definition - a mapping of the single Data Schema which has been explicitly specified to two Data Schemas derived and applicable to request and response message, respectively.

ISSUE2: The use of readOnly and writeOnly for mapping an explicitly specified Data Schema to two Data Schemas applicable to request and response message cannot be used as a general approach for defining distinct Data Schemas for request and response. In particular, it cannot be used when the types of the Data Schemas describing request and response are different - think of the case where the request uses an object, the response a string.

CONCLUSION: The use of writeOnly and readOnly cannot be the only way of specifying different Data Schemas for request and response. Therefore I propose to extend EventAffordance, adding two name value pairs, similar to SubscriptionResponse and CancellationResponse.

PS: I think that Data Schemas are a key aspect of Thing Descriptions - ambiguous or unspecified semantics, as well as arbitrary limitations of their expressiveness must be strictly avoided.

egekorkan commented 4 years ago

Interesting observation and I agree with this unclear situation over eventing, we need more work on this part. A dirty fix for your second issue would be to use oneOf. You can have in the subscription the following schema:

"subscription":{
  "oneOf": [
    { "type": "number", "readOnly": true },
    { "type": "string", "writeOnly": true }
  ]
}

I am not sure if it really is a fix but it looks somewhat OK to me.

hrennau commented 4 years ago

It is not sufficient to provide a Data Schema capable of validating both, request and response. I think the main function of the Data Schema is not validation, but description, guiding the construction of outgoing messages and the processing of incoming messages. So the spec would be obliged to define a generic mapping of "hybrid" Data Schemas to distinct Data Schemas for request and response, as without such a mapping the task of description would not be performed. It feels like a dark wood to me.

sebastiankb commented 4 years ago

@hrennau thank you for your comment. I agree with you that example 35 is quite tricky because the request and response pattern is reflected within the data schema. In particular, this example follows a similar approach that can be also found in OpenAPI specifictation:

readOnly boolean Relevant only for Schema "properties" definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as readOnly being true and is in the required list, the required will take effect on the response only. A property MUST NOT be marked as both readOnly and writeOnly being true. Default value is false.
writeOnly boolean Relevant only for Schema "properties" definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as writeOnly being true and is in the required list, the required will take effect on the request only. A property MUST NOT be marked as both readOnly and writeOnly being true. Default value is false.

Please note that this TD version will only provide a basic framework that is able to include different kind of event approaches. This hint is also given in the spec:

Event affordances have been defined in a flexible manner, in order to adopt existing (e.g., WebSub [websub]) or customer-oriented event mechanisms (e.g., Webhooks). For this reason, subscription and cancellation can be defined according to the desired mechanism.

The protocol binding document will offer more details about some concrete event mechanisms in one of the next updates.