# X-Result-Scope Conventions

To explicitly communicate to the client when a successful response payload has been intentionally filtered or expanded beyond the standard base URI scope, the Resource Registry API emits the `X-Result-Scope` HTTP header.

This ensures that clients, especially those implementing strict sync logic or UI state management, can programmatically detect when they are receiving a partial or aggregated view of the infrastructure rather than a global representation.

## Normative Values

The following table defines the possible values emitted within the `X-Result-Scope` header and the typical operational scenarios that trigger them.

| Header value | Meaning | Typical case |
|--------------|---------|--------------|
| `hierarchical` | Success is based on descendant-tree scope expansion relative to the base URI Context | `GET`/`HEAD` instance lookup with `hierarchical=true` |
| `role-filtered` | Response is visibility-filtered by caller role/scope | An instance's `contexts` map (only built when `includeContexts=true`) or a `List Instance Contexts` response, filtered to the caller's competence subtree |
| `state-filtered` | Response omits descendant-tree instances because their Context `effectiveState` is not `ACTIVE` | Hierarchical read/query over mixed-state subtrees |
| `previous-path` | The caller's token path resolved through a Context's `previousPaths`; `X-Resolved-Context-Path` carries its current path | Any operation that derives its operational Context from the token |
| `hierarchical,role-filtered` | Expanded tree lookup + role-based visibility filtering | Hierarchical query executed by non-global managerial role |
| `hierarchical,role-filtered,state-filtered` | All conditions apply: expanded tree + role visibility + state-filtered descendants | Hierarchical query by non-global role over mixed-state subtrees |

**Reference tree for subtree visibility:** `List Instance Contexts` always restricts membership visibility to the competence subtree defined by the operational token Context, including for `IS-M / Infra-M`; only a Root token yields a global membership view. Other instance responses apply the same tree to Context-bound roles (`IS-Admin / Ctx-M`, `IS-Editor`, `IS-Contrib`, `IS-Member`) when their optional `contexts` map is requested.

### Examples
- Hierarchical existence check:
  - Request: `HEAD /instances/{type}/{instance-uuid}?hierarchical=true`
  - Response header: `X-Result-Scope: hierarchical`
- Hierarchical lookup over mixed-state subtrees:
  - Request: `GET /instances/{type}?hierarchical=true`
  - Response header: `X-Result-Scope: hierarchical,state-filtered`
- Role-filtered instance Contexts:
  - Request: `GET /instances/{type}/{instance-uuid}/contexts`
  - Response header (when at least one membership lies outside the token Context subtree): `X-Result-Scope: role-filtered`
- Previous-path resolution:
  - Request token path: `/gcube/old-vo/VRE1`
  - Response headers: `X-Result-Scope: previous-path` and `X-Resolved-Context-Path: /gcube/new-vo/VRE1`
- Combined cases:
  - Response header: `X-Result-Scope: hierarchical,role-filtered`
  - Response header: `X-Result-Scope: hierarchical,role-filtered,state-filtered`

### Multiple Scope Modifiers (Formatting)

When multiple scope modifiers apply to the same response, they are combined into a comma-separated list within the `X-Result-Scope` header. 

Clients must treat this header as a standard HTTP list (which may contain optional whitespace around the comma, e.g., `hierarchical, role-filtered`). To reliably determine the active scopes, clients should parse the header by splitting on commas, stripping surrounding whitespace, and evaluating the presence of individual tokens, strictly ignoring both order and capitalization.
