Bindings: Confusing use of the term "protocol binding"

[benfrancis]

I'm filing this issue to capture unresolved feedback about the use of the term "protocol binding" in the names of work items in the 2023 charter, which risks causing continued confusion.

Please see my comments in w3c/wot#1065 for a detailed discussion.

The term "protocol binding" is being conflated with the term "protocol binding template" and used in a way which is inconsistent with the definition of the term "protocol binding" in WoT Architecture.

Is a "protocol binding" a vocabulary (including defaults) for use in Forms, or an instance of a Form in a Thing Description which may use such a vocabulary? It can not be both.

The reason this subtle point is important is that there are two ways of providing a protocol binding in a Thing Description instance:

1. By using protocol binding templates to provide a custom protocol binding for each interaction affordance of each Thing
2. By using a profile to re-use a common protocol binding shared between multiple interaction affordances and Things

Calling the "HTTP Protocol Binding Template" work item the "HTTP Protocol Binding" risks causing confusion with the protocol bindings provided in the WoT Profile specification such as the HTTP Basic Profile Protocol Binding.

I have suggested potential alternative terms for binding templates in w3c/wot#1065 (comment) (e.g. "protocol vocabulary").

Alternatively if the term "protocol binding template" really is going to be renamed to "protocol binding", then we will need a new term to describe instances of protocol bindings serialised as forms (e.g. "protocol binding instance"), and the shared protocol bindings provided by profiles (e.g. "sub-protocol") - but that opens up a whole other can of worms.

[egekorkan]

Before finding a term, I would like to identify the different "concepts" we have:

1. The core binding template document that serves as the place to put the requirements for the individual protocol binding documents.
2. Protocol and payload binding documents that explain the vocabulary, default terms, and associated behavior.
3. Profile documents that explain how a protocol must be used for that profile, together with other requirements. This is referred to as a Protocol Binding in the profile document
4. A TD instance that has forms and other terms that binds that Thing's operations to a protocol usage
5. A TM instance that possibly has forms and others terms but they are not complete. E.g. there is an HTTP form but there is a placeholder for the IP address.

I think that 3 and 5 are doing the same thing, i.e. restricting the usage of a protocol. 1 is more of a document to reference to, more fitting for the word template. 2 is descriptive, 3 and 5 are prescriptive. 4 is instance specific. With these in mind, I propose the following:

1. WoT Binding Templates: Explains how a binding document needs to be written.
2. WoT X Protocol/Payload Binding: Binding documents that explain the vocabulary, default terms, and associated behavior. Maybe we can add another word after this, like WoT X Protocol/Payload Binding Description. I find it a bit convoluting though.
3. Protocol Binding Restrictions: How a protocol usage is called in a profile.
4. Protocol Binding Instance: How a protocol usage appears in a TD. This includes terms that are defined in concept 2 or restrictions from concept 3.
5. Protocol Binding Restrictions: How a protocol usage is restricted by a TM. This should be simply explained as a concept but it is not something "tangible" like the others.

@benfrancis I would like to nail this discussion asap since it appears in the charter. Can you join a charter discussion, TD/Binding meeting? Otherwise, we can arrange a separate call for this.

[benfrancis]

@egekorkan Thank you for responding, and for your proposal.

I have the following concerns with your proposal:

1. It changes the definition of the terms "protocol binding" and "protocol binding template" to mean something different than in the existing W3C Recommendations
2. A "Protocol Binding" document in your proposal (e.g. "WoT HTTP Protocol Binding") does not actually bind interaction affordances to concrete messages of a given protocol (apart from a few basic defaults), it just provides a vocabulary for describing such a binding
3. The protocol binding sections currently present in WoT Profile do not just define "restrictions" on how a protocol binding template (as it's currently called) can be used, but instead provide an alternative to using a protocol binding template by prescribing how interaction affordances should be bound to messages in a given protocol, including behaviour which can not currently be described using a protocol binding template

If you don't like the alternative terminology I proposed in w3c/wot#1065 (comment) then I would instead suggest we stick to the existing definitions of the terms "protocol binding" and "protocol binding template", used as follows:

• WoT Binding Templates - a top level specification which describes how to define a binding template, plus the registries of the following three types of binding templates:
  • Protocol Binding Template (e.g. "HTTP Protocol Binding Template")
  • Payload Binding Template (e.g. "XML Payload Binding Template")
  • Platform Binding Template (e.g. "ECHONET Platform Binding Template")
• Protocol Binding - A binding of an interaction affordance to concrete messages in a given protocol which can be provided in the following ways:
  • By using a Protocol Binding Template in a Thing Description (or Thing Model) - in order to provide a custom protocol binding for each interaction affordance. You do this by using a vocabulary defined in a Protocol Binding Template document in a Form, e.g. "htv:method": "GET".
  • By using a Profile in a Thing Description (or Thing Model) - in order to re-use a common protocol binding shared between multiple interaction affordances and multiple Things. You do this by referencing a profile ID (URI) in the profile member of the TD, which then applies to all matching Forms in the TD.

Protocol Binding Templates and Profiles provide two alternative and complementary mechanisms for defining a protocol binding of a Thing. One is descriptive (best suited to brownfield applications where one system is being integrated with another) and the other is prescriptive (better suited to greenfield applications which can benefit from universal plug-and-play interoperability).

---

Wildcard Option

There's currently redundancy between the WoT Thing Description, WoT Profile and WoT Binding Templates specifications in that all three specifications define a set of overlapping "defaults" for communicating with Web Things using HTTP (e.g. GET to read a property, PUT to write a property, POST to invoke an action), with varying levels of detail.

An extreme option could be to combine all three of these into a single "HTTP Protocol Binding", which includes all of the details from the HTTP Basic Profile protocol binding as defaults. That is to say that if a Thing Description includes HTTP endpoints then a Consumer should assume that it conforms to those defaults, unless it overrides the defaults using the defined vocabulary. All Consumers would support those defaults.

That way, the HTTP Protocol Binding document would provide a detailed mapping of interaction affordances onto concrete messages of a given protocol, but those mappings could be overridden using the provided vocabulary (e.g. to change a PUT to a POST using "htv:method": "POST").

A Profile could then constrain Things by saying that they MUST conform to the defaults in the HTTP Protocol Binding and not override them, then it wouldn't need to define a protocol binding at all.

There could similarly be an SSE Protocol Binding which provides default mappings for observing properties and subscribing to events using Server-Sent Events, and a Webhook Protocol Binding which provides the same defaults for Webhooks.

---

@benfrancis I would like to nail this discussion asap since it appears in the charter. Can you join a charter discussion, TD/Binding meeting? Otherwise, we can arrange a separate call for this.

I'm sorry I couldn't spare another 6 hours to discuss the charter again this week. If you add this issue to the agenda of a specific meeting and can guarantee that it will be discussed, then I will try to join.

[egekorkan]

Some comments for @benfrancis :

• "I'm sorry I couldn't spare another 6 hours to discuss the charter again this week. If you add this issue to the agenda of a specific meeting and can guarantee that it will be discussed, then I will try to join." -> It is difficult to say that about the charter calls due to having so many topics to discuss but I can arrange it for a topic of the binding calls and invite you there.
• The overlap between TD and HTTP Binding (Template) is just temporary. Also see (Mention that HTTP Binding is specified at the TD spec and it is just mirrored here (for now) wot-binding-templates#247). There should be no discrepancy.
• "An extreme option could be to combine all three of these into a single "HTTP Protocol Binding", which includes all of the details from the HTTP Basic Profile protocol binding as defaults." Even though you say extreme, I think this might be a good way forward. I would swap the order though since protocol bindings will be somewhat normative and the current binding at profile mentions JSON, thus mixing two things.
• The whole argument against calling the subspecifications templates (e.g. HTTP Binding Template) is that it makes the document itself sound as a template and gives expectations that there will be another document called HTTP Binding. I have heard of easily 5 people who find it confusing.
• I think your distinction about "descriptive" and "prescriptive" are good, so I think that it might be a good idea to include them in the names, i.e. "Descriptive HTTP Binding" and "Prescriptive HTTP Binding". After writing this, I am not very happy with the names either since a newcomer will not immediately understand.
• There has been a resolution in the TD/Binding Call. Please see https://www.w3.org/2023/02/15-wot-td-minutes.html

[benfrancis]

It is difficult to say that about the charter calls due to having so many topics to discuss but I can arrange it for a topic of the binding calls and invite you there.

👍

Even though you say extreme, I think this might be a good way forward.

Interesting.

I would swap the order though since protocol bindings will be somewhat normative and the current binding at profile mentions JSON, thus mixing two things.

What do you mean by "swap the order"?

I agree that the prescription of particular JSON payloads in profiles complicates things.

The Thing Description specification already specifies that the default contentType of a Form is application/json. The profile could separately assert that conformant Things MUST stick that default as well.

However, Profiles currently go further than that, e.g. by defining the ActionStatus payload format, and being more explicit about the payload formats of meta interactions like writemultipleproperties and queryallactions. I'm not sure where such additional assertions would fit (maybe the TD specification or JSON binding document), but they are essential for full plug-and-play interoperability.

Similarly, the HTTP SSE Profile defines how to map data schemas onto event and property observation payloads and there's the ongoing debate about the payload format for WebHooks.

The whole argument against calling the subspecifications templates (e.g. HTTP Binding Template) is that it makes the document itself sound as a template and gives expectations that there will be another document called HTTP Binding. I have heard of easily 5 people who find it confusing.

Conversely, the problem with calling the sub-specifications "protocol bindings" is that it makes the document sound as though it provides a protocol binding on its own, which it currently doesn't. This has been a source of confusion for many years now and was one of my main motivations for working on profiles, in order to provide that crucial missing piece.

Merging the protocol binding work from profiles into binding documents would fulfil that need and resolve the ambiguity, but has significant ramifications.

I think your distinction about "descriptive" and "prescriptive" are good, so I think that it might be a good idea to include them in the names, i.e. "Descriptive HTTP Binding" and "Prescriptive HTTP Binding". After writing this, I am not very happy with the names either since a newcomer will not immediately understand.

This is another argument for merging the two.

There has been a resolution in the TD/Binding Call. Please see https://www.w3.org/2023/02/15-wot-td-minutes.html

Sounds good.

The resolution in today's call doesn't explicitly say that the binding documents will be normative. My assumption is that the WoT Binding Templates document will be a W3C REC containing registries which link to W3C Notes. Whether or not those Notes are normative or non-normative is another matter.

---

What's the next step?

If we were to go with the wildcard option of merging the protocol binding from the HTTP Basic Profile into the HTTP Protocol Binding Template document as defaults and renaming it to "HTTP Protcocol Binding" (then doing the same for an SSE Protocol Binding and Webhook Protocol Binding), what does that mean for WoT Profile 1.0? We either have to take the current approach in WoT Profile 1.0 (continuing to use the term protocol binding inside profiles as an alternative to protocol binding templates), or otherwise delay WoT Profile by two years or more until TD 2.0 and Binding Templates 2.0 are published.

[benfrancis]

See also...

• Consider merging Profile protocol bindings into Protocol Binding and Payload Binding documents wot-binding-templates#248
• Profile Mechanism 2.0 wot-profile#285 (comment)

...for discussion on how Bindings and Profiles could fit together.

[benfrancis]

tl;dr: If the current detailed prescriptive protocol bindings from WoT Profile are merged into binding documents as defaults (which profiles can then reference) then I'm OK with calling those documents "protocol bindings", otherwise I think they need to keep a different name like "protocol binding template" or "protocol vocabulary".

[mmccool]

going to label this as both details and charter since I'm not sure the issue appears in the charter draft.

[benfrancis]

To confirm, the current charter draft does also use this terminology:

specify additional protocol and payload bindings

[egekorkan]

Just to cross link, we will solve one part of the problem at #62 (comment) with a dedicated PR. However, the TD+Binding+Profile TFs need to work together on agreeing how a reader needs to be guided for an implementation.

[egekorkan]

@benfrancis , we got assigned to this but it is mainly to indicate that the discussion is between you and me. I think our decision is that we do not have a conclusion but the charter (not the details) do not constrain us in a specific way. In the next charter, we should dedicate initial work to clarifying all the terminology.

[benfrancis]

@egekorkan OK, but I hope we can involve more people in that discussion and not just discuss it amongst ourselves.

I think the current wording of the charter still implies (though doesn't explicitly say) that "additional protocol and payload bindings" will be defined in "binding documents", which are a separate thing to "profiles". That doesn't reflect the current reality where protocol bindings are actually defined in instances of forms in Thing Descriptions using binding templates or are defined in profiles.

I'm hopeful that we can find a better way for profiles and binding documents to work together so that (default) "protocol bindings" really are defined in binding documents and profiles just reference them, but if that proves not to be possible then I hope that we can adjust the terminology of the actual specifications to make it clearer that binding documents do not in fact define protocol bindings but vocabularies for defining custom protocol bindings in a TD.

As you say, these details can be figured out during the planning phase of the next charter period. However, given the change that is implied by the different terminology used in the new charter compared with the old charter (which talked about "vocabularies" and "templates" and "how to use that vocabulary in a protocol binding") I would feel more comfortable if we had input from more people (e.g. @mlagally @mmccool @sebastiankb @mjkoster) on the proposal for how bindings and profiles could work together in 2.0.

[benfrancis]

Please see #92 and #93 for two proposed solutions to resolving this conflict.

[mmccool]

It seems this issue only impacts the detailed work items, not the charter (will double check), so removing the charter label. Well, it is mentioned in the charter. Some cleanup is needed... suggest in general using the general term "binding".

[mmccool]

See PR #103 , which I hope resolves this issue for the charter.

[benfrancis]

See PR #103 , which I hope resolves this issue for the charter.

FWIW the issue is with using "binding" vs. "binding template", not "protocol binding" vs. "binding" so this kind of misses the point, but I appreciate the effort to use more general language in order to give us more wiggle room on the exact definition of those terms.