Copyright © 2010-2018 W3C ® ( MIT , ERCIM , Keio , Beihang ). W3C liability , trademark and permissive document license rules apply.
JSON-LD Framing allows developers to query by example and force a specific tree layout to a JSON-LD document.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document has been developed by the JSON-LD Working Group and was derived from the JSON-LD Community Group's Final Report .
There is a live JSON-LD playground that is capable of demonstrating the features described in this document.
This document was published by the JSON-LD Working Group as an Editor's Draft.
GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-json-ld-wg@w3.org ( archives ).
Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
This
document
is
governed
by
the
1
February
2018
W3C
Process
Document
.
This
document
is
one
of
three
JSON-LD
1.1
Recommendations
produced
by
the
JSON-LD
Working
Group
:
Set
of
Documents
A
JSON-LD
document
is
a
representation
lightweight
syntax
to
serialize
Linked
Data
[
LINKED-DATA
]
in
JSON
[
RFC8259
].
Its
design
allows
existing
JSON
to
be
interpreted
as
Linked
Data
with
minimal
changes.
As
with
other
representations,
of
a
Linked
Data
which
describe
directed
graph.
graphs,
A
single
directed
graph
can
have
many
different
serializations,
each
expressing
exactly
the
same
information.
Developers
typically
work
with
trees,
represented
as
JSON
objects
.
While
mapping
a
graph
to
a
tree
can
be
done,
the
layout
of
the
end
result
must
be
specified
in
advance.
A
Frame
can
be
used
by
a
developer
on
a
JSON-LD
document
to
specify
a
deterministic
layout
for
a
graph.
Using
delimiters
around
a
chunk
of
data
is
known
as
"framing".
JSON-LD
uses
JSON
delimiters
such
as
{
and
}
to
separate
statements
about
a
particular
subject.
JSON-LD
also
allows
subjects
to
reference
other
subjects
through
the
use
of
their
identifiers,
expressed
as
strings.
However,
given
that
JSON-LD
represents
a
one
or
more
graph
graphs
of
information,
there
is
more
than
one
way
to
frame
the
statements
about
several
related
subjects
into
a
whole
document.
In
fact,
a
graph
of
information
can
be
thought
of
as
a
long
list
of
independent
statements
(aka
triples
or
quads
)
that
are
not
bundled
together
in
any
way.
The
JSON-LD
Framing
API
enables
a
developer
to
specify
exactly
how
they
would
like
data
to
be
framed,
such
that
statements
about
a
particular
subject
are
bundled
together,
delimited
via
{
and
}
,
and
such
that
the
subjects
they
relate
to
"nest"
into
a
particular
tree
structure
that
matches
what
their
application
expects.
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 [ RFC8259 ]. You must also understand the JSON-LD 1.1 Syntax specification [ JSON-LD11 ], which is the base syntax used by all of the algorithms in this document, and the JSON-LD 1.1 API [ JSON-LD11-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 [ ECMASCRIPT ] and WebIDL [ WEBIDL ]. To understand how JSON-LD maps to RDF, it is helpful to be familiar with the basic RDF concepts [ RDF11-CONCEPTS ].
This section is non-normative.
There are a number of ways that one may participate in the development of this specification:
This section is non-normative.
The following typographic conventions are used in this specification:
markup
markup
definition
reference
markup
external
definition
reference
Notes are in light green boxes with a green left border and with a "Note" header in green. Notes are always informative.
This document uses the following terms as defined in JSON [ RFC8259 ]. Refer to the JSON Grammar section in [ RFC8259 ] for formal definitions.
@context
where
the
value,
or
the
@id
of
the
value,
is
null
,
explicitly
decouples
a
term's
association
with
an
IRI
.
A
dictionary
member
in
the
body
of
a
JSON-LD
document
whose
value
is
null
has
the
same
meaning
as
if
the
dictionary
member
was
not
defined.
If
@value
,
@list
,
or
@set
is
set
to
null
in
expanded
form,
then
the
entire
JSON
object
is
ignored.
Furthermore, the following terminology is used throughout this document:
_:
.
_:
.
@default
key.
@value
,
@list
,
or
@set
keywords,
or
@graph
and
@context
.
@id
key.
@version
member
in
a
context
,
or
via
explicit
API
option,
other
processing
modes
can
be
accessed.
This
specification
defines
extensions
for
the
json-ld-1.1
processing
mode
.
@type
,
and
values
of
terms
defined
to
be
vocabulary
relative
are
resolved
relative
to
the
vocabulary
mapping
,
not
the
base
IRI
.
@value
member
.
@vocab
key
whose
value
MUST
be
an
absolute
IRI
or
null
.
The Following terms are used within specific algorithms.
@graph
member,
or
only
if
required
to
represent
multiple
node
objects
.
This section is non-normative.
This section is non-normative.
Framing is used to shape the data in a JSON-LD document , using an example frame document which is used to both match the flattened data and show an example of how the resulting data should be shaped. Matching is performed by using properties present in in the frame to find objects in the data that share common values. Matching can be done either using all properties present in the frame, or any property in the frame. By chaining together objects using matched property values, objects can be embedded within one another.
A frame also includes a context , which is used for compacting the resulting framed output.
For example, assume the following JSON-LD frame:
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"contains": {
"@type": "Book",
"contains": {
"@type": "Chapter"
}
}
}
This frame document describes an embedding structure that would place objects with type Library at the top, with objects of type Book that were linked to the library object using the contains property embedded as property values. It also places objects of type Chapter within the referencing Book object as embedded values of the Book object.
When using a flattened set of objects that match the frame components:
{
"@context": {
"@vocab": "http://example.org/",
"contains": {"@type": "@id"}
},
"@graph": [{
"@id": "http://example.org/library",
"@type": "Library",
"contains": "http://example.org/library/the-republic"
}, {
"@id": "http://example.org/library/the-republic",
"@type": "Book",
"creator": "Plato",
"title": "The Republic",
"contains": "http://example.org/library/the-republic#introduction"
}, {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
}]
}
The Frame Algorithm can create a new document which follows the structure of the frame:
If
processing
mode
is
json-ld-1.1
,
or
the
omit
graph
flag
is
true
,
the
top-level
@graph
member
may
be
omitted.
{
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"@type": "Library",
"contains": {
"@id": "http://example.org/library/the-republic",
"@type": "Book",
"contains": {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
},
"creator": "Plato",
"title": "The Republic"
}
}
The
Framing
Algorithm
does
this
by
first
expanding
both
the
input
frame
and
document.
It
then
creates
a
map
of
flattened
subjects
.
The
outer-most
node
object
within
the
frame
is
used
to
match
objects
in
the
map,
in
this
case
looking
for
node
objects
which
have
an
@type
of
Library
,
and
a
contains
property
with
another
frame
used
to
match
values
of
that
property.
The
input
document
contains
exactly
one
such
node
object
.
The
value
of
contains
also
has
a
node
object
,
which
is
then
treated
as
a
frame
to
match
the
set
of
subjects
which
are
contains
values
of
the
Library
object,
and
so
forth.
This section is non-normative.
A
frame
may
specify
properties
that
don't
exist
in
an
input
file.
If
the
explicit
inclusion
flag
is
false
,
the
framing
algorithm
will
add
a
property
and
value
to
the
result.
The
@default
property
in
a
node
object
or
value
object
provides
a
default
value
to
use
in
the
resulting
output
document.
If
there
is
no
@default
value,
the
property
will
be
output
with
a
null
value.
(See
section
2.3.3
Omit
default
flag
for
ways
to
avoid
this).
The value of the property in the frame is not otherwise used in the output document. It's purpose is for frame matching and finding default values. Note the description value for Library in the following example.
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"description": "A great Library.",
"contains": {
"@type": "Book",
"description": {"@default": "A great book."},
"contains": {
"@type": "Chapter"
}
}
}
This section is non-normative.
Framing can be controlled using API options , or by adding framing keywords within the frame as described in section 4.1 Syntax Tokens and Keywords .
Framing flags set using keywords have effect only for the frame in which they appear, and for implicit frames which are created for objects where no frame object exists.
This section is non-normative.
The
object
embed
flag
determines
if
a
referenced
node
object
is
embedded
as
a
property
value
of
a
referencing
object,
or
kept
as
a
node
reference
.
The
initial
value
for
the
object
embed
flag
is
set
using
the
embed
option.
Consider
the
following
frame
based
on
the
default
@last
value
of
the
object
embed
flag
:
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library"
}
Because,
the
default
for
the
object
embed
flag
is
@last
(in
addition
to
the
explicit
inclusion
flag
being
false
),
non-listed
properties
are
added
to
the
output,
and
implicitly
embedded
using
a
default
empty
frame.
As
a
result,
the
same
output
used
in
the
Framed
library
objects
above
is
generated.
However,
if
the
@embed
property
is
added
explicitly
with
a
value
of
@never
,
the
values
for
Book
and
Chapter
will
be
excluded.
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"contains": {
"@type": "Book",
"@embed": "@never"
}
}
This section is non-normative.
The
explicit
inclusion
flag
used
to
determine
properties
which
will
be
included
in
the
output
document.
The
default
value
is
false
,
which
means
that
properties
present
in
an
input
node
object
that
are
not
in
the
associated
frame
will
be
included
in
the
output
object.
The
initial
value
for
the
explicit
inclusion
flag
is
set
using
the
explicit
option.
If
true
,
only
properties
present
in
the
input
frame
will
be
placed
into
the
output.
For example, take an expanded version of the library frame which include some properties from the input, but omit others.
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"description": {},
"contains": {
"@type": "Book",
"@explicit": true,
"title": {},
"contains": {
"@type": "Chapter"
}
}
}
The resulting output will exclude properties for Book which are not explicitly listed in the frame object :
Note
that
the
Library
object
contains
a
null
description
property,
as
it
is
explicitly
called
for
in
the
fram
using
"description":
{}
.
The
creator
property
does
not
exist
in
the
output,
because
it
is
not
explicit.
This section is non-normative.
The
omit
default
flag
changes
the
way
framing
generates
output
when
a
property
described
in
the
frame
is
not
present
in
the
input
document.
The
initial
value
for
the
omit
default
flag
is
set
using
the
omitDefault
option.
See
section
2.2
Default
content
for
a
further
discussion.
This section is non-normative.
The
omit
graph
flag
determines
if
framed
output
containing
a
single
node
object
is
contained
within
@graph
,
or
not.
The
initial
value
for
the
omit
graph
flag
is
set
using
the
omitGraph
option,
or
based
on
the
processing
mode
;
if
processing
mode
is
json-ld-1.0
,
the
output
always
includes
a
@graph
member
,
otherwise,
the
@graph
member
is
used
only
to
describe
multiple
node
objects
,
consistent
with
compaction.
See
section
4.2.2
Framing
Algorithm
for
a
further
discussion.
This section is non-normative.
The
require
all
flag
is
used
in
frame
matching
to
determine
when
a
node
object
from
an
input
document
matches
a
frame.
When
matching,
an
object
may
include
@type
and
other
properties,
a
match
is
made
when
any
property
value
in
the
object
matches
the
node
pattern
in
the
frame
object
if
the
value
of
the
require
all
flag
is
false
(the
default).
If
the
flag
value
is
true
,
then
all
properties
in
the
frame
object
must
be
present
in
the
node
object
for
the
node
to
match.
This section is non-normative.
A
frame
may
include
@reverse
,
or
a
value
of
a
term
defined
using
@reverse
to
invert
the
relationships
in
the
output
object.
For
example,
the
Library
example
can
be
inverted
using
the
following
frame:
{
"@context": {
"@vocab": "http://example.org/",
"within": {"@reverse": "contains"}
},
"@type": "Chapter",
"within": {
"@type": "Book",
"within": {
"@type": "Library"
}
}
}
Using the flattened library example above, results in the following:
There is an asymmetry between regular properties and reverse properties. Normally, when framing a node object , unless the explicit inclusion flag is set, all properties of the node are included in the output, but reverse properties are not, as they are not actually properties of the node.
To include reverse properties in the output, add them explicitly to the frame. Note that if the reverse relationship does not exist, it will simply be left out of the output.
This section is non-normative.
Frames
can
include
@graph
,
which
allows
information
from
named
graphs
contained
within
a
JSON-LD
document
to
be
exposed
within
it's
proper
graph
context.
By
default,
framing
uses
a
merged
graph
,
composed
of
all
the
node
objects
across
all
graphs
within
the
input.
By
using
@graph
within
a
frame,
the
output
document
can
include
information
specifically
from
named
graphs
contained
within
the
input
document.
The
following
example
uses
a
variation
on
our
library
theme
where
information
is
split
between
the
default
graph
,
and
a
graph
named
http://example.org/graphs/books
:
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"contains": {
"@id": "http://example.org/graphs/books",
"@graph": {
"@type": "Book"
}
}
}
[{
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/graphs/books",
"@graph": [{
"@id": "http://example.org/library/the-republic",
"@type": "http://example.org/Book",
"http://example.org/contains": {
"@id": "http://example.org/library/the-republic#introduction"
},
"http://example.org/creator": "Plato",
"http://example.org/title": "The Republic"
}, {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "http://example.org/Chapter",
"http://example.org/description": "An introductory chapter on The Republic.",
"http://example.org/title": "The Introduction"
}]
}, {
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"@type": "http://example.org/Library",
"http://example.org/contains": {"@id": "http://example.org/graphs/books"},
"http://example.org/name": "Library"
}]
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
,
MUST
NOT
,
RECOMMENDED
,
and
SHOULD
NOT
are
to
be
interpreted
as
described
in
[
RFC2119
].
There is one class of products that can claim conformance to this specification: JSON-LD Processors .
A conforming JSON-LD Processor is a system which can perform the Framing operation in a manner consistent with the algorithms defined in this specification.
JSON-LD Processors MUST NOT attempt to correct malformed IRIs or language tags; however, they MAY issue validation warnings. IRIs are not modified other than conversion between relative and absolute IRIs .
The algorithms in this specification are generally written with more concern for clarity than efficiency. Thus, JSON-LD Processors MAY implement the algorithms given in this specification in any way desired, so long as the end result is indistinguishable from the result that would be obtained by the specification's algorithms.
In algorithm steps that describe operations on keywords , those steps also apply to keyword aliases.
Implementers can partially check their level of conformance to this specification by successfully passing the test cases of the JSON-LD test suite [ JSON-LD-TESTS ]. Note, however, that passing all the tests in the test suite does not imply complete conformance to this specification. It only implies that the implementation conforms to aspects tested by the test suite.
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.
Reference to JSON data structures are interpreted using their internal representation for the purpose of describing algorithms.
This specification adds a number of keywords ( framing keywords ) to the ones defined in the JSON-LD 1.1 Syntax specification [ JSON-LD11 ]:
@default
@embed
@embed
as
the
following:
@always
@last
@embed
nor
object
embed
flag
is
not
specified.
@never
true
@last
).
false
@never
).
Any
other
value
for
@embed
is
invalid
and
indicates
that
an
invalid
@embed
value
error
has
been
detected
and
processing
is
aborted.
@explicit
@null
null
should
be
returned,
which
would
otherwise
be
removed
when
Compacting
.
@omitDefault
@requireAll
All JSON-LD tokens and keywords are case-sensitive.
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 ).
Framing makes use of the Node Map Generation algorithm to place each object defined in the JSON-LD document into a map of flattened subjects , allowing them to be operated upon by the Framing algorithm .
A valid JSON-LD Frame is a superset of a valid JSON-LD document , allowing additional content, which is preserved through expansion. The Grammar defined in the JSON-LD 1.1 Syntax specification [ JSON-LD11 ] is extended as follows:
@default
MAY
include
the
value
@null
,
or
an
array
containing
only
@null
,
in
addition
to
other
values
allowed
in
the
grammar
for
values
of
member
keys
expanding
to
absolute
IRIs
.
Processors
MUST
preserve
this
value
when
expanding.
All
other
members
of
a
default
object
MUST
be
ignored.
@id
and
@type
may
also
be
an
empty
dictionary
,
an
absolute
IRI
,
array
containing
only
an
empty
dictionary
,
or
an
array
of
absolute
IRIs
.
Processors
MUST
preserve
this
value
when
expanding.
@graph
member
at
the
top
level.
Nodes
with
a
subject
that
is
also
a
named
graph
,
where
the
frame
object
contains
@graph
,
extend
framing
to
node
objects
from
the
associated
named
graph
.
The framing algorithm takes an JSON-LD input ( expanded input ), which MUST be a JSON-LD document in expanded form , an input frame ( expanded frame ), which MUST be a JSON-LD frame in expanded form , a context ( context ), and a number of options and produces JSON-LD output .
If
an
error
is
detected
in
the
expanded
frame
,
a
invalid
frame
error
has
been
detected
and
processing
is
aborted.
Need
more
specifics
as
to
what
constitutes
a
valid
frame.
Set graph map to the result of performing the Node Map Generation algorithm on expanded input .
If
the
frameDefault
option
is
present
with
the
value
true
,
set
graph
name
to
@default
.
Otherwise,
create
merged
node
map
using
the
Merge
Node
Maps
algorithm
with
graph
map
and
add
merged
node
map
as
the
value
of
@merged
in
graph
map
and
set
graph
name
to
@merged
.
The
recursive
algorithm
operates
with
a
framing
state
(
state
),
created
initially
using
the
object
embed
flag
set
to
true
,
the
explicit
inclusion
flag
set
to
false
,
the
require
all
flag
set
to
true
,
the
omit
default
flag
set
to
false
,
graph
map
,
graph
name
,
along
with
map
of
flattened
subjects
set
to
the
property
associated
with
graph
name
in
graph
map
,
and
graph
stack
set
to
an
empty
array
.
The
initial
values
of
the
object
embed
flag
,
require
all
flag
,
and
omit
default
flag
MUST
be
overridden
by
values
set
in
options
.
Also
initialize
results
as
an
empty
array
.
Processors MAY use other runtime options to set different framing state defaults for values of state .
Invoke
the
recursive
algorithm
using
framing
state
(
state
),
the
keys
from
the
map
of
flattened
subjects
as
subjects
,
expanded
frame
(
frame
),
result
as
parent
,
and
null
as
active
property
.
The
recursive
algorithm
adds
elements
to
parent
either
by
appending
the
element
to
parent
,
if
it
is
an
array
,
or
by
appending
it
to
an
array
associated
with
active
property
in
parent
,
if
it
is
a
dictionary
.
Note
that
if
parent
is
an
array
,
active
property
MUST
be
null
,
and
if
it
is
a
dictionary
,
it
MUST
NOT
be
null
.
The following series of steps is the recursive portion of the framing algorithm:
@embed
,
@explicit
,
and
@requireAll
in
frame
.
ordered
flag
is
true
:
@id
and
id
.
@never
or
if
a
circular
reference
would
be
created
by
an
embed,
add
output
to
parent
and
do
not
perform
additional
processing
for
this
node
.
@last
,
remove
any
existing
embedded
node
from
parent
associate
with
graph
name
in
state
.
Requires
sorting
of
subjects.
We
could
consider
@sample
,
to
embed
just
the
first
matched
node.
With
sorting,
we
could
also
consider
@first
.
@last
or
@always
@graph
member
,
set
recurse
to
true
,
unless
graph
name
in
state
is
@merged
and
set
subframe
to
a
new
empty
dictionary
.
@graph
in
frame
,
or
a
new
empty
dictionary
,
if
it
does
not
exist,
and
set
recurse
to
true
,
unless
id
is
@merged
or
@default
.
true
:
@graph
as
active
property
.
ordered
flag
is
true
:
true
,
processors
MUST
NOT
add
any
values
for
property
to
output
,
and
the
following
steps
are
skipped.
@list
,
then
each
listitem
in
the
list
is
processed
in
sequence
and
added
to
a
new
list
dictionary
in
output:
@id
from
listitem
as
the
sole
item
in
a
new
subjects
array
,
the
first
value
from
@list
in
frame
as
frame
,
list
as
parent
,
and
@list
as
active
property
.
If
frame
does
not
exist,
create
a
new
frame
using
a
new
dictionary
with
properties
for
@embed
,
@explicit
and
@requireAll
taken
from
embed
,
explicit
and
requireAll
.
Could
this
use
the
list
array
,
and
null
for
active
property
?
@list
in
list
.
@id
from
item
as
the
sole
item
in
a
new
subjects
array
,
the
first
value
from
property
in
frame
as
frame
,
output
as
parent
,
and
property
as
active
property
.
If
frame
does
not
exist,
create
a
new
frame
using
a
new
dictionary
with
properties
for
@embed
,
@explicit
and
@requireAll
taken
from
embed
,
explicit
and
requireAll
.
@omitDefault
with
a
value
of
true
,
or
does
not
contain
@omitDefault
and
the
value
of
the
omit
default
flag
is
true
.
@preserve
and
a
value
that
is
a
copy
of
the
value
of
@default
in
frame
if
it
exists,
or
the
string
@null
otherwise.
@reverse
,
then
for
each
reverse
property
and
sub
frame
that
are
the
values
of
@reverse
in
frame
:
@reverse
property
in
output
with
a
new
dictionary
reverse
dict
as
its
value.
@id
of
id
:
If
the
processing
mode
is
json-ld-1.1
,
remove
the
@id
member
of
each
node
object
where
the
member
value
is
a
blank
node
identifier
which
appears
only
once
in
any
property
value
within
result
.
Using
result
from
the
recursive
algorithm,
set
compacted
results
to
the
result
of
using
the
compact
method
using
results
,
context
,
and
options
.
If
the
omit
graph
flag
is
false
and
compacted
results
does
not
have
a
top-level
@graph
member
,
or
its
value
is
not
an
array
,
modify
compacted
results
to
place
the
non
@context
properties
of
compacted
results
into
a
dictionary
contained
within
the
array
value
of
@graph
.
If
the
omit
graph
flag
is
true
,
a
top-level
@graph
member
is
used
only
to
contain
multiple
node
objects
.
Recursively,
replace
all
members
in
compacted
results
where
the
key
is
@preserve
with
the
value
of
the
member
.
If
the
value
of
the
member
is
@null
,
replace
the
value
with
null
.
If,
after
replacement,
an
array
contains
a
single
array
value,
replace
the
array
with
that
value.
If,
after
replacement,
an
array
contains
only
the
value
null
remove
the
value,
leaving
an
empty
array
.
Return compacted results .
The
Frame
Matching
Algorithm
is
used
as
part
of
the
Framing
algorithm
to
determine
if
a
particular
node
object
matches
the
criteria
set
in
a
frame
.
In
general,
a
node
object
matches
a
frame
if
it
meets
the
matches
on
@type
,
or
@id
,
or
if
it
matches
given
one
of
several
different
properties
(or
all
properties,
if
the
require
all
flag
is
present.).
As matching is performed on expanded node objects, all values will be in the form of an array.
Node matching uses a combination of JSON constructs to match any , zero , or some specific values:
[]
(
match
none
)
[
frame
object
]
(
node
pattern
)
[
IRI
+]
@type
and
@id
,
which
allows
a
match
on
any
of
the
listed
IRIs.
[
value
object
]
(
value
pattern
)
@value
,
@type
,
and
@language
may
also
be
an
array
of
one
or
more
string
values.
{}
(
wildcard
)
The frame matching algorithm takes the framing state ( state ), a list of subjects to match from the map of flattened subjects ( subjects ), a frame to match against ( frame ), and the requireAll flag and returns a list of matched subjects by filtering each node in subjects as follows:
Frame
matching
follows
an
order
of
precedence,
first
attempting
to
match
on
a
particular
@id
,
then
a
particular
@type
(or
lack
of
@type
),
then
by
matching
on
any
or
all
of
a
set
of
properties,
if
neither
@id
,
nor
@type
are
in
the
frame.
@id
property
value
which
is
also
a
value
of
the
@id
property
in
frame
.
Otherwise,
node
does
not
match
if
frame
has
a
non-empty
@id
property,
other
than
an
empty
dictionary
.
Otherwise,
frame
must
not
have
a
@id
property;
continue
to
the
next
step.
@id
property;
thus
the
"@id":
[]
pattern
would
never
match
any
node
object
.
the
"@id":
[{}]
pattern
would
match
any
node
object
and
is
equivalent
to
not
specifying
a
@id
property
in
frame
at
all
keyword
properties.
@type
:
@type
property
in
frame
includes
any
IRI
in
values
.
@type
property
in
frame
is
wildcard
.
@type
property
in
frame
is
match
none
.
@default
member
with
any
value,
and
any
other
property
in
node
has
a
non-default
match.
match
none
,
and
further
matching
is
aborted.
wildcard
.
value
pattern
(
value
pattern
):
property
matching
is
determined
using
the
Value
matching
algorithm
.
The
Value
Pattern
Matching
Algorithm
is
used
as
part
of
the
Framing
and
Frame
Matching
algorithms.
A
value
object
matches
a
value
pattern
using
the
and
match
none
patterns
on
wildcard
@value
,
@type
,
and
@language
,
in
addition
to
allowing
a
specific
value
to
match
a
set
of
values
defined
using
the
array
form
for
each
value
object
property.
The
algorithm
takes
a
value
pattern
(
pattern
)
and
value
object
(
value
)
as
parameters.
Value
matches
pattern
using
the
following
algorithm:
@value
,
@type
,
and
@language
in
value
,
or
null
if
none
exists.
@value
,
@type
,
and
@language
in
value
pattern
,
or
null
if
none
exists.
wildcard
,
or:
wildcard
,
and
wildcard
,
or
null
,
or
t1
is
null
and
t2
is
null
or
match
none
,
and
wildcard
,
or
null
,
or
l1
is
null
and
l2
is
null
or
match
none
.
This API provides a clean mechanism that enables developers to convert JSON-LD data into 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.
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 1.1 API [ JSON-LD11-API ].
[Constructor]
interface JsonLdProcessor {
static Promise<JsonLdDictionary> frame(
JsonLdInput input,
(JsonLdDictionary or USVString) frame,
optional JsonLdOptions? options);
};
The
JsonLdProcessor
interface
frame()
method
Frames
the
given
input
using
frame
according
to
the
steps
in
the
Framing
Algorithm
:
ordered
set
to
false
.
expand
method
using
frame
and
options
with
expandContext
set
to
null
,
the
frameExpansion
option
set
to
true
,
and
the
ordered
option
set
to
false
.
@context
from
frame
,
if
it
exists,
or
to
a
new
empty
context
,
otherwise.
null
.
@graph
set
the
frameDefault
option
to
options
with
the
value
true
.
input
;
either
in
the
form
of
an
dictionary
or
as
IRI
.
The
JsonLdFramingError
type
is
used
to
report
processing
errors.
dictionaryJsonLdFramingError{JsonLdFramingErrorCodecode; USVString?message= null; }; enumJsonLdFramingErrorCode{ "invalid frame", "invalid @embed value" };
JSON-LD Framing extends the error interface and codes defined in the JSON-LD 1.1 API [ JSON-LD11-API ].
code
message
The
JsonLdFramingErrorCode
represents
the
collection
of
valid
JSON-LD
Framing
error
codes.
invalid
@embed
value
@embed
is
not
one
recognized
for
the
object
embed
flag
.
invalid
frame
This section describes datatype definitions used within the JSON-LD API.
The JsonLdContext type is used to refer to a value that that may be a dictionary , a string representing an IRI , or an array of dictionaries and strings .
See JsonLdContext definition in the JSON-LD 1.1 API [ JSON-LD11-API ].
The
JsonLdOptions
type
is
used
to
pass
various
options
to
the
JsonLdProcessor
methods.
dictionaryJsonLdOptions{ (JsonLdEmbedor boolean)embed= "@last"; booleanexplicit= false; booleanomitDefault= false; booleanomitGraph; booleanrequireAll= false; booleanframeDefault= false; booleanordered= false; }; enumJsonLdEmbed{ "@always", "@last", "@never" };
In addition to those options defined in the JSON-LD 1.1 API [ JSON-LD11-API ], framing defines these additional options:
embed
true
sets
the
flag
to
@last
,
while
an
value
of
false
sets
the
flag
to
@never
.
explicit
frameDefault
omitDefault
omitGraph
false
if
processing
mode
if
json-ld-1.0
,
true
otherwise.
ordered
true
,
certain
algorithm
processing
steps
where
indicated
are
ordered
lexicographically.
If
false
,
order
is
not
considered
in
processing.
requireAll
JsonLdEmbed
enumerates
the
values
of
the
embed
option:
@always
@last
@embed
nor
object
embed
flag
is
not
specified.
@never
See JsonLdOptions definition in the JSON-LD 1.1 API [ JSON-LD11-API ].
This section is included merely for standards community review and will be submitted to the Internet Engineering Steering Group if this specification becomes a W3C Recommendation.
A
JSON-LD
Frame
uses
the
same
MIME
media
type
described
in
[
JSON-LD11
]
along
with
a
required
profile
parameter.
profile
A single URI identifying the resource as a JSON-LD Frame . A profile does not change the semantics of the resource representation when processed without profile knowledge, so that clients both with and without knowledge of a profiled resource can safely use the same representation.
http://www.w3.org/ns/json-ld#framed
Since
a
JSON-LD
frame
is
intended
to
specify
be
a
deterministic
layout
pure
data
exchange
format
for
a
JSON-LD
graph,
directed
graphs,
the
serialization
SHOULD
NOT
be
passed
through
a
code
execution
mechanism
such
as
JavaScript's
eval()
function.
function
to
be
parsed.
An
(invalid)
document
may
contain
code
that,
when
executed,
could
lead
to
unexpected
side
effects
compromising
the
security
of
a
system.
When processing JSON-LD documents, links to remote contexts are typically followed automatically, resulting in the transfer of files without the explicit request of the user for each one. If remote contexts are served by third parties, it may allow them to gather usage patterns or similar information leading to privacy concerns. Specific implementations, such as the API defined in the JSON-LD 1.1 Processing Algorithms and API specification [ JSON-LD11-API ], may provide fine-grained mechanisms to control this behavior.
JSON-LD
contexts
that
are
loaded
from
the
Web
over
non-secure
connections,
such
as
HTTP,
run
the
risk
of
being
altered
by
an
attacker
such
that
they
may
modify
the
JSON-LD
active
context
in
a
way
that
could
compromise
security.
It
is
RECOMMENDED
advised
that
any
application
that
depends
on
a
conforming
parser
does
not
attempt
remote
context
for
mission
critical
purposes
vet
and
cache
the
remote
context
before
allowing
the
system
to
directly
evaluate
use
it.
Given
that
JSON-LD
allows
the
substitution
of
long
IRIs
with
short
terms,
JSON-LD
frame
and
instead
purely
parse
documents
may
expand
considerably
when
processed
and,
in
the
input
into
a
language-native
worst
case,
the
resulting
data
structure.
might
consume
all
of
the
recipient's
resources.
Applications
should
treat
any
data
with
due
skepticism.
Fragment
identifiers
have
no
meaning
used
with
application/ld-frame+json
application/ld+json
resources.
are
treated
as
in
RDF
syntaxes,
as
per
RDF
1.1
Concepts
and
Abstract
Syntax
[
RDF11-CONCEPTS
].
Consider requirements from Self-Review Questionnaire: Security and Privacy .
This section is non-normative.
[Constructor] interfaceJsonLdProcessor{ static Promise<JsonLdDictionary>frame( JsonLdInput input, (JsonLdDictionary or USVString) frame, optionalJsonLdOptions? options); }; dictionaryJsonLdFramingError{JsonLdFramingErrorCodecode; USVString?message= null; }; enumJsonLdFramingErrorCode{ "invalid frame", "invalid @embed value" }; dictionaryJsonLdOptions{ (JsonLdEmbedor boolean)embed= "@last"; booleanexplicit= false; booleanomitDefault= false; booleanomitGraph; booleanrequireAll= false; booleanframeDefault= false; booleanordered= false; }; enumJsonLdEmbed{ "@always", "@last", "@never" };
This section is non-normative.
The following is a list of issues open at the time of publication.
This section is non-normative.
@embed
)
can
take
on
different
values
to
better
control
object
embedding.
wildcard
and
match
none
can
be
used
for
type
and
property
values.
@value
,
@type
,
and
@language
can
use
wildcard
and
match
none
and
may
also
use
a
set
of
specific
strings
to
match
(e.g.,
a
set
of
specific
languages).
@reverse
.
@id
to
allow
for
matching
specific
objects
in
a
frame.
json-ld-1.1
,
@id
members
with
blank
node
identifiers
used
only
for
that
@id
are
removed.
@link
and
in-memory
object
linking.
omitDefault
API
option
and/or
the
current
processing
mode
.
ordered
option,
defaulting
to
false
This
is
used
in
algorithms
to
control
interation
of
dictionary
member
keys.
Previously,
the
algorithms
always
required
such
an
order.
The
instructions
for
evaluating
test
results
have
been
updated
accordingly.
@reverse
,
or
a
term
defined
with
@reverse
,
which
can
cause
nodes
referencing
a
node
targeted
by
a
frame
to
have
a
reverse
reference
created.
This section is non-normative.
ordered
option,
defaulting
to
false
This
is
used
in
algorithms
to
control
interation
of
dictionary
member
keys.
Previously,
the
algorithms
always
required
such
an
order.
The
instructions
for
evaluating
test
results
have
been
updated
accordingly.
application/ld-frame+json
to
application/ld+json
with
a
required
profile
parameter.
This section is non-normative.
This 1.1 version of the specification is a product of deliberations by the members of the JSON-LD 1.1 Working Group chaired by Robert Sanderson and Benjamin Young along with members of the Working Group: Adam Soroka, Alejandra Gonzalez Beltran, Axel Polleres, Christopher Allen, Dan Brickley, Dave Longley, David Lehn, David Newbury, Harold Solbrig, Ivan Herman, Jeff Mixter, Leonard Rosenthol, Manu Sporny, Matthias Kovatsch, Sebastian Käbisch, Simon Steyskal, Steve Blackmon, Timothy Cole, Victor Charpenay, and Gregg Kellogg.
A large amount of thanks goes out to the JSON-LD Community Group's participants who worked through many of the technical issues on the mailing list and the weekly telecons: Chris Webber, David Wood, Drummond Reed, Eleanor Joslin, Farbian Gandon, Herm Fisher, Jamie Pitts, Kim Hamilton Duffy, Niklas Lindström, Paolo Ciccarese, Paul Frazze, Paul Warren, Rego Gmür, Rob Trainer, Ted Thibodeau Jr., and Victor Charpenay.