Backend portability: Dimension naming is recommended, not required

[emmanuelmathot]

Gap 1 — Dimension naming is recommended, not required

The openEO documentation (Data Cubes) presents t, bands, x, y as the canonical dimension names. This is also what most backends return, and is the outcome of the discussion in #208. However, the spec itself only recommends these names — it does not require them, and at least one backend we tested uses time instead of t.

The practical consequence: a single call like

cube.reduce_dimension(dimension="t", reducer="first")

raises a validation error on a backend that exposes the dimension as time. Conversely, dimension="time" is rejected on a spec-aligned backend that says "valid dimensions are bands, x, y". The same applies to apply_dimension(dimension="bands" | "spectral", ...).

Clients can work around this by reading the cube's dimensions() at build time or by keeping a per-endpoint lookup. Neither is a portability story a UDP library should have to carry.

Suggested direction. Either:

• Promote the existing recommendation to a requirement for common dimension types (temporal → t, bands → bands, spatial → x / y), or
• Add a spec-level compliance test and mark backends that deviate as non-conformant, or
• At minimum, provide a standard way (process or capability field) to query the canonical dimension names a backend uses, so clients don't have to introspect every cube.

Prior discussion: #208 (closed) established the names as a recommendation but explicitly acknowledged that backends may not follow it.

[jdries]

Correct, this is also my experience, and indeed in the context of UDP, the problem has gotten worse.
I also don't really see a good argument against taking a 'by convention' approach.
I think the argument was always along the lines of keeping options open in case for very specific datasets, for instance having two time dimensions etcetera.
A nuance could then be that we make x/y/t/bands mandatory for any collection that uses these 4 dimensions.

[soxofaan]

Another possibility:
also allow to pass the dimension type instead of the name to processes like reduce_dimension(... dimension=...), ....

Dimension types are more strictly specified than names (e.g. the datacube STAC extension defines type "temporal" for time dimension). Unfortunately, the datacube extension does not define a "bands" type

[m-mohr]

So for x, y, t, bands it's pretty straightforward, the question is what do we do with z, dggs, geometry, second time dimension, etc. From a specification standpoint it feels weird to require some and not define anything for everything else.

and at least one backend we tested uses time instead of t.

Which one is it? Could we try to convince them to use t instead of time? The question is whether implementors that don't follow a recommendation would follow a requirement (that we can't really enforce schematically). We see this in other cases where pre-defined things get ignored as well. So I'm not sure requiring x,y,t,bands would actually solve it.

Correct, this is also my experience, and indeed in the context of UDP, the problem has gotten worse.

Could you give an example? The UDP usage that I see at VITO from externally usually just covers your own backends, which should by x,y,t,bands. So there's probably no issue. Where does this issue pop up?

A nuance could then be that we make x/y/t/bands mandatory for any collection that uses these 4 dimension

There are multiple way to get to 4 dimensions that are not exactly this combination. And it would not cover any other usecase like vector data cubes, DGGS in the future, etc.

Dimension types are more strictly specified than names (e.g. the datacube STAC extension defines type "temporal" for time dimension). Unfortunately, the datacube extension does not define a "bands" type

That could just be an alternative to the name. The type things fails once you have e.g. two temporal dimensions. Then you'd have to fall back to dimension names again.

---

The main issue is that in OpenAPI we can't easily enforce these values (except maybe x and y), but we could enforce or warn in the test suite though. That could already be done with the recommendation though.
Whether the change in a OpenAPI description from recommended to required is actually helping, I'm not sure. It gives a better position in discussions, but other than that? Don't get me wrong, I'm not really against requiring certain names for certain dimension types. But it's also a breaking change, so requires a v2 of the API specification. Thus my first attempt would be to make the language stronger, expand to more dimension types, and make it more prominent. Currently the dimension names are pretty hidden in an OpenAPI description. Additionally, we could enhance the test suite and maybe even warn in the clients...

[soxofaan]

That could just be an alternative to the name. The type things fails once you have e.g. two temporal dimensions. Then you'd have to fall back to dimension names again.

I've never seen a use case with two temporal dimensions so far, while I've seen already multiple variants of the question "what is the correct name of the temporal dimension?". So I would consider the latter problem the most important one. And indeed, when one would have multiple temporal dimensions, the user is indeed expected to resolve the ambiguity by using the name instead of type.

---

Another possibility would be to introduce the concept of aliases or common names (as used for band names).

---

the problem has gotten worse.

Could you give an example?

If I remember correctly, I think we got cases of this when working out https://github.com/Open-EO/openeo-test-suite

I think it also pops up in use cases that support some kind of switching betweenload_collection of backend-controlled openEO collections and load_stac of less controlled STAC resources.

[emmanuelmathot]

My preference is option 3 and make dimension names programmatically discoverable rather than enforcing a convention.

That's also the motivation behind #590: if a backend could expose canonical dimension names as resolvable parameters, a UDP could reference {"from_parameter": "time_dimension"} and the backend injects the right name at execution time. We've built this as a workaround in openeo-udp via a ParameterManager that injects the correct name per-backend, but this logic belongs in the clients, not user code.

This would also combine well with @soxofaan's alias proposal: "temporal" as a type alias is the interface; backend-to-name resolution via a capability field (e.g. "dimension_names": {"temporal": "t"}) is the implementation. No breaking change.

[m-mohr]

My preference is option 3 and make dimension names programmatically discoverable rather than enforcing a convention.

I don't understand. The dimension names are exposed in the Collection metadata (cube:dimensions)?!

[soxofaan]

My preference is option 3 and make dimension names programmatically discoverable

with programmatically you mean here purely in the context of backend-side process graph evaluation, without any additional client involvement? Because the names are already discoverable (e.g. client/user side) from collection metadata.

Also: the programmatic discovery implies you have something else you want to resolve to a dimension name? So what would that be the input be here in this case, the dimension type ?
And then you also need new processes and resource definitions to express querying of the collection metadata within a process graph.

I think it's just a lot simpler to expand the scope of the dimension argument of reduce_dimension and alike to also accept the dimension type (or alias, or common name) in addition to the current direct name. No need for additional processes or backend-side collection metadata inspection features.

[emmanuelmathot]

Sorry, "discoverable" was not the right term, I meant "resolvable". Indeed, datacube extension in STAC resolves the dimension name source of truth but then we still have to find a way to retrieve it at execution time.