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
https://www.w3.org/TR/.
There is a
live JSON-LD playground that is capable
of demonstrating the features described in this document.
This document was published by the JSON-LD Working Group as a
Proposed Recommendation.
This document is intended to become a W3C 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).
The W3C Membership and other interested
parties are invited to review the document and
send comments to
public-json-ld-wg@w3.org
(subscribe,
archives) through 18 June 2020. Advisory
Committee Representatives should consult their
WBS questionnaires. Note that substantive technical comments
were expected during the Candidate
Recommendation review period that ended
03 April 2020.
Publication as a Proposed Recommendation does not imply endorsement by the W3C
Membership. This is a draft document and may be updated, replaced or
obsoleted by other documents at any time. It is inappropriate to cite this
document as other than work in progress.
This document was produced by a group
operating under the
W3C Patent Policy.
W3C maintains a
public list of any patent disclosures
made in connection with the deliverables of
the group; that page also includes
instructions for disclosing a patent. An individual who has actual
knowledge of a patent which the individual believes contains
Essential Claim(s)
must disclose the information in accordance with
section 6 of the W3C Patent Policy.
JSON-LD is a lightweight syntax to serialize Linked Data [LINKED-DATA] in JSON [RFC8259].
Its design allows existing JSON to be interpreted as Linked Data with minimal changes.
As with other representations of Linked Data which describe directed graphs,
a single directed graph can have many different serializations, each expressing
exactly the same information. Developers typically work with trees, represented as
JSON objects. While mapping a graph to
a tree can be done, the layout of the end result must be specified in advance.
A Frame can be used by a developer on a JSON-LD document to
specify a deterministic layout for a graph.
Using delimiters around a chunk of data is known as "framing".
JSON-LD uses JSON delimiters such as { and } to
separate statements about a particular subject. JSON-LD also allows subjects
to reference other subjects through the use of their identifiers, expressed
as strings.
However, given that JSON-LD represents one or more graphs of information,
there is more than one way to frame the statements about several related
subjects into a whole document. In fact, a graph of information can be
thought of as a long list of independent statements (aka triples) that are not bundled together in any way.
The
JSON-LD Framing API
enables a developer to specify exactly how they would like data to be framed,
such that statements about a particular subject are bundled together,
delimited via { and }, and such that the subjects
they relate to "nest" into a particular tree structure that matches what
their application expects.
1.1 How to Read this Document
This section is non-normative.
This document is a detailed specification for a serialization of Linked
Data in JSON. The document is primarily intended for the following audiences:
Authors who want to query JSON-LD documents to create representations
more appropriate for a given use case.
Software developers that want to implement processors and APIs for JSON-LD.
A companion document, the JSON-LD 1.1 specification
[JSON-LD11], specifies the grammar of JSON-LD documents.
To understand the basics in this specification you must first be familiar with
JSON, which is detailed in [RFC8259].
You must also understand the JSON-LD 1.1 Syntax specification [JSON-LD11],
which is the base syntax used by all of the algorithms in this document,
and the JSON-LD 1.1 API [JSON-LD11-API].
To understand the API and how it is intended to operate in a programming environment,
it is useful to have working knowledge of
the JavaScript programming language [ECMASCRIPT]
and WebIDL [WEBIDL].
To understand how JSON-LD maps to RDF, it is helpful to be
familiar with the basic RDF concepts [RDF11-CONCEPTS].
This document can highlight changes since the JSON-LD 1.0 version.
Select to changes.
1.2 Contributing
This section is non-normative.
There are a number of ways that one may participate in the development of
this specification:
The working group uses #json-ld
IRC channel is available for real-time discussion on irc.w3.org.
The #json-ld
IRC channel is also available for real-time discussion on irc.freenode.net.
1.3 Typographical conventions
This section is non-normative.
The following typographic conventions are used in this specification:
markup
Markup (elements, attributes, properties),
machine processable values (string, characters, media types),
property name,
or a file name is in red-orange monospace font.
variable
A variable in pseudo-code or in an algorithm description is in italics.
definition
A definition of a term, to be used elsewhere in this or other specifications,
is in bold and italics.
A references to a definition in this document,
when the reference itself is also a markup, is underlined,
red-orange monospace font, and is also an active link to the definition itself.
A reference to a definition in another document,
when the reference itself is also a markup,
is underlined, in italics red-orange monospace font,
and is also an active link to the definition itself.
Examples are in light khaki boxes, with khaki left border,
and with a numbered "Example" header in khaki.
Examples are always informative. The content of the example is in monospace font and may be syntax colored.
Examples may have tabbed navigation buttons
to show the results of transforming an example into other representations.
1.4 Terminology
This document uses the following terms as defined in external specifications
and defines terms specific to JSON-LD.
In the JSON serialization,
an array structure is represented as square brackets surrounding zero or more values.
Values are separated by commas.
In the internal representation,
a list (also called an array) is an ordered collection of zero or more values.
While JSON-LD uses the same array representation as JSON,
the collection is unordered by default.
While order is preserved in regular JSON arrays,
it is not in regular JSON-LD arrays unless specifically defined
(see the Sets and Lists section of JSON-LD 1.1.
In the JSON serialization,
an object structure
is represented as a pair of curly brackets surrounding zero or more name/value pairs (or members).
A name is a string.
A single colon comes after each name,
separating the name from the value.
A single comma separates a value from a following name.
In JSON-LD the names in an object must be unique.
The use of the null value within JSON-LD
is used to ignore or reset values.
A map entry in the @context where the value,
or the @id of the value, is null,
explicitly decouples a term's association with an IRI.
A map entry in the body of a JSON-LD document
whose value is null
has the same meaning as if the map entry was not defined.
If @value, @list, or @set is set to null in expanded form,
then the entire JSON object is ignored.
In the JSON serialization, a number
is similar to that used in most programming languages,
except that the octal and hexadecimal formats are not used and that leading zeros are not allowed.
In the internal representation,
a number is equivalent to either a long
or double,
depending on if the number has a non-zero fractional part (see [WEBIDL]).
A string
is a sequence of zero or more Unicode (UTF-8) characters,
wrapped in double quotes, using backslash escapes (if necessary).
A character is represented as a single character string.
A 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 terms defined to be vocabulary relative
are resolved relative to the vocabulary mapping,
not the base IRI.
A node in a graph that is neither an IRI,
nor a literal.
A blank node does not contain
a de-referenceable identifier because it is either ephemeral in nature
or does not contain information that needs to be linked to from outside of the linked data graph.
In JSON-LD,
a blank node is assigned an identifier starting with the prefix _:.
A blank node identifier
is a string that can be used as an identifier for a blank node within the scope of a JSON-LD document.
Blank node identifiers begin with _:.
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.
The base direction is the direction used when a string does not have a direction associated with it directly.
It can be set in the context using the @direction key
whose value must be one of the strings "ltr", "rtl", or null.
See the Context Definitions section of JSON-LD 1.1 for a normative description.
A 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
a node object or a value object
in the input.
See the Frame Objects section of JSON-LD 1.1 for a normative description.
The JSON-LD internal representation
is the result of transforming a JSON syntactic structure
into the core data structures suitable for direct processing:
arrays, maps, strings, numbers, booleans, and null.
A JSON-LD Processor is a system which can perform the algorithms defined in JSON-LD 1.1 Processing Algorithms and API.
See the Conformance section in JSON-LD 1.1 API for a formal description.
A 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,
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 @versionentry 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 @versionentry in a context is explicitly set to 1.1.
This specification extends JSON-LD 1.0
via the json-ld-1.1processing mode.
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.
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.
Used as a macro within various algorithms as to reduce the language used to describe
the process of compacting a stringvar 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.
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 @graphentry,
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.
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 @versionmap entry within a context
set to 1.1 to ensure that JSON-LD 1.0 processors will not misinterpret JSON-LD 1.1 features.
2.1 Framing
This section is non-normative.
Framing is used to shape the data in a JSON-LD document,
using an example frame document which is used to both match the
flattened
data and show an example of how the resulting data should be shaped.
Matching is performed by using properties present in in the frame
to find objects in the data that share common values. Matching can be done
either using all properties present in the frame, or any property in the frame.
By chaining together objects using matched property values, objects can be embedded
within one another.
A frame also includes a context, which is used for compacting the resulting
framed output.
This frame document describes an embedding structure that would place
objects with type Library at the top, with objects of
type Book that were linked to the library object using
the contains property embedded as property values. It also
places objects of type Chapter within the referencing Book object
as embedded values of the Book object.
When using a flattened set of objects that match the frame components:
{
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"@type": "Library",
"location": "Athens",
"contains": {
"@id": "http://example.org/library/the-republic",
"@type": "Book",
"creator": "Plato",
"title": "The Republic",
"contains": {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
}
}
}
The Framing Algorithm does this by
first expanding both the input frame and document. It then creates
a map of flattened subjects. The outer-most node object within the frame
is used to match objects in the map, in this case looking for node objects
which have an @type of Library, and a
contains property with another
frame used to match values of that property. The input document contains
exactly one such node object. The value of contains also has
a node object, which is then treated as a frame to match the set of subjects
which are contains values of the Library object, and so forth.
2.1.1 Matching on Properties
This section is non-normative.
In addition to matching on types, a frame can match on
one or more properties.
For example, the following frame selects object based on property
values, rather than @type.
This will generate the same framed results as when selecting on @type,
the property that is excluded uniquely identifies each node object.
Note that additional properties with the value null are added
for those properties explicitly excluded.
2.1.4 Matching on Values
This section is non-normative.
Frames can be matched based on the presence of specific property values.
These values can themselves use wildcards, to match on a specific
or set of values, language tags, types, or base direction.
For an example, we'll use an multilingual version of the library example
with more complex value representations.
By matching on an attribute of a value, we can match frames
having that attribute, and limit results to property values
that match. In this case, we'll frame the Library and Book objects
on values only in latinized Greek (el-Latn):
Frames can be matched if they match a specific
identifier (@id). This can be illustrated with the original
Flattened library objects
input using a frame which matches on specific @id values:
Frames can also be matched from an array of identifiers.
Within a frame, it is acceptable for @id to have an array value,
where the individual values are treated as IRIs.
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"
}
}
}
Default values may also be used for @type, similar to other properties.
In this case, a matched node object without an @type will take the
value of the default object from the frame.
The default object has a value which is a single IRI.
If multiple IRIs are specified, only the first will be used as the default type.
The frame matches objects having specific property values,
and provides defaults for @type for matched objects.
Example 23: Sample library frame with @default type
Framing flags set using keywords have effect only for the
frame in which they appear, and for implicit frames which are created
for objects where no frame object exists.
Because, the default for the object embed flag is @once
(in addition to the explicit inclusion flag being false),
non-listed properties are added to the output, and implicitly embedded
using a default empty frame. As a result, the same output used in the
Framed library objects above is generated,
assuming that the ordered flag is true.
However, if the @embed property is added explicitly with a
value of @never, the values for Book and Chapter will be excluded.
Example 28: Sample library frame with explicit @embed set to @never
When framed using the same frame with the default @embed of @once,
only the "books" property will have content,
if the ordered flag is true,
and the "contains" property will use a reference.
If we use a frame using "@embed": "@always",
both properties will include expanded values.
Example 32: Sample library frame with explicit @embed set to @always
The explicit inclusion flag used to determine
properties which will be included in the output document.
The default value is false, which means that properties
present in an input node object that are not in the associated frame will be
included in the output object.
If true, only properties present in
the input frame will be placed into the output.
The initial value for the explicit inclusion flag is set using the
explicit option.
For example, take an expanded version of the library frame which include
some properties from the input, but omit others.
Example 34: Sample library frame with @explicit set to true
The resulting output will exclude properties for Book which are not explicitly
listed in the frame object:
Note that the Library object contains a nulldescription 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.
The resulting output will include a "child" property with the value
null, which may not always be desired:
Note that because the option "@embed": "@always" is specified in the frame
under the child property, that "child": null appears in the output
for matches that do not have that property, which may be undesirable.
To prevent this default null output from occurring,
the @omitDefault may be set to true like so:
Example 39: Sample parent/child relationship frame with @omitDefault
The 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.
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.
This will, again, reproduce the desired framed output:
2.4 Reverse Framing
This section is non-normative.
A frame may include @reverse, or a value of a term defined using @reverse
to invert the relationships in the output object. For example, the
Library example can be inverted using the following frame:
Using the flattened library example above, results in the following:
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 http://example.org/graphs/books:
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT in this document
are to be interpreted as described in
BCP 14
[RFC2119] [RFC8174]
when, and only when, they appear in all capitals, as shown here.
There is one class of products that can claim conformance to this
specification: JSON-LD Processors.
A conforming JSON-LD Processor is a system which can perform the
Framing operation in a manner consistent with
the algorithms defined in this specification.
JSON-LD ProcessorsMUST 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 @versionentry
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 ProcessorsMAY
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).
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:
Values of entries in a frame object that are not keywordMAY also include a default object.
Values of @defaultMAY 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.
ProcessorsMUST preserve this value when expanding. All other entries of
a default objectMUST 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 @typeMAY also be a map with
a @default entry, whose values are restricted by be IRIs.
ProcessorsMUST 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 @graphentry at the top level.
Nodes with a subject that is also a named graph, where
the frame object contains @graph, extend framing
to node objects from the associated named graph.
4.1.2 Algorithm
The framing algorithm takes
five required input variables and one optional input variable.
The required inputs are
a framing state (state),
a list of subjects to frame,
an input frame (expanded frame),
a parent used to collect partial frame results,
and an active property.
The optional input variable is the ordered flag.
The algorithm adds elements to parent either by appending
the element to parent, if it is an array, or by appending it
to an array associated with active property in parent, if it is a map.
Note that if parent is an array, active propertyMUST be null,
and if it is a map, it MUST NOT be null.
If frame is an array, set frame to the value of the array, which MUST be a valid frame.
If frame is determined to be invalid,
an invalid frame
error has been detected and processing is aborted.
If frame has an @identry, 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 @typeentry, 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.
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 @graphentry,
set recurse to true, unless graph name in state is @merged
and set subframe to a new empty map.
Otherwise, set subframe to the first entry for @graph in frame,
or a new empty map, if it does not exist, and
set recurse to true, unless id
is @merged or @default.
Invoke the algorithm
using a copy of state
with the value of graph name set to id
and the value of embedded flag set to false,
the keys from the graph map in state associated with id as subjects,
subframe as frame,
output as parent, and @graph as active property.
If frame has an @includedentry,
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 propertyif 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,
processorsMUST 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 subjectsarray,
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 subjectsarray,
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-keywordproperty 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 frameMUST 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 mapreverse dict as its value.
Add reverse property to reverse dict with a new empty array as its value.
Invoke the algorithm
using a copy of state with the value of embedded flag set to true,
the reverse id
as the sole item in a new subjectsarray,
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.
A value object, used to match a specific value. Within a value object,
the values for @value, @type, and @language
may also be an array of one or more string values,
values of @language are compared without regard to case..
{} (wildcard)
An array containing an empty object
(after excluding any properties which are framing keywords)
matches any value that is present, and does not match if there are no values.
The frame matching algorithm takes the framing state (state),
a list of subjects to match from the map of flattened subjects (subjects),
a frame to match against (frame), and the requireAll flag
and returns a list of matched subjects by filtering each node in subjects as follows:
All properties, including @id and @type, but no other keywords are considered
when matching a frame.
node matches if frame has no properties.
If requireAll is true, node matches if all properties (property)
in frame match any of the following conditions.
Or, if requireAll is false, if any of the properties (property)
in frame match any of the following conditions.
For the values of each property from frame in node:
If property is @id:
property matches if the @id property in frame includes any IRI in values.
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 frameMUST 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 @defaultentry 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 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=(Window,Worker)],
but the API is also intended for use outside of a browser context.
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.
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 optionswith ordered set to false.
Set expanded frame to the result of using the
expand
method either remote frame
or frame
if there is no remote frame
for inputoptions
the frameExpansion option set to true,
and theordered 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 contextcontext as local context,
and context base as base URL.
Initialize an active context using context;
the base IRI is set to
the base option from
options, if set;
otherwise, if the
compactToRelative option is
true, to the IRI of the currently being processed
document, if available; otherwise to null.
Invoke the
Framing algorithm, passing
state,
the keys from subject map in state for subjects,
expanded frame,
results for parent,
and null as active property.
Recursively, replace all entries in results
where the key is @preserve with the first value of that entry.
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 compactArraysand 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 @contextentry 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 andcompacted results does not have a top-level @graphentry, or its value is
not an array, modify compacted results to place the non @contextentry
of compacted results into a map contained within the array value of
@graph. If omitGraph is true, a
top-level @graphentry 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.
The JsonLdInput interface is used to refer to an input value
that that may be a JsonLdRecord,
a sequence of JsonLdRecords,
a string representing an IRI,
which can be dereferenced to retrieve a valid JSON document,
or an already dereferenced RemoteDocument.
a string representing the particular error type, as described in
the various algorithms in this document.
message
an optional error message containing additional debugging information.
The specific contents of error messages are outside the scope of this
specification.
The JsonLdFramingErrorCode represents the collection of valid JSON-LD Framing error
codes.
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.
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.
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.
This section is included merely for standards community review and will be
submitted to the Internet Engineering Steering Group if this specification
becomes a W3C Recommendation.
A JSON-LD Frame uses the same MIME media type described in [JSON-LD11]
along with a required profile parameter.
application/ld+json
Type name:
application
Subtype name:
ld+json
Required parameters:
None
Optional parameters:
profile
A single URI identifying the resource as a JSON-LD Frame.
A profile does not change the semantics of the resource representation
when processed without profile knowledge, so that clients both with
and without knowledge of a profiled resource can safely use the same
representation.
Since JSON-LD is intended to be a pure data exchange format for
directed graphs, the serialization SHOULD NOT be passed through a
code execution mechanism such as JavaScript's eval()
function to be parsed. An (invalid) document may contain code that,
when executed, could lead to unexpected side effects compromising
the security of a system.
When processing JSON-LD documents, links to remote contexts are
typically followed automatically, resulting in the transfer of files
without the explicit request of the user for each one. If remote
contexts are served by third parties, it may allow them to gather
usage patterns or similar information leading to privacy concerns.
Specific implementations, such as the API defined in the
JSON-LD 1.1 Processing Algorithms and API specification [JSON-LD11-API],
may provide fine-grained mechanisms to control this behavior.
JSON-LD contexts that are loaded from the Web over non-secure connections,
such as HTTP, run the risk of being altered by an attacker such that
they may modify the JSON-LD active context in a way that
could compromise security. It is advised that any application that
depends on a remote context for mission critical purposes vet and
cache the remote context before allowing the system to use it.
Given that JSON-LD allows the substitution of long IRIs with short terms,
JSON-LD documents may expand considerably when processed and, in the worst case,
the resulting data might consume all of the recipient's resources. Applications
should treat any data with due skepticism.
As JSON-LD places no limits on the IRI schemes that may be used,
and vocabulary-relative IRIs use string concatenation rather than
IRI resolution, it is possible to construct IRIs that may be
used maliciously, if dereferenced.
Interoperability considerations:
Not Applicable
Published specification:
https://www.w3.org/TR/json-ld11-framing
Applications that use this media type:
Any programming environment that requires the exchange of
directed graphs. Implementations of JSON-LD have been created for
JavaScript, Python, Ruby, PHP, and C++.
Additional information:
Magic number(s):
Not Applicable
File extension(s):
.jsonld
Macintosh file type code(s):
TEXT
Person & email address to contact for further information:
Ivan Herman <ivan@w3.org>
Intended usage:
Common
Restrictions on usage:
None
Author(s):
Manu Sporny, Gregg Kellogg, Markus Lanthaler, Dave Longley
There are numerous formatting and terminology changes intended to align with
the 1.0 Recommendations of JSON-LD and JSON-LD-API in addition to the use
of common term definition sections.
The object embed flag (@embed) can take on different
values to better control object embedding.
Framing supports More specific frame matching, where
general wildcard and match none
can be used for type and property values.
Frame matching also supports value object matching, where
values for @value, @type, and @language
can use wildcard and match none
and may also use a set of specific strings to match (e.g., a set of specific
languages).
Framing allows specific graphs to be matched, and the outer-most frame
can either come from the merged graph or the default graph.
Framing supports @reverse.
Through the use of scoped contexts, parts of a frame can be
compacted using a different context than is used for the outer-most
object.
Frames can use one or more values for @id to allow for matching
specific objects in a frame.
The API now adds an ordered
option, defaulting to false This is used in algorithms to
control iteration of map entry keys. Previously, the
algorithms always required such an order. The instructions for
evaluating test results have been updated accordingly.
Frames may include reverse properties using @reverse, or a term
defined with @reverse, which can cause nodes referencing a
node targeted by a frame to have a reverse reference created.
E. Changes since JSON-LD Community Group Final Report
This section is non-normative.
The API now adds an ordered
option, defaulting to false This is used in algorithms to
control iteration of map entry keys. Previously, the
algorithms always required such an order. The instructions for
evaluating test results have been updated accordingly.
The IANA registration is changed from application/ld-frame+json to
application/ld+json with a required profile parameter.
The require all flag now needs all properties to be present, including
@id and @type.
Removed @first and @last values for the
object embed flag in favor of @once.
The processing mode is now implicitly json-ld-1.1, unless set
explicitly to json-ld-1.0.
In a frame @type can have a default value, which is not used for
frame matching purposes.
F. Changes since Candidate Release of 12 December 2019
Moved non-recursive portions algorithms
into the JsonLdProcessor processing steps.
Remove the graph stack from framing state
as being unnecessary.
G. 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.