Imported from registry/relations/download-file.md at commit 76a4a0c89924.

IRI Link Relation: download-file

Relation URI: https://iri.science/rels/download-file
CURIE: iri:download-file
Status: Provisional
Version: 1.0.0
Change controller: IRI technical subcommittee
Source representation type: Eligible DOE-IRI Resource representation with an explicit filesystem operation context
Source resource type: One of the exact Resource Types enumerated in Section 3
Target representation type: Resource-specific asynchronous file-download-request operation entry point
OpenAPI operation: POST /api/v2/filesystem/download/{resource_id} (operationId: download)

This document defines the iri:download-file operation-affordance relationship used by eligible DOE-IRI Resource representations.

The canonical relation URI is https://iri.science/rels/download-file. With the canonical IRI CURIE template https://iri.science/rels/{rel}, iri:download-file 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:download-file relationship advertises the operation entry point through which a client may request a file download in the source Resource’s configured filesystem context. File operands and download inputs remain in the OpenAPI-defined request body.

The relation identifies a task-submission operation. It is not a direct binary download link, file representation, or promise of a transfer result. It does not grant authorization, prove that the identified path exists, or guarantee that the download will complete.

3. Source, Target, and Operation Context

The relationship MAY originate only from a Resource whose exact resource_type is one of:

urn:doe-iri:resource:compute
urn:doe-iri:resource:compute:system
urn:doe-iri:resource:compute:node
urn:doe-iri:resource:storage
urn:doe-iri:resource:storage:filesystem
urn:doe-iri:resource:storage:mount
urn:doe-iri:resource:service:dtn

Eligibility is exact-type-based and is not inherited by other Resource Type descendants. For every eligible type, the adapter MUST establish the path namespace and one unambiguous execution/access context for the source Resource. Type classification, topology links, mount relationships, and supported_endpoints alone do not establish applicability.

In particular, a mount does not inherit operations from its filesystem or consuming system, and a DTN’s hosting or mount-access links do not imply a filesystem execution context. Generic compute and storage Resources are eligible only when their actual adapter semantics are known. If one source cannot identify an unambiguous context, the producer MUST expose separate Resources and use registered topology relations; it MUST NOT silently choose a host or add an undocumented context selector.

The producer MUST bind resource_id to the represented Resource’s adapter context. Because it is the only path variable, the advertised operation link is concrete rather than templated. If the operation belongs to a different Resource, the producer MUST expose the appropriate Resource relationship rather than advertise the operation as belonging to this source.

When supported_endpoints is present on the source Resource, advertising iri:download-file requires "filesystem" in that array. The reverse implication does not apply, and authorization-suppressed omission does not make a retained "filesystem" category inconsistent.

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

4. Cardinality

Each eligible Resource MAY advertise zero or one applicable operation entry point:

Resource  -- iri:download-file -->  File-download-request operation entry point
   1                   0..1

The HAL relation uses a singular link object when supplied.

5. Asynchronous Invocation Semantics

The mapped operation remains POST and returns TaskSubmitResponse. Following the relation submits asynchronous work; it does not synchronously return file content, a binary stream, or a redirect to one. Clients use the existing Task monitoring flow and the governing OpenAPI contract to determine the outcome and interpret any result.

Clients MUST NOT dereference this link as a direct download or infer a GET operation from the relation name.

6. Stability and Availability

The relationship describes a configured applicable operation affordance. Its presence SHOULD remain stable across ordinary changes in load, health, reachability, transfer capacity, or filesystem contents. It may change when the facility configures or withdraws the adapter operation or changes visibility for the requester.

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

7. Authorization, Visibility, and Omission

Authorization MAY affect visibility of the operation affordance. A provider MAY omit iri:download-file when the requester is not authorized to discover or use the entry point. Presence grants no permission and guarantees no successful download.

Omission means only that the affordance is not advertised in this representation. It does not prove that download requests are unsupported everywhere or permanently unavailable. 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.

8. OpenAPI Contract and Binding

The current operation mapping is:

POST /api/v2/filesystem/download/{resource_id}
operationId: download
success status: 200
success schema: TaskSubmitResponse
x-iri-relation: ["https://iri.science/rels/download-file"]

OpenAPI remains authoritative for the bound path parameter, PostDownloadRequest request body, responses, errors, Task submission, 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 or direct-download behavior from the relation name. The canonical relation URI, rather than operationId, is the machine-readable binding key.

9. HAL Representation

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

10. Governing Sources

• Resource operation-affordance RFC
• IRI v2 filesystem OpenAPI
• Common Resource profile
• Compute-system Resource Definition Profile
• Compute-node Resource Definition Profile
• Filesystem Resource Definition Profile
• Mount Resource Definition Profile
• DTN service Resource Definition Profile

DOE Integrated Research Infrastructure — Link Relation: download-file