CoverageJSON Examples in OGC API - Coverages (and some feedback/questions)

[jerstlouis]

@jonblower @chris-little @m-burgoyne

Dear all,

I've added an Examples Annex to OGC API - Coverages with several example responses using CoverageJSON.

I would very much appreciate if you could find the time to review these examples.
So far I've validated them with the Playground. The data for now is synthetic, though I hope to eventually have more realistic examples along with pretty images, especially if I can manage to implement CoverageJSON in our server. Please ignore the old media type as I've already fixed that (should be picked up in the next document auto-generation update).

What worked great

The "ranges" as they're called (in OGC API - Coverages we would call that a single range with multiple fields) is quite straight forward and simple.

The "parameters" definitions (in OGC API - Coverages we would call them the fields) are also straight forward and simple, with the semantic definitions and units which is great.

I like the idea of being able to reference things even after you've sliced away their dimensions with the different domain types. I've used it in an example response for Position Query.

Though I have not yet illustrated them (I should), the "bounds" seem well aligned with the concept of cell bounds in OGC API - Coverages, the boundsCoordinates defined in OGC API - Common - Part 2 (Section 8.2.2 Irregular Grids) in particular.

What is causing some struggles

• Max 4D: It seems that at the moment CoverageJSON is limited to 4-dimensional grids. (EDIT: At least the "domainType": "Grid" is) Is that correct? That seems to be confirmed by Add support for an additional explicit dimension in the CoverageJSON schema #216 . I will comment on that issue, but from my perspective this limitation does not considerably help interoperability. Assuming support for additional dimensions is introduced, if each axis/dimension is well anchored to a clear semantic definition / standard variable. The common 1-4D use cases would keep working just as well as they always did. Perhaps a separate requirements class for >4D grid would address this.
• Fixed axis names: Somewhat related, I realized that I need to name the axes x, y, z and t. Again if each axis is clearly mapped to a semantic definition / standard variable, mandating these specific axis names should not be necessary, and not doing so would be much more flexible and extensible. We could have reflected the exact names used for referencing axes in OGC API - Coverages (e.g., Lat, Lon, time, pressure). Luckily, we recommend the definition of aliases which mostly match with those axis names.
• Pressure as parametric (not vertical): There is one notable mismatch which is pressure levels. We are forced to store the pressure levels in z. As Roger Lott mentioned previously: pressure levels from a surface would be referenced to a parametric CRS. Vertical CRS now is explicitly a geometric coordinate system in the earth's gravity vector. See the discussion in Register a parametric CRS for isobaric surface (air pressure)  NamingAuthority#228 where I attempted to make progress towards a parametric CRS for pressure levels, but eventually in OGC API - Common / Coverages we abandoned the idea of a "CRS" for non-spatial dimensions in favor of a simple ad-hoc semantic definition. I've used "type": "CoordinateSystem" for describing this pressure z axis (see this example), hoping that is OK practice rather than calling it a Vertical CRS.
• Textual dimensions: I could not figure out how to properly define a non-numeric textual dimension, such as a category or taxonomy. Please see this example where I've resorted to "z": { "values": [ 0.0, 1.0 ] }, and then at the same level as "axes":, "zAxisText:values": [ "Gadus morhua", "Clupea harengus" ], to describe Atlantic Cod = 0, Atlantic Herring = 1. I would much welcome feedback if there is a better way to do this, or for improved capabilities in a future version to deal with such scenarios.

Binary CovJSON?

I am a big fan of Universal Binary JSON.
In fact if I had more time on my hands, I would probably be pushing more for it to become an OGC Community Standard.
Given that the majority of the coverage data is inside the NdArrays, and UBJSON has optimized array serialization, the binary payload would be very optimal. It's also quite easy to start playing with UBJSON with several packages like py-ubjson and @shelacek/ubjson (for NPM Node & Web) available to effortlessly convert between JSON and UBJSON.

I am curious whether any of you has previously experimented with UBJSON, or with other JSON binary serialization (e.g., CBOR) for CoverageJSON?

Thank you very much in advance for any help you can provide reviewing these examples or considering making the standard more flexible!