How to return a reference for Processes results?

[francescoingv]

I am trying to offer a process having the capability of outputTransmission = reference
I am focused on:

• execution-mode = async
• response = raw
• all outputs requested with "transmissionMode": "reference"

According to Table 11 and Requirement 30 of the standard:

• the body will be empty
• the returned status will be 204
• the media type will be none
• there will be one or more Link headers that reference each requested output

My understanding in pygeoapi architecture is that the Processor offering outputTransmission = reference will make the resource(s), one per requested output, and the client will be able to access that resource(s) at the provided link(s).
The URL where the Processor will make the resource(s) available is out of the scope of the standard, is not part of pygeoapi, and it is the sole responsibility of the Processor to make them, and only the Processor knows them.

In the case I am focusing on (i.e. execution-mode = async, response = raw, all outputs with "transmissionMode": "reference")
I understand the result of the Processor.execute() will be:

• mime_type = none
• outputs = "" (or none?)
• status = 204

From this result the Manager cannot add to the response_headers the Link headers that reference each requested output.

Please can someone address me if I am missing something.
If not, I would like Processor.execute() may also return the Link headers required in this case.

Also, I didn't find in the standard what attributes the link header should have.
Specifically what attribute should contain the output identifier for each header? Any other attribute required?
May I ask if there is an example?

Thank you

[francescoingv]

In the Manager,
please consider also passing the Link headers information in the dictionary passed to update_job(),
and then in get_job_result() retrieving, and passing back also the links (if present).

[francescoingv]

@tomkralidis
Following today meeting,
in case the client output request is:
"outputs" : {"out_1": { "transmissionMode": "reference" }, "out_2" : { "transmissionMode": "reference" } }'

I understand we said that the Processor.execute() should return with:
return None, None, ['<https://myExternal.org/outputs/myfile.txt> ; rel="out_1" ', '<https://myExternal.org/outputs/myfile.pdf> ; rel="out_2" ']
or alternatively:
return None, None, ['<https://myExternal.org/outputs/myfile.txt>; rel="out_1" ; type="application/txt" ', '<https://myExternal.org/outputs/myfile.pdf>; rel="out_2" ; type="application/pdf" ']

On top of the above,
the Manager.execute() should persist with self.update_job(job_id, job_update_metadata) also:

• status code
• links

and complete the function with:

response_headers['link'] = [
    '<https://myExternal.org/outputs/myfile.txt>; rel="out_1"',
    '<https://myExternal.org/outputs/myfile.pdf>; rel="out_2"',
]
return <job_id>, None, None, 204, response_headers

Similarly, Manager.get_job_result() should get status and links from self.get_job(job_id) and return:
return None, None, 204, ['<https://myExternal.org/outputs/myfile.txt> ; rel="out_1" ' , '<https://myExternal.org/outputs/myfile.pdf> ; rel="out_2" ']

In the above Manager.execute() returns one additional item:

• link headers

and Manager.get_job_result() returns two additional items:

• http_code = 204;
• link headers

Finally, according to the standard a curl request (to either execution or result) should return something like:

curl  -k -L -X POST https://myPygeoapiTestSite/processes/<process_id>/execution  -H 'Content-Type: application/json' -d '{ "inputs" : {...}, "outputs" : {"out_1": { "transmissionMode": "reference" }, "out_2" : { "transmissionMode": "reference" } }'
HTTP/1.1 204 ...
server: ...
date: Fri, 20 Mar 2026 13:57:34 GMT
...
link: <https://myExternal.org/outputs/myfile.txt> ; rel="out_1"; type="application/txt"
link: <https://myExternal.org/outputs/myfile.pdf> ; rel="out_2"; type="application/txt" ; type="application/pdf" 
...

or

curl  -k -L -X POST https://myPygeoapiTestSite/processes/<process_id>/execution  -H 'Content-Type: application/json' -d '{ "inputs" : {...}, "outputs" : {"out_1": { "transmissionMode": "reference" }, "out_2" : { "transmissionMode": "reference" } }'
HTTP/1.1 204 ...
server: ...
date: Fri, 20 Mar 2026 13:57:34 GMT
...
link: <https://myExternal.org/outputs/myfile.txt> ; rel="out_1"; type="application/txt" , <https://myExternal.org/outputs/myfile.pdf> ; rel="out_2"; type="application/txt" ; type="application/pdf" 
...