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

This document is an experimental work in progress.


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.

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:

To understand the basics in this specification you must first be familiar with JSON, which is detailed in [[!RFC7159]]. You must also understand the JSON-LD Syntax [[!JSON-LD]], which is the base syntax used by all of the algorithms in this document, and the JSON-LD API [[!JSON-LD-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 [[ECMA-262]] and WebIDL [[!WebIDL-2]]. To understand how JSON-LD maps to RDF, it is helpful to be familiar with the basic RDF concepts [[!RDF-CONCEPTS]].


There are a number of ways that one may participate in the development of this specification:


Typographical conventions

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.

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.

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.


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 abstract representation for the purpose of describing algorithms.

Syntax Tokens and Keywords

This specification adds a number of keywords to the ones defined in the [[!JSON-LD]] specification:

Used in Framing to set the default value for an output property when the framed node object does not include such a property.
Used in Framing to override the value of object embed flag within a specific frame. Valid values for @embed as the following:
Always embed node objects as property values, unless this would cause a circular reference.
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.
In the in-memory abstract representation, nodes are linked directly, which allows for circular references. Always use a node reference when serializing matching values. Do we want to describe this here? Or, perhaps in a separate JSON-LD Linking document?
Always use a node reference when serializing matching values.
Used in Framing to override the value of explicit inclusion flag within a specific frame.
Used in Framing when a value of null should be returned, which would otherwise be removed when Compacting.
Used in Framing to override the value of omit default flag within a specific frame.
Used in Framing to override the value of require all flag within a specific frame.

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


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.

Framing Requirements

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 [[JSON-LD]] is extended as follows:

  • Framing adds the following keywords used as keys of a node object, which MUST be preserved when expanding:
    • @embed,
    • @explicit,
    • @omitDefault, and
    • @requireAll

    Additionally, values of the @embed key MUST only be one of the following keyword values, or an array containing only one of these values:

    • @always,
    • @last,
    • @link,
    • @never,
    • true (equivalent to @last), or
    • false (equivalent to @never)

    Otherwise, an invalid @embed value error has been detected and processing is aborted.

  • Values of keys in a node object that are not keyword MAY also include a default object. Values of @default MAY include the value @null, or an array containing only @null, in addition to other values allowed in the grammar for values of keys expanding to absolute IRIs. Processors MUST preserve this value when expanding. All other key/value pairs of a default object MUST be ignored.
  • The values of @id and @type may also be an empty JSON object, or an array containing only an empty JSON object. Processors MUST preserve this value when expanding.

Framing Algorithm

The framing algorithm takes an JSON-LD input (expanded input), which MUST be a JSON-LD document in expanded form, an input frame (expanded frame), which MUST be a JSON-LD frame in expanded form, a context (context), and a number of options and produces JSON-LD output.

If an error is detected in the expanded frame, a processor MUST generate a JsonLdFramingError with code set to invalid frame. Need more specifics as to what constitutes a valid frame.

The recursive algorithm operates with a framing state (state), created initially using the object embed flag set to true, the explicit inclusion flag set to false, the require all flag set to true, and the omit default flag set to false along with map of flattened subjects set to the @merged property of the result of performing the Node Map Generation algorithm on expanded input, subjectStack set to an empty array, link set to an empty dictionary. Also initialize results as an empty array.

Processors MAY 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 frame (frame), 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 property MUST 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:

  1. If frame is an array, set frame to the first member of the array, which MUST be a valid frame.
  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. A node object (node) associated with a subject from the map of flattened subjects matches frame in the following circumstances:
    1. A subject matches if node has a @type property including any IRI from the corresponding @type property in frame.
    2. Otherwise, a subject matches if node has a @type property and frame has a @type property containing only an empty dictionary.
    3. Otherwise, a subject matches if node and frame both have the same @id property.
    4. Otherwise, a subject does not match if node has a property and frame has an empty array for that same property.
    5. Otherwise, a subject matches if requireAll is false and both node and frame contain common non-keyword properties of any value. Having any value might not be adequate, as contained nodes might have other matching criteria that could fail to match.
    6. Otherwise, a subject matches if requireAll is true and all the non-keyword properties in frame exist in node with any value, or properties missing in node each have a property in frame which has a dictionary value containing only the key @default with any value.
    7. Otherwise, a subject does not match.
  4. For each id and associated node object node from the set of matched subjects, ordered by id:

    Can we remove sorting, or make it subject to a processing flag? In general, sorting is a performance problem for JSON-LD, and inhibits stream processing.

    1. Initialize output to a new dictionary with @id and id and add output to link associated with id.
    2. If embed is @link and id is in link, node already exists in results. Add the associated node object from link to parent and do not perform additional processing for this node.
    3. 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.
    4. Otherwise, if embed is @last, remove any existing embedded node from parent. Requires sorting of subjects. We could consider @sample, to embed just the first matched node. With sorting, we could also consider @first.
    5. If embed is @last or @always
      1. For each property and objects in node, ordered by property:
        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 dictionary with the property @list, then each listitem in the list is processed in sequence and added to a new list dictionary in output:
            1. If listitem is a node reference, invoke the recursive algorithm using state, the value of @id from listitem as the sole member of a new subjects array, the first value from @list in frame as frame, list as parent, and @list as active property. Could this use the list array, and null for active property?
            2. Otherwise, append a copy of listitem to @list in list.
          2. If item is a node reference, invoke the recursive algorithm using state, the value of @id from item as the sole member of a new subjects array, the first value from property in frame as frame, output as parent, and property as active property.
          3. Otherwise, append a copy of item to active property in output.
      2. For each non-keyword property and objects in frame that is not in output:
        1. Let item be the first element in objects, which MUST be a dictionary.
        2. Set property frame to the first item in objects or a newly created dictionary if value is objects. property frame MUST be a dictionary.
        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 is true.
        4. 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 frame if it exists, or the string @null otherwise.
      3. 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 dictionary 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 recursive algorithm using state, the reverse id as the sole member of a new subjects array, sub frame as frame, null as active property, and the array value of reverse property in reverse dict as parent.
      4. 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 compacted results does not have a top-level @graph keyword, or if its value is not an array, modify compacted results to place the non @context properties of compacted results into a dictionary contained within the array value of @graph.

Recursively, replace all key-value pairs in compacted results where the key is @preserve with the value from the key-pair. If the value from the key-pair is @null, replace the value with null. If, after replacement, an array contains only the value null remove the value, leaving an empty array.

Return compacted results.

Framing Extensions to the Expansion Algorithm

To support the specifics of framing, the Expansion Algorithm is extended to support free-floating nodes. A free-floating node is a node reference which is not used as an object.

When run in the json-ld-framing-1.1-expand-frame processing mode, the algorithm is modified as follows:

  • In step 7.4.3: if value is a dictionary an error has not been detected, and expanded value is set to the result of performing the Expansion Algorithm on value recursively, passing active context, active property, and value for element. dlongley: I think this is expanded, but not sure.
  • In step 7.4.4: if value is an empty dictionary an error has not been detected, and expanded value to value.
  • After step 7.4.11: If expanded property is any other framing keyword (@explicit, @default, @embed, @explicit, @omitDefault, or @requireAll), set expanded value to the result of performing the Expansion Algorithm recursively, passing active context, active property, and value for element.
  • Skip step 12: free-floating nodes are retained.

The Application Programming Interface

This API provides a clean mechanism that enables developers to convert JSON-LD data into a 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 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-API]].

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. Set expanded input to the result of using the expand method using input and options.
  3. Set expanded frame to the result of using the expand method using frame and options with expandContext set to null and processingMode set to "json-ld-framing-1.1-expand-frame".
  4. Set context to the value of @context from frame, if it exists, or to a new empty context, otherwise.
  5. Set framed to the result of using the Framing algorithm, passing expanded input, expanded frame, context, and options.
  6. Fulfill the promise passing framed.
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.
The frame to use when re-arranging the data of input; either in the form of an JSON object or as IRI.
A set of options that MAY affect the framing algorithm such as, e.g., the input document's base IRI.

Error Handling

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

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

Data Structures

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


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

See JsonLdOptions definition in [[!JSON-LD-API]].


The JsonLdOptions type is used to convert a set of options to an interface method.

See JsonLdOptions definition in [[!JSON-LD-API]].

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.


Type name:
Subtype name:
Required parameters:
Optional parameters:
Encoding considerations:
The same as the application/json MIME media type.
Security considerations:
Since a JSON-LD frame 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 frame and instead purely parse the input into a language-native data structure.
Interoperability considerations:
Not Applicable
Published specification:
The JSON-LD specification.
Applications that use this media type:
Any programming environment that requires the exchange of directed graphs. Implementations of JSON-LD have been created for JavaScript, Python, Ruby, PHP and C++.
Additional information:
Magic number(s):
Not Applicable
File extension(s):
Macintosh file type code(s):
Person & email address to contact for further information:
Manu Sporny <msporny@digitalbazaar.com>
Intended usage:
Restrictions on usage:
Manu Sporny, Gregg Kellogg, Markus Lanthaler, Dave Longley
Change controller:

Fragment identifiers have no meaning with application/frame-ld+json resources.

Open Issues

The following is a list of open issues being worked on for the next release.


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 - of special mention are Niklas Lindström, François Daoust, and Zdenko 'Denny' Vrandečić. The editors would like to thank Mark Birbeck, who provided a great deal of the initial push behind the JSON-LD work via his work on RDFj. The work of Dave Lehn and Mike Johnson are appreciated for reviewing, and performing several implementations of the specification. Ian Davis is thanked for this work on RDF/JSON. Thanks also to Nathan Rixham, Bradley P. Allen, Kingsley Idehen, Glenn McDonald, Alexandre Passant, Danny Ayers, Ted Thibodeau Jr., Olivier Grisel, Josh Mandel, Eric Prud'hommeaux, David Wood, Guus Schreiber, Pat Hayes, Sandro Hawke, and Richard Cyganiak for their input on the specification.