Does Scripting need a dataType attribute for Property, Action, and Event

[danielpeintner]

The TD description provides along with the interaction name (for property, action, and event) also a fieldName for the according input or output datatype (see Property, Action, Event).

The current scripting API does not have such an attribute.

• Do we need one?
• Does it conflict with JS/TS type?

I think having these information is useful and needed. Let's suppose to have a TD that is created based on the following type for RGB

"inputData": {
    "type": "array",
    "items": {
        "type" : "integer",
        "minimum": 0,
        "maximum": 255
    },
    "minItems" : 3,
    "maxItems" : 3
}

Based on this information additional consistency checks can be applied and would refuse arrays of 4 items or with wrong ranges such as.

[-1, 22, 34, 800]

Hence ThingPropertyInit besides name and other attributes should also have outputData attribute. Similarly inits for actions and events....

[zolkis]

Yes - I am thinking how could we simplify this and how much should we push to the scripts to handle. Some comments.

1. The name outputData might be fine in a TD but is not very good in a scripting API :).

2. TD spec is using a data schema to describe data. How would that map to WebIDL, JS and TS?

3. Actually we need to create an issue against the current action init: it is not very helpful for an implementation to receive a serialized string description of input and output data. It needs to be broken down to a dictionary or interface. Alternatively, we need to specify how to generate data validators from a TD; this is also connected to how to represent/introspect/parse a TD. Again, TD parsing/generation/representation issue.

4. This is related to the arguments in Simplified API for JavaScript and other programming languages #64 of representing Things as objects (in the given language), meaning the implementation should map the TD type definitions to the language type definitions and generate data validators based on the descriptions.

I prefer to have input from a full stack implementation experience based on a stable TD in order to decide which design is best and which use cases will be supported in scripting.

[mkovatsc]

I would say this is even a bug in the FPWD, as we had this before and it is quite essential to define the data type of a Property, as its value/state must be handled by the runtime.

I edited the following after seeing ThingActionInit

In ThingActionInit, we indeed have ThingDescription inputDataDescription;, meaning we pass a subtree of the TD as object to the addAction() function -- just like before with the valueType object.

Thus, I assume that ThingDescription description; in ThingPropertyInit intended to be the field @danielpeintner is mentioning, maybe better called just dataDescription instead of description.

I hope with this everyone can implement this aspect of the FPWD for the PlugFest. Note that in the TD-TF, this part is being changed to the JSON Schema Ontology version anyway, which is different from the example above.

[zolkis]

@mkovatsc
Please see my comment 2 for types (languages have different types than the ones mentioned here) and comment 3: a subtree of a TD is not very helpful. Why to mix code and TD in Thing representations? The bug is in this design.

[zolkis]

BTW ThingPropertyInit already supports semantic types on the property. What other types do we still need there, based on what universal type system?

[mkovatsc]

The "semantic types" are for adding vocabulary items to the @type field in the TD.

Our problem is that JavaScript does not provide a declarative mechanism for variables. We could pass some kind of prototype with sample values, but how to pass restrictions like minimum and maximum?

At the moment, the idea is to use the TD definitions and pass them to the WoT Runtime to instantiate the right type and being able to do validation and reject before bothering the script with invalid inputData.

[zolkis]

Our problem is that JavaScript does not provide a declarative mechanism for variables.

Right, but it does provide procedural one.

Besides, we also heed to other languages in the API design, so it is safer to bet on procedural methods.

At the moment, the idea is to use the TD definitions and pass them to the WoT Runtime to instantiate the right type and being able to do validation and reject before bothering the script with invalid inputData.

No, the purpose of the ExposedThing interface is to programmatically define a Thing and a TD. If it is for just assembling a TD from fragments, then please use a string manipulation library and let's forget the scripting API.

[mkovatsc]

What I am saying is that for now we do not have a better solution than passing the TD definition, because JavaScript does not have a declarative way to specify a prototype. What we need are sufficient descriptors that can be passed in the Thing*Init objects. defineProperty() comes with insufficient descriptors.

JSON Schema is again only close, since it has the vocabulary, but is JSON and not a JS object that we can pass.

[zolkis]

But then let's carry that idea to the end and use TD to define a Thing object entirely, instead of specifying some parts with TD fragments and other parts with functions of the API...

[mkovatsc]

Okay, two options:

• Interactions are initialized through a TD subtree and a handler where needed
• Find a declarative approach similar to defineProperty() descriptors that represents a programmatic alternative to TD

I like the second option more. Is using JSON Schema as JS obejcts a possibility? In the TD, we use a Linked Data version ("JSON Schema Ontology") of JSON Schema that can generate normal JSON Schema.

[zolkis]

I am fine with defineProperty() or addProperty() - eventually with the addition to be able to specify a handler per property, even though they are not declarative.

Declarative would be the first approach, e.g.:

typedef USVString ThingDescription;
Promise<ExposedThing> create(ThingDescription description);

Of course the name create can be changed, but this just creates a JS object with bindings, based on description. All the logic, including protocol bindings are encapsulated by the implementation. Then a developer just writes the TD and calls create() on it. The reason to have a Scripting API is for specifying the handlers as app provided functions.

However, if the TD would support including or linking the code for those handlers in the TD (analogously how web pages include scripts), then we would not even need any scripting API. This would resemble the current web model most.

It would also simplify the deployment model, as we'll only talk about fetching/consuming a TD... and we could leverage a lot of work from the Web Platform. Just my 2 cents.

[zolkis]

The other way is to specify a fully procedural API, i.e. everything initialized with standardized items, instead of TD fragments. Whatever is specified in the TD, is translated to dictionaries etc in the Scripting API.

[mkovatsc]

Your Web page analogy misses the aspect of server-side code, which is the problem we are discussing for ExposedThings. Scripts in TDs would only be code-on-demand that is shipped to the WoT Client.

[zolkis]

No, it doesn't miss. If the TD of a server contains [handler] code or links to code that can be fetched, then a WoT runtime can instantiate an ExposedThing just based on the model (TD).

Scripts in TDs would only be code-on-demand that is shipped to the WoT Client.

I'm not sure I understand that. Could you explain more or give an example?

[mkovatsc]

Code enclosed or linked from HTML documents is code that is shipped to the client and executed there (REST "code-on-demand"). Server code stays on the server and most want to hide it -- just provide a RESTful interface, the server implementation is no client's business (also REST "layered system").

The TD is definitely analogous to HTML: it contains metadata, some of which can be information similar to HTML content, and links and forms that describe how to formulate requests for the application. Putting server-side code in the TD breaks the HTML analogy; we end up with something like PHP or JSP -- could be a nice concept to follow!

At the moment I see a lot of half-baked concepts put together, which confuses us and definitely people on the outside and future users. If I find the time, I can try to separate the different approach we are currently using.

[zolkis]

The gain in permitting scripts in a TD would be:

• would simplify the ExposedThing API a lot
• would allow the same algorithm ("door") for fetching a TD and scripts, no need for separate script management services etc. However, this would be a new security attack vector for TD.

We have shortly discussed the subject on today's TD call and there were no obvious heavy counter-arguments; we agreed to discuss this topic at TPAC.

[zolkis]

Putting server-side code in the TD breaks the HTML analogy

It's just a different target. The analogy is in extending a declarative markup with scripts, not in the deployment pattern. So I would not call it a break. You're right that scripts would be part of TD's meant for server Things and client Things will not have scripts/links.

Earlier we've been discussing the possibility of including manifest-like information with TDs. Similarly, scripts could be included as well, linked from the TD.

It is true this would only help ExposedThing interface, which IMHO has less priority than the client interface. One could always encapsulate an exposed Thing's implementation and just serve the WoT interface. Later on we might open up and standardize how to build exposed Things, how to make protocol bindings etc, but first we need to get ConsumedThing right.

[zolkis]

Fixed by #86 and followed up by #94.