Release openEO API v1.2.0

[m-mohr]

Background

We've collected improvements and useful new features for two years now, especially in the context of the openEO Platform project. This publishes clarifications and improvements to the public so that we don't need to work on the draft for too long. This API release is also required to be able to release openEO processes in version 2.0.0-rc.1 due to the changes from the "raster-cube" to "datacube" subtype and the related changes in the process schema.

You can review the changes at Open-EO/openeo-api#492.

tl;dr summary: Clarifications, new extensions, vector data cubes, STAC (API) updates, more link relation types, improved batch job results and logs, and more minor improvements.

The following changes have been made to the API in detail:

Added

• New extensions:
  • Commercial Data Extension
  • Federation Extension
• GET /: New Relation types: #404
  • create-form to link to the registration page
  • recovery-form to link to the credentials recovery page.
• GET /file_formats: Add pointcloud to the gis_data_types. #475
• GET /me: New Relation types alternate and related for user-specific external pages. #404
• GET /credentials/oidc: Allow authorization_code and urn:ietf:params:oauth:grant-type:device_code (both without PKCE) as grants for default_clients. #410
• GET /jobs and GET /jobs/{job_id}: Added a links property that can for example link to results and logs. #453
• GET /jobs/{job_id}/results:
  • Recommendation to add a link with relation type canonical which points to a signed URL with the same content as the response. #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
• 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
• 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
• 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
• 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
• Recommendation for UDF runtime names. #409
• Processes: Added dimensions schema for subtype datacube
• Collections: Added geometry dimension type to cube:dimensions
• New endpoint for metadata filters (queryables): /collections/{collection_id}/queryables. Also adds a new rel type to the collection links. #396

Changed

• Updated STAC specification examples and references to v1.0.0, please see the STAC changelog for all changes between 0.9 and 1.0.
• cube:dimensions: reference_system is allowed to be PROJJSON, too.
• Relaxed requirement that unsupported endpoints must return HTTP status code 501. Instead also HTTP status code 404 can be used (and is regularly used in practice). #415
• Minimum value for costs and budget is 0.
• GET /jobs/{job_id}/estimate: If a batch job can't be estimated reliably, a EstimateComplexity error should be returned. #443
• The /conformance endpoint is now generally used for OGC APIs, STAC API and openEO. conformsTo is also exposed in GET / for STAC APIs. The openEO API and all extensions got individual conformance classes. #186

Fixed

• Explicitly mention the use of HTTP content negotiation
• Clarify that the default charset is UTF-8 #462
• Fixed inconsistencies in errors.json: removed ProcessGraphIdDoesntMatch, clarified ProcessGraphMissing, added ProcessInvalid and ProcessGraphInvalid. #394, #395, #401
• Fixed the default value for the version number in the API url (v1.0 -> v1) and improved the description for API versioning. #393
• Fixed the Collection example to use gsd instead of eo:gsd. #399
• Clarify use of user_id. #404
• 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
• Clarify the fields plan (for processing requests) and billing_plan (in GET / and GET /me). #425 #426
• Clarified ambiguous batch job status changes.
• Reflect that the debug process has been renamed to inspect.
• Clarified uniqueness constraints for identifiers. #449 #454
• Clarified schematically the applicability of JSON Schema extensions (parameters, returns, dimensions) and their relation to the subtypes
• GET /: Removed the superfluous default value for currency. #423
• GET /credentials/oidc: Clarify that clients may add additional scopes
• GET /me: Clarify the behavior of the field budget.
• GET /jobs/{job_id}/logs, GET /services/{service_id}/logs and POST /result: Clarified the formatting of the message property. #455
• GET /jobs/{job_id}/estimate: Don't require that the costs are the upper limit. Services may specify the costs more freely depending on their terms of service.
• GET /services and GET /services/{service_id}: Clarify that enabled is required by removing the default value. #473
• Several appearances of nullable were clarified according to the lint report by Spectral
• Clarify how the well-known document works #460
• Clarify handling of JSON Schema versions

Proposal

I'm proposing to release openEO API 1.2.0 in May 2023.
I'll inform you here if any additional changes come in until we approved the release here.

Additional context

Deadline: May 31, 2023

[mkadunc]

👍

[jdries]

+1

[m-mohr]

I'm +1, of course :-)

@edzer @neteler @aljacob @bschumac Your votes would be appreciated.

[bschumac]

I vote 0+

[m-mohr]

Any particular reasons that prevent from voting +1, @bschumac?

[m-mohr]

@edzer @neteler @aljacob Your votes would be appreciated. The vote has currently been accepted of no vetoes come in.

[bschumac]

@m-mohr as far as I read the guidelines on https://openeo.org/psc.html there is no need to give a reason for the vote as long as it is not "-1". But of course I can tell you the background of my vote:
From a user perspective, some improvements may deliver very useful results with certain backends depending on their technology. On other backends the improvments have from my point of view no big impact, but also do not harm the user experience either.

[m-mohr]

@bschumac Thanks for the explanation. We aim for having everybody fully backing the changes, so as a chair I think it's my obligation to get everyone on board for what we are doing, but for this I need to understand the reasons. Otherwise, we can't incorporate potential changes required to get everyone on board. You are not obligued to give reasons, of course.

Having that said, I'm now very curious what you are referring to. I've looked through the changelog again and can't really find changes that are technology dependant. The proposed additions and changes should be applicable to all implementations as far as I can tell.

[aljacob]

+1 from my side.

[neteler]

+1 also from my side

[m-mohr]

Thanks, openEO API v1.2.0 has been released: https://github.com/Open-EO/openeo-api/releases/tag/1.2.0