Re: Why is the value of @version a number?

One of the trickier things we face is that JSON-LD is both a syntax (or JSON-based data format) and a processing API.


Regardless of how we signal the new features from the syntax-level, there will be parsing ramifications at the API level.

There's a note in the current spec which says:
"Setting the processing mode explicitly for JSON-LD 1.1 is necessary so that a JSON-LD 1.0 processor     does not attempt to process a JSON-LD 1.1 document and silently produce different results."

But for that to work, JSON-LD 1.0 processing code would have to error-out/give-up/whatever when they see `"@version": 1.1`. That essentially means that existing API code will have to upgraded in order to handle the `@version` key (try tossing `@version` into an example on http://json-ld.org/playground for instance).

The *consumer* of incoming JSON-LD needs to be aware of both what the inbound syntax contains, and what their processing/API code can currently handle (relative to what's been specified).

The forthcoming "list-of-lists" feature is a prime example of this scenario. ActivityStreams, which is used in the ActivityPub protocol used in Mastodon, may contain "raw" GeoJSON data. Consequently, they had to define their own media type and additional processing rules for handling that data properly. None of these documents signal a version, nor are they likely to get one added as they move around the decentralized Web.

Ultimately, I think our approach to versioning is going to need much more consideration and scenario planning... See https://github.com/w3c/json-ld-syntax/issues/33 for some current discussion.

What would help from a community perspective is more scenarios, tests, and apocalyptic use case advice. :) We want this "upgrade" to go smoothly for everyone, and consequently could  use "everyone's" help. ^_^

Thanks for starting this conversation!
Benjamin


--

http://bigbluehat.com/

http://linkedin.com/in/benjaminyoung

________________________________
From: Gregg Kellogg <gregg@greggkellogg.net>
Sent: Saturday, August 18, 2018 12:52:58 PM
To: Asbjørn Ulsberg
Cc: Robert Sanderson; Lutz Helm; Linked JSON
Subject: Re: Why is the value of @version a number?

\On Aug 18, 2018, at 4:59 AM, Asbjørn Ulsberg <asbjorn@ulsberg.no<mailto:asbjorn@ulsberg.no>> wrote:

[https://tr.cloudmagic.com/h/v6/emailtag/tag/2.0/1534593599/bc428a9bbcd4763a7a7e36381a958805/2/7370c81ae1304c5b743d984bf035dc36/358f796c3036bcd0d747bc6cc7b85e47/4d26143d9c798ef8d301ab6cba45fcf4/newton.gif]
Do I understand the versioning correctly in that it is not a semantic version number?

https://semver.org/

If JSON-LD followed SemVer, 1.0 processors should be able to process all 1.x versions of JSON-LD, but not 2.x, since the major version indicates breaking changes.

If there’s breaking changes in 1.1, it can surprise implementors since according to SemVer that’s supposed to be backwards compatible with 1.0.

(Not an official response, but my perspective on the choice of versioning).

Perhaps a difference of interpretation, but 1.1 is fully backwards compatible with 1.0. There is new functionality introduced, which requires the @verision signaling. According to the sited semver:

Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented.

Changes are backwards compatible and new functionality is added (the “within the private code” part is problematic). In my experience, new minor versions of software using semver often introduce new functionality, that you can’t expect software conforming to a previous version to implement. For this, there is patch versioning. Major versions are for when previously compliant code would break with the new version, which is not the case here.

That said, the choice of versioning at W3C can be IMHO more political than technical, and it’s not likely we’ll see a 2.0 version in spite of any changes that may be made. For this, we need look at the charter [1]: “All changes must preserve backward compatibility for JSON-LD 1.0 documents.” But, this may be subject to interpretation by the WG.

Gregg

[1] https://www.w3.org/2018/03/jsonld-wg-charter.html

--
Asbjørn Ulsberg    -=|=-    asbjorn@ulsberg.no<mailto:asbjorn@ulsberg.no>
«He's a loathsome offensive brute, yet I can't look away»

On lør., aug. 18, 2018 at 0:18, Robert Sanderson <azaroth42@gmail.com<mailto:azaroth42@gmail.com>> wrote:

I understand the concern, but at the speed of W3C standards, the likelihood of ever getting above 1.9 is extremely extremely low :D
1.0 started in 2012, 1.1 started 2018 ... extrapolating, it would be 2072 before we would need a 1.10

W3C does not have patch version, only external errata. I think a floating point number is fine here.

Rob

On Fri, Aug 17, 2018 at 3:01 PM, Gregg Kellogg <gregg@greggkellogg.net<mailto:gregg@greggkellogg.net>> wrote:
> On Aug 17, 2018, at 6:52 AM, Lutz Helm <helm@ub.uni-leipzig.de<mailto:helm@ub.uni-leipzig.de>> wrote:
>
> Hi,
>
> I just stumbled upon the fact that @version has to be a number in json-ld 1.1 contexts. Is there any reason why this is not a string?
> I guess it shouldn't ever happen that a spec is released as patch version, and there will probably not be more than eight more versions with nonbreaking changes to the spec, so a decimal number might suffice, but I'm still a little bit puzzled.

The reason @verion is a number, specifically 1.1, is so that a 1.0 processor not prepared for it will through an error, as every other value must either be a string, null, or an object. We want a 1.0 processor to stop processing so that it does not interpret the context and associated JSON-LD in a way which is different than a 1.1 processor would, so we make sure it will raise an exception.

Gregg

> Best regards,
> Lutz
>
> --
> Lutz Helm
> Bereich Digitale Dienste
> AG Anwendungsentwicklung
>
> Universitätsbibliothek Leipzig
> Beethovenstraße 6, 04107 Leipzig
>
> T: +49 341 97 30566
>
> helm@ub.uni-leipzig.de<mailto:helm@ub.uni-leipzig.de>
> https://www.ub.uni-leipzig.de/
>
>





--
Rob Sanderson
Semantic Architect
The Getty Trust
Los Angeles, CA 90049