Wot-thing-description: Simplified TD: @context

[mkovatsc]

Moderated focused discussion on the Simplified TD proposal and @context. Please stay on topic and use https://github.com/w3c/wot/issues/393 for any general remarks.

In https://github.com/w3c/wot/issues/393 @benfrancis wrote:

I agree on using this for optional semantic annotations
Could we have the option for a context to be a single string (URI) rather than an array? You could still use an array if multiple contexts are needed.
```
{
"@context": "https://iot.schema.org"
...
}
````

[mkovatsc]

JSON-LD allows for having either a single string (or any type) or an array. In the WG we follow a convention to have arrays wherever arrays are possible to self-describe what is possible and to simplify parsing/serializing (avoid the need for checking if simple type or array).

Question is if you would implement the full support including array or would only support the single string case. If you would support also arrays, would you prefer having the check in your parser/serializer for a more simple-looking TD over reduced parsing complexity?

[mkovatsc]

In https://github.com/w3c/wot/issues/393 @benfrancis wrote:

Fair question. I'd be inclined to support both a string and an array because I imagine a single context could be a common case if stable schema repositories like schema.org emerge.

[mkovatsc]

Please note that it does simplify/prettify the TD, but puts more burden on the parser. When you implement constrained Things, these few bytes additional of program flash and probably RAM are actually often discussed.

Need more discussion to revisit the convention of putting brackets where arrays are possible.

[draggett]

Constrained devices are better exposed via application platforms acting as gateways. The application that exposes a thing for a constrained device can readily support the IoT protocols and device specific details.

[zolkis]

We should choose the format that makes sense, not the one that results in minuscule gains in parsing (you have to check for type anyway and you have to validate anyway). If there are reasons based on use cases for using arrays, we should use arrays. But we should not use arrays just in case they might be useful.
Supporting both string and array would work, too - if there is a use case for it.

[sebastiankb]

At the beginning we allowed both variants. However, the PlugFest showed that some implementations failed to read TDs that used only string instead of array or the other way around. To simplify the implementation and to avoid such kind of error we decided to have only an array representation to allow one or more context integration of the TD.

[mkovatsc]

Results from the transition to Simplified TD:

• @context is optional
  
  
  
  • The Media Type application/td+json identifies the document as TD, and hence the vocabulary of the TD core model applies (depending on preference either through a plain JSON parser implementation or JSON-LD processing with the TD context applied before feeding to the processor).
  
  
  • TDs can be used without any semantic annotations (no @type entries)
  
  
• When @context is given it can be just a string for a single context file or an array for one or more context files. The TD context file can still be omitted, as it is always applied by TD parsers/processors.

An open issue is still how to simplify processing of domain-specific vocabulary, which would be given through additional context files in @context. It would be good to have namespacing by requiring prefixes for the domain-specific terms. To keep it simple, these prefixes should be standardized, e.g., through a registration mechanism. It would also help to avoid that Things always have to fetch the context files and process them; they could rely on pre-installed vocabular, which makes sense, as it needs to fit the Things' purpose and capabilities.

[sebastiankb]

The new TD version defines @context optional.

@mkovatsc

An open issue is still how to simplify processing of domain-specific vocabulary, which would be given through additional context files in @context. It would be good to have namespacing by requiring prefixes for the domain-specific terms. To keep it simple, these prefixes should be standardized, e.g., through a registration mechanism. It would also help to avoid that Things always have to fetch the context files and process them; they could rely on pre-installed vocabular, which makes sense, as it needs to fit the Things' purpose and capabilities.

Another option can be that domain vocabularies have to carry the namespace within the key when no @context is used. E.g., ""http://schema.org/name": "Manu Sporny","

[sebastiankb]

I think, there is a good consensus about this approach and no open question. I will close this issue.