# IRI Link Relation: `has-event`

**Relation URI:** `https://iri.science/rels/has-event`\
**CURIE:** `iri:has-event`\
**Status:** Provisional\
**Version:** 1.0.0<br>
**Source representation type:** Facility API `Incident` representation.<br>
**Target representation type:** Facility API `Event` representation identified by the source Incident's `event_uris`.

This document defines the `iri:has-event` relationship used by Facility API Incident representations.

The canonical relation URI is `https://iri.science/rels/has-event`. With the
canonical IRI CURIE template `https://iri.science/rels/{rel}`, `iri:has-event`
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:has-event` |
| Relation URI | `https://iri.science/rels/has-event` |
| Status | `provisional` |
| Semantic meaning | Identifies Events recorded as part of the source Incident. |
| Source representation type | Facility API `Incident` representation. |
| Target representation type | Facility API `Event` representation identified by the source Incident's `event_uris`. |
| Cardinality | `0..*` targets from an Incident representation. |
| Target stability | API resource representation. Each target identifies a recorded Event. |
| Authorization affects visibility | Yes. The relationship or individual Event targets MAY be omitted when the requester is not authorized to discover them; absence does not generally prove that no Events exist. |
| Target classification | API resource; not a DOE-IRI typed `Resource`, operation entry point, or relationship resource. |
| Relationship volatility | Membership may grow as Events are recorded for the Incident. |

## 2. Semantic Meaning

The `iri:has-event` relationship identifies Events recorded as part of an Incident. It provides navigation to the Event representations named by the Incident's legacy `event_uris` field.

The relationship does not establish a required inverse for every Event, and it does not itself determine an Incident's current status, resolution, or impact scope.

## 3. Source and Target Representation

The relationship MAY originate only from a Facility API `Incident` representation and MUST target Facility API `Event` representations identified by that Incident's `event_uris`.

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

## 4. Cardinality

An Incident MAY identify zero, one, or multiple recorded Events:

```text
Incident  -- iri:has-event -->  Event
   1               0..*
```

The HAL relation uses an array when multiple Event targets are supplied. It does not impose an inverse-cardinality requirement.

## 5. Static and Dynamic Semantics

The membership can grow as Events are recorded. Existing Event identity is not a live status assertion, and clients MUST use the target Event and Incident representations for their current properties.

## 6. Authorization and Visibility

Authorization MAY affect Event discoverability. A provider MAY expose an Incident while omitting individual `iri:has-event` targets that the requester is not authorized to discover. The absence of visible targets does not generally prove that the Incident has no Events.

## 7. Compatibility

This relation is additive. The required `event_uris` array remains authoritative during migration.

1. Producers retain `event_uris`.
2. Producers MAY add `_links["iri:has-event"]` as an array of HAL links.
3. Whenever both forms are present, the link array and `event_uris` MUST identify the same targets, disregarding order.
4. Consumers SHOULD prefer the advertised relation and MAY fall back to `event_uris`.

Removing or changing `event_uris` requires a subsequent OpenAPI change.

## 8. HAL Representation

```json
{
  "event_uris": [
    "/api/v2/status/events/network-maintenance-start",
    "/api/v2/status/events/network-maintenance-complete"
  ],
  "_links": {
    "iri:has-event": [
      { "href": "/api/v2/status/events/network-maintenance-start", "profile": "https://iri.science/profiles/status/event" },
      { "href": "/api/v2/status/events/network-maintenance-complete", "profile": "https://iri.science/profiles/status/event" }
    ]
  }
}
```

---

*DOE Integrated Research Infrastructure — Link Relation: has-event*