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.

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

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

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}
HEAD /instances/{type}/{instance-uuid}
GET /instances/{type}/{instance-uuid}
GET /access/... | ✅ | Expands visibility subtree. Retrieves instances that exist anywhere within the authorized descendant Contexts. | | 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. | | 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). | | 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}
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):

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

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.

`propagationMode` (Add to Context)¶

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

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

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 links, any mandatory ConsistsOf instances and their target Facet instances possessing an add: propagate constraint are strictly pulled into C2 to satisfy structural integrity.)

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

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

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

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.

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¶

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¶

includeContexts¶

Admin Specific Parameters¶

rawResult — Raw Query only¶

bypassHierarchyCheck — Admin Only¶

Parameter Conflicts¶

`limit` and `offset`¶

`lifecycle`¶

`polymorphic`¶

`depth`¶

`hierarchical`¶

`syncExistingHierarchy`¶

`propagationMode`¶

`propagationMode` (Add to Context)¶

`propagationMode` (Remove from Context)¶

`dryRun`¶

`metadataPolicy`¶

`includeContexts`¶

`rawResult` — Raw Query only¶

`bypassHierarchyCheck` — Admin Only¶