IRI 2.0
IRI Facility API Specification 2.0 is the current v2 development line in the documentation repository.
The repository currently labels the v2 specification as Draft.
Authoritative sources
OpenAPI version
The v2 documentation uses OpenAPI 3.1. The repository identifies compatibility with JSON Schema 2020-12 as a reason for that choice.
Canonical IRI v2 OpenAPI
The authoritative repository artifact for the canonical IRI v2 API contract is
specification-v2/openapi/all_spec_v2.yaml.
Its intended canonical publication URI is:
https://iri.science/api/v2/openapi.json
This is the canonical IRI contract, not a description of every facility’s
operational deployment. Implementations publish deployment-specific OpenAPI
documents containing their actual servers, security requirements, implemented
operations, and other applicable details. Their service-desc links normally
identify those deployed documents.
Relationship to v1
The repository maintains v1 and v2 independently:
The v2 README currently notes that some conceptual and design documentation remains shared with v1 until v2-specific documents diverge.
Important v2 design areas
Current v2 design work includes several complementary areas:
Resource classification
Resources use registered Resource Type identifiers.
See:
Type-specific semantics
Resource Definition Profiles provide type-specific semantics associated with resource_type.
See:
Hypermedia relationships
HAL-style links provide a mechanism for advertising relationships and navigation.
See:
Resource operation affordances
The approved Phase 1 operation-affordance migration maps all 25
Resource-scoped Compute, Filesystem, and Storage operations in the reviewed v2
contract to registered iri:* relations. Applicable links identify operation
entry points; the deployed OpenAPI Operation Objects bind those relations with
x-iri-relation and define methods, inputs, responses, errors, and security.
Phase 1 is additive. Resource.supported_endpoints remains in the v2 schema
and has not been deprecated or removed.
See:
Container execution capability discovery
The approved container-capability RFC adds optional container_runtimes data
to the Compute System Resource Definition Profile. It describes configured
runtime, image-format, acquisition, registry, privilege, accelerator, MPI,
build, and architecture behavior. It adds no image-acquisition endpoint and
does not change the existing job Container schema.
For container_runtimes, omission means structured capability information is
unknown, an empty array explicitly means container execution is unsupported,
and a non-empty array describes supported execution paths.
See the Container Execution Capability Discovery RFC.
IRI identifier governance
IRI URNs are governed through a registry model rather than being embedded as closed OpenAPI enumerations that must be revised for every taxonomy change.
See:
Proposals still under review
The Normalized Queueing Policy Discovery RFC
proposes queue information in Resource attributes. The
API Root Discovery and Implementation Conformance RFC
proposes a HAL API root, deployment-level conformance identifiers, and API-area
entry-point relations. Both remain Draft / Proposed; their identifiers and
behaviors are not canonical until the required registry and OpenAPI work is
adopted.
How to use this site with v2
Use this site to understand the model and implementation flow. Use the repository sources above whenever exact schema, requirement language, registered identifiers, or conformance behavior matters.