Question/discussion: Object wrapper for Property payloads

[jtc42]

Following in from WebThingsIO/api#143

I think this is a discussion worth having here as it’s one of the major breaking discrepancies between the Mozilla implementation and what the W3C spec seems to suggest.

While keeping the Mozilla protocol would obviously be ideal, there are a number of cases where this object wrapper could prove difficult to work with (e.g. non-JSON data types), and a few reasons I think it’d worth removing from this new spec.

I should clarify here, I’m referring specifically to the wrapper on the response for specific properties. In this case, the property name is already in the URL, so the wrapper seems irrelevant. Additionally, for response such as image files, the wrapper cannot be included anyway, so for consistency I really feel like removing it makes sense.

In the WebSocket API, I think it should stay as in the Mozilla implementation. In that case, the wrapper is used to specify the property name, and effectively takes the role of the URL in the REST API.

In this case, the Thing Description provides information about the media type and optionally a schema in cases where JSON data is returned. The schema directly describes the data without clients needing to infer a wrapper object.

Hopefully this is something others can chime in on!

Thanks all.

[benfrancis]

I agree that property resources shouldn't have object wrappers in the Web Thing Protocol's HTTP sub-protocol, so that it matches the defaults in the W3C Thing Description. This will mean that even if a WoT client doesn't know about the Web Thing Protocol but it implements the W3C WoT Thing Description specification's defaults then it should still be able to get and set properties.

I should clarify here, I’m referring specifically to the wrapper on the response for specific properties. In this case, the property name is already in the URL, so the wrapper seems irrelevant.

Minor point, but there's no requirement that says you have to have the property in name in the property's URL (the specification doesn't enforce any particular URL structure). But it should be possible to differentiate between properties by their URL regardless.

Where things become a bit more complicated is with action queues (i.e. the Actions resource of the Web Thing API) and event logs (i.e. the Events resource of the Web Thing API). The W3C Thing Description currently has no way to describe an action queue or event log in the way they are used in the Mozilla's Web Thing API so that's something we'll need to figure out (and is also being discussed by the Thing Description task force. See w3c/wot-thing-description#899, w3c/wot-thing-description#302 and w3c/wot-thing-description#892).

I agree that it makes sense to keep the wrapper in the WebSocket sub-protocol which lacks the additional context of a resource URI given a single WebSocket is shared by multiple interaction affordances.

[jtc42]

I agree that property resources shouldn't have object wrappers in the Web Thing Protocol's HTTP sub-protocol, so that it matches the defaults in the W3C Thing Description. This will mean that even if a WoT client doesn't know about the Web Thing Protocol but it implements the W3C WoT Thing Description specification's defaults then it should still be able to get and set properties.

That's super reassuring to hear!

Minor point, but there's no requirement that says you have to have the property in name in the property's URL (the specification doesn't enforce any particular URL structure). But it should be possible to differentiate between properties by their URL regardless.

Yep, sorry my bad. I think if a client is working with a property schema though, it will be via the Thing Description, at which point it has URL/form information, so even if the URL itself has nothing to do with the property name, it should still be fine.

Where things become a bit more complicated is with action queues (i.e. the Actions resource of the Web Thing API) and event logs (i.e. the Events resource of the Web Thing API). The W3C Thing Description currently has no way to describe an action queue or event log in the way they are used in the Mozilla's Web Thing API so that's something we'll need to figure out (and is also being discussed by the Thing Description task force. See w3c/wot-thing-description#899, w3c/wot-thing-description#302 and w3c/wot-thing-description#892).

Yeah this is tricky, especially in cases where you might want actions to return other media types like images.

One other thing this might cause issue with is a generic all-properties resource. If properties of a Thing are mixed media types then it won't be possible to have a list of every property in a nice format. A hacky workaround would be base64 encoding non-JSON property values, but that seems really nasty as a solution, and doesn't work for non-static properties like video streams.

I agree that it makes sense to keep the wrapper in the WebSocket sub-protocol which lacks the additional context of a resource URI given a single WebSocket is shared by multiple interaction affordances.

Also reassuring to hear. Though, this does still present problems with non-JSON media types. I'm aware websockets can send binary data, but I don't know if you can dynamically switch between text/JSON and binary (e.g. request a property in JSON, and get a binary response from the same socket).

[benfrancis]

I believe this question has been answered, please re-open if further discussion is needed.