# 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 the response was expanded or filtered relative to the requested scope. The absence of the header means that the response is exactly the requested scope, not that it is global.

## 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` | The request was evaluated over the token Context and its descendants (`hierarchical=true`). It is emitted on every such request, whether or not a descendant contributed to the result: it states how the result was computed, not what it contains | Any read, query, or write with `hierarchical=true` |
| `state-filtered` | Response omits instances or Context membership entries that lie inside the requested boundary, or a hierarchical write skipped descendant Contexts, because the `effectiveState` of those Contexts is not `active` | Hierarchical read/query over mixed-state subtrees; `List Instance Contexts` on an instance present in non-`active` Contexts; `hierarchical=true` or `syncExistingHierarchy=true` writes by a role without the administrative state override |
| `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 |

These are three atomic tokens, not a closed enumeration of pre-combined values. Any tokens that apply
to the same response are emitted as a comma-separated HTTP list.

**Membership boundary:** `membershipScope=subtree` explicitly requests memberships in the token
Context subtree and is the default for every role. Omitting memberships outside that requested
boundary is the requested result, not a filtering, and emits no token. A Root Context token
makes the subtree topologically global. `IS-M`, `Infra-M`, and `IS-Admin` may explicitly request
`membershipScope=global`; every other role receives `403 Forbidden` rather than a silently narrowed
successful response.

### 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`
- Explicit subtree membership view:
  - Request: `GET /instances/{type}/{instance-uuid}/contexts?membershipScope=subtree`
  - Response header: no scope token, even when memberships exist outside the subtree
- Global membership view:
  - Request by `IS-M`, `Infra-M`, or `IS-Admin`: `GET /instances/{type}/{instance-uuid}/contexts?membershipScope=global`
  - Response header: no scope token is required when the complete requested view is returned
- Membership view of an instance found in a descendant:
  - Request: `GET /instances/{type}/{instance-uuid}/contexts?hierarchical=true`
  - Response header: `X-Result-Scope: hierarchical`
- 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,state-filtered`
  - Response header: `X-Result-Scope: hierarchical,previous-path`

### 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, state-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.
