Merge remote-tracking branch 'origin/draft' into draft

Author: m-mohr

CHANGELOG.md

@@ -54,6 +54,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Clarify that the relation type `version-history` should include `/.well-known/openeo` in the URL.
 - Clarify that clients should (re-)request capabilities and discovery endpoints with token if available and supported. [#416](https://github.com/Open-EO/openeo-api/issues/416)
 - Clarify the fields `plan` (for processing requests) and `billing_plan` (in `GET /` and `GET /me`). [#425](https://github.com/Open-EO/openeo-api/issues/425) [#426](https://github.com/Open-EO/openeo-api/issues/426)
+- Clarified ambiguous batch job status changes.
 - Reflect that the `debug` process has been renamed to `inspect`.
 - Clarified uniqueness constraints for identifiers. [#449](https://github.com/Open-EO/openeo-api/issues/449) [#454](https://github.com/Open-EO/openeo-api/issues/454)
 - Clarified schematically the applicability of JSON Schema extensions (`parameters`, `returns`, `dimensions`) and their relation to the subtypes

openapi.yaml

@@ -2976,13 +2976,14 @@ paths:
     patch:
       summary: Modify a batch job
       operationId: update-job
-      description: >-
+      description: |-
         Modifies an existing job at the back-end, but maintains the identifier.
         Changes can be grouped in a single request.
 
+        The job status does not change.
 
-        Jobs can only be modified when the job is not queued or running.
-        Otherwise requests to this endpoint MUST be rejected with openEO error
+        Jobs can only be modified when the job is not queued and not running.
+        Otherwise, requests to this endpoint MUST be rejected with openEO error
         `JobLocked`.
       tags:
         - Data Processing
@@ -3371,19 +3372,23 @@ paths:
         The result will be stored in the format specified in the process.
         To specify the format use a process such as `save_result`.
 
-        This endpoint has no effect if the job status is already `queued` or
-        `running`. In particular, it doesn't restart a running job. Processing
-        MUST be canceled before to restart it.
-
         The job status is set to `queued`, if processing doesn't start
-        instantly.
+        instantly. The same applies if the job status is `canceled`, `finished`,
+        or `error`, which restarts the job and discards previous results if the
+        back-end doesn't reject the request with an error.
+        Clients SHOULD warn users and ask for confirmation if results may get
+        discarded.
 
         * Once the processing starts the status is set to `running`.
         * Once the data is available to download the status is set to
         `finished`.
         * Whenever an error occurs during processing, the status MUST be set to
         `error`.
 
+        This endpoint has no effect if the job status is already `queued` or
+        `running`. In particular, it doesn't restart a running job. To restart
+        a queued or running job, processing MUST have been canceled before.
+
         Back-ends SHOULD reject queueing jobs with openEO error `PaymentRequired`,
         if the back-end is able to detect that the budget is too low to fully
         process the request. Alternatively, back-ends MAY provide partial results
@@ -3405,20 +3410,20 @@ paths:
     delete:
       summary: Cancel processing a batch job
       operationId: stop-job
-      description: >-
+      description: |-
         Cancels all related computations for this job at the back-end. It will
         stop generating additional costs for processing.
 
-
         A subset of processed results may be available for downloading depending
-        on the state of the job as it was canceled. Finished results MUST NOT be
-        deleted until the job is deleted or job processing is started again.
+        on the state of the job at the time it was canceled.
 
+        Results MUST NOT be deleted until the job processing is started again or
+        the job is completely deleted through a request to
+        `DELETE /jobs/{job_id}`.
 
         This endpoint only has an effect if the job status is `queued` or
         `running`.
 
-
         The job status is set to `canceled` if the status was `running`
         beforehand and partial or preliminary results are available to be
         downloaded. Otherwise the status is set to `created`.