TAG interoperability concerns

[mlagally]

David Baron:
I'm also concerned that the architecture overview says "The format can be processed either through classic JSON libraries or a JSON-LD processor": is this defined in a way such that both types of processing will yield the same results in all cases? If not, what leads to interoperability?

[takuki]

Note: This is with regards to a TAG comment w3ctag/design-reviews#355 (comment) from @dbaron.

[takuki]

I created PR #379 for this issue.
Please comment and make suggestion or improvements to the PR.

[dbaron]

I was asked to give some examples of interoperability concerns. Here are two, one in each direction:

1. A developer is asked to optimize the file size of thing descriptions. Since this developer thinks that using content negotiation to serve either a compressed or uncompressed version wouldn't address the reason there was concern over file sizes to begin with, she decides to use her knowledge of JSON-LD, make her own copy of the context document https://www.w3.org/2019/wot/td/v1, rename a bunch of the JSON property names to be shorter. For example, she modifies this bit: "securityDefinitions":{"@id":"td:securityDefinitions","@type":"@id","@container":"@index"} to instead be "sd":{"@id":"td:securityDefinitions","@type":"@id","@container":"@index"} (and a bunch of similar changes), and then changes all of the thing descriptions in her system to reference this modified context document instead of the standard one, and also to use the sd name instead of securityDefinitions (and other similar changes). She tests that this works against a bunch of implementations, and it works fine since all the implementations she tests process the thing descriptions as JSON-LD (is there a correct term for this?), and then deploys the change. This change, however, reduces interoperability since it breaks the use of these thing descriptions in any implementation that processes them as JSON.

2. A developer (in an project unrelated to the one in the first example) receives a bug report that processing thing descriptions is sometimes slow due to the network latency needed to retrieve https://www.w3.org/2019/wot/td/v1 . (Or maybe, instead, this was the same bug report the previous developer got, about optimizing file size.) She looks at the thing description files and determines that the @context bit isn't actually needed. She tests her change in a bunch of implementations, and it works fine, since all of the implementations she tests process the thing descriptions as JSON (rather than as JSON-LD, as in the previous example). So she deploys the change. This change reduces interoperability in the opposite direction: it breaks the use of these thing descriptions in implementations that process them as JSON-LD.

These sort of interoperability problems seem inherent to any spec that defines things as JSON-LD without specifying which processing model implementations must use. So I keep asking these questions of specs that refer to JSON-LD, because these sort of interoperability problems are frequently real-world problems in systems deployed at the scale of the Web.

[mlagally]

Reopening and changing title to "Interoperability concerns"

[mlagally]

Discussion in arch call on 12.9.:

The entire TD specification makes normative assertions that define a valid TD. The URL https://www.w3.org/2019/wot/td/v1 is just used as an identifier, and the content does not have to be retrieved for validating a TD.
The entire section 5 of the TD specification defines the normative vocabulary of a TD.
Even JSON-LD serialisations need to satisfy this aspect of the specification.
For convenience, there is also an (informative) JSON-Schema for the valid syntax of the Thing Description (https://www.w3.org/TR/wot-thing-description/#json-schema-for-validation).

1. violates the specification, since the required terms are defined in the spec.
2. also violates the specification, since @context is mandatory.

We also work to address other interoperability concerns and work with the JSON-LD group and via mechanisms such as profiles.

[mlagally]

Further considerations of TD interoperability should be discussed in the TD TF.