search

w3c / wot-scripting-api

Web of Things (WoT) Scripting API
http://w3c.github.io/wot-scripting-api/
Other
42 stars 28 forks source link

Consuming composited Thing Description #363

Open JKRhb opened 2 years ago

JKRhb commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

relates to https://github.com/w3c/wot-thing-description/issues/1354

zolkis commented 2 years ago

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 commented 2 years ago

From the last comments in https://github.com/w3c/wot-thing-description/issues/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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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:

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 commented 2 years ago

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 commented 2 years ago

Good points, I think that the right way forward is in the middle. IMHO, when @mmccool's https://github.com/w3c/wot-discovery/pull/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 https://github.com/w3c/wot-discovery/pull/269 or in general in https://github.com/w3c/wot-discovery.

zolkis commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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.

JKRhb commented 10 months ago

I think with the discussion above we could probably close this issue as completed or even "won't fix".

Alternatively, though, we could also add some informative text mentioning that you can follow links (in ThingLinks or TDs describing composited Things) and create, for instance, ConsumedThing for the referenced subthings, but this can be considered an optional addition.

zolkis commented 10 months ago

I think there are some valid points here, and the outcome is not "wontfix", more like "we don't have enough information to spec this".