Where to place the HTTP Default Binding and which format

[egekorkan]

In the Binding part of the TD call of 10.11.2021, there was a small discussion on where to put the HTTP default binding. It was based on the w3c/wot-binding-templates#135 . There are some things to discuss in general:

• Where should this information be? In the call, @danielpeintner mentioned that the reason to put them in the TD spec in the first place was to show how protocol-specific information is conveyed and that HTTP was the most tested one so far.
• How should this information be formatted? In the Binding Templates, all protocol bindings have the same way of specifying the default values, i.e. for a given WoT operation, what is its default protocol method/options. In the TD spec, the default values for htv:methodName are put in a table and their values depend on the value of the op. These two ways are shown in the screenshots below, first one is the TD spec, second is the binding templates HTTP. They contain the same information but in different ways:

We should choose one and stick with it. I personally like the second approach, i.e. the one in the binding templates since it is easier to read and reason.

[relu91]

Where should this information be? In the call, @danielpeintner mentioned that the reason to put them in the TD spec in the first place was to show how protocol-specific information is conveyed and that HTTP was the most tested one so far.

Although I acknowledge the fact that leaving it inside the TD spec has the advantage to be normative, I would prefer to move as much information as possible to its Protocol Binding document. The advantage is to have one single place to maintain and point people to read. IMHO Thing Description specification should leave any protocol-specific information to Protocol Binding documents or Profile documents.

[benfrancis]

Note that this topic was originally raised in w3c/wot#996, which led me to file w3c/wot-binding-templates#135 and #1259 to consider which specification it should be removed from.

In terms of format, I prefer the table from the Protocol Binding Template specification which is organised by operation type. This is how we structure the protocol binding in the WoT Profile specification too.

@relu91 wrote:

IMHO Thing Description specification should leave any protocol-specific information to Protocol Binding documents or Profile documents.

As I said in w3c/wot#996 (comment), I think it's important to distinguish between a "protocol binding template" and a "protocol binding". The documents you are referring to are not "Protocol Binding" documents, they are "Protocol Binding Template" documents, which is slightly different.

My understanding is that a protocol binding template just provides the semantics for describing a particular protocol, and an actual protocol binding (which may use that vocabulary) is either provided:

• By forms in an instance of a Thing Description (a declarative protocol binding)
• By a protocol binding in a Profile specification (a concrete protocol binding)

The set of default HTTP verbs defined for different operations in the Thing Description specification (which are also separately defined in the non-normative Protocol Binding Templates specification but probably shouldn't be) is a very lightweight kind of concrete protocol binding which is really just a set of default values to help make Thing Descriptions less verbose, and was a bit of a stop-gap before we had the Core Profile. It doesn't include defaults for all operations and misses many details, so it's not really a complete protocol binding.

The concrete HTTP protocol binding in the WoT Profile specification builds on that set of defaults, but goes into much more detail by defining HTTP headers, payload formats, response codes etc.

Now that we have a Core Profile which defines a more comprehensive HTTP protocol binding, I think there are two questions:

1. Do we still need the set of default HTTP verbs?
2. If so, where should it live?

I would be open to removing the defaults altogether, but I'm inclined to think that they're still useful for Thing Descriptions which don't conform to the Core Profile but still use the default verbs for basic operations.

As to where they should live, I agree it's neat to put them as defaults alongside the vocabulary defined in the Protocol Binding Template, but as @relu91 mentioned this is a non-normative specification. That would mean that Consumers may implement the Thing Description specification, but not the HTTP Protocol Binding Template specification and would therefore not know to apply these defaults. The developer of a Thing Description may assume that a Consumer would apply those defaults, so omit those details. This could result in a Consumer being unable to use interaction affordances which don't include HTTP verbs explicitly.

Therefore I think they probably need to stay in the Thing Description specification, unless we decide they're not really needed any more in which case they should just be removed from both specifications.

[sebastiankb]

from today's TD call:

• coming from the PR update Section 8.3 #1301
• there was a discussion about what should be normative in TD regarding protocol binding topics. This needs to be clarified.

[JKRhb]

I suppose this is not really use-case-related but rather an "organizational" question, right?