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 with one element for every affected instance, containing strictly type and id (plus source/target reduced to type and id for relations).
Avalanche Operations (Add/Remove Context, Admin overrides)	Prefer: return=representation (or Header Missing)	Full Operation Envelope. The same flat array, with every element (Resource, Facet, IsRelatedTo, ConsistsOf) in its own complete representation and nothing nested. Relations include propagationConstraint and source/target as endpoint references (type, supertypes, id; metadata only with metadataPolicy=all, contexts only with contextsPolicy=all).

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 metadataPolicy=all, contextsPolicy=root, and membershipScope=global).

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.
contextsPolicy=root	None	Adds the contexts map (UUID \(\rightarrow\) Path) to each top-level response element only.
contextsPolicy=all	None	Adds the contexts map to top-level response elements AND all nested elements.
membershipScope=subtree	Default membership boundary	Each emitted contexts map contains memberships in the token Context subtree. It does not cause the map to appear when contextsPolicy=none.
membershipScope=global	IS-M, Infra-M, or IS-Admin	Each emitted contexts map contains every membership independently of the token Context. It does not alter instance selection or cause the map to appear when contextsPolicy=none.

⚠️ Extreme Overrides & Precedence Rules:

1. Projection Precedence: If _emit is used during a query, the representation-enrichment parameters (metadataPolicy, contextsPolicy) are strictly ignored. The response is exclusively bounded by the requested projection aliases. contexts cannot be projected by _emit (400 Bad Request).
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, and the system emits an X-Warning header to notify the client. A privilege-expanding value the caller is not entitled to (e.g., membershipScope=global) still returns 403 Forbidden.

(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. In an Operation Envelope every element of the array is top-level; all also enriches the source/target endpoint references of the relations).