JSON-LD
Framing
allows
developers
to
query
by
example
and
force
a
specific
tree
layout
to
a
JSON-LD
document.
This
specification
describes
a
superset
of
the
features
defined
in
JSON-LD
Framing
1.0
[
JSON-LD10-FRAMING
]
and,
except
where
noted,
the
algorithms
described
in
this
specification
are
fully
compatible
with
documents
created
using
the
previous
community
standard.
Status
of
This
Document
This
is
a
preview
Do
not
attempt
to
implement
this
version
of
the
specification.
Do
not
reference
this
version
as
authoritative
in
any
way.
Instead,
see
https://w3c.github.io/json-ld-framing/
for
the
Editor's
draft.
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/.
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
).
Please
see
the
Working
Group's
implementation
report
.
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.
JSON-LD
is
a
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
Linked
Data
which
describe
directed
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
one
or
more
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
)
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.
1.1
How
to
Read
this
Document
This
section
is
non-normative.
This
document
is
a
detailed
specification
for
a
serialization
of
Linked
Data
in
JSON.
The
document
is
primarily
intended
for
the
following
audiences:
Authors
who
want
to
query
JSON-LD
documents
to
create
representations
more
appropriate
for
a
given
use
case.
Software
developers
that
want
to
implement
processors
and
APIs
for
JSON-LD.
A
companion
document,
the
JSON-LD
1.1
specification
[
JSON-LD11
],
specifies
the
grammar
of
JSON-LD
documents.
To
understand
the
basics
in
this
specification
you
must
first
be
familiar
with
<a id=respec-offender-linking-error-not-matching-dfn-20 href="https://tools.ietf.org/html/rfc8259" class=respec-offending-element data-no-xref="" title="Linking error: not matching `
`">
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
document
can
highlight
changes
since
the
JSON-LD
1.0
version.
Select
to
changes.
1.2
Contributing
This
section
is
non-normative.
There
are
a
number
of
ways
that
one
may
participate
in
the
development
of
this
specification:
The
working
group
uses
#json-ld
IRC
channel
is
available
for
real-time
discussion
on
irc.w3.org
.
The
#json-ld
IRC
channel
is
also
available
for
real-time
discussion
on
irc.freenode.net.
1.3
Typographical
conventions
This
section
is
non-normative.
The
following
typographic
conventions
are
used
in
this
specification:
markup
Markup
(elements,
attributes,
properties),
machine
processable
values
(string,
characters,
media
types),
property
name,
or
a
file
name
is
in
red-orange
monospace
font.
variable
A
variable
in
pseudo-code
or
in
an
algorithm
description
is
in
italics.
definition
A
definition
of
a
term,
to
be
used
elsewhere
in
this
or
other
specifications,
is
in
bold
and
italics.
A
references
References
to
a
definition
in
this
document
,
when
the
reference
itself
is
also
a
markup,
is
underlined,
red-orange
monospace
font,
and
is
also
an
active
link
to
the
definition
itself.
A
reference
to
a
definition
in
another
document
,
when
the
reference
itself
is
also
a
markup,
is
underlined,
in
italics
red-orange
monospace
font,
and
is
also
an
active
link
to
the
definition
itself.
Examples are in light khaki boxes, with khaki left border,
and with a numbered "Example" header in khaki.
Examples are always informative. The content of the example is in monospace font and may be syntax colored.
Examples may have tabbed navigation buttons
to
show
the
results
of
transforming
an
example
into
other
representations.
1.4
Terminology
This
document
uses
the
following
terms
as
defined
in
external
specifications
and
defines
terms
specific
to
JSON-LD.
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
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
_:
.
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.
frame
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.
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.
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
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.
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
@version
entry
in
a
context
,
publishers
can
ensure
that
processors
conformant
with
<a id=respec-offender-linking-error-not-matching-dfn-21 href="https://www.w3.org/TR/2014/REC-json-ld-20140116/" class=respec-offending-element data-no-xref="" title="Linking error: not matching `
`">
JSON-LD
1.0
[
JSON-LD10
]
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
@version
entry
in
a
context
is
explicitly
set
to
1.1
.
This
specification
extends
<a id=respec-offender-linking-error-not-matching-dfn-22 href="https://www.w3.org/TR/2014/REC-json-ld-20140116/" class=respec-offending-element data-no-xref="" title="Linking error: not matching `
`">
JSON-LD
1.0
via
the
json-ld-1.1
processing
mode
.
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
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
key
entry
in
object
is
not
an
array
,
set
it
to
a
new
array
containing
the
original
value.
Append
value
to
the
value
of
the
key
entry
in
object
.
explicit
inclusion
flag
A
flag
specifying
that
for
properties
to
be
included
in
the
output,
they
must
be
explicitly
declared
in
the
matching
frame
.
Used
as
a
macro
within
various
algorithms
as
to
reduce
the
language
used
to
describe
the
process
of
compacting
a
string
var
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
string
value
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.
1.5
Syntax
Tokens
and
Keywords
This
specification
adds
a
number
of
keywords
(
framing
keywords
)
to
the
ones
defined
in
the
JSON-LD
1.1
Syntax
specification
[
JSON-LD11
]:
@default
Used
in
Framing
to
set
the
default
value
for
an
output
property
when
the
framed
node
object
does
not
include
such
a
property.
@embed
Used
in
Framing
to
override
the
value
of
object
embed
flag
within
a
specific
frame.
Valid
values
for
@embed
as
the
following:
@always
Always
embed
node
objects
as
property
values,
unless
this
would
cause
a
circular
reference.
@once
Just
a
single
value
within
a
given
node
object
should
be
embedded,
other
values
of
other
properties
use
a
node
reference
.
This
is
the
default
value
if
neither
@embed
nor
object
embed
flag
is
specified.
The
specific
node
object
chosen
to
embed
depends
on
ordering.
If
the
ordered
flag
is
true
,
this
will
be
the
first
node
object
encountered,
otherwise,
it
may
be
any
node
object.
All
JSON-LD
tokens
and
keywords
are
case-sensitive.
2.
Features
This
section
is
non-normative.
JSON-LD
1.1
introduces
new
features
that
are
compatible
with
JSON-LD
1.0
[
JSON-LD10
],
but
if
processed
by
a
JSON-LD
1.0
processor
may
produce
different
results.
Processors
default
to
json-ld-1.1
,
unless
the
processingMode
API
option
is
explicitly
set
to
json-ld-1.0
.
Publishers
are
encouraged
to
use
the
@version
map
entry
within
a
context
set
to
1.1
to
ensure
that
JSON-LD
1.0
processors
will
not
misinterpret
JSON-LD
1.1
features.
2.1
Framing
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.
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/"},
"@id": "http://example.org/library",
"@type": "Library",
"location": "Athens",
"contains": {
"@id": "http://example.org/library/the-republic",
"@type": "Book",
"creator": "Plato",
"title": "The Republic",
"contains": {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
}
}
}
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.
2.1.1
Matching
on
Properties
This
section
is
non-normative.
In
addition
to
matching
on
types,
a
frame
can
match
on
one
or
more
properties.
For
example,
the
following
frame
selects
object
based
on
property
values,
rather
than
@type
.
This
will
generate
the
same
framed
results
as
when
selecting
on
@type
,
the
property
that
is
excluded
uniquely
identifies
each
node
object
.
Note
that
additional
properties
with
the
value
null
are
added
for
those
properties
explicitly
excluded.
2.1.4
Matching
on
Values
This
section
is
non-normative.
Frames
can
be
matched
based
on
the
presence
of
specific
property
values.
These
values
can
themselves
use
wildcards
,
to
match
on
a
specific
or
set
of
values,
language
tags
,
types,
or
base
direction
.
For
an
example,
we'll
use
an
multilingual
version
of
the
library
example
with
more
complex
value
representations.
By
matching
on
an
attribute
of
a
value,
we
can
match
frames
having
that
attribute,
and
limit
results
to
property
values
that
match.
In
this
case,
we'll
frame
the
Library
and
Book
objects
on
values
only
in
latinized
Greek
(
el-Latn
):
Frames
can
be
matched
if
they
match
a
specific
identifier
(
@id
).
This
can
be
illustrated
with
the
original
Flattened
library
objects
input
using
a
frame
which
matches
on
specific
@id
values:
Frames
can
also
be
matched
from
an
array
of
identifiers.
Within
a
frame,
it
is
acceptable
for
@id
to
have
an
array
value,
where
the
individual
values
are
treated
as
IRIs
.
Example
17
:
Library
frame
with
array
@id
matching
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
,
or
as
a
value
of
@type
,
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
§
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.
Example
21
:
Sample
library
frame
with
@default
value
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"description": "A great Library.",
"contains": {
"@type": "Book",
"description": {"@default": "A great book."},
"contains": {
"@type": "Chapter"
}
}
}
Default
values
may
also
be
used
for
@type
,
similar
to
other
properties.
In
this
case,
a
matched
node
object
without
an
@type
will
take
the
value
of
the
default
object
from
the
frame
.
The
default
object
has
a
value
which
is
a
single
IRI
.
If
multiple
IRIs
are
specified,
only
the
first
will
be
used
as
the
default
type.
The
frame
matches
objects
having
specific
property
values,
and
provides
defaults
for
@type
for
matched
objects.
Example
23
:
Sample
library
frame
with
@default
type
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.
Because,
the
default
for
the
object
embed
flag
is
@once
(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,
assuming
that
the
ordered
flag
is
true
.
However,
if
the
@embed
property
is
added
explicitly
with
a
value
of
@never
,
the
values
for
Book
and
Chapter
will
be
excluded.
Example
28
:
Sample
library
frame
with
explicit
@embed
set
to
@never
When
framed
using
the
same
frame
with
the
default
@embed
of
@once
,
only
the
"books"
property
will
have
content,
if
the
ordered
flag
is
true
,
and
the
"contains"
property
will
use
a
reference.
If
we
use
a
frame
using
"@embed":
"@always"
,
both
properties
will
include
expanded
values.
Example
32
:
Sample
library
frame
with
explicit
@embed
set
to
@always
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.
If
true
,
only
properties
present
in
the
input
frame
will
be
placed
into
the
output.
The
initial
value
for
the
explicit
inclusion
flag
is
set
using
the
explicit
option.
For
example,
take
an
expanded
version
of
the
library
frame
which
include
some
properties
from
the
input,
but
omit
others.
Example
34
:
Sample
library
frame
with
@explicit
set
to
true
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
frame
using
"description":
{}
.
The
creator
property
does
not
exist
in
the
output,
because
it
is
not
explicit.
The
resulting
output
will
include
a
"child"
property
with
the
value
null
,
which
may
not
always
be
desired:
Note
that
because
the
option
"@embed":
"@always"
is
specified
in
the
frame
under
the
child
property,
that
"child":
null
appears
in
the
output
for
matches
that
do
not
have
that
property,
which
may
be
undesirable.
To
prevent
this
default
null
output
from
occurring,
the
@omitDefault
may
be
set
to
true
like
so:
Example
39
:
Sample
parent/child
relationship
frame
with
@omitDefault
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.
The
following
frame
matches
on
multiple
properties,
including
the
absence
of
a
property.
Using
the
Flattened
library
objects
example,
we
can
match
on
an
object
containing
both
the
title
and
description
or
title
and
creator
properties.
If
we
were
to
use
@requireAll
set
to
false
,
then
we
could
match
on
the
presence
of
any
property,
not
all
properties.
This
will,
again,
reproduce
the
desired
framed
output:
2.4
Reverse
Framing
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:
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.
2.5
Framing
Named
Graphs
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
:
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
,
SHOULD
,
and
SHOULD
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.
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
framing
test
suite
.
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.
4.
Framing
The
following
sections
describe
algorithms
for
framing
JSON-LD
documents.
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
).
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.
4.1
Framing
Algorithm
4.1.1
Overview
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:
The
values
of
@id
and
@type
may
also
be
an
empty
map
,
an
IRI
reference
,
array
containing
only
an
empty
map
,
or
an
array
of
IRI
references
.
Values
of
@type
MAY
also
be
a
map
with
a
@default
entry,
whose
values
are
restricted
by
be
IRIs
.
Processors
MUST
preserve
this
value
when
expanding.
Framing
either
operates
on
the
merged
node
definitions
contained
in
the
input
document,
or
on
the
default
graph
depending
on
if
the
input
frame
contains
the
@graph
entry
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
.
4.1.2
Algorithm
The
framing
algorithm
takes
five
required
input
variables
and
one
optional
input
variable.
The
required
inputs
are
a
framing
state
(
state
),
a
list
of
subjects
to
frame,
an
input
frame
(
expanded
frame
),
a
parent
used
to
collect
partial
frame
results,
and
an
active
property
.
The
optional
input
variable
is
the
ordered
flag.
The
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
map
.
Note
that
if
parent
is
an
array
,
active
property
MUST
be
null
,
and
if
it
is
a
map
,
it
MUST
NOT
be
null
.
If
frame
is
an
array
,
set
frame
to
the
value
of
the
array
,
which
MUST
be
a
valid
frame
.
If
frame
is
determined
to
be
invalid,
an
invalid
frame
error
has
been
detected
and
processing
is
aborted.
If
frame
has
an
@id
entry
,
its
value
MUST
be
either
an
array
containing
a
single
empty
map
as
a
value,
a
valid
IRI
or
an
array
where
all
values
are
valid
IRIs
.
If
frame
has
a
@type
entry
,
its
value
MUST
be
either
an
array
containing
a
single
empty
map
as
a
value,
an
array
containing
a
map
with
a
entry
whose
key
is
@default
,
a
valid
IRI
or
an
array
where
all
values
are
valid
IRIs
.
Create
a
list
of
matched
subjects
by
filtering
subjects
against
frame
using
the
Frame
Matching
algorithm
with
state
,
subjects
,
frame
,
and
requireAll
.
For
each
id
and
associated
node
object
node
from
the
set
of
matched
subjects,
ordered
lexicographically
by
id
if
the
optional
ordered
flag
is
true
:
If
the
embedded
flag
in
state
is
false
and
there
is
an
existing
embedded
node
in
parent
associated
with
graph
name
and
id
in
state
,
do
not
perform
additional
processing
for
this
node
.
Otherwise,
if
the
embedded
flag
in
state
is
true
and
either
embed
is
@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
.
Otherwise,
if
the
embedded
flag
in
state
is
true
,
embed
is
@once
,
and
there
is
an
existing
embedded
node
in
parent
associated
with
graph
name
and
id
in
state
,
add
output
to
parent
and
do
not
perform
additional
processing
for
this
node
.
If
graph
map
in
state
has
an
entry
for
id
:
If
frame
does
not
have
a
@graph
entry
,
set
recurse
to
true
,
unless
graph
name
in
state
is
@merged
and
set
subframe
to
a
new
empty
map
.
Otherwise,
set
subframe
to
the
first
entry
for
@graph
in
frame
,
or
a
new
empty
map
,
if
it
does
not
exist,
and
set
recurse
to
true
,
unless
id
is
@merged
or
@default
.
Invoke
the
algorithm
using
a
copy
of
state
with
the
value
of
graph
name
set
to
id
and
the
value
of
embedded
flag
set
to
false
,
the
keys
from
the
graph
map
in
state
associated
with
id
as
subjects
,
subframe
as
frame
,
output
as
parent
,
and
@graph
as
active
property
.
If
frame
has
an
@included
entry
,
invoke
the
algorithm
using
a
copy
of
state
with
the
value
of
embedded
flag
set
to
false
,
subjects
,
frame
,
output
as
parent
,
and
@included
as
active
property
.
For
each
property
and
objects
in
node
,
ordered
lexicographically
by
property
if
the
optional
ordered
flag
is
true
:
If
property
is
a
keyword
,
add
property
and
objects
to
output
.
Otherwise,
if
property
is
not
in
frame
,
and
explicit
is
true
,
processors
MUST
NOT
add
any
values
for
property
to
output
,
and
the
following
steps
are
skipped.
For
each
item
in
objects
:
If
item
is
a
map
with
the
property
@list
,
then
each
listitem
in
the
list
is
processed
in
sequence
and
added
to
a
new
list
map
in
output:
If
listitem
is
a
node
reference
,
invoke
the
algorithm
using
a
copy
of
state
with
the
value
of
embedded
flag
set
to
true
,
the
value
of
@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
map
with
properties
for
@embed
,
@explicit
and
@requireAll
taken
from
embed
,
explicit
and
requireAll
.
Otherwise,
append
a
copy
of
listitem
to
@list
in
list
.
If
item
is
a
node
reference
,
invoke
the
algorithm
using
a
copy
of
state
with
the
value
of
embedded
flag
set
to
true
,
the
value
of
@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
map
with
properties
for
@embed
,
@explicit
and
@requireAll
taken
from
embed
,
explicit
and
requireAll
.
For
each
non-
keyword
property
and
objects
in
frame
(other
than
`@type)
that
is
not
in
output
:
Let
item
be
the
first
value
in
objects
,
which
MUST
be
a
frame
object
.
Set
property
frame
to
the
first
value
in
objects
or
a
newly
created
frame
object
if
value
is
objects
.
property
frame
MUST
be
a
map
.
Skip
property
and
property
frame
if
property
frame
contains
@omitDefault
with
a
value
of
true
,
or
does
not
contain
@omitDefault
and
the
value
of
the
omit
default
flag
in
state
is
true
.
Add
property
to
output
with
a
new
map
having
a
property
@preserve
and
a
value
that
is
a
copy
of
the
value
of
@default
in
frame
if
it
exists,
or
the
string
@null
otherwise.
If
frame
has
the
property
@reverse
,
then
for
each
reverse
property
and
sub
frame
that
are
the
values
of
@reverse
in
frame
:
Create
a
@reverse
property
in
output
with
a
new
map
reverse
dict
as
its
value.
Add
reverse
property
to
reverse
dict
with
a
new
empty
array
as
its
value.
Invoke
the
algorithm
using
a
copy
of
state
with
the
value
of
embedded
flag
set
to
true
,
the
reverse
id
as
the
sole
item
in
a
new
subjects
array
,
sub
frame
as
frame
,
null
as
active
property
,
and
the
array
value
of
reverse
property
in
reverse
dict
as
parent
.
Once
output
has
been
set
are
required
in
the
previous
steps,
add
output
to
parent
.
4.2
Frame
Matching
Algorithm
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
,
@id
,
or
if
it
matches
given
one
of
several
different
properties.
If
the
require
all
flag
is
true
,
all
properties
must
have
defaults
or
match
for
the
frame
to
match.
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
)
An
empty
array
matches
no
values,
or
a
value
which
is,
itself,
an
empty
array.
A
value
object
,
used
to
match
a
specific
value.
Within
a
value
object
,
the
values
for
@value
,
@type
,
and
@language
may
also
be
an
array
of
one
or
more
string
values,
values
of
@language
are
compared
without
regard
to
case.
.
{}
(
wildcard
)
An
array
containing
an
empty
object
(after
excluding
any
properties
which
are
framing
keywords
)
matches
any
value
that
is
present,
and
does
not
match
if
there
are
no
values.
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:
All
properties,
including
@id
and
@type
,
but
no
other
keywords
are
considered
when
matching
a
frame.
node
matches
if
frame
has
no
properties.
If
requireAll
is
true
,
node
matches
if
all
properties
(
property
)
in
frame
match
any
of
the
following
conditions.
Or,
if
requireAll
is
false
,
if
any
of
the
properties
(
property
)
in
frame
match
any
of
the
following
conditions.
For
the
values
of
each
property
from
frame
in
node
:
If
property
is
@id
:
property
matches
if
the
@id
property
in
frame
includes
any
IRI
in
values
.
Framing
works
on
map
of
flattened
subjects
,
and
the
act
of
flattening
ensures
that
all
subjects
have
an
@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
Otherwise,
if
property
is
@type
:
property
matches
if
the
@type
property
in
frame
includes
any
IRI
in
values
.
Otherwise,
property
matches
if
values
is
not
empty
and
the
@type
property
in
frame
is
wildcard
.
Otherwise,
property
matches
if
values
is
empty
and
the
@type
property
in
frame
is
match
none
.
Otherwise,
property
matches
if
the
@type
property
in
frame
is
a
default
object
.
Otherwise,
property
does
not
match.
If
property
is
@id
or
@type
and
does
not
match,
node
does
not
match,
and
processing
is
terminated.
Otherwise,
the
value
of
property
in
frame
MUST
be
empty,
or
an
array
containing
a
valid
frame
.
property
matches
if
values
is
empty,
or
non
existent,
the
value
of
property
in
frame
is
a
map
containing
only
the
@default
entry
with
any
value,
and
any
other
property
in
node
has
a
non-default
match.
node
does
not
match
if
values
is
not
empty
and
the
value
of
property
in
frame
is
match
none
,
and
further
matching
is
aborted.
Otherwise,
property
matches
if
values
is
not
empty
and
the
value
of
property
in
frame
is
wildcard
.
Let
matched
subjects
be
the
result
of
calling
this
algorithm
recursively
using
state
,
value
subjects
for
subjects
,
node
pattern
for
frame
,
and
the
requireAll
flag.
property
matches
if
matched
subjects
is
not
empty.
Otherwise,
property
does
not
match.
4.3
Value
Pattern
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
match
none
and
wildcard
patterns
on
@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:
Let
v1
,
t1
,
and
l1
be
the
values
of
@value
,
@type
,
and
@language
in
value
,
or
null
if
none
exists,
where
values
of
@language
are
normalized
to
lower
case.
.
Let
v2
,
t2
,
and
l2
be
the
values
of
@value
,
@type
,
and
@language
in
value
pattern
,
or
null
if
none
exists,
where
string
values
of
@language
are
normalized
to
lower
case.
.
Value
matches
pattern
when
pattern
is
wildcard
,
or:
v1
is
in
v2
,
or
v1
is
not
null
and
v2
is
wildcard
,
and
t1
is
in
t2
,
or
t1
is
not
null
and
t2
is
wildcard
,
or
null
,
or
t1
is
null
and
t2
is
null
or
match
none
,
and
l1
is
in
l2
,
or
l1
is
not
null
and
l2
is
wildcard
,
or
null
,
or
l1
is
null
and
l2
is
null
or
match
none
.
5.
The
Application
Programming
Interface
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
API
uses
Promises
to
represent
the
result
of
the
various
deferred
operations.
Promises
are
defined
in
[
ECMASCRIPT
].
General
use
within
specifications
can
be
found
in
[
promises-guide
].
Implementations
MAY
chose
to
implement
in
an
appropriate
way
for
their
native
environments
as
long
as
they
generally
use
the
same
methods,
arguments,
and
options
and
return
the
same
results.
Interfaces
are
marked
[Exposed=JsonLd]
,
which
creates
a
global
interface.
The
use
of
WebIDL
in
JSON-LD,
while
appropriate
for
use
within
browsers,
is
not
limited
to
such
use.
5.1
JsonLdProcessor
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
].
It
is
important
to
highlight
that
implementations
do
not
modify
the
input
parameters.
If
an
error
is
detected,
the
<a id=respec-offender-linking-error-not-matching-dfn data-xref-type=_IDL_ class=respec-offending-element title="Linking error: not matching `
`">
Promise
is
rejected
with
a
JsonLdFramingError
having
an
appropriate
code
and
processing
is
stopped.
Create
a
new
<a id=respec-offender-linking-error-not-matching-dfn-3 data-xref-type=_IDL_ class=respec-offending-element title="Linking error: not matching `
`">
Promise
promise
and
return
it.
The
following
steps
are
then
executed
asynchronously.
Set
expanded
input
to
the
result
of
using
the
expand
method
either
remote
document
or
input
if
there
is
no
remote
document
for
input
and
options
with
ordered
set
to
false
.
Set
context
to
the
value
of
@context
from
remote
frame
or
frame
,
if
it
exists,
or
to
a
new
empty
context
,
otherwise.
Set
context
base
to
the
<a data-xref-for=RemoteDocument title="Linking error: not matching `
`" data-xref-type=attribute|dict-member class=respec-offending-element id=respec-offender-linking-error-not-matching-dfn-4 data-link-for=RemoteDocument>
documentUrl
from
remote
frame
,
if
available,
otherwise
to
the
<a data-xref-for=JsonLdOptions title="Linking error: not matching `
`" data-xref-type=attribute|dict-member class=respec-offending-element id=respec-offender-linking-error-not-matching-dfn-5 data-link-for=JsonLdOptions>
base
option
from
options
.
Initialize
active
context
to
the
result
of
the
Context
Processing
algorithm
passing
a
new
empty
context
as
active
context
context
as
local
context
,
and
context
base
as
base
URL
.
Initialize
an
active
context
using
context
;
the
base
IRI
is
set
to
the
base
option
from
options
,
if
set;
otherwise,
if
the
compactToRelative
option
is
true
,
to
the
IRI
of
the
currently
being
processed
document,
if
available;
otherwise
to
null
.
Invoke
the
Framing
algorithm
,
passing
state
,
the
keys
from
subject
map
in
state
for
subjects
,
expanded
frame
,
results
for
parent
,
and
null
as
active
property
.
Recursively,
replace
all
entries
in
results
where
the
key
is
@preserve
with
the
first
value
of
that
entry
.
The
value
of
the
entry
will
be
an
array
with
a
single
value;
this
will
effectively
replace
the
map
containing
@preserve
with
that
value.
Set
compacted
results
to
the
result
of
using
the
compact
method
using
active
context
,
inverse
context
,
null
for
active
property
,
results
as
element
,,
and
the
<a data-xref-for=JsonLdOptions title="Linking error: not matching `
`" data-xref-type=attribute|dict-member class=respec-offending-element id=respec-offender-linking-error-not-matching-dfn-6 data-link-for=JsonLdOptions>
compactArrays
and
ordered
flags
from
options
.
If
compacted
results
is
an
empty
array
,
replace
it
with
a
new
map
.
Otherwise,
if
compacted
results
is
an
array
,
replace
it
with
a
new
map
with
a
single
entry
whose
key
is
the
result
of
IRI
compacting
@graph
and
value
is
compacted
results
.
Add
an
@context
entry
to
compacted
results
and
set
its
value
to
the
provided
context
.
Recursively,
replace
all
@null
values
in
compacted
results
with
null
.
If,
after
replacement,
an
array
contains
only
the
value
null
remove
that
value,
leaving
an
empty
array.
If
omitGraph
is
false
and
compacted
results
does
not
have
a
top-level
@graph
entry
,
or
its
value
is
not
an
array
,
modify
compacted
results
to
place
the
non
@context
entry
of
compacted
results
into
a
map
contained
within
the
array
value
of
@graph
.
If
omitGraph
is
true
,
a
top-level
@graph
entry
is
used
only
to
contain
multiple
node
objects
.
Resolve
the
promise
with
compacted
results
,
transforming
compacted
results
from
the
internal
representation
to
a
JSON
serialization.
input
The
JSON-LD
object
or
array
of
JSON-LD
objects
to
perform
the
framing
upon
or
an
IRI
referencing
the
JSON-LD
document
to
frame.
frame
The
frame
to
use
when
re-arranging
the
data
of
input
;
either
in
the
form
of
an
map
or
as
IRI
.
options
A
set
of
options
that
MAY
affect
the
framing
algorithm
such
as,
e.g.,
the
input
document's
base
IRI
.
The
JsonLdOptions
type
defines
default
option
values.
WebIDL
typedef
<a id=respec-offender-linking-error-not-matching-dfn-24 data-xref-type=dfn href="https://heycam.github.io/webidl/" class=respec-offending-element title="Linking error: not matching `
`">
record
<
<a id=respec-offender-linking-error-not-matching-dfn-7 data-xref-type=_IDL_ class=respec-offending-element title="Linking error: not matching `
`">
USVString
,
<a id=respec-offender-linking-error-not-matching-dfn-8 data-xref-type=_IDL_ class=respec-offending-element title="Linking error: not matching `
`">
any
>
JsonLdRecord
;
The
JsonLdRecord
is
the
definition
of
a
map
used
to
contain
arbitrary
map
entries
which
are
the
result
of
parsing
a
JSON
Object
.
WebIDL
typedef
(
JsonLdRecord
or
<a id=respec-offender-linking-error-not-matching-dfn-25 data-xref-type=dfn href="https://heycam.github.io/webidl/" class=respec-offending-element title="Linking error: not matching `
`">
sequence
<
JsonLdRecord
>
or
<a id=respec-offender-linking-error-not-matching-dfn-9 data-xref-type=_IDL_ class=respec-offending-element title="Linking error: not matching `
`">
USVString
or
<a id=respec-offender-linking-error-not-matching-dfn-10 data-xref-type=_IDL_ class=respec-offending-element title="Linking error: not matching `
`">
RemoteDocument
)
JsonLdInput
;
The
JsonLdInput
interface
is
used
to
refer
to
an
input
value
that
that
may
be
a
JsonLdRecord
,
a
sequence
of
JsonLdRecords
,
a
string
representing
an
IRI
,
which
can
be
dereferenced
to
retrieve
a
valid
JSON
document,
or
an
already
dereferenced
RemoteDocument
.
a
string
representing
the
particular
error
type,
as
described
in
the
various
algorithms
in
this
document.
message
an
optional
error
message
containing
additional
debugging
information.
The
specific
contents
of
error
messages
are
outside
the
scope
of
this
specification.
The
JsonLdFramingErrorCode
represents
the
collection
of
valid
JSON-LD
Framing
error
codes.
In
addition
to
those
options
defined
in
the
JSON-LD
1.1
API
[
JSON-LD11-API
],
framing
defines
these
additional
options:
embed
Sets
the
value
object
embed
flag
used
in
the
Framing
Algorithm
.
A
boolean
value
of
true
sets
the
flag
to
@once
,
while
a
value
of
false
sets
the
flag
to
@never
.
Only
a
single
value
within
a
given
node
object
should
be
embedded,
other
values
of
other
properties
use
a
node
reference
.
This
is
the
default
value
if
neither
@embed
nor
object
embed
flag
is
specified.
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.
application/ld+json
Type
name:
application
Subtype
name:
ld+json
Required
parameters:
None
Optional
parameters:
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.
Since
JSON-LD
is
intended
to
be
a
pure
data
exchange
format
for
directed
graphs,
the
serialization
SHOULD
NOT
be
passed
through
a
code
execution
mechanism
such
as
JavaScript's
eval()
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
advised
that
any
application
that
depends
on
a
remote
context
for
mission
critical
purposes
vet
and
cache
the
remote
context
before
allowing
the
system
to
use
it.
Given
that
JSON-LD
allows
the
substitution
of
long
IRIs
with
short
terms,
JSON-LD
documents
may
expand
considerably
when
processed
and,
in
the
worst
case,
the
resulting
data
might
consume
all
of
the
recipient's
resources.
Applications
should
treat
any
data
with
due
skepticism.
As
JSON-LD
places
no
limits
on
the
IRI
schemes
that
may
be
used,
and
vocabulary-relative
IRIs
use
string
concatenation
rather
than
IRI
resolution,
it
is
possible
to
construct
IRIs
that
may
be
used
maliciously,
if
dereferenced.
Interoperability
considerations:
Not
Applicable
Published
specification:
https://www.w3.org/TR/json-ld11-framing
Applications
that
use
this
media
type:
Any
programming
environment
that
requires
the
exchange
of
directed
graphs.
Implementations
of
JSON-LD
have
been
created
for
JavaScript,
Python,
Ruby,
PHP,
and
C++.
Additional
information:
Magic
number(s):
Not
Applicable
File
extension(s):
.jsonld
Macintosh
file
type
code(s):
TEXT
Person
&
email
address
to
contact
for
further
information:
Ivan
Herman
<ivan@w3.org>
Intended
usage:
Common
Restrictions
on
usage:
None
Author(s):
Manu
Sporny,
Gregg
Kellogg,
Markus
Lanthaler,
Dave
Longley
The
following
is
a
list
of
issues
open
at
the
time
of
publication.
Allow
class-scoped
framing.
Several
frames
in
the
same
frame
document?
Reframing
Relationships.
D.
Changes
since
1.0
Draft
of
30
August
2012
This
section
is
non-normative.
There
are
numerous
formatting
and
terminology
changes
intended
to
align
with
the
1.0
Recommendations
of
JSON-LD
and
JSON-LD-API
in
addition
to
the
use
of
common
term
definition
sections.
The
object
embed
flag
(
@embed
)
can
take
on
different
values
to
better
control
object
embedding.
Framing
supports
More
specific
frame
matching
,
where
general
wildcard
and
match
none
can
be
used
for
type
and
property
values.
Frame
matching
also
supports
value
object
matching,
where
values
for
@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).
Framing
allows
specific
graphs
to
be
matched,
and
the
outer-most
frame
can
either
come
from
the
merged
graph
or
the
default
graph
.
Framing
supports
@reverse
.
Through
the
use
of
scoped
contexts
,
parts
of
a
frame
can
be
compacted
using
a
different
context
than
is
used
for
the
outer-most
object.
Frames
can
use
one
or
more
values
for
@id
to
allow
for
matching
specific
objects
in
a
frame.
The
API
now
adds
an
ordered
option,
defaulting
to
false
This
is
used
in
algorithms
to
control
iteration
of
map
entry
keys.
Previously,
the
algorithms
always
required
such
an
order.
The
instructions
for
evaluating
test
results
have
been
updated
accordingly.
Frames
may
include
reverse
properties
using
@reverse
,
or
a
term
defined
with
@reverse
,
which
can
cause
nodes
referencing
a
node
targeted
by
a
frame
to
have
a
reverse
reference
created.
E.
Changes
since
JSON-LD
Community
Group
Final
Report
This
section
is
non-normative.
The
API
now
adds
an
ordered
option,
defaulting
to
false
This
is
used
in
algorithms
to
control
iteration
of
map
entry
keys.
Previously,
the
algorithms
always
required
such
an
order.
The
instructions
for
evaluating
test
results
have
been
updated
accordingly.
The
IANA
registration
is
changed
from
application/ld-frame+json
to
application/ld+json
with
a
required
profile
parameter.
The
require
all
flag
now
needs
all
properties
to
be
present,
including
@id
and
@type
.
Removed
@first
and
@last
values
for
the
object
embed
flag
in
favor
of
@once
.
The
processing
mode
is
now
implicitly
json-ld-1.1
,
unless
set
explicitly
to
json-ld-1.0
.
In
a
frame
@type
can
have
a
default
value,
which
is
not
used
for
frame
matching
purposes.
F.
Changes
since
Candidate
Release
of
12
December
2019
Moved
non-recursive
portions
algorithms
into
the
JsonLdProcessor
processing
steps.
Remove
the
graph
stack
from
framing
state
as
being
unnecessary.
G.
Changes
since
Proposed
Recommendation
Release
of
7
May
2020
This
section
is
non-normative.
Changed
[Exposed=(Window,Worker)]
to
[Exposed=JsonLd]
,
which
is
declared
as
a
global
interface
in
order
to
expose
the
JsonLdProcessor
interface
for
non-browser
usage
to
address
review
suggestions.
H.
Changes
since
Recommendation
of
16
July
2020
This
section
is
non-normative.
Regenerated
definition
list,
which
does
not
attempt
to
filter
out
unused
definitions.
I.
Acknowledgements
This
section
is
non-normative.
The
editors
would
like
to
specially
thank
the
following
individuals
for
making
significant
contributions
to
the
authoring
and
editing
of
this
specification:
Timothy
Cole
(University
of
Illinois
at
Urbana-Champaign)
Gregory
Todd
Williams
(J.
Paul
Getty
Trust)
Ivan
Herman
(
W3C
Staff)
Jeff
Mixter
(OCLC
(Online
Computer
Library
Center,
Inc.))
David
Lehn
(Digital
Bazaar)
David
Newbury
(J.
Paul
Getty
Trust)
Robert
Sanderson
(J.
Paul
Getty
Trust,
chair)
Harold
Solbrig
(Johns
Hopkins
Institute
for
Clinical
and
Translational
Research)
Simon
Steyskal
(WU
(Wirschaftsuniversität
Wien)
-
Vienna
University
of
Economics
and
Business)
A
Soroka
(Apache
Software
Foundation)
Ruben
Taelman
(Imec
vzw)
Benjamin
Young
(Wiley,
chair)
Additionally,
the
following
people
were
members
of
the
Working
Group
at
the
time
of
publication:
Steve
Blackmon
(Apache
Software
Foundation)
Dan
Brickley
(Google,
Inc.)
Newton
Calegari
(NIC.br
-
Brazilian
Network
Information
Center)
Victor
Charpenay
(Siemens
AG)
Sebastian
Käbisch
(Siemens
AG)
Axel
Polleres
(WU
(Wirschaftsuniversität
Wien)
-
Vienna
University
of
Economics
and
Business)
Leonard
Rosenthol
(Adobe)
Jean-Yves
ROSSI
(CANTON
CONSULTING)
Antoine
Roulin
(CANTON
CONSULTING)
Manu
Sporny
(Digital
Bazaar)
Clément
Warnier
de
Wailly
(CANTON
CONSULTING)
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:
Chris
Webber,
David
Wood,
Drummond
Reed,
Eleanor
Joslin,
Fabien
Gandon,
Herm
Fisher,
Jamie
Pitts,
Kim
Hamilton
Duffy,
Niklas
Lindström,
Paolo
Ciccarese,
Paul
Frazze,
Paul
Warren,
Reto
Gmür,
Rob
Trainer,
Ted
Thibodeau
Jr.,
and
Victor
Charpenay.