Move Table for ops to TD spec

[mmccool]

Propose cleaning up ops table and move to TD document.

• move ops table to TD spec (eg. PR to delete here, PR to add there)
• edit existing definitions to be consistent (e.g. Property vs. Property Affordance, etc)

See also w3c/wot-profile#92

If you object to moving, pls comment below...

[mmccool]

More generally ops etc. are related to a discussion about definitions of what actions, events, and properties are anyway (standard collections of resources? categories of resources? categories of static resources?) and what ops are (standard methods?) and recommendations for how to relate these to RESTful APIs etc. (e.g. the standard RESTful "List" method is supported via Links with particular "all" and "multiple" ops, "Get" and "Replace" are supported by reading and writing properties, "Create", "Update", "Delete", if supported, should be actions...). Some of this more general discussion probably belongs in architecture, but this issue is merely proposing that the detailed, specific table belongs in the TD spec because that is where people will be looking for definitions of these specific enumeration values.

[egekorkan]

Is there any blockers regarding creating a PR in the TD spec?

[egekorkan]

I am moving this to TD. This is core of the TD spec and arch is currently behind the TD spec. It also makes it difficult to test these in the TD spec since without a table we have no assertions for them

[mlagally]

@mmccool @egekorkan
Can you please clarify what exactly you would like to move, i.e. which table we are talking about?

The architecture introduces the concepts and baseline requirements and we should not just move content around without clear reasons.
If a specific section is outdated, let's create an issue and update it.

[egekorkan]

The change is at w3c/wot-thing-description#1257

I think this is a bit on the too technical side and TD lacks such a table. We should not have circular references, i.e. I start reading the Architecture document, I am linked to TD to understand the TD specification, then I am linked back to the Architecture to understand the meaning of the forms I will put in a TD. We can have them in the both places but they should be kept synced and it is difficult to assure this when a PR lands only at one spec.

[mlagally]

@egekorkan
I agree that we should avoid duplication where it makes sense or potentially causes divergence.

Note that we have a clear structure and split of concerns between the architecture and TD spec since we released the 1.0 version of the spec.

The architecture spec contains terminology, application domains, concepts, interaction model, deployment scenarios, introduction to building blocks, guidelines and security guidelines.
The thing description contains the data model and a JSON-LD serialisation.

We should avoid breaking this structure if we don't have to. As we agreed in today's editors call, the usual reader starts reading the architecture and dive deeper into corresponding building blocks / specifications. This may be the TD, discovery, scripting or binding templates.

It is obvious that there are some overlaps, specifically when it comes to these operations. These have been described in the architecture spec for the last 3 years and provide a good overview of the interaction semantics.

I completely agree that the section in the TD spec that describes operations requires significant additional work and a more detailed technical description. However I would think that the level of description has to be more detailed than just adding a simple table without describing concrete semantics of each operation, interaction flows and error behavior.

I would expect that the TD specification includes a subsection for each of these operations with these details.

[egekorkan]

@mlagally wrote:

Note that we have a clear structure and split of concerns between the architecture and TD spec since we released the 1.0 version of the spec.

It seems that this is actually not true. See #625, #619, #412, w3c/wot-discovery#190. My guess is that even the editors of other specs do not read the normative parts of the architecture document, resulting in collisions.

However I would think that the level of description has to be more detailed than just adding a simple table without describing concrete semantics of each operation, interaction flows and error behavior.
I would expect that the TD specification includes a subsection for each of these operations with these details.

This would be actually in the architecture document if such a table describing operations is also here. Explanation of such behavior has nothing to do with the TD document. Opening an issue here about this.

[mlagally]

arch call on 25.11.: definitions of operations are in the TD, the concepts should be explained and some replacement text should be proposed here. See also: #626

[egekorkan]

Not sure what I should do here