Clear description of the issue "using WebIDL to describe maplike access of JSON-LD documents with @ fields"

[danielpeintner]

This issue is meant to find a crisp and crystal clear description of the issue "using WebIDL to describe maplike access of JSON-LD documents with @ fields".

Please comment whether the following statements are clear or how they can be improved.

---

The new Scripting API is meant to wrap a thing description document (defined in JSON-LD). Doing so requires to describe fieldnames starting with @ such as @context or @type (stemming from JSON-LD) and also describe how to fetch such fields.

Let's assume a partial interface description for a thing in WebIDL

interface Thing {
  readonly attribute DOMString name;
  readonly attribute sequence<DOMString> @context;
  readonly attribute sequence<DOMString> @type;
  ...
}

Unfortunately, attribute sequence<DOMString> @context is not valid WebIDL!

On the other hand valid JavaScript usage with the bracket notation is possible.

let thing = ...; /* getting a thing */

if( thing["@context"].indexOf("https://w3c.github.io/wot/w3c-wot-td-context.jsonld") !== -1
 &&  thing["@type"].indexOf("Thing")  !== -1 ) {
   console.log("Yes, we got a WoT Thing");
   /* do further processing */
}

The question arises how to use WebIDL in situations where JS code is valid and WebIDL isn't?

[zolkis]

A "fake" summary of the Thing Description (TD) in WebIDL is in the first comment of #96, serving only for illustration/inspiration (otherwise I agree that using WebIDL there is invalid and confusing). It was done for introducing the second comment, which is the scripting API that is designed based on the TD structure.

The problem we have there is the @context and @type meta-properties in an object that might also contain type and context properties.

One way out is to use a getMetadata(id) method where id is either 'context' or 'type' to denote @context and @type read-only meta-properties. However, in ECMAScript it would be possible to access meta-properties with map access, e.g. object['@context'] - the question is could we define such accessors in WebIDL.

The question is how to concisely write the Scripting API spec so that it is clear to implementations (that may use WebIDL tooling) what is to be exposed and how to validate it.

[mkovatsc]

I would keep it to the point what we want and leave out the TD aspects to avoid confusion. Thus, I would post the following to the WebIDL Issues:

---

This is not about using WebIDL for JSON-LD or any document. We want to define an object API to enable the interaction with Things in the Web of Things from a scripting runtime system. (To be intuitive, the structure of the object API shall follow the structure of the description document, though.)

Most of that object API can be simply defined using WebIDL interfaces, as most attributes and all functions are well defined.

However, we also want that same object API to allow for introspection of optional, arbitrary string metadata, that is, attribute names within the object API that we do not know beforehand. Furthermore, some of these attribute names may not be valid identifiers such as @-prefixed JSON-LD keywords, so that we need the map-like access with brackets (e.g., myAPIObject["@type"]) .

(There was the proposal to define a getJSONLD() function that returns a plain object that fulfills this second requirement separately by carrying these optional annotations in a second object retrieved from the API object; while this works, it appears pretty ugly for introspection...)

Thus, we want to check if there is a good way to express both aspects on a single object in WebIDL. The object definition would be a combination of an interface and maybe this new record type (whatwg/webidl#180 (comment) seems to be related to our problem).

If this combination is not possible, we would only use WebIDL for the first, straight-forward part of the object API and then explain in prose that the API object can be introspected for additional metadata using normal iteration and map-like access.

[zolkis]

We already got pretty clear and usable feedback there, the rest we need to figure out ourselves IMHO.

[mkovatsc]

@zolkis could you summarize here the options and solutions we now have based on the clear feedback?

[mkovatsc]

Technically, the following works (tested in Firefox Web Console):

> var test = '{ "@context": "some uri", "name": "My Thing", "properties": { "on": { "forms": "blub" } } }'
< undefined
> obj = JSON.parse(test);
< Object { @context: "some uri", name: "My Thing", properties: Object }
> obj["@context"]
< "some uri"
> obj.properties.on
< Object { forms: "blub" }
> for (i in obj) console.log(i);
  @context 
  name 
  properties 
< undefined

[zolkis]

Fixed by #113.