Examples

These examples illustrate how the IRI concepts fit together. They are not normative schemas.

For exact fields, required properties, relation semantics, and allowed identifiers, consult the applicable specification, OpenAPI contract, and registry.

{
  "resource_id": "frontier",
  "resource_type": "urn:doe-iri:resource:compute:system",
  "_links": {
    "self": {
      "href": "https://facility.example/api/v2/status/resources/frontier"
    },
    "iri:has-mount": {
      "href": "https://facility.example/api/v2/status/resources/frontier-orion-scratch-mount",
      "title": "Frontier mount of Orion scratch storage",
      "type": "application/hal+json",
      "profile": "https://iri.science/profiles/resource-definition/storage/mount"
    }
  }
}

Traversal:

compute resource
      │
      │ iri:has-mount
      ▼
mount relationship resource

The client follows the advertised href; it does not construct the mount URL from the compute resource ID.

Example 2: Discovering the API description 

{
  "_links": {
    "service-desc": {
      "href": "https://facility.example/openapi.json",
      "type": "application/vnd.oai.openapi+json;version=3.1"
    }
  }
}

A client that needs the machine-readable API contract can retrieve the advertised service description.

Example 3: Resource classification and profile interpretation 

resource_type
   │
   └── urn:doe-iri:resource:compute:system
                     │
                     ▼
          Resource Definition semantics

The Resource Type URN and Resource Definition Profile are separate identifiers with separate purposes.

See IRI Registry.

Example 4: Portable client behavior

Avoid client logic like:

job_url = facility_base + "/api/v2/compute/jobs/" + resource_id

The problem is not the programming language; the problem is assuming a routing convention that is not part of the discovered representation.

Prefer the conceptual flow:

resource = get_resource(resource_uri)
operation = find_registered_relation(resource, desired_relation)
target_uri = operation["href"]

The exact relation names and operation semantics must come from the governing IRI specification and registry.

Example 5: Cross-facility traversal 

Facility A representation
        │
        │ registered relation
        ▼
advertised target
        │
        ▼
Facility or service endpoint
        │
        ├── target representation
        └── service-desc ──► OpenAPI

Because the URI is advertised, the target does not need to share the same hostname or path layout as the source representation.

Example 6: Retrying a job submission

For a deployment that has enabled the Python reference implementation’s idempotency support, generate a UUID before submitting a job and keep the same key and payload if the request times out. Given a trusted SUBMIT_URL obtained from iri:submit-job, an ACCESS_TOKEN for that facility, and a valid job specification saved as job-spec.json, an illustrative request is:

IDEMPOTENCY_KEY='"8e03978e-40d5-43e8-bc93-6894a57f9324"'
curl --include --request POST "$SUBMIT_URL" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-binary @job-spec.json

Choose your own UUID for each logical submission and include any additional facility-required request context. After a timeout, repeat the request with the same URL, key, user, and payload. A completed matching retry returns the cached Job response with Idempotency-Key-Reply: hit. A request still in progress returns 409, so wait before retrying.

See Idempotency-Key and Job Retries for complete submit and update examples, configuration requirements, error handling, and retention limits. Confirm deployment support before relying on this optional behavior.

Authoritative references