Describe JSON-LD with WebIDL - How to handle @ tags

[danielpeintner]

Hi WebIDL community,

we in the WoT working group and specifically the task force around scripting are working on a document (current version) that tries to describe the functionality of a WoT thing description (TD) that is based on JSON-LD. Moreover, based on this TD JSON-LD document scripting acts as a wrapper and adds further functionality to manipulate the content.

JSON-LD documents tend to have lots of @ tagnames. For example a TD snippet:

{
  "@context": ["https://w3c.github.io/wot/w3c-wot-td-context.jsonld"],
  "@type": ["Thing"],
  "name": "MyLampThing"
  ...
}

These @ tags cause issues in WebIDL (as in any programming language) given that those names are not valid identifiers.

interface WoTTD {
	readonly attribute DOMString @type;
	...
}

Moreover, a naive solutions to this issue like removing/replacing the @ prefix all together is also not very usable/practical given that

• besides @type there might be also type fields
• serializing the wrapped JSON-LD content again requires additional processing
• no "correct" representation/match between TD and scripting

Hence, I was wondering whether you, as the WebIDL experts, have additional proposals or another way of tackle this issue. Have you (or others?) run into the same issue with JSON-LD and WebIDL?
How could we describe the content of a JSON-LD document with WebIDL?

Thanks a lot for any insight or tip!

[tobie]

So I think the problem here is you’re using WebIDL to describe the JSON format and not the actual JS APIs that are going to wrap it up. You probably want to use JSON schema for this and/or follow whatwg/infra#159.

[domenic]

Agreed, Web IDL is not meant to describe JSON and is not in general a good tool for the job.

[marcoscaceres]

Also agree. We screwed up web manifest trying to describe it as WebIDL. Please avoid making similar mistakes.

[zolkis]

I also suggested using a method, for instance something like getMetaData(id) for fetching the @ fields, e.g. for @context we'd invoke getMetaData('context').

However, it was suggested that if we can't get WebIDL to support the use case, then just simply leave them out of the WebIDL descriptions and use prose in the spec describing them (like with internal slots), since ECMAScript allows using object['@context'] accessors. It's perhaps confusing.

[bzbarsky]

Realistically, you have a few options, if these are meant to be objects implemented by the browser (and hence interfaced with via Web IDL):

1. You could use an IDL maplike, so thing.get("@context") would work.
2. You could use an IDL named getter, so thing["@context"] would work, but with somewhat different semantics from a readonly attribute.
3. You could define some sort of name-mangling scheme that maps @foo onto a valid Web IDL identifier.

What you probably can't get browsers to implement is having an object that has a bunch of stuff defined in IDL and oh, some other properties that are not defined in IDL.

If these are not objects meant to be implemented by browsers, then I'm not sure why one would use Web IDL for defining them, necessarily.

[zolkis]

Thanks @bzbarsky, makes sense. Either 1. or 2. would work for me. We are using maplike also elsewhere in the API. Need to check on the named getter semantics.

Although the Web of Things mainly targets runtimes for (server) Thing implementations, the future possibility of implementing client, or even server Things in browsers is in scope, hence we strive to be able to describe Thing APIs with WebIDL.

[tobie]

Note that you can also have something like this:

interface Thing {
  object getJSONLD();
};

Where getJSONLD simply returns the JSON, either raw, or cleaned-up as described in prose somewhere.

[kenchris]

Probably just .jsonld() as .json() is used elsewhere on the platform (but returning a promise)