Merge pull request #308 from Open-EO/draft - release 1.0.0

.gitignore

@@ -2,3 +2,5 @@ __pycache__/
 package-lock.json
 node_modules/
 /redoc.html
+.vscode
+.idea

.spectral.yml

@@ -0,0 +1,37 @@
+extends: "spectral:oas"
+# don't error on circular schemas, these are currently not supported by spectral
+# https://github.com/stoplightio/spectral/issues/894
+except:
+  "openapi.yaml#/components/schemas/process_graph/example":
+    - oas3-valid-schema-example
+  "openapi.yaml#/paths/~1processes/get/responses/200/content/application~1json/example":
+    - oas3-valid-oas-content-example
+  "openapi.yaml#/paths/~1process_graphs/get/responses/200/content/application~1json/example":
+    - oas3-valid-oas-content-example
+  "openapi.yaml#/paths/~1service_types/get/responses/200/content/application~1json/example":
+    - oas3-valid-oas-content-example
+  "openapi.yaml#/paths/~1file_formats/get/responses/200/content/application~1json/example":
+    - oas3-valid-oas-content-example
+rules:
+  # Ported from Spectral 4.0
+  contact-properties: true
+  tag-description: true
+  oas3-parameter-description: true
+  operation-summary-formatted:
+    description: Operation `summary` should start with upper case and not end with a dot.
+    recommended: true
+    type: style
+    given: '$.paths.*[?( @property === ''get'' || @property === ''put'' || @property === ''post'' || @property === ''delete'' || @property === ''options'' || @property === ''head'' || @property === ''patch'' || @property === ''trace'' )]'
+    then:
+      field: summary
+      function: pattern
+      functionOptions:
+        match: '^[A-Z].*[^\.]$'
+    tags:
+      - operation
+  operation-id-kebab-case:
+    given: "$"
+    then:
+      function: pattern
+      functionOptions:  # this object be passed down as options to the custom function
+        match: ^[a-z][a-z0-9\-]*$

.travis.yml

@@ -1,27 +1,13 @@
-language: python
-
-python:
-- "3.5"
+language: node_js
 
 node_js:
 - "8"
 
 sudo: required
 
-before_install:
-# Speccy
-- npm install -g speccy
-- speccy lint openapi.yaml -r tests/speccy.yml
-# OpenAPI Spec Validator
-- pip install openapi-spec-validator
-- openapi-spec-validator openapi.yaml
-# DIY example validation (PR#194)
-- pip install -r tests/requirements.txt
-- pytest tests
-# ToDo: Check assets/pg-evi-example.json against the schema in pg-schema.json
-
 install:
 - npm install
+- npm test
 
 script:
 - npm run build
@@ -33,7 +19,6 @@ before_deploy:
   if [[ $TRAVIS_BRANCH == 'master' ]] ; then
     cp ../redoc.html index.html
     cp ../errors.json errors.json
-    cp ../subtype-schemas.json subtype-schemas.json
     cp -r ../assets assets
   fi
 - |
@@ -42,7 +27,6 @@ before_deploy:
     mkdir -p draft
     cp ../redoc.html draft/index.html
     cp ../errors.json draft/errors.json
-    cp ../subtype-schemas.json draft/subtype-schemas.json
     cp -r ../assets draft/assets
   fi
 - |
@@ -51,7 +35,6 @@ before_deploy:
     mkdir -p $TRAVIS_TAG
     cp ../redoc.html $TRAVIS_TAG/index.html
     cp ../errors.json $TRAVIS_TAG/errors.json
-    cp ../subtype-schemas.json $TRAVIS_TAG/subtype-schemas.json
     cp -r ../assets $TRAVIS_TAG/assets
   fi
 

CHANGELOG.md

@@ -6,11 +6,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased / Draft
 
+
+## 1.0.0 - 2020-07-17
+
+### Added
+- `GET /me`: Added optional `name` property to better separate an internal user id from a displayable user name. Adopted description of `user_id` accordingly.
+- `GET /udf_runtimes`: 
+    - Added optional `title` property for UDF runtimes. [#266](https://github.com/Open-EO/openeo-api/issues/266)
+    - Added required `type` property for UDF runtimes to support better code generation.
+- `GET /service_types`: Added optional `title` and `description` properties for service types. [#266](https://github.com/Open-EO/openeo-api/issues/266)
+- `GET /file_formats`: Added optional `description` property for file formats. [#266](https://github.com/Open-EO/openeo-api/issues/266)
+- `GET /collections/{collection_id}` and `GET /processes`: Mention of link `rel` type `example` to refer to examples. [#285](https://github.com/Open-EO/openeo-api/issues/285)
+- `GET /collections/{collection_id}`: Added optional `assets` property for collection-level assets. This may link to visualizations for example. [#211](https://github.com/Open-EO/openeo-api/issues/211)
+- `GET /collections`, `GET /jobs`, `GET /process_graphs`, `GET /Services`: Allow all non-scalar properties to be part of the response although strongly discouraged.
+
+### Changed
+- `GET /credentials/oidc`: field `scopes` is not required anymore, but when specified, it should contain the `openid` scope. [#288](https://github.com/Open-EO/openeo-api/pull/288)
+- `GET /.well-known/openeo` and `GET /`: `production` fields default to `false` instead of `true`.
+- `GET /jobs/{job_id}/logs` and `GET /services/{service_id}/logs`: `path` property is not required any longer. [#320](https://github.com/Open-EO/openeo-api/issues/320)
+- `GET /file_formats`: `parameters` is now required for each file format. [#318](https://github.com/Open-EO/openeo-api/issues/318)
+- `GET /service_types`: `configuration` and `process_parameters` are now required for each service. [#318](https://github.com/Open-EO/openeo-api/issues/318)
+- `GET /service_types` and `GET /file_formats`:
+    - Allow full JSON Schema for parameters, instead of a very limited subset.
+    - Instead of the proprietary property `example` use `examples` from JSON Schema instead.
+- `GET /collections` and `GET /collections/{collection_id}`:
+    - Additional dimensions in `cube:properties` can only be of type `other`.
+    - The extents `interval` and `bbox` can have multiple entries.
+- Allow all STAC versions that are compatible to STAC 0.9.0.
+- Process graph nodes have an additional field `namespace` to distinguish pre-defined and user-defined processes. The default behavior has not changed. [#305](https://github.com/Open-EO/openeo-api/issues/305)
+- Added `format: commonmark` to all properties supporting CommonMark formatting.
+- `errors.json`: The pre-defined error messages have been reworked.  [#272](https://github.com/Open-EO/openeo-api/issues/272), [#273](https://github.com/Open-EO/openeo-api/issues/273)
+    - Added `FolderOperationUnsupported`, `UnsupportedApiVersion`, `PermissionsInsufficient`, `ProcessGraphIdDoesntMatch` and `PredefinedProcessExists`.
+    - Added variable `reason` to error `FilePathInvalid` and `type` to `FileTypeInvalid` and`ServiceUnsupported`.
+    - Replaced the following error messages. The variables in the messages may have changed, too.
+        - `ProcessArgumentUnsupported` -> `ProcessParameterUnsupported`
+        - `ProcessArgumentInvalid` -> `ProcessParameterInvalid`
+        - `ProcessParameterMissing` and `ProcessArgumentRequired` -> `ProcessParameterRequired`
+        - `ServiceArgumentUnsupported` -> `ServiceConfigUnsupported`
+        - `ServiceArgumentInvalid` -> `ServiceConfigInvalid`
+        - `ServiceArgumentRequired` -> `ServiceConfigRequired`
+    - Removed all error messages with tag `Processes` (`CRSInvalid`, `CoordinateOutOfBounds`) or related to storing file formats (`FormatUnsupported`, `FormatArgumentUnsupported`, `FormatArgumentInvalid`, `FormatUnsuitable`) as they are usually defined directly in the process specification as `exceptions`.
+
+### Removed
+- `GET /processes`: Examples containing process graphs. Use links with `rel` type `example` and `type` set to `application/json` instead. [#285](https://github.com/Open-EO/openeo-api/issues/285)
+- `subtype-schemas.json`. It's now published as part of [openeo-processes](https://github.com/Open-EO/openeo-processes/blob/master/meta/subtype-schemas.json).
+
+### Fixed
+- `/.well-known/openeo`:
+    - Clarified that version numbers must be unique. [#287](https://github.com/Open-EO/openeo-api/issues/287)
+    - Clarified that non-production ready versions should be connected to if no production-ready version is supported. [#289](https://github.com/Open-EO/openeo-api/issues/289)
+- `GET /jobs/{job_id}/results`: Clarified that unlocated results set `geometry` to `null` and omit the `bbox` property.
+- `GET /jobs/{job_id}/logs`: Clarified that back-ends can log at any stage of the job. [#315](https://github.com/Open-EO/openeo-api/issues/315)
+- `POST /jobs` and `POST /services`: Clarified definition of `Location` header in `HTTP 201` responses. [#269](https://github.com/Open-EO/openeo-api/issues/269)
+- `GET /service/{service_id}`: Property `configuration` is required instead of a non-existing property named `parameters`.
+- `POST /validation`: Clarify that unresolvable process parameters must not throw. [#314](https://github.com/Open-EO/openeo-api/issues/314)
+- Formally forbid 5 elements in bounding boxes.
+- Re-use corresponding schema for header `OpenEO-Identifier` (adds `pattern`).
+- Parameters passed to child process graphs are not defined recursively any longer. [#268](https://github.com/Open-EO/openeo-api/issues/268)
+- Parameters for child process graphs are not specified for return values and service type parameters any longer. [#268](https://github.com/Open-EO/openeo-api/issues/268)
+- Clarified the expected behavior for process parameters, if a default value is given and the parameter is implicitly set to be required. [#303](https://github.com/Open-EO/openeo-api/issues/303)
+- Several clarifications and improvements for the documentation.
+
 ## 1.0.0-rc.2 - 2020-02-20
 
 ### Added
 - `PUT /process_graphs/{process_graph_id}` to store and replace custom process-graphs. [#260](https://github.com/Open-EO/openeo-api/issues/260)
-- `/jobs/{job_id}/logs` and `GET /services/{service_id}/logs`: Reintroduced the missing `offset` parameter.
+- `GET .../logs`: Reintroduced the missing `offset` parameter.
 
 ### Changed
 - For batch jobs (`/jobs`), services (`/services`) and sync. processing (`/result`) the property `process_graph` got replaced by `process`. It contains a process graph and optionally all process metadata. [#260](https://github.com/Open-EO/openeo-api/issues/260)
@@ -32,6 +93,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Clarified that back-ends not supporting pagination will return all resources.
 - Clarified how `from_parameter` is resolved in case no value is given.
 - Clarified `GET .../logs` endpoint behaviour.
+- Clarify difference between STAC specification and STAC API.
+- Clarify that a copy of the STAC Item is recommended to be part of the assets in a batch job download.
 - Removed outdated error codes from `errors.json`.
 
 ## 1.0.0-rc.1 - 2020-01-31

README.md

@@ -6,17 +6,18 @@ 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.0.0-rc.2** 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.0.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* - Bug fixes based on developer feedback, introduce extension concept. Potentially version 1.0.0-final. |
-| [**1.0.0-rc.2**](https://api.openeo.org)                  | **current** | Release candidate 2 for first stable version of openEO, see the [changelog](CHANGELOG.md#100-rc2---2020-02-20). |
-| [1.0.0-rc.1](https://api.openeo.org/1.0.0-rc.1)           | legacy      | Release candidate 1 for first stable version of openEO, see the [changelog](CHANGELOG.md#100-rc1---2020-01-31). |
-| [0.4.2](https://api.openeo.org/v/0.4.2)                   | legacy      | Bugfix release, see the [changelog](CHANGELOG.md#042---2019-06-11). |
-| [0.4.1](https://api.openeo.org/v/0.4.1)                   | legacy      | Bugfix release, see the [changelog](CHANGELOG.md#041---2019-05-29). |
-| [0.4.0](https://api.openeo.org/v/0.4.0)                   | legacy      | Improved discovery, added processes catalogue, new process graph structure and [more](CHANGELOG.md#040---2019-03-07). |
-| [0.3.1](https://api.openeo.org/v/0.3.1)                   | legacy      | Fixing minor issues, see the [changelog](CHANGELOG.md#031---2018-11-06). |
+| [draft](https://api.openeo.org/draft)                     | planned     | *Unstable* - Next version. |
+| [**1.0.0**](https://api.openeo.org)                       | **current** | First stable version of openEO. [Changelog](CHANGELOG.md#100---2020-07-17). |
+| [1.0.0-rc.2](https://api.openeo.org/1.0.0-rc.2)           | legacy      | Introduced user-defined processes. [Changelog](CHANGELOG.md#100-rc2---2020-02-20). |
+| [1.0.0-rc.1](https://api.openeo.org/1.0.0-rc.1)           | legacy      | Better UDF support, support for file import, support for processing logs, better alignment with STAC and upcoming OGC APIs. Removes WebSocket-based Subscription API. [Changelog](CHANGELOG.md#100-rc1---2020-01-31) |
+| [0.4.2](https://api.openeo.org/v/0.4.2)                   | legacy      | Bugfix release. [Changelog](CHANGELOG.md#042---2019-06-11). |
+| [0.4.1](https://api.openeo.org/v/0.4.1)                   | legacy      | Bugfix release. [Changelog](CHANGELOG.md#041---2019-05-29). |
+| [0.4.0](https://api.openeo.org/v/0.4.0)                   | legacy      | Improved discovery, added processes catalogue, new process graph structure. [Changelog](CHANGELOG.md#040---2019-03-07). |
+| [0.3.1](https://api.openeo.org/v/0.3.1)                   | legacy      | Bugfix release. [Changelog](CHANGELOG.md#031---2018-11-06). |
 | [0.3.0](https://api.openeo.org/v/0.3.0)                   | legacy      | Major rework. |
 | [0.0.2](https://github.com/Open-EO/openeo-api/tree/0.0.2) | legacy      | Proof of concept, implemented. |
 | [0.0.1](https://github.com/Open-EO/openeo-api/tree/0.0.1) | legacy      | First draft with basic ideas, loosely implemented. |
@@ -29,5 +30,4 @@ This repository contains a set of files formally describing the openEO API, each
 
 * [openapi.yaml](openapi.yaml) provides the [OpenAPI](https://www.openapis.org/) 3.0 definition of the openEO API. See the table above for human-readable versions of the OpenAPI definition.
 * [errors.json](errors.json) is a list of potential global error codes and messages, excluding specific exceptions separately available for each process.
-* [subtype-schema.json](subtype-schema.json) defines data types (subtypes) for JSON Schema used in openEO.
 * 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.

assets/pg-evi-example.json

@@ -1,7 +1,7 @@
 {
   "dc": {
     "process_id": "load_collection",
-    "description": "Loading the data.",
+    "description": "Loading the data",
     "arguments": {
       "id": "Sentinel-2",
       "spatial_extent": {
@@ -115,7 +115,7 @@
               }
             }
           },
-          "p3": {
+          "m3": {
             "process_id": "multiply",
             "arguments": {
               "x": 2.5,

assets/pg-schema.json

@@ -24,7 +24,15 @@
       ],
       "properties": {
         "process_id": {
-          "$ref": "#/definitions/process_id"
+          "type": "string",
+          "pattern": "^\\w+$"
+        },
+        "namespace": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null
         },
         "result": {
           "type": "boolean",
@@ -127,11 +135,6 @@
           }
         }
       ]
-    },
-    "process_id": {
-      "type": "string",
-      "subtype": "process-id",
-      "pattern": "^\\w+$"
     }
   }
 }