Suggestions from Fuhu's Team - Suggestion 3 - Some suggested zone query related endpoints

[geofizzydrink]

Fuhu's Team have been exploring the use and application and exposure of back-end DGGS zone query operations directly through the API. The above diagram shows three (3) proposed conformance classes related to this

1. Zone Retrieval

   • this appears to be based on implementing a similar concept to that of OGC API EDR
   • A question for us to ask and resolve here is: "can this functionality be achieved directly through an implementation of OGC API EDR?" If so, then we should not specifically define a DGGS variant of this. If not, or there are fundamental differences in how these endpoints would work between an OGC API EDR perspective vs a OGC API DGGS perspective, then we should consider an additional optional conformance class as suggested here (possibly as an extension to the core API Spec - e.g. Part 2)

2. Zone Geometry

   • This is basically exposing the direct back end DGGS zone geometry operations following the DE-9IM operation described in ISO 19170-1 / OGC AS Topic 21 v2.0
   • While for the core standard we (as a group) have moved away from this (originally proposed during OGC Testbed-16) in favour of the more data centric operations instead of the DGGS centric operations, there is merit in exposing these operations directly through the API - particularly for education settings.
   • We could expose these endpoints as a separate optional conformance class and/or as an additional Part to the spec (e.g. include in a Part 2 - DGGS Operations spec)

3. Zone Query

   • These are another set of DGGS centric zone query operations that are not just focused on the DE-9IM relationships
   • A key question for us to resolve here is are the functionalities presented by these proposed endpoints achievable using the current "Zone Query" conformance class (leveraging url query parameters and OGC API Features - Part 3 Filtering operations)?
     • If the answer to this is yes, then I'd say that we don't need to define these endpoints explicitly. In this case, it would be good for us to work up example applications of the .../zones endpoint that covers off on all of these operations.
     • If, for any of these proposed endpoints, the answer is no then we should define that endpoint to provide the appropriate Zone Query functionality that is missing from the .../zones endpoint.

[ogcscotts]

@geofizzydrink and SWG: do you see each of these requirements classes as equating to 3 independent building blocks which could be uniquely implemented, or would you bundle them together to a single query and retrieval block specific to a DGGS? I suppose the answer depends on whether some or all of the functionality can be brought over from other OGC APIs.

[geofizzydrink]

Hi @ogcscotts, I think that wherever possible we should leverage existing APIs to achieve the functional outcomes DGGS implementers need. And so, given the suggestions/proposals from Fuhu's team we should as a group review these in this this context. So my initial thoughts on each of these proposed conformance classes are:

"zone retrieval"

• This is similar in scope to OGC API EDR Data Queries. So if the DGGS-centric functionality for these endpoints can be achieved using straight OGC API EDR then I would suggest that is the best way to go. If, however, we need to do something different (that is more DGGS specific) then we could propose this conformance class as a separate part to the DGGS API standard (e.g. OGC API DGGS - Part 2 Zone Data Queries - or something similar).
• I don't think these endpoints would be useful as "building blocks" because as currently proposed they could cause confusion with the corresponding OGC API EDR endpoints.

"zone geometry"

• As I commented above these endpoints are an implementation of the DGGS application of the DE9-IM spatial relationships. In most data focused applications of DGGS the functionality expressed by these endpoints will be facilitated via backend functions - and in many cases there may be multiples of these functions performed as part of the Data Quantisation and Data Retrieval DGGS operations.
• This conformance class is useful for those wishing to demonstrate DGGS infrastructures and how they work in an educational setting. So I think it is worth us defining it (but as an independent optional conformance class that an implementer of OGC API DGGS can choose whether, or not, to build into their infrastructure).

"Zone Query"

• This one we will need to test against the functionality we can achieve by implementing OGC API Features - Part 3 Filtering.
• If, leveraging the Features API, we can achieve the functional outcomes of these proposed endpoints using the currently defined "zone query" conformance class then we should go with that and then draft a users guide to show how a user/implementer could achieve these query variants.
• If, for any of these, we just can't get the functionality by leveraging other OGC APIs then we should specify these in the OGC API DGGS spec - either by specifying additional query parameters or by adding new endpoints.

With the emergence and maturity being developed in the "OGC API Building Blocks" concept it will be useful for our group to take a look at the core DGGS API endpoints and where it makes sense we should propose some of the key DGGS endpoints to be included as OGC API Building Blocks.

[ogcscotts]

@geofizzydrink makes sense. Probably worth looping @ghobona and @doublebyte1 into the conversation.

[jerstlouis]

@geofizzydrink @ogcscotts Throwing in my thoughts:

1. Zone Data Retrieval

It is closer in many ways to OGC API - Tiles than EDR, but the main things that DGGS Zone Retrieval allows to do which cannot be done with any other OGC API is to retrieve data for DGGS whose cell geometry is not axis-aligned / not rectangular (like ISEA3H), which cannot be done with any of the other OGC APIs. If the DGGS is axis-aligned and cells are square (or rhombuses which can be skewed into rectangles), then a corresponding TileMatrixSet can be defined for it, and data for individual zones can be retrieved using OGC API - Tiles, and OGC API - Coverages with subset and downsampling for a selected resolution. It would also correspond to an EDR Cube Query, but at the moment EDR does not yet support downsampling, though it is being considered for an extension or revision I believe. Still, Zone Data Retrieval is an essential functionality of a DGGS (the What is here?) which is good to be implemented consistently regardless of the geometry / axis-alignment of the cells.

2. Zone Geometry

I think we should make the distinction between "zone geometry" (retrieving the geometry of a cell) vs. "DE-9IM operations between zones". I still believe the usefulness of both of these things in a Web API is limited to educational/demonstration, because in a practical setting those operations do not cross the client-server boundary (the client and the server use a software library to perform these operations). However, the zone geometry fits nicely being included in the "Zone Information" resource, which I think we could define in OGC API - DGGS Core, possibly as a recommendation. For example, we already include zone geometry in our server if negotiating GeoJSON for a zone information resource:

https://maps.gnosis.earth/ogcapi/collections/sentinel2-l2a/dggs/GNOSISGlobalGrid/zones/0-0-0?f=geojson

For the DE-9IM operation, if there is an interest in standardizing that, I think it should be done in a separate document. I re-iterate that there is limited use for this in a Web API, and it would be much, much more valuable to standardize this as an open-source DGGS abstraction software library API for DGGS instead (similar to how GDAL allows supporting any raster/vector format, interacting with this library would allow to implement DGGS support, including OGC API - DGGS data retrieval / Zone Query, in a DGGS-agnostic way by using this library).

3. Zone Query

The purpose of this is an efficient "Where is it?" query that returns a response as compact zone listing, which is valuable for clients or server understanding a particular DGGS. It could be used as a way to reduce the number of Zone Data queries to retrieve the results of a computation (only making requests for those zone where there is data), or it could also be used to retrieve the actual results of the computation if the answer to the query is binary (zone area included or not in the response set). This requirements class would be particularly useful for chained processing across multiple OGC API - DGGS services that all understand the same grid. While it is a different end-point (/dggs/{dggsId}/zones) than Features (/items), it would re-use the filter building block from Features - Part 3: Filtering, as well as CQL2 as a way to express queries. filter could also be used with Zone Data as well. Also, properties= as a way to include an aggregation of the values or of derived fields for each zone is something that could be considered. For Data Retrieval, properties can select values to include, and also define derived fields. Whether filter and/or properties should be included in OGC API - DGGS - Part 1: Core or not is something we should discuss, possibly those could be separate requirements classes for Part 1. We also support properties and filter for Coverages/Tiles, and filter for Maps as well.