Produce ExposedThing from a ThingModel instance

[relu91]

Now that a new paragraph about Thing Model is landed in the TD specification (w3c/wot-thing-description#1024) we should evaluate possible choices about how to integrate it in the Scripting API.

As I see it, a good starting point for integrating Thing Models is in the workflow for producing ExposedThings. We could exploit the work done with ExposedThingInit and define a transformation algorithm between a TM instance and the ExposedThingInit object. We could even change the produce method signature such as it can handle ThingModel or ExposedThingInit instances as arguments.

Another option is to use the algorithm described in the mentioned PR. But as I raised during the call it is a bit vague when looking at it from an implementer's point of view. The TD group would like to keep it as it is since they would like to have a process that could be used also by tools or even humans rather than an automatic process computed by a runtime.

Opinions?

[zolkis]

We'd define ThingModel as object as well...

I think we should still separate the notion of "init object" as a JS concept from what it can map (externally defined notions/objects) in the algorithms.
After that PR, the init object for produce() can be a ThingModel or a ThingDescription (coming from another ConsumedThing), or any JS object that passes validation (as defined in the algorithm), regardless how was it put together.

[relu91]

After that PR, the init object for produce() can be a ThingModel or a ThingDescription (coming from another ConsumedThing), or any JS object that passes validation (as defined in the algorithm), regardless how was it put together.

The point is that we need some processing steps for ThingModel because it can have placeholders like the following:

{
   title:"{{YOURTITLE}}"
}

Without mentioning the fact that it might need to be merged with other bases TMs. So we can't use it as it is. On the other hand, you're right about TDs since they are also valid PartialTD (or ExposedThingInit).

[zolkis]

Just to be exact, I make a difference between ExposedThingInit (a JS object that is undergoing the validation algorithm defined in the Scripting API spec) and any terms defined in the TD TF, including Partial TD, TD, Thing Model etc.

The normative steps are in the produce() and expose() steps, and in the sub-algorithms they use, like validation.

It is out of scope for Scripting how does someone merge Thing Models, how the TD or Partial TD was generated etc.

It is in scope for Scripting to handle the use cases that are legal for non-Scripting use cases, i.e. network-interface for WoT (which used to be called WoT Interface or WoT Network Interface, though today it might have different name).

Since exposing Things is not standardized at WoT Interface level, the Scripting API defines its behavior. Therefore there is no external requirement on what and how to accept. Which is why it makes sense to me to syntactically separate the init object from terms defined outside of Scripting, and semantically map them in the algorithms.

[relu91]

Just to be exact, I make a difference between ExposedThingInit (a JS object that is undergoing the validation algorithm defined in the Scripting API spec) and any terms defined in the TD TF, including Partial TD, TD, Thing Model etc.

The normative steps are in the produce() and expose() steps, and in the sub-algorithms they use, like validation.

Yes, I think we are on the same page. Still, as you mentioned here:

We'd define ThingModel as object as well...

We have to add a new JS object that represents a ThingModel instance and refer to an algorithm to transform it to an ExposedThingInit. As said also in w3c/wot-thing-description#1047 it would be ideal to have this algorithm defined in TD doc and we just use it. I think there're strong use cases to have TMs as first citizens in a Script runtime.

[zolkis]

The way I think about it is that produce() accepts an object (which we call ExposedThingInit in Web IDL) that is undergoing validation. This is the function signature, that we accept an object. All the rest are external notions to Scripting and are just creating confusion IMHO. But at validation level we can decide what source to check: ThingModel? Thing Description? Partial TD? ConsumedThing?

In other words, I would not bother to represent all the possible sources or mappings (Thing Model, Thing Description, Partial TD, ConsumedThing) on Web IDL signature level. It just complicates things, since Web IDL is an intermediate representation that we don't even use for generating any code, we just use Web IDL as prose in the spec, to illustrate the API in a standard way.

On validation (algorithm) level, we can just make clauses to handle specific TD stanza (title, etc), which may have various sources (Thing Model, etc).

[relu91]

This is a duck typing approach. Accept everything and then validate which is the standard way to build JS based applications. However, I feel like with WebIDL we could convey more hints to the implementers. We should still validate the input object but at least everything it's clear from the method signature. Which downside do you foresee if we'll define a ThingModel object?

In other words, I would not bother to represent all the possible sources or mappings (Thing Model, Thing Description, Partial TD, ConsumedThing) on Web IDL signature level. It just complicates things, since Web IDL is an intermediate representation that we don't even use for generating any code, we just use Web IDL as prose in the spec, to illustrate the API in a standard way.

While the idea of having a separation of concern is good, I would expect that the architectural concepts are reported as runtime objects in the API. Much like when designing a DSL you have the domain-specific terms in the language itself.
Maybe it's me because I really like type systems 🤣

[danielpeintner]

Q: I wonder whether we actually need (should?) go along that path. According to my understanding I would rather start from TD only. There might be implementations offering ThingModel to TD conversion but do we really need to cover that in Scripting API?

Comments welcome!

FYI: implementation-wise there seems to be already support, see https://www.npmjs.com/package/json-placeholder-replacer

[zolkis]

While the idea of having a separation of concern is good, I would expect that the architectural concepts are reported as runtime objects in the API.

If we can define a Web IDL interface for ThingModel, ThingDescription (, ConsumedThing), then we can OR the types.

If all of these are defined as generic objects, then I would use the idiomatic xxxTypeInit dictionaries that all Web specs are using and map to the source types in the algorithms. That is also more future-proof :).

[relu91]

Q: I wonder whether we actually need (should?) go along that path. According to my understanding I would rather start from TD only. There might be implementations offering ThingModel to TD conversion but do we really need to cover that in Scripting API?

I think this is the same answer of "Why do we need an ExposeThingInit?". The thing is that a TD describes a fully running WebThing instance and it cannot be used* to instruct a runtime to produce a WebThing. It is way more practical to use ExposeThingInit. What would be more useful is that ExposeThingInit objects could be shared and extended in other projects to create a nice structure of dependencies. This feature is exactly what a ThingModel provides. Instead of defining our own rules for extending ExposeThingInit instances, we can leverage the concept of ThingModel and enjoy its features (like placeholders, and a standard serialization/sharing format). That's why I opened this issue. I hope it answers your question!

* side note: you could use a TD but all the forms and security definitions should comply with the current runtime implementation which in the end means that you should know at dev time the capabilities of your deployment system (not really common)

If we can define a Web IDL interface for ThingModel, ThingDescription (, ConsumedThing), then we can OR the types.

Yep, that's what I'd do.

[zolkis]

Yep, that's what I'd do.

I think that should be a spec of its own. Not sure it should be hosted by the TD TF, or by the Scripting TF, but it should be a proper web spec, with Web IDL, algorithms, all the regular sections etc. I see that an ideal solution, but until we have that, IMHO we should stick with the ExposedThingInit dictionary and express the ThingModel knowledge in the algorithms (instead in syntax which is missing if we don't have a rigorously defined interface for a ThingModel).

This topic should be discussed in the F2F.

[danielpeintner]

Note: I think we need to be aware that ThingModel adds a lot more complexity. A TD (or ExposedThingInit) is a single self-contained file.

A TD based on ThingModels can be build upon several TMs

• one for example covering the "light" part, the other the "switch" part
• one extending constructs of the other (causing linking/reference TM issues)
• ... combinations ...

see https://w3c.github.io/wot-thing-description/#thing-model

[zolkis]

A TD based on ThingModels can be build upon several TMs.

True. IMHO how to assemble TM fragments into an ExposedThingInit should be out of scope for the Scripting API (produce()).
It should be handled by a separate tool (or separate API), since it will have to solve separate problems.
IMHO the produce() function should accept only one init object (a single TM, TD or ConsumedThing).
How to arrive to that init object is the responsibility of another tool, or API.
One more reason why we should keep the separation of concerns and go with ExposedThingInit for produce().

[relu91]

I agree that linking and extending may be easily supported by some build tool but notice that ThingModels have placeholders. I foresee that a really common use case for those placeholders is to fill them at runtime not statically by some tool. We don't have placeholders in ExposedThingInit. If we are leaving out ThingModels from the API, I think that we should at least provide support for placeholders.

[zolkis]

ExposedThingInit is an object. It may contain whatever the runtime can interpret, but we'd better specify its content.

The use case in Scripting is that the produce() API accepts one document (Thing Description) based upon which a runtime can construct an exposed Thing with its interactions (hooks to be provided via the ExposedThing API).

How we arrive to the TD provided to produce() is out of scope for produce().
I hope we don't need to specify a JSON editor.