This NOTE describes an extension to [[JSON-LD11]], [[JSON-LD11-API]], and [[JSON-LD11-FRAMING]] to allow arcs in a Linked Data Graph to be annotated using the [[RDFStar]] model.
This is an unofficial proposal.
[[[RDFStar]]] [[RDFStar]] addresses the problem of annotating arcs in a Linked Data Graph by extending the RDF data model [[RDF11-CONCEPTS]] to allow for triples to be used as the subject or object of another RDF triple. This note describes an update to the JSON-LD data model to allow limited form of a node object to use another node object as its node identifier.
The two popular graph-based data models have been RDF [[RDF11-CONCEPTS]] and Labeled-property Graphs, which are roughly similar, with the RDF model being more formal in identifying nodes, datatypes and relationships, while Property Graphs use a less formal relationship model somewhat similar to JSON. In both models, nodes are related via edges (AKA arcs), but in Property Graphs, those edges may themselves be annotated with properties. This is useful in providing additional metadata and semantics to relationships of the nodes.
Historically, in RDF, this can be simulated through Reification, where a triple is represented by another resource with properties for the subject, predicate, and object, which allows additional properties to be asserted on that reification node.
In [[RDFStar]], a triple may act as the subject or object in another triple, for example, we can modify how certain we are about a relationship as follows:
This NOTE explores an extension of JSON-LD which can allow the value of an `@id` property to be an embedded node, and the description of an annotation object which serves as a short-hand when the annotated value also is described directly in the graph.
A JSON-LD-star document complies with this specification if it follows the normative statements in . For convenience, normative statements for documents are often phrased as statements on the properties of the document.
This specification makes use of the following namespace prefixes:
These are used within this document as part of a compact IRI
as a shorthand for the resulting IRI, such as
used to represent
The Following terms are used within specific algorithms.
This specification adds the concepts of an embedded node and annotation object to JSON-LD in order to add the ability to make statements about individual triples in an RDF-star Graph.
An embedded node supports the ability to make one or more statements about a triple, represented by an embedded node, without that triple being necessarily considered to be part of the Linked Data Graph.
The following example shows how the value of `@id` can be an of embedded node, which expresses a single triple:
An annotation object supports the ability to make one or more statements (annotations) about a triple, where the triple is considered to be part of the Linked Data Graph.
JSON-LD allows many more sophisticated ways of describing data and both embedded nodes and annotation objects work along with these other features, to the extent that they are used in describing a single relationship.
JSON-LD allows the description of within node objects, either by defining a term using `@reverse`, or using `@reverse` directly within a node object.
An embedded node MUST NOT, itself, use a reverse property.
The relationships between nodes can be reversed even when those nodes use embedded objects:
Annotations may themselves use reverse properties, in which case the annotated triple will be the subject (instead of the object) of the annotation:
[[RDFstar]] allows embedded triples to contain other embedded triples, recursively. Similarly, an embedded node may be made up of other embedded nodes, and annotations may be made upon embedded nodes.
Annotation objects and embedded nodes can be used together. As well, annotation objects can be used to annotate embedded nodes (see ), embedded nodes may be used within annotation objects, and annotation objects may be used to annotate annotations. However, the grammar prevents embedded nodes from including annotation objects.
While it is beyond the scope of this document to discuss use cases for these scenarios, it is an important notion of regularity of expression, which is shared by formats such as Turtle-star.
Consider the following examples:
More examples can be found in the [[[JSON-LD-star-tests]]].
The JSON-LD Data Model is extended consistent with [[RDFStar]]:
Embedded Nodes can be considered as reified triples.
Align with [[RDFStar]].
The is extended as follows:
This specification extends the algorithms from [[[JSON-LD11-API]]] [[JSON-LD11-API]] to support the addition of embedded nodes and annotation objects.
The following algorithm extensions require that the rdfstar flag be set.
The algorithm has minor updates to allow for an embedded node to be used as the value of `@id`, and to allow and validate the special requirements for annotation objects.
Expansion does not change annotations into embedded nodes, neither does it reverse node relationships. This is performed by other algorithms.
Before step 220.127.116.11, and changing 18.104.22.168 to be an "Otherwise, if", add the following steps:
After step 13.4.14 add the following step:
Step 15.1 extends the set of allowed entries to include `@annotation`.
Before step 18 add the following step:
The Compaction Algorithm has minor updates to allow for an embedded node to be used as the value of `@id`, and to allow embedded nodes and annotation objects. Values that might otherwise be serialized as a string must stay as a map if they contain an annotation object.
Step 7 is updated to exclude elements haveing an `@annotation` entry.
After step 12.1.1, add the following steps:
The flattening algorithms are updated to allow the use of embedded nodes, and to turn annotation objects into embedded nodes.
There is a new Create Annotations Algorithm optionally invoked using the createAnnotations API flag, which will re-create most annotation objects within a node map.
The main changes to the Flattening Algorithm is to move the blank node regeneration to a single recursive step run prior to running the Node Map Generation algorithm. This is required to consistently regenerate blank node identifiers used within embedded nodes, which are otherwise untouched by the algorithm.
Before step 2 add the following step:
Before step 3 add the following step:
Node Map Generation Algorithm has significant updates due to the requirements of unfolding annotation objects into embedded nodes and representing embedded nodes as keys in the node map. Also, some assumptions are made in the original algorithm that the active subject being a map implies a reverse relationship, which is no longer the case when an embedded node may be the active subject.
Principle changes include the following:
A new optional parameter reverse is added defaulting to `false`.
In step 2, when referencing the active subject entry of graph, if active subject is a map, index using the canonical lexical form of active subject. Additionally, do use `null` if reverse is `false`.
Before step 4.1.1, ad the following steps:
Replace 6.3 and 6.4 with the following steps:
@idwhose value is id.
Change the condition for step 6.5 to check the reverse parameter for `true` rather than if active subject is a map.
Before step 6.8, ad the following steps:
Update step 22.214.171.124.1 to include a reverse parameter with the value `true`.
This algorithm use used to comprehensively rename the blank node identifiers used within a map by recursively visiting each element of the map.
This will change the naming of renamed blank nodes used in existing tests. As indicated in the JSON-LD Test Suite:
When comparing documents after flattening, framing or generating RDF, blank node identifiers may not be predictable.
One way to do this is to transform both the generated results and the expected results into an RDF Dataset and perform a blank node bijection (as described for RDF Dataset Isomorphsim) and then use the resulting bijection to rename the blank nodes in the result based on those that are expected.
The algorithm takes a single input variable element and returns a representation of that element with blank node identifiers remapped.
This algorithm is used to find entries in a node map where the key is a canonicalized embedded node and that embedded node exists in non-embedded form in the node map and move them to be annotation objects under that node. This effectively reverses the process of unfolding annotation objects performed in . It is also used in .
The algorithm takes a single input variable node map and updates it in place.
The RDF transformation algorithms have minimal changes to allow emit and consume RDF-star triples.
The Deserialize JSON-LD to RDF Algorithm has minimal changes to allow an embedded triple to be used as the subject or object of an RDF-star triple, and to use annotation objects, where appropriate.
After step 1.3.1 add the following step:
The Object to RDF algorithm has a minimal update to allow a serialized embedded node to be transformed into an RDF-star triple by invoking the Deserialize JSON-LD to RDF Algorithm recursively.
The first argument MAY be an embedded node in canonical lexical form.
Before Step 4 add the following steps:
The Serialize RDF as JSON-LD Algorithm algorithm has updates to transform RDF-star triples used as the subject or object of another triple to be used as the index into a node map and represented as embedded nodes.
Change step 5.7.1 to the following steps:
@idwhose value is set to embedded subject.
@idwhose value is set to subject.
Before step 5.7.4, add the following steps:
@idwhose value is set to embedded object.
After step 6.4, add the following steps:
The RDF to Object Conversion algorithm has updates to transform RDF-star triples into an embedded node.
Before step 2, add the following steps: