Imported from registry/profiles/account/capability.md at commit 76a4a0c89924.

IRI Account Capability Profile

Profile URI: https://iri.science/profiles/account/capability
OpenAPI type: Capability
Status: Draft
Version: 1.0.0

1. Purpose

This document defines the semantic profile for an IRI Account Capability representation.

The canonical identifier for this profile is:

https://iri.science/profiles/account/capability

An IRI Capability represents an allocatable or otherwise distinguishable aspect of an IRI Resource.

A Capability allows a Facility to describe a portion, class, or characteristic of a Resource against which allocations may be granted and usage may be accounted.

For example, a compute Resource may expose a Capability corresponding to GPU-enabled nodes, while another Capability may represent CPU-only capacity.

A Capability is distinct from:

  • a Resource, which represents the underlying compute, storage, network, service, or other infrastructure;
  • a Project Allocation, which grants a Project some quantity of a Capability;
  • a User Allocation, which assigns some portion of a Project Allocation to a user;
  • an allocation unit, which identifies how the quantity of a Capability is measured.

The normative structural definition of a Capability representation is provided by the IRI Facility API OpenAPI specification.

This profile supplements that schema with application-level semantics, relationship conventions, and interoperability requirements.

2. Profile Semantics

An IRI Capability identifies an aspect of a Resource that can participate in the IRI allocation model.

A Capability MAY correspond:

  • one-to-one with an underlying Resource;
  • to a subset or partition of a Resource;
  • to a particular class of Resource functionality;
  • to an allocatable Resource characteristic.

For example, a compute system may expose:

GPU nodes
CPU nodes
large-memory nodes

as separately allocatable Capabilities even though they belong to the same underlying compute Resource.

A Capability does not itself represent:

  • an allocation;
  • an authorization grant;
  • current availability;
  • an operation entry point;
  • a guarantee that the Capability can presently be consumed.

Those concerns are represented independently.

3. Structural Contract

The structural definition of the Capability representation is defined by the IRI Facility API OpenAPI Capability schema.

The current Capability schema defines the following properties:

Property Required Semantic purpose
id Yes Stable identifier for the Capability.
name No Human-readable long name of the Capability.
description No Human-readable description of the Capability.
last_modified No Time at which the Capability representation was last modified.
units Yes Allocation units supported by the Capability.
self_uri Yes Canonical API URI of the Capability representation.

The OpenAPI schema is authoritative for:

  • property names;
  • JSON data types;
  • required properties;
  • nullable properties;
  • formats;
  • structural validation;
  • read-only properties.

The applicable IRI controlled-vocabulary or URN specifications are authoritative for registered allocation-unit identifiers where those specifications are adopted.

This profile is authoritative for additional semantic and interoperability conventions associated with a Capability representation.

4. Capability Identity

The id property identifies the Capability instance.

The identifier MUST be stable within the identifier scope established by the IRI Facility API.

Clients MUST treat id as an opaque identifier unless another IRI specification explicitly defines additional semantics for that identifier.

For example:

{
  "id": "perlmutter-gpu"
}

identifies a particular Capability.

Clients MUST NOT infer API paths from the Capability identifier.

For example, a client MUST NOT assume that:

perlmutter-gpu

implies:

/api/v2/account/capabilities/perlmutter-gpu

The canonical Capability URI MUST instead be obtained from self_uri or the corresponding advertised hypermedia link.

5. Capability Naming

5.1 name

name provides the human-readable name of the Capability.

For example:

{
  "name": "Perlmutter GPU Nodes"
}

The name is descriptive and MUST NOT be treated as the stable identity of the Capability.

5.2 description

description provides additional human-readable information about the Capability.

For example:

{
  "description": "GPU-enabled compute capacity available to allocated projects."
}

Descriptions MAY change without changing the identity of the Capability.

6. Allocation Units

The units property identifies the units in which allocations associated with the Capability may be expressed.

For example:

{
  "units": [
    "node_hours"
  ]
}

A Capability MAY support more than one allocation unit when permitted by the governing API contract.

The presence of a unit on a Capability means that allocations for that Capability may be expressed using that unit.

It does not indicate:

  • the amount allocated;
  • the amount consumed;
  • remaining capacity;
  • Resource availability.

Those values belong to the applicable allocation representation.

Conceptually:

Capability
    │
    └── supports allocation measurement in
             ↓
        Allocation Unit

ProjectAllocation
    │
    └── records
             ↓
        allocation + usage

If the IRI Allocation Unit vocabulary is represented using DOE-IRI URNs, producers and consumers SHOULD use the registered canonical URN values defined by the applicable IRI specification.

7. Capability and Resource Relationship

A Capability is associated with an IRI Resource.

The Resource representation exposes this association in the Resource-to-Capability direction through:

capability_uris

The registered hypermedia relation is:

iri:has-capability

with canonical relation URI:

https://iri.science/rels/has-capability

Conceptually:

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

A Capability linked through iri:has-capability represents an allocatable or otherwise distinguished aspect of the source Resource.

The existence of this relationship MUST NOT be interpreted as:

  • granting an allocation;
  • granting permission to use the Resource;
  • indicating current availability;
  • indicating remaining allocation;
  • identifying an operation endpoint.

8. Capability and Allocation Relationship

A Project Allocation applies to a Capability.

The current Project Allocation representation exposes the target Capability through:

capability_uri

which maps to:

iri:has-capability

in the current HAL relationship model.

The same relation therefore appears in different representation contexts:

Resource
   │
   └── iri:has-capability
              ↓
         Capability


ProjectAllocation
   │
   └── iri:has-capability
              ↓
         Capability

The source representation determines the specific contextual interpretation:

  • from a Resource, the Capability is provided or associated with that Resource;
  • from a Project Allocation, the allocation applies to that Capability.

The canonical iri:has-capability relation definition is authoritative for the complete cross-context semantics.

This Capability profile MUST NOT redefine the registered relation.

9. Hypermedia Representation

When represented using HAL, a Capability SHOULD advertise its canonical identity through _links.self.

For example:

{
  "id": "perlmutter-gpu",
  "name": "Perlmutter GPU Nodes",
  "description": "GPU-enabled compute capacity available to allocated projects.",
  "units": [
    "node_hours"
  ],

  "_links": {
    "self": {
      "href": "https://api.example.org/api/v2/account/capabilities/perlmutter-gpu",
      "type": "application/hal+json",
      "profile": "https://iri.science/profiles/account/capability"
    },

    "curies": [
      {
        "name": "iri",
        "href": "https://iri.science/rels/{rel}",
        "templated": true
      }
    ]
  }
}

In this representation:

  • self identifies the Capability representation;
  • href identifies the target URI;
  • type identifies the expected representation media type;
  • profile identifies the IRI Account Capability semantic profile.

The representation profile URI is not a Capability identifier and MUST NOT be treated as one.

10. Relationship URIs

IRI-specific relations use the IRI CURIE namespace.

For example:

{
  "name": "iri",
  "href": "https://iri.science/rels/{rel}",
  "templated": true
}

The CURIE:

iri:has-capability

expands to:

https://iri.science/rels/has-capability

The canonical relation document defines the normative semantics of the relationship.

The Capability profile MUST NOT redefine those link-relation semantics.

11. Relationship to Existing URI Properties

The current Capability schema defines:

self_uri

as the canonical URI of the Capability representation.

When the HAL hypermedia model is used:

self_uri
    ↓
_links.self

For example:

{
  "self_uri":
    "https://api.example.org/api/v2/account/capabilities/perlmutter-gpu",

  "_links": {
    "self": {
      "href":
        "https://api.example.org/api/v2/account/capabilities/perlmutter-gpu",
      "profile": "https://iri.science/profiles/account/capability"
    }
  }
}

During the compatibility period:

  1. Producers retain the required self_uri property.
  2. Producers MAY additionally expose _links.self.
  3. Whenever both are present, _links.self.href MUST exactly equal self_uri.
  4. Consumers SHOULD prefer the advertised HAL relation and MAY fall back to self_uri.
  5. Removing or changing self_uri requires a separate OpenAPI schema revision.

Clients SHOULD use the advertised canonical URI rather than constructing Capability URLs from identifiers.

12. Media Type

This profile identifies the semantics of the Capability representation independently of a particular serialization.

When a Capability is represented using HAL JSON, the representation SHOULD use:

application/hal+json

and MAY identify this profile where appropriate:

https://iri.science/profiles/account/capability

The media type and profile serve different purposes:

application/hal+json
    ↓
HOW the representation is encoded

https://iri.science/profiles/account/capability
    ↓
WHAT semantic representation contract applies

They MUST NOT be treated as interchangeable.

13. Static and Dynamic Semantics

A Capability representation primarily describes relatively stable allocation and Resource-model information.

Relatively stable information includes:

id
name
description
units

last_modified indicates when the Capability representation was most recently modified when that value is available.

The existence of a Capability MUST NOT be interpreted as indicating:

  • that capacity is currently available;
  • that an authenticated user has an allocation;
  • that a Project is authorized to consume the Capability;
  • that the underlying Resource is operational.

Those questions require the appropriate Resource status, allocation, authorization, or operational representations.

14. Authorization and Visibility

Authorization MAY affect which Capabilities are visible to a requester.

A Facility MAY expose only Capabilities the requester is permitted to discover, subject to the governing API contract.

The absence of a Capability from a Resource or Capability collection MUST NOT necessarily be interpreted as proof that the Capability does not exist.

Likewise, visibility of a Capability MUST NOT itself be interpreted as authorization to consume that Capability.

Allocation and authorization decisions remain separate from Capability discovery.

Clients SHOULD treat the returned representation as the Capability information visible in the current requester context.

15. Conformance

A representation conforms to the IRI Account Capability Profile when:

  1. it conforms to the applicable IRI Facility API Capability schema;
  2. its properties are interpreted according to the IRI Facility API and this profile;
  3. id is treated as a Resource-local identifier rather than a URL template;
  4. units identifies supported allocation measurement units rather than allocation quantities;
  5. Capability visibility is not interpreted as an authorization or allocation grant;
  6. associated Resource and allocation relationships use registered IRI link relations where advertised;
  7. IRI-specific link relations use the canonical IRI relation namespace;
  8. profile URIs identify representation semantics and are not used as substitutes for link-relation identifiers;
  9. when both self_uri and _links.self are present, they identify the same target;
  10. clients are not required to infer or construct Capability URLs.

A conforming representation MAY contain additional properties and links where permitted by the applicable IRI API specification.

16. Profile Identification

The canonical identifier for this profile is:

https://iri.science/profiles/account/capability

The profile URI is a stable semantic identifier.

Repository paths, GitHub URLs, OpenAPI locations, allocation-unit identifiers, Capability instance identifiers, and documentation-generation URLs MUST NOT be substituted for this canonical identifier.

The canonical URI SHOULD resolve to documentation describing this profile.

17. Versioning

The profile version identifies the revision of this profile document.

Compatible editorial clarifications and backward-compatible semantic additions MAY retain the same profile URI.

Adding new allocation units or new Capability instances does not itself require a new Capability profile URI.

Changes that materially alter the interpretation or processing semantics of the common Capability representation SHOULD be evaluated for compatibility before incorporation into the existing profile.

The canonical profile URI SHOULD remain stable across compatible revisions.

DOE Integrated Research Infrastructure — Account Capability Profile