JSON-LD 1.1 Framing

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:

• Framing adds framing keywords which may be used as entries of a node object, which MUST be preserved when expanding.
• Values of entries in a frame 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 entry keys expanding to IRIs. Processors MUST preserve this value when expanding. All other entries of a default object MUST be ignored.
• The values of @id and @type may also be an empty map, an IRI reference, array containing only an empty map, or an array of IRI references. Values of @type MAY also be a map with a @default entry, whose values are restricted by be IRIs. Processors MUST preserve this value when expanding.
• Framing either operates on the merged node definitions contained in the input document, or on the default graph depending on if the input frame contains the @graph entry at the top level. Nodes with a subject that is also a named graph, where the frame object contains @graph, extend framing to node objects from the associated named graph.

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.