@version announcement for enabling 1.1 features

[gkellogg]

In PR #445, @lanthaler had a concern that a 1.0 processor would silently ignore extra properties of an expanded term definition, such as @context as specified for #247. As it happens, this is one of the few places the 1.0 algorithms didn't look for extra values to raise an exception.

One way to do this is using the processingMode API option, which is defined to be json-ld-1.1 for the 1.1, or json-ld-1.0 for the Recommendation. But, in most cases, this can't be specified, and there's no way to determine what version a document is intended for.

One solution is require that a context using 1.1 features specifically announce this using @version.

{
  "@context": {
    "@version": 1.1,
    "term-using-1.1-features": {"@context": {...}}
  }
}

I would say that either processingMode is specified explicitly (keeping the default at json-ld-1.0), or that the context contains @version. One consideration is that Framing now uses processingMode: json-ld-1.1-expand-frame to allow the special features in a frame document, and adding this using @version would be problematic.

That said, another solution would be to create an erratum on 1.0 to add better checking for keys in an expanded term definition, and possibly other places, as may prove necessary.

[gkellogg]

See @lanthaler's comment in #445 (review)

[akuckartz]

I dislike ‘version‘ properties.

[gkellogg]

@akuckartz Do you have an alternative suggestion for how to ensure that 1.0 implementations don't silently ignore 1.1 features?

[gkellogg]

My thought here is to not define a default for processingMode in the API. In 1.0, the processingMode defaults to json-ld-1.0. In 1.1, I would say that the default comes from the context used for expansion or compaction.

If not specified through the API, Context processing establishes a version in the first context that is a JSON Object that could contain @version. If it is specified, it must be 1.1 (future versions of JSON-LD may establish other numeric values). If version 1.0 has been established (via API or the absence of @version in the first encountered JSON Object context), encountering a @version: 1.1 is an error.

This allows legacy contexts to be used along with 1.1 contexts, as long as the 1.1 context is established first, or the version is set explicitly through the API. 1.0 processors will (should) have implicitly set version to 1.0, and will (should) error when encountering a @version key in a context.

The consequence for this when expanding is that the version cannot be absolutely established until after context processing.

[lanthaler]

SGTM