Feedback on 2.0 / Collections (CODE SPRINT JAN 2026)

[jerstlouis]

Requirement 53:

• that contain the collection parameter -- can we say property instead of parameter here (B also below)
• process input values are retrieved -- isn't this somewhat confusing to call this "input values"? We could say something like for "which data is retrieved for a specific input"? Since we have the concept of "process inputs", and a collection input retrieves data (bunch of values) for one specific input.
• C -- The SHALL here is not written from the server's perspective, and offers too much flexibility regarding relative URIs. Suggesting:

The server SHALL support both collection identifiers (for collections hosted on the same API as the Processes API) and absolute URIs of the collection description (but not sub-resources of the collection). This allows the server to decide, based on the expected input value type from the process description and other factors, which supported data access mechanisms should be employed to retrieved input values from the collection. (note the typo in retrieved)

• Suggesting we get rid of D in favor of the collectionIds option above
• Req. 54: retrieved typo again
• 8.1.3.2. Filtering -- We should add some informative text here that clarifies that with the use of Collection Output / Virtual Collections, these filtering / subsetting parameters would often NOT be specified in the execution requests, and instaed the server would automatically subset/filter as a direct result of what is being requested from the output/virtual collection.
• Requirement 56 (derived fields) -- This should be its own requirements/conformance class. Typos: dervied -> derived, correspoding missing an n.
• 8.2.2. Referencing a remote collection -- contain the collection parameter. collection property (in B also). C: Similar comment: The server SHALL support absolute URIs of a collection description (but not sub-resources of the collection).
• 8.3.1. Overview -- prameters missing an a. would need to be continuously be re-submitted. -- extra be
• 8.3.2. Parameter response -- clarify it's a query parameter (also in Req. 60 A)
• Permission 13: Condition 5, 6 profiles query parameter should be singular?

[fmigneault]

commenting on the suggestions

---

Req 53 C & D

In order to use only the Collection ID, I think there is a very strong assumption that a structure similar to the following is used:

• /ogcapi/collections/...
• /ogcapi/processes/...

That is a big assumption. The /processes endpoint could be at an entirely different level, making the plain ID very ambiguous. There could also be multiple ../collections endpoints on a server (here's an example on mine):

• https://hirondelle.crim.ca/dggs-api/collections/
• https://hirondelle.crim.ca/stac/collections/
• https://hirondelle.crim.ca/geoserver/ogc/dggs/v1/collections
• https://hirondelle.crim.ca/geoserver/ogc/coverages/v1/collections

I would personally vote for disallowing a plain ID.
It is clearer and better for traceability to always use the absolute URL, or at least a relative one, that can be resolved reliably to the absolute URL. The plain ID might not make it uniquely identifiable, which makes it a bad approach.

---

8.1.3.2. Filtering

That specific entry is for "collection input". It might be confusing to introduce "collection output" concepts at the same time (ie: jsut describe a "basic collection input" there, expand on the virtual/output case later).

The indication would make more sense in 8.3 with a cross-reference to 8.1.3.2 since it is when 8.3 is involved that it becomes relevant.

Note that similar details are somewhat indicated in the 8.3.1 Overview if you read between the lines. The explanation could be refined more explicitly there.

[jerstlouis]

@fmigneault

Regarding the Collection ID, that was implying a /collections/{collectionId} relative to the OGC API - Processes landing page.
If the /collections is somewhere else, it's technically on a "different server" and not local from the perspective of not being part of the same API, no? Then it requires to use a full absolute path, but also from the client's perspective, the client would not know that this is the "same server" so it would actually be handled by the Remote Collection requirements class? Relative URIs is what feels overly complicated to me, as it's not clear what they are relative to?

I agree it's simpler to only support absolute URIs, but the collectionId only option makes sense to me if you already makes a distinction for servers that only support "local" collections, since those are the /collections/{collectionId} under exactly the same root/landing page as /processes/{processId}. In your hirondelle.crim.ca examples, those would all be different servers so they would require the "Remote Collections" requirement class and full absolute URIs.

That specific entry is for "collection input".

Yes I know, but the fact that Collection Input appears first and expands on all the possible filtering parameters really gives out the wrong impression about how this was primarilty intended to be used. All these filtering / subsetting parameters are for special cases, and the general case really is to let the server itself automatically do the subsetting (especially for Collection Output, and in the case of the bbox and datetime query parameters, where subsetting automatically flows from the incoming data access requests). This is why I brought this up here that some context (informative text) should be added here, in the collection input section, so that a reader understands that there is often no need to provide any subsetting/filtering query parameters at all (in particular when combined with Collection Output).

[fmigneault]

it's technically on a "different server" and not local from the perspective of not being part of the same API

My examples show quite clearly that they are all on the same server (same hostname). From a client perspective, there is no distinction whether they are implemented "all as one" or by multiple micro-services (nor should it care). If the client wants to pass one of these collections as process input on the same server, it would certainly look "local" to them, but the process engine cannot figure out which one they meant.

Relative URIs is what feels overly complicated to me, as it's not clear what they are relative to?

It is very clear. It is relative to the endpoint the request is submitted to, therefore /processes/{processID}/execution in this case. If you want to point at a "local" collection, you could use either ../../../collections/{collectionID} or /ogcapi/collections/{collectionID} if your API endpoint is {hostname}/ogcapi/.... That is how every URL/path join is expected to work on the web.

expands on all the possible filtering parameters really gives out the wrong impression about how this was primarilty intended to be used

It is perfectly valid to use the filtering parameters without using the collection response defining a virtual collection. The process is simply ran over the matched/filtered content of the collection. That is not wrong, just a different way to execute.

It really takes a lot of effort to understand the complexity of the entire virtual collection execution method. I think it would be beneficial for readers to take one problem at a time.

It is just like the sync/async case that mixes everything currently. It makes it harder to interpret the different concepts and the flexibility of the API when it is all thrown together.

[jerstlouis]

@fmigneault

My examples show quite clearly that they are all on the same server (same hostname)

From the OGC API perspective, there is a clear "landing page" and this is what "local" was intended to mean... From the same landing page as the Processing API. Nothing to do with the hostname, and the backend servers could still be spread out as different proxies or sub-domain resolution as different servers.

If you want to point at a "local" collection, you could use either ../../../collections/{collectionID} or /ogcapi/collections/{collectionID} if your API endpoint is {hostname}/ogcapi/...

I would definitely opt against any kind of relative URIs. While I understand relative to the execution endpoint makes some sense, when you read an execution request (or more complex workflow definition), you might not immediately see the execution endpoint so it is really overcomplicating things. If you don't like the simpler collectionId only let's just always require the full absolute URIs, and servers who want to just support collectionId can do so as a custom behavior.

But we still need the distinction of "local" vs "remote" server and even though those collections are on hirondelle.crim.ca, if they are not within the same landing page as the Processes API, then the server would need to declare conformance to "Remote Collections" so that the client knows that it can reference those collections. It should be OK for the server to only accept references to the CRIM collections (and/or to other pilot participants for example) if you have some checks/security in place, but it still relies on the "Remote Collections" requirements class.

It is perfectly valid to use the filtering parameters without using the collection response defining a virtual collection.

Yes, I am not saying otherwise.

It makes it harder to interpret the different concepts and the flexibility of the API when it is all thrown together.

Yes, but what I'm pointing out here is that throwing all the filtering parameters at the user before explaining that one of the main advantage of collection input (the primary one in my opinion) is to let the server automatically subset based on client requests is not ideal. Then readers start to think they need to formulate bbox and so on and really will not understand the point of all this.

Perhaps if we had the Sync, Async and Collection Output execution modes as requirements classes before Collection Input that might address the issue.

It really takes a lot of effort to understand the complexity of the entire virtual collection execution method.

If we explain it right it really should not be so difficult...
Since the input is exactly the opposite of the output, it shouldn't really matter which one we explain first.
It's really as simple as data going into the process and out of the process through OGC APIs for data access.
I think most of the difficulty is for people very used to batched processing having to think about a different way to do things. I don't think it's conceptually "complex", and I think we ironed out most of the details quite well already with the dataAccessAPIs etc. Of course it would be nice to manage more TIEs between multiple servers. And yes there might be some work to fit this collection output mode into an existing processing engine.

[fmigneault]

From the same landing page as the Processing API.

As far as I am aware, Landing Page does not explicitly indicate that any such structure for processes, collections, etc. must be followed. The {root} part is purposely flexible. There is only a recommendation in Collection Requirement to implement landing page, but even then, it does not force a specific structure, just that the link is present, and which could point anywhere (including another server). Also, you could have multiple links with rel: https://www.opengis.net/def/rel/ogc/1.0/data to discover multiple collection endpoints, so it still remains ambiguous with just an ID. Therefore, this undefined "local" concept is not reliable.

might not immediately see the execution endpoint so it is really overcomplicating things

If it is too complicated to resolve a relative path, magically discovering it from just the ID is even more complex. If you only care just about the ID anyway, you can always uri.rsplit("/")[-1] it and job done.

If using proper relative-URI, but you worry about the relative/positioning resolution, that is what the /ogcapi/collections/col variant is for (note the prefix /). That forces replacing any path by the provided one, and starting back from the hostname. Therefore, you can ignore whether it is submitted on /processes/test, ogcapi/processes/test, /ogcapi/processes/test/execution, or any other endpoint since it will always result to /ogcapi/collections/col.

let's just always require the full absolute URIs

Currently, the collection URI (whether relative or absolute), works just like an href input. It is pure URL resolution, so no reason to force absolute URIs either. It either resolve with the request context or not. And if relative-URI causes issues later in the processing engine, it should be the job of the API receiving the request to normalize the URIs as absolute before passing them to the engine.

But we still need the distinction of "local" vs "remote" server and even though those collections are on hirondelle.crim.ca, if they are not within the same landing page as the Processes API, then the server would need to declare conformance to "Remote Collections"

My server supports them, but for actual remote collections (as in on a different server, which implies staging remote data). I really don't like this wording of "Remote" for different path mappings on the same server, as it misdirects about the interpretation. Even though the services on CRIM server do not reside on the same "local/common root" that you describe, there is internal logic to map them together to allow local collections/processes interactions as if they were a "single API", without any remote data staging, even though they use different endpoints. For all intent and purpose, they are "local" from the point of view of the client.

Then readers start to think they need to formulate bbox and so on and really will not understand the point of all this. Perhaps if we had the Sync, Async and Collection Output execution modes as requirements classes before Collection Input that might address the issue.

Maybe there should be a generic section before all of them. I really consider Virtual/Output Collection more like an "execution method" like sync/async, rather than an "output" in the same sense as the usual value/href. A foreword section about the execution modes/paradigms could introduce them and provide the nuances about filtering parameters.

I think the "basic use" of Collection Input + Filters is just as important as the Virtual Collection execution, because it is easier to plug in the execution body without worrying about the specific OGC API request pattern of a given data access mechanism.

If we explain it right it really should not be so difficult...

I recall quite a lot of very lengthy GitHub threads between us for me trying to understand what is happening, so I can understand what to implement. I can't imagine others figuring out all the finer details without going through all the same questions 😅

I think most of the difficulty is for people very used to batched processing having to think about a different way to do things. I don't think it's conceptually "complex"

This is exactly why. Indeed, it is not complex once you understand the behavior, but it is a completely opposite way of thinking from every other execution I/O parameter described in the document. This is why introducing it within a conformance classes using a different execution paradigm just creates confusion.

[jerstlouis]

@fmigneault

for actual remote collections (as in on a different server, which implies staging remote data). I really don't like this wording of "Remote" for different path mappings on the same server, as it misdirects about the interpretation

There's no way from the client perspective to know that things are on the "same server" or "different server".
Basing it on the host name is even more arbitrary than not within the same landing page. So I'm not sure how we would make that local / remote distinction at all if not basing it on under the same landing page root. I think it's very reliable and clear if we say that "local" refers to the collections at /collections/{collectionId} where / refers to the landing page of the Processes API (ignoring any link relations), and I think it's the only way we can make the distinction. It's perfectly fine for the server implementation to optimize access to the collections on the same domain as if they were local if it recognizes to actually be on the same server or is aware of a more direct access path to the data, regardless of the host name or path the collection happens to be at.

I really consider Virtual/Output Collection more like an "execution method" like sync/async,

I fully agree with that, and that is in line with splitting sync and async from core and having those three executions methods req. classes next to each other. A particular process could support any or all of those three.

A foreword section about the execution modes/paradigms could introduce them and provide the nuances about filtering parameters.

That would be a good place to include it (and maybe also a note as well inside the Collection Output mode itself).

I think the "basic use" of Collection Input + Filters is just as important as the Virtual Collection execution, because it is easier to plug in the execution body without worrying about the specific OGC API request pattern of a given data access mechanism.

Well for Collection Output, you really don't want to hardcode in the execution request things like the bbox that should flow from the data access, so that the workflow is valid for any AoI and the client fetching its current AoI automatically sets up the right subsetting. So it depends on the use case really, and we might have different opinions about the ideal execution patterns going forward (Collection Output is ideal for DGGS, since you can request data at multiple scales and/or for root zones in parallel -- i.e., processing sub-zones of a root zone at some relative depth).

[fmigneault]

There's no way from the client perspective to know that things are on the "same server" or "different server".

That is why I don't like the wording "local/remote" at all in that "landing page" context. It is for the server to decide what is local/remote, so the whole separation of their definition based on any URI is quite abstract if not useless in the first place.

IMO, what matters is "does the server need to fetch data from elsewhere to do the processing or not". Is the processing done "close to the data or not", as there is some data transfer considerations with additional steps which implies legal, financial, security, traceability, etc. challenges. That is the only purpose to advertise "remote collection" conformance support. It provides a way for the server to tell clients that it is able to handle collections from other servers, not just defined/managed by itself, so it does not depend only on "locally" available data, regardless how that is mapped under the hood. That allows distinguishing that server from a standalone application that will, for example, refuse external data inputs for security or whatever.

However, how such collection references gets resolved does not matter if it is "local", "remote", "landing page", or some other path. A URI is always valid. So why make the Collection ID any more special based on the "landing" location or whatever? We really don't care. What matters is that given a URI, relative or absolute, you have a valid resource identifier that can always be resolved to a given location within the request context, and the server knows what to do with it afterwards, whether that includes downloading data, load from DB access, from FS access, etc.

---

Well for Collection Output, you really don't want to hardcode in the execution request things like the bbox [...]

I would argue that it could still be used for Collection Output, for example, to set up default values that must always be set, or define AOI/TOI limits, if the operation that invokes the process via the collection later omits any corresponding parameters. For sure, if you want to allow the flexibility over parameters to be passed down dynamically, you would omit them (or maybe not, as they could still override anyway?).

All in all, I don't think it is black and white. Lots of grey areas, hence why it should be a separate section, which Collection Input/Output can reference, and which will be easier to find in the TOC.

[jerstlouis]

@fmigneault

It provides a way for the server to tell clients that it is able to handle collections from other servers, not just defined/managed by itself,

That is precisely the only purpose of the local / remote collection distinction.

If the server does not advertise support for Remote Collections, then the client can only reference collections from that exact API deployment.

The way that is defined is as being under the landing page (not under the same same domain name, which could host different API deployments that may or may not be "local" from the server's perspective).

[fmigneault]

If we consider that different "servers" are defined by their "landing page" root location (even though they might be implemented literally from the same code, running on the same machine, and accessing the same database, but just happen to have different path prefixes), they would need to declare Remote Collections conformance to transfer collection references between each other, even though they cannot connect to others beside themselves?

Doesn't that exactly contradict the "only purpose of the local / remote collection distinction" regarding telling clients what it can and cannot do? That API must purposely indicate incorrectly to clients that it will handle other collections (eg: one on Ecere's server), although it won't as it is limited to its specific DB connection?

And then, for CRIM's OGC API - Processes implementation that is always a side service to these collections (so I do not have to reimplemented everything in each of them), it cannot by definition support Collection Input because of Requirement 53 specifically about "local collection", nor Remote Collections as it has the previous Collection Input as prerequisite that cannot be fulfilled?

That doesn't make any sense. It seems to me there is a mixture of capabilities/definition here with an overloaded "local" term.

OGC APIs are flexible and extensible with each other by design, but you are not allowed to use other path patterns than the specific "landing page" structure, or else these conformance classes are meaningless?

I have a strong impression that "local" is a very poor choice of term to refer to the "path relatively to landing page" concept (and all of it is avoided altogether simply by using the only valid URI Identifier).

[jerstlouis]

If we consider that different "servers" are defined by their "landing page" root location (even though they might be implemented literally from the same code, running on the same machine, and accessing the same database, but just happen to have different path prefixes), they would need to declare Remote Collections conformance to transfer collection references between each other, even though they cannot connect to others beside themselves?

Yes.

Doesn't that exactly contradict the "only purpose of the local / remote collection distinction" regarding telling clients what it can and cannot do?

No.

although it won't as it is limited to its specific DB connection?

There is no visibility to the outside world that these services under different landing page share a DB connection.

And then, for CRIM's OGC API - Processes implementation that is always a side service to these collections (so I do not have to reimplemented everything in each of them), it cannot by definition support Collection Input

I'm not following... You can either somehow package support for serving collections together with your OGC API - Processes implementations and deploy it together, or you can rely on "Remote Collections" with the caveat that only specific remote collections (those sharing the DB connection e.g., from the same domain) are supported.

It seems to me there is a mixture of capabilities/definition here with an overloaded "local" term.

The local term only had one meaning: the collections under the same landing page as the Processes API.
You are overloading it with a different meaning that clients have no visibility into: other APIs having access to the shared DB connection.

all of it is avoided altogether simply by using the only valid URI Identifier.

That does not solve anything at all.
It seems that you keep assuming that "if the collection is hosted on the same domain, then it can share the same DB connection".
That is not always the case.

[fmigneault]

Collection Input explicitly indicates in its requirements that it is to reference a "local collection" (not any collection).
By definition, my server does not have "local collections" according to the landing-page structure.
Remote Collections has the prerequisite of Collection Input.

Therefore, by dependency, since "local collection" is enforced in Collection Input, it is virtually impossible for my server to factually declare conformance to either local/remote collection without purposely ignoring these "local" constraint.

There is technologically absolutely no blocker to support collection, but the "local" term unnecessarily imposes a constraint (landing-page structure) that is not necessary to support collections.

It seems that you keep assuming that "if the collection is hosted on the same domain, then it can share the same DB connection".

I didn't say that. You are misinterpreting my comments.

I said that given a URI, you can always resolve the specific collection that is being referenced, regardless of it being a "local collection" or a "remote collection", regardless of it residing on the same domain or not, regardless of the API path, regardless how it works on the backend. It is an unnecessary distinction for the collection URI resolution, since as previously established, what is actually "on the same server" is entirely up to its own implementation.

It is not necessary to tie "landing page" structure with "local/remote" collection (is data transferred) concepts.

If I configured an HTTP redirect from hirondelle.crim.ca/collections/ to https://www.eodms-sgdot.nrcan-rncan.gc.ca/stac/collections/, while hirondelle.crim.ca/processes/ remained on CRIM infrastructure redirecting to /weaver/..., I would absolutely need to transfer data from EODMS locally to do the processing. Therefore, according to "landing-page", it "looks like" a "local collection" purely based on API paths, but completely misleads the client since there is inevitably data transfer. There is no purpose to distinguish local/remote in that case, since it is unreliable anyway.

If I used only rcm-ard, it works only if hirondelle.crim.ca/collections/ and hirondelle.crim.ca/processes/ are used specifically. It is limiting, and any other endpoint is ambiguous.

Instead, using any of the below, I can ALWAYS resolve the specific collection URI, because it is purely based on HTTP URI resolution, not some abstract "local" concept.

• https://hirondelle.crim.ca/collections/rcm-ard
• /collections/rcm-ard (landing-page location)
• ../../../collections/rcm-ard (submitted to /processes/{p}/execution)
• /weaver/collections/rcm-ard
• ../../../../collections/rcm-ard (submitted to /weaver/processes/{p}/execution)
• ../collections/rcm-ard (submitted to /jobs - Part 4)

Therefore, just like a href input, there is no advantage to support some abstract "ID" reference. The collection input should simply and always be a URI, and the Collection Input "local" constraint should be removed.

[jerstlouis]

@fmigneault

Therefore, by dependency, since "local collection" is enforced in Collection Input, it is virtually impossible for my server to factually declare conformance to either local/remote collection without purposely ignoring these "local" constraint.

Maybe we can review the wording, but conceptually this should not be an issue.
Your server does support "Collection Input" so the dependency is fine -- there are simply not any "local" collections available :)

Therefore, just like a href input, there is no advantage to support some abstract "ID" reference. The collection input should simply and always be a URI, and the Collection Input "local" constraint should be removed.

There is, in my opinion, value in the concept of a "local" collection in the context that some products can deploy an OGC API instance that provides both access to data and processing capabilities for that data under the same API landing page. That is what "local collections" was all about. This is irrelevant for products that do not support such deployment model. For them, all collections input will always be "remote" (even though they may be able to access the data locally for some collections on the same domain or from some particular domain(s) without going through HTTP requests).

We can potentially forget about the collectionId short-hand and always use URIs (though I'm still not a fan of relative URIs inside execution requests). But from the conformance perspective, I still think it is valuable to have this concept of "collections available from within this API deployment which also provides processes", even though it is not currently applicable to your solutions.

[fmigneault]

I guess if the "local" term is removed from Collection Input to make it a transversal concept, it would work. The subsections of Remote Collection are all cross-references to their Collection Input counterpart, highlighting that they are "the same concepts".

Then, there could be a Permission that says something along the line of:

Important

• A collection relative to the landing-page may be referenced by Collection ID instead of a URI
• In such case, the {collectionID} MUST be resolved as {root}/collections/{collectionID}, where {root} represents the landing-page of the corresponding {root}/processes server.

I would be fine with ⬆️ since it avoids the "local" term easily misinterpreted based on one's definition of "local server", and it is just more explicit about the actual requirement relative to how collectionID is mapped.

Then, I am not blocked by the current "local" ambiguity, and I can even point at the specific requirement/permission link if someone passes collection: {collectionID} to help explain the error my server would raise.

[jerstlouis]

@fmigneault Yes that is all that this was intended to say (what was meant by "local"). I'm happy if we either clearly spell out that this is all that is meant by local in this context, or if we avoid the term local altogether because it introduces too much confusion.

That would need to be a Requirement that the server supports such collectionId short-hand (only when applicable i.e. there actually are collections available at {root}/collections) rather than a permission though (so that clients can rely on this).