JSON-LD Best Practice - Version JSON-LD Context files

[msporny]

I'm doing a spotty review of the WoT TD spec here:

https://w3c.github.io/wot-thing-description/

A couple of comments on how to specify JSON-LD Context files and associated RDF Vocabularies under W3C space. The current spec contains this in the examples.

  "@context": [
        "http://www.w3.org/ns/td",
    ],

I suggest versioning the JSON-LD Context file so you have some control over future upgradability, so do this instead:

• Publish the TD vocabulary at: https://www.w3.org/2019/wot/td
• Publish the JSON-LD Context file at: https://www.w3.org/2019/wot/td/v1

This is what the Verifiable Claims WG is doing and is considered a best practice because:

• It enables you to do drastic upgrades to the TD vocabulary and not break implementations in the field. For example, if in 2022 you decide you made some terrible mistakes, you can always publish a radically different TD at: https://www.w3.org/2022/wot/td and a new JSON-LD Context at: https://www.w3.org/2022/wot/td/v2.
• It enables you to do simple upgrades to the JSON-LD Context... v1.1, v1.0.4, etc. without breaking field deployments.
• It enables people to understand when the context/vocab they are using was last published/updated just by looking at the URL.

[vcharpenay]

Quick question, @msporny: isn't it redundant to have both 2019 and v1 in the same URI?

• if your aim is to have distinct URIs for vocab and context, one could make it more explicit, e.g. by appending the actual file name at the end of the context path.
• if it is to avoid cases where two versions get published the same year, why not adding a month to the URI (some W3C URIs follow that pattern, like rdf:, rdfs:, owl:)?

Otherwise, I would personally suggest to have one single namespace for both resources, set up with content negotiation; the two files are inter-dependent, it is legitimate to put them under the same namespace. What is your opinion on that?

[msporny]

isn't it redundant to have both 2019 and v1 in the same URI?

No, because you might do a bug fix in 2020 to the v1 context. I expect such an event would be rare, but there are some cases where this might happen.

if your aim is to have distinct URIs for vocab and context, one could make it more explicit, e.g. by appending the actual file name at the end of the context path.

Yes, that is correct... https://www.w3.org/2022/wot/td would provide a human readable vocabulary document, while https://www.w3.org/2022/wot/td/v1 would provide just the JSON-LD Context. Yes, you could do content negotiation, but we've found that many developers do a terrible job wrt. conneg and they either botch their implementations, or generate a ton of questions wrt. "I'm getting back text/html for the JSON-LD Context, what is going on!?" :)

Does that answer all of your questions?

[ashimura]

@msporny I just wanted to ask you if your point is:

• adding year as an additional identifier to identify TD vocabulary updates
• adding v* as a yet another additional identifier to identify JSON-LD context updates

If so, maybe we can continue to use "https://www.w3.org/ns/td" as the basis
for the WoT Thing Description namespaces and add year and v* to identify
vocabulary changes and context changes.

What do you think?

[ektrah]

My personal take: When publishing updated context files, it’s a good idea to version these. However, when referencing them, I see little value in being able to reference a context file with or without e.g. some typo fixed. If the updated context file doesn’t break any existing referencing files, all referencing files should simply use the latest published context file. Of course, if the context file contains breaking changes, then referencing files need to explicitly opt-in. So, to me, it seems sufficient to have exactly one numeric part in the URI that is only incremented when referencing files shouldn’t be updated automatically to the latest version.

[ashimura]

@msporny @ektrah sorry maybe I was not clear enough.

My point was how about using https://www.w3.org/ns/td/2019/v1 , etc.

And another question of mine as well was we (=WoT WG) should also clarify how to use "2019" part and "v1" part to manage vocabulary changes and context changes :)

[sebastiankb]

https://www.w3.org/ns/td/2019/v1 looks fine to me, but for me it's not clear if it's compliant to W3C namespace policy

[vcharpenay]

If it is simpler to keep http://www.w3.org/ns/td, I would rather suggest the following:

• keep exactly this namespace for the OWL ontology and rely on owl:versionIRI for versioning (which does not imply any change in the namespace IRI over time)
• version the JSON-LD context with full semantic versioning with context-x.y.z.jsonld (x major, y minor and z patch)

In other words:

• http://www.w3.org/ns/td for the ontology
• http://www.w3.org/ns/td/context-1.0.0.jsonld for the JSON-LD context

With that, we minimize both the amount of changes in the spec and possible ambiguity.

[msporny]

My point was how about using https://www.w3.org/ns/td/2019/v1 , etc.

Please no, let's not do this... the VCWG decided to use the structure below. The DID WG is expected to use the pattern below as well:

    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
    "https://www.w3.org/2019/did/v1",

We spent a considerable amount of time exploring the right way to do this... and the proposals above are problematic (too verbose, under ns/* which leads to philosophical rabbit holes w/ Web Developers, exposing .jsonld extension when that's not necessary, unnecessary minor point versioning, etc.)

Please use this pattern instead:

• http://www.w3.org/2019/td for the ontology (this enables you to drastically change the ontology in the future)
• http://www.w3.org/2019/td/v1 for the JSON-LD context (this enables you to make breaking changes in future years, and major/minor should be as deep as you go. Please don't do point releases to JSON-LD Contexts). This approach also let's you drastically rewrite the v1 context in a future release (in the year 2022, for instance) w/o breaking deployed implementations.

You have full backwards and forward compatibility with the approach above.

[vcharpenay]

I personally find the proposal satisfactory. Now, as you said, @msporny, it is probably better if developers figure out what is behind a URL just by looking at the URL. Yet, there is nothing saying .../2019/td/v1 is the context URL.

So, why not .../2019/td/context-v1 or somtheing similar?

[msporny]

So, why not .../2019/td/context-v1 or somtheing similar?

We have found (through developer use of schema.org in the wild, as well as Verifiable Credentials) that developers copy-paste examples and don't often think about what they're copy-pasting. We've also found that most JSON developers don't care that it's a JSON-LD Context, they just view it as a declaration like an #include statement, and when they don't do the proper statement, their code doesn't work.

So adding 'context' doesn't add value to the vast majority of developers, and those that know about JSON-LD or implementation details, know what it is.

[mkovatsc]

We should define it just like @msporny recommends and close this chapter/Issue.

[mkovatsc]

We clarified this during the call with Ralph and PLH, @vcharpenay implemented the change accordingly, and it was merged.