This document is also available in this non-normative format: diff to previous version .
This document is licensed under a Creative Commons Attribution 3.0 License .
JSON [ RFC4627 ] has proven to be a highly useful object serialization and messaging format. JSON-LD [ JSON-LD ] harmonizes the representation of Linked Data in JSON by outlining a common JSON representation format for expressing directed graphs; mixing both Linked Data and non-Linked Data in a single document. This document outlines an Application Programming Interface and a set of algorithms for programmatically transforming JSON-LD documents.
This document is merely a public working draft of a potential specification. It has no official standing of any kind and does not represent the support or consensus of any standards organisation.
This document is an experimental work in progress.
JSON,
as
specified
in
[
RFC4627
],
is
a
simple
language
for
representing
data
on
the
Web.
Linked
Data
is
a
technique
for
creating
a
graph
of
interlinked
data
across
different
documents
or
Web
sites.
Data
entities
are
described
using
IRI
s,
which
are
typically
dereferencable
and
thus
may
be
used
to
find
more
information
about
an
entity,
creating
a
"Web
"Web
of
Knowledge".
Knowledge".
JSON-LD
is
intended
to
be
a
simple
publishing
method
for
expressing
not
only
Linked
Data
in
JSON,
but
also
for
adding
semantics
to
existing
JSON.
JSON-LD is designed as a light-weight syntax that can be used to express Linked Data. It is primarily intended to be a way to use Linked Data in Javascript and other Web-based programming environments. It is also useful when building interoperable Web services and when storing Linked Data in JSON-based document storage engines. It is practical and designed to be as simple as possible, utilizing the large number of JSON parsers and libraries available today. It is designed to be able to express key-value pairs, RDF data, RDFa [ RDFA-CORE ] data, Microformats [ MICROFORMATS ] data, and Microdata [ MICRODATA ]. That is, it supports every major Web-based structured data model in use today.
The syntax does not necessarily require applications to change their JSON, but allows to easily add meaning by adding context in a way that is either in-band or out-of-band. The syntax is designed to not disturb already deployed systems running on JSON, but provide a smooth upgrade path from JSON to JSON with added semantics. Finally, the format is intended to be easy to parse, efficient to generate, convertible to RDF in one pass, and require a very small memory footprint in order to operate.
This document is a detailed specification for a serialization of 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. 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 ].
Examples may contain references to existing vocabularies and use prefix es to refer to Web Vocabularies. The following is a list of all vocabularies and their prefix abbreviations, as used in this document:
dc
,
e.g.,
dc:title
)
foaf
,
e.g.,
foaf:knows
)
rdf
,
e.g.,
rdf:type
)
xsd
,
e.g.,
xsd:integer
)
JSON [ RFC4627 ] defines several terms which are used throughout this document:
The following definition for Linked Data is the one that will be used for this specification.
Note that the definition for Linked Data above is silent on the topic of unlabeled nodes. Unlabeled nodes are not considered Linked Data . However, this specification allows for the expression of unlabled nodes, as most graph-based data sets on the Web contain a number of associated nodes that are not named and thus are not directly de-referenceable.
There are a number of ways that one may participate in the development of this specification:
This API provides a clean mechanism that enables developers to convert JSON-LD data into a a variety of output formats that are easier to work with in various programming languages. If a JSON-LD API is provided in a programming environment, the entirety of the following API must be implemented.
[NoInterfaceObject]
interface JsonLdProcessor {
object expand (object input, optional object? context) raises (InvalidContext);
object compact (object input, optional object? context) raises (InvalidContext, ProcessingError);
object frame (object input, object frame, object options) raises (InvalidFrame);
object normalize (object input, optional object? context) raises (InvalidContext);
object triples (object input, JsonLdTripleCallback tripleCallback, optional object? context) raises (InvalidContext);
};
compact
input
according
to
the
steps
in
the
Compaction
Algorithm
.
The
input
must
be
copied,
compacted
and
returned
if
there
are
no
errors.
If
the
compaction
fails,
an
appropirate
exception
must
be
thrown.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| input |
object
|
|
|
The JSON-LD object to perform compaction on. |
| context |
object
|
|
|
The
base
context
to
use
when
compacting
the
input
.
|
| Exception | Description | ||||
|---|---|---|---|---|---|
| InvalidContext |
|
||||
| ProcessingError |
|
object
expand
input
according
to
the
steps
in
the
Expansion
Algorithm
.
The
input
must
be
copied,
expanded
and
returned
if
there
are
no
errors.
If
the
expansion
fails,
an
appropriate
exception
must
be
thrown.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| input |
object
|
|
|
The JSON-LD object to copy and perform the expansion upon. |
| context |
object
|
|
|
An
external
context
to
use
additionally
to
the
context
embedded
in
input
when
expanding
the
input
.
|
| Exception | Description | ||||
|---|---|---|---|---|---|
| InvalidContext |
|
object
frame
input
using
the
frame
according
to
the
steps
in
the
Framing
Algorithm
.
The
input
is
used
to
build
the
framed
output
and
is
returned
if
there
are
no
errors.
If
there
are
no
matches
for
the
frame,
null
must
be
returned.
Exceptions
must
be
thrown
if
there
are
errors.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| input |
object
|
|
|
The JSON-LD object to perform framing on. |
| frame |
object
|
|
|
The frame to use when re-arranging the data. |
| options |
object
|
|
|
A set of options that will affect the framing algorithm. |
| Exception | Description | ||||
|---|---|---|---|---|---|
| InvalidFrame |
|
object
normalize
input
according
to
the
steps
in
the
Normalization
Algorithm
.
The
input
must
be
copied,
normalized
and
returned
if
there
are
no
errors.
If
the
compaction
fails,
null
must
be
returned.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| input |
object
|
|
|
The JSON-LD object to perform normalization upon. |
| context |
object
|
|
|
An
external
context
to
use
additionally
to
the
context
embedded
in
input
when
expanding
the
input
.
|
| Exception | Description | ||||
|---|---|---|---|---|---|
| InvalidContext |
|
object
triples
input
according
to
the
RDF
Conversion
Algorithm
,
calling
the
provided
tripleCallback
for
each
triple
generated.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| input |
object
|
|
|
The JSON-LD object to process when outputting triples. |
| tripleCallback |
|
|
|
A
callback
that
is
called
whenever
a
processing
error
occurs
on
the
given
input
.
This
callback
should
be
aligned
with
the
RDF
API.
|
| context |
object
|
|
|
An
external
context
to
use
additionally
to
the
context
embedded
in
input
when
expanding
the
input
.
|
| Exception | Description | ||||
|---|---|---|---|---|---|
| InvalidContext |
|
object
The
JsonLdTripleCallback
is
called
whenever
the
processor
generates
a
triple
during
the
triple()
call.
[NoInterfaceObject Callback]
interface JsonLdTripleCallback {
void triple (DOMString subject, DOMString property, DOMString objectType, DOMString object, DOMString? datatype, DOMString? language);
};
triple
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| subject |
DOMString
|
|
|
The subject IRI that is associated with the triple. |
| property |
DOMString
|
|
|
The property IRI that is associated with the triple. |
| objectType |
DOMString
|
|
|
The
type
of
object
that
is
associated
with
the
triple.
Valid
values
are
IRI
and
literal
.
|
| object |
DOMString
|
|
|
The object value associated with the subject and the property. |
| datatype |
DOMString
|
|
|
The datatype associated with the object. |
| language |
DOMString
|
|
|
The language associated with the object in BCP47 format. |
void
All algorithms described in this section are 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 to any of these algorithms and language-native data structures must be used where applicable.
JSON-LD specifies a number of syntax tokens and keywords that are using in all algorithms described in this section:
@context
@base
@vocab
@coerce
@literal
@iri
@language
@datatype
:
@subject
@type
@context
keyword.
Processing of JSON-LD data structure is managed recursively. During processing, each rule is applied using information provided by the active context . Processing begins by pushing a new processor state onto the processor state stack and initializing the active context with the initial context . If a local context is encountered, information from the local context is merged into the active context .
The active context is used for expanding keys and values of a JSON object (or elements of a list (see List Processing )).
A
local
context
is
identified
within
a
JSON
object
having
a
key
of
@context
with
string
,
array
or
a
JSON
object
value.
When
processing
a
local
context
,
special
processing
rules
apply:
@context
@context
element
using
the
JSON
Pointer
"/@context"
as
described
in
[
JSON-POINTER
].
Set
value
@base
key,
it
must
have
a
value
of
a
simple
string
with
the
lexical
form
of
an
absolute
IRI.
Add
the
base
mapping
to
the
local
context
.
Turtle allows @base to be relative. If we did this, we would have to add IRI Expansion .
@vocab
key,
it
must
have
a
value
of
a
simple
string
with
the
lexical
form
of
an
absolute
IRI.
Add
the
vocabulary
mapping
to
the
local
context
after
performing
IRI
Expansion
on
the
associated
value.
@coerce
key,
it
must
have
a
value
of
a
JSON
object
.
Add
the
@coerce
mapping
to
the
local
context
performing
IRI
Expansion
on
the
associated
value(s).
@language
key,
it
must
have
a
value
of
a
simple
string
or
null
.
Add
the
language
to
the
local
context
.
@coerce
mapping
into
the
active
context
's
@coerce
mapping
as
described
below
.
@coerce
mapping
from
the
local
context
to
the
active
context
overwriting
any
duplicate
values.
Map
each
key-value
pair
in
the
local
context
's
@coerce
mapping
into
the
active
context
's
@coerce
mapping,
overwriting
any
duplicate
values
in
the
active
context
's
@coerce
mapping.
The
@coerce
mapping
has
either
a
single
value,
a
single
term
value
or
an
array
of
prefix:term
prefix:suffix
or
term
values.
When
merging
with
an
existing
mapping
in
the
active
context
,
map
all
prefix:term
prefix:suffix
prefix
and
term
values
to
array
form
and
replace
with
the
union
of
the
value
from
the
local
context
and
the
value
of
the
active
context
.
If
the
result
is
an
array
with
a
single
value,
the
processor
may
represent
this
as
a
string
value.
The initial context is initialized as follows:
@base
is
set
using
section
5.1
Establishing
a
Base
URI
of
[
RFC3986
].
Processors
may
provide
a
means
of
setting
the
base
IRI
programatically.
@coerce
is
set
with
a
single
mapping
from
@iri
to
@type
.
{
"@base": document-location,
"@coerce": {
"@iri": "@type"
}
}
Keys and some values are evaluated to produce an IRI. This section defines an algorithm for transforming a value representing an IRI into an actual IRI.
IRIs
may
be
represented
as
an
absolute
IRI,
a
term
,
a
prefix
:
term
:suffix
construct,
or
as
a
value
relative
to
@base
or
@vocab
.
The algorithm for generating an IRI is:
@coerce
mapping)
and
the
active
context
has
a
@vocab
mapping,
join
the
mapped
value
to
the
suffix
using
textual
concatenation.
@base
mapping,
join
the
mapped
value
to
the
suffix
using
the
method
described
in
[
RFC3986
].
Some
keys
and
values
are
expressed
using
IRIs.
This
section
defines
an
algorithm
for
transforming
an
IRI
to
a
compact
IRI
using
the
term
s
and
prefix
es
specified
in
the
local
context
.
The algorithm for generating a compacted IRI is:
Some values in JSON-LD can be expressed in a compact form. These values are required to be expanded at times when processing JSON-LD documents.
The algorithm for expanding a value is:
@iri
,
expand
the
value
by
adding
a
new
key-value
pair
where
the
key
is
@iri
and
the
value
is
the
expanded
IRI
according
to
the
IRI
Expansion
rules.
@literal
and
the
unexpanded
value.
The
second
key-value
pair
will
be
@datatype
and
the
associated
coercion
datatype
expanded
according
to
the
IRI
Expansion
rules.
Some values, such as IRIs and typed literals, may be expressed in an expanded form in JSON-LD. These values are required to be compacted at times when processing JSON-LD documents.
The algorithm for compacting a value is:
@iri
,
the
compacted
value
is
the
value
associated
with
the
@iri
key,
processed
according
to
the
IRI
Compaction
steps.
@literal
key.
As
stated
previously,
expansion
Expansion
is
the
process
of
taking
a
JSON-LD
input
and
expanding
all
IRIs
document
and
typed
literals
to
their
fully-expanded
form.
The
output
will
not
contain
applying
a
single
context
declaration
and
will
have
such
that
all
IRIs
IRI,
datatypes,
and
typed
literals
fully
expanded.
literal
values
are
expanded
so
that
the
context
is
no
longer
necessary.
JSON-LD
document
expansion
is
typically
used
as
a
part
of
Framing
or
Normalization
.
For example, assume the following JSON-LD input document:
{
"@context":
{
"name": "http://xmlns.com/foaf/0.1/name",
"homepage": "http://xmlns.com/foaf/0.1/homepage",
"@coerce":
{
"@iri": "homepage"
}
},
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/"
}
Running the JSON-LD Expansion algorithm against the JSON-LD input document provided above would result in the following output:
{
"http://xmlns.com/foaf/0.1/name": "Manu Sporny",
"http://xmlns.com/foaf/0.1/homepage":
{
"@iri": "http://manu.sporny.org/"
}
}
This algorithm is a work in progress, do not implement it.
What are the implications for expanding lists?
As
stated
previously,
compaction
Compaction
is
the
process
of
taking
a
JSON-LD
input
document
and
compacting
all
applying
a
context
such
that
the
most
compact
form
of
the
document
is
generated.
JSON
is
typically
expressed
in
a
very
compact,
key-value
format.
That
is,
full
IRIs
using
are
rarely
used
as
keys.
At
times,
a
JSON-LD
document
may
be
received
that
is
not
in
its
most
compact
form.
JSON-LD,
via
the
API,
provides
a
way
to
compact
a
JSON-LD
document.
For example, assume the following JSON-LD input document:
{
"http://xmlns.com/foaf/0.1/name": "Manu Sporny",
"http://xmlns.com/foaf/0.1/homepage":
{
"@iri": "http://manu.sporny.org/"
}
}
Additionally, assume the following developer-supplied JSON-LD context:
{
"name": "http://xmlns.com/foaf/0.1/name",
"homepage": "http://xmlns.com/foaf/0.1/homepage",
"@coerce":
{
"@iri": "homepage"
}
}
Running
the
JSON-LD
Compaction
algorithm
given
context.
the
context
supplied
above
against
the
JSON-LD
input
document
provided
above
would
result
in
the
following
output:
{
"@context":
{
"name": "http://xmlns.com/foaf/0.1/name",
"homepage": "http://xmlns.com/foaf/0.1/homepage",
"@coerce":
{
"@iri": "homepage"
}
},
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/"
}
The
output
will
contain
a
single
top-level
compaction
algorithm
also
enables
the
developer
to
map
any
expanded
format
into
an
application-specific
compacted
format.
While
the
context
declaration
and
will
only
use
term
s
and
prefix
es
and
will
ensure
that
all
typed
literals
are
fully
compacted.
provided
above
mapped
http://xmlns.com/foaf/0.1/name
to
name
,
it
could
have
also
mapped
it
to
any
arbitrary
string
provided
by
the
developer.
This algorithm is a work in progress, do not implement it.
What are the implications for compacting lists?
JSON-LD
Framing
allows
developers
to
query
by
example
and
force
a
work
in
progress,
do
not
implement
it.
specific
tree
layout
to
a
JSON-LD
document.
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
typically
don't
work
directly
with
graphs,
but
rather,
prefer
trees
when
dealing
with
JSON.
trees,
represented
as
JSON
object
s.
While
mapping
a
graph
to
a
tree
can
be
done,
the
layout
of
the
end
result
must
be
specified
in
advance.
This
section
defines
an
algorithm
A
Frame
can
be
used
by
a
developer
on
a
JSON-LD
document
to
specify
a
deterministic
layout
for
mapping
a
graph.
Framing is the process of taking a JSON-LD document, which expresses a graph of information, and applying a specific graph layout (called a Frame ).
The JSON-LD document below expresses a library, a book and a chapter:
{
"@context": {
"Book": "http://example.org/vocab#Book",
"Chapter": "http://example.org/vocab#Chapter",
"contains": "http://example.org/vocab#contains",
"creator": "http://purl.org/dc/terms/creator"
"description": "http://purl.org/dc/terms/description"
"Library": "http://example.org/vocab#Library",
"title": "http://purl.org/dc/terms/title",
"@coerce":
{
"@iri": "contains"
},
},
"@subject":
[{
"@subject": "http://example.com/library",
"@type": "Library",
"contains": "http://example.org/library/the-republic"
},
{
"@subject": "http://example.org/library/the-republic",
"@type": "Book",
"creator": "Plato",
"title": "The Republic",
"contains": "http://example.org/library/the-republic#introduction"
},
{
"@subject": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
}]
}
Developers
typically
like
to
operate
on
items
in
a
tree
given
hierarchical,
tree-based
fashion.
Ideally,
a
developer
would
want
the
data
above
sorted
into
top-level
libraries,
then
the
books
that
are
contained
in
each
library,
and
then
the
chapters
contained
in
each
book.
To
achieve
that
layout,
the
developer
can
define
the
following
frame
.
:
{
"@context": {
"Book": "http://example.org/vocab#Book",
"Chapter": "http://example.org/vocab#Chapter",
"contains": "http://example.org/vocab#contains",
"creator": "http://purl.org/dc/terms/creator"
"description": "http://purl.org/dc/terms/description"
"Library": "http://example.org/vocab#Library",
"title": "http://purl.org/dc/terms/title"
},
"@type": "Library",
"contains": {
"@type": "Book",
"contains": {
"@type": "Chapter"
}
}
}
When the framing algorithm is run against the previously defined JSON-LD document, paired with the frame above, the following JSON-LD document is the end result:
{
"@context": {
"Book": "http://example.org/vocab#Book",
"Chapter": "http://example.org/vocab#Chapter",
"contains": "http://example.org/vocab#contains",
"creator": "http://purl.org/dc/terms/creator"
"description": "http://purl.org/dc/terms/description"
"Library": "http://example.org/vocab#Library",
"title": "http://purl.org/dc/terms/title"
},
"@subject": "http://example.org/library",
"@type": "Library",
"contains": {
"@subject": "http://example.org/library/the-republic",
"@type": "Book",
"creator": "Plato",
"title": "The Republic",
"contains": {
"@subject": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
},
},
}
This algorithm is a work in progress, do not implement it.
The framing algorithm takes JSON-LD input that has been normalized according to the Normalization Algorithm ( normalized input ), an input frame that has been expanded according to the Expansion Algorithm ( expanded frame ), and a number of options and produces JSON-LD output . The following series of steps is the recursive portion of the framing algorithm:
null
.
Invalid
Frame
Format
exception.
Add
each
matching
item
from
the
normalized
input
to
the
matches
array
and
decrement
the
match
limit
by
1
if:
rdf:type
that
exists
in
the
item's
list
of
rdf:type
s.
Note:
the
rdf:type
can
be
an
array
,
but
only
one
value
needs
to
be
in
common
between
the
item
and
the
expanded
frame
for
a
match.
rdf:type
property,
but
every
property
in
the
expanded
frame
exists
in
the
item.
matches array not defined anywhere.
@embed
keyword,
set
the
object
embed
flag
to
its
value.
If
the
match
frame
contains
an
@explicit
keyword,
set
the
explicit
inclusion
flag
to
its
value.
Note:
if
the
keyword
exists,
but
the
value
is
neither
true
or
false
,
set
the
associated
flag
to
true
.
@subject
property,
replace
the
item
with
the
value
of
the
@subject
property.
@subject
property,
and
its
IRI
is
in
the
map
of
embedded
subjects
,
throw
a
Duplicate
Embed
exception.
@subject
property
and
its
IRI
is
not
in
the
map
of
embedded
subjects
:
@subject
.
rdf:type
:
@iri
value
that
exists
in
the
normalized
input
@subject
key
where
the
value
is
the
value
of
the
@iri
,
and
all
of
the
other
key-value
pairs
for
that
subject.
Set
the
recursion
match
frame
to
the
value
associated
with
the
match
frame
's
key.
Replace
the
value
associated
with
the
key
by
recursively
calling
this
algorithm
using
recursion
input
list
,
recursion
match
frame
as
input.
null
otherwise.
null
,
process
the
omit
missing
properties
flag
:
@omitDefault
keyword,
set
the
omit
missing
properties
flag
to
its
value.
Note:
if
the
keyword
exists,
but
the
value
is
neither
true
or
false
,
set
the
associated
flag
to
true
.
@default
keyword
is
set
in
the
property
frame
set
the
item's
value
to
the
value
of
@default
.
null
set
it
to
the
item,
otherwise,
append
the
item
to
the
JSON-LD
output
.
What are the implications for framing lists?
This algorithm is a work in progress, do not implement it.
Normalization is the process of taking JSON-LD input and performing a deterministic transformation on that input that results in all aspects of the graph being fully expanded and named in the JSON-LD output . The normalized output is generated in such a way that any conforming JSON-LD processor will generate identical output given the same input. The problem is a fairly difficult technical problem to solve because it requires a directed graph to be ordered into a set of nodes and edges in a deterministic way. This is easy to do when all of the nodes have unique names, but very difficult to do when some of the nodes are not labeled.
Normalization is useful when comparing two graphs against one another, when generating a detailed list of differences between two graphs, and when generating a cryptographic digital signature for information contained in a graph or when generating a hash of the information contained in a graph.
The example below is an un-normalized JSON-LD document:
{
"@context":
{
"name": "http://xmlns.com/foaf/0.1/name",
"homepage": "http://xmlns.com/foaf/0.1/homepage",
"xsd": "http://www.w3.org/2001/XMLSchema#",
"@coerce":
{
"@iri": ["homepage"]
}
},
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/"
}
The example below is the normalized form of the JSON-LD document above:
Whitespace is used below to aid readability. The normalization algorithm for JSON-LD removes all unnecessary whitespace in the fully normalized form.
[{
"@subject":
{
"@iri": "_:c14n0"
},
"http://xmlns.com/foaf/0.1/homepage":
{
"@iri": "http://manu.sporny.org/"
},
"http://xmlns.com/foaf/0.1/name": "Manu Sporny"
}]
Notice how all of the term s have been expanded and sorted in alphabetical order. Also, notice how the subject has been labeled with a blank node identifier . Normalization ensures that any arbitrary graph containing exactly the same information would be normalized to exactly the same form shown above.
In
time,
there
may
be
more
than
one
normalization
algorithm
that
will
need
to
be
identified.
For
identification
purposes,
this
algorithm
is
named
"Universal
"Universal
Graph
Normalization
Algorithm
2011"
2011"
(
UGNA2011
).
@subject
and
the
value
is
a
string
that
is
an
IRI
or
a
JSON
object
containing
the
key
@iri
and
a
value
that
is
a
string
that
is
an
IRI.
s<NUMBER>
or
c<NUMBER>
.
When performing the steps required by the normalization algorithm, it is helpful to track the many pieces of information in a data structure called the normalization state . Many of these pieces simply provide indexes into the graph. The information contained in the normalization state is described below.
_:
and
that
has
a
path,
via
properties,
that
starts
with
the
node
reference
.
_:
and
that
has
a
path,
via
properties,
that
ends
with
the
node
reference
.
_:
,
is
not
used
by
any
other
node's
label
in
the
JSON-LD
input
,
and
does
not
start
with
the
characters
_:c14n
.
The
prefix
has
two
uses.
First
it
is
used
to
temporarily
name
nodes
during
the
normalization
algorithm
in
a
way
that
doesn't
collide
with
the
names
that
already
exist
as
well
as
the
names
that
will
be
generated
by
the
normalization
algorithm.
Second,
it
will
eventually
be
set
to
_:c14n
to
generate
the
final,
deterministic
labels
for
nodes
in
the
graph.
This
prefix
will
be
concatenated
with
the
labeling
counter
to
produce
a
node
label
.
For
example,
_:j8r3k
is
a
proper
initial
value
for
the
labeling
prefix
.
1
.
The normalization algorithm expands the JSON-LD input , flattens the data structure, and creates an initial set of names for all nodes in the graph. The flattened data structure is then processed by a node labeling algorithm in order to get a fully expanded and named list of nodes which is then sorted. The result is a deterministically named and ordered list of graph nodes.
@subject
and
the
value
is
the
concatenation
of
the
labeling
prefix
and
the
string
value
of
the
labeling
counter
.
Increment
the
labeling
counter
.
@iri
and
the
value
is
the
value
of
the
@subject
key
in
the
node.
_:c14n
,
relabel
the
node
using
the
Node
Relabeling
Algorithm
.
@subject
key
associated
with
a
value
starting
with
_:
according
to
the
steps
in
the
Deterministic
Labeling
Algorithm
.
This algorithm renames a node by generating a unique new label and updating all references to that label in the node state map . The old label and the normalization state must be given as an input to the algorithm. The old label is the current label of the node that is to be relabeled.
The node relabeling algorithm is as follows:
_:c14n
and
the
old
label
begins
with
_:c14n
then
return
as
the
node
has
already
been
renamed.
The deterministic labeling algorithm takes the normalization state and produces a list of finished nodes that is sorted and contains deterministically named and expanded nodes from the graph.
_:c14n
,
the
labeling
counter
to
1
,
the
list
of
finished
nodes
to
an
empty
array,
and
create
an
empty
array,
the
list
of
unfinished
nodes
.
_:
then
put
the
node
reference
in
the
list
of
finished
nodes
.
_:
then
put
the
node
reference
in
the
list
of
unfinished
nodes
.
_:c14n
from
the
list
of
unfinished
nodes
and
add
it
to
the
list
of
finished
nodes
.
The shallow comparison algorithm takes two unlabeled nodes, alpha and beta , as input and determines which one should come first in a sorted list. The following algorithm determines the steps that are executed in order to determine the node that should come first in a list:
_:
is
first.
_:
,
then
the
node
associated
with
the
lexicographically
lesser
label
is
first.
_:c14n
is
first.
The object comparison algorithm is designed to compare two graph node property values, alpha and beta , against the other. The algorithm is useful when sorting two lists of graph node properties.
@literal
is
first.
@datatype
is
first.
@language
is
first.
@iri
is
first.
The deep comparison algorithm is used to compare the difference between two nodes, alpha and beta . A deep comparison takes the incoming and outgoing node edges in a graph into account if the number of properties and value of those properties are identical. The algorithm is helpful when sorting a list of nodes and will return whichever node should be placed first in a list if the two nodes are not truly equivalent.
When performing the steps required by the deep comparison algorithm, it is helpful to track state information about mappings. The information contained in a mapping state is described below.
1
.
s1
and
its
index
is
set
to
0
.
The deep comparison algorithm is as follows:
outgoing
direction
to
the
algorithm
as
inputs.
outgoing
direction
to
the
algorithm
as
inputs.
incoming
direction
to
the
algorithm
as
inputs.
incoming
direction
to
the
algorithm
as
inputs.
The
node
serialization
algorithm
takes
a
node
state
,
a
mapping
state
,
and
a
direction
(either
outgoing
direction
or
incoming
direction
)
as
inputs
and
generates
a
deterministic
serialization
for
the
node
reference
.
true
.
outgoing
direction
and
the
incoming
list
otherwise,
if
the
label
starts
with
_:
,
it
is
the
target
node
label
:
1
or
the
length
of
the
adjacent
unserialized
labels
list
,
whichever
is
greater.
0
,
perform
the
Combinatorial
Serialization
Algorithm
passing
the
node
state
,
the
mapping
state
for
the
first
iteration
and
a
copy
of
it
for
each
subsequent
iteration,
the
generated
serialization
label
,
the
direction
,
the
adjacent
serialized
labels
map
,
and
the
adjacent
unserialized
labels
list
.
Decrement
the
maximum
serialization
combinations
by
1
for
each
iteration.
The algorithm generates a serialization label given a label and a mapping state and returns the serialization label .
_:c14n
,
the
serialization
label
is
the
letter
c
followed
by
the
number
that
follows
_:c14n
in
the
label
.
s
followed
by
the
string
value
of
mapping
1
.
The combinatorial serialization algorithm takes a node state , a mapping state , a serialization label , a direction , a adjacent serialized labels map , and a adjacent unserialized labels list as inputs and generates the lexicographically least serialization of nodes relating to the node reference .
1
or
the
length
of
the
adjacent
unserialized
labels
list
,
whichever
is
greater.
0
:
1
for
each
iteration.
outgoing
direction
then
directed
serialization
refers
to
the
outgoing
serialization
and
the
directed
serialization
map
refers
to
the
outgoing
serialization
map
,
otherwise
it
refers
to
the
incoming
serialization
and
the
directed
serialization
map
refers
to
the
incoming
serialization
map
.
Compare
the
serialization
string
to
the
directed
serialization
according
to
the
Serialization
Comparison
Algorithm
.
If
the
serialization
string
is
less
than
or
equal
to
the
directed
serialization
:
The serialization comparison algorithm takes two serializations, alpha and beta and returns either which of the two is less than the other or that they are equal.
The mapping serialization algorithm incrementally updates the serialization string in a mapping state .
_
character
and
the
serialization
key
to
the
serialization
string
.
true
.
0
onto
the
key
stack
.
The label serialization algorithm serializes information about a node that has been assigned a particular serialization label .
[
character
to
the
label
serialization
.
@subject
property.
The
keys
should
be
processed
in
lexicographical
order
and
their
associated
values
should
be
processed
in
the
order
produced
by
the
Object
Comparison
Algorithm
:
<
KEY
>
where
KEY
is
the
current
key.
Append
string
to
the
label
serialization
.
@iri
key
with
a
value
that
starts
with
_:
,
set
the
object
string
to
the
value
_:
.
If
the
value
does
not
start
with
_:
,
build
the
object
string
using
the
pattern
<
IRI
>
where
IRI
is
the
value
associated
with
the
@iri
key.
@literal
key
and
a
@datatype
key,
build
the
object
string
using
the
pattern
"
"
LITERAL
"^^<
"^^<
DATATYPE
>
where
LITERAL
is
the
value
associated
with
the
@literal
key
and
DATATYPE
is
the
value
associated
with
the
@datatype
key.
@literal
key
and
a
@language
key,
build
the
object
string
using
the
pattern
"
"
LITERAL
"@
"@
LANGUAGE
where
LITERAL
is
the
value
associated
with
the
@literal
key
and
LANGUAGE
is
the
value
associated
with
the
@language
key.
"
"
LITERAL
"
"
where
LITERAL
is
the
value
associated
with
the
current
key.
|
separator
character
to
the
label
serialization
.
]
character
to
the
label
serialization
.
[
character
to
the
label
serialization
.
<
PROPERTY
>
<
REFERER
>
where
PROPERTY
is
the
property
associated
with
the
incoming
reference
and
REFERER
is
either
the
subject
of
the
node
referring
to
the
label
in
the
incoming
reference
or
_:
if
REFERER
begins
with
_:
.
|
separator
character
to
the
label
serialization
.
]
character
to
the
label
serialization
.
When
normalizing
xsd:double
values,
implementers
must
ensure
that
the
normalized
value
is
a
string.
In
order
to
generate
the
string
from
a
double
value,
output
equivalent
to
the
function
in
C
must
be
used
where
printf("%1.6e",
printf("%1.6e",
value)
"%1.6e"
"%1.6e"
is
the
string
formatter
and
value
is
the
value
to
be
converted.
To convert the a double value in JavaScript, implementers can use the following snippet of code:
// the variable 'value' below is the JavaScript native double value that is to be converted (value).toExponential(6).replace(/(e(?:\+|-))([0-9])$/, '$10$2')
When data needs to be normalized, JSON-LD authors should not use values that are going to undergo automatic conversion. This is due to the lossy nature of xsd:double values.
Some
JSON
serializers,
such
as
PHP's
native
implementation,
backslash-escapes
the
forward
slash
character.
For
example,
the
value
http://example.com/
would
be
serialized
as
http:\/\/example.com\/
in
some
versions
of
PHP.
This
is
problematic
when
generating
a
byte
stream
for
processes
such
as
normalization.
There
is
no
need
to
backslash-escape
forward-slashes
in
JSON-LD.
To
aid
interoperability
between
JSON-LD
processors,
a
JSON-LD
serializer
must
not
backslash-escape
forward
slashes.
Round-tripping data can be problematic if we mix and match @coerce rules with JSON-native datatypes, like integers. Consider the following code example:
var myObj = { "@context" : {
"number" : "http://example.com/vocab#number",
"@coerce": {
"xsd:nonNegativeInteger": "number"
}
},
"number" : 42 };
// Map the language-native object to JSON-LD
var jsonldText = jsonld.normalize(myObj);
// Convert the normalized object back to a JavaScript object
var
myObj2
=
jsonld.parse(jsonldText);
At
this
point,
myObj2
and
myObj
will
have
different
values
for
the
"number"
"number"
value.
myObj
will
be
the
number
42,
while
myObj2
will
be
the
string
"42".
"42".
This
type
of
data
round-tripping
error
can
bite
developers.
We
are
currently
wondering
if
having
a
"coerce
validation"
"coerce
validation"
phase
in
the
parsing/normalization
phases
would
be
a
good
idea.
It
would
prevent
data
round-tripping
issues
like
the
one
mentioned
above.
A JSON-LD document may be converted to any other RDF-compatible document format using the algorithm specified in this section.
The JSON-LD Processing Model describes processing rules for extracting RDF from a JSON-LD document. Note that many uses of JSON-LD may not require generation of RDF.
The processing algorithm described in this section is provided in order to demonstrate how one might implement a JSON-LD to RDF processor. Conformant implementations are only required to produce the same type and number of triples during the output process and are not required to implement the algorithm exactly as described.
The RDF Conversion Algorithm is a work in progress.
This section is non-normative.
JSON-LD is intended to have an easy to parse grammar that closely models existing practice in using JSON for describing object representations. This allows the use of existing libraries for parsing JSON.
As with other grammars used for describing Linked Data , a key concept is that of a resource . Resources may be of three basic types: IRI s, for describing externally named entities, BNodes , resources for which an external name does not exist, or is not known, and Literals, which describe terminal entities such as strings, dates and other representations having a lexical representation possibly including an explicit language or datatype.
An Internationalized Resource Identifier ( IRI ), as described in [ RFC3987 ], is a mechanism for representing unique identifiers on the web. In Linked Data , an IRI is commonly used for expressing a subject , a property or an object .
Data described with JSON-LD may be considered to be the representation of a graph made up of subject and object resources related via a property resource. However, specific implementations may choose to operate on the document as a normal JSON description of objects having attributes.
The algorithm below is designed for in-memory implementations with random access to JSON object elements.
A conforming JSON-LD processor implementing RDF conversion must implement a processing algorithm that results in the same default graph that the following algorithm generates:
@context
key,
process
the
local
context
as
described
in
Context
.
@iri
key,
set
the
active
object
by
performing
IRI
Expansion
on
the
associated
value.
Generate
a
triple
representing
the
active
subject
,
the
active
property
and
the
active
object
.
Return
the
active
object
to
the
calling
location.
@iri
really
just
behaves
the
same
as
@subject
,
consider
consolidating
them.
@literal
key,
set
the
active
object
to
a
literal
value
as
follows:
@datatype
key
after
performing
IRI
Expansion
on
the
specified
@datatype
.
@language
key,
use
it's
value
to
set
the
language
of
the
plain
literal.
@list
key
and
the
value
is
an
array
process
the
value
as
a
list
starting
at
Step
4
.
@subject
key:
@list
coercion,
and
the
value
is
an
array
,
process
the
value
as
a
list
starting
at
Step
4
.
@subject
key,
set
the
active
object
to
newly
generated
blank
node
identifier
@type
,
set
the
active
property
to
rdf:type
.
rdf:first
and
rdf:next
,
terminating
the
list
with
rdf:nil
using
the
following
sequence:
rdf:nil
.
rdf:first
as
the
active
property
.
rdf:nil
.
rdf:rest
and
rest
blank
node
identifier
.
@iri
coercion,
set
the
active
object
by
performing
IRI
Expansion
on
the
string.
language
key
with
a
non-
null
value,
use
it's
value
to
set
the
language
of
the
plain
literal
.
xsd:integer
or
xsd:double
,
depending
on
if
the
value
contains
a
fractional
and/or
an
exponential
component.
Generate
a
triple
using
the
active
subject
,
active
property
and
the
generated
typed
literal.
xsd:boolean
.
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,
Dave
Longley,
Dave
Lehn
and
Mike
Johnson
who
reviewed,
provided
feedback,
and
performed
several
implementations
of
the
specification,
and
Ian
Davis,
who
created
RDF/JSON.
Thanks
also
to
Nathan
Rixham,
Bradley
P.
Allen,
Kingsley
Idehen,
Glenn
McDonald,
Alexandre
Passant,
Danny
Ayers,
Ted
Thibodeau
Jr.,
Olivier
Grisel,
Niklas
Lindström,
Lindstr�m,
Markus
Lanthaler,
and
Richard
Cyganiak
for
their
input
on
the
specification.
Another
huge
thank
you
goes
out
to
Dave
Longley
who
designed
many
of
the
algorithms
used
in
this
specification,
including
the
normalization
algorithm
which
was
a
monumentally
difficult
design
challenge.