Response Shape Matrix

The following matrices provide a unified reference for how query parameters, HTTP headers, and JSON clauses alter the structural density and schema of the JSON response payload strictly for Graph Element Instances (Resource, Facet, IsRelatedTo, and ConsistsOf).

To maximize clarity, the behavior is divided into two orthogonal dimensions: the Base Response Shape (the structural skeleton) and the Payload Enrichment (the dynamic injection of system fields).

Base Response Shape

This table defines the fundamental architectural structure of the returned JSON payload.

| Operation Category | Shaping Directive | Output JSON Base Shape | |——————–|——————-|————————| | Standard Operations
(Read, List, Create, Update) | None | Full Instance Representation. The complete topological structure of the requested instance(s). | | Search / Query
(Execute JSON Query, Query Templates) | _emit clause (in JSON body) | Projected Record. Flat dictionary matching the _emit aliases. Structural nesting is destroyed. | | Avalanche Operations
(Add/Remove Context, Admin overrides) | Prefer: return=minimal | Minimal Operation Envelope. Flat array of affected elements containing strictly type and id (plus source/target for relations). | | Avalanche Operations
(Add/Remove Context, Admin overrides) | Prefer: return=representation
(or Header Missing) | Full Operation Envelope. Top-level array of Resource and IsRelatedTo instances. Resource instances nest their full Facet representations. propagationConstraint is strictly included for relations. |

Payload Enrichment Modifiers

This table defines how specific query parameters dynamically inject system-managed fields into the Base Response Shape. These modifiers can be combined freely (e.g., passing both metadataPolicy=all and includeContexts=true).

| Parameter | Combinatorial Constraint | Enrichment Effect on Base Shape | |———–|————————–|———————————| | metadataPolicy=none | None | No metadata object is injected. | | metadataPolicy=root | None | Adds the metadata object (tracking timestamps and authors) to the top-level instance(s) only. | | metadataPolicy=all | None | Adds the metadata object to the top-level instance(s) AND all nested elements. | | includeContexts=true | None | Adds the contexts map (UUID → Path) to the top-level instance(s) AND all nested elements. |

⚠️ Extreme Overrides & Precedence Rules:

  1. Projection Precedence: If _emit is used during a query, all enrichment parameters (metadataPolicy, includeContexts) are strictly ignored. The response is exclusively bounded by the requested projection aliases.

  2. Minimal Envelope Precedence: If an avalanche operation is executed with Prefer: return=minimal, all enrichment parameters are strictly ignored to honor the maximum bandwidth-optimization contract. The system emits an X-Warning header to notify the client.

(Note: In the context of metadataPolicy=root, “top-level” refers to the outermost objects in the response array/payload. For Read/List, this is the requested instance. For Operation Envelopes, these are the Resource and IsRelatedTo instances forming the backbone of the avalanche result).