Imported from registry/profiles/status/incident.md at commit 76a4a0c89924.

IRI Status Incident Profile

Profile URI: https://iri.science/profiles/status/incident
OpenAPI type: Incident
Status: Draft
Version: 1.0.0

1. Purpose

This document defines the semantic profile for an IRI Status Incident representation.

The canonical identifier for this profile is:

https://iri.science/profiles/status/incident

An IRI Incident represents a discrete occurrence, planned or unplanned, that actually or potentially affects the availability, performance, integrity, security, or usability of one or more IRI Resources.

An Incident provides a higher-level status record that can group related Events over time and across multiple Resources.

An Incident is distinct from:

a Resource, which represents compute, storage, network, service, or other infrastructure;
an Event, which represents an occurrence associated with a Resource at a particular point in time;
dynamic Resource state, which represents the current operational condition of a Resource.

The normative structural definition of an Incident representation is provided by the IRI Facility API OpenAPI specification. This profile supplements that schema with application-level semantics and interoperability requirements.

2. Profile Semantics

An IRI Incident represents a condition, activity, maintenance period, outage, reservation, or other occurrence that may affect one or more Resources.

An Incident MAY:

apply to one Resource or multiple Resources;
contain zero or more associated Events;
represent planned or unplanned activity;
describe an occurrence that has ended or one for which no end time has yet been recorded.

The existence of an Incident does not necessarily mean that every associated Resource is unavailable.

The status, temporal properties, associated Events, affected Resources, and resolution information together describe the Incident.

Clients SHOULD use the relationships advertised by the Incident representation to discover associated Events and potentially impacted Resources rather than constructing API paths from Incident or Resource identifiers.

3. Structural Contract

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

The current Incident schema defines the following properties:

Property	Required	Semantic purpose
`id`	Yes	Stable identifier for the Incident.
`name`	No	Human-readable name of the Incident.
`description`	No	Human-readable description of the Incident.
`last_modified`	Yes	Time at which the Incident representation was last modified.
`status`	Yes	Current status associated with the Incident.
`start`	Yes	Time at which the Incident began or is scheduled to begin.
`end`	No	Time at which the Incident ended or is scheduled to end.
`type`	Yes	Classification of the Incident.
`resolution`	Yes	Current resolution state of the Incident.
`self_uri`	Yes	Canonical API URI of the Incident representation.
`event_uris`	Yes	URIs identifying Events associated with the Incident.
`resource_uris`	Yes	URIs identifying Resources that may be impacted by the Incident.

The OpenAPI schema is authoritative for:

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

This profile is authoritative for additional semantic and interoperability conventions associated with those properties and their corresponding hypermedia relationships.

4. Incident Identity

The id property identifies the Incident.

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

Clients MUST treat id as an opaque identifier unless a separate IRI specification explicitly defines internal semantics for that identifier.

Clients MUST NOT construct API URLs by combining the Incident identifier with assumed path templates.

For example, a client MUST NOT assume that an Incident having:

{
  "id": "maintenance-1234"
}

can necessarily be retrieved by constructing:

/api/v2/status/incidents/maintenance-1234

The canonical API location of an Incident representation MUST instead be determined from an advertised URI or hypermedia link.

5. Incident Type

The type property classifies the nature of the Incident.

The current IRI Facility API defines the following values:

Value	Meaning
`planned`	The Incident represents planned activity.
`unplanned`	The Incident represents unplanned activity.
`reservation`	The Incident represents a reservation-related occurrence.

The Incident type describes the nature of the occurrence and MUST NOT by itself be interpreted as indicating Resource availability or Incident resolution state.

For example:

{
  "type": "planned"
}

indicates planned activity but does not establish whether associated Resources are currently available, degraded, or unavailable.

6. Status and Resolution

6.1 `status`

The status property represents the current status associated with the Incident.

The current IRI Facility API defines:

up
down
degraded
unknown

The Incident status characterizes the Incident’s current operational effect or represented status condition.

The status of an Incident MUST NOT automatically be interpreted as the status of every Resource identified by the Incident.

For example, an Incident affecting multiple Resources MAY represent an overall degraded condition even when individual Resources have different current states.

Clients requiring authoritative current Resource status SHOULD retrieve the affected Resource representations and their applicable state information.

6.2 `resolution`

The resolution property identifies the current resolution state of the Incident.

The current IRI Facility API defines:

unresolved
cancelled
completed
extended
pending

The resolution state describes the disposition or resolution progress of the Incident.

status and resolution represent different concepts.

For example:

{
  "status": "degraded",
  "resolution": "pending"
}

indicates an Incident whose represented operational condition is degraded and whose resolution is pending.

Clients MUST NOT derive one property solely from the value of the other.

7. Temporal Semantics

7.1 `start`

start identifies when the Incident began or is scheduled to begin.

The property is required.

For example:

{
  "start": "2026-08-17T14:00:00Z"
}

7.2 `end`

end identifies when the Incident ended or is scheduled to end.

The property is optional and nullable.

For example:

{
  "end": "2026-08-17T18:00:00Z"
}

An absent or null end value indicates only that an end time is not represented.

Clients MUST NOT infer solely from a missing or null end value that an Incident is currently active.

Likewise, the presence of an end value MUST NOT independently determine the Incident’s current status or resolution.

7.3 Incident Lifetime

The combination of:

start
end
status
resolution
type

provides temporal and lifecycle information about an Incident.

This profile does not currently define a complete state-transition model between status, resolution, start, and end.

Implementations MUST NOT invent additional mandatory lifecycle transitions that are not defined by the applicable IRI specification.

A future revision of this profile MAY define additional lifecycle invariants if adopted by IRI.

8. Incident Relationships

An Incident has two principal relationships represented by the current OpenAPI model:

event_uris
resource_uris

These relationships have different semantics.

8.1 Incident to Event

event_uris identifies Events associated with the Incident.

The registered IRI hypermedia relation is:

iri:has-event

with canonical relation URI:

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

Conceptually:

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

An Event linked through iri:has-event is part of the represented Incident’s event history or grouping.

8.2 Incident to Resource

resource_uris identifies Resources that may be impacted by the Incident.

The registered IRI hypermedia relation is:

iri:may-impact

with canonical relation URI:

https://iri.science/rels/may-impact

Conceptually:

Incident  -- iri:may-impact -->  Resource
   1                0..*

The may-impact semantics are intentional.

The existence of the relationship MUST NOT be interpreted as proof that the target Resource:

is currently unavailable;
is currently degraded;
has experienced an outage;
will necessarily be affected;
has the same status as the Incident.

Clients requiring authoritative Resource state SHOULD follow the Resource relationship and inspect the applicable Resource and state representations.

9. Hypermedia Representation

When represented using HAL, an Incident SHOULD advertise its associated Events and potentially impacted Resources through _links.

For example:

{
  "id": "inc-1234",
  "name": "Scheduled filesystem maintenance",
  "description": "Maintenance affecting access to the scratch filesystem.",
  "last_modified": "2026-08-17T15:30:00Z",
  "status": "degraded",
  "type": "planned",
  "start": "2026-08-17T14:00:00Z",
  "end": "2026-08-17T18:00:00Z",
  "resolution": "pending",

  "_links": {
    "self": {
      "href": "https://api.example.org/api/v2/status/incidents/inc-1234",
      "type": "application/hal+json",
      "profile": "https://iri.science/profiles/status/incident"
    },

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

    "iri:has-event": [
      {
        "href": "https://api.example.org/api/v2/status/events/event-101",
        "title": "Maintenance started",
        "type": "application/hal+json",
        "profile": "https://iri.science/profiles/status/event"
      },
      {
        "href": "https://api.example.org/api/v2/status/events/event-102",
        "title": "Filesystem entered degraded state",
        "type": "application/hal+json",
        "profile": "https://iri.science/profiles/status/event"
      }
    ],

    "iri:may-impact": [
      {
        "href": "https://api.example.org/api/v2/status/resources/orion-scratch",
        "title": "Orion Scratch Filesystem",
        "type": "application/hal+json",
        "profile": "https://iri.science/profiles/status/resource"
      }
    ]
  }
}

In this representation:

self identifies the Incident representation itself;
the profile on self identifies the IRI Status Incident Profile;
iri:has-event identifies Events associated with the Incident;
iri:may-impact identifies Resources that may be impacted by the Incident;
each href identifies an actual target representation;
type identifies the expected media type of the target representation.

A target link MAY additionally include a profile when a registered IRI representation profile exists for that target representation.

The relation URI and representation profile URI serve different purposes and MUST NOT be treated as interchangeable identifiers.

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-event

expands to:

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

and:

iri:may-impact

expands to:

https://iri.science/rels/may-impact

The canonical relation documents define the normative semantics of those relationships.

This Incident profile MUST NOT redefine those link-relation semantics.

11. Relationship to Existing URI Properties

The current IRI Facility API OpenAPI schema defines:

self_uri
event_uris
resource_uris

These properties expose resource URIs directly in the Incident representation.

When the IRI HAL hypermedia model is used, the corresponding relationships SHOULD be represented through _links:

self_uri
    ↓
_links.self

event_uris
    ↓
_links["iri:has-event"]

resource_uris
    ↓
_links["iri:may-impact"]

For example:

{
  "self_uri": "https://api.example.org/api/v2/status/incidents/inc-1234",

  "event_uris": [
    "https://api.example.org/api/v2/status/events/event-101",
    "https://api.example.org/api/v2/status/events/event-102"
  ],

  "resource_uris": [
    "https://api.example.org/api/v2/status/resources/orion-scratch"
  ],

  "_links": {
    "self": {
      "href": "https://api.example.org/api/v2/status/incidents/inc-1234",
      "profile": "https://iri.science/profiles/status/incident"
    },

    "iri:has-event": [
      {
        "href": "https://api.example.org/api/v2/status/events/event-101",
        "profile": "https://iri.science/profiles/status/event"
      },
      {
        "href": "https://api.example.org/api/v2/status/events/event-102",
        "profile": "https://iri.science/profiles/status/event"
      }
    ],

    "iri:may-impact": [
      {
        "href": "https://api.example.org/api/v2/status/resources/orion-scratch",
        "profile": "https://iri.science/profiles/status/resource"
      }
    ]
  }
}

During the compatibility period:

Producers retain the required event_uris and resource_uris properties.
Producers MAY additionally expose _links["iri:has-event"] and _links["iri:may-impact"].
Whenever both forms are present, event_uris and _links["iri:has-event"] MUST identify the same targets, disregarding order.
Whenever both forms are present, resource_uris and _links["iri:may-impact"] MUST identify the same targets, disregarding order.
Consumers SHOULD prefer advertised hypermedia relations and MAY fall back to the corresponding URI-valued properties.
Removing or changing the existing URI properties requires a separate OpenAPI schema revision.
self_uri remains authoritative under the current OpenAPI contract until changed by an approved schema revision.

Clients implementing the HAL representation SHOULD use advertised _links for navigation rather than constructing URLs from identifiers.

12. Media Type

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

When an Incident is represented using HAL JSON, the representation SHOULD use:

application/hal+json

and MAY identify this profile where appropriate:

https://iri.science/profiles/status/incident

The profile URI does not replace the media type.

The media type identifies how the representation is encoded; the profile identifies the additional IRI Incident semantics applied to that representation.

13. Static and Dynamic Semantics

An Incident is a dynamic status-domain representation whose properties MAY change during its lifetime.

Properties that may change include:

last_modified
status
end
resolution
event_uris
resource_uris

Changes to associated Events or potentially impacted Resources MAY cause the Incident representation to change.

Clients SHOULD NOT assume that an Incident representation retrieved previously still represents current Incident state.

The Incident’s last_modified property provides the representation’s modification timestamp according to the IRI Facility API contract.

The existence of an Incident relationship MUST NOT be treated as proof of current Resource availability or unavailability.

Current Resource state SHOULD be obtained from the applicable Resource or state representation.

14. Authorization and Visibility

Authorization MAY affect information visible through an Incident representation.

A provider MAY omit:

Events;
impacted Resources;
descriptive information;
relationships;
other information

when the requester is not authorized to discover that information, subject to the requirements of the applicable OpenAPI schema.

The absence of an Event or Resource relationship MUST NOT necessarily be interpreted as proof that the relationship does not exist.

Where legacy URI properties and corresponding HAL relationships are both returned, they MUST remain consistent with each other.

Clients SHOULD treat the representation as the set of Incident information visible to the authenticated requester.

15. Conformance

A representation conforms to the IRI Status Incident Profile when:

it conforms to the applicable IRI Facility API Incident schema;
its properties are interpreted according to the semantics defined by the IRI Facility API and this profile;
Incident identifiers are treated as identifiers rather than URL templates;
associated Events are discoverable through event_uris or iri:has-event;
potentially impacted Resources are discoverable through resource_uris or iri:may-impact;
IRI-specific link relations use the canonical IRI relation namespace;
profile URIs identify representation semantics and are not used as substitutes for link-relation identifiers;
when both event_uris and _links["iri:has-event"] are present, they identify the same targets;
when both resource_uris and _links["iri:may-impact"] are present, they identify the same targets;
clients are not required to infer or construct related-resource 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/status/incident

The profile URI is a stable semantic identifier.

Repository paths, GitHub URLs, OpenAPI document locations, 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.

Changes that materially alter the interpretation or processing semantics of the Incident 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 — Status Incident Profile