Imported from registry/profiles/README.md at commit 76a4a0c89924.

IRI Representation Profiles

This directory contains the semantic profiles used by the DOE Integrated Research Infrastructure (IRI) Facility API.

Profiles define semantic and interoperability conventions for IRI representations. They supplement the structural API contract defined by OpenAPI and do not replace it.

The canonical profile namespace is:

https://iri.science/profiles/...

Repository paths such as registry/profiles/... and GitHub URLs are documentation locations, not profile identifiers.

Profile Model

IRI uses two related kinds of profiles in this directory:

Representation Profiles
    Define semantic conventions for independently meaningful API representations.

Resource Definition Profiles
    Define additional type-specific semantics for an IRI Resource selected by
    resource_type.

For an ordinary independently meaningful representation:

OpenAPI schema
    ↓
Representation Profile
    ↓
semantic and interoperability conventions

For a typed IRI Resource:

OpenAPI Resource schema
    ↓
https://iri.science/profiles/status/resource
    common Resource semantics
    ↓
resource_type
    ↓
registered Resource Type URN
    ↓
https://iri.science/profiles/resource-definition/<domain>/<type>
    additional type-specific semantics

A Resource Definition Profile supplements the common Resource profile; it does not replace it and does not define a separate Resource Definition API object.

IRI v2 does not require separate Resource Definition and Resource State representations, endpoints, or conformance models.

Sources of Truth

Authority is resolved by concern.

A profile MUST NOT silently override the OpenAPI structural contract, URN registry, or registered link-relation semantics.

Current Profiles

Facility

Status

Account and Allocation

Compute and Task

Profiles, API Contracts, and Service Descriptions

These authorities serve different purposes:

Representation profile
    semantic representation contract

Link relation
    relationship or applicability semantics

Canonical IRI OpenAPI
    portable structural and API contract

Deployment OpenAPI
    contract for an actual running service

service-desc
    discovery mechanism for the applicable deployed service description

The intended canonical publication URI for the IRI v2 OpenAPI contract is https://iri.science/api/v2/openapi.json. An independently deployed facility’s service-desc normally identifies its deployment OpenAPI, which can state its actual servers, security requirements, and implemented operations. The canonical OpenAPI does not become a representation profile, and profiles do not redefine OpenAPI conformance.

Resource Definition Profiles

Resource Definition Profiles specialize the common IRI Resource representation according to a registered resource_type.

The canonical URI form is:

https://iri.science/profiles/resource-definition/<domain>/<type>

The authoritative mapping between Resource Type URNs and Resource Definition Profiles is maintained in:

../urns/resource-types.md

Clients MUST NOT assume that a profile URI can be derived mechanically from a Resource Type URN.

Compute Resource Definitions

Storage Resource Definitions

Service Resource Definitions

Identifier Roles

The following identifiers answer different questions and MUST NOT be used interchangeably.

Resource Type URN
    WHAT kind of Resource is this?

Representation Profile URI
    WHAT semantic representation contract applies?

Link Relation
    WHY is the target related or applicable?

Instance URI / href
    WHERE is the target representation or operation entry point?

For example:

urn:doe-iri:resource:storage:mount
    Resource Type

https://iri.science/profiles/resource-definition/storage/mount
    Resource Definition Profile

iri:has-mount
    Link Relation

https://api.example.org/api/v2/status/resources/frontier-orion-scratch-mount
    Target instance URI

HAL Link Target Profiles

In a HAL Link Object, profile identifies the semantic profile of the link target.

The four parts of a typical IRI HAL link answer different questions:

relation
    WHY is the target linked?

href
    WHERE is the target?

type
    HOW is the target represented?

profile
    WHAT semantic representation contract applies to the target?

Example:

{
  "_links": {
    "iri:has-mount": {
      "href": "https://api.example.org/api/v2/status/resources/frontier-orion-scratch-mount",
      "title": "Frontier mount of Orion scratch filesystem",
      "type": "application/hal+json",
      "profile": "https://iri.science/profiles/resource-definition/storage/mount"
    }
  }
}

The profile value above describes the target mount representation. It does not identify the iri:has-mount relation or the source representation.

When the target is an IRI representation with a known canonical profile, documentation examples SHOULD include that target profile.

Important exceptions include:

• curies, which is HAL metadata;
• service-desc, whose target is normally a service description such as OpenAPI rather than an IRI representation;
• ordinary external help targets;
• operation-affordance targets such as iri:submit-job, whose target is an operation entry point rather than a Job representation.

For polymorphic relations such as iri:attached-to and iri:hosted-on, the profile MUST be chosen from the actual target type shown by the example. The registered relation definition is authoritative for target classification.

For _links.self, use the profile applicable to the represented object. In a Resource Definition Profile example, use that representation’s most-specific Resource Definition Profile.

What Belongs in a Profile

Representation profiles define semantic and interoperability conventions such as:

• interpretation of OpenAPI properties;
• identity semantics;
• relationships and navigation;
• compatibility between legacy URI properties and HAL links;
• authorization-sensitive visibility;
• processing expectations;
• conformance requirements;
• profile identification and versioning.

Resource Definition Profiles may additionally define:

• type-specific attributes;
• controlled vocabularies used by those attributes;
• type-specific relationships;
• applicable operation affordances;
• interpretation and conformance requirements for the selected Resource Type.

Profiles SHOULD reference the authoritative URN and link-relation registries instead of duplicating their registration authority.

What Does Not Belong in a Profile

Profiles SHOULD NOT:

• redefine OpenAPI property types, requiredness, or nullability;
• independently define the DOE-IRI URN grammar;
• independently register Resource Type or controlled attribute URNs;
• invent iri:* link relations;
• redefine registered link-relation semantics;
• use GitHub or repository paths as canonical profile identifiers;
• invent lifecycle transition rules absent from a governing specification;
• infer API paths from identifiers;
• require a separate Resource Definition / Resource State model in IRI v2.

Not every OpenAPI schema requires a representation profile. Helper schemas, request objects, enums, and nested value objects generally remain OpenAPI-only unless they acquire independent semantic identity or interoperability requirements.

Adding or Updating a Profile

Before adding or modifying a profile:

1. Read the current IRI v2 OpenAPI schema.
2. Read the applicable URN registry entries.
3. Read the applicable link-relation definitions.
4. Read rfc/rfc-hal-links.md when hypermedia is involved.
5. Determine whether the representation warrants an independent profile or is better represented as part of another profile.
6. Use the canonical https://iri.science/profiles/... identifier.
7. Preserve the distinction between structure, semantics, registered identifiers, relations, and instance URIs.
8. Update this README when adding or removing a profile.

Resource Definition Profiles follow the repository guidance in AGENTS.md and the type-specific attribute/profile model defined by:

../../rfc/rfc-type-specific-attributes.md

Related Registry Documentation

• DOE-IRI Registry
• DOE-IRI URN Registry
• Resource Type URNs
• Controlled Attribute URNs
• IRI Link Relation Index
• HAL _links RFC
• Type-Specific Attributes and Resource Definition Profiles RFC

DOE Integrated Research Infrastructure — IRI Representation Profiles