# Resource Registry — API Query Parameters Reference

This section documents each query parameter in isolation: what it does, its default value, and how it behaves differently per role.

## Pagination Parameters

## `limit` and `offset`

**Purpose:** Pagination for list endpoints.

| Parameter | Type | Default |
|-----------|------|---------|
| `limit` | integer | 10 |
| `offset` | integer | 0 |

| Role | `limit` | `offset` |
|------|:-------:|:--------:|
| IS-M / Infra-M | ✅ | ✅ |
| IS-Admin / Ctx-M | ✅ | ✅ |
| IS-Editor | ✅ | ✅ |
| IS-Contrib | ✅ | ✅ |
| IS-Member | ✅ | ✅ |

**Applicable endpoints:**
- **List Contexts:** `GET /contexts`
- **Execute Context JSON Query:** `QUERY /contexts`
- **Execute Type JSON Query:** `QUERY /types`
- **List Instances:** `GET /instances/{type}`
- **Execute JSON Query:** `QUERY /instances`
- **List Query Templates:** `GET /query-templates`
- **Execute Query Template JSON Query:** `QUERY /query-templates`
- **Execute Query Template:** `QUERY /query-templates/{name}`
- All applicable `/access` read-only mirror endpoints of the above.

**Behavior:**
*Note on maximum limit:* To prevent out-of-memory errors and Denial-of-Service attacks (especially on the public `/access` facade), the server enforces a hard maximum bound for the `limit` parameter of `50`. Passing `-1` explicitly requests "give me the maximum allowed by the server". This is a deliberate architectural affordance: it decouples client applications from the server's hardcoded threshold. If the server administrator later reduces the limit to `20` to mitigate load, clients passing `-1` will seamlessly continue to operate (receiving chunks of 20) without needing code updates. Passing `-1` or any integer exceeding the threshold will automatically be clamped to the system maximum, and the server will emit an `X-Warning` header to inform the client of the clamping (e.g., `199 resource-registry "modified-query-parameters=limit; requested-value=-1; applied-value=50; reason=Clamped to system maximum"`). Clients performing massive data exports must paginate.

**Normative pagination behavior (ordering, stability, and concurrent writes):**
- **Default order:** unless explicitly documented by a specific endpoint, result ordering is backend-defined.
- **No cross-request stability guarantee:** with `limit`/`offset`, when concurrent create/update/delete operations occur, page boundaries may shift between requests.
- **Duplicates and skips are possible:** clients may observe repeated or missing elements across subsequent pages under concurrent writes.
- **Operational recommendation:** for deterministic batch processing, clients should use a bounded/snapshot-like strategy (for example, constrain the dataset by stable filters and process in short windows) instead of assuming globally stable offset pagination over mutable collections.

## Behavioral Parameters

## `lifecycle`

**Purpose:** Select which Context lifecycle slice is visible when reading the Context collection.

| Parameter | Type | Default | Accepted Values |
|-----------|------|---------|-----------------|
| `lifecycle` | string | `live` | `live`, `deleted`, `all` |

| Role | Available | Effective values |
|------|:---------:|------------------|
| IS-M / Infra-M | ✅ | `live`, `deleted`, `all` |
| IS-Admin / Ctx-M | ✅ | `live` *(requests for `deleted`/`all` are rejected)* |
| IS-Editor | ✅ | `live` *(requests for `deleted`/`all` are rejected)* |
| IS-Contrib | ✅ | `live` *(requests for `deleted`/`all` are rejected)* |
| IS-Member | ✅ | `live` *(requests for `deleted`/`all` are rejected)* |

**Applicable endpoints:**
- **List Contexts:** `GET /contexts`
- **Execute Context JSON Query:** `QUERY /contexts`
- All applicable `/access` read-only mirror endpoints of the above.

**Behavior:**
- `live` (default): returns only non-cemetery contexts.
- `deleted`: returns only cemetery contexts (`state=DELETED`).
- `all`: returns the union of live + cemetery contexts.
- The parameter affects only collection reads. Single-context reads by UUID (`GET /contexts/{context-uuid}`) and token-bound reads (`GET /contexts/@current`) keep their dedicated authorization and lookup semantics.

> ⚠️ **Authorization Gate:** Values `deleted` and `all` are restricted to `IS-M / Infra-M`. For all other roles, the server rejects the request with `403 Forbidden`.

## `polymorphic`

**Purpose:** Control whether subtypes are included alongside the explicitly requested type.

| Parameter | Type | Default |
|-----------|------|---------|
| `polymorphic` | boolean | `true` |

| Role | Available |
|------|:---------:|
| IS-M / Infra-M | ✅ |
| IS-Admin / Ctx-M | ✅ |
| IS-Editor | ✅ |
| IS-Contrib | ✅ |
| IS-Member | ✅ |

**Applicable endpoints:**
- **List Instances:** `GET /instances/{type}`
- **Execute JSON Query:** `QUERY /instances` *(Note: When `_emit` is used, apply the canonical rules in [JSON Query Syntax Reference](appendix/07-json-query-syntax-reference.html#canonical-emit-precedence-rules))*
- **Execute Query Template:** `QUERY /query-templates/{name}` *(Note: When `_emit` is used, apply the canonical rules in [JSON Query Syntax Reference](appendix/07-json-query-syntax-reference.html#canonical-emit-precedence-rules))*
- All applicable `/access` read-only mirror endpoints of the above.

**Behavior:**
No role-based behavioral differences. Available uniformly to all callers.

> ⚠️ **Strict Type Filtering Warning:** Because the default value is `true`, queries will inherently return instances of the requested type *and all its subtypes*. Clients (especially strongly-typed parsers) that expect a rigid return structure and cannot handle unknown derived types **must explicitly pass `polymorphic=false`** to enforce strict type filtering and prevent deserialization errors.

## `depth`

**Purpose:** Control how much of the Type/Context hierarchy is considered by the operation — the depth of the retrieved tree when reading a single element (Context or Type), or the breadth of Type-name matching when querying the Types collection.

| Parameter | Type | Default |
|-----------|------|---------|
| `depth` | integer | `0` on Read endpoints; `-1` on `QUERY /types` (see note below) |

| Role | Available |
|------|:---------:|
| IS-M / Infra-M | ✅ |
| IS-Admin / Ctx-M | ✅ |
| IS-Editor | ✅ |
| IS-Contrib | ✅ |
| IS-Member | ✅ |

**Applicable endpoints:**
- **Read Context:** `GET /contexts/{context-uuid}`
- **Read Current Context:** `GET /contexts/@current`
- **Read Type:** `GET /types/{type-name}`
- **Execute Type JSON Query:** `QUERY /types` *(different consumption than the Read endpoints above — see the Type-Definition Query note below; different default — see Contrasting Defaults note below)*
- All applicable `/access` read-only mirror endpoints of the above.

**Behavior:**
No role-based behavioral differences. Available uniformly to all callers.

*Depth values (Read endpoints — `GET /contexts/{uuid}`, `GET /contexts/@current`, `GET /types/{type-name}`):*
- `0` (default): only the requested element. *(Note: The baseline JSON representation of a Context inherently includes depth-limited summaries of its `parent` and `children` to allow graph navigation. `depth=0` ensures these remain as strictly minimal summaries without triggering recursive expansion).*
- positive integer `N`: the element and N levels of its descendants (if `N` exceeds the available descendant depth, the response is naturally bounded by existing data and no warning is emitted).
- `-1`: the element and all descendants recursively.
- Any other negative value is invalid: the system falls back to `0` and emits `X-Warning`.

*Depth values (`QUERY /types`):*
- `-1` (default): descendant closure is unbounded — a name match (the query's own `name`, or a Relation Type's `source`/`target` name) also matches any registered descendant of that name.
- positive integer `N`: the match expands to descendants up to N levels down.
- `0`: restricts the match to the exact literal name only (no polymorphic expansion).
- Any other negative value is invalid: the system falls back to `-1` and emits `X-Warning`.

> **Contrasting defaults between Read and Query, by design:** `GET /types/{type-name}` defaults to `depth=0` because it is an identity fetch — asking for `Service` must return exactly `Service`, not a surprise blend of its subtypes. `QUERY /types` defaults to `depth=-1` because it is a search/filter operation, and every other `QUERY` endpoint in this API defaults to inclusive, polymorphic-equivalent matching (`polymorphic=true` on Instances and Query Templates). The behavioral analogy that matters is Query-to-Query across collections (Types Query should feel like Instances Query), not Read-to-Query within the Types collection — reusing the same parameter *name* for both roles does not obligate reusing the same default *value*. Clients that need strict, non-polymorphic name matching on `QUERY /types` must explicitly pass `depth=0`.

> **Type-Definition Query Semantics (`QUERY /types`):** Type-definition records (`ResourceSchema`, `FacetSchema`, `IsRelatedToSchema`, `ConsistsOfSchema`, `PropertySchema`) carry no OrientDB subclass relationship to each other — every registered schema in a category is a flat row in one shared class, distinguished only by its own `name` and `extendedTypes`. For this endpoint, `depth` does not shape a returned tree (there is no tree to return — the response is a flat filtered array); instead, it bounds the *Type-hierarchy walk* used to resolve an equality match against a Type **name** — the query's own `name` field, or the `source`/`target` name inside a Relation Type definition — into a match against that name *and its descendants up to `depth` levels* (same walk that powers `GET /types/{type-name}?depth=N`, just consumed differently: to build a name-membership match instead of to serialize a tree). The same `depth` value applies uniformly to every name-position match within the query (the root match and any nested `source`/`target` match alike) — there is no per-field override. See [JSON Query Syntax Reference](appendix/07-json-query-syntax-reference.html#depth-based-type-name-matching-type-definition-queries-only) for worked examples, including how this composes with other constraints in the same query (e.g. filtering by a declared property name).

## `hierarchical`

**Purpose:** Extend the scope of an operation to include child (and descendant) Contexts of the current Context, in addition to the current Context itself. The current Context is determined by the authorization token.

| Parameter | Type | Default |
|-----------|------|---------|
| `hierarchical` | boolean | `false` |

| Role | Available | Scope |
|------|:---------:|-------|
| IS-M / Infra-M | ✅ | Token Context + all descendants |
| IS-Admin / Ctx-M | ✅ | Token Context + all descendants |
| IS-Editor | ✅ | Token Context + all descendants. Note: hierarchical writes skip **non-`ACTIVE`** descendant Contexts. |
| IS-Contrib | ✅ (Reads only) | Token Context + all descendants. Ignored for writes. |
| IS-Member | ✅ (Reads only) | Token Context + all descendants. Write operations forbidden. |

**Applicable endpoints:**
- **List Instances:** `GET /instances/{type}`
- **Execute JSON Query:** `QUERY /instances`
- **Exists Instance:** `HEAD /instances/{type}/{instance-uuid}`
- **Read Instance:** `GET /instances/{type}/{instance-uuid}`
- **Create Instance:** `POST /instances/{type}`
- **Create/Update Instance:** `PUT /instances/{type}/{instance-uuid}`
- **Execute Query Template:** `QUERY /query-templates/{name}`
- **Admin Add to Context:** `PUT /admin/instances/{type}/{instance-uuid}/contexts/{new-context-uuid}`
- **Admin Remove from Context:** `DELETE /admin/instances/{type}/{instance-uuid}`
- **Execute Raw Query:** `QUERY /admin/raw-query`
- All applicable `/access` read-only mirror endpoints of the above.

**Behavior:**

**Hierarchical Support Matrix by Operation Type:**

| Operation Category | Endpoints | Supported | Operational Effect |
|--------------------|-----------|:---------:|--------------------|
| **Read / Lookup** | `GET /instances/{type}`<br>`HEAD /instances/{type}/{instance-uuid}`<br>`GET /instances/{type}/{instance-uuid}`<br>`GET /access/...` | ✅ | Expands visibility subtree. Retrieves instances that exist *anywhere* within the authorized descendant Contexts. |
| **Search / Query** | `QUERY /instances`<br>`QUERY /query-templates/{name}`<br>`QUERY /access/query-templates/{name}` | ✅ | Expands search boundary to include all descendant Contexts. |
| **Write (Hierarchical Distribution)** | `PUT /instances/{type}/{instance-uuid}` (Create/Update)<br>`POST /instances/{type}` (Create) | ✅ | With `hierarchical=true`, applies the creation/update of a Resource to the current Context AND all descendant Contexts within the authorized subtree. Ignored with `X-Warning` for non-Resource instances. |
| **Membership Add** | `PUT /instances/{type}/{instance-uuid}/contexts/{new-context}` | ❌ | Ignored (`X-Warning`). Membership sharing is explicit to a single target Context. To share hierarchically, use Admin API. Unlike a creation, whose effect is bounded by its payload, the avalanche of a membership change depends on relations that may have been created after the caller read the graph (see [Hierarchical Creation, but No Hierarchical Membership Changes on Standard Endpoints](12-is-architectural-decisions.html#hierarchical-creation-but-no-hierarchical-membership-changes-on-standard-endpoints)). |
| **Membership Remove** | `DELETE /instances/{type}/{instance-uuid}` | ❌ | Ignored (`X-Warning`). Removal acts strictly on the current token Context, for the same reason as Membership Add. |
| **Raw Query** | `QUERY /admin/raw-query` | ✅ | Only for global admins (`IS-M / Infra-M`). Extends the underlying database session's visibility to the token Context's descendants. |
| **Admin Membership** | `PUT /admin/instances/{type}/{instance-uuid}/contexts/{new-context}`<br>`DELETE /admin/instances/{type}/{instance-uuid}` | ✅ | True hierarchical overrides. Can bypass Context boundaries to merge **Relation** instances or surgically wipe subtrees. |

**Global Atomicity Guarantee for Mutations:** For all supported write operations (Create/Update, Admin Add, Admin Remove) where `hierarchical=true` modifies state across multiple Contexts, the entire distribution is executed as a single, atomic database transaction. If the payload violates a schema constraint or encounters a conflict in even one descendant Context, the entire global transaction fails and is rolled back entirely (no partial commits).

**Note for `HEAD` requests (`HEAD /instances/{type}/{instance-uuid}`):** Using `hierarchical=true` on a `HEAD` request will return `200 OK` if the instance exists *anywhere* in the requested subtree. Because `HEAD` requests do not return a body, this will not tell you *which* specific Context the instance is in; it only serves as a fast binary check ("does it exist in my tree?"). If you need to know exactly which Contexts the instance belongs to, you must use a `GET` read request with the `includeContexts=true` parameter.

To disambiguate existence and visibility without violating HTTP status code semantics, clients should rely on the following deterministic behavior matrix for instance lookups (evaluating the composite key `(type, instance-uuid)` on both `HEAD` and `GET`):

| Instance Location | Call *without* `hierarchical` | Call *with* `hierarchical=true` |
|-------------------|-------------------------------|---------------------------------|
| Does not exist anywhere | `404 Not Found` | `404 Not Found` |
| Exists, but entirely outside the authorized subtree (e.g., parallel branch) | `403 Forbidden` | `403 Forbidden` |
| Exists in a child/descendant Context, but **not** directly in the current Context | `403 Forbidden` | `200 OK` |
| Exists directly in the current Context | `200 OK` | `200 OK` |

*Architectural Note:* Consistency between `HEAD` and `GET` requests is guaranteed only when using identical URLs. Because query parameters are an integral part of the HTTP URI identifier, a client must apply the exact same parameters to both calls. If you use `hierarchical=true` on a `HEAD` request to verify existence within the subtree, you must include `hierarchical=true` on the subsequent `GET` request to retrieve it. Failing to do so changes the scope of the request and will predictably result in a `404 Not Found` or `403 Forbidden` if the instance does not exist in the narrower root Context.

*Point-read symmetry note:* Support for `hierarchical` on point lookups (`HEAD` / `GET /instances/{type}/{instance-uuid}`) is intentional. It keeps discovery and fetch operations scope-coherent: if an instance is discovered through a hierarchical list/query call, the subsequent point read must preserve `hierarchical=true` to evaluate the same visibility domain.

> ⚠️ **Parameter Conflict:** The flags `hierarchical=true` and `syncExistingHierarchy=true` describe mutually exclusive topological propagation strategies. Passing both flags simultaneously in a `PUT` operation is strictly forbidden and will result in a `400 Bad Request`.

#### Hierarchical Operations over Mixed-State Subtrees

When a client executes a hierarchical operation (`hierarchical=true`) starting from a valid `ACTIVE` Context, the target subtree might contain descendant Contexts with a mix of non-`ACTIVE` operational states (e.g., `SUSPENDED`, `CREATED`). To guarantee robust execution and avoid breaking entire subtree operations due to a single locked child Context, the system adopts a **strict fail-safe filtering contract**.

**Hierarchical Operation × `effectiveState` Matrix:**

| Operation Type | Subtree descendants behavior | Emits `X-Result-Scope` |
|----------------|------------------------------|------------------------|
| **Reads & Queries** (e.g., `GET`, `HEAD`) | **Filtered.** Instances physically located within non-`ACTIVE` descendant Contexts are silently filtered out of the result set as if they do not exist. Furthermore, if an instance exists in multiple Contexts, any non-`ACTIVE` descendant Contexts are explicitly omitted from the instance's `contexts` map. | Yes (`state-filtered`) |
| **Hierarchical Writes** (`hierarchical=true` on `POST`/`PUT`, `syncExistingHierarchy=true` on `PUT`, `IS-Editor`) | **Skipped.** Non-`ACTIVE` descendant Contexts are left untouched, and the payload is synchronized over every `ACTIVE` one, exactly as hierarchical reads omit them. | Yes (`state-filtered`) |
| **Admin Overrides** (`IS-Admin / Ctx-M` or higher) | **Applied.** Global administrators inherently bypass operational locks. When executing hierarchical writes, their mutations are actively applied to *all* descendants, including `SUSPENDED` and `CREATED` Contexts, allowing them to prepare/sync environments before they are brought online. | No |

*Note on Client Observability:* When the system filters out instances or Context mappings during a hierarchical read/query for a standard user, it explicitly returns the `X-Result-Scope: state-filtered` HTTP header. This provides essential observability, signaling to the client that the returned payload is structurally sound but operationally incomplete relative to the physical graph.

## `syncExistingHierarchy`

**Purpose:** Modifies an update operation to synchronize structural changes across the hierarchical subtree, but *only* in Contexts where the instance is already present.

| Parameter | Type | Default | Required |
|-----------|------|---------|:--------:|
| `syncExistingHierarchy` | boolean | `false` | ❌ |

| Role | Available | Scope |
|------|:---------:|-------|
| IS-M / Infra-M | ✅ | Token Context + all descendants |
| IS-Admin / Ctx-M | ✅ | Token Context + all descendants |
| IS-Editor | ✅ | Token Context + all descendants. **Non-`ACTIVE`** descendant Contexts are skipped. |
| IS-Contrib | ❌ | Hierarchical writes forbidden |
| IS-Member | ❌ | Write operations forbidden |

**Applicable endpoints:**
- **Create/Update Instance:** `PUT /instances/{type}/{instance-uuid}`

**Behavior:**
This parameter is designed explicitly to safely synchronize updates across shared instances. When passed on a `PUT /instances/{type}/{instance-uuid}` update request:
- It **does not** distribute the instance to new descendant Contexts (unlike `hierarchical=true`).
- It syncs the structural changes (like **Facet** instance addition/removal) *only in the descendant Contexts where the instance is already present*.
- On a creation request via `PUT /instances/{type}/{instance-uuid}`, this flag is intrinsically ignored. This parameter is **not applicable** to `POST /instances/{type}`; passing it will be ignored and trigger an `X-Warning` header.
- **Atomicity Guarantee:** Like `hierarchical=true`, the entire synchronization across all applicable Contexts is executed as a single, atomic database transaction. If the update fails in any single Context (e.g., due to a local schema violation or a concurrent modification conflict), the entire global transaction is rolled back, guaranteeing absolute state consistency without partial updates.

> ⚠️ **Parameter Conflict:** The flags `hierarchical=true` and `syncExistingHierarchy=true` describe mutually exclusive topological propagation strategies. Passing both flags simultaneously in a `PUT` operation is strictly forbidden and will result in a `400 Bad Request`.

## `propagationMode`

**Purpose:** Controls the depth of the avalanche graph traversal during `Add to Context` (`PUT`) and `Remove from Current Context` (`DELETE`) operations.

**Cross-Reference Mode Availability:**
| Mode | Add to Context | Remove from Context | Roles |
|------|:--------------:|:-------------------:|-------|
| `surgical` | ✅ (Admin API only) | ✅ (All write roles) | See per-operation table |
| `shallow` | ✅ (Default) | ✅ (Default) | All write roles |
| `deep` | ✅ | ❌ (falls back to `shallow`, `X-Warning`) | All write roles |

### `propagationMode` (Add to Context)

**Purpose:** Controls the depth of the avalanche graph traversal during `Add to Context` operations (`PUT`).

| Parameter | Type | Default | Accepted Values |
|-----------|------|---------|-----------------|
| `propagationMode` | string | `shallow` | `shallow`, `deep`, `surgical` (Admin API only) |

| Role | Available | Scope |
|------|:---------:|-------|
| IS-M / Infra-M | ✅ | Yes |
| IS-Admin / Ctx-M | ✅ | `shallow`, `deep` only |
| IS-Editor | ✅ | `shallow`, `deep` only |
| IS-Contrib | ❌ | N/A (Cannot perform Add to Context) |
| IS-Member | ❌ | N/A (Write operations forbidden) |

**Applicable endpoints:**
- **Add to Context:** `PUT /instances/{type}/{instance-uuid}/contexts/{new-context-uuid}` - *`propagationMode=surgical` is NOT permitted (`400 Bad Request`)*
- **Admin Add to Context:** `PUT /admin/instances/{type}/{instance-uuid}/contexts/{new-context-uuid}`

**Behavior:**
- **`surgical` (Precise Injection - Admins Only):** Restricted to global administrators via `/admin/` endpoints. It adds the explicitly targeted instance; what else it adds depends on the type of the targeted instance:
  - **Resource instance:** The system adds the targeted **Resource** instance and its **ConsistsOf**/**Facet** instances according to the `add` constraint of each **ConsistsOf** instance; a mandatory **Facet** instance left behind makes the operation fail schema validation. It explicitly ignores all outgoing **IsRelatedTo** instances, and consequently the downstream linked **Resource** instances.
  - **Facet instance:** Behaves identically to `shallow` and `deep`: a **Facet** instance has no outgoing relations to propagate, and in every mode it is added together with the **ConsistsOf** instance pointing to it, whose source **Resource** instance must already be in the target Context. The parameter is safely ignored and the system emits an `X-Warning` header.
  - **IsRelatedTo instance:** Adds the targeted **IsRelatedTo** instance. This requires the source **Resource** instance to already exist in the target Context. The target **Resource** instance is always pulled into the Context, because an **IsRelatedTo** instance cannot exist without its target, whatever the `add` constraint of the **IsRelatedTo** instance. The pulled **Resource** instance brings its **ConsistsOf**/**Facet** instances according to the `add` constraint of each **ConsistsOf** instance, and none of its own **IsRelatedTo** instances.
  - **ConsistsOf instance:** Behaves identically to `shallow` and `deep` because adding a **ConsistsOf** instance inherently requires adding its target **Facet** instance.
- **`shallow` (Standard Default):** The traversal halts the avalanche path if it encounters a target **Entity** instance that is already present in the destination Context, assuming its downstream dependencies are satisfied.
- **`deep` (Full Transitive Closure):** The system ignores whether an intermediate **Entity** instance is already present in the target Context and continues evaluating its outgoing **Relation** instances to ensure the entire dependency chain is fully propagated. To prevent infinite loops in cyclic topologies, the system relies on a Modified Depth-First Search algorithm with a Visited Set, halting recursion if an instance has already been evaluated during the current transaction (see [Complex Topology Scenarios](appendix/03-complex-topology-scenarios.md)).

**Propagation Scenarios: Surgical vs Shallow vs Deep**

> **Visual Disclaimer (Infrastructure Topology Focus):** To avoid unreadable diagrams, the following simplified scenarios focus exclusively on the Infrastructure Topology (the graph of **Resource** instances and **IsRelatedTo** instances). While omitted from these didactic diagrams to reduce noise, it is strictly understood that every valid **Resource** instance must encapsulate its own Descriptive Topology (its attached **Facet** instances).

To understand the difference, consider a topology involving four **Resource** instances (`R1`, `R2`, `R3`, `R4`):

**Initial State:**

The scenario contains the following **Resource** instances:
- **Resource** instance `R1` exists in Context `C1`.
- **Resource** instance `R2` exists in Context `C1`.
- **Resource** instance `R3` exists in Contexts `C1` and `C2`.
- **Resource** instance `R4` exists in Context `C1`.

The scenario contains the following **IsRelatedTo** instances:
- `R1` is linked to `R2` via **IsRelatedTo** instance `IRT12`, which exists in Context `C1` and is configured with `add: propagate`.
- `R2` is linked to `R3` via **IsRelatedTo** instance `IRT23`, which exists in Context `C1` and is configured with `add: propagate`.
- `R3` is linked to `R4` via **IsRelatedTo** instance `IRT34`, which exists in Context `C1` and is configured with `add: propagate`.

```mermaid
---
config:
  theme: neutral
  flowchart:
    edgeLabelBackground: "#ffffff"
---
graph LR
    R1("<b>R1</b> <br/> <sub>[<i>C1</i>]</sub>"):::resource
    R2("<b>R2</b> <br/> <sub>[<i>C1</i>]</sub>"):::resource
    R3("<b>R3</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R4("<b>R4</b> <br/> <sub>[<i>C1</i>]</sub>"):::resource

    R1 -->|"<b>IRT12</b> <br/> add: propagate <br/> <sub>[<i>C1</i>]</sub>"| R2
    R2 -->|"<b>IRT23</b> <br/> add: propagate <br/> <sub>[<i>C1</i>]</sub>"| R3
    R3 -->|"<b>IRT34</b> <br/> add: propagate <br/> <sub>[<i>C1</i>]</sub>"| R4

    classDef resource fill:#4f81bd,stroke:#385d8a,stroke-width:3px,color:#fff;
    linkStyle default stroke:#385d8a,stroke-width:3px;
```

When an admin executes an `Add to Context` operation to add `R1` to Context `C2`:

- **Scenario A: Surgical (Precise Injection)**
  The algorithm adds `R1` to `C2` but explicitly ignores the `add: propagate` constraints on outgoing **IsRelatedTo** instances. `R2`, `R3`, and `R4` are not evaluated.
  *(Note: While `R1` is injected alone regarding `IsRelatedTo` links, any mandatory **ConsistsOf** instances and their target **Facet** instances possessing an `add: propagate` constraint are strictly pulled into `C2` to satisfy structural integrity.)*

```mermaid
---
config:
  theme: neutral
  flowchart:
    edgeLabelBackground: "#ffffff"
---
graph LR
    R1("<b>R1</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R2("<b>R2</b> <br/> <sub>[<i>C1</i>]</sub>"):::resource
    R3("<b>R3</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R4("<b>R4</b> <br/> <sub>[<i>C1</i>]</sub>"):::resource

    R1 -->|"<b>IRT12</b> <br/> add: propagate <br/> <sub>[<i>C1</i>]</sub>"| R2
    R2 -->|"<b>IRT23</b> <br/> add: propagate <br/> <sub>[<i>C1</i>]</sub>"| R3
    R3 -->|"<b>IRT34</b> <br/> add: propagate <br/> <sub>[<i>C1</i>]</sub>"| R4

    classDef resource fill:#4f81bd,stroke:#385d8a,stroke-width:3px,color:#fff;
    linkStyle default stroke:#385d8a,stroke-width:3px;
```
```eval_rst
- **Scenario B: Shallow (Stop on Existing)**
  The algorithm stops as soon as it encounters an instance that is **already present** in the target Context.
  ``R1`` enters ``C2`` :math:`\rightarrow` ``R2`` enters ``C2`` :math:`\rightarrow` ``R3`` **is already in ``C2`` (STOP)**.
  ``R4`` is never evaluated and remains exclusively in Context ``C1``.
```
```mermaid
---
config:
  theme: neutral
  flowchart:
    edgeLabelBackground: "#ffffff"
---
graph LR
    R1("<b>R1</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R2("<b>R2</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R3("<b>R3</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R4("<b>R4</b> <br/> <sub>[<i>C1</i>]</sub>"):::resource

    R1 -->|"<b>IRT12</b> <br/> add: propagate <br/> <sub>[<i>C1, C2</i>]</sub>"| R2
    R2 -->|"<b>IRT23</b> <br/> add: propagate <br/> <sub>[<i>C1, C2</i>]</sub>"| R3
    R3 -->|"<b>IRT34</b> <br/> add: propagate <br/> <sub>[<i>C1</i>]</sub>"| R4

    classDef resource fill:#4f81bd,stroke:#385d8a,stroke-width:3px,color:#fff;
    linkStyle default stroke:#385d8a,stroke-width:3px;
```
```eval_rst
- **Scenario C: Deep (Full Traversal)**
  The algorithm calculates the **complete transitive closure**, continuing to traverse outgoing **Relation** instances even if an intermediate instance is already in the target Context.
  ``R1`` enters ``C2`` :math:`\rightarrow` ``R2`` enters ``C2`` :math:`\rightarrow` ``R3`` is already in ``C2``, but the algorithm *continues* evaluating its outgoing **Relation** instances :math:`\rightarrow` the ``IRT34`` **Relation** instance pushes ``R4`` into ``C2``.
```
```mermaid
---
config:
  theme: neutral
  flowchart:
    edgeLabelBackground: "#ffffff"
---
graph LR
    R1("<b>R1</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R2("<b>R2</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R3("<b>R3</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R4("<b>R4</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource

    R1 -->|"<b>IRT12</b> <br/> add: propagate <br/> <sub>[<i>C1, C2</i>]</sub>"| R2
    R2 -->|"<b>IRT23</b> <br/> add: propagate <br/> <sub>[<i>C1, C2</i>]</sub>"| R3
    R3 -->|"<b>IRT34</b> <br/> add: propagate <br/> <sub>[<i>C1, C2</i>]</sub>"| R4

    classDef resource fill:#4f81bd,stroke:#385d8a,stroke-width:3px,color:#fff;
    linkStyle default stroke:#385d8a,stroke-width:3px;
```

### `propagationMode` (Remove from Context)

**Purpose:** Controls whether the deletion of an instance triggers propagation constraints on its connected **Relation** instances during `Remove from Current Context` operations (`DELETE`).

| Parameter | Type | Default | Accepted Values |
|-----------|------|---------|-----------------|
| `propagationMode` | string | `shallow` | `surgical`, `shallow` |

| Role | Available | Scope |
|------|:---------:|-------|
| IS-M / Infra-M | ✅ | Yes |
| IS-Admin / Ctx-M | ✅ | Yes |
| IS-Editor | ✅ | Yes |
| IS-Contrib | ✅ | Yes |
| IS-Member | ❌ | N/A (Write operations forbidden) |

**Applicable endpoints:**
- **Remove from Current Context:** `DELETE /instances/{type}/{instance-uuid}`
- **Admin Remove from Context:** `DELETE /admin/instances/{type}/{instance-uuid}`

*(Note: `dryRun` is strictly reserved for orchestrating topological membership operations and avalanche previews. It is not supported for `PUT /instances/{type}/{instance-uuid}` instance replacement or `syncExistingHierarchy` operations. To preview the scope of a hierarchical synchronization before committing, consider performing a `hierarchical=true` `GET` read to enumerate the descendant Contexts where the instance is already present).*

**Behavior:**
- **`surgical` (Safe Undo):** Replaces the need for a non-standard `PURGE` verb. It restricts the operation to the explicitly targeted instance and its strictly required topological dependencies. This acts as a safe override and is available to all roles permitted to delete.
  - **Resource instance:** The system removes the targeted **Resource** instance. Because a **Facet** instance cannot exist without its parent, all its attached **Facet** instances (and the **ConsistsOf** instances attaching them) are necessarily removed as well. All outgoing **IsRelatedTo** instances are also removed, but the system explicitly ignores their `remove` constraints, preventing the avalanche from removing downstream target **Resource** instances.
  - **Facet instance:** Behaves identically to `shallow` because **Facet** instances possess no outgoing relations to propagate. The parameter is safely ignored and the system emits an `X-Warning` header.
  - **IsRelatedTo instance:** Removes only the targeted **IsRelatedTo** instance. The target **Resource** instance is completely ignored, regardless of the `remove` constraint value on that **IsRelatedTo** instance. This acts as a safe "undo" facility to remove an accidental link without collateral damage.
  - **ConsistsOf instance:** Behaves identically to `shallow` because removing a **ConsistsOf** instance inherently mandates the removal of its target **Facet** instance.
- **`shallow` (Standard Default):** The standard cascading removal. The traversal evaluates all `remove` constraints (`cascade`, `keep`, `cascadeWhenOrphan`). The avalanche stops naturally along any path where an **Entity** instance survives. *(Note: If the directly targeted instance of the `DELETE` operation is a **Relation** instance, its `remove` propagation constraint is still evaluated, and the avalanche propagates downstream to its target exactly as if the removal had originated from the source **Resource** instance).*

*(Note: The value `deep` is not semantically applicable to DELETE operations. Deletion evaluates constraints directly; ignoring a survival condition would bypass model integrity. If `deep` is passed, the system emits an `X-Warning` header and falls back to `shallow`.)*

> **Advanced Topologies:** To see exactly how propagation constraints behave in advanced graph topologies (such as cyclic dependencies and diamond patterns) during both Add and Remove operations, refer to [Complex Topology Scenarios](appendix/03-complex-topology-scenarios.md).

## `dryRun`

**Purpose:** Simulate the execution of operations that trigger complex cascading effects (avalanche effect) without persisting any changes.

| Parameter | Type | Default |
|-----------|------|---------|
| `dryRun` | boolean | `false` |

| Role | Available |
|------|:---------:|
| IS-M / Infra-M | ✅ |
| IS-Admin / Ctx-M | ✅ |
| IS-Editor | ✅ |
| IS-Contrib | ✅ |
| IS-Member | ❌ |

**Applicable endpoints:**
- **Add to Context:** `PUT /instances/{type}/{instance-uuid}/contexts/{new-context-uuid}`
- **Admin Add to Context:** `PUT /admin/instances/{type}/{instance-uuid}/contexts/{new-context-uuid}`
- **Remove from Current Context:** `DELETE /instances/{type}/{instance-uuid}`
- **Admin Remove from Context:** `DELETE /admin/instances/{type}/{instance-uuid}`

*(Note: `dryRun` is strictly reserved for orchestrating topological membership operations and avalanche previews. It is not supported for `PUT /instances/{type}/{instance-uuid}` instance replacement or `syncExistingHierarchy` operations. To preview the scope of a hierarchical synchronization before committing, consider performing a `hierarchical=true` `GET` read to enumerate the descendant Contexts where the instance is already present).*

**Behavior:**
When `dryRun=true`, the service traverses the graph, evaluates all propagation constraints (e.g., `add: propagate`, `remove: cascade`), applies validation, and returns the complete set of affected instances exactly as it would during a real execution, but performs a rollback before committing to the database. This allows clients to preview the impact of a destructive or wide-reaching operation. **Validation Parity:** If the simulated operation violates any schema constraint or topological rule (e.g., it would result in a missing mandatory **Facet** instance), the endpoint strictly rejects the request exactly as a real execution would (returning `409 Conflict` with the validation error message). It does **not** return a `200 OK` containing a simulated broken graph.

`dryRun` never expands permissions: the same authorization checks and role constraints of the corresponding real operation are applied before simulation.

> ⚠️ **Concurrency and State Mutation Risk:** `dryRun` is a non-binding simulation snapshot: it does not reserve state, does not acquire distributed locks up to a later confirm call, and does not provide cross-request serializability. Between the `check` (`dryRun=true`) and the subsequent `confirm` (real execution) of the [Try-Check-Confirm Pattern](#try-check-confirm-pattern-dryruntrue), concurrent writes by other users may fundamentally change the graph state. Therefore, a subsequent real execution can legitimately fail with a `409 Conflict` or result in a different avalanche even if the preview succeeded perfectly milliseconds before.

**Success-code matrix (normative):** For the definitive matrix combining `dryRun`, `Prefer: return`, Success HTTP Codes, and response payload shapes, see the [Operation Envelope and Parameter Matrix](09-api-instances-and-admin.html#operation-envelope-and-parameter-matrix).

## Inclusion Parameters

## `metadataPolicy`

**Purpose:** Control whether metadata is omitted, included only on the top-level response elements, or propagated to all nested elements when the endpoint returns nested graph structures.

| Parameter | Type | Default | Accepted Values |
|-----------|------|---------|-----------------|
| `metadataPolicy` | string | `none` | `none`, `root`, `all` |

| Role | Available | Metadata content |
|------|:---------:|-----------------|
| IS-M / Infra-M | ✅ | **Full:** all fields visible, no obfuscation |
| IS-Admin / Ctx-M | ✅ | **Filtered:** dates visible, `createdBy` and `lastUpdateBy` returned as `"[REDACTED]"` |
| IS-Editor | ✅ | **Filtered:** dates visible, `createdBy` and `lastUpdateBy` returned as `"[REDACTED]"` |
| IS-Contrib | ✅ | **Filtered:** dates visible, `createdBy` and `lastUpdateBy` returned as `"[REDACTED]"` |
| IS-Member | ✅ | **Filtered:** dates visible, `createdBy` and `lastUpdateBy` returned as `"[REDACTED]"` |

**Applicable endpoints:**
- **List Contexts:** `GET /contexts`
- **Execute Context JSON Query:** `QUERY /contexts`
- **Read Context:** `GET /contexts/{context-uuid}`
- **Read Current Context:** `GET /contexts/@current`
- **Create Context:** `PUT /contexts/{context-uuid}`
- **Tracked Update Context:** `PATCH /contexts/{context-uuid}`
- **Execute Type JSON Query:** `QUERY /types`
- **Read Type:** `GET /types/{type-name}`
- **List Instances:** `GET /instances/{type}`
- **Execute JSON Query:** `QUERY /instances` *(Note: When `_emit` is used, apply the canonical rules in [JSON Query Syntax Reference](appendix/07-json-query-syntax-reference.html#canonical-emit-precedence-rules))*
- **Exists Instance:** `HEAD /instances/{type}/{instance-uuid}` *(same representation selection as Read; the body is omitted)*
- **Read Instance:** `GET /instances/{type}/{instance-uuid}`
- **Create Instance:** `POST /instances/{type}`
- **Create/Update Instance:** `PUT /instances/{type}/{instance-uuid}`
- **Merge Update Instance:** `PATCH /instances/{type}/{instance-uuid}`
- **Add to Context:** `PUT /instances/{type}/{instance-uuid}/contexts/{new-context-uuid}` *(Note: Applicable only when the full response representation is returned, which is the default unless `Prefer: return=minimal` is specified).*
- **Remove from Current Context:** `DELETE /instances/{type}/{instance-uuid}` *(Note: Applicable only when the full response representation is returned).*
- **List Query Templates:** `GET /query-templates`
- **Execute Query Template JSON Query:** `QUERY /query-templates`
- **Read Query Template:** `GET /query-templates/{name}`

- **Execute Query Template:** `QUERY /query-templates/{name}` *(Note: When `_emit` is used, apply the canonical rules in [JSON Query Syntax Reference](appendix/07-json-query-syntax-reference.html#canonical-emit-precedence-rules))*
- **Admin Add to Context:** `PUT /admin/instances/{type}/{instance-uuid}/contexts/{new-context-uuid}` *(Note: Applicable only when the full response representation is returned).*
- **Admin Remove from Context:** `DELETE /admin/instances/{type}/{instance-uuid}` *(Note: Applicable only when the full response representation is returned).*
- **Execute Raw Query:** `QUERY /admin/raw-query` *(Note: Only when `rawResult=false`)*
- All applicable `/access` read-only mirror endpoints of the above.

**Behavior:**
- `none` (default): omit metadata entirely.
- `root`: include metadata only on the top-level response elements.
- `all`: include metadata on the top-level response elements and on all nested elements returned by the endpoint.
- On endpoints that do not return nested graph elements (such as Contexts, Types, and Query Template definitions), `root` and `all` are equivalent in response shape.

> **Compatibility note for this version:** `metadataPolicy` is the canonical parameter. The legacy parameters `includeMeta` and `allMeta` have been consolidated into `metadataPolicy`, are still accepted server-side in this release for backward compatibility, and will be removed in the next major version. Clients should migrate now.

**Legacy-to-canonical mapping accepted by the server in this version:**
- `includeMeta` omitted/false and `allMeta` omitted/false -> `metadataPolicy=none`
- `includeMeta=true` and `allMeta` omitted/false -> `metadataPolicy=root`
- `includeMeta=true` and `allMeta=true` -> `metadataPolicy=all`
- Legacy `allMeta=true` without `includeMeta=true` remains invalid legacy input: it is ignored by the compatibility layer and triggers an `X-Warning` header.

## `includeContexts`

**Purpose:** Include in the response the list of Contexts where each instance (and its nested elements) is present. *(Note on Asymmetry: Unlike `metadataPolicy`, which can intentionally limit metadata to only the top-level response elements via `metadataPolicy=root`, `includeContexts` automatically applies to both the top-level instance and all its nested elements. This asymmetry is intentional: understanding the specific Context boundaries of nested **Facet** and **Relation** instances is often critical for topological debugging, whereas nested metadata is usually redundant).*

| Parameter | Type | Default |
|-----------|------|---------|
| `includeContexts` | boolean | `false` |

| Role | Available | Scope of returned Contexts |
|------|:---------:|---------------------------|
| IS-M / Infra-M | ✅ | All Contexts where the instance is present |
| IS-Admin / Ctx-M | ⚠️ | Filtered to the competence subtree (i.e., the current Context and all its descendants where the instance is present) |
| IS-Editor | ⚠️ | Filtered to the competence subtree (i.e., the current Context and all its descendants where the instance is present) |
| IS-Contrib | ⚠️ | Filtered to the competence subtree (i.e., the current Context and all its descendants where the instance is present) |
| IS-Member | ⚠️ | Filtered to the competence subtree (i.e., the current Context and all its descendants where the instance is present) |

**Applicable endpoints:**
- **List Instances:** `GET /instances/{type}`
- **Execute JSON Query:** `QUERY /instances` *(Note: When `_emit` is used, apply the canonical rules in [JSON Query Syntax Reference](appendix/07-json-query-syntax-reference.html#canonical-emit-precedence-rules))*
- **Exists Instance:** `HEAD /instances/{type}/{instance-uuid}` *(same representation selection as Read; the body is omitted)*
- **Read Instance:** `GET /instances/{type}/{instance-uuid}`
- **Create Instance:** `POST /instances/{type}`
- **Create/Update Instance:** `PUT /instances/{type}/{instance-uuid}`
- **Merge Update Instance:** `PATCH /instances/{type}/{instance-uuid}`
- **Add to Context:** `PUT /instances/{type}/{instance-uuid}/contexts/{new-context-uuid}` *(Note: Applicable only when the full response representation is returned, which is the default unless `Prefer: return=minimal` is specified).*
- **Remove from Current Context:** `DELETE /instances/{type}/{instance-uuid}` *(Note: Applicable only when the full response representation is returned).*
- **Execute Query Template:** `QUERY /query-templates/{name}` *(Note: When `_emit` is used, apply the canonical rules in [JSON Query Syntax Reference](appendix/07-json-query-syntax-reference.html#canonical-emit-precedence-rules))*
- **Admin Add to Context:** `PUT /admin/instances/{type}/{instance-uuid}/contexts/{new-context-uuid}` *(Note: Applicable only when the full response representation is returned).*
- **Admin Remove from Context:** `DELETE /admin/instances/{type}/{instance-uuid}` *(Note: Applicable only when the full response representation is returned).*
- **Execute Raw Query:** `QUERY /admin/raw-query` *(Note: Only when `rawResult=false`)*
- All applicable `/access` read-only mirror endpoints of the above.

**Behavior:**
**Not available for:** Context and Type endpoints (Contexts and Types are not Context-scoped in the same way).

**Context membership rule:**
- A **Resource** instance is present in all Contexts that form the union of the Contexts of all its **Facet** instances. By design (and strictly enforced by the IS-Model), it is physically impossible for a **Facet** instance to belong to a Context where its parent **Resource** instance does not exist.
- A **ConsistsOf** instance is present in all Contexts where its target **Facet** instance is present.
- An **IsRelatedTo** instance's membership is an explicitly maintained subset of the intersection of its source and target **Resource** Contexts. *(For the strict mathematical intersection rule governing general **Relation** instances across Contexts, see [Topological and Contextual Rules](03-is-model-core-topology.html#topological-and-contextual-rules)).*

## Admin Specific Parameters

## `rawResult` — Raw Query only

**Purpose:** Returns the payload exactly as provided by the underlying database engine, bypassing the Information System model conversion.

| Parameter | Type | Default | Required |
|-----------|------|---------|:--------:|
| `rawResult` | boolean | `false` | ❌ |

| Role | Available |
|------|:---------:|
| IS-M / Infra-M | ✅ |
| IS-Admin / Ctx-M | ❌ |
| IS-Editor | ❌ |
| IS-Contrib | ❌ |
| IS-Member | ❌ |

**Applicable endpoints:**
- **Execute Raw Query:** `QUERY /admin/raw-query`

**Behavior:**
This parameter applies exclusively to `QUERY /admin/raw-query` (raw OrientDB SQL query). The query itself is expected in the request body (e.g. `{"query": "SELECT..."}`). It must be a read-only OrientDB SQL statement. As the endpoint uses a read-only database user, non-idempotent operations (`INSERT`, `UPDATE`, `DELETE`, `CREATE`, `DROP`) are automatically rejected. Any valid read-only statement is accepted (e.g. `SELECT`, `TRAVERSE`, `MATCH`).

- `false` (default): element rows are converted to the Information System model format and apply `metadataPolicy`/`includeContexts`. Scalar and projection rows have no Information System representation, so they retain their backend-native JSON shape; explicitly requested enrichment parameters are ignored for those rows and emit `X-Warning`.
- `true`: every row is returned exactly as provided by the OrientDB backend, retaining backend-native field names; only `hierarchical` affects execution scope, while `metadataPolicy` and `includeContexts` are ignored and emit `X-Warning` when requested.

> ⚠️ This endpoint is **NOT for production use**. The OrientDB SQL syntax may change or disappear without notice when the backend is replaced.
>
> **Scope guarantee (client-facing contract):** visibility and Context boundaries are enforced by the service implementation and data model, including when `hierarchical=true` is used where applicable. Backend storage/partitioning internals are intentionally out of scope for this reference because they are not required by API clients to invoke the contract correctly.
> 
> **Note:** `polymorphic` does not apply to this endpoint. The raw OrientDB SQL query is executed as-is; polymorphic filtering must be expressed in the SQL itself.

## `bypassHierarchyCheck` — Admin Only

**Purpose:** Allows global administrators to explicitly bypass the boundary verification when adding instances to Contexts.

| Parameter | Type | Default | Required |
|-----------|------|---------|:--------:|
| `bypassHierarchyCheck` | boolean | `false` | ❌ |

| Role | Available |
|------|:---------:|
| IS-M / Infra-M | ✅ |
| IS-Admin / Ctx-M | ❌ |
| IS-Editor | ❌ |
| IS-Contrib | ❌ |
| IS-Member | ❌ |

**Applicable endpoints:**
- **Admin Add to Context:** `PUT /admin/instances/{type}/{instance-uuid}/contexts/{new-context-uuid}`

**Behavior:**
When an administrator performs an `Admin Add to Context` operation, the system normally verifies that the target Context belongs to the same logical hierarchy as the source Context to prevent accidental graph cross-contamination. 
By passing `bypassHierarchyCheck=true`, an `IS-M / Infra-M` explicitly declares their intent to bypass this validation, allowing them to force the injection of instances across completely divergent subtrees. Because this operation breaks standard boundaries, the bypass is never implicit; the administrator must explicitly declare their intent via this parameter.

> **⚠️ Warning on Recursive Propagation:** The `bypassHierarchyCheck` parameter applies **recursively** to the entire avalanche effect triggered by the `propagationMode`. For example, if combined with `propagationMode=deep`, the system will recursively import the initial instance *and all its transitively connected dependencies* into the new Context branch without enforcing hierarchy checks on any of the propagated nodes. This is an immensely powerful tool designed to migrate entire graph clusters across tenant boundaries, but it carries a severe risk of unintended cross-tenant contamination. Administrators are strongly advised to always run complex cross-boundary imports with `dryRun=true` first to inspect the blast radius.

## Parameter Conflicts

The API is strictly defensive against ambiguous or contradictory intents. The following query parameter combinations are mutually exclusive and will trigger an immediate `400 Bad Request` or an `X-Warning` header if submitted together.

| Query Parameter 1 | Query Parameter 2 | Resolution Rule | System Effect |
| :--- | :--- | :--- | :--- |
| `hierarchical=true` | `syncExistingHierarchy=true` | These represent two mutually exclusive distribution topologies for a `PUT` operation. | `400 Bad Request` |
| `rawResult=true` | `metadataPolicy=root` / `metadataPolicy=all` | `rawResult` takes precedence. `metadataPolicy` is ignored. | `X-Warning` Header |
| `rawResult=true` | `includeContexts=true` | `rawResult` takes precedence. `includeContexts` is ignored. | `X-Warning` Header |

In addition to parameter-to-parameter conflicts, the API enforces precedence rules when parameters conflict with HTTP Headers:

| HTTP Header | Query Parameter | Resolution Rule | System Effect |
| :--- | :--- | :--- | :--- |
| `Prefer: return=minimal` | `metadataPolicy=root` / `metadataPolicy=all` | `Prefer: return=minimal` takes precedence. `metadataPolicy` is ignored. | `X-Warning` Header |
| `Prefer: return=minimal` | `includeContexts=true` | `Prefer: return=minimal` takes precedence. `includeContexts` is ignored. | `X-Warning` Header |

Finally, when the client submits a JSON Query Payload (via `QUERY /instances`) or executes a Query Template (via `QUERY /query-templates/{name}` and its `/access` mirror), internal query directives can override URL parameters:

| JSON Payload Directive | Query Parameter | Resolution Rule | System Effect |
| :--- | :--- | :--- | :--- |
| `_emit` | `metadataPolicy=root` / `metadataPolicy=all` | `_emit` takes precedence. `metadataPolicy` is ignored. | `X-Warning` Header |
| `_emit` | `includeContexts=true` | `_emit` takes precedence. `includeContexts` is ignored. | `X-Warning` Header |

*(Note on `_emit`: The resolution rules and precedence interactions for the `_emit` JSON query keyword are formally detailed in the [Canonical _emit precedence rules](appendix/07-json-query-syntax-reference.html#canonical-emit-precedence-rules) chapter).*
