diff --git a/CHANGELOG.md b/CHANGELOG.md index 41262bc..edad7d5 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 8c0ea77..b68ba09 100644 --- a/README.md +++ b/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 diff --git a/examples/dggs.json b/examples/dggs.json new file mode 100644 index 0000000..fd157df --- /dev/null +++ b/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" + } + ] +} diff --git a/json-schema/schema.json b/json-schema/schema.json index 10554cc..e8519db 100644 --- a/json-schema/schema.json +++ b/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",