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.

Parameter Value Handling¶

Every query parameter follows the same four rules:

Malformed or unknown value → 400 Bad Request. A value of the wrong type (e.g., limit=abc, hierarchical=yes), outside the accepted enumeration (e.g., metadataPolicy=full), or outside the documented domain (e.g., depth=-5, offset=-1, limit=0) is a client error. The server never replaces it with a default. Boolean parameters accept only true and false, case-insensitively; enumerated values follow the lowerCamelCase convention (see Naming Conventions).
Valid value not applicable to the operation, or overridden by another directive (e.g., a Prefer: return=minimal header or an _emit projection) → ignored, with an X-Warning of the ignored-query-parameters family. An unknown parameter name is ignored the same way.
Valid value beyond a server bound (limit above the maximum, or limit=-1) → clamped, with an X-Warning of the modified-query-parameters family.
Privilege-expanding value without the required role → 403 Forbidden; it is never ignored or narrowed (see REST API Design Principles).

The rules are evaluated in this order: authorization first (rule 4), then value validity (rule 1), then applicability (rules 2 and 3). A privilege-expanding value is therefore rejected with 403 Forbidden even when another directive would have ignored it (e.g., membershipScope=global together with Prefer: return=minimal, _emit, or rawResult=true); for an authorized role the same combination is ignored with X-Warning.

The sections below state, for each parameter, its accepted values; every other value falls under rule 1.

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.

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.

| 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
Execute Query Template: QUERY /query-templates/{name}
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.

| 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}):

The response is always a flat array with the requested element first, followed by the included descendants level by level (see Read shape and depth for Contexts).
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 and returns 400 Bad Request.

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 and returns 400 Bad Request.

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 Instance queries and Query Template execution). 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) form a flat collection: each definition is 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 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.

Every request with hierarchical=true returns X-Result-Scope: hierarchical, whether or not a descendant contributed to the result: the token states that the result was computed over the subtree, so an empty or unchanged result means there was nothing more to find, not that the expansion did not happen.

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}
List Instance Contexts: GET /instances/{type}/{instance-uuid}/contexts
Create Instance: POST /instances/{type}
Create/Update Instance: PUT /instances/{type}/{instance-uuid}
Execute Query Template: QUERY /query-templates/{name}
Add to Context: PUT /instances/{type}/{instance-uuid}/contexts/{new-context-uuid} (write use restricted to IS-M, Infra-M, and IS-Admin)
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}
HEAD /instances/{type}/{instance-uuid}
GET /instances/{type}/{instance-uuid}
GET /instances/{type}/{instance-uuid}/contexts
GET /access/... | ✅ | Expands visibility subtree. Retrieves instances that exist anywhere within the authorized descendant Contexts, except, for roles without the administrative state override, those only in non-active descendants. | | Search / Query | QUERY /instances
QUERY /query-templates/{name}
QUERY /access/query-templates/{name} | ✅ | Expands search boundary to include all descendant Contexts. | | Write (Hierarchical Distribution) | PUT /instances/{type}/{instance-uuid} (Create/Update)
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 (for roles allowed to use the parameter; any other role receives 403 Forbidden). | | Membership Add | PUT /instances/{type}/{instance-uuid}/contexts/{new-context} | ✅ | IS-M, Infra-M, and IS-Admin may atomically apply the source blueprint to the target Context and all descendants. Other roles receive 403 Forbidden when requesting this write expansion. | | Membership Remove | DELETE /instances/{type}/{instance-uuid} | ❌ | Ignored (X-Warning) as not applicable, for roles allowed to use hierarchical on writes; any other role receives 403 Forbidden. Removal acts strictly on the current token Context: hierarchical removal is the privileged Admin Remove from Context operation. | | 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 Removal | DELETE /admin/instances/{type}/{instance-uuid} | ✅ | Hierarchically removes membership from the token Context subtree. |

Global Atomicity Guarantee for Mutations: For all supported write operations (Create/Update, Add to Context, Admin Remove from Context) 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 (for roles without the administrative state override, in an active part of it; see the lookup matrix below). 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 contextsPolicy=root or contextsPolicy=all.

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):

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. When the exact (type, instance-uuid) key exists only in a descendant, omitting the flag narrows the requested Context scope and deterministically returns 403 Forbidden.

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 located only within non-active descendant Contexts are left out of lists and query results. A point lookup (HEAD / GET) of such an instance returns 403 Forbidden, as for any instance that exists outside the requested scope. Furthermore, memberships in non-active Contexts are omitted from every contexts map, with or without hierarchical=true (the default membershipScope=subtree already covers the descendants). | 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) | | Administrative Overrides (IS-Admin, Ctx-M, or higher) | Applied. Administrative roles bypass operational locks within the scope granted by their role. Their hierarchical writes reach suspended and created descendants. | No state-filtered (the hierarchical token is still emitted) |

Note on Client Observability: When the system filters out instances during a hierarchical read/query, or Context memberships from a contexts map in any read, 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 | ❌ |

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. Both cases apply to roles allowed to use the flag; any other role receives 403 Forbidden (see Parameter Value Handling).
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.

`propagationMode` (Add to Context)¶

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

Applicable endpoints:

Add to Context: PUT /instances/{type}/{instance-uuid}/contexts/{new-context-uuid}

Behavior:

surgical (Precise Injection): Restricted to IS-M, Infra-M, and IS-Admin on the standard Add to Context endpoint. 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. The parameter is safely ignored and the system emits an X-Warning header.
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).

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.

---
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 instances, each of its ConsistsOf instances possessing an add: propagate constraint is pulled into C2 together with its target Facet instance.)

---
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;

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 \(\rightarrow\) R2 enters C2 \(\rightarrow\) R3 is already in ``C2`` (STOP). R4 is never evaluated and remains exclusively in Context C1.

---
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;

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 \(\rightarrow\) R2 enters C2 \(\rightarrow\) R3 is already in C2, but the algorithm continues evaluating its outgoing Relation instances \(\rightarrow\) the IRT34 Relation instance pushes R4 into C2.

---
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).

| Role | Available | Scope | |——|:———:|——-| | IS-M / Infra-M | ✅ | Yes | | IS-Admin | ✅ | Yes | | 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. The parameter is safely ignored and the system emits an X-Warning header.
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, it is a valid but inapplicable value: the system emits an X-Warning header and falls back to shallow (rule 2 of Parameter Value Handling).)

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.

`dryRun`¶

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

| 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}
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, 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.

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.

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}
Create Type: PUT /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)
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}
Create/Update Query Template: PUT /query-templates/{name}
Execute Query Template: QUERY /query-templates/{name} (Note: When _emit is used, apply the canonical rules in JSON Query Syntax Reference)
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.

`contextsPolicy`¶

Purpose: Control whether the response includes the contexts membership map and whether that map is added only to top-level response elements or also to their nested elements. This policy controls representation depth only; role- and token-based visibility independently determine which Context memberships each emitted map may contain.

none (default): omit contexts from every returned element.
root: include contexts only on top-level response elements. In a list or operation envelope, every direct array item is a top-level element.
all: include contexts on top-level and nested elements, including nested Facet and ConsistsOf instances, and the source/target endpoint references of Relations.

Wire values are lowercase. Supplying any other value returns 400 Bad Request (see Parameter Value Handling).

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)
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)
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).

`membershipScope`¶

Purpose: Select the Context boundary used to populate every emitted contexts membership map. This parameter is orthogonal to contextsPolicy, which controls where those maps appear, and to hierarchical, which controls the Context boundary used to select or mutate instances.

subtree (default): include memberships in the token Context and its descendants. A token issued for the Root Context therefore covers the complete Context tree.
global: include every Context membership independently of the token Context. This value is restricted to IS-M, Infra-M, and IS-Admin.

Wire values are lowercase. An unknown value returns 400 Bad Request. A caller other than IS-M, Infra-M, or IS-Admin requesting global receives 403 Forbidden; the server never silently downgrades it to subtree.

| Role | subtree | global | |——|:———:|:——–:| | IS-M / Infra-M | ✅ | ✅ | | IS-Admin | ✅ | ✅ | | Ctx-M | ✅ | ❌ | | IS-Editor | ✅ | ❌ | | IS-Contrib | ✅ | ❌ | | IS-Member | ✅ | ❌ |

Applicable endpoints:

Every instance endpoint that supports contextsPolicy.
List Instance Contexts: GET /instances/{type}/{instance-uuid}/contexts and its /access mirror. This endpoint always returns memberships, so membershipScope applies without a contextsPolicy parameter.
Execute Query Template: QUERY /query-templates/{name} and its /access mirror when the returned representation includes membership maps.

Interaction rules:

On ordinary instance representations, membershipScope does not cause a contexts map to appear; contextsPolicy=root|all remains necessary.
hierarchical=true&membershipScope=global is valid and intentionally independent: instances are selected from the token Context subtree, while each emitted membership map is global.
Omitting memberships outside an explicitly requested subtree is the requested base result and emits no X-Result-Scope token.
State-based restrictions that further narrow the requested boundary still emit their applicable X-Result-Scope token.
On GET /instances/{type}/{instance-uuid}/contexts, membershipScope does not affect how the instance is found: the lookup follows the same rule as Read (token Context, or its descendants with hierarchical=true) for every role, global included. A caller that knows only the UUID uses a token of a Context high enough in the tree, with hierarchical=true.

Privileged 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, contextsPolicy, and membershipScope. 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, non-default contextsPolicy, and an explicit non-default membershipScope 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` — Cross-Boundary Add¶

Purpose: Allows IS-M, Infra-M, and IS-Admin to explicitly bypass destination-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:

Add to Context: PUT /instances/{type}/{instance-uuid}/contexts/{new-context-uuid}

Behavior: Add to Context normally restricts Ctx-M and IS-Editor to the token Context subtree and allows IS-M, Infra-M, and IS-Admin to reach that subtree plus sibling Contexts. By passing bypassHierarchyCheck=true, an IS-M, Infra-M, or IS-Admin explicitly declares the intent to target a completely unrelated branch. The flag waives destination containment only: the exact token Context remains the operation’s source topology. Because this operation breaks standard boundaries, the bypass is never implicit.

⚠️ 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.

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

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:

(Note on _emit: The resolution rules and precedence interactions for the _emit JSON query keyword are formally detailed in the Canonical _emit precedence rules chapter).

Resource Registry — API Query Parameters Reference¶

Parameter Value Handling¶

Pagination Parameters¶

limit and offset¶

Behavioral Parameters¶

lifecycle¶

polymorphic¶

depth¶

hierarchical¶

Hierarchical Operations over Mixed-State Subtrees¶

syncExistingHierarchy¶

propagationMode¶

propagationMode (Add to Context)¶

propagationMode (Remove from Context)¶

dryRun¶

Inclusion Parameters¶

metadataPolicy¶

contextsPolicy¶

membershipScope¶

Privileged Parameters¶

rawResult — Raw Query only¶

bypassHierarchyCheck — Cross-Boundary Add¶

Parameter Conflicts¶

`limit` and `offset`¶

`lifecycle`¶

`polymorphic`¶

`depth`¶

`hierarchical`¶

`syncExistingHierarchy`¶

`propagationMode`¶

`propagationMode` (Add to Context)¶

`propagationMode` (Remove from Context)¶

`dryRun`¶

`metadataPolicy`¶

`contextsPolicy`¶

`membershipScope`¶

`rawResult` — Raw Query only¶

`bypassHierarchyCheck` — Cross-Boundary Add¶