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.
In the JSON serialization,
an array structure is represented as square brackets surrounding zero or more values.
Values are separated by commas.
In the internal representation,
a list (also called an array) is an ordered collection of zero or more values.
While JSON-LD uses the same array representation as JSON,
the collection is unordered by default.
While order is preserved in regular JSON arrays,
it is not in regular JSON-LD arrays unless specifically defined
(see the Sets and Lists section of JSON-LD 1.1.
In the JSON serialization,
an object structure
is represented as a pair of curly brackets surrounding zero or more name/value pairs (or members).
A name is a string.
A single colon comes after each name,
separating the name from the value.
A single comma separates a value from a following name.
In JSON-LD the names in an object must be unique.
The use of the null value within JSON-LD
is used to ignore or reset values.
A map entry in the @context where the value,
or the @id of the value, is null,
explicitly decouples a term's association with an IRI.
A map entry in the body of a JSON-LD document
whose value is null
has the same meaning as if the map entry was not defined.
If @value, @list, or @set is set to null in expanded form,
then the entire JSON object is ignored.
In the JSON serialization, a number
is similar to that used in most programming languages,
except that the octal and hexadecimal formats are not used and that leading zeros are not allowed.
In the internal representation,
a number is equivalent to either a long
or double,
depending on if the number has a non-zero fractional part (see [WEBIDL]).
A string
is a sequence of zero or more Unicode (UTF-8) characters,
wrapped in double quotes, using backslash escapes (if necessary).
A character is represented as a single character string.
A relative IRI reference is an IRI reference that is relative to some other IRI,
typically the base IRI of the document.
Note that properties,
values of @type,
and values of terms defined to be vocabulary relative
are resolved relative to the vocabulary mapping,
not the base IRI.
A node in a graph that is neither an IRI,
nor a literal.
A blank node does not contain
a de-referenceable identifier because it is either ephemeral in nature
or does not contain information that needs to be linked to from outside of the linked data graph.
In JSON-LD,
a blank node is assigned an identifier starting with the prefix _:.
A blank node identifier
is a string that can be used as an identifier for a blank node within the scope of a JSON-LD document.
Blank node identifiers begin with _:.
An object expressed as a value such as a string or number.
Implicitly or explicitly includes a datatype IRI and, if the datatype is rdf:langString, an optional language tag.
The base direction is the direction used when a string does not have a direction associated with it directly.
It can be set in the context using the @direction key
whose value must be one of the strings "ltr", "rtl", or null.
See the Context Definitions section of JSON-LD 1.1 for a normative description.
A compact IRI has the form of prefix:suffix
and is used as a way of expressing an IRI without needing to define separate term definitions
for each IRI contained within a common vocabulary identified by prefix.
The default language is the language used when a string does not have a language associated with it directly.
It can be set in the context using the @language key
whose value must be a string representing a [BCP47] language code or null.
See the Context Definitions section of JSON-LD 1.1 for a normative description.
An expanded term definition is a term definition
where the value is a map
containing one or more keyword keys to define the associated IRI,
if this is a reverse property,
the type associated with string values, and a container mapping.
See the Expanded Term Definition section of JSON-LD 1.1 for a normative description.
A JSON-LD document,
which describes the form for transforming another JSON-LD document
using matching and embedding rules.
A frame document allows additional keywords and certain map entries
to describe the matching and transforming process.
A frame object is a map element within a frame
which represents a specific portion of the frame matching either
a node object or a value object
in the input.
See the Frame Objects section of JSON-LD 1.1 for a normative description.
An id map is a map value of a term
defined with @container set to @id.
The values of the id map must be node objects,
and its keys are interpreted as IRIs representing
the @id of the associated node object.
If a value in the id map contains a key expanding to @id,
its value must be equivalent to the referencing key in the id map.
See the Id Maps section of JSON-LD 1.1 for a normative description.
A JSON literal is a literal where the associated datatype IRI is rdf:JSON.
In the value object representation, the value of @type is @json.
JSON literals represent values which are valid JSON [RFC8259].
See the The rdf:JSON Datatype section in JSON-LD 1.1 for a normative description.
The JSON-LD internal representation
is the result of transforming a JSON syntactic structure
into the core data structures suitable for direct processing:
arrays, maps, strings, numbers, booleans, and null.
A JSON-LD Processor is a system which can perform the algorithms defined in JSON-LD 1.1 Processing Algorithms and API.
See the Conformance section in JSON-LD 1.1 API for a formal description.
A string that is specific to JSON-LD,
described in the Syntax Tokens and Keywords section of JSON-LD 1.1,
and normatively specified in the Keywords section of JSON-LD 1.1,
A language map is a map value of a term
defined with @container set to @language,
whose keys must be strings representing [BCP47] language codes
and the values must be any of the following types:
null,
string, or
an array of zero or more of the above possibilities.
See the Language Maps section of JSON-LD 1.1 for a normative description.
A list object is a map that has a @list key.
It may also have an @index key, but no other entries.
See the Lists and Sets section of JSON-LD 1.1 for a normative description.
A prefix is the first component of a compact IRI
which comes from a term that maps to a string that,
when prepended to the suffix of the compact IRI,
results in an IRI.
The processing mode defines how a JSON-LD document is processed.
By default, all documents are assumed to be conformant with this specification.
By defining a different version using the @versionentry in a context,
publishers can ensure that processors conformant with JSON-LD 1.0 [JSON-LD]
will not accidentally process JSON-LD 1.1 documents, possibly creating a different output.
The API provides an option for setting the processing mode to json-ld-1.0,
which will prevent JSON-LD 1.1 features from being activated,
or error if @versionentry in a context is explicitly set to 1.1.
This specification extends JSON-LD 1.0
via the json-ld-1.1processing mode.
A set object is a map that has an @setentry.
It may also have an @index key, but no other entries.
See the Lists and Sets section of JSON-LD 1.1 for a normative description.
A term definition is an entry in a context,
where the key defines a term
which may be used within a map
as a key, type, or elsewhere that a string is interpreted as a vocabulary item.
Its value is either a string (simple term definition),
expanding to an IRI,
or a map (expanded term definition).
A type map is a map value of a term
defined with @container set to @type,
whose keys are interpreted as IRIs
representing the @type of the associated node object;
the value must be a node object, or array of node objects.
If the value contains a term expanding to @type,
its values are merged with the map value when expanding.
See the Type Maps section of JSON-LD 1.1 for a normative description.
The vocabulary mapping is set in the context using the @vocab key
whose value must be an IRI, a compact IRI, a term, or null.
See the Context Definitions section of JSON-LD 1.1 for a normative description.
The currently active property or keyword that the processor should use when processing.
The active property is represented in the original lexical form,
which is used for finding coercion mappings in the active context.
Used as a macro within various algorithms as a way to add a value
to an entry in a map (object) using a specified key.
The invocation may include an as array flag defaulting to false.
If as array is true
and the value of key in object does not exist
or is not an array, set it to a new array
containing any original value.
If value is an array,
then for each element v in value,
use add value recursively to add v to key in entry.
Otherwise:
If key is not an entry in object,
add value as the value of key in object.
Otherwise
If the value of the keyentry in object is not an array,
set it to a new array containing the original value.
Append value
to the value of the keyentry in object.
Used as a macro within various algorithms as to reduce the language used to describe
the process of compacting a stringvar representing an IRI or keyword
using an active context either specified directly, or coming from the scope of
the algorithm step using this term.
An optional value is used, if explicitly provided.
Unless specified, the vocab flag defaults to true,
and the reverse flag defaults to false.
Return the result of using the IRI Compaction algorithm,
passing active context,
var,
value (if supplied),
vocab,
and result.
Used as a macro within various algorithms as to reduce the language used to describe
the process of expanding a stringvalue representing an IRI or keyword
using an active context either specified directly, or coming from the scope of
the algorithm step using this term.
Optional defined and local context arguments are used, if explicitly provided.
Unless specified,
the document relative flag defaults to false,
and the vocab flag defaults to true.
Return the result of using the IRI Expansion algorithm,
passing active context,
value,
local context (if supplied),
defined (if supplied),
document relative,
and vocab.
A flag specifying that all properties present in the input frame
must either have a default value
or be present in the JSON-LD input
for the frame to match.
2. Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, and MUST NOT in this document
are to be interpreted as described in
BCP 14
[RFC2119] [RFC8174]
when, and only when, they appear in all capitals, as shown here.
A JSON-LD-star document complies with this specification if it follows
the normative statements in § 7. Grammar Extensions.
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:
Prefix
IRI
ex
http://example.org/
rdf
http://www.w3.org/1999/02/22-rdf-syntax-ns#
xsd
http://www.w3.org/2001/XMLSchema#
These are used within this document as part of a compact IRI
as a shorthand for the resulting IRI, such as dcterms:title
used to represent http://purl.org/dc/terms/title.
3. JSON-LD-star-specific Terms
This section is non-normative.
The Following terms are used within specific algorithms.
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:
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.
5.1 Reverse Properties
This section is non-normative.
JSON-LD allows the description of JSON-LD 1.1
within node objects, either by defining a term using @reverse, or using
@reverse directly within a node object.
An embedded nodeMUST 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:
5.2 Deep Embedding
This section is non-normative.
[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.
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.
The restrictions on @id are identical to those of a node object.
An embedded nodeMUST NOT contain any of the following keywords (or alias of such a keywords):
@included, or @graph.
If the embedded node contains @type (or an alias), it MUST have a single value
and the node MUST NOT contain any other non-keyword entries.
If the embedded node does not contain @type (or an alias),
it MUST have another entry (aside from @id) which describes a relationship,
such as an IRI, @reverse having a single value, or @nest which ultimately
resolves to a single property/value relationship.
The following algorithm extensions require that the rdfstar flag be set.
8.1 Expansion Algorithm
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.
Note
Expansion does not change annotations into embedded nodes,
neither does it reverse node relationships.
This is performed by other algorithms.
Before step 13.4.3.1, and changing 13.4.3.1 to be an "Otherwise, if",
add the following steps:
If the rdfstar flag is not set,
and active property is @annotation,
an invalid annotation error has been detected and processing is aborted.
If value is a non-empty map and
the rdfstar flag is set,
set expanded value to the result of using this algorithm recursively
passing active context, null for active property,
value for element, base URL,
and the frameExpansion and ordered flags.
The resulting expanded value MUST BE a valid embedded node, otherwise,
an invalid embedded node error has been detected and processing is aborted.
After step 13.4.14 add the following step:
If expanded property is `@annotation:
Continue with the next key from element if the rdfstar flag is not set.
Set expanded value to the result of using this algorithm recursively
passing active context, @annotation for active property,
value for element, base URL,
and the frameExpansion and ordered flags.
Step 15.1 extends the set of allowed entries to include @annotation.
If result contains the entry@annotation
all associated values MUST BE annotation objects, otherwise,
an invalid annotation error has been detected and processing is aborted.
Additionally, if there is no active property,
or active property is @graph or @included,
the annotation appears in an inappropriate location and
an invalid annotation error has been detected and processing is aborted.
Step 7 is updated to exclude elements haveing an @annotationentry.
After step 12.1.1, add the following steps:
Otherwise, if expanded value is an embedded node,
initialize compacted value with the result of calling
this algorithm, recursively,
passing active context,
null for active property,
expanded value for element,
and the compactArrays and ordered flags.
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.
A new argument reverse is introduced which is
passed when processing an @reversemap.
If an @annotation key is encountered, it creates an
embedded node based on the active subject and
the map containing the @annotation key which is used
in a recursive invokation of this algorithm on the
contents of the annotation object.
A new optional parameter reverse is added defaulting to false.
In step 2, when referencing the active subjectentry
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:
If element has an @annotation entry:
Initialize annotation subject as a new
map with an entry for @id taken from active subject.
If active subject is a node reference,
use value of @id from active subject.
Add an entry for active property with the value
an array containing element,
after removing the @annotation value from element.
Initialize annotation as an array containing the values
from the @annotation entry in element adding
an @id entry to each with the value annotation subject.
Recursively call this algorithm passing annotation for element,
node map, and active graph.
Add an entry for active property
with the value from active subject.
If active subject is a node reference,
use value of @id from active subject.
Otherwise:
Add an entry for @id taken from active subject.
If active subject is a node reference,
use value of @id from active subject.
Add an entry for active property
with the value id.
Initialize annotation as an array containing the values
from the @annotation entry in element adding
an @id entry to each with the value annotation subject.
Recursively call this algorithm passing annotation for element,
node map, and active graph.
Update step 6.9.3.1.1 to include a reverse
parameter with the value true.
8.3.3 Rename Blank Nodes
This algorithm use used to comprehensively rename the blank node identifiers
used within a map by recursively visiting each element of the map.
Note
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.
Transform item into a map by deserializing
item as JSON.
Invoke the Object to RDF Algorithm
passing a new map with the entry @default and
value a new map with a new entry using
the value of @id from entry as key and entry
as value. If the value of @id is not a string,
use the canonical lexical form
as the key.
Set subject index to the result of using
the canonical lexical form
of embedded subject.
If node map does not have a subject indexentry,
create one and initialize its value to a new map
consisting of a single entry@id whose value is
set to embedded subject.
Otherwise, if node map does not have a subjectentry,
create one and initialize its value to a new map
consisting of a single entry@id whose value is
set to subject.
If node map does not have an object indexentry,
create one and initialize its value to a new map
consisting of a single entry@id whose value is
set to embedded object.
After step 6.4, add the following steps:
Update graph object in graph map
by invoking the
Create Annotations Algorithm
passing graph object for node map.
Create a new mapembedded node
with the entry@id whose value
is the result of calling this algorithm, recursively,
passing the subject from value.
If the predicate from value is rdf:type,
and the useRdfType flag is not true,
add an entry for @type whose value
is an array containing the object from value.
Otherwise, add an entry for predicate whose value
is an array containing the result of calling this algorithm,
recursively,
passing the object from value.