Add a proposal for manageable affordances and data mapping #2162
Conversation
|
Interesting. However, adding variables as a top level member of Thing Descriptions makes me nervous about the potential for ballooning complexity. First you add variables, then you add if statements, then you add loops, and before you know it you've turned Thing Descriptions into a turing complete programming language! Before we go down this road I have a counter-proposal to consider, using semantic annotations for manageable actions and data mapping. |
thanks @TailTed ! Co-authored-by: Ted Thibodeau Jr <[email protected]>
|
Thank you @benfrancis, for commenting. There is definitely some room for improvement, but I would not opt out of introducing a variable mechanism just for fear of turning the Thing Description declarative model into a Turing-complete language. There are plenty of examples of declarative languages that introduce variables without becoming a monstrosity. The closest to us are OpenAPI and AsyncAPI. Then, they can solve most use cases for payload mapping, where we need the flexibility to adapt to different protocols or platform formats. Moreover, they are quite widespread and well-understood concepts that would help onboarding people without explaining TD-specific mechanisms. I would spend some time experimenting with them and exploring their potential. One final thing that I didn't mention in the proposal (because it is out of scope) is that they can solve the problem of how to describe the mapping between action inputs/outputs and URI variables. |
|
@relu91 wrote:
That is a fair point, and we do already have However, I do think it's quite a big jump from including template-style placeholders in what is otherwise static metadata describing the physical affordances of Things, to describing complex data structures and internal state of a "stateful runtime context" in Consumers. I also think describing re-useable patterns as Thing Models is a clever idea and I acknowledge that people have asked for ways to express relationships between affordances, but I worry about how difficult it will become to implement a general purpose WoT Consumer which is capable of bringing all these concepts together. I agree this could benefit from more experimentation, and in particular the feasibility of implementing a Consumer that can actually function without any out-of-band information about the Thing. |
egekorkan
left a comment
egekorkan
left a comment
There was a problem hiding this comment.
Thank you @relu91 for the proposal. I think it is a good idea to combine the two concepts when thinking of the solution. However, I think it will complicate the discussion at the same time since we need to fullfil both requirements at the same time. There is a bit too much to digest.
I have left my general comments as reviews for the whole file. In general, they may sound negative but I want to avoid adding this level of complexity and still not solving the issues we have. Thus, a better linking to the problems we have is needed
There was a problem hiding this comment.
the file name has a typo manegiable should be manageable
There was a problem hiding this comment.
https://github.com/w3c/wot-thing-description/blob/main/planning/work-items/analysis/analysis-manageable-affordances.md does not contain any requirements and are not extended here. Also, the analysis content should be copied here (see https://github.com/w3c/wot-thing-description/tree/main/proposals/common-definitions).
| - Define a simple yet powerful mechanism to cover most of the analyzed user stories and **implementations**. | ||
|
|
||
| --- | ||
|
|
| { | ||
| "href": "http://example.com/jobs", | ||
| "htv:methodName": "POST", | ||
| "http:headers": { |
There was a problem hiding this comment.
This is wrong usage of the http vocabulary. See https://w3c.github.io/wot-binding-templates/bindings/protocols/http/#binding-http-usage-1
I like this one more, but currently it is not how it should be modeled.
| ```json | ||
| { | ||
| "priority": 5 | ||
| } | ||
| ``` |
|
|
||
| - **State (set of Variables):** Define runtime client data structure shared by all affordances listed in it (e.g., `activeJobQueue`). | ||
| - **Subaffordances:** Group related Actions, Properties, and Events that operate within the same context. | ||
| - **Model**: Without needing to define all the affordances from scratch every time, we can define a set of common Thing Models (e.g., AsyncActionThingModel). |
There was a problem hiding this comment.
While it is good to use what we already have (TMs), we are starting to load too much into what a TM can be. It is already used in two rather different ways:
- A model for how I model e.g., temperature sensors in my platform.
- A model for how a device looks like before instantiation (like partial TD)
Now we would add another concept into the same word and people would be more lost about what to do with a TM they get.
There was a problem hiding this comment.
Also, the schemaDefinitions we currently have is not used. That can be the first place to start.
There was a problem hiding this comment.
I think I'm right in saying that currently a Consumer is never expected to fetch a Thing Model when it is referenced in a Thing Description, when a Thing Model is linked from a Thing Description it just indicates that the Thing Description is an instance of that model - the Thing Description still has to contain the full content of the Thing Model plus any instance-specific metadata. I think that's a good thing since it simplifies Consumer implementation.
This would would therefore be quite a big change because a Consumer now has to follow links in a Thing Description and fetch other resources in order to construct a complete Thing Description.
|
|
||
| #### Limitations & Future Work | ||
|
|
||
| - Naming and Terminology: The term "Capability" may conflict with existing IoT frameworks. Future work may explore alternative names like "Cluster" or "Module" or "Group" "RuntimeContext". |
There was a problem hiding this comment.
It already conflicts with our terminology where we use capability together with affordance. Searching for "capabilit" in https://www.w3.org/TR/wot-architecture11 results in this. Not very happy with the current state but probably it is in people's minds already.
There was a problem hiding this comment.
The proposal should explain how it addresses the concrete use cases in the analysis document. Currently, the examples in this document are still theoritical.
| } | ||
| ``` | ||
|
|
||
| In the example above, the `jobType` property in the Action input schema is marked as a Variable. When the client invokes the `startJob` action, it will bind the value of `jobType` to the `X-Job-Type` HTTP header in the request and the real payload sent to the the server will not contain the `jobType` field. |
There was a problem hiding this comment.
I think the weird uriVariables concept in the BACnet binding can be fixed with this in a beautiful way: https://w3c.github.io/wot-binding-templates/bindings/protocols/bacnet/#vocabulary-uri-variables
That would ground the discussion on a concrete solution.
|
|
||
| If we want to support mapping low-level message parts, we can first map the low-level payload to our TD data model with a new keyword (e.g., `messageSchema`), and then use Variables to bind the runtime data to the low-level message parts. | ||
|
|
||
| Example: |
There was a problem hiding this comment.
I would use the examples from ECHONET or WebThing here.
4 participants
Description of Changes
This proposal connects two previously separate work items (Manageable Affordances and Data Mapping) to provide a unified solution for modeling complex, stateful interactions and granular protocol binding in the WoT Thing Description (TD). I drafted some ideas that I collected during these months. Definitely open to discussion and a work in progress.
Related Issue
TDB: There are many I'll about later
Closes #
Type of Change