Consider merging Profile protocol bindings into Protocol Binding and Payload Binding documents

[benfrancis]

It has been suggested that in the next charter period the term "protocol binding template" might be renamed to "protocol binding" throughout W3C WoT specifications. E.g. the "WoT HTTP Binding Template" would become the "WoT HTTP Protocol Binding".

There's a long discussion, the summary of which is that I disagree with this change on the basis that:

1. The current protocol binding template documents do not actually provide a "protocol binding" (i.e. a mapping of interaction affordances onto concrete messages of a given protocol), but just a vocabulary (and some basic defaults) for describing such a protocol binding in a Form of a Thing Description
2. WoT Profile actually does define an "HTTP protocol binding", so creating a different document called "HTTP Protocol Binding" would be confusing

There are several different suggestions in that thread for resolving this conflict, but one of them is to actually combine the concept of prescriptive protocol bindings from profiles with the concept of descriptive protocol bindings using protocol binding templates into a single type of document. The content of the protocol binding sections of profiles would be merged into "protocol binding" and "payload binding" documents as a set of defaults, which Things can then override using a semantic vocabulary. All Consumers implementing the protocol binding would implement those defaults.

This would allow a different approach to profiles where they just reference a particular protocol binding and payload binding document, instead of defining a protocol binding inside a profile. I've described this approach in detail here, but the basic idea is that a profile would prescribe a particular binding and require that conformant Things stick to its defaults rather than overriding them.

This approach could resolve the conflict between prescriptive vs. descriptive protocol bindings by combining them into a single concept, where the former is just a set of defaults for the latter. However, it will only work if the task force working on Binding Templates are happy with the idea of merging the prescriptive protocol bindings from profiles into the new protocol binding documents, as defaults.

Some of this would be quite straightforward, e.g.

• The HTTP Protocol Binding would have a default method and success response code for every operation type (e.g. GET and 200 for queryaction)
• The JSON Payload Binding would have a default payload format for every operation, (e.g. a payload format for writemultipleproperties which is currently a bit ambiguous in the Thing Description specification)

However, some areas might be more controversial, e.g.:

• The ActionStatus payload format for queryaction and queryallactions operations and the whole concept of dynamic resources in action queues
• Defining a default protocol binding and payload format for a readmultipleproperties operation is tricky
• The mapping of event and property observation payloads to Event Stream messages in SSE, where the event field is the name of the event/property, the data field is a JSON serialised payload and the id field is a datestamp
• The payload format for Webhooks

There might also be some tricky areas where the Protocol Binding and Payload Binding currently work together in a Profile, e.g. the JSON payload of a queryaction response contains a href member which is meant to contain an HTTP URL of an action status resource. This might have to be clarified in the profile itself.

What do you think? Is this a feasible way forward?

If you think this level of detail would be too prescriptive as defaults in a protocol binding document then I don't think "protocol binding template" should be renamed to "protocol binding", because they don't actually provide a protocol binding. We'd continue to have two different ways of providing protocol bindings, using profiles and protocol binding templates.

CC @egekorkan @relu91

[relu91]

Thank you for CCing me and for the detailed explanation of your ideas.

What do you think? Is this a feasible way forward?

There might be some technicalities that we might need to discuss but I would at least try to work towards a convergence of Profiles and Protocol Bindings Templates. If we can work in synergy on these two aspects I think the overall result will be an improvement of the whole Web of Things architecture and standards.

What I found odd, or maybe just interesting is that I don't find that much controversial the point you listed. Aren't they just additional constraints to be built on top of a new hypothetical HTTP Bidinding + JSON Binding? They look like Platform Bindings, not that much different from a Philips Hue binding.

Maybe what is useful here is to start with how we should update the current document template for Protocol Binding Templates and Payload Bindings Templates to be really useful for Profiles.

[benfrancis]

Thanks for your feedback @relu91.

What I found odd, or maybe just interesting is that I don't find that much controversial the point you listed. Aren't they just additional constraints to be built on top of a new hypothetical HTTP Bidinding + JSON Binding?

The potentially controversial part is that I'm suggesting all of those constraints would be part of the protocol binding document and payload binding documents as defaults, not "built on top of them" as part of the profile. The profile would just reference those documents and require that their defaults are used. Otherwise it's actually the "HTTP Profile" which is providing the "protocol binding", not the "HTTP Protocol Binding" document. Do you see the distinction?

Currently there are two ways of providing a protocol binding (by using a profile or a protocol binding template). If you want to call the "HTTP Protocol Binding Template" the "HTTP Protocol Binding" then in my view it has to fulfil both of those functions.

So for example:

• The HTTP Protocol Binding document would have to define that unless specified otherwise the HTTP response to an invokeaction operation should be expected to have either a 200 status code (for a synchronous action) or 201 status code with an action resource URL in a Location header (for an asynchronous action), and that that action resource URL could later be queried as part of a queryaction operation)
• The HTTP Protocol Binding document might also try to specify a default URL structure for readmultipleproperties operations (which is currently very hard to express unambiguously in a Thing Description and would therefore be hard to override in TD 1.1)
• The JSON Payload Binding document would have to define the ActionStatus payload format as the default payload format for an asynchronous queryaction operation (it would currently be impossible to override this in TD 1.1 because it can't describe dynamic resources, but hopefully that will be fixed in TD 2.0)
• The JSON Payload Binding document would have to define the payload format for writemultipleproperties and writeallproperties operations as being an object keyed by property name (this is currently only very loosely defined in the TD specification I'm not really sure how you would override it because there isn't really a mechanism for doing so in TD 1.1)

All Consumers which implement the binding documents would have to implement these defaults. Consumers which only need to support Things which conform to the HTTP+JSON Profile would only need to implement these defaults.

This goes quite a lot further than the current set of very basic defaults in the HTTP Protocol Binding Template document, but personally I think that's a good thing because it provides a greater level of interoperability by default. It also goes further than the JSON payload binding which is currently quite loosely defined in the Thing Description specification.

I think I understand what you mean about platform binding templates (to the extent that I understand what they're going to be), but in this case we wouldn't be binding to a platform, we'd be defining one. We'd essentially be prescribing a default sub-protocol for using the Web of Things with a given protocol/payload format, but with the flexibility to override those defaults using a vocabulary to describe any other platform which uses that protocol.

Sorry that's another long explanation, but I want to be clear about the extent of what I'm suggesting. Does it still sound OK to you?

Maybe what is useful here is to start with how we should update the current document template for Protocol Binding Templates and Payload Bindings Templates to be really useful for Profiles.

As an example, the way I imagine this might look in the HTTP Binding Document is that there would be a section which looks a lot like the current Protocol Binding section of the HTTP Basic Profile, where it takes each operation type in turn and explains the default flow for how that operation would be implemented using HTTP. Similar to the current Example Sequences section in the HTTP Binding Template document, but rather than providing informative examples it would define normative defaults. (There could then be additional examples of how to override those defaults using the defined vocabulary terms).

[benfrancis]

See w3c/wot-profile#285 (comment) for example document outlines of an HTTP Protocol Binding and JSON Payload Binding specifications if taking this approach.

[benfrancis]

I have created a WoT HTTP Protocol Binding 2.0 (and companion WoT HTTP Basic Profile 2.0 ) strawman proposal to explore the ideas discussed in this issue in more detail.

See my email on the WoT WG mailing list for more explanation.

Feedback is welcome here.