Explain why @context provides interop #548
Conversation
| <p> | ||
| A human-readable document describing the expected order of values for the | ||
| <code>@context</code> <a>property</a> SHOULD be available. A machine-readable | ||
| description (i.e. a normal JSON-LD "context" document) SHOULD be available |
There was a problem hiding this comment.
A JSON-LD Context isn't a SHOULD, it's a MUST, as described elsewhere in the specification (so we shouldn't restate it here).
There was a problem hiding this comment.
Fixed in 0221fbb ... but using your text.
| @@ -2097,6 +2095,19 @@ <h4>Semantic Interoperability</h4> | |||
| <code>@protected</code> feature in the JSON-LD 1.1 specification. | |||
| </li> | |||
| </ul> | |||
| <p> | |||
| A human-readable document describing the expected order of values for the | |||
| <code>@context</code> <a>property</a> SHOULD be available. A machine-readable | |||
There was a problem hiding this comment.
This is not testable, and thus should not be normative... thus the lowercase 'should' in the previous text.
| </p> | ||
| <p> | ||
| These requirements guarantee semantic interoperability between JSON and JSON-LD | ||
| for terms defined by the <code>@context</code> mechanism. While JSON-LD processors |
There was a problem hiding this comment.
I really like this last sentence and will be stealing it and integrating it into the PR I provided in an attempt to merge the best language in both PRs.
| be semantically compatible with one another without the JSON implementations | ||
| needing to process the documents as JSON-LD. To achieve this, the | ||
| specification imposes the following additional restrictions on both syntaxes: | ||
| This specification ensures that "plain" JSON and JSON-LD syntaxes are semantically |
There was a problem hiding this comment.
I like this language better than the language in my PR, I'll move it over to my PR in an attempt to align the language.
| of values of the <code>@context</code> <a>property</a> should be defined by | ||
| at least a human-readable extension specification and preferably by a | ||
| machine-readable specification as well. | ||
| JSON-based processors MUST process the <code>@context</code> <a>property</a> |
There was a problem hiding this comment.
Agree with the simplification here and moving the text to a paragraph below.
There was a problem hiding this comment.
I have just been designing the parser for our JSON implementation, and it seems to me that the only reason that I need to process the @context is to ensure that the terms (aliases that are used for URIs) in the body of the VC are pointed to by the @context values i.e. that no terms are present in the VC that are not pointed to by the @context values. Of course in our implementation a human will have read the contents of the @context web pages that are pointed to and will have configured the alias terms into our JSON parser so that it will be happy to encounter either the full URIs or the short form aliases.
It might be useful to tell JSON implementors that they do not need to define new @context values themselves, since they can use full URIs for all their new VC terms if they want to.
There was a problem hiding this comment.
I question whether it would be good to do this as this is not a common practice for HTTP APIs that use JSON (or JSON documents in general).
| JSON-based processors MUST process the <code>@context</code> <a>property</a> | ||
| to the extent of ensuring the expected values exist in the expected order for | ||
| the <a>credential</a> type being processed. | ||
|
|
There was a problem hiding this comment.
Why is the order of values important?
There was a problem hiding this comment.
JSON-LD typically works in a last-defined-wins model. There is a feature in JSON-LD 1.1, called @protected that works (more or less) in a first defined wins mode. So, order is important in both cases and if we enforce order, you don't need to use full blown JSON-LD processing if you just want to do a JSON-based processor.
| of values of the <code>@context</code> <a>property</a> should be defined by | ||
| at least a human-readable extension specification and preferably by a | ||
| machine-readable specification as well. | ||
| JSON-based processors MUST process the <code>@context</code> <a>property</a> |
There was a problem hiding this comment.
I have just been designing the parser for our JSON implementation, and it seems to me that the only reason that I need to process the @context is to ensure that the terms (aliases that are used for URIs) in the body of the VC are pointed to by the @context values i.e. that no terms are present in the VC that are not pointed to by the @context values. Of course in our implementation a human will have read the contents of the @context web pages that are pointed to and will have configured the alias terms into our JSON parser so that it will be happy to encounter either the full URIs or the short form aliases.
It might be useful to tell JSON implementors that they do not need to define new @context values themselves, since they can use full URIs for all their new VC terms if they want to.
| will use the specific mechanism provided and can verify that all terms are correctly | ||
| specified, JSON-based processors implicitly accept the same set of terms | ||
| without testing that they are correct. | ||
| </p> |
There was a problem hiding this comment.
If you expect JSON processors to check that the set of @context values are in the correct order, then why don't you expect JSON processors to check that all the terms in the VC are also defined by the @context? Only a human administrator can configure the JSON parser to check both of these. So why one without the other? Or have I misunderstood something?
There was a problem hiding this comment.
then why don't you expect JSON processors to check that all the terms in the VC are also defined by the @context?
Frankly, because a subset of JSON developers have said that they don't want to do that. Experience w/ schema.org demonstrates that most will happily just copy-paste examples and work from those.
In an ideal world, everyone would just point a JSON-LD processor at the document and hit a button... but there is non-trivial subset of developers that don't want the "burden" of running a JSON-LD processor on their content and would rather risk semantic non-interop than pull an extra library into their software stack (and in some cases, the library doesn't exist in their development environment). In any case, we're trying to make that subset of JSON implementers happy... the ones that don't want to be bothered by semantics (but we still have to make sure that we provide enough tooling for them to interop when it becomes important to them.
An editorial alternative to proposal #546, related to issue #491