Consuming composited Thing Description

[JKRhb]

In the current version of the Thing Description Editor's Draft a composition feature for Thing Models has been introduced. Here, subordinate TMs are referred to in the links container using the link relation tm:subthing. If a composited Thing Model is converted into a Thing Description, these links and their associated subthings are converted as well, as displayed in this example.

How should a consumer deal with such a composited Thing Description? Should all linked Thing Description be retrieved and consumed as well if the "top level" TD is consumed? Or should the TDs of subthings be consumed in a separate step?

[danielpeintner]

This example deals with ThingModels which is currently not supported by the Scripting API (we should look into TMs soon).

When it comes to a TD, composed by several TMs, all TM links et cetera should be resolved... I think.

[danielpeintner]

relates to w3c/wot-thing-description#1354

[zolkis]

How should a consumer deal with such a composited Thing Description? Should all linked Thing Description be retrieved and consumed as well if the "top level" TD is consumed? Or should the TDs of subthings be consumed in a separate step?

@danielpeintner is right, currently in principle implementations should encapsulate this when consuming, but this behavior is not explicitly defined in Scripting spec algorithms.

Since this seems to be an artifact of defining TD's, I would not transfer the burden to follow all links to the applications.
This alone would make dealing with WoT as complex for apps as any other IoT protocol to start with.

In my view, consuming a TD (in Scripting) should mean fully consuming it, to produce a JS object that can deal with the Thing described, however complex is it.

[JKRhb]

From the last comments in w3c/wot-thing-description#1354 I got the impression that the consumption of subthings is entirely optional step. If a consumer is interested in a subthing, it can simply retrieve its TD and create a new ConsumedThing from it that is independent of the original Thing.

Would you say that this should be mentioned somewhere in the Scripting API specification? Or is it not relevant for the document?

[egekorkan]

I sort of have the feeling that this is some kind of discovery as well and can be handled by the part of the spec on this.

[zolkis]

It's not discovery, its fetching content/resources by following links, more akin to rendering a web page.
We are entering a DOM discussion here, leading to a similar, but even larger complexity boom. :)

[zolkis]

I got the impression that the consumption of subthings is entirely optional step. If a consumer is interested in a subthing, it can simply retrieve its TD and create a new ConsumedThing from it that is independent of the original Thing.

I would like to avoid opening that up to the developers. IMHO a Thing Description should be parsed and turned into an API object by the implementation. Any steps like following links for sub-things should be encapsulated by the implementations.
In the end, developers should have one object describing the Thing, not a DOM-like tree model.

[danielpeintner]

I see the links container as a way to communicate "external" links.
The TD labels it as follows:

Provides Web links to arbitrary resources that relate to the specified Thing Description.

In the same spirit a scripting API implementation (or document) should not do anything with it. IF someone is interested in this kind of information it can follow these links and do whatever is desired...

[zolkis]

IF someone is interested in this kind of information it can follow these links and do whatever is desired...

Please propose an API that can deal with generic iterative fetching and parsing of TD trees.

So far the Scripting API did not require scripts (developers) to parse TDs manually. The Scripting API is not a generic TD parsing tool, it's a special "parsing tool" that provides JS objects to enable the use cases included in its charter (consume, produce, discover). Partial consume is not included in that.
If we go into there, it will open a can of worms and will be too complex to be useful.

I see the following developer scenarios valid:

• Fetch and parse TDs directly with tools or libraries (no Scripting API needed).
• Use the Scripting API to produce JS objects that can interact with a Thing including its resources.

Implementations MAY decide to fetch links or not, but the latter might end up with an unusable ConsumedThing (which will downgrade the implementation). The Scripting API could expose a consume option for that choice, if that choice will be agreed to make sense.

In the case the app wants to deal with parsing TD forms, it can fetch the links separately even now. However, in the generic case a TD should be a full Thing Description to operate that thing, including all resources, and that is the default behavior I'd expect from implementations, and an opt-out from that policy should be carefully discussed.

[danielpeintner]

Please propose an API that can deal with generic iterative fetching and parsing of TD trees.

Let me try to rephrase. As mentioned before, the Scripting API does not need to do anything. It simply reports the TD which may contain links. Who parses it or who is even interested in it is out of scope. I see it as a hint, not more.

[relu91]

Good points, I think that the right way forward is in the middle. IMHO, when @mmccool's w3c/wot-discovery#269 will be merged we could re-use the concept of ThingLinks in the Scripting API in the Discovery section. In principle, in the PR is described that the introduction mechanism MAY return a set of TDs, which means that application developers MAY discover TDs using the direct method expressing their will to "follow links" (btw, this is another reason why we need a direct method instead of simply using fetch 🥳 ). I think we can cover this pretty easily, but I would continue the discussion at w3c/wot-discovery#269 or in general in https://github.com/w3c/wot-discovery.

[zolkis]

the introduction mechanism MAY return a set of TDs, which means that application developers MAY discover TDs using the direct method expressing their will to "follow links"

To me that looks like a mechanism implementations want to encapsulate. Is there a use case for a script to be involved with manually following links? We can already do that link following without a Scripting API. IMHO the WoT Scripting discovery can serve the TDs as they are fetched by the implementation in the way they determine to make most sense on the given platform (the script will not have access to the same platform information an implementation has).

[zolkis]

Let me try to rephrase. As mentioned before, the Scripting API does not need to do anything. It simply reports the TD which may contain links. Who parses it or who is even interested in it is out of scope. I see it as a hint, not more.

OK, I see, but I don't get the use case. Looks like something half baked, or it's me who doesn't get it.
Basically currently implementations can choose to retrieve the links, or not (the latter is being the case now IIUC). The TD spec should have clear instructions on this. If it's left open, then we don't need to expose it.
However, a guidance for implementations about this should be in place.

We cannot just say that scripts should browse for links and choose a form to fetch them, since then why do we have the consume API that does it for them? Either we do provide an abstraction, or we don't, but a mix is not a good option.

I would be fine considering an experimental feature of passing a user choice whether to retrieve links or not.
But in order to formulate an algorithm, we should know more about the use case behind this feature in the TD.

[zolkis]

The discovery use case above IMHO should be treated separately, even though that is also about following links.
IIUC, the use case there is that a script wants to get links before fetching TDs - but then there should be also other information about the link content, so that the script (or user) could decide which TDs are of interest.
IMHO that would be overengineering (for the Scripting API, not to the discovery protocol), given that it would be simpler to pass filters to discovery.
Then implementations can select the best/most efficient mechanism to satisfy the client's communicated needs.

I can see that the point in both cases are that a script is given a list of URLs to TDs to fetch.

• In the case of discovery, it would be relatively easy to encapsulate in the API, since whatever discovery provides (TDs or links), they need to be consumed. So there the change would be that consume() would accept both TDs and URLs pointing to TDs (that's a wasp nest, too, as we know).
• In the case of composite TDs, the complication is modeling the relationship between the links and the host TD. Do we have clear use cases on that?