Imported from registry/profiles/compute/job.md at commit 76a4a0c89924.

IRI Compute Job Profile

Profile URI: https://iri.science/profiles/compute/job
OpenAPI type: Job
Status: Draft
Version: 1.0.0

1. Purpose

This document defines the semantic profile for an IRI Compute Job representation.

The canonical identifier for this profile is:

https://iri.science/profiles/compute/job

An IRI Job represents a compute job submitted to a compute Resource through the IRI Compute API.

A Job provides identity and execution-state information for submitted work and MAY include the Job Specification associated with that work.

A Job is distinct from:

  • a compute Resource, which represents the compute system on which jobs may be submitted;
  • a Job Specification, which describes the requested execution;
  • a Job Status, which describes the execution state associated with the Job;
  • a Task, which represents asynchronous IRI API operation processing outside the compute-job model;
  • an operation entry point, such as the endpoint advertised through iri:submit-job.

The normative structural definition of a Job representation is provided by the IRI Facility API OpenAPI specification.

This profile supplements that schema with application-level semantics, identity rules, lifecycle interpretation, hypermedia conventions, and interoperability requirements.

2. Profile Semantics

An IRI Job represents a submitted unit of computational work.

A Job is created or identified within the context of a compute Resource.

Conceptually:

Compute Resource
      │
      │ iri:submit-job
      ▼
Job-submission operation
      │
      │ returns
      ▼
     Job

A Job MAY contain:

  • its unique job identifier;
  • its current Job Status;
  • the Job Specification associated with the job.

A Job representation MUST NOT be interpreted as describing the compute Resource itself.

Likewise, the existence of a Job does not establish:

  • that the job is currently executing;
  • that the compute Resource is currently available;
  • that additional jobs may be submitted;
  • that the requester remains authorized to modify the job;
  • that the job’s requested resources remain available.

Those conditions require the applicable current Job, Resource, authorization, scheduler, and API information.

3. Structural Contract

The structural definition of the Job representation is defined by the IRI Facility API OpenAPI Job schema.

The current Job schema defines:

Property Required Semantic purpose
id Yes Identifier of the Job.
status No Current Job Status when supplied.
job_spec No Job Specification associated with the Job when supplied.

The status property MAY be null.

The job_spec property MAY be null.

The OpenAPI schema is authoritative for:

  • property names;
  • JSON data types;
  • required properties;
  • nullable properties;
  • nested Job Status structure;
  • nested Job Specification structure;
  • structural validation;
  • enumerated Job State values.

This profile is authoritative for additional semantic and interoperability conventions associated with the Job representation.

4. Job Identity

The id property identifies the Job.

For example:

{
  "id": "job-12345"
}

The Job identifier MUST be treated as opaque unless another IRI specification explicitly defines additional semantics for the identifier.

Clients MUST NOT assume that the Job identifier encodes:

  • the compute Resource;
  • the scheduler;
  • the submitting user;
  • the Project;
  • the queue;
  • an API path;
  • a globally unique identifier.

For example, a client discovering:

{
  "id": "job-12345"
}

MUST NOT independently construct:

/api/v2/compute/status/perlmutter/job-12345

or:

/api/v2/compute/job/perlmutter/job-12345

unless those URLs are supplied by the governing API contract or advertised through hypermedia.

The Job identifier identifies which Job is represented.

It does not identify where the Job representation is located.

5. Job Status

The status property contains a JobStatus representation when current Job Status information is included.

For example:

{
  "status": {
    "state": "queued",
    "time": 1787072400,
    "message": "Job is waiting in queue"
  }
}

The current Job Status structure contains:

Property Required Semantic purpose
state Yes Current execution state represented by the Job Status.
time No Timestamp associated with the status, represented as seconds since the epoch.
message No Human-readable status information.
exit_code No Process exit code when available.
meta_data No Backend-specific metadata associated with the Job Status.

The status property itself MAY be absent or null in a Job representation.

The absence of Job Status information MUST NOT be interpreted as establishing a particular Job State.

6. Job State

The current IRI Compute API defines the following Job State values:

new
queued
held
active
completed
failed
canceled

A Job Status containing:

{
  "state": "active"
}

indicates that the current Job Status reports the Job in the active state.

The Job State describes execution lifecycle state.

It MUST NOT be interpreted as:

  • Resource health;
  • Resource availability;
  • allocation state;
  • Project state;
  • authorization state.

6.1 State Transitions

The current Job schema defines the set of Job State values but does not define a complete normative Job State transition graph.

Accordingly, this profile does not impose additional mandatory transitions between:

new
queued
held
active
completed
failed
canceled

Implementations MUST NOT infer mandatory transition rules solely from the ordering of these values in the schema.

A future IRI specification MAY define additional Job lifecycle invariants or transition semantics.

7. Job Status Details

7.1 time

The time property identifies the timestamp associated with the Job Status when supplied.

The current OpenAPI representation expresses this value as seconds since the epoch.

For example:

{
  "time": 1787072400
}

The timestamp applies to the represented Job Status.

It MUST NOT automatically be interpreted as:

  • Job submission time;
  • Job start time;
  • Job completion time;
  • Job creation time.

unless the governing API contract or backend semantics explicitly establish that meaning.

7.2 message

message provides human-readable information associated with the Job Status.

For example:

{
  "message": "Job is waiting in queue"
}

Clients MAY display this value to users.

Clients MUST NOT depend on the free-form message string for portable machine processing when an applicable structured property exists.

7.3 exit_code

exit_code contains the process exit code when one is available.

For example:

{
  "state": "completed",
  "exit_code": 0
}

The presence or interpretation of an exit code remains subject to the governing compute implementation and Job Status contract.

Clients MUST NOT assume that an absent exit_code indicates successful or unsuccessful execution.

7.4 meta_data

meta_data contains backend-specific Job Status information.

For example:

{
  "meta_data": {
    "scheduler_id": "1234567"
  }
}

The contents of meta_data are backend-specific unless separately standardized.

Portable clients MUST NOT require particular meta_data members unless another IRI specification defines those members.

Clients SHOULD ignore unrecognized metadata fields.

8. Job Specification

The job_spec property MAY contain the Job Specification associated with the Job.

Conceptually:

Job
 │
 ├── id
 ├── status
 └── job_spec
        │
        ├── executable
        ├── container
        ├── arguments
        ├── directory
        ├── name
        ├── environment
        ├── resources
        ├── attributes
        ├── launcher
        └── other execution parameters

The current V2 Job Specification includes execution-related concepts such as:

executable
container
arguments
directory
name
inherit_environment
environment
stdin_path
stdout_path
stderr_path
resources
attributes
pre_launch
post_launch
launcher

The OpenAPI JobSpec schema is authoritative for the structure and validation of those properties.

8.1 Job Specification as Request and Representation Data

Job submission uses JobSpec as its request representation.

A returned Job MAY include that Job Specification through:

job_spec

The two uses have related but distinct contexts:

JobSpec submitted to operation
       ↓
desired execution specification


Job.job_spec
       ↓
specification represented as associated with the Job

Clients MUST NOT assume that job_spec is present in every returned Job.

The current status-retrieval operation allows Job Specification inclusion to be controlled separately.

8.2 Job Specification Is Not a Job

A Job Specification describes requested execution.

A Job represents submitted work.

For example:

{
  "executable": "/usr/bin/python",
  "arguments": [
    "simulation.py"
  ]
}

is not, by itself, a Job identity.

A Job exists when the Facility’s compute service assigns a Job identity according to the governing API contract.

9. Compute Resource Context

A Job executes within the context of a compute Resource.

The current V2 Compute API identifies the compute Resource through the resource_id path parameter used by Job operations.

For example:

POST /api/v2/compute/job/{resource_id}

PUT /api/v2/compute/job/{resource_id}/{job_id}

GET /api/v2/compute/status/{resource_id}/{job_id}

However, the current Job representation does not contain:

resource_uri

or another URI-valued Resource relationship.

Therefore, this profile does not invent a Job-to-Resource relation. No registered IRI relation currently establishes this Job-to-compute-Resource relationship.

A future IRI relation MAY define an explicit Job-to-compute-Resource relationship.

Until such a relation is registered, clients MUST NOT derive a Resource URI from the Job identifier.

The governing OpenAPI operation context remains authoritative for identifying the compute Resource used by the operation.

10. Job Submission

Job submission is an operation performed against an applicable compute Resource.

The registered operation-affordance relation is:

iri:submit-job

with canonical relation URI:

https://iri.science/rels/submit-job

The source of iri:submit-job is a compute-system Resource having:

resource_type =
urn:doe-iri:resource:compute:system

Conceptually:

Compute-system Resource
          │
          │ iri:submit-job
          ▼
Job-submission operation entry point
          │
          │ POST JobSpec
          ▼
         Job

The iri:submit-job target is the operation entry point, not a Job representation.

The relation identifies where an applicable submission operation is located.

It does not itself specify:

  • the HTTP method;
  • request structure;
  • response structure;
  • authentication;
  • authorization;
  • allocation requirements;
  • queue policy;
  • schedulability.

Those invocation semantics are defined by the governing OpenAPI contract.

11. Hypermedia Representation

When represented using HAL, an independently retrievable Job SHOULD advertise its canonical representation through _links.self.

For example:

{
  "id": "job-12345",

  "status": {
    "state": "active",
    "time": 1787072400,
    "message": "Job is running"
  },

  "job_spec": {
    "executable": "/usr/bin/python",
    "arguments": [
      "simulation.py"
    ],
    "name": "climate-simulation"
  },

  "_links": {
    "self": {
      "href":
        "https://api.example.org/api/v2/compute/status/perlmutter/job-12345",
      "type": "application/hal+json",
      "profile": "https://iri.science/profiles/compute/job"
    },

    "curies": [
      {
        "name": "iri",
        "href": "https://iri.science/rels/{rel}",
        "templated": true
      }
    ],

    "iri:get-job": {
      "href":
        "https://api.example.org/api/v2/compute/status/perlmutter/job-12345"
    },

    "iri:update-job": {
      "href":
        "https://api.example.org/api/v2/compute/job/perlmutter/job-12345"
    },

    "iri:cancel-job": {
      "href":
        "https://api.example.org/api/v2/compute/cancel/perlmutter/job-12345"
    },

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

In this representation:

  • self identifies the canonical Job representation;
  • profile identifies the IRI Compute Job semantic profile;
  • iri:get-job, iri:update-job, and iri:cancel-job identify optional operation entry points applicable to this fully bound Job context;
  • service-desc identifies the applicable deployed OpenAPI description, which contains the matching canonical x-iri-relation bindings for the advertised operations.

The operation links do not carry an IRI representation profile because their targets are operation entry points rather than Job representations. Both the compute Resource identifier and Job identifier are producer-bound in every operation href shown.

The example self URI reflects the current V2 retrieval operation.

Clients MUST use the advertised link rather than reconstructing it from id or other Job properties.

12. Relationship to Existing URI Properties

The current V2 Job schema does not define:

self_uri
resource_uri

or other URI-valued relationship properties.

Therefore, unlike several Facility, Status, and Account representations, there is no legacy URI property requiring HAL compatibility mapping.

A HAL-enabled producer SHOULD advertise:

_links.self

when the Job is independently retrievable.

This allows canonical Job navigation to be introduced without adding another transitional *_uri property solely for hypermedia migration.

The current Job schema also lacks an explicit compute-Resource URI.

This profile therefore does not define a compatibility mapping for a Job-to-Resource relationship.

13. Job Operations

The following registered operation-affordance relations MAY originate from a Job representation when the operation is applicable and visible to the requester:

iri:get-job
iri:update-job
iri:cancel-job

The registered relation definitions own their complete semantics, source eligibility, cardinality, stability, authorization behavior, and omission rules. This profile does not redefine them.

Standard self remains the canonical retrieval relation for a Job. iri:get-job is an optional operation affordance and does not replace or redefine self, even when both links have the same target URI.

Every Job-source operation link MUST have both resource_id and job_id bound by the producer. The producer MUST retain the compute Resource operation context because clients cannot infer a Resource identifier from the Job identifier. A Job-source link MUST NOT leave either identifier as a URI-template variable.

iri:update-job and iri:cancel-job MAY be omitted when the operation is not applicable to the selected Job’s lifecycle state. Presence advertises an applicable entry point but grants no permission and guarantees no successful invocation.

The following registered relations remain compute-system Resource sourced and MUST NOT originate from a Job representation:

iri:submit-job
iri:query-jobs

When a Job advertises any operation-affordance relation, it MUST also advertise at least one applicable service-desc link. The deployed OpenAPI description identified by that link MUST contain the matching canonical x-iri-relation binding. OpenAPI remains authoritative for methods, parameters, request and response schemas, errors, and security requirements.

Operation-affordance links MUST NOT carry an IRI representation profile. Their absence means only that the operation is not advertised in the current representation; it does not prove that the operation is unsupported everywhere or permanently unavailable.

14. Static and Dynamic Semantics

A Job combines relatively stable identity with dynamic execution state.

Relatively stable information includes:

id

The following information is dynamic:

status

The associated job_spec is generally derived from the Job’s execution specification but MAY be affected by supported Job update operations.

Clients MUST NOT assume that a previously retrieved Job Status remains current.

For example:

{
  "status": {
    "state": "queued"
  }
}

may later become:

{
  "status": {
    "state": "active"
  }
}

or another state permitted by the governing Job implementation.

A Job representation SHOULD therefore be treated as a representation of Job information at retrieval time rather than an immutable execution-state record.

Historical execution information, where supported, remains governed by the applicable compute API operation.

15. Authorization and Visibility

Job representations and Job operations are authorization-sensitive.

A provider MAY restrict:

  • whether a Job is visible;
  • whether Job Status is visible;
  • whether the Job Specification is visible;
  • whether backend metadata is visible;
  • whether update operations are permitted;
  • whether other Job operations are permitted.

A provider MAY omit iri:get-job, iri:update-job, or iri:cancel-job based on authorization and, where applicable, the selected Job’s lifecycle state. If any such operation link is advertised, the applicable bound service-desc MUST also be visible in that representation.

Visibility of a Job MUST NOT itself be interpreted as authorization to modify, cancel, or otherwise operate on the Job.

Visibility of a Job operation link likewise grants no permission and does not guarantee successful invocation.

Likewise, visibility of:

iri:submit-job

on a compute Resource does not itself grant permission to submit a Job.

Authorization remains governed by the applicable API security and Facility policy.

Clients SHOULD treat a returned Job representation as the information visible within the current authenticated requester context.

16. Conformance

A representation conforms to the IRI Compute Job Profile when:

  1. it conforms to the applicable IRI Facility API Job schema;
  2. its properties are interpreted according to the IRI Compute API and this profile;
  3. id is treated as a Job identifier rather than a URL template;
  4. status, when present, conforms to the applicable JobStatus schema;
  5. state is interpreted using the Job State values defined by the governing OpenAPI contract;
  6. clients do not impose an undocumented Job State transition graph;
  7. job_spec, when present, conforms to the applicable JobSpec schema;
  8. Job Specification semantics are distinguished from Job identity;
  9. the compute Resource context is not inferred from the Job identifier;
  10. no Job-to-Resource relation is invented without an applicable registered IRI relation;
  11. iri:submit-job and iri:query-jobs are interpreted as compute-system-Resource-to-operation-entry-point relationships, not Job relationships;
  12. an advertised _links.self identifies the canonical retrievable Job representation;
  13. iri:get-job is treated as an optional operation affordance and does not replace or redefine self;
  14. advertised iri:get-job, iri:update-job, and iri:cancel-job links have both Resource and Job identifiers bound by the producer and retain the applicable compute Resource operation context;
  15. profile URIs identify representation semantics and are not used as Job identifiers or link-relation identifiers;
  16. clients do not infer or construct Job URLs when an advertised link or governing API contract supplies the applicable target;
  17. Job or operation-link visibility is not interpreted as authorization to perform Job operations;
  18. every advertised Job operation-affordance link has an applicable service-desc whose deployed OpenAPI contains the matching canonical x-iri-relation binding; and
  19. Job operation-affordance links do not carry IRI representation profiles.

A conforming representation MAY contain additional properties and links where permitted by the applicable IRI API specification.

17. Profile Identification and Versioning

The canonical identifier for this profile is:

https://iri.science/profiles/compute/job

The profile URI is a stable semantic identifier.

Repository paths, GitHub URLs, OpenAPI document locations, Job identifiers, compute Resource Type URNs, Job instance URLs, and documentation-generation URLs MUST NOT be substituted for this canonical identifier.

The canonical URI SHOULD resolve to documentation describing this profile.

The profile version identifies the revision of this profile document.

Compatible editorial clarifications and backward-compatible semantic additions MAY retain the same profile URI.

Changes to individual:

  • Jobs;
  • Job Status values;
  • Job Specifications;
  • compute Resources;
  • scheduler identifiers;
  • registered Job operation relationships

do not themselves require a new Job profile URI unless they materially change the semantics of the common Job representation.

Changes that materially alter the interpretation or processing semantics of the Job representation SHOULD be evaluated for compatibility before incorporation into the existing profile.

The canonical profile URI SHOULD remain stable across compatible revisions.

DOE Integrated Research Infrastructure — Compute Job Profile