A first look at the draft IRI Facility API 2.0

The draft v2 model gives facilities a common way to describe resources, relationships, and operations so people, workflows, and authorized AI agents can explore infrastructure without hard-coding each site’s layout.

DOE research facilities are different by design. A leadership computing center, a light source, a data service, and a cloud platform should not all work the same way. That diversity becomes harder to manage, though, when one scientific workflow needs to move among them.

The draft Integrated Research Infrastructure (IRI) Facility API 2.0 is now available for preview and implementation feedback. Its job is not to standardize how every facility operates. It gives facilities a shared way to say what they provide, how their resources fit together, and which operations apply to those resources.

A resource that can explain itself

IRI 1.0 established a common representation for facility resources. Version 2.0 makes those descriptions richer through three parts that work together:

• resource_type says what a resource is. Registered DOE-IRI Uniform Resource Names (URNs) distinguish compute systems, compute nodes, GPUs, storage systems, filesystems, mounts, data-transfer services, and other resource classes. New types can be added without turning the main schema into a closed list.
• attributes carries details for that type. A compute system can describe execution capabilities; a filesystem can describe its scope, protocol, or storage tier. Resource Definition Profiles give those fields a shared meaning. A generic client can still carry unfamiliar attributes as opaque data.
• _links describes connections and applicable operations. Registered relations can show that a storage system provides a filesystem or that a filesystem has a mount. Other links can advertise operations such as job submission or directory listing.

Instead of receiving a flat inventory, a client can explore a capability graph. It might move from a storage system to a filesystem, then to a mount and the compute system that consumes it. It can find an applicable job-submission operation and then locate the service description that explains how to call it.

Discover first, act second

An IRI 2.0 client does not have to build URLs from resource names or assume that every facility puts the same operation in the same place. A typed link points to an operation that applies to a resource. The facility’s OpenAPI document supplies the HTTP method, inputs, responses, errors, and security requirements.

“Applicable” is deliberate wording. A link does not grant authorization or promise that capacity is available. The facility still controls access and can tailor what an authenticated user is able to discover.

This pattern works for a conventional workflow engine as well as an AI agent. Either can begin with a scientific need, search for resources by semantic type, read the relevant profile, follow only operations the facility advertises, and validate a request against the machine-readable API contract before sending it.

Shared terms, local decisions

IRI 2.0 splits the contract into parts so that the structure and the scientific meaning can evolve without becoming tangled:

• OpenAPI 3.1 defines request and response structure.
• The IRI Registry governs resource types, controlled values, representation profiles, and link relations.
• Resource Definition Profiles explain type-specific attributes and relationships.
• The RFC process records design proposals and community decisions.
• Each facility’s published OpenAPI document describes what its running service supports.

This leaves room for detailed domain information without forcing every concept into one universal object. It also gives clients a sensible fallback. If a generic client does not recognize a specialized type or attribute, it can still process the common resource fields instead of failing outright.

Adoption can happen one facility at a time

IRI 1.0 and 2.0 remain separate API lines. A facility can adopt v2 on its own schedule, and its operational service description remains the authority for the endpoints and security mechanisms it has implemented. The common contract defines how systems interoperate; it does not mean every facility has enabled every operation.

That flexibility is also what lets the model work across very different backends. An adapter can map IRI operations to an HPC scheduler, a Kubernetes platform, a storage service, or cloud infrastructure without changing the language seen by a researcher-facing client.

The word “draft” matters here. The published v2 contract, profiles, and registry material are open for review and implementation work; this preview should not be read as a claim of uniform production deployment across DOE facilities.

Explore the draft

The published IRI v2 OpenAPI draft, IRI representation profiles, and registered link relations are available online. The specification, registry, reference implementation, and examples are developed openly in the DOE IRI GitHub organization.

At SC26, IRI 2.0: A Common Language for DOE Research Infrastructure will show these descriptions supporting human-driven workflows and AI agents. Join John MacAuley and Justas Balcas at DOE booth #4829 on Monday, November 16 at 7:00 p.m. CST (Station 1) or Wednesday, November 18 at 1:00 p.m. CST (Station 2).