Merge pull request #582 from Open-EO/draft

Release v1.3.0

Author: m-mohr

.github/workflows/docs.yml

@@ -11,14 +11,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Inject env variables
-        uses: rlespinasse/github-slug-action@v3.x
-      - uses: actions/setup-node@v3
+        uses: rlespinasse/github-slug-action@v5
+      - uses: actions/setup-node@v5
         with:
           node-version: 'lts/*'
-      - uses: actions/checkout@v3
-      - run: |
-          npm install
-          npm run build
+      - uses: actions/checkout@v5
+      - run: npm install
+      - run: npm run build
       - name: clone gh-pages and clean-up
         if: ${{ env.GITHUB_REF_SLUG == 'master' }}
         run: |
@@ -29,11 +28,12 @@ jobs:
         if: ${{ env.GITHUB_REF_SLUG != 'master' }}
         run: mkdir gh-pages
       - run: |
-          cp redoc.html gh-pages/index.html
+          cp *.html gh-pages/
           cp errors.json gh-pages/errors.json
+          cp openapi.yaml gh-pages/openapi.yaml
           cp -rv assets/. gh-pages/assets/
       - name: deploy to root (master)
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         if: ${{ env.GITHUB_REF_SLUG == 'master' }}
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
@@ -42,7 +42,7 @@ jobs:
           user_name: 'openEO CI'
           user_email: openeo.ci@uni-muenster.de
       - name: deploy to ${{ env.GITHUB_REF_SLUG }}
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         if: ${{ env.GITHUB_REF_SLUG != 'master' }}
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/tests.yml

@@ -4,11 +4,9 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@v5
         with:
           node-version: 'lts/*'
-      - uses: actions/checkout@v3
-      - name: Run tests
-        run: |
-          npm install
-          npm test
+      - uses: actions/checkout@v5
+      - run: npm install
+      - run: npm test

.gitignore

@@ -1,6 +1,5 @@
-__pycache__/
-package-lock.json
-node_modules/
-/redoc.html
-.vscode
-.idea
+package-lock.json
+/node_modules/
+/*.html
+.vscode
+.idea

.redocly.lint-ignore.yaml

@@ -0,0 +1,8 @@
+openapi.yaml:
+  no-required-schema-properties-undefined:
+    - '#/components/schemas/dimension_spatial_horizontal/allOf/1/required/0'
+    - '#/components/schemas/dimension_spatial_vertical/allOf/1/anyOf/0/required/0'
+    - '#/components/schemas/dimension_spatial_vertical/allOf/1/anyOf/1/required/0'
+    - '#/paths/~1jobs~1{job_id}~1estimate/get/responses/200/content/application~1json/schema/anyOf/0/required/0'
+    - '#/paths/~1jobs~1{job_id}~1estimate/get/responses/200/content/application~1json/schema/anyOf/1/required/0'
+    - '#/paths/~1jobs~1{job_id}~1estimate/get/responses/200/content/application~1json/schema/anyOf/2/required/0'

.redocly.yaml

@@ -0,0 +1,16 @@
+extends:
+  - recommended
+
+openapi:
+  expandResponses: "200,201,202,203,204"
+  pathInMiddlePanel: true
+
+apis:
+  core:
+    root: ./openapi.yaml
+  commercial-data:
+    root: ./extensions/commercial-data/openapi.yaml
+  processing-parameters:
+    root: ./extensions/processing-parameters/openapi.yaml
+  workspaces:
+    root: ./extensions/workspaces/openapi.yaml

.spectral.yml

@@ -8,6 +8,7 @@ rules:
   tag-description: true
   oas3-parameter-description: true
   oas3-unused-component: false # Broken: https://github.com/stoplightio/spectral/issues/1271
+  array-items: false
   operation-summary-formatted:
     description: Operation `summary` should start with upper case and not end with a dot.
     given: '$.paths.*[?( @property === ''get'' || @property === ''put'' || @property === ''post'' || @property === ''delete'' || @property === ''options'' || @property === ''head'' || @property === ''patch'' || @property === ''trace'' )]'

CHANGELOG.md

@@ -4,15 +4,69 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Unreleased / Draft
+## [Unreleased] / Draft
 
-## [1.2.0] - 2021-05-31
+### Added
+
+### Deprecated
+
+### Changed
+
+### Fixed
+
+## [1.3.0] - 2026-02-02
+
+### Added
+
+- **New extensions:**
+  - [Remote Process Definition Extension](./extensions/remote-process-definition/README.md)
+  - [Processing Parameters Extension](./extensions/processing-parameters/README.md)
+  - [Workspaces Extension](./extensions/workspaces/README.md)
+- `GET /`: New relation type `web-editor` [#577](https://github.com/Open-EO/openeo-api/issues/577)
+- `GET /credentials/oidc`: Added `authorization_parameters` property to enforce specific parameters for the authorization endpoint [#534](https://github.com/Open-EO/openeo-api/issues/534)
+- `POST /result`: Added response header "OpenEO-Identifier" to expose an identifier associated with a synchronous processing request.
+- Added `stacktrace` to log entries (e.g. for `GET /jobs/{job_id}/logs`) [#512](https://github.com/Open-EO/openeo-api/issues/512)
+- Added `version` property to `GET /processes` [#517](https://github.com/Open-EO/openeo-api/issues/517)
+- Added `queued`, `started` and `unpublished` to the batch job metadata and the corresponding STAC results [#542](https://github.com/Open-EO/openeo-api/issues/542)
+- Added a status diagram that explains the status changes of batch jobs [#436](https://github.com/Open-EO/openeo-api/issues/436)
+- Added all the batch job timestamps (including the new timestamps above) to the Collection type of batch job results
+- Support for standard JSON Web Tokens (JWT) being used as Bearer tokens [#558](https://github.com/Open-EO/openeo-api/issues/558)
+
+### Deprecated
+
+- Deprecated the openEO-specific Bearer token format (authentication mechanism/provider id/access token) [#558](https://github.com/Open-EO/openeo-api/issues/558)
+- STAC 0.9.x
+
+### Changed
+
+- Updated Federation Extension to v0.2.0
+- Migrate from openEO-specific tokens to JWT, i.e. deprecating the openEO-specific format in favor of JWT [#558](https://github.com/Open-EO/openeo-api/issues/558)
+- `GET /`: Requires the fields `type` and `conformsTo`
+- `GET /udf_runtimes`: Requires at least one UDF runtime to be provided. [#511](https://github.com/Open-EO/openeo-api/issues/511)
+
+### Fixed
+
+- `GET /conformance`: Added missing security definitions
+- `GET /file_formats`: Base parameter on top of normal JSON Schema, not Process JSON Schema
+- `PATCH /services/{service_id}` and `PATCH /jobs/{job_id}`: Explicitly allow updating back-end specific properties (as in `POST`)
+- `GET /services/{service_id}` and `GET /jobs/{job_id}`: Explicitly allow listing back-end specific properties (as provided in `POST`)
+- `GET /jobs/{job_id}/results`: Clarify that signed URLs (used as "canonical" link) should be regenerated each time.
+- `GET /jobs/{job_id}/results`: Clarify that "canonical" job result link should include/encode the original query parameters
+- Clarified for log levels which default values apply
+- Clarified how the relation types `license`, `version-history` and `author` can be used to enrich the process metadata. [#531](https://github.com/Open-EO/openeo-api/issues/531)
+- Clarified the behaviour of `federation:backends` for `POST /validation`
+- Clarified the meaning of `expires` in batch job results
+- Clarified that `last_successful_check` (from Federation Extension) can be null.
+- Clarified the relation between result and end nodes, the usage of the result flag, and the relation between the outermost ("root") and child process graphs [#547](https://github.com/Open-EO/openeo-api/issues/547)
+- Fixed various OpenAPI issues reported by redocly lint
+
+## [1.2.0] - 2021-05-25
 
 ### Added
 
 - **New extensions:**
-    - [Commercial Data Extension](./extensions/commercial-data/README.md)
-    - [Federation Extension](./extensions/federation/README.md)
+  - [Commercial Data Extension](./extensions/commercial-data/README.md)
+  - [Federation Extension](./extensions/federation/README.md)
 - `GET /`: New Relation types: [#404](https://github.com/Open-EO/openeo-api/issues/404)
   - `create-form` to link to the registration page
   - `recovery-form` to link to the credentials recovery page.
@@ -24,9 +78,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Recommendation to add a link with relation type `canonical` which points to a signed URL with the same content as the response. [#397](https://github.com/Open-EO/openeo-api/issues/397)
   - Added metadata field `openeo:status` to indicate the job status (and whether the result is complete or not).
   - Added parameter `partial` to allow retrieving incomplete results, which must also add the new property `openeo:status` to the metadata. [#430](https://github.com/Open-EO/openeo-api/issues/430)
-- `GET /jobs/{job_id}/logs`, `GET /services/{service_id}/logs`: Added `level` parameter to requests to set the minimum log level returned by the response. [#485](https://github.com/Open-EO/openeo-api/issues/485)
+- `GET /jobs/{job_id}/logs`, `GET /services/{service_id}/logs` and `POST /result`: Added `level` parameter to requests to set the minimum log level returned by the response. [#485](https://github.com/Open-EO/openeo-api/issues/485)
 - Added property `log_level` to secondary web service, batch job and synchronous processing endpoints to indicate the minimum severity level that should be stored for logs. [#329](https://github.com/Open-EO/openeo-api/issues/329)
-- `GET /jobs/{job_id}/logs`, `GET /services/{service_id}/logs` and `POST /result`: Added `level` property in responses to reflect the minimum log level that may appear in the response. [#329](https://github.com/Open-EO/openeo-api/issues/329)
+- `GET /jobs/{job_id}/logs`, `GET /services/{service_id}/logs`: Added `level` property in responses to reflect the minimum log level that may appear in the response. [#329](https://github.com/Open-EO/openeo-api/issues/329)
 - Recommendation to add media types and titles to links for a better user experience.
 - Allow the relation type `canonical` to be used generally for (shared) resources (e.g. UDPs or batch jobs) without requiring Bearer authentication. [#405](https://github.com/Open-EO/openeo-api/issues/405)
 - Recommendation for UDF runtime names. [#409](https://github.com/Open-EO/openeo-api/issues/409)
@@ -431,6 +485,7 @@ Initial version.
 
 
 [Unreleased]: <https://github.com/Open-EO/openeo-api/compare/master...dev>
+[1.3.0]: <https://github.com/Open-EO/openeo-api/compare/1.2.0...1.3.0>
 [1.2.0]: <https://github.com/Open-EO/openeo-api/compare/1.1.0...1.2.0>
 [1.1.0]: <https://github.com/Open-EO/openeo-api/compare/1.0.1...1.1.0>
 [1.0.1]: <https://github.com/Open-EO/openeo-api/compare/1.0.0...1.0.1>

README.md

@@ -6,12 +6,13 @@ openEO develops an open API to connect R, Python and JavaScript clients to big E
 
 ## Versions / Branches
 
-The [master branch](https://github.com/Open-EO/openeo-api/tree/master) is the 'stable' version of the openEO API specification. It is currently version **1.2.0** of the specification. The [draft branch](https://github.com/Open-EO/openeo-api/tree/draft) is where active development takes place.
+The [master branch](https://github.com/Open-EO/openeo-api/tree/master) is the 'stable' version of the openEO API specification. It is currently version **1.3.0** of the specification. The [draft branch](https://github.com/Open-EO/openeo-api/tree/draft) is where active development takes place.
 
 | Version / Branch                                          | Status      | Description |
 | --------------------------------------------------------- | ----------- | ----------- |
 | [draft](https://api.openeo.org/draft)                     | planned     | *Unstable* - Next version. |
-| [**1.2.0**](https://api.openeo.org)                       | **current** | Clarifications, new extensions, vector data cubes, STAC (API) updates, more link relation types, improved batch job results and logs. [Changelog](CHANGELOG.md#120---2023-05-31). |
+| [**1.3.0**](https://api.openeo.org)                       | **current** | Clarifications, Remote Process Definition and Processing Parameters extensions, new token format, batch job improvements, etc. [Changelog](CHANGELOG.md#130---2026-02-02). |
+| [1.2.0](https://api.openeo.org/1.2.0)                     | legacy      | Clarifications, Commercial Data and Federation extensions, vector data cubes, STAC (API) updates, more link relation types, improved batch job results and logs. [Changelog](CHANGELOG.md#120---2023-05-31). |
 | [1.1.0](https://api.openeo.org/1.1.0)                     | legacy      | Clarifications, STAC updates, return value for child processes, more details for logs and jobs, default clients for OIDC. [Changelog](CHANGELOG.md#110---2021-06-15). |
 | [1.0.1](https://api.openeo.org/1.0.1)                     | legacy      | Clarifications, bugfixes and CORS improvements. [Changelog](CHANGELOG.md#101---2020-12-07). |
 | [1.0.0](https://api.openeo.org/1.0.0)                     | legacy      | First stable version of openEO. [Changelog](CHANGELOG.md#100---2020-07-17). |
@@ -29,10 +30,13 @@ See also the [changelog](CHANGELOG.md) and the [milestones](https://github.com/O
 
 ## Extensions
 
-| Name                                           | Version | Stability    | Description |
-| ---------------------------------------------- | ------- | ------------ | ----------- |
-| [Commercial Data](extensions/commercial-data/) | 0.1.0   | experimental | Provides an interface for discovering, ordering and using commercial data. |
-| [Federation](extensions/federation/)           | 0.1.0   | experimental | Covers federation aspects, i.e. where multiple back-ends are exposed as a single API. |
+| Name                                                               | Version | Stability    | Description |
+| ------------------------------------------------------------------ | ------- | ------------ | ----------- |
+| [Commercial Data](extensions/commercial-data/)                     | 0.1.0   | experimental | Provides an interface for discovering, ordering and using commercial data. |
+| [Federation](extensions/federation/)                               | 0.2.0   | experimental | Covers federation aspects, i.e. where multiple back-ends are exposed as a single API. |
+| [Processing Parameters](extensions/processing-parameters/)         | 0.1.0   | experimental | Explore and handle additional processing parameters that a back-end can offer for the processing modes (sync. processing, batch jobs, web services). |
+| [Remote Process Definition](extensions/remote-process-definition/) | 0.1.0   | experimental | Load user-defined processes that are hosted externally through the process namespace into process graphs. |
+| [Workspaces](extensions/workspaces/)                               | 0.1.0   | experimental | Connect external file storage systems (e.g. cloud buckets) to openEO back-end implementations. |
 
 ## Repository
 
@@ -43,14 +47,14 @@ This repository contains a set of files formally describing the openEO API, each
 * The [assets](assets/) folder contains some useful additional files such as examples or schemas. All of these are non-binding additions. The source of truth are the top-level specification files.
 * The [extensions](extensions/) folder contains extensions to the openEO API.
 
-# Development
+## Development
 
 The `draft` branch is the latest version and is the one to create Pull Requests against.
 
 For development some tools can be used:
 
 1. Install [node and npm](https://nodejs.org) - should run with any recent version
 2. Run `npm install` in this folder to install the dependencies
-3. Run the linter for the OpenAPI file with `npm test`. This will lint the files and check against some best-practices. It uses `spectral` in the background.
+3. Run the linter for the OpenAPI file with `npm test`. This will lint the files and check against some best-practices. It uses `spectral` and `redocly` in the background.
 4. To show the files nicely formatted in a web browser, run `npm start`. It starts a server and opens the API specification rendered with ReDoc in a web browser.
-5. To create a static HTML page (e.g. for hosting it on GitHub Pages), you can run `npm run build` and it will create a `redoc.html` in this folder.
+5. To create a static HTML page (e.g. for hosting it on GitHub Pages), you can run `npm run build` and it will create a `index.html` in this folder and additional files for the extensions.

assets/status-diagram.png

@@ -200,7 +200,7 @@
 		]
 	},
 	"ProcessInvalid": {
-		"description": "The process given is invalid, which ususlly means that the process metadata is invalid.",
+		"description": "The given process definition is invalid, which usually means that the process metadata is invalid.",
 		"message": "Invalid process specified.",
 		"http": 400,
 		"tags": [
@@ -241,8 +241,8 @@
 		]
 	},
 	"ProcessGraphComplexity": {
-		"description": "The process graph is too complex for synchronous processing and will likely time out. Please use a batch job instead.",
-		"message": "The process is too complex for for synchronous processing. Please use a batch job instead.",
+		"description": "The process graph is computationally too demanding for synchronous processing and will likely time out. Please use a batch job instead.",
+		"message": "The process graph is too demanding for synchronous processing. Please use a batch job instead.",
 		"http": 400,
 		"tags": [
 			"Data Processing"