Add DGGS dimension type

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Added `unit` field to more dimensions
+- Added a Spatial DGGS Dimension Object (`type: dggs`)
 
 ### Changed
 

README.md

@@ -13,6 +13,10 @@ It specifies datacube related metadata, especially their dimensions and potentia
 - Examples:
   - [Item example](examples/item.json): Shows the basic usage of the extension in a STAC Item
   - [Collection example](examples/collection.json): Shows the basic usage of the extension in a STAC Collection
+  - [Item asset example](examples/item_asset.json): Shows usage of the extension in Item Assets
+  - [Vector example](examples/vector.json): Shows a vector dimension with geometry metadata
+  - [Daymet HI annual example](examples/daymet-hi-annual.json): Shows a real-world Collection with datacube metadata
+  - [DGGS item example](examples/dggs.json): Shows usage of a DGGS-based spatial dimension in a STAC Item
 - [JSON Schema](json-schema/schema.json)
 - [Changelog](./CHANGELOG.md)
 
@@ -74,6 +78,36 @@ A spatial dimension in vertical (z) direction.
 
 A Vertical Spatial Dimension Object MUST specify an `extent` or `values`. It MAY specify both.
 
+### Spatial DGGS Dimension Object
+
+A spatial dimension based on a Discrete Global Grid System (DGGS).
+
+| Field Name       | Type           | Description                                                  |
+| ---------------- | -------------- | ------------------------------------------------------------ |
+| type             | string         | **REQUIRED.** Type of the dimension, always `dggs`. |
+| description      | string         | Detailed multi-line description to explain the dimension. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. |
+| extent           | \[number\]     | The spatial extent of the DGGS zones as a GeoJSON-style bbox: `[west, south, east, north]` or `[west, south, minz, east, north, maxz]`. |
+| values           | \[string\]     | An ordered list of DGGS zone identifiers. Useful when enumerating a known set of zones (for example, a tile index or explicit zone subset). |
+| resolution       | integer        | The DGGS refinement level used by the zone identifiers. Useful to state the hierarchy level explicitly when `values` are present. |
+| step             | integer\|null  | The spacing between refinement levels when multiple levels are represented. Use `null` for irregular level spacing. |
+| reference_system | string         | **REQUIRED.** Identifier of the DGGS reference system (DGGRS), preferably a URI. |
+
+It is RECOMMENDED that a Spatial DGGS Dimension Object specifies at least one of `extent` or `values`
+unless it would be equivalent to the bbox/extent in the containing Item/Collection.
+
+For DGGS dimensions, `reference_system` identifies the DGGS reference system (DGGRS), not a coordinate reference system (CRS).
+Values such as `https://www.opengis.net/def/dggrs/OGC/1.0/HEALPix` from the
+[OGC DGGRS Register](https://defs.opengis.net/prez/catalogs/ogc-cat:register/col/def:dggrs) are valid examples.
+
+Guidance for vertical information with DGGS:
+
+- Most DGGS implementations used in practice are surface-based (2D).
+- For elevation, depth, pressure level, or altitude, prefer a separate
+  [Vertical Spatial Dimension Object](#vertical-spatial-dimension-object) with `axis` set to `z`.
+- Use DGGS-only encoding of `z` only if the selected DGGRS natively defines volumetric zones and the zone identifiers represent those volumes.
+- In most interoperable STAC/datacube use cases, model horizontal partitioning as `dggs`
+  and vertical structure as a separate `z` dimension.
+
 ### Temporal Dimension Object
 
 A temporal dimension based on the ISO 8601 standard. The temporal reference system for the data is expected to be ISO 8601 compliant

examples/dggs.json

@@ -0,0 +1,90 @@
+{
+  "stac_version": "1.1.0",
+  "stac_extensions": [
+    "https://stac-extensions.github.io/datacube/v2.3.0/schema.json"
+  ],
+  "id": "datacube-dggs-123",
+  "type": "Feature",
+  "geometry": {
+    "type": "Polygon",
+    "coordinates": [
+      [
+        [
+          -10,
+          40
+        ],
+        [
+          10,
+          40
+        ],
+        [
+          10,
+          55
+        ],
+        [
+          -10,
+          55
+        ],
+        [
+          -10,
+          40
+        ]
+      ]
+    ]
+  },
+  "bbox": [
+    -10,
+    40,
+    10,
+    55
+  ],
+  "properties": {
+    "title": "DGGS-based data cube in a STAC Item.",
+    "datetime": "2024-01-01T00:00:00Z",
+    "cube:dimensions": {
+      "dggs": {
+        "type": "dggs",
+        "reference_system": "https://www.opengis.net/def/dggrs/OGC/1.0/HEALPix",
+        "resolution": 6,
+        "step": 1,
+        "values": [
+          "C1A",
+          "C1B",
+          "C1C"
+        ]
+      },
+      "time": {
+        "type": "temporal",
+        "extent": [
+          "2024-01-01T00:00:00Z",
+          "2024-12-31T23:59:59Z"
+        ],
+        "step": "P1M"
+      }
+    },
+    "cube:variables": {
+      "temperature": {
+        "dimensions": [
+          "time",
+          "dggs"
+        ],
+        "type": "data",
+        "unit": "K",
+        "data_type": "float32"
+      }
+    }
+  },
+  "assets": {
+    "data": {
+      "href": "http://cool-sat.com/catalog/datacube-dggs-123/data.zarr",
+      "type": "application/zarr",
+      "title": "DGGS Data cube"
+    }
+  },
+  "links": [
+    {
+      "rel": "self",
+      "href": "http://cool-sat.com/catalog/datacube-dggs-123/item.json"
+    }
+  ]
+}

json-schema/schema.json

@@ -209,6 +209,9 @@
       "type": "object",
       "additionalProperties": {
         "anyOf": [
+          {
+            "$ref": "#/definitions/dggs_dimension"
+          },
           {
             "$ref": "#/definitions/vector_dimension"
           },
@@ -261,7 +264,8 @@
           "not": {
             "enum": [
               "spatial",
-              "geometry"
+              "geometry",
+              "dggs"
             ]
           }
         },
@@ -447,6 +451,70 @@
         }
       }
     },
+    "dggs_dimension": {
+      "title": "Spatial DGGS Dimension Object",
+      "type": "object",
+      "required": [
+        "type",
+        "reference_system"
+      ],
+      "not": {
+        "required": [
+          "axis"
+        ]
+      },
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "dggs"
+        },
+        "description": {
+          "$ref": "#/definitions/description"
+        },
+        "extent": {
+          "title": "Spatial extent",
+          "description": "Bounding box of DGGS zones following GeoJSON bbox semantics: [west, south, east, north] or [west, south, minz, east, north, maxz].",
+          "type": "array",
+          "oneOf": [
+            {
+              "minItems": 4,
+              "maxItems": 4
+            },
+            {
+              "minItems": 6,
+              "maxItems": 6
+            }
+          ],
+          "items": {
+            "type": "number"
+          }
+        },
+        "values": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "description": "Zone identifier",
+            "type": "string"
+          }
+        },
+        "resolution": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "DGGS refinement level used by the zone identifiers."
+        },
+        "step": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 1
+        },
+        "reference_system": {
+          "type": "string",
+          "description": "Identifier of the DGGS reference system (DGGRS), preferably a URI. This is not a CRS."
+        }
+      }
+    },
     "temporal_dimension": {
       "title": "Temporal Dimension Object",
       "type": "object",