JSON-LD 1.1 Framing

An Extension to the Application Programming Interface for the JSON-LD Syntax

W3C Recommendation

This version:
https://www.w3.org/TR/2020/REC-json-ld11-framing-20200716/
Latest published version:
https://www.w3.org/TR/json-ld11-framing/
Latest editor's draft:
https://w3c.github.io/json-ld-framing/
Test suite:
https://w3c.github.io/json-ld-framing/tests/
Implementation report:
https://w3c.github.io/json-ld-api/reports/
Previous version:
https://www.w3.org/TR/2020/PR-json-ld11-framing-20200507/
Editors:
Dave Longley (Digital Bazaar) (v1.0 and v1.1)
Gregg Kellogg (v1.0 and v1.1)
Pierre-Antoine Champin (LIRIS - Université de Lyon) (v1.1)
Former editors:
Manu Sporny (Digital Bazaar) (v1.0)
Markus Lanthaler (Google) (v1.0)
Authors:
Dave Longley (Digital Bazaar) (v1.0)
Manu Sporny (Digital Bazaar) (v1.0)
Gregg Kellogg (v1.0 and v1.1)
Markus Lanthaler (Google) (v1.0)
Niklas Lindström (v1.0)
Participate:
GitHub w3c/json-ld-framing
File a bug
Commit history
Pull requests

Please check the errata for any errors or issues reported since publication.

See also translations.

This document is also available in this non-normative format: EPUB


Abstract

JSON-LD Framing allows developers to query by example and force a specific tree layout to a JSON-LD document.

This specification describes a superset of the features defined in JSON-LD Framing 1.0 [JSON-LD10-FRAMING] and, except where noted, the algorithms described in this specification are fully compatible with documents created using the previous community standard.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document has been developed by the JSON-LD Working Group and was derived from the JSON-LD Community Group's Final Report.

There is a live JSON-LD playground that is capable of demonstrating the features described in this document.

This document was published by the JSON-LD Working Group as a Recommendation.

GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-json-ld-wg@w3.org (archives).

Please see the Working Group's implementation report.

This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2019 W3C Process Document.

Set of Documents

This document is one of three JSON-LD 1.1 Recommendations produced by the JSON-LD Working Group:

1. Introduction

This section is non-normative.

JSON-LD is a lightweight syntax to serialize Linked Data [LINKED-DATA] in JSON [RFC8259]. Its design allows existing JSON to be interpreted as Linked Data with minimal changes. As with other representations of Linked Data which describe directed graphs, a single directed graph can have many different serializations, each expressing exactly the same information. Developers typically work with trees, represented as JSON objects. While mapping a graph to a tree can be done, the layout of the end result must be specified in advance. 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:

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:

1.3 Typographical conventions

This section is non-normative.

The following typographic conventions are used in this specification:

markup
Markup (elements, attributes, properties), machine processable values (string, characters, media types), property name, or a file name is in red-orange monospace font.
variable
A variable in pseudo-code or in an algorithm description is in italics.
definition
A definition of a term, to be used elsewhere in this or other specifications, is in bold and italics.
definition reference
A reference to a definition in this document is underlined and is also an active link to the definition itself.
markup definition reference
A references to a definition in this document, when the reference itself is also a markup, is underlined, red-orange monospace font, and is also an active link to the definition itself.
external definition reference
A reference to a definition in another document is underlined, in italics, and is also an active link to the definition itself.
markup external definition reference
A reference to a definition in another document, when the reference itself is also a markup, is underlined, in italics red-orange monospace font, and is also an active link to the definition itself.
hyperlink
A hyperlink is underlined and in blue.
[reference]
A document reference (normative or informative) is enclosed in square brackets and links to the references section.
Changes from Recommendation
Sections or phrases changed from the previous Recommendation may be highlighted using a control in § 1.1 How to Read this Document.
Note

Notes are in light green boxes with a green left border and with a "Note" header in green. Notes are always informative.

Examples are in light khaki boxes, with khaki left border,
and with a numbered "Example" header in khaki.
Examples are always informative. The content of the example is in monospace font and may be syntax colored.

Examples may have tabbed navigation buttons
to show the results of transforming an example into other representations.

1.4 Terminology

This document uses the following terms as defined in external specifications and defines terms specific to JSON-LD.

Terms imported from Other Specifications

Terms imported from ECMAScript Language Specification [ECMASCRIPT], The JavaScript Object Notation (JSON) Data Interchange Format [RFC8259], Infra Standard [INFRA], and Web IDL [WEBIDL]

array
In the JSON serialization, an array structure is represented as square brackets surrounding zero or more values. Values are separated by commas. In the internal representation, 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.
boolean
The values true and false that are used to express one of two possible states.
JSON object
In the JSON serialization, an object structure is represented as a pair of curly brackets surrounding zero or more name/value pairs (or members). A name is a string. A single colon comes after each name, separating the name from the value. A single comma separates a value from a following name. In JSON-LD the names in an object must be unique.

In the internal representation a JSON object is described as a map (see [INFRA]), composed of entries with key/value pairs.

In the Application Programming Interface, a map is described using a [WEBIDL] record.

null
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.
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]).
scalar
A scalar is either a string, number, true, or false.
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.

Terms imported from Internationalized Resource Identifiers (IRIs) [RFC3987]

IRI
The absolute form of an IRI containing a scheme along with a path and optional query and fragment segments.
IRI reference
Denotes the common usage of an Internationalized Resource Identifier. An IRI reference may be absolute or relative. However, the "IRI" that results from such a reference only includes absolute IRIs; any relative IRI references are resolved to their absolute form.
relative IRI reference
A relative IRI reference is an IRI reference that is relative to some other IRI, typically the base IRI of the document. Note that properties, values of @type, and values of terms defined to be vocabulary relative are resolved relative to the vocabulary mapping, not the base IRI.

Terms imported from RDF 1.1 Concepts and Abstract Syntax [RDF11-CONCEPTS], RDF Schema 1.1 [RDF-SCHEMA], and Linked Data Design Issues [LINKED-DATA]

base IRI
The base IRI is an IRI established in the context, or is based on the JSON-LD document location. The base IRI is used to turn relative IRI references into IRIs.
blank node
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 _:.
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 _:.
dataset
A dataset representing a collection of RDF graphs including exactly one default graph and zero or more named graphs.
datatype IRI
A datatype IRI is an IRI identifying a datatype that determines how the lexical form maps to a literal value.
default graph
The default graph of a dataset is an RDF graph having no name, which may be empty.
graph name
The IRI or blank node identifying a named graph.
language-tagged string
A language-tagged string consists of a string and a non-empty language tag as defined by [BCP47]. The language tag must be well-formed according to section 2.2.9 Classes of Conformance of [BCP47]. Processors may normalize language tags to lowercase.
Linked Data
A set of documents, each containing a representation of a linked data graph or dataset.
list
A list is an ordered sequence of IRIs, blank nodes, and literals.
literal
An object expressed as a value such as a string or number. Implicitly or explicitly includes a datatype IRI and, if the datatype is rdf:langString, an optional language tag.
named graph
A named graph is a linked data graph that is identified by an IRI or blank node.
node
A node in an RDF graph, either the subject and object of at least one triple. Note that a node can play both roles (subject and object) in a graph, even in the same triple.
object
An object is a node in a linked data graph with at least one incoming edge.
property
The name of a directed-arc in a linked data graph. Every property is directional and is labeled with an IRI or a blank node identifier. Whenever possible, a property should be labeled with an IRI.
Note
The use of blank node identifiers to label properties is obsolete, and may be removed in a future version of JSON-LD.
Also, see predicate in [RDF11-CONCEPTS].
RDF graph
A labeled directed graph, i.e., a set of nodes connected by directed-arcs. Also called linked data graph.
resource
A resource denoted by an IRI, a blank node or literal representing something in the world (the "universe of discourse").
subject
A subject is a node in a linked data graph with at least one outgoing edge, related to an object node through a property.
triple
A component of an RDF graph including a subject, predicate, and object, which represents a node-arc-node segment of an RDF graph.

JSON-LD Specific Term Definitions

active context
A context that is used to resolve terms while the processing algorithm is running.
base direction
The base direction is the direction used when a string does not have a direction associated with it directly. It can be set in the context using the @direction key whose value must be one of the strings "ltr", "rtl", or null. See the Context Definitions section of JSON-LD 1.1 for a normative description.
context
A set of rules for interpreting a JSON-LD document as described in the The Context section of JSON-LD 1.1, and normatively specified in the Context Definitions section of JSON-LD 1.1.
default object
A default object is a map that has a @default key.
frame
A JSON-LD document, which describes the form for transforming another JSON-LD document using matching and embedding rules. A frame document allows additional keywords and certain map entries to describe the matching and transforming process.
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.
JSON-LD document
A JSON-LD document is a serialization of an RDF dataset. See the JSON-LD Grammar section in JSON-LD 1.1 for a formal description.
JSON-LD internal representation
The JSON-LD internal representation is the result of transforming a JSON syntactic structure into the core data structures suitable for direct processing: arrays, maps, strings, numbers, booleans, and null.
JSON-LD Processor
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.
JSON-LD value
A JSON-LD value is a string, a number, true or false, a typed value, or a language-tagged string. It represents an RDF literal.
keyword
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,
node object
A node object represents zero or more properties of a node in the graph serialized by the JSON-LD document. A map is a node object if it exists outside of the JSON-LD context and:
  • it does not contain the @value, @list, or @set keywords, or
  • it is not the top-most map in the JSON-LD document consisting of no other entries than @graph and @context.
The entries of a node object whose keys are not keywords are also called properties of the node object. See the Node Objects section of JSON-LD 1.1 for a normative description.
node reference
A node object used to reference a node having only the @id key.
processing mode
The processing mode defines how a JSON-LD document is processed. By default, all documents are assumed to be conformant with this specification. By defining a different version using the @version entry in a context, publishers can ensure that processors conformant with JSON-LD 1.0 [JSON-LD10] will not accidentally process JSON-LD 1.1 documents, possibly creating a different output. The API provides an option for setting the processing mode to json-ld-1.0, which will prevent JSON-LD 1.1 features from being activated, or error if @version entry in a context is explicitly set to 1.1. This specification extends JSON-LD 1.0 via the json-ld-1.1 processing mode.
scoped context
A scoped context is part of an expanded term definition using the @context entry. It has the same form as an embedded context. When the term is used as a type, it defines a type-scoped context, when used as a property it defines a property-scoped context.
typed value
A typed value consists of a value, which is a string, and a type, which is an IRI.
value object
A value object is a map that has an @value entry. See the Value Objects section of JSON-LD 1.1 for a normative description.
vocabulary mapping
The vocabulary mapping is set in the context using the @vocab key whose value must be an IRI, a compact IRI, a term, or null. See the Context Definitions section of JSON-LD 1.1 for a normative description.

1.4.1 Algorithm Terms

The Following terms are used within specific algorithms.

active property
The currently active property or keyword that the processor should use when processing. The active property is represented in the original lexical form, which is used for finding coercion mappings in the active context.
explicit inclusion flag
A flag specifying that for properties to be included in the output, they must be explicitly declared in the matching frame.
framing state
A map containing values for the object embed flag, the require all flag, the embedded flag, used internally to help determine if object embedding is appropriate, the explicit inclusion flag, and the omit default flag.
input frame
The initial Frame provided to the framing algorithm.
IRI compacting
Used as a macro within various algorithms as to reduce the language used to describe the process of compacting a string var representing an IRI or keyword using an active context either specified directly, or coming from the scope of the algorithm step using this term. An optional value is used, if explicitly provided. Unless specified, the vocab flag defaults to true, and the reverse flag defaults to false.
  1. Return the result of using the IRI Compaction algorithm, passing active context, var, value (if supplied), vocab, and result.
JSON-LD input
The JSON-LD data structure that is provided as input to the algorithm.
map of flattened subjects
A map of subjects that is the result of the Node Map Generation algorithm.
object embed flag
A flag specifying that node objects should be directly embedded in the output, instead of being referred to by their IRI.
omit default flag
A flag specifying that properties that are missing from the JSON-LD input, but present in the input frame, should be omitted from the output.
omit graph flag
A flag that determines if framing output is always contained within a @graph entry, or only if required to represent multiple node objects.
require all flag
A flag specifying that all properties present in the input frame must either have a default value or be present in the JSON-LD input for the frame to match.

1.5 Syntax Tokens and Keywords

This specification adds a number of keywords (framing keywords) to the ones defined in the JSON-LD 1.1 Syntax specification [JSON-LD11]:

@default
Used in Framing to set the default value for an output property when the framed node object does not include such a property.
@embed
Used in Framing to override the value of object embed flag within a specific frame. Valid values for @embed as the following:
@always
Always embed node objects as property values, unless this would cause a circular reference.
@once
Just a single value within a given node object should be embedded, other values of other properties use a node reference. This is the default value if neither @embed nor object embed flag is specified.
Note
The specific node object chosen to embed depends on ordering. If the ordered flag is true, this will be the first node object encountered, otherwise, it may be any node object.
@never
Always use a node reference when serializing matching values.

Any other value for @embed is invalid and indicates that an invalid @embed value error has been detected and processing is aborted.

@explicit
Used in Framing to override the value of explicit inclusion flag within a specific frame.
@null
Used in Framing when a value of null should be returned, which would otherwise be removed when Compacting.
@omitDefault
Used in Framing to override the value of omit default flag within a specific frame.
@requireAll
Used in Framing to override the value of require all flag within a specific frame.

All JSON-LD tokens and keywords are case-sensitive.

2. Features

This section is non-normative.

JSON-LD 1.1 introduces new features that are compatible with JSON-LD 1.0 [JSON-LD10], but if processed by a JSON-LD 1.0 processor may produce different results. Processors default to json-ld-1.1, unless the processingMode API option is explicitly set to json-ld-1.0. Publishers are encouraged to use the @version map entry within a context set to 1.1 to ensure that JSON-LD 1.0 processors will not misinterpret JSON-LD 1.1 features.

2.1 Framing

This section is non-normative.

Framing is used to shape the data in a JSON-LD document, using an example frame document which is used to both match the flattened data and show an example of how the resulting data should be shaped. Matching is performed by using properties present in in the frame to find objects in the data that share common values. Matching can be done either using all properties present in the frame, or any property in the frame. By chaining together objects using matched property values, objects can be embedded within one another.

A frame also includes a context, which is used for compacting the resulting framed output.

For example, assume the following JSON-LD frame:

Example 2: Sample library frame
{
  "@context": {"@vocab": "http://example.org/"},
  "@type": "Library",
  "contains": {
    "@type": "Book",
    "contains": {
      "@type": "Chapter"
    }
  }
}

This frame document describes an embedding structure that would place objects with type Library at the top, with objects of type Book that were linked to the library object using the contains property embedded as property values. It also places objects of type Chapter within the referencing Book object as embedded values of the Book object.

When using a flattened set of objects that match the frame components:

Example 3: Flattened library objects
{
  "@context": {
    "@vocab": "http://example.org/",
    "contains": {"@type": "@id"}
  },
  "@graph": [{
    "@id": "http://example.org/library",
    "@type": "Library",
    "location": "Athens",
    "contains": "http://example.org/library/the-republic"
  }, {
    "@id": "http://example.org/library/the-republic",
    "@type": "Book",
    "creator": "Plato",
    "title": "The Republic",
    "contains": "http://example.org/library/the-republic#introduction"
  }, {
    "@id": "http://example.org/library/the-republic#introduction",
    "@type": "Chapter",
    "description": "An introductory chapter on The Republic.",
    "title": "The Introduction"
  }]
}

The Frame Algorithm can create a new document which follows the structure of the frame:

If processing mode is not json-ld-1.0, or the omit graph flag is true, the top-level @graph entry may be omitted.

Example 5: Framed library objects
{
  "@context": {"@vocab": "http://example.org/"},
  "@id": "http://example.org/library",
  "@type": "Library",
  "location": "Athens",
  "contains": {
    "@id": "http://example.org/library/the-republic",
    "@type": "Book",
    "creator": "Plato",
    "title": "The Republic",
    "contains": {
      "@id": "http://example.org/library/the-republic#introduction",
      "@type": "Chapter",
      "description": "An introductory chapter on The Republic.",
      "title": "The Introduction"
    }
  }
}

The Framing Algorithm does this by first expanding both the input frame and document. It then creates 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.

Example 6: Library frame with property matching
{
  "@context": {"@vocab": "http://example.org/"},
  "location": "Athens",
  "contains": {
    "title": "The Republic",
    "contains": {
      "title": "The Introduction"
    }
  }
}

This will generate the same framed results as when selecting on @type, as the property values are unique to each node object.

See § 2.3.5 Require all flag to see how matching can be restricted to match node objects containing all, versus any such listed property.

2.1.2 Wildcard Matching

This section is non-normative.

The empty map ({}) is used as a wildcard, which will match a property if it exists in a target node object, independent of any specific value.

For example, the following frame selects object based on property wildcarding, rather than @type.

Example 8: Library frame with wildcard matching
{
  "@context": {"@vocab": "http://example.org/"},
  "location": {},
  "contains": {
    "creator": {},
    "contains": {
      "description": {}
    }
  }
}

This will generate the same framed results as when selecting on @type, as the matched properties are distinct to each node object.

2.1.3 Match on the Absence of a Property

This section is non-normative.

The empty array ([]) is used for match none, which will match a node object only if a property does not exist in a target node object.

For example, the following frame selects object based on the absence of properties, rather than @type.

Example 10: Library frame with absent matching
{
  "@context": {"@vocab": "http://example.org/"},
  "creator": [],
  "title": [],
  "contains": {
    "location": [],
    "description": [],
    "contains": {
      "location": []
    }
  }
}

This will generate the same framed results as when selecting on @type, the property that is excluded uniquely identifies each node object. Note that additional properties with the value null are added for those properties explicitly excluded.

2.1.4 Matching on Values

This section is non-normative.

Frames can be matched based on the presence of specific property values. These values can themselves use wildcards, to match on a specific or set of values, language tags, types, or base direction.

For an example, we'll use an multilingual version of the library example with more complex value representations.

Example 12: Multilingual library objects
{
  "@context": {
    "@vocab": "http://example.org/",
    "contains": {"@type": "@id"}
  },
  "@graph": [{
    "@id": "http://example.org/library",
    "@type": "Library",
    "location": [
      {"@value": "Athens", "@language": "en"},
      {"@value": "Αθήνα", "@language": "grc"},
      {"@value": "Athína", "@language": "el-Latn"}
    ],
    "contains": "http://example.org/library/the-republic"
  }, {
    "@id": "http://example.org/library/the-republic",
    "@type": "Book",
    "creator": [
      {"@value": "Plato", "@language": "en"},
      {"@value": "Πλάτων", "@language": "grc"},
      {"@value": "Plátōn", "@language": "el-Latn"}
    ],
    "title": [
      {"@value": "The Republic", "@language": "en"},
      {"@value": "Πολιτεία", "@language": "grc"},
      {"@value": "Res Publica", "@language": "el-Latn"}
    ],
    "contains": "http://example.org/library/the-republic#introduction"
  }, {
    "@id": "http://example.org/library/the-republic#introduction",
    "@type": "Chapter",
    "description": "An introductory chapter on The Republic.",
    "title": "The Introduction"
  }]
}

By matching on an attribute of a value, we can match frames having that attribute, and limit results to property values that match. In this case, we'll frame the Library and Book objects on values only in latinized Greek (el-Latn):

Example 13: Library frame with language matching
{
  "@context": {"@vocab": "http://example.org/"},
  "location": {"@value": {}, "@language": "el-Latn"},
  "contains": {
    "creator": {"@value": {}, "@language": "el-Latn"},
    "title": {"@value": {}, "@language": "el-Latn"},
    "contains": {
      "title": "The Introduction"
    }
  }
}

This generates the following framed results:

2.1.5 Matching on @id

This section is non-normative.

Frames can be matched if they match a specific identifier (@id). This can be illustrated with the original Flattened library objects input using a frame which matches on specific @id values:

Example 15: Library frame with @id matching
{
  "@context": {"@vocab": "http://example.org/"},
  "@id": "http://example.org/library",
  "contains": {
    "@id": "http://example.org/library/the-republic",
    "contains": {
      "@id": "http://example.org/library/the-republic#introduction"
    }
  }
}

This generates the following framed results:

Frames can also be matched from an array of identifiers. Within a frame, it is acceptable for @id to have an array value, where the individual values are treated as IRIs.

Example 17: Library frame with array @id matching
{
  "@context": {"@vocab": "http://example.org/"},
  "@id": ["http://example.org/home", "http://example.org/library"],
  "contains": {
    "@id": ["http://example.org/library/the-republic"],
    "contains": {
      "@id": ["http://example.org/library/the-republic#introduction"]
    }
  }
}

This generates the following framed results:

2.1.6 Empty Frame

This section is non-normative.

An empty frame matches any node object, even if those objects are embedded elsewhere, causing them to be serialized at the top level.

Example 19: Empty frame
{
  "@context": {"@vocab": "http://example.org/"}
}

This generates the following framed results:

2.2 Default content

This section is non-normative.

A frame may specify properties that don't exist in an input file. If the explicit inclusion flag is false, the framing algorithm will add a property and value to the result. The @default property in a node object or value object, or as a value of @type, provides a default value to use in the resulting output document. If there is no @default value, the property will be output with a null value. (See § 2.3.3 Omit default flag for ways to avoid this).

Note

The value of the property in the frame is not otherwise used in the output document. It's purpose is for frame matching and finding default values. Note the description value for Library in the following example.

Example 21: Sample library frame with @default value
{
  "@context": {"@vocab": "http://example.org/"},
  "@type": "Library",
  "description": "A great Library.",
  "contains": {
    "@type": "Book",
    "description": {"@default": "A great book."},
    "contains": {
      "@type": "Chapter"
    }
  }
}

Default values may also be used for @type, similar to other properties. In this case, a matched node object without an @type will take the value of the default object from the frame. The default object has a value which is a single IRI. If multiple IRIs are specified, only the first will be used as the default type.

The frame matches objects having specific property values, and provides defaults for @type for matched objects.

Example 23: Sample library frame with @default type
{
  "@context": {"@vocab": "http://example.org/"},
  "@type": "Library",
  "contains": {
    "@type": {"@default": "Book"},
    "creator": "Plato",
    "contains": {
      "@type": {"@default": "Chapter"},
      "description": "An introductory chapter on The Republic."
    }
  }
}

Data missing specific values for @type, but which matches based on other property values.

Example 24: Typeless library objects
{
  "@context": {
    "@vocab": "http://example.org/",
    "contains": {"@type": "@id"}
  },
  "@graph": [{
    "@id": "http://example.org/library",
    "@type": "Library",
    "contains": "http://example.org/library/the-republic"
  }, {
    "@id": "http://example.org/library/the-republic",
    "creator": "Plato",
    "title": "The Republic",
    "contains": "http://example.org/library/the-republic#introduction"
  }, {
    "@id": "http://example.org/library/the-republic#introduction",
    "description": "An introductory chapter on The Republic.",
    "title": "The Introduction"
  }]
}

2.3 Framing Flags

This section is non-normative.

Framing can be controlled using API options, or by adding framing keywords within the frame as described in § 1.5 Syntax Tokens and Keywords.

Note

Framing flags set using keywords have effect only for the frame in which they appear, and for implicit frames which are created for objects where no frame object exists.

2.3.1 Object Embed Flag

This section is non-normative.

The object embed flag determines if a referenced node object is embedded as a property value of a referencing object, or kept as a node reference. The initial value for the object embed flag is set using the embed option. Consider the following frame based on the default @once value of the object embed flag:

Example 26: Sample library frame with implicit @embed set to @once
{
  "@context": {"@vocab": "http://example.org/"},
  "@type": "Library"
}

Because, the default for the object embed flag is @once (in addition to the explicit inclusion flag being false), non-listed properties are added to the output, and implicitly embedded using a default empty frame. As a result, the same output used in the Framed library objects above is generated, assuming that the ordered flag is true.

However, if the @embed property is added explicitly with a value of @never, the values for Book and Chapter will be excluded.

Example 28: Sample library frame with explicit @embed set to @never
{
  "@context": {"@vocab": "http://example.org/"},
  "@type": "Library",
  "contains": {
    "@type": "Book",
    "@embed": "@never"
  }
}

To illustrate the case where @once does not expand values, consider an alternate library example where books are doubly indexed.

Example 30: Flattened library objects with double index
{
  "@context": {
    "@vocab": "http://example.org/",
    "books": {"@type": "@id"},
    "contains": {"@type": "@id"}
  },
  "@graph": [{
    "@id": "http://example.org/library",
    "@type": "Library",
    "books": "http://example.org/library/the-republic",
    "contains": "http://example.org/library/the-republic"
  }, {
    "@id": "http://example.org/library/the-republic",
    "@type": "Book",
    "creator": "Plato",
    "title": "The Republic",
    "contains": "http://example.org/library/the-republic#introduction"
  }, {
    "@id": "http://example.org/library/the-republic#introduction",
    "@type": "Chapter",
    "description": "An introductory chapter on The Republic.",
    "title": "The Introduction"
  }]
}

When framed using the same frame with the default @embed of @once, only the "books" property will have content, if the ordered flag is true, and the "contains" property will use a reference.

If we use a frame using "@embed": "@always", both properties will include expanded values.

Example 32: Sample library frame with explicit @embed set to @always
{
  "@context": {"@vocab": "http://example.org/"},
  "@type": "Library",
  "@embed": "@always"
}

2.3.2 Explicit inclusion flag

This section is non-normative.

The explicit inclusion flag used to determine properties which will be included in the output document. The default value is false, which means that properties present in an input node object that are not in the associated frame will be included in the output object. If true, only properties present in the input frame will be placed into the output. The initial value for the explicit inclusion flag is set using the explicit option.

For example, take an expanded version of the library frame which include some properties from the input, but omit others.

Example 34: Sample library frame with @explicit set to true
{
  "@context": {"@vocab": "http://example.org/"},
  "@type": "Library",
  "description": {},
  "contains": {
    "@type": "Book",
    "@explicit": true,
    "title": {},
    "contains": {
      "@type": "Chapter"
    }
  }
}

The resulting output will exclude properties for Book which are not explicitly listed in the frame object:

Note that the Library object contains a null description property, as it is explicitly called for in the frame using "description": {}. The creator property does not exist in the output, because it is not explicit.

2.3.3 Omit default flag

This section is non-normative.

The omit default flag changes the way framing generates output when a property described in the frame is not present in the input document. The initial value for the omit default flag is set using the omitDefault option. See § 2.2 Default content for a further discussion.

Consider the following input document:

Example 36: Sample parent/child relationship data
{
  "@context": {
    "@vocab": "http://example.org/",
    "child": {"@type": "@id"}
  },
  "@graph": [{
    "@id": "http://example.org#John",
    "@type": "Person",
    "name": "John",
    "child": "http://example.org#Jane"
  }, {
    "@id": "http://example.org#Jane",
    "@type": "Person",
    "name": "Jane"
  }]
}

To illustrate where the omit default flag is useful, consider the following frame, which does not use @omitDefault:

Example 37: Sample parent/child relationship frame without @omitDefault
{
  "@context": {
    "@vocab": "http://example.org/",
    "child": {"@type": "@id"}
  },
  "@type": "Person",
  "child": {
    "@embed": "@always"
  }
}

The resulting output will include a "child" property with the value null, which may not always be desired:

Note that because the option "@embed": "@always" is specified in the frame under the child property, that "child": null appears in the output for matches that do not have that property, which may be undesirable. To prevent this default null output from occurring, the @omitDefault may be set to true like so:

Example 39: Sample parent/child relationship frame with @omitDefault
{
  "@context": {
    "@vocab": "http://example.org/",
    "child": {"@type": "@id"}
  },
  "@type": "Person",
  "child": {
    "@embed": "@always",
    "@omitDefault": true
  }
}

Which yields this (desirable) output:

2.3.4 Omit graph flag

This section is non-normative.

The omit graph flag determines if framed output containing a single node object is contained within @graph, or not. The initial value for the omit graph flag is set using the omitGraph option, or based on the processing mode; if processing mode is json-ld-1.0, the output always includes a @graph entry, otherwise, the @graph entry is used only to describe multiple node objects, consistent with compaction. See § 4.1 Framing Algorithm for a further discussion.

The result is the same as the original Flattened library objects example, but a @graph at the top-level. Example 5 shows the results with the omit graph flag set to true, which is the default value when the processing mode is set to the default json-ld-1.1. The top-level object can be enclosed within @graph by setting the processing mode to json-ld-1.0, or by setting the omit graph flag to false.

2.3.5 Require all flag

This section is non-normative.

The require all flag is used in frame matching to determine when a node object from an input document matches a frame. When matching, an object may include @type and other properties, a match is made when any property value in the object matches the node pattern in the frame object if the value of the require all flag is false (the default). If the flag value is true, then all properties in the frame object must be present in the node object for the node to match.

The following frame matches on multiple properties, including the absence of a property. Using the Flattened library objects example, we can match on an object containing both the title and description or title and creator properties. If we were to use @requireAll set to false, then we could match on the presence of any property, not all properties.

Example 42: Frame with @requireAll
{
  "@context": {"@vocab": "http://example.org/"},
  "@type": "Library",
  "contains": {
    "@requireAll": true,
    "creator": {},
    "title": {},
    "contains": {
      "@requireAll": true,
      "description": {},
      "title": {}
    }
  }
}

This will, again, reproduce the desired framed output:

2.4 Reverse Framing

This section is non-normative.

A frame may include @reverse, or a value of a term defined using @reverse to invert the relationships in the output object. For example, the Library example can be inverted using the following frame:

Example 44: Inverted library frame
{
  "@context": {
    "@vocab": "http://example.org/",
    "within": {"@reverse": "contains"}
  },
  "@type": "Chapter",
  "within": {
    "@type": "Book",
    "within": {
      "@type": "Library"
    }
  }
}

Using the flattened library example above, results in the following:

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:

Example 46: Frame with named graphs
{
  "@context": {"@vocab": "http://example.org/"},
  "@type": "Library",
  "contains": {
    "@id": "http://example.org/graphs/books",
    "@graph": {
      "@type": "Book"
    }
  }
}
Example 47: Flattened Input with named graphs
[{
  "@context": {"@vocab": "http://example.org/"},
  "@id": "http://example.org/graphs/books",
  "@graph": [{
    "@id": "http://example.org/library/the-republic",
    "@type": "http://example.org/Book",
    "http://example.org/contains": {
      "@id": "http://example.org/library/the-republic#introduction"
    },
    "http://example.org/creator": "Plato",
    "http://example.org/title": "The Republic"
  }, {
    "@id": "http://example.org/library/the-republic#introduction",
    "@type": "http://example.org/Chapter",
    "http://example.org/description": "An introductory chapter on The Republic.",
    "http://example.org/title": "The Introduction"
  }]
}, {
  "@context": {"@vocab": "http://example.org/"},
  "@id": "http://example.org/library",
  "@type": "http://example.org/Library",
  "http://example.org/contains": {"@id": "http://example.org/graphs/books"},
  "http://example.org/name": "Library"
}]

3. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

There is one class of products that can claim conformance to this specification: JSON-LD Processors.

A conforming JSON-LD Processor is a system which can perform the Framing operation in a manner consistent with the algorithms defined in this specification.

JSON-LD Processors MUST NOT attempt to correct malformed IRIs or language tags; however, they MAY issue validation warnings. IRIs are not modified other than conversion between relative and absolute IRIs.

Unless specified using processingMode API option, the processing mode is set using the @version entry in a local context and affects the behavior of algorithms including expansion and compaction. Once set, it is an error to attempt to change to a different processing mode, and processors MUST generate, a processing mode conflict error and abort further processing.

The algorithms in this specification are generally written with more concern for clarity than efficiency. Thus, JSON-LD Processors MAY implement the algorithms given in this specification in any way desired, so long as the end result is indistinguishable from the result that would be obtained by the specification's algorithms.

In algorithm steps that describe operations on keywords, those steps also apply to keyword aliases.

Note

Implementers can partially check their level of conformance to this specification by successfully passing the test cases of the JSON-LD framing test suite. Note, however, that passing all the tests in the test suite does not imply complete conformance to this specification. It only implies that the implementation conforms to aspects tested by the test suite.

4. Framing

The following sections describe algorithms for framing JSON-LD documents. Framing is the process of taking a JSON-LD document, which expresses a graph of information, and applying a specific graph layout (called a Frame).

Framing makes use of the Node Map Generation algorithm to place each object defined in the JSON-LD document into a map of flattened subjects, allowing them to be operated upon by the Framing algorithm.

All algorithms described in this section are intended to operate on language-native data structures. That is, the serialization to a text-based JSON document isn't required as input or output to any of these algorithms.

Reference to JSON data structures are interpreted using their internal representation for the purpose of describing algorithms.

4.1 Framing Algorithm

4.1.1 Overview

A valid JSON-LD Frame is a superset of a valid JSON-LD document, allowing additional content, which is preserved through expansion. The Grammar defined in the JSON-LD 1.1 Syntax specification [JSON-LD11] is extended as follows:

4.1.2 Algorithm

The framing algorithm takes five required input variables and one optional input variable. The required inputs are a framing state (state), a list of subjects to frame, an input frame (expanded frame), a parent used to collect partial frame results, and an active property. The optional input variable is the ordered flag.

The algorithm adds elements to parent either by appending the element to parent, if it is an array, or by appending it to an array associated with active property in parent, if it is a map. Note that if parent is an array, active property MUST be null, and if it is a map, it MUST NOT be null.

  1. 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.
    1. Frame MUST be a map.
    2. If frame has an @id entry, its value MUST be either an array containing a single empty map as a value, a valid IRI or an array where all values are valid IRIs.
    3. If frame has a @type entry, its value MUST be either an array containing a single empty map as a value, an array containing a map with a entry whose key is @default, a valid IRI or an array where all values are valid IRIs.
  2. Initialize flags embed, explicit, and requireAll from object embed flag, explicit inclusion flag, and require all flag in state overriding from any property values for @embed, @explicit, and @requireAll in frame.
  3. Create a list of matched subjects by filtering subjects against frame using the Frame Matching algorithm with state, subjects, frame, and requireAll.
  4. For each id and associated node object node from the set of matched subjects, ordered lexicographically by id if the optional ordered flag is true:
    1. Initialize output to a new map with @id and id.
    2. 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.
    3. 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.
    4. 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.
    5. If graph map in state has an entry for id:
      1. If frame does not have a @graph entry, set recurse to true, unless graph name in state is @merged and set subframe to a new empty map.
      2. 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.
      3. If recurse is true:
        1. Set the value of graph name in state to id.
        2. Set the value of embedded flag in state to false.
        3. 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.
    6. If frame has an @included entry, invoke the algorithm using a copy of state with the value of embedded flag set to false, subjects, frame, output as parent, and @included as active property.
    7. For each property and objects in node, ordered lexicographically by property if the optional ordered flag is true:
      1. If property is a keyword, add property and objects to output.
      2. Otherwise, if property is not in frame, and explicit is true, processors MUST NOT add any values for property to output, and the following steps are skipped.
      3. For each item in objects:
        1. 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:
          1. If listitem is a node reference, invoke the algorithm using a copy of state with the value of embedded flag set to true, the value of @id from listitem as the sole item in a new subjects array, the first value from @list in frame as frame, list as parent, and @list as active property. If frame does not exist, create a new frame using a new map with properties for @embed, @explicit and @requireAll taken from embed, explicit and requireAll.
          2. Otherwise, append a copy of listitem to @list in list.
        2. If item is a node reference, invoke the algorithm using a copy of state with the value of embedded flag set to true, the value of @id from item as the sole item in a new subjects array, the first value from property in frame as frame, output as parent, and property as active property. If frame does not exist, create a new frame using a new map with properties for @embed, @explicit and @requireAll taken from embed, explicit and requireAll.
        3. Otherwise, append a copy of item to active property in output.
      4. For each non-keyword property and objects in frame (other than `@type) that is not in output:
        1. Let item be the first value in objects, which MUST be a frame object.
        2. Set property frame to the first value in objects or a newly created frame object if value is objects. property frame MUST be a map.
        3. 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.
        4. 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.
      5. If frame has the property @reverse, then for each reverse property and sub frame that are the values of @reverse in frame:
        1. Create a @reverse property in output with a new map reverse dict as its value.
        2. For each reverse id and node in the map of flattened subjects that has the property reverse property containing a node reference with an @id of id:
          1. Add reverse property to reverse dict with a new empty array as its value.
          2. Invoke the algorithm using a copy of state with the value of embedded flag set to true, the reverse id as the sole item in a new subjects array, sub frame as frame, null as active property, and the array value of reverse property in reverse dict as parent.
      6. Once output has been set are required in the previous steps, add output to parent.

4.2 Frame Matching Algorithm

The Frame Matching Algorithm is used as part of the Framing algorithm to determine if a particular node object matches the criteria set in a frame. In general, a node object matches a frame if it meets the matches on @type, @id, or if it matches given one of several different properties. If the require all flag is true, all properties must have defaults or match for the frame to match.

Note

As matching is performed on expanded node objects, all values will be in the form of an array.

Node matching uses a combination of JSON constructs to match any, zero, or some specific values:

[] (match none)
An empty array matches no values, or a value which is, itself, an empty array.
[frame object] (node pattern)
A non-empty frame object, used to match specific values using recursive node matching.
[IRI+]
One or more strings in the form of an IRI, used for matching on @type and @id, which allows a match on any of the listed IRIs.
[value object] (value pattern)
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.

  1. node matches if frame has no properties.
  2. 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:
    1. If property is @id:
      1. property matches if the @id property in frame includes any IRI in values.
      2. 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
    2. Otherwise, if property is @type:
      1. property matches if the @type property in frame includes any IRI in values.
      2. Otherwise, property matches if values is not empty and the @type property in frame is wildcard.
      3. Otherwise, property matches if values is empty and the @type property in frame is match none.
      4. Otherwise, property matches if the @type property in frame is a default object.
      5. Otherwise, property does not match.
    3. If property is @id or @type and does not match, node does not match, and processing is terminated.
    4. Otherwise, the value of property in frame MUST be empty, or an array containing a valid frame.
    5. property matches if values is empty, or non existent, the value of property in frame is a map containing only the @default entry with any value, and any other property in node has a non-default match.
    6. node does not match if values is not empty and the value of property in frame is match none, and further matching is aborted.
    7. Otherwise, property matches if values is not empty and the value of property in frame is wildcard.
    8. Otherwise, if the value of property in frame is a value pattern (value pattern): property matching is determined using the Value matching algorithm.
    9. Otherwise, for any node pattern (node pattern) which is one of the values of property in frame:
      1. Let value subjects be the list of subjects from the map of flattened subjects matching the node object values from values.
      2. 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.
      3. property matches if matched subjects is not empty.
    10. 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:

  1. 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..
  2. 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..
  3. Value matches pattern when pattern is wildcard, or:
    1. v1 is in v2, or v1 is not null and v2 is wildcard, and
    2. 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
    3. l1 is in l2, or l1 is not null and l2 is wildcard, or null, or l1 is null and l2 is null or match none.

5. The Application Programming Interface

This API provides a clean mechanism that enables developers to convert JSON-LD data into a variety of output formats that are easier to work with in various programming languages. If a JSON-LD API is provided in a programming environment, the entirety of the following API MUST be implemented.

The JSON-LD API uses Promises to represent the result of the various deferred operations. Promises are defined in [ECMASCRIPT]. General use within specifications can be found in [promises-guide]. Implementations MAY chose to implement in an appropriate way for their native environments as long as they generally use the same methods, arguments, and options and return the same results.

Note

Interfaces are marked [Exposed=JsonLd], which creates a global interface. The use of WebIDL in JSON-LD, while appropriate for use within browsers, is not limited to such use.

5.1 JsonLdProcessor

The JSON-LD Processor interface is the high-level programming structure that developers use to access the JSON-LD transformation methods. The definition below is an experimental extension of the interface defined in the JSON-LD 1.1 API [JSON-LD11-API].

It is important to highlight that implementations do not modify the input parameters. If an error is detected, the Promise is rejected with a JsonLdFramingError having an appropriate code and processing is stopped.

WebIDL/*
 * The JsonLd interface is created to expose the JsonLdProcessor interface.
 */
[Global=JsonLd, Exposed=JsonLd]
interface JsonLd {};

[Exposed=JsonLd]
interface JsonLdProcessor {
  constructor();
  static Promise<JsonLdRecord> frame(
    JsonLdInput input,
    JsonLdInput frame,
    optional JsonLdOptions options = {});
};

The JsonLdProcessor interface frame() method Frames the given input using frame according to the steps in the Framing Algorithm:

  1. Create a new Promise promise and return it. The following steps are then executed asynchronously.
  2. If the provided input is a RemoteDocument, initialize remote document to input.
  3. Otherwise, if the provided input is a string representing the IRI of a remote document, await and dereference it as remote document using LoadDocumentCallback, passing input for url, and the extractAllScripts option from options for extractAllScripts.
  4. Set expanded input to the result of using the expand method either remote document or input if there is no remote document for input and options with ordered set to false.
  5. If the provided frame is a RemoteDocument, initialize remote frame to frame.
  6. Otherwise, if the provided frame is a string representing the IRI of a remote document, await and dereference it as remote frame using LoadDocumentCallback, passing frame for url, and the extractAllScripts option from options for extractAllScripts.
  7. Set expanded frame to the result of using the expand method either remote frame or frame if there is no remote frame for input options the frameExpansion option set to true, and theordered set to false.
  8. Set context to the value of @context from remote frame or frame, if it exists, or to a new empty context, otherwise.
  9. Set context base to the documentUrl from remote frame, if available, otherwise to the base option from options.
  10. Initialize active context to the result of the Context Processing algorithm passing a new empty context as active context context as local context, and context base as base URL.
  11. 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.
  12. Initialize inverse context to the result of performing the Inverse Context Creation algorithm.
  13. If frame has a top-level property which expands to @graph set the frameDefault option to options with the value true.
  14. Initialize a new framing state (state) to an empty map.
    1. Set object embed flag in state to embed with the default value @once.
    2. Set the embedded flag in state to false
    3. Set explicit inclusion flag in state to explicit with the default value false.
    4. Set require all flag in state to requireAll with the default value false.
    5. Set omit default flag in state to omitDefault with the default value false.
    6. Set the graph name in state to either @default if frameDefault is true, otherwise to false.
    7. Set the graph map in state to the result of performing the Node Map Generation algorithm on expanded input.
      1. If graph name in state is @merged, add en entry for @merged in graph map set to the result of the Merge Node Maps algorithm passing graph map.
    8. Set subject map in state to the map of flattened subjects which is the value of graph name in graph map.
  15. Initialize results as an empty array.
  16. 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.
  17. If the processing mode is not json-ld-1.0, remove the @id entry of each node object in results where the entry value is a blank node identifier which appears only once in any property value within results.
  18. 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.
  19. Set compacted results to the result of using the compact method using active context, inverse context, null for active property, results as element,, and the compactArrays and ordered flags from options.
    1. If compacted results is an empty array, replace it with a new map.
    2. 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.
    3. Add an @context entry to compacted results and set its value to the provided context.
  20. 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.
  21. If omitGraph is false and compacted results does not have a top-level @graph entry, or its value is not an array, modify compacted results to place the non @context entry of compacted results into a map contained within the array value of @graph. If omitGraph is true, a top-level @graph entry is used only to contain multiple node objects.
  22. 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.
WebIDLtypedef record<USVString, any> JsonLdRecord;

The JsonLdRecord is the definition of a map used to contain arbitrary map entries which are the result of parsing a JSON Object.

WebIDLtypedef (JsonLdRecord or sequence<JsonLdRecord> or USVString or RemoteDocument) JsonLdInput;

The JsonLdInput interface is used to refer to an input value that that may be a JsonLdRecord, a sequence of JsonLdRecords, a string representing an IRI, which can be dereferenced to retrieve a valid JSON document, or an already dereferenced RemoteDocument.

When the value is a JsonLdRecord or sequence of JsonLdRecords, the values are taken as their equivalent internal representation values, where a JsonLdRecord is equivalent to a map, and a sequence of JsonLdRecords is equivalent to an array of maps. The map entries are converted to their equivalents in [INFRA].

5.2 Error Handling

The JsonLdFramingError type is used to report processing errors.

WebIDLdictionary JsonLdFramingError {
  JsonLdFramingErrorCode code;
  USVString? message = null;
};
enum JsonLdFramingErrorCode {
  "invalid frame",
  "invalid @embed value"
};

JSON-LD Framing extends the error interface and codes defined in JSON-LD 1.1 Processing Algorithms and API the JSON-LD 1.1 API [JSON-LD11-API].

code
a string representing the particular error type, as described in the various algorithms in this document.
message
an optional error message containing additional debugging information. The specific contents of error messages are outside the scope of this specification.

The JsonLdFramingErrorCode represents the collection of valid JSON-LD Framing error codes.

invalid @embed value
The value for @embed is not one recognized for the object embed flag.
invalid frame
The frame is invalid.

5.3 Data Structures

This section describes datatype definitions used within the JSON-LD API.

5.3.1 JsonLdContext

The JsonLdContext type is used to refer to a value that that may be a map, a string representing an IRI, or an array of maps and strings.

See JsonLdContext definition in the JSON-LD 1.1 API [JSON-LD11-API].

5.3.2 JsonLdOptions

The JsonLdOptions type is used to pass various options to the JsonLdProcessor methods.

WebIDLdictionary JsonLdOptions {
  (JsonLdEmbed or boolean)  embed         = "@once";
  boolean                   explicit      = false;
  boolean                   omitDefault   = false;
  boolean                   omitGraph;
  boolean                   requireAll    = false;
  boolean                   frameDefault  = false;
  boolean                   ordered       = false;
};

enum JsonLdEmbed {
  "@always",
  "@once",
  "@never"
};

In addition to those options defined in the JSON-LD 1.1 API [JSON-LD11-API], framing defines these additional options:

embed
Sets the value object embed flag used in the Framing Algorithm. A boolean value of true sets the flag to @once, while a value of false sets the flag to @never.
explicit
Sets the value explicit inclusion flag used in the Framing Algorithm.
frameDefault
Instead of framing a merged graph, frame only the default graph.
omitDefault
Sets the value omit default flag used in the Framing Algorithm
omitGraph
Sets the value omit graph flag used in the Framing Algorithm. If not set explicitly, it is set to false if processing mode is json-ld-1.0, true otherwise.
ordered
If set to true, certain algorithm processing steps where indicated are ordered lexicographically. If false, order is not considered in processing.
requireAll
Sets the value require all flag used in the Framing Algorithm.

JsonLdEmbed enumerates the values of the embed option:

@always
Always embed node objects as property values, unless this would cause a circular reference.
@never
Always use a node reference when serializing matching values.
@once
Only a single value within a given node object should be embedded, other values of other properties use a node reference. This is the default value if neither @embed nor object embed flag is specified.

See JsonLdOptions definition in the JSON-LD 1.1 API [JSON-LD11-API].

6. Security Considerations

See, Security Considerations in § A. IANA Considerations.

7. Privacy Considerations

See, Privacy Considerations in [JSON-LD11].

8. Internationalization Considerations

See, Internationalization Considerations in [JSON-LD11].

A. IANA Considerations

This section is included merely for standards community review and will be submitted to the Internet Engineering Steering Group if this specification becomes a W3C Recommendation.

A JSON-LD Frame uses the same MIME media type described in [JSON-LD11] along with a required profile parameter.

application/ld+json

Type name:
application
Subtype name:
ld+json
Required parameters:
None
Optional parameters:
profile

A single URI identifying the resource as a JSON-LD Frame. A profile does not change the semantics of the resource representation when processed without profile knowledge, so that clients both with and without knowledge of a profiled resource can safely use the same representation.

http://www.w3.org/ns/json-ld#framed
To specify a JSON-LD Frame.

The http://www.w3.org/ns/json-ld#framed SHOULD be used when serving and requesting a JSON-LD frame document.

Encoding considerations:
See RFC 8259, section 11.
Security considerations:
See RFC 8259, section 12 [RFC8259]

Since JSON-LD is intended to be a pure data exchange format for directed graphs, the serialization SHOULD NOT be passed through a code execution mechanism such as JavaScript's eval() function to be parsed. An (invalid) document may contain code that, when executed, could lead to unexpected side effects compromising the security of a system.

When processing JSON-LD documents, links to remote contexts are typically followed automatically, resulting in the transfer of files without the explicit request of the user for each one. If remote contexts are served by third parties, it may allow them to gather usage patterns or similar information leading to privacy concerns. Specific implementations, such as the API defined in the JSON-LD 1.1 Processing Algorithms and API specification [JSON-LD11-API], may provide fine-grained mechanisms to control this behavior.

JSON-LD contexts that are loaded from the Web over non-secure connections, such as HTTP, run the risk of being altered by an attacker such that they may modify the JSON-LD active context in a way that could compromise security. It is advised that any application that depends on a remote context for mission critical purposes vet and cache the remote context before allowing the system to use it.

Given that JSON-LD allows the substitution of long IRIs with short terms, JSON-LD documents may expand considerably when processed and, in the worst case, the resulting data might consume all of the recipient's resources. Applications should treat any data with due skepticism.

As JSON-LD places no limits on the IRI schemes that may be used, and vocabulary-relative IRIs use string concatenation rather than IRI resolution, it is possible to construct IRIs that may be used maliciously, if dereferenced.

Interoperability considerations:
Not Applicable
Published specification:
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
Change controller:
W3C

Fragment identifiers used with application/ld+json are treated as in RDF syntaxes, as per RDF 1.1 Concepts and Abstract Syntax [RDF11-CONCEPTS].

B. IDL Index

This section is non-normative.

WebIDL/*
 * The JsonLd interface is created to expose the JsonLdProcessor interface.
 */
[Global=JsonLd, Exposed=JsonLd]
interface JsonLd {};

[Exposed=JsonLd]
interface JsonLdProcessor {
  constructor();
  static Promise<JsonLdRecord> frame(
    JsonLdInput input,
    JsonLdInput frame,
    optional JsonLdOptions options = {});
};

typedef record<USVString, any> JsonLdRecord;

typedef (JsonLdRecord or sequence<JsonLdRecord> or USVString or RemoteDocument) JsonLdInput;

dictionary JsonLdFramingError {
  JsonLdFramingErrorCode code;
  USVString? message = null;
};
enum JsonLdFramingErrorCode {
  "invalid frame",
  "invalid @embed value"
};

dictionary JsonLdOptions {
  (JsonLdEmbed or boolean)  embed         = "@once";
  boolean                   explicit      = false;
  boolean                   omitDefault   = false;
  boolean                   omitGraph;
  boolean                   requireAll    = false;
  boolean                   frameDefault  = false;
  boolean                   ordered       = false;
};

enum JsonLdEmbed {
  "@always",
  "@once",
  "@never"
};

C. Open Issues

This section is non-normative.

The following is a list of issues open at the time of publication.

Allow class-scoped framing.

Issue 38: Several frames in the same frame document? defer-future-versionspec:enhancementspec:substantive

Several frames in the same frame document?

Issue 73: Reframing Relationships defer-future-version

Reframing Relationships.

D. Changes since 1.0 Draft of 30 August 2012

This section is non-normative.

E. Changes since JSON-LD Community Group Final Report

This section is non-normative.

F. Changes since Candidate Release of 12 December 2019

This section is non-normative.

G. Changes since Proposed Recommendation Release of 7 May 2020

This section is non-normative.

H. Acknowledgements

This section is non-normative.

The editors would like to specially thank the following individuals for making significant contributions to the authoring and editing of this specification:

Additionally, the following people were members of the Working Group at the time of publication:

A large amount of thanks goes out to the JSON-LD Community Group participants who worked through many of the technical issues on the mailing list and the weekly telecons: Chris Webber, David Wood, Drummond Reed, Eleanor Joslin, Fabien Gandon, Herm Fisher, Jamie Pitts, Kim Hamilton Duffy, Niklas Lindström, Paolo Ciccarese, Paul Frazze, Paul Warren, Reto Gmür, Rob Trainer, Ted Thibodeau Jr., and Victor Charpenay.

I. References

I.1 Normative references

[BCP47]
Tags for Identifying Languages. A. Phillips; M. Davis. IETF. September 2009. IETF Best Current Practice. URL: https://tools.ietf.org/html/bcp47
[ECMASCRIPT]
ECMAScript Language Specification. Ecma International. URL: https://tc39.es/ecma262/
[INFRA]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[JSON-LD10]
JSON-LD 1.0. Manu Sporny; Gregg Kellogg; Marcus Langhaler. W3C. 16 January 2014. W3C Recommendation. URL: https://www.w3.org/TR/2014/REC-json-ld-20140116/
[JSON-LD11]
JSON-LD 1.1. Gregg Kellogg; Pierre-Antoine Champin; Dave Longley. W3C. 7 May 2020. W3C Proposed Recommendation. URL: https://www.w3.org/TR/json-ld11/
[JSON-LD11-API]
JSON-LD 1.1 Processing Algorithms and API. Gregg Kellogg; Dave Longley; Pierre-Antoine Champin. W3C. 7 May 2020. W3C Proposed Recommendation. URL: https://www.w3.org/TR/json-ld11-api/
[LINKED-DATA]
Linked Data Design Issues. Tim Berners-Lee. W3C. 27 July 2006. W3C-Internal Document. URL: https://www.w3.org/DesignIssues/LinkedData.html
[promises-guide]
Writing Promise-Using Specifications. Domenic Denicola. W3C. 9 November 2018. TAG Finding. URL: https://www.w3.org/2001/tag/doc/promises-guide
[RDF-SCHEMA]
RDF Schema 1.1. Dan Brickley; Ramanathan Guha. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf-schema/
[RDF11-CONCEPTS]
RDF 1.1 Concepts and Abstract Syntax. Richard Cyganiak; David Wood; Markus Lanthaler. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf11-concepts/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC3987]
Internationalized Resource Identifiers (IRIs). M. Duerst; M. Suignard. IETF. January 2005. Proposed Standard. URL: https://tools.ietf.org/html/rfc3987
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174
[RFC8259]
The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. December 2017. Internet Standard. URL: https://tools.ietf.org/html/rfc8259
[WEBIDL]
Web IDL. Boris Zbarsky. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/

I.2 Informative references

[JSON-LD10-FRAMING]
JSON-LD Framing 1.0. Manu Sporny; Gregg Kellogg; David Longley; Marcus Langhaler. W3C. 30 August 2012. Unofficial Draft. URL: https://json-ld.org/spec/ED/json-ld-framing/20120830/