JSON-LD 1.1 Framing
JSON-LD 1.1 Framing
An Extension to the Application Programming Interface for the JSON-LD Syntax
W3C Recommendation
16 July 2020
This version:
Latest published version:
Latest editor's draft:
Test suite:
Implementation report:
Previous version:
Editors:
Dave Longley
Digital Bazaar
(v1.0 and v1.1)
Gregg Kellogg
(v1.0 and v1.1)
Pierre-Antoine Champin
LIRIS - Université de Lyon
(v1.1)
Former editors:
Manu Sporny
Digital Bazaar
(v1.0)
Markus Lanthaler
Google
(v1.0)
Authors:
Dave Longley
Digital Bazaar
(v1.0)
Manu Sporny
Digital Bazaar
(v1.0)
Gregg Kellogg
(v1.0 and v1.1)
Markus Lanthaler
Google
(v1.0)
Niklas Lindström
(v1.0)
Participate:
GitHub w3c/json-ld-framing
File a bug
Commit history
Pull requests
Please check the
errata
for any errors or
issues reported since publication.
See also
translations
This document is also available in this non-normative format:
EPUB
2010-2020
W3C
MIT
ERCIM
Keio
Beihang
).
W3C
liability
trademark
and
permissive document license
rules
apply.
Abstract
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 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
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 a
Recommendation.
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
This document has been reviewed by
W3C
Members, by software developers, and
by other
W3C
groups and interested parties, and is endorsed by the Director
as a
W3C
Recommendation. It is a stable document and may be used as
reference material or cited from another document.
W3C
's role in making the
Recommendation is to draw attention to the specification and to promote its
widespread deployment. This enhances the functionality and interoperability
of the Web.
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 March 2019
W3C
Process Document
Set of Documents
This document is one of three JSON-LD 1.1 Recommendations produced by the
JSON-LD Working Group
JSON-LD 1.1
JSON-LD 1.1 Processing Algorithms and API
JSON-LD 1.1 Framing
1.
Introduction
This section is non-normative.
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.
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
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:
Technical discussion typically occurs on the public mailing list:
public-json-ld-wg@w3.org
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.
definition reference
A reference to a definition
in this document
is underlined and is also an active link to the definition itself.
markup definition reference
A 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.
external definition reference
A reference to a definition
in another document
is underlined, in italics, and is also an active link to the definition itself.
markup external definition reference
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.
hyperlink
A hyperlink is underlined and in blue.
reference
A document reference (normative or informative) is enclosed in square brackets
and links to the references section.
Changes from Recommendation
Sections or phrases changed from the previous Recommendation
may be
highlighted
using a control
in
1.1
How to Read this Document
Note
Notes are in light green boxes with a green left border and with a "Note" header in green.
Notes are always informative.
Example
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.
Terms imported from Other Specifications
Terms imported from
ECMAScript Language Specification
ECMASCRIPT
],
The JavaScript Object Notation (JSON) Data Interchange Format
RFC8259
],
Infra Standard
INFRA
], and
Web IDL
WEBIDL
array
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
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.
boolean
The values
true
and
false
that are used
to express one of two possible states.
JSON object
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.
In the
internal representation
JSON object
is described as a
map
(see [
INFRA
]),
composed of
entries
with key/value pairs.
In the
Application Programming Interface
map
is described using a [
WEBIDL
record
null
The use of the
null
value within JSON-LD
is used to ignore or reset values.
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
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.
number
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
number
is equivalent to either a
long
or
double
depending on if the number has a non-zero fractional part (see [
WEBIDL
]).
scalar
A scalar is either a
string
number
true
, or
false
string
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.
Terms imported from
Internationalized Resource Identifiers (IRIs)
RFC3987
IRI
The absolute form of an
IRI
containing a
scheme
along with a
path
and optional
query
and
fragment
segments.
IRI
reference
Denotes the common usage of an
Internationalized Resource Identifier
An
IRI
reference
may be absolute or
relative
However, the "
IRI
" that results from such a reference only includes absolute
IRIs
any
relative
IRI
references
are resolved to their absolute form.
relative
IRI
reference
A relative
IRI
reference is an
IRI
reference
that is relative to some other
IRI
typically the
base
IRI
of the document.
Note that
properties
values of
@type
and values of
defined to be
vocabulary relative
are resolved relative to the
vocabulary mapping
not the
base
IRI
Terms imported from
RDF 1.1 Concepts and Abstract Syntax
RDF11-CONCEPTS
],
RDF Schema 1.1
RDF-SCHEMA
], and
Linked Data Design Issues
LINKED-DATA
base
IRI
The
base
IRI
is an
IRI
established in the
context
or is based on the
JSON-LD document
location.
The
base
IRI
is used to turn
relative
IRI
references
into
IRIs
blank node
node
in a
graph
that is neither an
IRI
nor a
literal
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
_:
blank node identifier
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
_:
dataset
dataset
representing a collection of
RDF graphs
including exactly one
default graph
and zero or more
named graphs
datatype
IRI
datatype
IRI
is an
IRI
identifying a datatype that determines how the lexical form maps to a
literal value
default graph
The
default graph
of a
dataset
is an
RDF graph
having no
name
, which may be empty.
graph name
The
IRI
or
blank node
identifying a
named graph
language-tagged string
language-tagged string
consists of a string and a non-empty language tag
as defined by [
BCP47
].
The
language tag
must be well-formed
according to
section 2.2.9 Classes of Conformance
of [
BCP47
].
Processors may normalize
language tags
to lowercase.
Linked Data
A set of documents, each containing a representation of a
linked data graph
or
dataset
list
list
is an ordered sequence of
IRIs
blank nodes
, and
literals
literal
An
object
expressed as a value such as a
string
or
number
Implicitly or explicitly includes a
datatype
IRI
and, if the datatype is
rdf:langString
, an optional
language tag
named graph
named graph
is a
linked data graph
that is identified by an
IRI
or
blank node
node
node
in an
RDF graph
, either the
subject
and
object
of at least one
triple
Note that a
node
can play both roles (
subject
and
object
) in a
graph
, even in the same
triple
object
An
object
is a
node
in a
linked data graph
with at least one incoming edge.
property
The name of a directed-arc in a
linked data graph
Every
property
is directional
and is labeled with an
IRI
or a
blank node identifier
Whenever possible, a
property
should be labeled with an
IRI
Note
The use of
blank node identifiers
to label properties is obsolete,
and may be removed in a future version of JSON-LD.
Also, see
predicate
in [
RDF11-CONCEPTS
].
RDF graph
A labeled directed
graph
i.e., a set of
nodes
connected by directed-arcs.
Also called
linked data graph
resource
resource
denoted by an
IRI
, a
blank node
or
literal
representing something in the world (the "universe of discourse").
subject
subject
is a
node
in a
linked data graph
with at least one outgoing edge,
related to an
object
node through a
property
triple
A component of an
RDF graph
including a
subject
predicate
, and
object
, which represents
a node-arc-node segment of an
RDF graph
JSON-LD Specific Term Definitions
active context
context
that is used to resolve
while the processing algorithm is running.
base direction
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.
context
A set of rules for interpreting a
JSON-LD document
as described in the
The Context
section of JSON-LD 1.1,
and normatively specified in the
Context Definitions
section of JSON-LD 1.1.
default object
default object
is a
map
that has a
@default
key.
frame
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.
frame object
A frame object is a
map
element within a
frame
which represents a specific portion of the
frame
matching either
node object
or a
value object
in the input.
See the
Frame Objects
section of JSON-LD 1.1 for a normative description.
JSON-LD document
JSON-LD document
is a serialization of
an
RDF dataset
See the
JSON-LD Grammar
section in JSON-LD 1.1 for a formal description.
JSON-LD internal representation
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
JSON-LD Processor
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.
JSON-LD value
JSON-LD value
is a
string
number
true
or
false
typed value
or a
language-tagged string
It represents an
RDF literal
keyword
string
that is specific to JSON-LD,
described in the
Syntax Tokens and Keywords
section of JSON-LD 1.1,
and normatively specified in the
Keywords
section of JSON-LD 1.1,
node object
node object
represents zero or more
properties
of a
node
in the
graph
serialized by the
JSON-LD document
map
is a
node object
if it exists outside of the JSON-LD
context
and:
it does not contain the
@value
@list
, or
@set
keywords, or
it is not the top-most
map
in the JSON-LD document
consisting of no other
entries
than
@graph
and
@context
The
entries
of a
node object
whose keys are not keywords are also called
properties
of the
node object
See the
Node Objects
section of JSON-LD 1.1 for a normative description.
node reference
node object
used to reference a node having only the
@id
key.
processing mode
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
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
JSON-LD 1.0
via the
json-ld-1.1
processing mode
scoped context
scoped context
is part of an
expanded term definition
using the
@context
entry
. It has the same form as an
embedded context
When the term is used as a type, it defines a
type-scoped context
when used as a property it defines a
property-scoped context
typed value
typed value
consists of a value,
which is a
string
and a type,
which is an
IRI
value object
value object
is a
map
that has an
@value
entry
See the
Value Objects
section of JSON-LD 1.1 for a normative description.
vocabulary mapping
The vocabulary mapping is set in the
context
using the
@vocab
key
whose value must be an
IRI
, a
compact
IRI
, a
term
, or
null
See the
Context Definitions
section of JSON-LD 1.1 for a normative description.
1.4.1
Algorithm Terms
The Following terms are used within specific algorithms.
active property
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
explicit inclusion flag
A flag specifying that for
properties
to be included in the output,
they must be explicitly declared in the matching
frame
framing state
map
containing values for
the
object embed flag
the
require all flag
the
embedded flag
used internally to help determine if object embedding is appropriate,
the
explicit inclusion flag
and the
omit default flag
input frame
The initial
Frame
provided to the framing algorithm.
IRI
compacting
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
JSON-LD input
The JSON-LD data structure that is provided as input to the algorithm.
map of flattened subjects
A map of subjects that is the result of the
Node Map Generation algorithm
object embed flag
A flag specifying that
node objects
should be directly embedded in the output,
instead of being referred to by their
IRI
omit default flag
A flag specifying that properties that are missing from the
JSON-LD input
but present in the
input frame
should be omitted from the output.
omit graph flag
A flag that determines if framing output is always contained within a
@graph
entry
or only if required to represent multiple
node objects
require all flag
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.
Note
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.
@never
Always use a
node reference
when serializing matching values.
Any other value for
@embed
is invalid and indicates that an
invalid @embed value
error has been detected and processing is aborted.
@explicit
Used in
Framing
to override the
value of
explicit inclusion flag
within a specific frame.
@null
Used in
Framing
when a value of
null
should be returned, which would otherwise be removed when
Compacting
@omitDefault
Used in
Framing
to override the
value of
omit default flag
within a specific frame.
@requireAll
Used in
Framing
to override the
value of
require all flag
within a specific frame.
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.
frame
also includes a
context
, which is used for compacting the resulting
framed output.
For example, assume the following JSON-LD frame:
Example
: Sample library 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:
Example
: Flattened library objects
"@context": {
"@vocab": "http://example.org/",
"contains": {"@type": "@id"}
},
"@graph": [{
"@id": "http://example.org/library",
"@type": "Library",
"location": "Athens",
"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:
Example
: Framed library objects
Open in playground
"@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"
If
processing mode
is not
json-ld-1.0
, or the
omit graph flag
is
true
the top-level
@graph
entry
may be omitted.
Example
: Framed library objects
"@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
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
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
Example
: Library frame with property matching
"@context": {"@vocab": "http://example.org/"},
"location": "Athens"
"contains": {
"title": "The Republic"
"contains": {
"title": "The Introduction"
This will generate the same framed results as when selecting on
@type
as the property values are unique to each node
object
Example
: Framed library objects with property matching
Open in playground
"@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"
See
2.3.5
Require all flag
to see how matching can be restricted to match
node objects
containing
all, versus any such listed property.
2.1.2
Wildcard Matching
This section is non-normative.
The empty
map
{}
) is used as a
wildcard
, which will
match a property if it exists in a target
node object
, independent of any specific value.
For example, the following frame selects object based on property
wildcarding, rather than
@type
Example
: Library frame with wildcard matching
"@context": {"@vocab": "http://example.org/"},
"location": {}
"contains": {
"creator": {}
"contains": {
"description": {}
This will generate the same framed results as when selecting on
@type
as the matched properties are distinct to each
node object
Example
: Framed library objects with wildcard matching
Open in playground
"@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"
2.1.3
Match on the Absence of a Property
This section is non-normative.
The empty
array
[]
) is used for
match none
, which will
match a node object only if a property does not exist in a target
node object
For example, the following frame selects object based on the absence of properties,
rather than
@type
Example
10
: Library frame with absent matching
"@context": {"@vocab": "http://example.org/"},
"creator": []
"title": []
"contains": {
"location": []
"description": []
"contains": {
"location": []
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.
Example
11
: Framed library objects with wildcard matching
Open in playground
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"@type": "Library",
"location": "Athens",
"creator": null
← This property is added
"title": null
← This property is added
"contains": {
"@id": "http://example.org/library/the-republic",
"@type": "Book",
"creator": "Plato",
"description": null
← This property is added
"location": null
← This property is added
"title": "The Republic",
"contains": {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"location": null
← This property is added
"title": "The Introduction"
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.
Example
12
: Multilingual library objects
"@context": {
"@vocab": "http://example.org/",
"contains": {"@type": "@id"}
},
"@graph": [{
"@id": "http://example.org/library",
"@type": "Library",
"location": [
{"@value": "Athens", "@language": "en"},
{"@value": "Αθήνα", "@language": "grc"},
{"@value": "Athína", "@language": "el-Latn"}
],
"contains": "http://example.org/library/the-republic"
}, {
"@id": "http://example.org/library/the-republic",
"@type": "Book",
"creator": [
{"@value": "Plato", "@language": "en"},
{"@value": "Πλάτων", "@language": "grc"},
{"@value": "Plátōn", "@language": "el-Latn"}
],
"title": [
{"@value": "The Republic", "@language": "en"},
{"@value": "Πολιτεία", "@language": "grc"},
{"@value": "Res Publica", "@language": "el-Latn"}
],
"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"
}]
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
):
Example
13
: Library frame with language matching
"@context": {"@vocab": "http://example.org/"},
"location": {"@value": {}, "@language": "el-Latn"},
"contains": {
"creator": {"@value": {}, "@language": "el-Latn"},
"title": {"@value": {}, "@language": "el-Latn"},
"contains": {
"title": "The Introduction"
This generates the following framed results:
Example
14
: Framed library objects with wildcard matching
Open in playground
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"@type": "Library",
"location": {"@value": "Athína", "@language": "el-Latn"},
"contains": {
"@id": "http://example.org/library/the-republic",
"@type": "Book",
"creator": {"@value": "Plátōn", "@language": "el-Latn"},
"title": {"@value": "Res Publica", "@language": "el-Latn"},
"contains": {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
2.1.5
Matching on
@id
This section is non-normative.
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:
Example
15
: Library frame with @id matching
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"contains": {
"@id": "http://example.org/library/the-republic",
"contains": {
"@id": "http://example.org/library/the-republic#introduction"
This generates the following framed results:
Example
16
: Framed library objects with @id matching
Open in playground
"@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"
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
"@context": {"@vocab": "http://example.org/"},
"@id": ["http://example.org/home", "http://example.org/library"],
"contains": {
"@id": ["http://example.org/library/the-republic"],
"contains": {
"@id": ["http://example.org/library/the-republic#introduction"]
This generates the following framed results:
Example
18
: Framed library objects with @id matching
Open in playground
"@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"
2.1.6
Empty Frame
This section is non-normative.
An empty frame matches any node object, even if those
objects are embedded elsewhere, causing them to be serialized at the top level.
Example
19
: Empty frame
"@context": {"@vocab": "http://example.org/"}
This generates the following framed results:
Example
20
: Framed library objects with empty frame
Open in playground
"@context": {"@vocab": "http://example.org/"},
"@graph": [{
"@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"
}, {
"@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"
}, {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
}]
2.2
Default content
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
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).
Note
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"
Example
22
: Sample library output with @default value
Open in playground
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"@type": "Library",
"description": null
"location": "Athens",
"contains": {
"@id": "http://example.org/library/the-republic",
"@type": "Book",
"creator": "Plato",
"description": "A great book.",
"title": "The Republic",
"contains": {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
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
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"contains": {
"@type": {"@default": "Book"}
"creator": "Plato",
"contains": {
"@type": {"@default": "Chapter"}
"description": "An introductory chapter on The Republic."
Data missing specific values for
@type
, but which matches based on
other property values.
Example
24
: Typeless library objects
"@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",
"creator": "Plato",
"title": "The Republic",
"contains": "http://example.org/library/the-republic#introduction"
}, {
"@id": "http://example.org/library/the-republic#introduction",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
}]
Example
25
: Sample library output with @default type
Open in playground
"@context": {"@vocab": "http://example.org/"},
"@graph": [{
"@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",
"description": "A great book.",
"title": "The Republic"
}]
2.3
Framing Flags
This section is non-normative.
Framing can be controlled using
API options
or by adding framing
keywords
within the
frame
as
described in
1.5
Syntax Tokens and Keywords
Note
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.
2.3.1
Object Embed Flag
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
@once
value of the
object embed flag
Example
26
: Sample library frame with implicit @embed set to @once
"@context": {"@vocab": "http://example.org/"},
"@type": "Library"
Example
27
: Framed library objects with @embed set to @once
Open in playground
"@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"
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
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"contains": {
"@type": "Book",
"@embed": "@never"
Example
29
: Framed library objects with @embed set to @never
Open in playground
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"@type": "Library",
"location": "Athens",
"contains": {
"@id": "http://example.org/library/the-republic"
To illustrate the case where
@once
does not expand values,
consider an alternate library example where books are doubly indexed.
Example
30
: Flattened library objects with double index
"@context": {
"@vocab": "http://example.org/",
"books": {"@type": "@id"},
"contains": {"@type": "@id"}
},
"@graph": [{
"@id": "http://example.org/library",
"@type": "Library",
"books": "http://example.org/library/the-republic",
"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"
}]
Example
31
: Framed library objects with double index
Open in playground
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"@type": "Library",
"contains": {
"@id": "http://example.org/library/the-republic"
},
"books": {
"@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"
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
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"@embed": "@always"
Example
33
: Framed library objects with double index and @always
Open in playground
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"@type": "Library",
"books": {
"@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"
},
"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"
2.3.2
Explicit inclusion flag
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.
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
"@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
Example
35
: Framed library objects with @explicit set to true
Open in playground
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"@type": "Library",
"description": null
← This property is explicit
"location": "Athens",
"contains": {
"@id": "http://example.org/library/the-republic",
"@type": "Book",
"creator": "Plato", ← This property is omitted
"title": "The Republic",
"contains": {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
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.
2.3.3
Omit default flag
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
2.2
Default content
for a further discussion.
Consider the following input document:
Example
36
: Sample parent/child relationship data
"@context": {
"@vocab": "http://example.org/",
"child": {"@type": "@id"}
},
"@graph": [{
"@id": "http://example.org#John",
"@type": "Person",
"name": "John",
"child": "http://example.org#Jane"
}, {
"@id": "http://example.org#Jane",
"@type": "Person",
"name": "Jane"
}]
To illustrate where the
omit default flag
is useful, consider the following
frame, which does
not
use
@omitDefault
Example
37
: Sample parent/child relationship frame without @omitDefault
"@context": {
"@vocab": "http://example.org/",
"child": {"@type": "@id"}
},
"@type": "Person",
"child": {
"@embed": "@always"
The resulting output will include a "child" property with the value
null
, which may not always be desired:
Example
38
: Sample parent/child relationship output without @omitDefault
Open in playground
"@context": {
"@vocab": "http://example.org/",
"child": {"@type": "@id"}
},
"@graph": [{
"@id": "http://example.org#John",
"@type": "Person",
"name": "John",
"child": {
"@id": "http://example.org#Jane",
"@type": "Person",
"name": "Jane"
}, {
"@id": "http://example.org#Jane",
"@type": "Person",
"name": "Jane",
"child": null
}]
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
"@context": {
"@vocab": "http://example.org/",
"child": {"@type": "@id"}
},
"@type": "Person",
"child": {
"@embed": "@always",
"@omitDefault": true
Which yields this (desirable) output:
Example
40
: Sample parent/child relationship output with @omitDefault
Open in playground
"@context": {
"@vocab": "http://example.org/",
"child": {"@type": "@id"}
},
"@graph": [{
"@id": "http://example.org#John",
"@type": "Person",
"name": "John",
"child": {
"@id": "http://example.org#Jane",
"@type": "Person",
"name": "Jane"
}, {
"@id": "http://example.org#Jane",
"@type": "Person",
"name": "Jane"
↑ Does not include "child" property
}]
2.3.4
Omit graph flag
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
entry
, otherwise, the
@graph
entry
is used only
to describe multiple
node objects
, consistent with compaction.
See
4.1
Framing Algorithm
for a further discussion.
The result is the same as the original
Flattened library objects
example,
but a
@graph
at the top-level.
Example 5
shows the results
with the
omit graph flag
set to
true
, which is the default value when
the
processing mode
is set to the default
json-ld-1.1
The top-level object can be enclosed within
@graph
by setting the
processing mode
to
json-ld-1.0
or by setting the
omit graph flag
to
false
Example
41
: Framed library objects with @omitGraph set to false
Open in playground
"@context": {"@vocab": "http://example.org/"},
"@graph": [{
"@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"
}]
2.3.5
Require all flag
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.
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.
Example
42
: Frame with @requireAll
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"contains": {
"@requireAll": true,
"creator": {},
"title": {},
"contains": {
"@requireAll": true,
"description": {},
"title": {}
This will, again, reproduce the desired framed output:
Example
43
: Framed library objects with @requireAll set to true
Open in playground
"@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"
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:
Example
44
: Inverted library 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:
Example
45
: Inverted library output
Open in playground
"@context": {
"@vocab": "http://example.org/",
"within": {"@reverse": "contains"}
},
"@id": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction",
"within": {
"@id": "http://example.org/library/the-republic",
"@type": "Book",
"contains": {"@id": "http://example.org/library/the-republic#introduction"},
"creator": "Plato",
"title": "The Republic",
"within": {
"@id": "http://example.org/library",
"@type": "Library",
"location": "Athens",
"contains": {"@id": "http://example.org/library/the-republic"}
Note
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
Example
46
: Frame with named graphs
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"contains": {
"@id": "http://example.org/graphs/books",
"@graph": {
"@type": "Book"
Example
47
: Flattened Input with named graphs
[{
"@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"
}]
Example
48
: Framed output with named graphs
Open in playground
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"@type": "Library",
"name": "Library",
"contains": {
"@id": "http://example.org/graphs/books",
"@graph": {
"@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"
3.
Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words
MAY
MUST
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
Unless specified using
processingMode
API option,
the
processing mode
is set using the
@version
entry
in a local
context
and
affects the behavior of algorithms including
expansion
and
compaction
Once set, it is an error to attempt to change to a different processing mode,
and processors
MUST
generate,
processing mode conflict
error and abort further processing.
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.
Note
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
).
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
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:
Framing adds
framing keywords
which may be used as
entries
of a
node object
, which
MUST
be preserved when expanding.
Values of
entries
in a
frame object
that are not
keyword
MAY
also include a
default object
Values of
@default
MAY
include the value
@null
or an
array
containing only
@null
, in addition to other values
allowed in the grammar for values of
entry
keys expanding to
IRIs
Processors
MUST
preserve this value when expanding. All other
entries
of
default object
MUST
be ignored.
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
@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
framing state
state
),
a list of
subjects
to frame,
an
input frame
expanded frame
),
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.
Frame
MUST
be a
map
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
Initialize flags
embed
explicit
, and
requireAll
from
object embed flag
explicit inclusion flag
, and
require all flag
in
state
overriding from any property values
for
@embed
@explicit
, and
@requireAll
in
frame
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
Initialize
output
to a new
map
with
@id
and
id
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
If
recurse
is
true
Set the value of
graph name
in
state
to
id
Set the value of
embedded flag
in
state
to
false
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
Otherwise, append a copy of
item
to
active property
in
output
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.
For each
reverse id
and
node
in the
map of flattened subjects
that has the property
reverse property
containing a
node reference
with an
@id
of
id
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.
Note
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.
frame object
node pattern
A non-empty
frame object
, used to match specific values using recursive node matching.
IRI
+]
One or more strings in the form of an
IRI
, used for matching on
@type
and
@id
which allows a match on
any
of the listed IRIs.
value object
value pattern
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
),
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
Otherwise,
property
matches if the
@type
property in
frame
is
wildcard
or
match none
Note
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
Otherwise, if the value of
property
in
frame
is a
value pattern
value pattern
):
property matching is determined using the
Value matching algorithm
Otherwise, for any
node pattern
node pattern
) which is one of the values of
property
in
frame
Let
value subjects
be the list of subjects from the
map of flattened subjects
matching the
node object
values from
values
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.
Note
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
Promise
is
rejected with a
JsonLdFramingError
having an appropriate
code
and processing is stopped.
WebIDL
/*
* The JsonLd interface is created to expose the JsonLdProcessor interface.
*/
Global
=JsonLd
Exposed
JsonLd
interface
JsonLd
{};
Exposed
JsonLd
interface
JsonLdProcessor
constructor
();
static
Promise
JsonLdRecord
frame
JsonLdInput
input
JsonLdInput
frame
optional
JsonLdOptions
options
= {});
};
The
JsonLdProcessor
interface
frame()
method
Frames
the given
input
using
frame
according to the steps in the
Framing
Algorithm
Create a new
Promise
promise
and return it. The
following steps are then executed asynchronously.
If the provided
input
is a
RemoteDocument
initialize
remote document
to
input
Otherwise, if the provided
input
is a
string
representing the
IRI
of a remote document, await and dereference it as
remote document
using
LoadDocumentCallback
, passing
input
for
url
and the
extractAllScripts
option from
options
for
extractAllScripts
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
If the provided
frame
is a
RemoteDocument
initialize
remote frame
to
frame
Otherwise, if the provided
frame
is a
string
representing the
IRI
of a remote document, await and dereference it as
remote frame
using
LoadDocumentCallback
, passing
frame
for
url
and the
extractAllScripts
option from
options
for
extractAllScripts
Set
expanded frame
to the result of using the
expand
method either
remote frame
or
frame
if there is no
remote frame
for
input
options
the
frameExpansion
option set to
true
and the
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
documentUrl
from
remote frame
, if available, otherwise to the
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
Initialize
inverse context
to the result of performing the
Inverse Context Creation algorithm
If
frame
has a top-level
property which expands to
@graph
set the
frameDefault
option to
options
with the
value
true
Initialize a new
framing state
state
) to an empty
map
Set
object embed flag
in
state
to
embed
with the default value
@once
Set the
embedded flag
in
state
to
false
Set
explicit inclusion flag
in
state
to
explicit
with the default value
false
Set
require all flag
in
state
to
requireAll
with the default value
false
Set
omit default flag
in
state
to
omitDefault
with the default value
false
Set the
graph name
in
state
to
either
@default
if
frameDefault
is
true
otherwise to
false
Set the
graph map
in
state
to the result of performing the
Node Map Generation
algorithm on
expanded input
If
graph name
in
state
is
@merged
add en entry for
@merged
in
graph map
set
to the result of the
Merge Node Maps
algorithm
passing
graph map
Set
subject map
in
state
to the
map of flattened subjects
which is the value of
graph name
in
graph map
Initialize
results
as an empty
array
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
If the
processing mode
is not
json-ld-1.0
remove the
@id
entry
of each
node object
in
results
where the
entry
value is a
blank node identifier
which appears only once
in any property value within
results
Recursively, replace all
entries
in
results
where the key is
@preserve
with the first value of that
entry
Note
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
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
record
USVString
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
sequence
JsonLdRecord
> or
USVString
or
RemoteDocument
JsonLdInput
The
JsonLdInput
interface is used to refer to an input value
that that may be a
JsonLdRecord
sequence
of
JsonLdRecords
string
representing an
IRI
which can be dereferenced to retrieve a valid JSON document,
or an already dereferenced
RemoteDocument
When the value is a
JsonLdRecord
or sequence of
JsonLdRecords
the values are taken as their equivalent internal representation values,
where a
JsonLdRecord
is equivalent to a
map
and a sequence of
JsonLdRecords
is equivalent to an
array
of
maps
. The
map entries
are converted to their equivalents
in [
INFRA
].
5.2
Error Handling
The
JsonLdFramingError
type is used to report processing errors.
WebIDL
dictionary
JsonLdFramingError
JsonLdFramingErrorCode
code
USVString
message
= null;
};
enum
JsonLdFramingErrorCode
invalid frame
invalid @embed value
};
JSON-LD Framing extends the error interface and codes defined in
JSON-LD 1.1 Processing Algorithms and API
the JSON-LD 1.1 API [
JSON-LD11-API
].
code
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.
invalid @embed value
The value for
@embed
is not one recognized for the
object embed flag
invalid frame
The frame is invalid.
5.3
Data Structures
This section describes datatype definitions used within the JSON-LD API.
5.3.1
JsonLdContext
The
JsonLdContext
type is used to refer to a value that
that may be a
map
, a
string
representing an
IRI
, or an array of
maps
and
strings
See
JsonLdContext
definition in the JSON-LD 1.1 API [
JSON-LD11-API
].
5.3.2
JsonLdOptions
The
JsonLdOptions
type is used to pass various options to the
JsonLdProcessor
methods.
WebIDL
dictionary
JsonLdOptions
JsonLdEmbed
or
boolean
embed
= "@once";
boolean
explicit
= false;
boolean
omitDefault
= false;
boolean
omitGraph
boolean
requireAll
= false;
boolean
frameDefault
= false;
boolean
ordered
= false;
};
enum
JsonLdEmbed
@always
@once
@never
};
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
explicit
Sets the value
explicit inclusion flag
used in the
Framing Algorithm
frameDefault
Instead of framing a
merged graph
, frame only the
default graph
omitDefault
Sets the value
omit default flag
used in the
Framing Algorithm
omitGraph
Sets the value
omit graph flag
used in the
Framing Algorithm
. If not set explicitly,
it is set to
false
if
processing mode
is
json-ld-1.0
true
otherwise.
ordered
If set to
true
, certain algorithm
processing steps where indicated are ordered lexicographically.
If
false
, order
is not considered in processing.
requireAll
Sets the value
require all flag
used in the
Framing Algorithm
JsonLdEmbed
enumerates the values of the
embed
option:
@always
Always embed
node objects
as property values, unless this would
cause a circular reference.
@never
Always use a
node reference
when serializing matching values.
@once
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.
See
JsonLdOptions
definition in the JSON-LD 1.1 API [
JSON-LD11-API
].
6.
Security Considerations
See,
Security Considerations
in
A.
IANA Considerations
7.
Privacy Considerations
See,
Privacy Considerations
in [
JSON-LD11
].
8.
Internationalization Considerations
See,
Internationalization Considerations
in [
JSON-LD11
].
A.
IANA Considerations
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.
To specify a JSON-LD
Frame
The
SHOULD
be used when serving and requesting a JSON-LD frame document.
Encoding considerations:
See
RFC 8259, section 11
Security considerations:
See
RFC 8259, section 12
RFC8259
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:
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
Intended usage:
Common
Restrictions on usage:
None
Author(s):
Manu Sporny, Gregg Kellogg, Markus Lanthaler, Dave Longley
Change controller:
W3C
Fragment identifiers used with
application/ld+json
are treated as in RDF syntaxes, as per
RDF 1.1 Concepts and Abstract Syntax
RDF11-CONCEPTS
].
B.
IDL Index
This section is non-normative.
WebIDL
/*
* The JsonLd interface is created to expose the JsonLdProcessor interface.
*/
Global
=JsonLd
Exposed
JsonLd
interface
JsonLd
{};
Exposed
JsonLd
interface
JsonLdProcessor
constructor
();
static
Promise
JsonLdRecord
frame
JsonLdInput
input
JsonLdInput
frame
optional
JsonLdOptions
options
= {});
};
typedef
record
USVString
any
JsonLdRecord
typedef
JsonLdRecord
or
sequence
JsonLdRecord
> or
USVString
or
RemoteDocument
JsonLdInput
dictionary
JsonLdFramingError
JsonLdFramingErrorCode
code
USVString
message
= null;
};
enum
JsonLdFramingErrorCode
invalid frame
invalid @embed value
};
dictionary
JsonLdOptions
JsonLdEmbed
or
boolean
embed
= "@once";
boolean
explicit
= false;
boolean
omitDefault
= false;
boolean
omitGraph
boolean
requireAll
= false;
boolean
frameDefault
= false;
boolean
ordered
= false;
};
enum
JsonLdEmbed
@always
@once
@never
};
C.
Open Issues
This section is non-normative.
The following is a list of issues open at the time of publication.
Issue 29
: Allow class-scoped framing
defer-future-version
spec:enhancement
Allow class-scoped framing.
Issue 38
: Several frames in the same frame document?
defer-future-version
spec:enhancement
spec:substantive
Several frames in the same frame document?
Issue 73
: Reframing Relationships
defer-future-version
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.
If
processing mode
is not
json-ld-1.0
@id
entries
with
blank node identifiers
used only for that
@id
are removed.
The JSON syntax has been abstracted into an
internal representation
to allow for other serialization formats that are functionally equivalent
to JSON.
Preserved values are compacted using the properties of the referencing term.
Removed support for
@link
and in-memory object linking.
Added the
omit default flag
, controlled via the
omitDefault
API option and/or
the current
processing mode
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
This section is non-normative.
Removed duplicate
1.1
How to Read this Document
This is in response to
Issue 92
Improved algorithms in
4.1
Framing Algorithm
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.
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.
I.
References
I.1
Normative references
[BCP47]
Tags for Identifying Languages
. A. Phillips; M. Davis. IETF. September 2009. IETF Best Current Practice. URL:
[ECMASCRIPT]
ECMAScript Language Specification
. Ecma International. URL:
[INFRA]
Infra Standard
. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL:
[JSON-LD10]
JSON-LD 1.0
. Manu Sporny; Gregg Kellogg; Marcus Langhaler. W3C. 16 January 2014. W3C Recommendation. URL:
[JSON-LD11]
JSON-LD 1.1
. Gregg Kellogg; Pierre-Antoine Champin; Dave Longley. W3C. 7 May 2020. W3C Proposed Recommendation. URL:
[JSON-LD11-API]
JSON-LD 1.1 Processing Algorithms and API
. Gregg Kellogg; Dave Longley; Pierre-Antoine Champin. W3C. 7 May 2020. W3C Proposed Recommendation. URL:
[LINKED-DATA]
Linked Data Design Issues
. Tim Berners-Lee. W3C. 27 July 2006. W3C-Internal Document. URL:
[promises-guide]
Writing Promise-Using Specifications
. Domenic Denicola. W3C. 9 November 2018. TAG Finding. URL:
[RDF-SCHEMA]
RDF Schema 1.1
. Dan Brickley; Ramanathan Guha. W3C. 25 February 2014. W3C Recommendation. URL:
[RDF11-CONCEPTS]
RDF 1.1 Concepts and Abstract Syntax
. Richard Cyganiak; David Wood; Markus Lanthaler. W3C. 25 February 2014. W3C Recommendation. URL:
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels
. S. Bradner. IETF. March 1997. Best Current Practice. URL:
[RFC3987]
Internationalized Resource Identifiers (IRIs)
. M. Duerst; M. Suignard. IETF. January 2005. Proposed Standard. URL:
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
. B. Leiba. IETF. May 2017. Best Current Practice. URL:
[RFC8259]
The JavaScript Object Notation (JSON) Data Interchange Format
. T. Bray, Ed.. IETF. December 2017. Internet Standard. URL:
[WEBIDL]
Web IDL
. Boris Zbarsky. W3C. 15 December 2016. W3C Editor's Draft. URL:
I.2
Informative references
[JSON-LD10-FRAMING]
JSON-LD Framing 1.0
. Manu Sporny; Gregg Kellogg; David Longley; Marcus Langhaler. W3C. 30 August 2012. Unofficial Draft. URL: