Imported from registry/relations/has-capability.md at commit 76a4a0c89924.

IRI Link Relation: has-capability

Relation URI: https://iri.science/rels/has-capability
CURIE: iri:has-capability
Status: Provisional
Version: 1.0.0
Source representation type: DOE-IRI Resource representation or Facility API ProjectAllocation representation.
Source resource type: Any registered DOE-IRI resource type (urn:doe-iri:resource:*) when the source is a Resource; not applicable when the source is a ProjectAllocation.
Target representation type: Facility API Capability representation identified by capability_uris on a Resource or capability_uri on a ProjectAllocation.

This document defines the iri:has-capability relationship used by Facility API Resource and ProjectAllocation representations.

The canonical relation URI is https://iri.science/rels/has-capability. With the canonical IRI CURIE template https://iri.science/rels/{rel}, iri:has-capability expands to that URI. The relation URI identifies the link-relation semantics and is distinct from any target representation profile.

1. Relationship Metadata

2. Semantic Meaning

The iri:has-capability relationship identifies a Capability associated with its source. The relation has one shared meaning, with source-specific interpretation:

• On a DOE-IRI Resource, the target Capability is provided by the Resource.
• On a Facility API ProjectAllocation, the target Capability is the Capability to which the allocation applies.

It does not assert current availability, allocation balance, enabled state, user permission, or schedulability of the Capability.

3. Source and Target Representation

The relationship MAY originate from either of the following source representations:

• A DOE-IRI Resource representation, targeting the Facility API Capability representations named by its capability_uris array.
• A Facility API ProjectAllocation representation, targeting the Facility API Capability representation named by its required capability_uri.

The targets are independently identifiable API resources, not DOE-IRI typed Resources, operation entry points, or relationship resources.

4. Cardinality

A Resource MAY identify zero, one, or multiple Capability targets:

Resource  -- iri:has-capability -->  Capability
   1                 0..*

A ProjectAllocation has exactly one semantic Capability target under the current required capability_uri contract:

ProjectAllocation  -- iri:has-capability -->  Capability
       1                      1

A Resource uses an array when multiple targets are supplied. A ProjectAllocation uses a singular link object. During the additive transition, _links remains optional even for the exact-one ProjectAllocation association.

5. Static and Dynamic Semantics

For a Resource, this relation describes relatively stable configured capability membership and SHOULD NOT change solely because a Capability is temporarily unavailable, exhausted, disabled for a requester, or otherwise affected by operational conditions.

For a ProjectAllocation, this relation identifies the Capability against which the allocation is recorded. It is not a live assertion of remaining allocation, current service availability, or whether the source is usable by a particular requester.

6. Authorization and Visibility

Authorization MAY affect Capability discoverability. A provider MAY omit individual iri:has-capability targets or the relation when it cannot reveal the target. The absence of visible targets does not generally prove that the source has no Capability associations.

7. Compatibility

This relation is additive. Existing URI fields remain authoritative during migration.

1. Resource producers retain capability_uris and MAY add _links["iri:has-capability"] as an array of HAL links.
2. ProjectAllocation producers retain capability_uri and MAY add _links["iri:has-capability"] as a singular HAL link object.
3. Whenever both forms are present, the Resource link array and capability_uris MUST identify the same targets, disregarding order; the ProjectAllocation link’s href MUST equal capability_uri.
4. Consumers SHOULD prefer the advertised relation and MAY fall back to the corresponding legacy URI field.

Removing or changing either URI field requires a subsequent OpenAPI change.

8. HAL Representation

Resource example:

{
  "capability_uris": [
    "/api/v2/account/capabilities/cpu-node-hours",
    "/api/v2/account/capabilities/gpu-node-hours"
  ],
  "_links": {
    "iri:has-capability": [
      { "href": "/api/v2/account/capabilities/cpu-node-hours", "profile": "https://iri.science/profiles/account/capability" },
      { "href": "/api/v2/account/capabilities/gpu-node-hours", "profile": "https://iri.science/profiles/account/capability" }
    ]
  }
}

ProjectAllocation example:

{
  "capability_uri": "/api/v2/account/capabilities/gpu-node-hours",
  "_links": {
    "iri:has-capability": {
      "href": "/api/v2/account/capabilities/gpu-node-hours",
      "profile": "https://iri.science/profiles/account/capability"
    }
  }
}

DOE Integrated Research Infrastructure — Link Relation: has-capability