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
Copyright © 2010-2020 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
JSON-LD Framing allows developers to query by example and force a specific tree layout to a JSON-LD document.
This 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.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document has been developed by the JSON-LD Working Group and was derived from the JSON-LD Community Group's Final Report.
There is a live JSON-LD playground that is capable of demonstrating the features described in this document.
This document was published by the JSON-LD Working Group as a Recommendation.
GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to [email protected] (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.
This document is one of three JSON-LD 1.1 Recommendations produced by the JSON-LD Working Group:
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. A Frame can be used by a developer on a JSON-LD document to specify a deterministic layout for a graph.
Using delimiters around a chunk of data is known as "framing".
JSON-LD uses JSON delimiters such as {
and }
to
separate statements about a particular subject. JSON-LD also allows subjects
to reference other subjects through the use of their identifiers, expressed
as strings.
However, given that JSON-LD represents one or more graphs of information, there is more than one way to frame the statements about several related subjects into a whole document. In fact, a graph of information can be thought of as a long list of independent statements (aka triples) that are not bundled together in any way.
The
JSON-LD Framing API
enables a developer to specify exactly how they would like data to be framed,
such that statements about a particular subject are bundled together,
delimited via {
and }
, and such that the subjects
they relate to "nest" into a particular tree structure that matches what
their application expects.
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:
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.
This section is non-normative.
There are a number of ways that one may participate in the development of this specification:
This section is non-normative.
The following typographic conventions are used in this specification:
markup
markup definition reference
markup external definition reference
Notes are in light green boxes with a green left border and with a "Note" header in green. Notes are always informative.
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.
This document uses the following terms as defined in external specifications and defines terms specific to JSON-LD.
Terms imported from ECMAScript Language Specification [ECMASCRIPT], The JavaScript Object Notation (JSON) Data Interchange Format [RFC8259], Infra Standard [INFRA], and Web IDL [WEBIDL]
true
and false
that are used
to express one of two possible states.In the internal representation a JSON object is described as a map (see [INFRA]), composed of entries with key/value pairs.
In the Application Programming Interface, a map is described using a [WEBIDL] record.
@context
where the value,
or the @id
of the value, is null
,
explicitly decouples a term's association with an IRI.
A map entry in the body of a JSON-LD document
whose value is null
has the same meaning as if the map entry was not defined.
If @value
, @list
, or @set
is set to null
in expanded form,
then the entire JSON object is ignored.true
, or false
.Terms imported from Internationalized Resource Identifiers (IRIs) [RFC3987]
@type
,
and values of terms 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]
_:
._:
.rdf:langString
, an optional language tag.@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.
@default
key.true
or false
,
a typed value,
or a language-tagged string.
It represents an RDF literal.
@value
, @list
, or @set
keywords, or@graph
and @context
.@id
key.@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.@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.
@value
entry.
See the Value Objects section of JSON-LD 1.1 for a normative description.@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.The Following terms are used within specific algorithms.
true
,
and the reverse flag defaults to false
.
@graph
entry,
or only if required to represent multiple node objects.This specification adds a number of keywords (framing keywords) to the ones defined in the JSON-LD 1.1 Syntax specification [JSON-LD11]:
@default
@embed
@embed
as the following:
@always
@once
@embed
nor object embed flag
is specified.
ordered
flag is true
,
this will be the first node object encountered,
otherwise, it may be any node object.@never
Any other value for @embed
is invalid and indicates that an
invalid @embed value
error has been detected and processing is aborted.
@explicit
@null
null
should be returned, which would otherwise be removed when
Compacting.@omitDefault
@requireAll
All JSON-LD tokens and keywords are case-sensitive.
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.
This section is non-normative.
Framing is used to shape the data in a JSON-LD document, using an example frame document which is used to both match the flattened data and show an example of how the resulting data should be shaped. Matching is performed by using properties present in in the frame to find objects in the data that share common values. Matching can be done either using all properties present in the frame, or any property in the frame. By chaining together objects using matched property values, objects can be embedded within one another.
A frame also includes a context, which is used for compacting the resulting framed output.
For example, assume the following JSON-LD frame:
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"contains": {
"@type": "Book",
"contains": {
"@type": "Chapter"
}
}
}
This frame document describes an embedding structure that would place objects with type Library at the top, with objects of type Book that were linked to the library object using the contains property embedded as property values. It also places objects of type Chapter within the referencing Book object as embedded values of the Book object.
When using a flattened set of objects that match the frame components:
{
"@context": {
"@vocab": "http://example.org/",
"contains": {"@type": "@id"}
},
"@graph": [{
"@id": "http://example.org/library",
"@type": "Library",
"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:
If processing mode is not json-ld-1.0
, or the omit graph flag is true
,
the top-level @graph
entry may be omitted.
{
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"@type": "Library",
"location": "Athens",
"contains": {
"@id": "http://example.org/library/the-republic",
"@type": "Book",
"creator": "Plato",
"title": "The Republic",
"contains": {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
}
}
}
The Framing Algorithm does this by
first expanding both the input frame and document. It then creates
a map of flattened subjects. The outer-most node object within the frame
is used to match objects in the map, in this case looking for node objects
which have an @type
of Library
, and a
contains
property with another
frame used to match values of that property. The input document contains
exactly one such node object. The value of contains also has
a node object, which is then treated as a frame to match the set of subjects
which are contains
values of the Library
object, and so forth.
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
.
{ "@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.
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.
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
.
{ "@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.
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
.
{ "@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.
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.
{
"@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
):
{ "@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:
@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:
{ "@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:
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.
{ "@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:
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.
{ "@context": {"@vocab": "http://example.org/"} }
This generates the following framed results:
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).
The value of the property in the frame is not otherwise used in the output document. It's purpose is for frame matching and finding default values. Note the description value for Library in the following example.
{ "@context": {"@vocab": "http://example.org/"}, "@type": "Library", "description": "A great Library.", "contains": { "@type": "Book", "description": {"@default": "A great book."}, "contains": { "@type": "Chapter" } } }
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.
{ "@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.
{
"@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"
}]
}
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.
Framing flags set using keywords have effect only for the frame in which they appear, and for implicit frames which are created for objects where no frame object exists.
This section is non-normative.
The object embed flag determines if a referenced
node object is embedded as a property value of a referencing
object, or kept as a node reference.
The initial value for the object embed flag is set using the
option.
Consider the following frame
based on the default embed
@once
value of the object embed flag:
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library"
}
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
flag is ordered
true
.
However, if the @embed
property is added explicitly with a
value of @never
, the values for Book and Chapter will be excluded.
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"contains": {
"@type": "Book",
"@embed": "@never"
}
}
To illustrate the case where @once
does not expand values,
consider an alternate library example where books are doubly indexed.
{
"@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"
}]
}
When framed using the same frame with the default @embed
of @once
,
only the "books" property will have content,
if the
flag is ordered
true
,
and the "contains" property will use a reference.
If we use a frame using "@embed": "@always"
,
both properties will include expanded values.
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"@embed": "@always"
}
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
option.explicit
For example, take an expanded version of the library frame which include some properties from the input, but omit others.
{ "@context": {"@vocab": "http://example.org/"}, "@type": "Library", "description": {}, "contains": { "@type": "Book", "@explicit": true, "title": {}, "contains": { "@type": "Chapter" } } }
The resulting output will exclude properties for Book which are not explicitly listed in the frame object:
Note that the Library object contains a null
description property, as it is explicitly called for in the frame
using "description": {}
. The creator property does
not exist in the output, because it is not explicit.
This section is non-normative.
The omit default flag changes the way framing generates output when a property
described in the frame is not present in the input document.
The initial value for the omit default flag is set using the
option.
See § 2.2 Default content for a further discussion.omitDefault
Consider the following input document:
{ "@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
:
{ "@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:
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:
{ "@context": { "@vocab": "http://example.org/", "child": {"@type": "@id"} }, "@type": "Person", "child": { "@embed": "@always", "@omitDefault": true } }
Which yields this (desirable) output:
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
option, or based on
the processing mode; if processing mode is omitGraph
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
.
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.
{ "@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:
This section is non-normative.
A frame may include @reverse
, or a value of a term defined using @reverse
to invert the relationships in the output object. For example, the
Library example can be inverted using the following frame:
{ "@context": { "@vocab": "http://example.org/", "within": {"@reverse": "contains"} }, "@type": "Chapter", "within": { "@type": "Book", "within": { "@type": "Library" } } }
Using the flattened library example above, results in the following:
There is an asymmetry between regular properties and reverse properties. Normally, when framing a node object, unless the explicit inclusion flag is set, all properties of the node are included in the output, but reverse properties are not, as they are not actually properties of the node.
To include reverse properties in the output, add them explicitly to the frame. Note that if the reverse relationship does not exist, it will simply be left out of the output.
This section is non-normative.
Frames can include @graph
, which allows information from named graphs
contained within a JSON-LD document to be exposed within it's proper
graph context. By default, framing uses a merged graph, composed of all
the node objects across all graphs within the input. By using @graph
within a frame, the output document can include information specifically
from named graphs contained within the input document.
The following example uses a variation on our library theme where information
is split between the default graph, and a graph named http://example.org/graphs/books
:
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"contains": {
"@id": "http://example.org/graphs/books",
"@graph": {
"@type": "Book"
}
}
}
[{
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/graphs/books",
"@graph": [{
"@id": "http://example.org/library/the-republic",
"@type": "http://example.org/Book",
"http://example.org/contains": {
"@id": "http://example.org/library/the-republic#introduction"
},
"http://example.org/creator": "Plato",
"http://example.org/title": "The Republic"
}, {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "http://example.org/Chapter",
"http://example.org/description": "An introductory chapter on The Republic.",
"http://example.org/title": "The Introduction"
}]
}, {
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"@type": "http://example.org/Library",
"http://example.org/contains": {"@id": "http://example.org/graphs/books"},
"http://example.org/name": "Library"
}]
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, 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,
a 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.
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.
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.
A valid JSON-LD Frame is a superset of a valid JSON-LD document, allowing additional content, which is preserved through expansion. The Grammar defined in the JSON-LD 1.1 Syntax specification [JSON-LD11] is extended as follows:
@default
MAY include the value @null
,
or an array containing only @null
, in addition to other values
allowed in the grammar for values of entry keys expanding to IRIs.
Processors MUST preserve this value when expanding. All other entries of
a default object MUST be ignored.@id
and @type
may also be an empty map,
an IRI reference,
array containing only an empty map,
or an array of IRI references.
Values of @type
MAY also be a map with
a @default
entry, whose values are restricted by be IRIs.
Processors MUST preserve this value when expanding.@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.The framing algorithm takes
five required input variables and one optional input variable.
The required inputs are
a framing state (state),
a list of subjects to frame,
an input frame (expanded frame),
a parent used to collect partial frame results,
and an active property.
The optional input variable is the
flag.ordered
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
.
invalid frame
error has been detected and processing is aborted.
@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.@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.@embed
, @explicit
, and @requireAll
in frame.ordered
flag is true
:
@id
and id.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.
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.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.@graph
entry,
set recurse to true
, unless graph name in state is @merged
and set subframe to a new empty map.@graph
in frame,
or a new empty map, if it does not exist, and
set recurse to true
, unless id
is @merged
or @default
.true
:
false
.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.
@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.
ordered
flag is true
:
true
,
processors MUST NOT add any values for property to output, and the following
steps are skipped.@list
, then each
listitem in the list is processed in sequence and added to a new list map
in output:
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.@list
in list.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.@omitDefault
with a value of true
,
or does not contain @omitDefault
and the value of
the omit default flag in state is true
.@preserve
and
a value that is a copy of the value of @default
in
frame if it exists, or the string @null
otherwise.@reverse
, then
for each reverse property and sub frame that are the values of @reverse
in frame:
@reverse
property in output with a new map reverse dict as its value.@id
of id:
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.The Frame Matching Algorithm is used as part of the Framing algorithm
to determine if a particular node object matches the criteria set in a frame.
In general, a node object matches a frame if it meets the matches on @type
,
@id
,
or if it matches given one of several different properties.
If the require all flag is true
, all properties must have defaults
or match for the frame to match.
As matching is performed on expanded node objects, all values will be in the form of an array.
Node matching uses a combination of JSON constructs to match any, zero, or some specific values:
[]
(match none
)[frame object]
(node pattern
)[IRI+]
@type
and @id
,
which allows a match on any of the listed IRIs.[value object]
(value pattern
)@value
, @type
, and @language
may also be an array of one or more string values,
values of @language
are compared without regard to case..{}
(wildcard
)The frame matching algorithm takes the framing state (state), a list of subjects to match from the map of flattened subjects (subjects), a frame to match against (frame), and the requireAll flag and returns a list of matched subjects by filtering each node in subjects as follows:
All properties, including @id
and @type
, but no other keywords are considered
when matching a frame.
@id
:
@id
property in frame includes any IRI in values.@type
property in frame is wildcard
or match none
.@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@type
:
@type
property in frame includes any IRI in values.@type
property in frame is wildcard
.@type
property in frame is match none
.@type
property in frame is a default object.@id
or @type
and does not match,
node does not match, and processing is terminated.@default
entry with any value,
and any other property in node has a non-default match.match none
, and further matching is aborted.wildcard
.value pattern
(value pattern):
property matching is determined using the Value matching algorithm. The Value Pattern Matching Algorithm is used as part of the Framing
and Frame Matching algorithms. A value object
matches a value pattern using the
and match none
patterns on wildcard
@value
, @type
, and
@language
, in addition to allowing a specific value to match a
set of values defined using the array form for each value
object property.
The algorithm takes a value pattern
(pattern) and value object (value) as parameters.
Value matches pattern using the following algorithm:
@value
, @type
, and @language
in value, or null if none exists,
where values of @language
are normalized to lower case..@value
, @type
, and @language
in value pattern, or null if none exists,
where string values of @language
are normalized to lower case..wildcard
, or:
wildcard
, andwildcard
, or null, or t1 is null
and t2 is null or match none
, andwildcard
, or null, or l1 is null
and l2 is null or match none
.This API provides a clean mechanism that enables developers to convert JSON-LD data into a variety of output formats that are easier to work with in various programming languages. If a JSON-LD API is provided in a programming environment, the entirety of the following API MUST be implemented.
The JSON-LD API uses Promises to represent the result of the various deferred operations. Promises are defined in [ECMASCRIPT]. General use within specifications can be found in [promises-guide]. Implementations MAY chose to implement in an appropriate way for their native environments as long as they generally use the same methods, arguments, and options and return the same results.
Interfaces are marked [Exposed=JsonLd]
,
which creates a global interface.
The use of WebIDL in JSON-LD, while appropriate for use within browsers,
is not limited to such use.
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
and processing is stopped.code
WebIDL/* * The JsonLd interface is created to expose the JsonLdProcessor interface. */ [Global=JsonLd, Exposed=JsonLd
] interfaceJsonLd
{}; [Exposed=JsonLd
] interfaceJsonLdProcessor
{constructor
(); static Promise<JsonLdRecord
>frame
(JsonLdInput
input,JsonLdInput
frame, optionalJsonLdOptions
options = {}); };
The JsonLdProcessor
interface
frame()
method
Frames
the given input
using frame
according to the steps in the Framing
Algorithm:
Promise
promise and return it. The
following steps are then executed asynchronously.ordered
set to false
.true
,
and theordered
set to false
.@context
from remote frame or frame, if it exists, or to
a new empty context, otherwise.documentUrl
from remote frame, if available, otherwise to the base
option
from options.null
.@graph
set the frameDefault
option to options with the
value true
.embed
with the default value @once
.false
explicit
with the default value false
.requireAll
with the default value false
.omitDefault
with the default value false
.@default
if frameDefault
is true
,
otherwise to false
.@merged
,
add en entry for @merged
in graph map set
to the result of the Merge Node Maps algorithm
passing graph map.
null
as active property.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.@preserve
with the first value of that entry.
@preserve
with that value.compact
method using
active context,
inverse context,
null
for active property,
results as element,,
and the compactArrays
and ordered
flags from options.
@graph
and value is compacted results.@context
entry to compacted results and set its value
to the provided context.@null
values in compacted results with null
.
If, after replacement, an array contains only the value null
remove that value, leaving
an empty array.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.input
; either
in the form of an map or as IRI.JsonLdOptions
type defines default option values.WebIDLtypedef 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.
WebIDLtypedef (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
,
a sequence
of JsonLdRecords,
a 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].
The JsonLdFramingError
type is used to report processing errors.
WebIDLdictionaryJsonLdFramingError
{JsonLdFramingErrorCode
code
; USVString?message
= null; }; enumJsonLdFramingErrorCode
{ "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
message
The JsonLdFramingErrorCode
represents the collection of valid JSON-LD Framing error
codes.
invalid @embed value
@embed
is not one recognized for the object embed flag.
invalid frame
This section describes datatype definitions used within the JSON-LD API.
The JsonLdContext type is used to refer to a value that that may be a 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].
The JsonLdOptions
type is used to pass various options to the
JsonLdProcessor
methods.
WebIDLdictionaryJsonLdOptions
{ (JsonLdEmbed
or boolean)embed
= "@once"; booleanexplicit
= false; booleanomitDefault
= false; booleanomitGraph
; booleanrequireAll
= false; booleanframeDefault
= false; booleanordered
= false; }; enumJsonLdEmbed
{ "@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
true
sets the flag to
@once
, while a value of false
sets the flag
to @never
.explicit
frameDefault
omitDefault
omitGraph
false
if processing mode is json-ld-1.0
, true
otherwise.ordered
true
, certain algorithm
processing steps where indicated are ordered lexicographically.
If false
, order
is not considered in processing.requireAll
JsonLdEmbed
enumerates the values of the
option:embed
@always
@never
@once
@embed
nor object embed flag
is specified.See JsonLdOptions definition in the JSON-LD 1.1 API [JSON-LD11-API].
See, Privacy Considerations in [JSON-LD11].
See, Internationalization Considerations in [JSON-LD11].
This section is included merely for standards community review and will be submitted to the Internet Engineering Steering Group if this specification becomes a W3C Recommendation.
A JSON-LD Frame uses the same MIME media type described in [JSON-LD11]
along with a required profile
parameter.
profile
A single URI identifying the resource as a JSON-LD Frame. A profile does not change the semantics of the resource representation when processed without profile knowledge, so that clients both with and without knowledge of a profiled resource can safely use the same representation.
http://www.w3.org/ns/json-ld#framed
The http://www.w3.org/ns/json-ld#framed
SHOULD
be used when serving and requesting a JSON-LD frame document.
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.
Fragment identifiers used with application/ld+json are treated as in RDF syntaxes, as per RDF 1.1 Concepts and Abstract Syntax [RDF11-CONCEPTS].
This section is non-normative.
WebIDL/* * The JsonLd interface is created to expose the JsonLdProcessor interface. */ [Global=JsonLd, Exposed=JsonLd
] interfaceJsonLd
{}; [Exposed=JsonLd
] interfaceJsonLdProcessor
{constructor
(); static Promise<JsonLdRecord
>frame
(JsonLdInput
input,JsonLdInput
frame, optionalJsonLdOptions
options = {}); }; typedef record<USVString, any>JsonLdRecord
; typedef (JsonLdRecord
or sequence<JsonLdRecord
> or USVString or RemoteDocument)JsonLdInput
; dictionaryJsonLdFramingError
{JsonLdFramingErrorCode
code
; USVString?message
= null; }; enumJsonLdFramingErrorCode
{ "invalid frame
", "invalid @embed value
" }; dictionaryJsonLdOptions
{ (JsonLdEmbed
or boolean)embed
= "@once"; booleanexplicit
= false; booleanomitDefault
= false; booleanomitGraph
; booleanrequireAll
= false; booleanframeDefault
= false; booleanordered
= false; }; enumJsonLdEmbed
{ "@always
", "@once
", "@never
" };
This section is non-normative.
The following is a list of issues open at the time of publication.
Allow class-scoped framing.
Several frames in the same frame document?
Reframing Relationships.
This section is non-normative.
@embed
) can take on different
values to better control object embedding.wildcard
and match none
can be used for type and property values.@value
, @type
, and @language
can use wildcard
and match none
and may also use a set of specific strings to match (e.g., a set of specific
languages).@reverse
.@id
to allow for matching
specific objects in a frame.json-ld-1.0
,
@id
entries with blank node identifiers
used only for that @id
are removed.@link
and in-memory object linking.omitDefault
API option and/or
the current processing mode.ordered
option, defaulting to false
This is used in algorithms to
control iteration of map entry keys. Previously, the
algorithms always required such an order. The instructions for
evaluating test results have been updated accordingly.@reverse
, or a term
defined with @reverse
, which can cause nodes referencing a
node targeted by a frame to have a reverse reference created.This section is non-normative.
ordered
option, defaulting to false
This is used in algorithms to
control iteration of map entry keys. Previously, the
algorithms always required such an order. The instructions for
evaluating test results have been updated accordingly.application/ld-frame+json
to
application/ld+json
with a required profile
parameter.@id
and @type
.@first
and @last
values for the
object embed flag in favor of @once
.json-ld-1.1
, unless set
explicitly to json-ld-1.0
.@type
can have a default value, which is not used for
frame matching purposes.This section is non-normative.
JsonLdProcessor
processing steps.This section is non-normative.
[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.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:
Additionally, the following people were members of the Working Group at the time of publication:
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.