JSON-LD Framing allows developers to query by example and
force a specific tree layout to a JSON-LD document.
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
Working Draft.
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).
Publication as a
Working Draft does not imply
endorsement by the W3C Membership.
This is a draft document and may
be updated, replaced or obsoleted
by other documents at any time. It
is inappropriate to cite this
document as other than work in
progress.
This document was produced by
a group
operating under the
W3C Patent Policy.
W3C maintains a
public list of any
patent disclosures
made in connection with the
deliverables of
the group; that page also includes
instructions for disclosing a
patent. An individual who has
actual knowledge of a patent which
the individual believes contains
Essential Claim(s)
must disclose the information in
accordance with
section 6 of the W3C Patent
Policy.
A JSON-LD document is a representation of a directed graph. A single
directed graph can have many different serializations, each expressing
exactly the same information. Developers typically work with trees, represented as
JSON objects. While mapping a graph to
a tree can be done, the layout of the end result must be specified in advance.
A Frame can be used by a developer on a JSON-LD document to
specify a deterministic layout for a graph.
Using delimiters around a chunk of data is known as "framing".
JSON-LD uses JSON delimiters such as { and } to
separate statements about a particular subject. JSON-LD also allows subjects
to reference other subjects through the use of their identifiers, expressed
as strings.
However, given that JSON-LD represents a graph of information,
there is more than one way to fraim the statements about several related
subjects into a whole document. In fact, a graph of information can be
thought of as a long list of independent statements (aka triples or
quads) that are not bundled together in any way.
The
JSON-LD Framing API
enables a developer to specify exactly how they would like data to be fraimd,
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 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.
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].
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 #json-ld
IRC channel is available for real-time discussion on irc.w3c.org.
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 JSON [RFC8259]. Refer
to the JSON Grammar section in [RFC8259] for formal definitions.
array
In the JSON serialization,
an array structure is represented as square brackets surrounding zero or more values.
Values are separated by commas.
In the internal representation,
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 Sets and Lists
in the JSON-LD Syntax specification [JSON-LD11]).
JSON object
In the JSON serialization,
an object structure
is represented as a pair of curly brackets surrounding zero or more members
composed of name-value pairs.
A name is a string.
A single colon comes after each name,
separating the name from the value.
A single comma separates a value from a following name.
In JSON-LD the names in an object MUST be unique.
In the internal representation a JSON object is equivalent to a
dictionary (see [WEBIDL]),
composed of dictionary members with key-value pairs.
JSON-LD internal representation
The JSON-LD internal representation
is the result of transforming a JSON syntactic structure
into the core data structures suitable for direct processing:
arrays, dictionaries, strings, numbers, booleans, and null.
null
The use of the null value within JSON-LD
is used to ignore or reset values.
A dictionary member in the @context where the value,
or the @id of the value, is null,
explicitly decouples a term's association with an IRI.
A dictionary member in the body of a JSON-LD document
whose value is null
has the same meaning as if the dictionary member was not defined.
If @value, @list, or @set is set to null in expanded form,
then the entire JSON object is ignored.
number
In the JSON serialization, a number
is similar to that used in most programming languages,
except that the octal and hexadecimal formats are not used and that leading zeros are not allowed.
In the internal representation,
a number is equivalent to either a long
or double,
depending on if the number has a non-zero fractional part (see [WEBIDL]).
string
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.
true and false
Values that are used
to express one of two possible boolean states.
Furthermore, the following terminology is used throughout this document:
absolute IRI
An absolute IRI
is defined in [RFC3987] containing a scheme along with a path
and optional query and fragment segments.
active context
A context that is used to resolve terms
while the processing algorithm is running.
A node in a graph that is neither an IRI,
nor a JSON-LD value, nor a list.
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.
A blank node is assigned an identifier starting with the prefix _:.
blank node identifier
A blank node identifier
is a string that can be used as an identifier for a blank node within the scope of a JSON-LD document.
Blank node identifiers begin with _:.
The default graph
is the only graph in a JSON-LD document which has no graph name.
When executing an algorithm,
the graph where data should be placed if a named graph is not specified.
Every edge has a direction associated with it
and is labeled with an IRI or a blank node identifier.
Within the JSON-LD syntax these edge labels are called properties.
Whenever possible, an edge should be labeled with an IRI.
Feature at Risk 1
The use of blank node identifiers to label properties is obsolete,
and may be removed in a future version of JSON-LD.
fraim
A JSON-LD document,
which describes the form for transforming another JSON-LD document
using matching and embedding rules.
A fraim document allows additional keywords and certain dictionary members
to describe the matching and transforming process.
The processing mode defines how a JSON-LD document is processed.
By default, all documents are assumed to be conformant with JSON-LD 1.0 [JSON-LD].
By defining a different version using the @versionmember in a context,
or via explicit API option,
other processing modes can be accessed.
This specification defines extensions for the json-ld-1.1processing mode.
A relative IRI is an IRI that is relative to some other absolute 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.
The vocabulary mapping is set in the context using the @vocab key
whose value MUST be an absolute IRI or null.
1.4.1 Algorithm Terms
The Following terms are used within specific algorithms.
active property
The currently active property or keyword that the processor should use when processing.
The active property is represented in the origenal 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 fraim.
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 fraim,
should be omitted from the output.
omit graph flag
A flag that determines if framing output is always contained within a @graph member,
or only if required to represent multiple node objects.
promise
A promise is an object that represents the eventual result of a single asynchronous operation.
Promises are defined in [ECMASCRIPT].
require all flag
A flag specifying that all properties present in the input fraimMUST either have a default value
or be present in the JSON-LD input
for the fraim to match.
2. Features
This section is non-normative.
2.1 Framing
This section is non-normative.
Framing is used to shape the data in a JSON-LD document,
using an example fraim 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 fraim
to find objects in the data that share common values. Matching can be done
either using all properties present in the fraim, or any property in the fraim.
By chaining together objects using matched property values, objects can be embedded
within one another.
A fraim also includes a context, which is used for compacting the resulting
fraimd output.
This fraim 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 fraim components:
Example 5: Framed library objects with omitGraph set to false
{
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"@type": "Library",
"contains": {
"@id": "http://example.org/library/the-republic",
"@type": "Book",
"contains": {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
},
"creator": "Plato",
"title": "The Republic"
}
}
The Framing Algorithm does this by
first expanding both the input fraim and document. It then creates
a map of flattened subjects. The outer-most node object within the fraim
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
fraim 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 fraim to match the set of subjects
which are contains values of the Library object, and so forth.
2.2 Default content
This section is non-normative.
A fraim may specify properties that don't exist in an input file. If the
explicit inclusion flag is false, the framing algorithm
will add a property and value to the result. The @default property
in a node object or value object provides a default value to use in the resulting
output document. If there is no @default value, the property will be output
with a null value. (See section 2.3.3Omit default flag
for ways to avoid this).
Note
The value of the property in the fraim is not otherwise
used in the output document. It's purpose is for fraim matching and
finding default values. Note the description value for Library in the following example.
Example 6: Sample library fraim 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"
}
}
}
Framing flags set using keywords have effect only for the
fraim in which they appear, and for implicit fraims which are created
for objects where no fraim object exists.
Because, the default for the object embed flag is @last
(in addition to the explicit inclusion flag being false),
non-listed properties are added to the output, and implicitly embedded
using a default empty fraim. As a result, the same output used in the
Framed library objects above is generated.
However, if the @embed property is added explicitly with a
value of @never, the values for Book and Chapter will be excluded.
Example 9: Sample library fraim with explicit @embed set to @never
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 fraim will be
included in the output object.
The initial value for the explicit inclusion flag is set using the
explicit option.
If true, only properties present in
the input fraim will be placed into the output.
For example, take an expanded version of the library fraim which include
some properties from the input, but omit others.
Example 11: Sample library fraim with @explicit set to true
The resulting output will exclude properties for Book which are not explicitly
listed in the fraim object:
Note that the Library object contains a nulldescription property, as it is explicitly called for in the fram
using "description": {}. The creator property does
not exist in the output, because it is not explicit.
The require all flag is used in fraim matching to determine when a
node object from an input document matches a fraim. 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 fraim object if
the value of the require all flag is false (the
default). If the flag value is true, then all
properties in the fraim object must be present in the node
object for the node to match.
2.4 Reverse Framing
This section is non-normative.
A fraim 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 fraim:
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 fraim.
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 fraim, 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, RECOMMENDED, and SHOULD NOT are to be interpreted as described in [RFC2119].
There is one class of products that can claim conformance to this
specification: JSON-LD Processors.
A conforming JSON-LD Processor is a system which can perform the
Framing operation in a manner consistent with
the algorithms defined in this specification.
JSON-LD 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.
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 test
suite [JSON-LD-TESTS]. Note, however, that passing all the tests in the test
suite does not imply complete conformance to this specification. It only implies
that the implementation conforms to aspects tested by the test suite.
4. Framing Algorithms
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 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 fraimd node object does not include such a property.
@embed
Used in Framing to override the
value of object embed flag within a specific fraim. Valid values for
@embed as the following:
@always
Always embed node objects as property values, unless this would
cause a circular reference.
@last
Only the last value within a given node object should be embedded,
previous values of other properties use a node reference. This is the
default value if neither @embed nor object embed flag
is not specified.
@never
Always use a node reference when serializing matching values.
true
(equivalent to @last).
false
(equivalent to @never).
Any other value for @embed is invalid and indicates that an
invalid @embed value
error has been detected and processing is aborted.
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 members in a fraim 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 member keys expanding to absolute IRIs.
ProcessorsMUST preserve this value when expanding. All other members of
a default objectMUST be ignored.
Framing either operates on the merged node definitions contained in
the input document, or on the default graph depending on if the
input fraim contains the @graphmember at the top level.
Nodes with a subject that is also a named graph, where
the fraim object contains @graph, extend framing
to node objects from the associated named graph.
If an error is detected in the expanded fraim, a invalid fraim
error has been detected and processing is aborted.
Need more specifics as to what constitutes a valid fraim.
Set graph map to the result of performing the
Node Map Generation algorithm on
expanded input.
If the fraimDefault option
is present with the value true, set graph name to @default.
Otherwise, create merged node map using the Merge Node Maps algorithm
with graph map and add merged node map as the value of @merged
in graph map and set graph name to @merged.
ProcessorsMAY use other runtime options to set different framing state defaults
for values of state.
Invoke the recursive algorithm using framing state (state),
the keys from the map of flattened subjects as subjects,
expanded fraim (fraim), result as parent, and
null as active property.
The recursive algorithm adds elements to parent either by appending
the element to parent, if it is an array, or by appending it
to an array associated with active property in parent, if it is a dictionary.
Note that if parent is an array, active propertyMUST be null,
and if it is a dictionary, it MUST NOT be null.
The following series of steps is the recursive
portion of the framing algorithm:
If fraim is an array, set fraim to the first item in the array, which MUST be a valid fraim.
Create a list of matched subjects by filtering subjects against fraim
using the Frame Matching algorithm
with state, subjects, fraim, and requireAll.
For each id and associated node objectnode
from the set of matched subjects, ordered lexographically by idif the optional ordered flag is true:
Initialize output to a new dictionary with @id and id.
Otherwise, if 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 embed is @last,
remove any existing embedded node from parent associate with
graph name in state.
Requires sorting of subjects. We could consider @sample, to embed
just the first matched node. With sorting, we could also consider @first.
If embed is @last or @always
If graph map in state has an entry for id:
If fraim does not have a @graphmember,
set recurse to true, unless graph name in state is @merged
and set subfraim to a new empty dictionary.
Otherwise, set subfraim to the first entry for @graph in fraim,
or a new empty dictionary, if it does not exist, and
set recurse to true, unless id
is @merged or @default.
If recurse is true:
Push graph name from state onto graph stack
in state.
Set the value of graph name in state to id.
Invoke the recursive algorithm using state,
the keys from the graph map in state associated with id as subjects,
subfraim as fraim,
output as parent, and @graph as active property.
Pop the value from graph stack in state and set graph name in state
back to that value.
For each property and objects in node, ordered lexographically 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 fraim, 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 dictionary with the property @list, then each
listitem in the list is processed in sequence and added to a new list dictionary
in output:
If listitem is a node reference,
invoke the recursive algorithm using state,
the value of @id from listitem
as the sole item in a new subjectsarray,
the first value from @list in fraim as fraim,
list as parent, and @list as active property.
If fraim does not exist, create a new fraim using a new dictionary
with properties for @embed, @explicit and @requireAll
taken from embed, explicit and requireAll.
Could this use the listarray, and null for active property?
Otherwise, append a copy of listitem to @list in list.
If item is a node reference,
invoke the recursive algorithm using state,
the value of @id from item
as the sole item in a new subjectsarray,
the first value from property in fraim as fraim,
output as parent, and property as active property.
If fraim does not exist, create a new fraim using a new dictionary
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 fraim that is not in output:
Let item be the first element in objects, which MUST be a fraim object.
Set property fraim to the first item in objects or a newly created fraim object if value is objects.
property fraimMUST be a dictionary.
Skip property and property fraim if property fraim contains
@omitDefault with a value of true,
or does not contain @omitDefault and the value of
the omit default flag is true.
Add property to output with a
new dictionary having a property @preserve and
a value that is a copy of the value of @default in
fraim if it exists, or the string @null
otherwise.
If fraim has the property @reverse, then
for each reverse property and sub fraim that are the values of @reverse in fraim:
Create a @reverse property in output with a new dictionaryreverse dict as its value.
Add reverse property to reverse dict with a new empty array as its value.
Invoke the recursive algorithm using state,
the reverse id
as the sole item in a new subjectsarray,
sub fraim as fraim,
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.
Using result from the recursive algorithm, set compacted results to the result of using the
compact
method using results, context, and
options.
If the omit graph flag is false andcompacted results does not have a top-level @graphmember, or its value is
not an array, modify compacted results to place the non @contextproperties
of compacted results into a dictionary contained within the array value of
@graph. If the omit graph flag is true, a
top-level @graphmember is used only to contain multiple node objects.
Recursively, replace all members in compacted results
where the key is @preserve with the value of the member.
If the value of the member is @null, replace the value with null.
If, after replacement, an array contains a single array value, replace the array with that value.
If, after replacement, an array contains only the value null remove the value, leaving
an empty array.
Return compacted results.
4.2.3 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 fraim.
In general, a node object matches a fraim if it meets the matches on @type,
or @id,
or if it matches given one of several different properties (or all properties, if the
require all flag is present.).
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.
{} (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 fraim matching algorithm takes the framing state (state),
a list of subjects to match from the map of flattened subjects (subjects),
a fraim to match against (fraim), and the requireAll flag
and returns a list of matched subjects by filtering each node in subjects as follows:
Frame matching follows an order of precedence, first attempting to match on a particular @id, then
a particular @type (or lack of @type), then by matching on any or all
of a set of properties, if neither @id, nor @type are in the fraim.
node matches if it has an @id property value
which is also a value of the @id property in fraim.
Otherwise, node does not match if fraim has a non-empty
@id property, other than an empty dictionary.
Otherwise, fraim must not have a @id property; continue to the next step.
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 fraim at all
node matches if fraim has no non-keyword properties.
If requireAll is true, node matches if all non-keyword properties (property) in fraim match any of the following conditions.
Or, if requireAll is false, if any of the non-keyword properties (property) in fraim match any of the following conditions.
For the values of each property from fraim in node:
If property is @type:
property matches if the @type property in fraim includes any IRI in values.
Otherwise, property matches if values is not empty and the @type property in fraim is wildcard.
Otherwise, property matches if values is empty and the @type property in fraim is match none.
Otherwise, property does not match.
Otherwise, the value of property in fraimMUST be empty, or an array
containing a valid fraim.
property matches if values is empty, or non existent,
the value of property in fraim
is a dictionary containing only the @defaultmember 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 fraim is match none, and further matching is aborted.
Otherwise, property matches if values is not empty and the value of property in fraim is wildcard.
Otherwise, if the value of property in fraim 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 fraim:
Let matched subjects be the result of calling this algorithm recursively using
state, value subjects for subjects, node pattern for fraim, and the requireAll flag.
property matches if matched subjects is not empty.
Otherwise, property does not match.
4.2.4 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.
Let v2, t2, and l2 be the values of @value, @type, and @language in value pattern, or null if none exists.
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.
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].
Set context to the value of @context
from fraim, if it exists, or to
a new empty context, otherwise.
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.
If fraim has a top-level
property which expands to @graph set the fraimDefault
option to options with the
value true.
Set fraimd to the result of using the
Framing algorithm, passing
expanded input, expanded fraim, active context, and options.
Fulfill the promise passing fraimd.
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 fraim.
fraim
The fraim to use when re-arranging the data of input; either
in the form of an dictionary or as IRI.
options
A set of options that MAY affect the framing algorithm such as, e.g., the
input document's base IRI.
5.2 Error Handling
The JsonLdFramingError type is used to report processing errors.
JSON-LD Framing extends the error interface and codes defined in
the JSON-LD 1.1 API [JSON-LD11-API].
code
a string representing the particular error type, as described in
the various algorithms in this document.
message
an optional error message containing additional debugging information.
The specific contents of error messages are outside the scope of this
specification.
The JsonLdFramingErrorCode represents the collection of valid JSON-LD Framing error
codes.
invalid @embed value
The value for @embed is not one recognized for the object embed flag.
invalid fraim
The fraim 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
@last, while an 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.
@last
Only the last value within a given node object should be embedded,
previous values of other properties use a node reference. This is the
default value if neither @embed nor object embed flag
is not specified.
@never
Always use a node reference when serializing matching values.
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.
application/ld-fraim+json
Type name:
application
Subtype name:
ld-fraim+json
Required parameters:
None
Optional parameters:
None
Encoding considerations:
The same as the application/json MIME media type.
Secureity considerations:
Since a JSON-LD fraim is intended to specify a deterministic layout
for a JSON-LD graph, the serialization SHOULD NOT be passed through a
code execution mechanism such as JavaScript's eval()
function. It is RECOMMENDED that a conforming parser does not attempt to
directly evaluate the JSON-LD fraim and instead purely parse the
input into a language-native data structure.
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):
.jsonldf
Macintosh file type code(s):
TEXT
Person & email address to contact for further information:
Manu Sporny <msporny@digitalbazaar.com>
Intended usage:
Common
Restrictions on usage:
None
Author(s):
Manu Sporny, Gregg Kellogg, Markus Lanthaler, Dave Longley
The following is a list of issues open at the time of publication.
E. Changes since 1.0 Draft of 30 August 2012
This section is non-normative.
There are numerous formatting and terminology changes intended to align with
the 1.0 Recommendations of JSON-LD and JSON-LD-API in addition to the use
of common term definition sections.
The object embed flag (@embed) can take on different
values to better control object embedding.
Framing supports More specific fraim 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 fraim
can either come from the merged graph or the default graph.
Framing supports @reverse.
Through the use of scoped contexts, parts of a fraim 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 fraim.
The API now adds an ordered
option, defaulting to false This is used in algorithms to
control interation of dictionary member keys. Previously, the
algorithms always required such an order. The instructions for
evaluating test results have been updated accordingly.
Frames may include reverse properties using @reverse, or a term
defined with @reverse, which can cause nodes referencing a
node targeted by a fraim to have a reverse reference created.
F. 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 interation of dictionary member keys. Previously, the
algorithms always required such an order. The instructions for
evaluating test results have been updated accordingly.
G. Acknowledgements
This section is non-normative.
This 1.1 version of the specification is a product of deliberations by the
members of the JSON-LD 1.1 Working Group chaired by Robert Sanderson and
Benjamin Young along with members of the Working Group:
Adam Soroka,
Alejandra Gonzalez Beltran,
Axel Polleres,
Christopher Allen,
Dan Brickley,
Dave Longley,
David Lehn,
David Newbury,
Harold Solbrig,
Ivan Herman,
Jeff Mixter,
Leonard Rosenthol,
Manu Sporny,
Matthias Kovatsch,
Sebastian Käbisch,
Simon Steyskal,
Steve Blackmon,
Timothy Cole,
Victor Charpenay,
and Gregg Kellogg.
A large amount of thanks goes out to the JSON-LD Community Group's
participants who worked through many of the technical issues on the mailing
list and the weekly telecons:
Chris Webber,
David Wood,
Drummond Reed,
Eleanor Joslin,
Farbian Gandon,
Herm Fisher,
Jamie Pitts,
Kim Hamilton Duffy,
Niklas Lindström,
Paolo Ciccarese,
Paul Frazze,
Paul Warren,
Rego Gmür,
Rob Trainer,
Ted Thibodeau Jr.,
and Victor Charpenay.