Relationship Cheat Sheet
This page summarizes all 47 registered IRI relations and the standard links used by IRI v2. Each relation name links to its authoritative definition. This is an explanatory reference; the definitions, profiles, and checked-out OpenAPI remain authoritative. Proposed changes are not included.
Reading the tables
- Direction: source → target. Cardinality counts targets per source; it does not impose an inverse cardinality unless the definition says so.
- Cardinality:
1means exactly one;0..1means optional, at most one;0..*means zero or more. - Type shorthand:
compute:node,service:dtn, and similar names expand underurn:doe-iri:resource:. They identify Resource Types. Names such asEvent,Site, andJobidentify API representations, not Resource Type URNs. - Any Resource: any conforming IRI
Resourcerepresentation, including a service Resource. This does not mean any API representation. - Visibility: the tables describe semantic cardinality. Authorization can hide links or targets where the definition permits it. Required URI fields and retained HAL links must remain consistent; omission does not generally prove that a relationship or capability does not exist.
- Configuration: topology links describe configured relationships. They do not establish current health, availability, caller permission, or successful future access. Ordinary outages do not by themselves remove configured relationships.
- Wire form: HAL requires
href; never emit"href": null. Use singular link objects for singular relations and arrays for plural relations, following the definition’s examples and HAL links RFC. A link’sprofiledescribes its target representation, not its relation.
Core, facility, status, and allocation relations — 10
| Relation | Allowed source | Required target | Cardinality | Description and key restrictions |
|---|---|---|---|---|
| iri:located-at | Any Resource | Site |
1 |
Physical/administrative site from required site_uri. Do not independently hide the link while returning that field. It does not identify live process placement or hosting. |
| iri:has-site | Facility |
Site |
0..* |
Associated sites from site_uris. |
| iri:has-resource | Site |
Any Resource | 0..* |
Resources hosted at the site, from resource_uris. |
| iri:generated-by | Event |
Incident |
0..1 |
Incident associated with the event. Required-but-nullable incident_uri: null means omit the link. |
| iri:has-event | Incident |
Event |
0..* |
Events recorded as part of the incident, from event_uris. Does not require an inverse relationship on every event. |
| iri:impacts | Event |
Any Resource | 1 |
Resource to which the event applies, from required resource_uri. Distinct from an incident’s possible impact scope. |
| iri:may-impact | Incident |
Any Resource | 0..* |
Resources within the incident’s assessed possible impact scope, from resource_uris. |
| iri:has-project | ProjectAllocation |
Project |
1 |
Project to which the allocation belongs, from required project_uri. |
| iri:has-capability | Any Resource; ProjectAllocation |
Capability |
Resource: 0..*; ProjectAllocation: 1 |
A Resource provides the Capability (capability_uris); a ProjectAllocation applies to it (required capability_uri). |
| iri:has-project-allocation | UserAllocation |
ProjectAllocation |
1 |
Parent project allocation, from required project_allocation_uri. |
Where both legacy URI properties and HAL links are returned, their targets must agree. A nullable or absent URI maps to an omitted link. These mappings are additive; HAL links do not remove the current URI-property requirements.
Storage topology relations — 8
| Relation | Allowed source Resource Type | Required target Resource Type | Cardinality | Description and key restrictions |
|---|---|---|---|---|
| iri:provides-filesystem | storage:system |
storage:filesystem |
0..* |
Storage infrastructure provides a logical filesystem. This is provider topology, not mount or health information. |
| iri:provides-block | storage:system |
storage:block |
0..* |
Storage infrastructure provides logical block storage. Current attachment is not implied. |
| iri:provides-object | storage:system |
storage:object |
0..* |
Storage infrastructure provides a logical object resource. The target is not an object API endpoint. |
| iri:has-mount | storage:filesystem |
storage:mount |
0..* |
Filesystem exposure through a mount relationship Resource. A mount should normally describe one filesystem-to-consuming-system exposure and be referenced by one filesystem. |
| iri:mounted-on | storage:mount |
compute:system |
1 |
Consuming system whose namespace contains the filesystem exposure. One mount describes one exposure on one system; use separate mounts for different systems. Nodes and services are not allowed targets. |
| iri:accesses-mount | Any Resource representing an actual configured filesystem consumer | Exactly storage:mount |
0..* |
Consumer is configured to access a filesystem through this exposure. Includes compute, systems, nodes, generic services, DTNs, inference services, and other conforming types with that role; type validity alone is insufficient. |
| iri:accessed-by | Exactly storage:mount |
Any Resource representing an actual configured filesystem consumer | 0..* |
Inverse of iri:accesses-mount: identifies consumers of this exposure. Target profile describes the actual consumer, using the common Resource profile unless an applicable specialized profile is established. |
| iri:attached-to | storage:block |
compute:system or compute:node |
Exclusive: 0..1; shared: 0..* |
Configured block presentation/attachment. Cardinality depends on urn:doe-iri:storage:block-access-mode:exclusive or :shared. Shared mode does not establish safe arbitrary concurrent writes. |
Mounts are relationship Resources carrying exposure-specific information such
as mount_path, access mode, and protocol. A mount path belongs to the
declared consuming system’s namespace. If its required consuming-system target
cannot be disclosed, the definition recommends hiding the mount itself rather
than presenting misleading, incomplete topology.
The mount-access pair describes the same configured association in opposite
directions. Each direction is independently optional; neither reciprocal
advertisement nor exhaustive lists are required. Visible links describing the
same configuration must agree. Authorization may hide consumers or mounts,
and omission is not a negative access assertion. Resource Types, hosting,
containment, and iri:mounted-on alone do not establish access. Access links do
not relocate mount_path into a consumer’s node, service, or container
namespace, change the exactly-one iri:mounted-on target, or confer operation
eligibility.
Compute topology relations — 3
| Relation | Allowed source Resource Type | Required target Resource Type | Cardinality | Description and key restrictions |
|---|---|---|---|---|
| iri:has-node | compute:system |
compute:node |
0..* |
Node participates in, or is managed as part of, the system. Does not assert availability for workload execution or require one parent system per node. |
| iri:has-cpu | compute:node |
compute:cpu |
0..* |
Node contains, provides, or is associated with a CPU Resource. Hidden or omitted targets do not establish that the node has no CPUs. |
| iri:has-gpu | compute:node |
compute:gpu |
0..* |
Node contains, provides, or is associated with a GPU Resource. Omission alone does not establish zero accelerators. |
Service hosting relation — 1
| Relation | Allowed source Resource Type | Required target Resource Type | Cardinality | Description and key restrictions |
|---|---|---|---|---|
| iri:hosted-on | service:dtn or service:inference |
compute:system or compute:node |
0..* |
Hosting infrastructure for the service. Does not identify current routing, live replica placement, or a target currently serving requests. |
DTN technology, transfer protocols, and service endpoint attributes do not by themselves advertise operations, establish configured mount access, or grant caller authorization. Mount access is described by the pair in the storage topology table above.
Rules shared by all 25 operation relations
An operation relation targets an operation entry point, not the Resource,
Job, Task, file, location, or endpoint description returned by the operation.
Its 0..1 cardinality counts advertised entry points, not result objects.
- The adapter must implement the operation in the source’s explicit context.
Bind
resource_idto that context. Topology and Resource Type hierarchy alone do not establish operation applicability. - Eligibility is based on the exact types listed for each operation family; it is not automatically inherited by CPU, GPU, or other descendants.
- Follow the advertised
href. Obtain methods, inputs, responses, errors, and security from the applicable deployed OpenAPI description. Do not construct URLs or infer HTTP methods from relation names. - An advertised operation relation requires at least one applicable
service-descwhose deployed OpenAPI has the matching canonicalx-iri-relationbinding. Do not add an IRI representationprofileto the operation link or use HAL metadata to invent its method or request schema. - Presence grants no permission and guarantees no successful invocation. Omission means not advertised in this representation, not universally unsupported. Do not automatically forward credentials to an unrelated origin named by a discovered link or descriptor.
- When
supported_endpointsis present on a Resource, compute-operation links require"compute"and filesystem-operation links require"filesystem"in that array. Neither category implies any particular operation. The two storage-discovery relations have no such category requirement. This rule does not apply to Job representations.
See the operation-affordance RFC for the common binding rules.
Compute operation relations — 5
All five targets below are operation entry points. Each has cardinality 0..1
per eligible source. Generic compute, nodes, CPUs, and GPUs are not eligible.
| Relation | Allowed source | Cardinality | Description and additional restrictions |
|---|---|---|---|
| iri:submit-job | compute:system |
0..1 |
Submit a job in the system’s adapter context. resource_id is bound; advertise a concrete link. |
| iri:query-jobs | compute:system |
0..1 |
Query job statuses in that system context. Concrete link; query criteria remain in the OpenAPI-defined request. |
| iri:get-job | compute:system or Job |
0..1 |
Retrieve a selected job and its current status. Apply the selected-job binding rules below. |
| iri:update-job | compute:system or Job |
0..1 |
Update a selected job. On a Job, the link may be withdrawn when the update is not applicable to its lifecycle state. |
| iri:cancel-job | compute:system or Job |
0..1 |
Cancel a selected job. On a Job, the link may be withdrawn when cancellation is not applicable to its lifecycle state. |
Selected-job binding: for get-job, update-job, and cancel-job, a
compute-system source binds resource_id and may leave only job_id as a URI
template variable, with templated: true. A Job source binds both identifiers
and must advertise a concrete URI. A client cannot infer the compute-system
context from job_id, and expanding a template grants no permission over an
arbitrary job. A Job’s get-job link may cease to be advertised when its
operation context is no longer retained or visibility changes.
Filesystem operation relations — 18
Allowed source types for every row: exactly compute, compute:system,
compute:node, storage, storage:filesystem, storage:mount, or service:dtn.
storage:system, storage:block, storage:object, other services, CPUs, and
GPUs are not eligible.
Required context for every row: the adapter must establish the source’s filesystem namespace and one unambiguous execution/access context. Generic compute/storage semantics must be known; a mount requires its own mount-specific context; a DTN must itself be the adapter context. Neither mounts nor DTNs inherit operations from related Resources. If one source cannot identify an unambiguous context, expose separate Resources and registered topology links; do not silently select a host or add an undocumented context selector.
Target and invocation for every row: an asynchronous operation entry point.
The current mappings use POST and return TaskSubmitResponse; monitor the
Task for the outcome. They do not synchronously return the requested content,
metadata, or proof of completion. Bind resource_id and advertise a concrete
link, except for the permitted upload query template below.
| Relation | Cardinality | Description and additional restrictions |
|---|---|---|
| iri:change-file-mode | 0..1 |
Request a file permission-mode change. |
| iri:change-file-owner | 0..1 |
Request a file ownership change. |
| iri:identify-file | 0..1 |
Identify the type of a file or directory. |
| iri:stat-file | 0..1 |
Request file metadata. |
| iri:checksum-file | 0..1 |
Request a file checksum. |
| iri:create-directory | 0..1 |
Create a directory. |
| iri:create-symlink | 0..1 |
Create a symbolic link. |
| iri:list-directory | 0..1 |
List directory entries. |
| iri:read-file-head | 0..1 |
Read the beginning of a file. |
| iri:read-file-tail | 0..1 |
Read the end of a file. |
| iri:view-file | 0..1 |
Request file content asynchronously. Not a direct-content link or a GET file operation. |
| iri:copy-path | 0..1 |
Copy a file or directory path. |
| iri:download-file | 0..1 |
Request asynchronous download work. Do not treat the link as a direct download, binary stream, redirect, or inferred GET. |
| iri:upload-file | 0..1 |
Submit a multipart file upload. Required query parameter path may be bound or exposed as {?path} with templated: true; no other variable may remain unresolved. Preserve binding and encoding during expansion. |
| iri:remove-path | 0..1 |
Request destructive removal. Requires an explicit invocation under caller policy; discovery or traversal must not execute it. |
| iri:compress-paths | 0..1 |
Compress paths into an archive. |
| iri:extract-archive | 0..1 |
Extract an archive. |
| iri:move-path | 0..1 |
Move or rename a path. |
Storage discovery operation relations — 2
Both targets are discovery operation entry points. Both current mappings use
GET; bind resource_id to the source’s adapter context and advertise a
concrete link. Optional query filters are supplied according to OpenAPI.
Discovery results do not establish configured topology, authorization to use a
location or endpoint, health, or successful future access.
| Relation | Allowed source Resource Types | Cardinality | Description and additional restrictions |
|---|---|---|---|
| iri:resolve-storage-locations | Exactly compute, compute:system, compute:node, storage, storage:system, storage:filesystem, storage:mount, storage:block, storage:object, or service:dtn |
0..1 |
Resolve user-context StorageInstance entries. Optional filters: logicalpath, project, allocation, intent. The adapter must support the particular source and its response semantics; see the context conditions below. |
| iri:get-storage-access-endpoints | Exactly storage, storage:system, storage:filesystem, storage:block, or storage:object |
0..1 |
Retrieve AccessEndpoint descriptions. Optional filters: protocol, endpoint_id. Requires implemented discovery; generic storage semantics must be known and filesystem identifiers/path context explicitly supported. Mounts, compute Resources, and services are not eligible. Does not execute a transfer or protocol request. |
Location-resolution context conditions: generic compute/storage require
known, unambiguous adapter semantics; a compute system requires implementation
in that configured system context; a node requires explicit node configuration;
a filesystem requires accepted identifiers and a defined path/resolution
context; a mount requires explicit mount-specific support; a DTN must itself
be the adapter context. Storage systems, block storage, and object storage
require the existing StorageInstance response semantics to apply to them.
Classification, hosting, and mount-access links alone do not establish
eligibility. Ambiguous contexts require separate Resources rather than an
implicit host choice or undocumented selector.
The number of returned locations or endpoint descriptions is independent of
the discovery link’s 0..1 cardinality. Returned AccessEndpoint.capabilities
describe supported operations; they do not grant permission or advertise
protocol-invocation links.
Standard links and HAL CURIE declarations
These standard relations do not use the iri: prefix. Their IRI mappings and
requirements are defined by the HAL links RFC.
| Link | Source/context | Target | Cardinality or presence rule | Description and restrictions |
|---|---|---|---|---|
self |
Representation with canonical identity | Its canonical representation URI | 1 |
Required on HAL representations with canonical identity; agrees with self_uri when retained. A transient TaskSubmitResponse has no such requirement. |
help |
Facility mapping |
Help/support portal | 0..1 |
Maps optional, nullable support_uri; omit when absent/null. |
monitor |
TaskSubmitResponse mapping |
Task |
1 |
Maps required task_uri to the Task used to monitor the asynchronous result. |
service-desc |
Applicable representation/context | Machine-readable deployed service description, usually OpenAPI | At least 1 when an operation relation is advertised; otherwise recommended by the HAL RFC, with no fixed maximum specified |
Must describe the applicable deployment. The canonical IRI OpenAPI is appropriate only if it accurately describes that deployment. Grants no authorization. |
curies is a HAL declaration array, not a separately registered IRI domain
relation. It is optional; when the iri: abbreviation is used, declare its
mapping with name: iri, href: https://iri.science/rels/{rel}, and
templated: true. Canonical IRI relation URIs use
https://iri.science/rels/<relation-name>. Neither Resource Type URNs nor target
profile URIs replace these relation identifiers.