search

w3c / json-ld-syntax

JSON-LD 1.1 Specification
https://w3c.github.io/json-ld-syntax/
Other
112 stars 22 forks source link

Inline metadata escaping #40

Closed hsolbrig closed 6 years ago

hsolbrig commented 6 years ago

This is the first of four options that were the result of the meeting on Aug 3, 2018.

Requirement: A way to annotate JSON-LD Context with information about when and how it was generated, its intended purpose, why little bits of cleverness are there and what they are intended to do, who to complain to, etc.

Additional notes and observations: 1) People need to do things of this sort. As an example, see the "comments" element in https://github.com/biolink/biolink-model/blob/master/context.jsonld and note its rather unwieldy formatting formatting. We cannot prohibit it -- we can only decide whether the solutions people arrive with are compatible with the basic specification and each other. 2) This is NOT intended to be a mechanism to add additional processing instructions. That is what the JSON-LD specification is for. 3) This is NOT intended to be yet another comment mechanism for JSON itself. This strictly applies to the JSON-LD context section and is intended to refer solely to its content.

Proposal: Specify an escape sequence (suggestion: '@@') that indicates that everything from there to the end of the line is not processed. Not only is this not processed, but formally state that JSON-LD compliant processing tools are neither required nor expected to preserve the escape sequence and whatever follows it. The annotation property exists solely to attach metadata to a particular instance of a particular bit of JSON-LD. JSON-LD users are warned that this information may (and will) disappear when undergoing any processing or transformation.

Also add a warning that the "@@" token has no special significance in JSON. A side effect of this bit is that, were one to read the example below into a JSON parser, one would loose everything except the last entry ("description: ...") which would sort of guarantee that it doesn't get out of hand.

Example use:

{
"@context": {
    "@@": "Auto generated from biolink-model.yaml by contextgen.py version: 0.0.2",
    "@@": "Generation date: 2018-07-10 09:37",
    "@@": "Schema: biolink model",
    "@@": "id: https://biolink.github.io/biolink-model/ontology/biolink.ttl",
    "@@": "description: Entity and association taxonomy and datamodel for life-sciences data",
    "@@": "license: https://creativecommons.org/publicdomain/zero/1.0/",
    "biolink": "http://bioentity.io/vocab/",
         ...
hsolbrig commented 6 years ago

Addendum:

The only burden that this approach places on JSON-LD processing tools is that they need to ignore the "@@" token.

gkellogg commented 6 years ago

In your example comments is actually not in the @context, it's in the body of the JSON-LD which includes @context. This could be handled by having a term definition for comments, to be something like rdfs:comment. Processors retrieving the document for retrieving a context will discard everything else.

Regarding @@:

everything from there to the end of the line is not processed.

This gets into the JSON processing model, so end-of-line is a problem. It would rather be that any value associated with the key @@ is discarded. In any case, the choice of @@ is somewhat arbitrary and rather non-intuitive, IMHO.

The more I see on this, the more I dislike the notion of trying to add a comment mechanism to the JSON-LD processing model. If necessary, it can be expressed in the body of the document, where it is either discarded, if associated with an unmapped term, or transformed, which might be appropriate for rdfs:comment.

azaroth42 commented 6 years ago

Administrative note that this is one of four proposals coming from the closure of #32.

hsolbrig commented 6 years ago

The everything for there to the end of the line was an error and not what I had intended. The intent, as shown in the example, was that it fell in the JSON processing model and was not meant to be a change. The problem with rdfs:comment is that it does have semantics in RDF space -- we need one (just one) reserve name that is ignored.

azaroth42 commented 6 years ago

WG consensus was to close all documentation issues as out of scope, but to revisit in the future as potential best practice rather than syntax concerns.

Further, for this issue, WG resolved that @@ as a keyword was identical to the already rejected @comment.

Resolutions: