Copyright © 2012-2023 the Contributors to the JSON-LD Connect 1.0 Specification, published by the Linking Data in JSON Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.
JSON-LD Connect is a way of turning a JSON-LD document into a live graph of interconnected and indexed objects.
This specification was published by the Linking Data in JSON Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.
This document is an experimental work in progress.
A JSON-LD document is a representation of a directed graph. A single directed graph can have many different serializations, each expressing exactly the same information. Developers wanting to work with interconnected JSON objects, can use the connect algorithm described here to "stich together" node definitions and creating an index of important values mapped to each node. This enables navigation between node definitions via interlinking keys (representing arcs in graph nomenclature).
Technically, connect works by replacing each node reference in the input data with a real, programmatic object reference, to one, merged node definition. This results in the creation of a simple in-memory graph.
Out of the box, the connect process creates an index mapping node
@id
values to the node definition. It is also
possible to configure the process to create additional indexes, as well as
adding a local reverse key map to each node definition.
This document is a detailed specification for Linked Data in JSON. The document is primarily intended for the following audiences:
To understand the basics in this specification you must first be familiar with JSON, which is detailed in [RFC4627]. You must also understand the JSON-LD Syntax [json-ld], which is the base syntax used by all of the algorithms in this document, and the JSON-LD API [JSON-LD-API]. To understand the API and how it is intended to operate in a programming environment, it is useful to have working knowledge of the JavaScript programming language [ECMA-262] and WebIDL [WEBIDL]. To understand how JSON-LD maps to RDF, it is helpful to be familiar with the basic RDF concepts [RDF-CONCEPTS].
The intent of the Working Group and the Editors of this specification is to eventually align terminology used in this document with the terminology used in the RDF Concepts document to the extent to which it makes sense to do so. In general, if there is an analogue to terminology used in this document in the RDF Concepts document, the preference is to use the terminology in the RDF Concepts document.
The following is an explanation of the general terminology used in this document:
@value
,
@list
or @set
and it has one or more keys
other than @id
.@id
key._:
.There are a number of ways that one may participate in the development of this specification:
The algorithm described in this section is intended to operate on language-native data structures. That is, the serialization to a text-based JSON document isn't required as input or output, and language-native data structures MUST be used where applicable.
@rev
All JSON-LD tokens and keywords are case-sensitive.
Connecting is the process of turning an input JSON-LD document into an interconnected and indexed data structure.
Create an idMap
and a typeMap
, being the
map of result objects and type map of the
connected output respectively.
For each object, do the following series of steps:
@id
,
find an existing object indexed by that id from the idMap
. If
one is found, use that as the current result object.
@id
, add the result object
under that key to the idMap
.
@type
, and the current
object has no key whose resolved meaning is @value
, get or
add an array for the type value in the typeMap
. Append the
result object to that array.
If the @rev
flag is used, pass the current key (called reverse
link) and current object (called linking object) to each recursive call in
the process above. At the end of the process, get or create a
revMap from the current object. Get or create a list for the
reverse link key from the revMap, and append the linking object to that.
Then set that revMap on the current object.
The resulting idMap
and typeMap
are added to the
final connected output.
This algorithm is a work in progress. It is currently undefined whether the creation of typeMaps and revMaps should be optional. It is also still undefined which keys will label these in the connected output.
The JSON-LD processor interface is the high-level programming structure that developers use to access the JSON-LD transformation methods. The definition below is an experimental extension of the interface defined in the [JSON-LD-API].
The JSON-LD API signatures are the same across all programming languages. Due
to the fact that asynchronous programming is uncommon in certain languages, developers MAY
implement processor with a synchronous interface instead. In that case, the callback
parameter MUST NOT be included and the result MUST be returned as return value instead.
input
according
to the steps in the
Connect Algorithm. The input
is used to build the connected output and is returned if there are no errors.
Exceptions MUST be thrown if there are errors.
input
when expanding the input
.input
.The JsonLdCallback is used to return a processed JSON-LD representation as the result of processing an API method.
See JsonLdCallback definition in [JSON-LD-API].
This section describes datatype definitions used within the JSON-LD API.
The JsonLdOptions type is used to convert a set of options to an interface method.
See JsonLdOptions definition in [JSON-LD-API].
A large amount of thanks goes out to the JSON-LD Community Group participants who worked through many of the technical issues on the mailing list and the weekly telecons. Of special mention are Manu Sporny, Dave Longley, Gregg Kellogg, Markus Lanthaler, François Daoust, and Zdenko 'Denny' Vrandečić. The editors would like to thank Mark Birbeck, who provided a great deal of the initial push behind the JSON-LD work via his work on RDFj. The work of Dave Lehn and Mike Johnson are appreciated for reviewing, and performing several implementations of the specification. Ian Davis is thanked for this work on RDF/JSON. Thanks also to Nathan Rixham, Bradley P. Allen, Kingsley Idehen, Glenn McDonald, Alexandre Passant, Danny Ayers, Ted Thibodeau Jr., Olivier Grisel, Josh Mandel, Eric Prud'hommeaux, David Wood, Guus Schreiber, Pat Hayes, Sandro Hawke, and Richard Cyganiak for their input on the specification.