# 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**<br>*(Read, List, Create, Update)* | *None* | **Full Instance Representation**. The complete topological structure of the requested instance(s). |
| **Search / Query**<br>*(Execute JSON Query, Query Templates)* | `_emit` clause *(in JSON body)* | **Projected Record**. Flat dictionary matching the `_emit` aliases. Structural nesting is destroyed. |
| **Avalanche Operations**<br>*(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**<br>*(Add/Remove Context, Admin overrides)* | `Prefer: return=representation`<br>*(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 → 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).*
