Imported from registry/relations/impacts.md at commit 76a4a0c89924.

IRI Link Relation: impacts

Relation URI: https://iri.science/rels/impacts
CURIE: iri:impacts
Status: Provisional
Version: 1.0.0
Source representation type: Facility API Event representation.
Target representation type: DOE-IRI Resource representation identified by the source Event’s resource_uri.
Target resource type: Any registered DOE-IRI resource type (urn:doe-iri:resource:*)

This document defines the iri:impacts relationship used by Facility API Event representations.

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

1. Relationship Metadata

Field Definition
Relationship iri:impacts
Relation URI https://iri.science/rels/impacts
Status provisional
Semantic meaning Identifies the DOE-IRI Resource to which the source Event applies.
Source representation type Facility API Event representation.
Target representation type DOE-IRI Resource representation identified by the source Event’s resource_uri.
Cardinality Exactly 1 target under the current required resource_uri contract.
Target stability Resource representation. The association is stable for an immutable Event.
Authorization affects visibility Yes. A provider MAY omit the relation when the target Resource is not visible to the requester; absence does not generally prove that no target exists.
Target classification Resource
Relationship volatility Stable for an immutable Event; it is not a live assertion about the Resource’s current condition.

2. Semantic Meaning

The iri:impacts relationship identifies the Resource to which an Event applies. It provides HAL navigation to the DOE-IRI Resource representation named by the Event’s legacy resource_uri field.

This relation is source-specific: it means an Event applies to one Resource. It MUST NOT be substituted for iri:may-impact, which identifies Resources within an Incident’s assessed impact scope.

3. Source and Target Representation

The relationship MAY originate only from a Facility API Event representation and MUST target the DOE-IRI Resource representation identified by that Event’s required resource_uri.

The target is a Resource, not an operation entry point or relationship resource.

4. Cardinality

Each Event has exactly one semantic Resource target under the current required resource_uri contract:

Event  -- iri:impacts -->  Resource
  1             1

The HAL relation uses a singular link object. During the additive transition, _links remains optional even though the semantic relationship is exact-one.

5. Static and Dynamic Semantics

The Event-to-Resource association is stable for an immutable Event. It does not by itself state that the Resource is currently degraded, unavailable, or otherwise affected; clients must consult applicable current representations.

6. Authorization and Visibility

Authorization MAY affect Resource discoverability. A provider MAY omit iri:impacts when the target cannot be revealed. The absence of a visible relation does not generally prove that the Event has no Resource target.

7. Compatibility

This relation is additive. The required resource_uri field remains authoritative during migration.

  1. Producers retain resource_uri.
  2. Producers MAY add a singular _links["iri:impacts"] HAL link object.
  3. Whenever both forms are present, the link’s href MUST equal resource_uri.
  4. Consumers SHOULD prefer the advertised relation and MAY fall back to resource_uri.

Removing or changing resource_uri requires a subsequent OpenAPI change.

8. HAL Representation

{
  "resource_uri": "/api/v2/status/resources/pioneer",
  "_links": {
    "iri:impacts": {
      "href": "/api/v2/status/resources/pioneer",
      "profile": "https://iri.science/profiles/status/resource"
    }
  }
}

DOE Integrated Research Infrastructure — Link Relation: impacts