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 | The requested subtree contains non-active descendant Contexts, whose instances are not selected; or Context membership entries are omitted from a contexts map; 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.