Retrieving information from ThingDescription (or internal metadata)

[danielpeintner]

The current scripting API w.r.t the ConsumedThing interface does not provide any mean to retrieve a list of available properties, action, events.

Moreover, even when "knowing" the interaction (i.e. property name) there is no possibility to get metadata such as semantic information (e.g., @type, valueType, ...).

Is it in the scope of the Scripting API to provide such information in a fine-grained manner. An alternative would be to provide a mean to report the TD itself (which would mean the TD needs to be parsed&processed again).

Any thoughts?

[zolkis]

I don't understand the concern. In my interpretation, the ConsumedThing interface provides the following:

• name, URL
• a TD of the Thing
• retrieve/update properties
• invoke actions
• add, remove events.

Did you mean to say that properties should be explicitly represented as enumerable object properties, actions as local functions, events as local events? That would mean to define a "representation" object instead of a proxy object as currently is done?

In such case we need to specify the algorithms for the bindings, how to generate/define properties, etc, based on TD.

The current approach is simpler, more like a REST API, but the representation objects would be easier to use.

[danielpeintner]

Let me try to re-phrase my comment.

What I meant was that there are case where it may be handy to have some kind of iterator to walk over the available interactions of a ConsumedThing. Supposing there is such an iterator it would be possible to provide additional information such as semantic @types et cetera along with it.

Currently the TD needs to be retrieved and parsed separately. The consequence is the same. But maybe you are right. Having such an iterator may cause additional issues (such as what happens when the TD gets updated) and is less REST-like.

[draggett]

I support that in my web of things server by exposing the object obtained by calling JSON.parse() on the JSON thing description. The application can then walk the interaction model and associated metadata. In a demo, I use this to display the interaction model within a web page where the web page script interacts with a thing. Note that this approach works nicely for the plain JSON serialisation, but would be more cumbersome for app developers if the object model is that of the JSON-LD serialisation.

[zolkis]

@draggett, should we standardize that?, i.e. should we change the type of ConsumedThing::description to Object from Dictionary and specify that it should mirror the remote Thing with the events, functions (actions) and properties with the right access rights (enumerable=true, configurable=false, writable=false)?

Then we could invoke an action in two ways,
consumedThing.description.open("entrance-door", ...)
and
consumedThing.invokeAction("open", "entrance-door", ...)?

Now the app would need to enumerate functions on an object in the first case to find about the "open" action, vs parse a TD.

I'd say parsing the TD provides more information, so I would stick with the current approach.

There could be a library that parses TDs... in that case, ConsumedThing::description should be an opaque USVString rather than a Dictionary?

[draggett]

Whilst OCF, oneM2M and ECHNET have defined standard interaction models for a selection of home appliances, these three organisations have done so differently. Moreover, when you look at the home appliances on sale today, it soon becomes clear that there is little likelihood of them conforming to such standards. Instead, we need to make it easier for apps to deal with variations that vendors use to differentiate their products. This is in fact essential if we are to move beyond the limitations of services that are provided by each vendor for their own products.

I would therefore argue that we do need a standard interface for apps to access the interaction model and associated metadata, including links to the associated semantic models. This is needed for smart applications to adapt to variations across devices from different vendors or for different models of device from the same vendor.

This is also related to communications metadata, and enabling apps to adapt to the current context, and to select between alternative levels of service when that is feasible. This can be implemented in terms of accessing and updating metadata.

[draggett]

A related point is that the generic scripting API will be perceived as cumbersome compared to a simpler approach that makes use of getters and setters. For languages like JavaScript these can be set up dynamically from the thing description. For static programming language like Java, however, you need to compile the thing descriptions which requires prior knowledge of the things you want to use in your application.

[zolkis]

Off-topic, but could't reflection be used in Java?

However, I still incline towards the current API if we were to define a Scripting API. This we can standardize, but the object API would just be a bindings - which is also a valid approach and would be better aligned with some members' views I know.

[draggett]

Using the current API you could indeed use some form reflection with Java, but given the need to compile your Java application code, there is little advantage over using Java classes automatically generated from the thing description.

I can envisage the case where you write your app generically, so that it can adapt to differences in the interaction models for different models of device, or devices from different manufacturers. This is likely to involve APIs for for accessing and reasoning over the semantic models for the devices so that the app can tell what interaction is needed for a given capability. In this situation, you wouldn't need to recompile your app, and reflection would be important.

[zolkis]

What I can make so far from the discussion is that

• we keep the Scripting API as it is now, i.e. for a consumed Thing the API provides a TD in some form (string, or dictionary, or <suggestions-welcome>)
• we discuss functionality for TD introspection; should that be (a) part of the Scripting API, (b) a separate library (not standardized in WoT).

I tend to incline to (b), or at least defer adding the functionality until a later version of the API.

To mention the other viewpoint, we could also apply this logic to the whole Scripting API, i.e. it could be indeed done in a separate library and not standardized in WoT, but instead become part of bindings. Then (for consuming Things) there could be a library that generates API objects based on the TD, or a library that implements a generic meta-API like the current Scripting API. For exposing (and discovering/introspecting) Things, we need a directory/repository API.

Since this is a pivotal point, brought up by @benfrancis, and addressed by @mkovatsc at the Duesseldorf F2F, could we record here a summary of the relevant group decisions about whether

1. do we standardize a Scripting (meta-)API and why (instead of each WoT solution provisioning a library in the client runtime);
2. do we include introspection/reflection in this API, or defer it to a separate (library) functionality;
3. do we standardize explicit directory/repository interactions (API), or do we assume that a Thing can fulfill the role of directory/repository and hence this becomes a WoT application (and not standardized in the group)?
   @mkovatsc , @benfrancis

[zolkis]

This has been fixed.