How to expose which version of openeo-processes is available/targeted

[soxofaan]

I'm working on adding openeo API 1.2 and processes 2.0 to the VITO backend and the current goal is:

• https://openeo.vito.be/openeo/1.1/ (openeo API 1.1) provides the 1.x version of openeo-processes
• https://openeo.vito.be/openeo/1.2/ (openeo API 1.2) provides the 2.x version of openeo-processes

It would help (e.g. for user support) if we could make the linking between these versions more explicit in the metadata in some way.

Is there a way to expose the (target) openeo-processes version explicitly, e.g. globally in capabiltiies doc, or per process?

[m-mohr]

Hmm... Globally doesn't make a lot of sense as we often have the case that we implement processes from different versions, e.g. when new processes get added (e.g. you are on 1.x and add just one or two new processes from 2.x). Has happened in the past.
On the other hand, processes are meant to be self-declaring and unversioned. Like if you encounter a process from 1.1.0 that reports that version but is has been changed by the user (e.g. removed/added a parameter or updated a schema), is it still 1.1.0 or what version is it?

So I would try to avoid adding version numbers for processes. What's the use case? Wouldn't the client just read the process and detect that it's 1.2 or 2.0 e.g. based on the raster-cube / data cube subtype etc? It think that's the way to go and was always intended that way. This doesn't prevent you from adding a custom property "version" or so to the processes though.

[soxofaan]

Yes indeed, in practice the bag of provided processes is a bit a mix of 1.0, 1.1, 1.2, 2.0 and non-standard processes. Certainly the case in VITO backend for example. Still there is probably some kind of target upper bound a back-end wants/can provide.
But I agree that it is probably messy to try to put a global version stamp on that.

However, in Open-EO/openeo-aggregator#118 we found out that v1.x and v2.x processes don't mix nicely, because of rastercube (v1 style) vs datacube (v2 style) mismatch.
This is a reason for a back-end to stick to v1.x or go all in on v2. So that's why I was wondering if this could be made more explicit in some way.

Note that this will be especially challenging in the aggregator where processes of multiple backend have to be combined, making the synchronization exercise considerable harder.

[m-mohr]

Yes, in a federated interface this needs either good alignment and a migration path that is followed by all back-ends or a good strategy in the aggregator to "mix" them. I'm not sure how version numbers would help here though. If you have a version number you'd still need to merge somehow, right? Isn't it enough there to just replace raster/vector-cube with datacube in comparison?

[soxofaan]

The path we're currently trying in the VITO backend is

• API roots /openeo/1.0 and /openeo/1.1 stick to v1.x version of processes
• (new) API root /openeo/1.2 works with v2.x of processes

(Note: I think we did the same when we supported both v0.4 and v1.0 of openEO API and processes)

We could do the same in the aggregator:

• /openeo/1.1 and /openeo/1.0 combines backends with v1.1 or v1.0 openEO API + v1.x processes (what we currently have)
• /openeo/1.2 combines backends with v1.2 openEO API + v2.x processes (new, but no backend has this production ready I think)

That implies that we set up the convention to have a hard link between API version and processes version: a given an API endpoint version, you also know if you get v1 or v2 processes. This goes a bit against the spirit of the openEO API, but it could be a workable more practical alternative to trying to introduce a new API to declare the version level of the processes.

[m-mohr]

Maybe we just add a version flag to the resposne of GET /processes?
It can be either a specific version number, e.g. 1.0.0, or null/missing, which means unknown/mixed.

[soxofaan]

yes something like that would certainly help with the discussed use cases

[m-mohr]

See PR #549