"Protocol Binding" vs. "Binding Template"

[benfrancis]

I've noticed that the current draft of the WoT Binding Templates specification uses the terms "protocol binding" and "binding template" fairly interchangeably. In actual fact they are two distinctive concepts, with one making use of the other.

From the WoT Binding Templates specification

Binding Templates enable a Thing Description to be adapted to a specific protocol, data payload formats or platforms that combine both in specific ways. This is done through additional descriptive vocabularies, Thing Models and examples that aim to guide the implementors of Things and Consumers alike. This document acts as the base and explains how other binding templates should be designed. Concrete binding templates are then provided in their respective documents that are linked to from this document.

From the WoT Thing Description specification:

A Protocol Binding is the mapping from an Interaction Affordance to concrete messages of a specific protocol... Protocol Bindings of Interaction Affordances are serialized as forms

My understanding is that basically a binding template provides a vocabulary for describing a protocol binding with a given protocol, and a protocol binding is an instance of that template for an individual thing.

With the creation of the WoT Profile specification there are now two types of protocol binding:

1. Declarative - Serialised as forms in a Thing Description instance, using vocabulary from a binding template (e.g. the HTTP Binding Template)
2. Concrete - Referenced from a standardised protocol binding provided by a profile specification (e.g. the Core Profile), denoted by the profile member of a Thing Description

This makes some of the WoT Binding Templates specification a bit confusing to read. For example the title of section 4.1.1 is "Creating a new Protocol Binding" whereas it should probably be called "Creating a new Binding Template".

I suggest reviewing the wording in the Binding Templates specification to make sure the distinction between a "protocol binding" and a "binding template" is clear.

[egekorkan]

I think I am partly to blame for the confusion in general since I made it apparent that there are these two terms. The way the new structure is aiming to handle this is:

• The reason behind the word template is not known to me. My guess is that these binding specifications are recommendations on how to use certain protocols/platforms. What you are saying at

My understanding is that basically a binding template provides a vocabulary for describing a protocol binding with a given protocol, and a protocol binding is an instance of that template for an individual thing.

is also almost correct. A protocol binding template explains how a protocol should/can be described in the TD. A platform binding template explains how a platform should/can be described in a TD.

I will do a pass over it remove unclear parts and use consistent wording.

[benfrancis]

@egekorkan wrote:

The reason behind the word template is not known to me

I have always been confused by this term too, and by the precise relationship between a protocol binding template and a protocol binding. The language recently added to the WoT Thing Description specification about a form being a serialisation of a protocol binding made this much clearer to me.

However, the new concepts of "profiles" and "thing models" have complicated things further, since both of those concepts are arguably more like "templates" than "binding templates" are. This is also true of the term "blueprint", which the WoT Architecture specification uses to define a binding template.

The Core Profile also defines a protocol binding, without using a "binding template"[1].

A protocol binding template explains how a protocol should/can be described in the TD. A platform binding template explains how a platform should/can be described in a TD.

OK, that makes sense thank you.

Is there an opportunity to pick a better names for binding templates in the future?

1. A "protocol binding template" is more like a "protocol binding vocabulary", providing a semantic vocabulary which can be used to describe protocol bindings in TD forms.
2. A "payload binding template" is more like a "representation format mapping", denoted by a content type in TD forms.
3. A "platform binding template" sounds like implementation guidance which specifies which protocol binding vocabulary and representation format to use for a specific platform, and provides best practices through Thing Models and example Thing Descriptions.

The three are quite different to each other, and by my understanding only the third one is really like a "template". Even then I'm guessing the actual template part would be provided by Thing Models (it's hard to tell for sure since there are currently no examples).

In the short term I think clearly distinguishing between "protocol binding template" and "protocol binding" would help a lot. In the longer term perhaps different terms could be considered. As new concepts are added to the WoT architecture it's getting harder and harder to explain how they all fit together, in part because the names given to the different components don't clearly describe what they do.

---

1. I have a PR with an illustrative example of what the Core Profile protocol binding might look like if the Thing Description used the HTTP Binding Template instead of relying on the profile.

[egekorkan]

Call of 20.04:

• These definitions are now in the architecture specification at https://w3c.github.io/wot-architecture/#terminology
• We should change the title of https://w3c.github.io/wot-binding-templates/#creating-a-new-protocol-binding to include the word template. After that, we can close this issue
• In short, templates are descriptive and bindings are prescriptive

[egekorkan]

@benfrancis what do you think?

[benfrancis]

• These definitions are now in the architecture specification at https://w3c.github.io/wot-architecture/#terminology

The definitions in WoT Architecture do help, but there is still no mention in either WoT Architecture or WoT Thing Description that protocol bindings can also be provided by profiles, without the use of Binding Templates.

• We should change the title of https://w3c.github.io/wot-binding-templates/#creating-a-new-protocol-binding to include the word template. After that, we can close this issue

Changing the title of section 4.1.1 would help, but there are 15 other instances of the term "protocol binding" in the WoT Binding Templates specification which also need reviewing to check whether they need changing to "binding template".

• In short, templates are descriptive and bindings are prescriptive

Makes sense.

[egekorkan]

I will reopen this to allow @ektrah to comment

[egekorkan]

@mkovatsc @ektrah had commented that actually, it makes more sense to call the protocol and payload binding template documents as just binding (removing template) and using the word template only in the core document, which actually refers to documents like https://github.com/w3c/wot-binding-templates/blob/main/bindings/index.template.html

@ashimura and @chachamimm has similar opinions.

Templating mechanism should be explained, i.e. the usage of the actual template documents

@egekorkan To align the usage back to protocol bindings and not protocol binding templates (except in the core document).

[benfrancis]

I don't understand.

From the TD spec:

A Protocol Binding is the mapping from an Interaction Affordance to concrete messages of a specific protocol such as HTTP [RFC7231], CoAP [RFC7252], or MQTT [MQTT]. Protocol Bindings of Interaction Affordances are serialized as forms as defined in 6.3.9 forms.

The protocol binding is the form in the Thing Description which binds an interaction affordance to a concrete protocol request or message. For example, this is a protocol binding:

            {
                "op": "invokeaction",
                "href": "https://mylamp.example.com/toggle",
                "htv:methodName": "POST"
            }

The protocol binding template documents, e.g. the WoT HTTP Binding Template, define vocabularies for describing those protocol bindings for a given protocol, e.g. the HTTP vocabulary:

That document is not a protocol binding, it provides a vocabulary for defining a protocol binding in a Thing Description.

(Really a better name for protocol binding templates would be protocol binding vocabularies.)

[egekorkan]

@benfrancis so your arguments had convinced me in the beginning that we are providing templates but in the call, the consensus was that the word template is actually more confusing. For example, the CoAP Binding (Template) shows how we should bind wot operations to CoAP. I think that both opinions make sense. Regarding changing to name to vocabularies, given that we have default mappings and recommendations/assertions on how to use the vocabularies, that would not be enough in my opinion.

@benfrancis is the current document aligned with what you are proposing?

[benfrancis]

the CoAP Binding (Template) shows how we should bind wot operations to CoAP

I had a quick scan of that document and it looks to me like it just provides a vocabulary and a set of defaults like the HTTP Binding Template does. Anything more prescriptive than that will probably not be capable of describing a wide range of brownfield devices, which as I understand it is the intended use case of protocol binding templates. The actual protocol binding is provided by a form in a Thing Description. E.g.

           {
                "op": "readproperty",
                "href": "coaps://rs.example.com/status",
                "contentType": "application/cbor",
                "cov:methodName": "GET"
            }

in the call, the consensus was that the word template is actually more confusing

I agree that the word "template" is confusing, because both thing models and profiles are more like templates than "protocol binding templates" are. However, calling them protocol bindings is definitely more confusing because "protocol bindings" are defined as something else in the WoT Architecture and WoT Thing Description specifications, which both say that protocol bindings are expressed as forms in Thing Descriptions (they don't explain that protocol bindings can also be provided by profiles, but that's a separate issue.).

A protocol binding is a kind of instantiation of a protocol binding template as a form. Calling both the vocabulary and the form which uses the vocabulary a "protocol binding" is going to get very confusing (using "protocol binding" and "binding template" interchangeably has already been the source of a lot of confusion). Having a different "HTTP protocol binding" defined separately in the TD specification, Protocol Binding Templates specification and Profile specification would be even more confusing.

Regarding changing to name to vocabularies, given that we have default mappings and recommendations/assertions on how to use the vocabularies, that would not be enough in my opinion.

Having "vocabulary" specifications provide recommendations on how to use the vocabulary makes perfect sense to me. Where protocol binding defaults should be defined is another open question (do the defaults defined in the HTTP protocol binding template specification still apply if you don't explicitly use the htv: vocabulary anywhere in your protocol binding for example?), but in principle I don't see a problem with those being in the vocabulary specification as well.

@benfrancis is the current document aligned with what you are proposing?

I'm sorry I haven't had time to do a detailed review of your latest PR which changed the wording. I seem to recall that I had issues with some details, but the gist of it was OK.

In summary: "protocol binding vocabulary" is better than "protocol binding template" which is better than "protocol binding".

Renaming "protocol binding templates" to "protocol bindings" at this stage is going to cause even more confusion in my opinion.

Note the current definitions from WoT Architecture:

Protocol Binding The mapping from an Interaction Affordance to concrete messages of a specific protocol, thereby informing Consumers how to activate the Interaction Affordance. W3C WoT serializes Protocol Bindings as hypermedia controls.

Binding Templates A re-usable collection of blueprints that enable a Thing Description to be used with a specific protocol, data payload format or an IoT platform that combine both of them in specific ways. This is done through additional descriptive vocabularies, Thing Models and examples that aim to guide the implementers of Things and Consumers alike.

To me the distinction is clear:

• A protocol binding template provides a vocabulary for describing protocol bindings
• A protocol binding is expressed as a form in a Thing Description, using the vocabulary from a protocol binding template
• (Profiles offer an alternative to using protocol binding templates by defining a common protocol binding in an external specification which is referenced from a Thing Description using its profile member)

[mkovatsc]

From the TD spec

You mean the WoT Thing Description Template?

[benfrancis]

You mean the WoT Thing Description Template?

https://w3c.github.io/wot-thing-description/#protocol-bindings