What we want from the Scripting API when based on Simplified TD

[mkovatsc]

The Thing Description (TD) uses a formal, and hence well-defined model that describes Things. Among other details, Things can have metadata attributes such as name and id, semantic metadata attributes such as @context and @type (obviously using JSON-LD keywords), interaction definitions in the structured attributes properties, actions, and events, and finally links to other Things or metadata documents in the structured attribute links.

This formal model and instances of the descriptions are the basis to instantiate software objects in a JavaScript runtime that act as object API to interact with the corresponding Thing. Since not all Things are the same, the object API needs to provide introspection, to check the values of the metadata attributes and which interactions are available. It would be most intuitive, when the software object has the same structure as the TD model. Most of this can easily be defined in WebIDL, as we have a list of identifiers.

Problem 1: the semantic attribute identifiers contain an @ character, and hence are no valid identifiers for JavaScript. The solution should be to access them with the bracket notation, e.g., myThing["@type"] to introspect the semantic attribute @type. To my understanding, this would be done using a readonly maplike<key_type, value_type>; definition for the WebIDL interface. Others say "named getter" would do the trick. Please clarify. What we lose is the definition of which semantic attributes are to be expected (e.g., @context and @type). However, semantic attributes were made purely optional based on community feedback, so maplike should be fine, no?

Furthermore, the Thing Description must be extensible to be able to evolve other time and to adapt to the many different IoT ecosystems. For this, we allow domain-specific vocabularies, which can easily be imported in the TD document through the JSON-LD @context keyword. This would add additional semantic attributes that usually would be of the form prefix:term or could be a full IRI. The colon (:) also makes them invalid JavaScript identifiers, and hence we also need maplike for them.

Problem 2: There is a perceived risk of a security leak for some, as the WebIDL does not restrict what attributes will be part of the object API. Yet I fail to see the actual risk here: TDs are well defined and can be validated through multiple mechanisms such as JSON Schema, Shapes/SHACL, or even custom validators of the runtime that also knows which feature exactly is supported. The Scripting API can define a MUST be validated before instantiating the API object. Furthermore, the maplike mechanism defines which types are allowed: key_type is always a string, value_type is always a JSON data type -- never a function/callback/Promise/etc.

Summary:

• Does maplike enable introspection for the object API?

interface ConsumedThing {
  readonly attribute DOMString name;
  /* business as usual continues... */
  /* introspection for extensible metadata attributes */
  readonly maplike<USVString, value_type>;
};

• How to best constrain the value_type to JSON data types only?
• Can there be a security risk when the API objects are generated from JSON documents that can further be validated against a formal model?

[zolkis]

WebIDL restricts using one maplike in a given interface and all its inherited interfaces (should be fine for this use case). Also, an interface containing maplike cannot be declared iterable (which may be a problem).

In principle I suggest separating JSON[-LD] data from interface objects specified in the API doc.
The result of fetching a TD is data that can be used for instantiating a standardized ConsumedThing object.
IMO the ConsumedThing object should be defined exactly and completely in the Scripting API spec.
For introspection it should be enough to have a method that returns a data object/record that uses map-like access for semantic metadata attributes (only), or all attributes.

Spec prose can specify algorithms to validate maplike values as JSON data types.

The algorithms used in an API implementation (runtime) for validating a TD could be defined externally and referenced from the Scripting API spec.

[mkovatsc]

Maplike solves your first point:

Maplike interfaces support an API for querying the map entries appropriate for the language binding. If the readonly keyword is not used, then it also supports an API for modifying the map entries.

Note: In the ECMAScript language binding, the API for interacting with the map entries is similar to that available on ECMAScript Map objects. If the readonly keyword is used, this includes entries, forEach, get, has, keys, values, @@iterator methods, and a size getter. For read–write maplikes, it also includes clear, delete, and set methods.

The existence of maplike tells me we are wrong in what we want. I want to maximize user=developer-friendliness.

We do not need spec prose. We can cleanly define a type for value_type. I am just confused that there is no ready-to-use definition already.

[zolkis]

The problem is that based on the Web IDL spec the interfaces that contain a maplike are purely map-like, IOW you cannot make the ConsumedThing interface declare to be maplike AND also contain methods and other properties. The way I understand to do it is to define ConsumedThing as an API object, and for the data structure that reflects the TD (ThingDescription/ThingMetadata/etc) declare an interface to be maplike - but then all its properties are defined by mapping.

Also, IMHO it would be more clear (developer-friendly) to say

let context = thing.td['@context'];

than to say

let context = thing['@context'];

AFAIK JSON types are denoted by any. We do need prose to specify/refer to externally defined algorithms on how to transform/validate values.

We might also want to enumerate/refer to known (e.g. '@context', '@type' etc.) key-valuetype pairs for a TD, so that implementations could make a more thorough checks than key should be string and value type can be JSON type.

[mkovatsc]

The problem is that based on the Web IDL spec the interfaces that contain a maplike are purely map-like

I cannot see how you come to this conclusion. There is no text on this. Yet there is text, what other member names must not be called:

Maplike interfaces must not have any interface members named "entries", "forEach", "get", "has", "keys", "size", or "values", or have any inherited interfaces that have members with these names.

A problem I see here is that with this, myThing.properties.status.get() will not work. Need a different name.

[mkovatsc]

Another aspect that came up is: who would RDF-style consumers of the TD want the annotations. @vcharpenay mentioned that in one of his explorations, he flattened the parsed JSON-LD object first to work with it. A ConsumedThing with readonly maplike access cannot be flattened; he would need a copy first anyway...

We need more reasons like this to decide whether we have the annotations inline with the API object or, for instance, get a copy via something like myObject = myThing.getTD().

[zolkis]

Both the text and examples in bindings hint at "pure" maplike interfaces, at least as how they meant to be used: https://developer.mozilla.org/en-US/docs/Mozilla/WebIDL_bindings
However, it should be possible to implement maplike on any interface, since even if we assume maplike interfaces were "pure", one could declare another interface that implement a ("pure") maplike interface, ending up with the same thing. So probably you are right about that.

Still, I think we might be better off using named getters if you want to host semantic attributes on the same object, so instead of saying

interface ConsumedThing {
   // ...
   readonly maplike<DOMString, USVString>;
};

we'd say

interface ConsumedThing {
  // ...
  getter USVString (DOMString name);  
};

Anyway, IMHO it would be both more clear and more flexible to use a getter for the TD (returning a maplike object) like also @tobie and @kenchris suggested, rather than to inline its semantic attributes at ConsumedThing object level by making it maplike. Conversely, IMHO inlining would not be more developer-friendly.

@vcharpenay could you give input? :)

[mkovatsc]

https://github.com/mozilla/gecko-dev/blob/250785729c6ba4fdae4d9967acf7c4733fb8b76f/dom/webidl/RTCStatsReport.webidl

interface RTCStatsReport {
  readonly maplike<DOMString, object>;
  [ChromeOnly]
  readonly attribute DOMString mozPcid;
};

https://github.com/mozilla/gecko-dev/blob/86897859913403b68829dbf9a154f5a87c4b0638/dom/webidl/TestInterfaceJSMaplikeSetlikeIterable.webidl

interface TestInterfaceMaplike {
  maplike<DOMString, long>;
  void setInternal(DOMString aKey, long aValue);
  void clearInternal();
  boolean deleteInternal(DOMString aKey);
  boolean hasInternal(DOMString aKey);
};

[mkovatsc]

AFAIK JSON types are denoted by any

The problem with any is that it includes Function, as it is a sub-type of Object. Although we are safe through the definition of (RFC7159) JSON and a preceding TD validation that there will not be any Function in the TD data, I was thinking about excluding objects from the extension mechanism altogether.

For the known/core objects, the Scripting API provides a WebIDL interface to define how to use the particular object in a script, e.g., for properties or links.

For unknown/extension objects, the Scripting API cannot provide interfaces. At the moment, I cannot see, for what purpose additional contexts might bring in such objects as values and what a script would do. They basically carry additional Linked Data instances. Overall a JSON-LD security consideration, but TD can have additional restrictions. And it still is possible to point to RDF resources by simply using their URI instead of inlining.

Additional contexts are mainly there for providing metadata, which should be a literal (boolean, integer, number, string) or a vocabulary term (string as well; works like an enumeration within the controlled vocabulary of the context and can also be the URI of any RDF class or instance).

To all: please provide use cases for unknown/extension objects in the TD -- and how they would be used by a script.

[zolkis]

It seems fine to represent the type of semantic metadata with USVString in general.

I agree that we cannot have an API that creates interface objects based on a TD, but we can create dictionary objects (without functions) for representing them. The functions operating on that data should be in well defined interfaces. Validation must happen in the runtime, and we should be able to reference the algorithm from the Scripting API spec.

[danielpeintner]

It seems fine to represent the type of semantic metadata with USVString in general.

I am not sure if the following aspect applies to other terms but I do know that entries for @context can be of type string (e.g., "https://w3c.github.io/wot/w3c-wot-td-context.jsonld") but also of type object IF there is the need for a prefix (e.g., {"iot": "http://iotschema.org/"}).

I wonder whether similar aspects for other semantic metadata has a consequence on the API...

[zolkis]

Typically how a script would use semantic metadata? Any examples in mind?

[mkovatsc]

e.g., {"iot": "http://iotschema.org/"}

Very good and obvious point I completely forgot!

I agree with @zolkis that we need concrete examples how a script would consume this. I would like to see something that combines simple scripting with the potential of Linked Data. This could work with through registered prefixes for WoT context files, e.g., so that https://iot.schema.org/ always has the prefix iot:. Normal developers could rely on this to do simple string matching; Semantic Web developers still get the power of queries, reasoning, etc. @vcharpenay comments?

[mkovatsc]

My current assumption was for ExposedThing has been like this:

myThing.properties.addProperty({ ... });

Would a named setter on the ExposedThing interface like setter ThingProperty setProperty(string id, ThingProperty property) allow the following:

myThing.properties.status = { ... };

while the runtime internally calls setProperty(), which does a validation of { ... }?

If so, we could have both, addProperty() and the named setter, which internally uses the implementation of addProperty(), no?

[mkovatsc]

If the named getter on ConsumedThing like getter any (USVString identifier) allows the following:

let semType = myThing.properties.status["@type"];
let unit = myThing.properties.status["iot:unit"];

then a named getter might be better, because myThing.properties.status.get() would be available. With maplike, get() is reserved.

[zolkis]

let semType = myThing.properties.status["@type"];
let unit = myThing.properties.status["iot:unit"];

This doesn't seem very JS developer friendly to me (may be for semantic guys). It would be nice to [reduce to] use simple property names such as "unit" in scripts and keep namespace and context separately.

Besides, what use cases do we have for mixing namespaces within an interaction?
I am just not convinced that operating in JSON-LD terms with JS syntax makes for a good API.
Let's base this on concrete use cases, examples and work it up from there.