Add spec text for scoped contexts

[gkellogg]

to syntax and API documents along with compaction and expansion tests.

Fixes #247. Fixes #262. Fixes #369.

[gkellogg]

This ended up being a pretty small change to Expansion and Compaction algorithms. Solves three different open issues. Note that #426 would have addressed this too, but it seems to be lacking support.

[lanthaler]

The required changes are indeed surprisingly small.

What concerns me is that a conformant JSON-LD 1.0 processor would silently process a document with scoped contexts by simply ignoring them. This would yield to a situation in which two JSON-LD processors would process and thus interpret a document differently. This is particularly dangerous if a default vocab is set at the top level of a document as it is the case for almost every usage of schema.org. I think we should tweak the design so that 1.0 processors would reject such documents. What do you think?

[lanthaler]

This is a property of a conformant document, not a requirement of the algorithm. So shouldn't this remain a lowercase must?
(same elsewhere)

[gkellogg]

Debatable, but that seems to be were we came down in the 1.0 document, so we'll use "must".

[lanthaler]

errors -> error

[lanthaler]

Do we really want swallow the error though? Or should we start supporting nested errors?

[gkellogg]

IMO, we go overboard on errors as it is. This tells the author that the problem is with a scoped context, rather than with the context in general, so it seems more useful this way to me.

[gkellogg]

What concerns me is that a conformant JSON-LD 1.0 processor would silently process a document with scoped contexts by simply ignoring them ...

I believe @context is still illegal for a JSON-LD 1.0 processor, so if run using processing mode "json-ld-1.0" an error should be generated. For it to be accepted, processing mode must be "json-ld-1.1". The spec says that "json-ld-1.1" is the default processing mode for version 1.1.

From 1.0:

Initialize container to the value associated with the @container key, which must be either @list, @set, @index, or @language. Otherwise, an invalid container mapping error has been detected and processing is aborted.

[gkellogg]

Oops, never mind, wrong change; let me check more; we were pretty careful for looking at such things.

[gkellogg]

Looks like you're right. Create Term Definition doesn't look for a constrained list of term definition properties, which it should have. Perhaps we could consider an errata for 1.0 to error on "invalid term definition" if it contains anything other than @id, @reverse, @container, or @language, or @type. Without this then we could certainly run into a situation where a 1.0 processor sees a 1.1 document and does something different.

Do you have a suggestion for how to handle this? We need to be able to do new things for 1.1.

[gkellogg]

@lanthaler thanks for your review! I addressed your specific issues, and added wording about giving an error on unexpected keys in a term definition. Something like that could be considered for a 1.0 errata, but would need to investigate how to make that happen.

Probably best to wait until we're closer to finishing 1.1 in case any other things to be addressed in 1.0 come up.

[dlongley]

+1 to merging this. If we can leave an issue open to try and address the 1.0 vs. 1.1 issue in a better way that would be a good thing.

[lanthaler]

Term mappings require the value to be null, a string or an object. So we could trigger an issue by a value that is a number (version), a boolean (flag), or an array (list of required features). Something like

{
  "@context": {
    "@version": 2,        <---------------------------- triggers an error
    "name": "http://schema.org/name",
    "interest": {
      "@id": "http://xmlns.com/foaf/0.1/interest",
      "@context": {
        "@vocab": "http://xmlns.com/foaf/0.1/"
      }
    }
  },
  ...
}

or

{
  "@context": {
    "@mustunderstand": [ "nestedcontexts" ],        <--- triggers an error
    "name": "http://schema.org/name",
    "interest": {
      "@id": "http://xmlns.com/foaf/0.1/interest",
      "@context": {
        "@vocab": "http://xmlns.com/foaf/0.1/"
      }
    }
  },
  ...
}

[gkellogg]

Of there, the "@version": 2 (better 1.1 as the spec version is titled) is least objectionable, but I'd rather not need to resort to this. Most other things that are being considered for 1.1 will be caught, just not this specific feature. I'd rather handle it with an errata to 1.0.

That said, we might want to have a specific version announcement feature in the context. Perhaps setting the processingMode directly, in which case:

{
  "@context": {
    "@processingMode": "json-ld-1.1",
    ...
  }
}

would be a better way to do this, and be consistent with our description of processingMode JsonLdOptions value, which could also be an alternative way of specifying the processing model.

The JSON-LD Framing 1.1 document specifies using "json-ld-framing-1.1-expand-frame" as the processing mode to be passed to the Expansion algorithm when processing the JSON-LD Frame (this should probably change to "json-ld-1.1-frame-expansion", or similar, once framing is rolled into the API document). We could consider requiring that frames include this processingMode setting to allow for such features, rather than make it implicit.

[gkellogg]

@lanthaler If you think your review concerns are satisfied, can you complete the review?

I'm going to add an issue on adding @version to the context for enabling such features, although I'm not sold on it myself.

Presume your issues have been resolved, given the open issue #446 on version announcement.

[lanthaler]

Sounds good