Annotation mode

[gkellogg]

The current version of the spec extends the potential value of @id to allow an object value, which is treated as an embedded triple, so the value is treated as a node object that can assert a single triple. For example:

{
  "@context": {
    "@base": "http://example.org/",
    "ex": "http://example.org/",
    "foaf": "http://xmlns.com/foaf/0.1/"
  },
  "@id": {
    "@id": "bob",
    "foaf:age": 23
  },
  "ex:certainty": 0.8
}

This is analogous to the Turtle* representation using an embedded triple:

@base <http://example.org/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix ex: <> .

<<:bob foaf:age 23>> ex:certainty 0.8 .

Work in the RDF* group has bifurcated syntax to support PG and SA modes separately, and the above example would be compatible with a Separate Assertion, where the the <<:bob foaf:age 23>> is not, itself, asserted in the graph. Turtle* (and SPARQL*) now support an annotation mode, where the triple can be both asserted and annotated in a single view:

:bob foaf:age 23 {| ex:certainty 0.8 |}.

In the past, we discussed adding an @object keyword, which IIRC would have looked something like the following:

{
  "@context": {
    "@base": "http://example.org/",
    "ex": "http://example.org/",
    "foaf": "http://xmlns.com/foaf/0.1/"
  },
  "@id": "bob",
  "foaf:age": {
    "ex:certainty": 0.8,
    "@object": 23
  }
}

While this seems to share more character with Gremlin syntax, placing the annotation in the middle of the relationship, it is at odds with Turtle*'s annotation syntax. An alternative might look something like the following:

{
  "@context": {
    "@base": "http://example.org/",
    "ex": "http://example.org/",
    "foaf": "http://xmlns.com/foaf/0.1/"
  },
  "@id": "bob",
  "foaf:age": {
    "@value": 23,
    "@annotation": {
      "ex:certainty": 0.8
    }
  }
}

The restrictions might be the following:

• The value of @annotation is interpreted as a node object and must not include an @id.
• It may be used as part of a value object, or a node object who's sole property is @id.
• Within an annotation, values may, themselves have annotations and the annotated @id may use the embedded syntax.

[pchampin]

this seems to share more character with Gremlin syntax

I would actually argue the opposite!
First, nothing prevents you from putting the @object key before the other keys.
Second, if the keys were serialized in lexicographical order (which some serializers do), @object will appear before "normal" keys (starting with a letter), while @annotation would appear before @value. 😛

Teasing apart, I agree that the @annotation is less disruptive of the normal structure of the graph in plain JSON-LD, so that's on the plus side for this proposal.

[@annotation] may be used as part of a value object, or a node object who's sole property is @id.

I think it is a shame to restrict annotated node objects that way. Consider the following Turtle*:

   :alice :knows [ :name "Bob"; :age 42 ] {| :since 2017 |}.

I would like to have the same ease of use in JSON-LD*:

{ "@context": "...",
  "@id": "#alice",
  "knows": {
    "name": "Bob",
    "age": 42,
    "@annotation": { "since": 2017 }
  }
}

However, this JSON-LD* could easily be misinterpreted as:

   :alice :knows [ :name "Bob"; :age 42 {| :since 2017 |} ].

Moving the @annotation key at the bottom of the object would mitigate that issue, but stil...

For this, the @objectproposal would be less misleading:

{ "@context": "...",
  "@id": "#alice",
  "knows": {
    "since": 2017,
    "@object": {
        "name": "Bob",
        "age": 42,
    }
  }
}

[pchampin]

Also, if we allow multiple attributes in annotated node objects (regardless of the @annotation vs. @object choice), we must carefully restrict which the node objects can contain @annotation/@object: it must not be the root object of the JSON-LD document, nor the value (directly or through an array) of a keyword. E.g., it would make no sense to annotate the node object in @graph, @included or @id (as extended of JSON-LD*).

For @list and @set, this could be allowed, but the annotated triple would be subtly different depending on the keyword (S P O for @set, Bnode rdf:first O for @list) so the added value is probably not worth the confusion this might generate.

[gkellogg]

I would actually argue the opposite!
First, nothing prevents you from putting the @object key before the other keys.
Second, if the keys were serialized in lexicographical order (which some serializers do), @object will appear before "normal" keys (starting with a letter), while @annotation would appear before @value. 😛

I guess my point was not on key ordering, but object embedding. In the @object case, you have a node object which identifies the subject, the property references another node object, which is the annotation, and it, in turn, uses @object to reference the value. In this case, it's more like subject [predicate] => [annotation} => object rather than subject [predicate] => object [annotation]

[gkellogg]

[@annotation] may be used as part of a value object, or a node object who's sole property is @id.

I think it is a shame to restrict annotated node objects that way. Consider the following Turtle*:

   :alice :knows [ :name "Bob"; :age 42 ] {| :since 2017 |}.

RDF* supports the annotation of a single triple, not multiple triples, but the annotation may, of course, make several statements, including using other annotations or embedded triples. In that sense, in my original thinking, you can only use @annotation on a value object, or a node reference.

Of course, we could consider using @annotation on a node object, in which case it does just annotate the triple with subject of the node object it contains, which I think is reasonable. That would allow you to state your example, with the added benefit of annotating an IRI object, that was also the subject of other triples described in that node object.

[gkellogg]

Also, if we allow multiple attributes in annotated node objects (regardless of the @annotation vs. @object choice), we must carefully restrict which the node objects can contain @annotation/@object: it must not be the root object of the JSON-LD document, nor the value (directly or through an array) of a keyword. E.g., it would make no sense to annotate the node object in @graph, @included or @id (as extended of JSON-LD*).

I think we should chose one direction or the other, and not both, unless there is strong evidence that both are necessary. My intention is to write up each, including the algorithm updates, and then we can "vote" on what makes the most sense.

[pchampin]

I was not suggesting to support both @object and @annotation, sorry if that wasn't clear.

[gkellogg]

This seems settled now, so I think we can close this.

[pchampin]

Agreed