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.