JSON-LD Framing

A frame document acts as a template that precisely defines the desired shape of the output JSON. Unlike simple compaction or expansion, framing guarantees a specific tree layout, making it essential for applications that require a predictable, hard-coded data structure for rendering or processing.

• Predictable Parsing: Developers can write code against a known, fixed structure.
• Template Matching: The frame uses matching on @type and properties to select which nodes to include.
• Eliminates Ambiguity: Resolves the inherent flexibility of graph-based JSON-LD into a strict document tree.

The frame is itself a JSON-LD document that defines the desired output skeleton. It specifies which types and properties to include, and crucially, how to nest related entities. The @embed flag controls whether referenced nodes are embedded directly or kept as node references.

• @type Filtering: Include only nodes of a specific type, e.g., "@type": "schema:Product".
• @embed Directive: Use @always to force full embedding of related entities, or @never to keep them as URI references.
• @explicit Flag: When true, only properties explicitly listed in the frame are included in the output, providing strict control.

A core function of framing is controlling how related entities are represented. The @embed keyword dictates whether a referenced entity is embedded as a nested object or kept as a simple node reference (an IRI). This is critical for managing payload size and data duplication.

• @always: Embeds the full object, creating a nested tree. Ideal for single-page application data.
• @once: Embeds the object only the first time it's encountered; subsequent references become links.
• @never: Always uses a node reference, keeping the output flat and avoiding circular dependencies.

JSON-LD data is fundamentally a directed graph, but most application code expects a hierarchical tree. Framing is the primary algorithm for performing this lossy but necessary conversion, selecting a root node and projecting the graph outward from that perspective.

• Root Selection: The frame defines the entry point for the tree projection.
• Cycle Handling: Framing algorithms gracefully handle cyclic graph structures by falling back to node references.
• Context Preservation: The output retains the @context to ensure semantic meaning is not lost during reshaping.

Framing is widely used in headless CMS and e-commerce platforms to shape complex product catalogs into the exact format required by front-end frameworks like React or Vue. It decouples the backend's rich semantic graph from the front-end's specific data consumption needs.

• API Response Shaping: A single API endpoint can serve differently framed views of the same data for web, mobile, and IoT clients.
• Reduced Client Logic: Shifts complex data transformation from the client to the server or build step.
• Compatibility: Supported by all major JSON-LD processors, including the official jsonld.js library.

While compaction shortens IRIs using a context, it does not guarantee a specific tree structure. Framing is the only JSON-LD API operation that provides full control over the output document's shape, making it the tool of choice when a strict schema-like output is required.

• Compaction: Optimizes for size and readability, but structure is non-deterministic.
• Flattening: Produces a flat, predictable array of node objects, losing the original hierarchy.
• Framing: The only operation that combines a deterministic hierarchy with semantic context.