Imported from registry/relations/submit-job.md at commit 76a4a0c89924.

IRI Link Relation: submit-job

Relation URI: https://iri.science/rels/submit-job
CURIE: iri:submit-job
Status: Provisional
Version: 1.0.0
Change controller: IRI technical subcommittee
Source representation type: DOE-IRI Resource representation
Source resource type: urn:doe-iri:resource:compute:system
Target representation type: Resource-specific job-submission operation entry point
OpenAPI operation: POST /api/v2/compute/job/{resource_id} (operationId: launchJob)

This document defines the iri:submit-job operation-affordance relationship used by DOE-IRI compute-system Resource representations.

The canonical relation URI is https://iri.science/rels/submit-job. With the canonical IRI CURIE template https://iri.science/rels/{rel}, iri:submit-job expands to that URI. The relation URI identifies the link-relation semantics and is distinct from any target representation profile.

1. Relationship Metadata

2. Semantic Meaning

The iri:submit-job relationship advertises the operation entry point through which a client may submit a job for the source compute system. The source MUST be a DOE-IRI Resource whose exact resource_type is urn:doe-iri:resource:compute:system. Eligibility is not inherited by generic compute, compute-node, CPU, or GPU Resource types.

The relation identifies navigation to an applicable affordance. It does not itself specify the HTTP method or request contract, grant permission, prove current capacity, guarantee schedulability, or replace the governing OpenAPI operation contract.

3. Source, Target, and Operation Context

The relationship MAY originate only from:

urn:doe-iri:resource:compute:system

The target is a Resource-specific operation entry point, not a Resource representation or relationship Resource. The producer MUST bind resource_id to the represented compute system’s adapter context. Because resource_id is the operation’s only path variable, the advertised link is concrete rather than templated.

The adapter MUST implement the mapped operation for that context. A producer MUST NOT synthesize this link solely because "compute" appears in supported_endpoints. When supported_endpoints is present on the source Resource, advertising iri:submit-job requires "compute" in that array; the reverse implication does not apply. Authorization-suppressed omission does not make a retained "compute" category inconsistent.

A representation advertising iri:submit-job MUST also advertise at least one applicable service-desc link whose deployed OpenAPI description contains the binding in Section 7. The operation link MUST NOT carry an IRI representation profile.

4. Cardinality

A compute-system Resource MAY advertise zero or one applicable job-submission entry point:

Compute System  -- iri:submit-job -->  Job-submission operation entry point
       1                    0..1

The HAL relation uses a singular link object when supplied.

5. Stability and Availability

The relationship describes a configured applicable operation affordance. Its presence SHOULD remain stable across ordinary changes in capacity, queue state, health, allocation balance, and schedulability. It may change when the facility configures or withdraws the adapter operation or changes what is visible to the requester.

The relation does not prove that the target is currently healthy, reachable, or available. Clients MUST use the governing OpenAPI contract and handle ordinary invocation failures.

6. Authorization, Visibility, and Omission

Authorization MAY affect visibility of the operation affordance. A provider MAY omit iri:submit-job when the requester is not authorized to discover or use the entry point. Conversely, link visibility does not grant permission and does not guarantee that a submission will be accepted.

Omission means only that the affordance is not advertised in this representation. It does not prove that the compute system has no job-submission operation, that the operation is unsupported by every adapter, or that the requester can never become authorized.

Links MUST NOT contain credentials or secrets. A client MUST NOT automatically forward credentials to an unrelated origin solely because an operation link or service description names it.

7. OpenAPI Contract and Binding

The current operation mapping is:

POST /api/v2/compute/job/{resource_id}
operationId: launchJob
x-iri-relation: ["https://iri.science/rels/submit-job"]

OpenAPI remains authoritative for the method, path parameter semantics, JobSpec request body, responses, errors, and security behavior. Clients MUST follow the advertised target and the applicable deployed OpenAPI description; they MUST NOT construct a URL or infer an HTTP method from the relation name. The canonical relation URI, rather than operationId, is the machine-readable binding key.

8. HAL Representation

{
  "id": "system-a",
  "resource_type": "urn:doe-iri:resource:compute:system",
  "supported_endpoints": ["compute"],
  "_links": {
    "curies": [
      {
        "name": "iri",
        "href": "https://iri.science/rels/{rel}",
        "templated": true
      }
    ],
    "iri:submit-job": {
      "href": "https://api.example.org/api/v2/compute/job/system-a"
    },
    "service-desc": {
      "href": "https://api.example.org/openapi.json",
      "type": "application/vnd.oai.openapi+json;version=3.1"
    }
  }
}

9. Governing Sources

• Resource operation-affordance RFC
• IRI v2 compute OpenAPI
• Common Resource profile
• Compute-system Resource Definition Profile

DOE Integrated Research Infrastructure — Link Relation: submit-job