[Editors] Document structure and content of all the WoT specs

[ashimura]

We have the following spec documents for WoT:

• Web of Things (WoT) Architecture 1.1
• Web of Things (WoT) Profile
• Web of Things (WoT) Thing Description 1.1
• Web of Things (WoT) Binding Templates
• Web of Things (WoT) Discovery
• Web of Things (WoT) Scripting API
• Web of Things (WoT) Security and Privacy Guidelines
• Web of Things (WoT): Use Cases and Requirements

We need to make sure (1) all those spec documents have enough description for each spec and also (2) there is no conflicts/duplication among them.

As the starting point, I'd suggest we start with the following two steps:

• Step 1: We look into the ToC of the Web of Things (WoT) Architecture 1.1 and the other specs to see if there is any overlap and/or missing description. (See Issue #997 for detail)
• Step 2: We look into the ToC of the Web of Things (WoT) Profile and the other specs to see if there is any overlap and/or missing description.

and then see the relationship among the other documents as the Step 3.

For example, the Web of Things (WoT) Architecture 1.1 document has Setion 9. WoT Building Blocks which includes description on all the building blocks and we should see what kind/level of description should stay there or rather should be moved to the other spec document.

The Web of Things (WoT) Profile document also has Section 5.2 Protocol Binding and we should see which part of the description should stay there or rather should be moved to the Web of Things (WoT) Binding Templates document.

Note that this issue is the central hub for this discussion and we should create dedicated smaller issue for each narrow actual problem.

[benfrancis]

The Web of Things (WoT) Profile document also has Section 5.2 Protocol Binding and we should see which part of the description should stay there or rather should be moved to the Web of Things (WoT) Binding Templates document.

I think it's important to distinguish here between:

1. A "protocol binding template" which provides the semantics for describing a particular protocol (e.g. htv:methodName, htv:headers, htv:fieldName, htv:fieldValue) in a Thing Description
2. A "protocol binding" which maps WoT operations (e.g. writeproperty) onto concrete messages in a particular protocol, e.g.

PUT /things/lamp/properties/on HTTP/1.1
Host: mythingserver.com
Content-Type: application/json
true

Currently there is duplication of the latter for HTTP in three places:

1. WoT Thing Description - 8.3.1 Protocol Binding based on HTTP
2. WoT Binding Templates - 2.2 HTTP Default Vocabulary Terms
3. WoT Profile - 5.2 Protocol Binding

Providing a protocol binding for HTTP is one of the core requirements of the WoT Profile specification so it should definitely stay there.

I think there's possibly an argument for keeping a simple set of defaults for HTTP for consumers that don't implement the full Core Profile, but if that exists it should either be in the Thing Description specification or the WoT Binding Templates specification, not both. Both sections could also be removed and superseded by the Core Profile.

Edit: I have filed https://github.com/w3c/wot-thing-description/issues/1259 and https://github.com/w3c/wot-binding-templates/issues/135

[benfrancis]

Something else I think should be fixed is moving the table of operation names from WoT Architecture to WoT Thing Description. I have filed https://github.com/w3c/wot-architecture/issues/623 for this.