From 92a8a42ef6b7c74497003c9c4718e016ae75da06 Mon Sep 17 00:00:00 2001 From: rhysrevans3 Date: Thu, 16 Oct 2025 10:06:03 +0100 Subject: [PATCH 1/4] Replacing cube:variable with common bands. --- examples/daymet-hi-annual.json | 72 ++++++++++----------- examples/item.json | 12 ++-- examples/item_asset.json | 12 ++-- json-schema/schema.json | 112 +++++++++++++++------------------ 4 files changed, 99 insertions(+), 109 deletions(-) diff --git a/examples/daymet-hi-annual.json b/examples/daymet-hi-annual.json index 55e826a..25bd62c 100644 --- a/examples/daymet-hi-annual.json +++ b/examples/daymet-hi-annual.json @@ -82,106 +82,106 @@ ] } }, - "cube:variables": { + "bands": { "lat": { - "type": "auxiliary", - "extent": [ - 17.960035, - 23.512327 - ], + "cube:type": "auxiliary", + "statistics": { + "minimum": 17.960035, + "maximum": 23.512327 + }, "description": "latitude coordinate", "unit": "degrees_north", - "dimensions": [ + "cube:dimension_refs": [ "y", "x" ] }, "lon": { - "type": "auxiliary", - "extent": [ - -160.29884, - -154.77806 - ], + "cube:type": "auxiliary", + "statistics": { + "minimum": -160.29884, + "maximum": -154.77806 + }, "description": "longitude coordinate", "unit": "degrees_east", - "dimensions": [ + "cube:dimension_refs": [ "y", "x" ] }, "prcp": { - "type": "data", + "cube:type": "data", "description": "The total accumulated precipitation over the monthly period of the daily total precipitation. Sum of all forms of precipitation converted to a water-equivalent depth.", - "extent": [ - 0, - null - ], + "statistics": { + "minimum": 0, + "maximum": null + }, "unit": "mm", - "dimensions": [ + "cube:dimension_refs": [ "time", "y", "x" ] }, "swe": { - "type": "data", + "cube:type": "data", "description": "The average of the daily snow water equivalent (the amount of water contained within the snowpack) in kilograms per square meter over the monthly period.", - "extent": [ - 0, - null - ], + "statistics": { + "minimum": 0, + "maximum": null + }, "unit": "kg/m2", - "dimensions": [ + "cube:dimension_refs": [ "time", "y", "x" ] }, "tmin": { - "type": "data", + "cube:type": "data", "description": "The average minimum temperature for a daily period over the entire monthly period.", "unit": "degrees C", - "dimensions": [ + "cube:dimension_refs": [ "time", "y", "x" ] }, "tmax": { - "type": "data", + "cube:type": "data", "description": "The average maximum temperature for a daily period over the entire monthly period.", "unit": "degrees C", - "dimensions": [ + "cube:dimension_refs": [ "time", "y", "x" ] }, "vp": { - "type": "data", + "cube:type": "data", "description": "The average of the daily average partial pressure of water vapor over the monthly period.", "unit": "Pa", - "dimensions": [ + "cube:dimension_refs": [ "time", "y", "x" ] }, "time_bnds": { - "type": "auxiliary", + "cube:type": "auxiliary", "description": "", - "dimensions": [ + "cube:dimension_refs": [ "time", "nv" ] }, "lambert_conformal_conic": { - "type": "auxiliary", + "cube:type": "auxiliary", "description": "Lambert Conformal Conic.", - "values": [ + "cube:values": [ -32767 ], - "dimensions": [] + "cube:dimension_refs": [] } } } \ No newline at end of file diff --git a/examples/item.json b/examples/item.json index ef2d2a6..fc00ec7 100644 --- a/examples/item.json +++ b/examples/item.json @@ -98,22 +98,22 @@ ] } }, - "cube:variables": { + "bands": { "temp": { - "dimensions": [ + "cube:dimension_refs": [ "time", "y", "x", "pressure_levels" ], - "type": "data", + "cube:type": "data", "nodata": "nan", "data_type": "float32" }, "color": { - "dimensions": [], - "type": "auxiliary", - "values": [ + "cube:dimension_refs": [], + "cube:type": "auxiliary", + "cube:values": [ "red", "green", "blue" diff --git a/examples/item_asset.json b/examples/item_asset.json index 7d1ca17..597a9a8 100644 --- a/examples/item_asset.json +++ b/examples/item_asset.json @@ -104,20 +104,20 @@ ] } }, - "cube:variables": { + "bands": { "temp": { - "dimensions": [ + "cube:dimension_refs": [ "time", "y", "x", "pressure_levels" ], - "type": "data" + "cube:type": "data" }, "color": { - "dimensions": [], - "type": "auxiliary", - "values": [ + "cube:dimension_refs": [], + "cube:type": "auxiliary", + "cube:values": [ "red", "green", "blue" diff --git a/json-schema/schema.json b/json-schema/schema.json index 10554cc..b61c393 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -180,8 +180,26 @@ "require_any_field": { "$comment": "Please list all fields here so that we can force the existance of one of them in other parts of the schemas.", "anyOf": [ - {"required": ["cube:dimensions"]}, - {"required": ["cube:variables"]} + { + "required": [ + "cube:dimensions" + ] + }, + { + "required": [ + "cube:dimension_refs" + ] + }, + { + "required": [ + "cube:type" + ] + }, + { + "required": [ + "cube:values" + ] + } ] }, "require_field": { @@ -196,8 +214,17 @@ "cube:dimensions": { "$ref": "#/definitions/cube:dimensions" }, - "cube:variables": { - "$ref": "#/definitions/cube:variables" + "cube:dimension_refs": { + "$ref": "#/definitions/cube:dimension_refs" + }, + "cube:type": { + "$ref": "#/definitions/cube:type" + }, + "cube:values": { + "$ref": "#/definitions/values" + }, + "bands": { + "$ref": "#/definitions/bands" } }, "patternProperties": { @@ -227,12 +254,19 @@ ] } }, - "cube:variables": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/variable" + "cube:dimensions_refs": { + "type": "array", + "items": { + "type": "string" } }, + "cube:type": { + "type": "string", + "enum": [ + "data", + "auxiliary" + ] + }, "additional_dimension": { "title": "Additional Dimension Object", "type": "object", @@ -406,12 +440,12 @@ "type": "array", "oneOf": [ { - "minItems":4, - "maxItems":4 + "minItems": 4, + "maxItems": 4 }, { - "minItems":6, - "maxItems":6 + "minItems": 6, + "maxItems": 6 } ], "items": { @@ -426,7 +460,7 @@ "type": "string" } }, - "geometry_types": { + "geometry_types": { "type": "array", "uniqueItems": true, "items": { @@ -496,55 +530,11 @@ } } }, - "variable": { - "title": "Variable Object", - "type": "object", + "bands": { "required": [ - "dimensions" + "cube:dimensions_refs" ], - "properties": { - "variable_type": { - "type": "string", - "enum": [ - "data", - "auxiliary" - ] - }, - "description": { - "$ref": "#/definitions/description" - }, - "dimensions": { - "type": "array", - "items": { - "type": "string" - } - }, - "values": { - "type": "array", - "minItems": 1 - }, - "extent": { - "type": "array", - "minItems": 2, - "maxItems": 2, - "items": { - "type": [ - "string", - "number", - "null" - ] - } - }, - "unit": { - "$ref": "#/definitions/unit" - }, - "nodata": { - "$ref": "#/definitions/nodata" - }, - "data_type": { - "$ref": "#/definitions/data_type" - } - } + "$ref": "https://schemas.stacspec.org/v1.1.0/item-spec/json-schema/bands.json#bands" }, "type_spatial": { "type": "string", @@ -670,4 +660,4 @@ "type": "string" } } -} +} \ No newline at end of file From c9a63f2071ca3d8f7ede1a0801c13ea3b5297fbe Mon Sep 17 00:00:00 2001 From: rhysrevans3 Date: Thu, 16 Oct 2025 10:29:55 +0100 Subject: [PATCH 2/4] requiring cube:type for bands. --- json-schema/schema.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/json-schema/schema.json b/json-schema/schema.json index b61c393..a282af8 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -532,7 +532,8 @@ }, "bands": { "required": [ - "cube:dimensions_refs" + "cube:dimensions_refs", + "cube:type" ], "$ref": "https://schemas.stacspec.org/v1.1.0/item-spec/json-schema/bands.json#bands" }, From e9d37506cb4ec0bd6958ea67849fc76fdeec2331 Mon Sep 17 00:00:00 2001 From: rhysrevans3 Date: Thu, 16 Oct 2025 10:30:07 +0100 Subject: [PATCH 3/4] Update to README.md. --- README.md | 56 +++++++++++++++++++++++++++---------------------------- 1 file changed, 27 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 8c0ea77..691ac42 100644 --- a/README.md +++ b/README.md @@ -26,12 +26,34 @@ The following fields can be used in the following parts of a STAC document: - [x] Assets (both Collections and Items, incl. Item Asset Definitions in Collections) - [ ] Links -| Field Name | Type | Description | -| ---------------- | -------------------------------------------------- | ------------------------------------------- | -| cube:dimensions | Map | **REQUIRED.** Uniquely named dimensions of the datacube. | -| cube:variables | Map | Uniquely named variables of the datacube. | +| Field Name | Type | Description | +| -------------------- | -------------------------------------------------- | ------------------------------------------- | +| cube:dimensions | Map | **REQUIRED.** Uniquely named dimensions of the datacube. | -The keys of `cube:dimensions` and `cube:variables` should be unique together; a key like `lat` should not be both a dimension and a variable. +- [ ] Catalogs +- [ ] Collections +- [ ] Item Properties (incl. Summaries in Collections) +- [ ] Assets (both Collections and Items, incl. Item Asset Definitions in Collections) +- [x] [Bands](https://github.com/radiantearth/stac-spec/blob/master/commons/common-metadata.md#bands) +- [ ] Links + +| Field Name | Type | Description | +| -------------------- | ----------------- | ------------------------------------------- | +| cube:dimensions_refs | Array | **REQUIRED.** The dimensions of the variable. This should refer to keys in the cube:dimensions object or be an empty list if the variable has no dimensions. | +| cube:type | string | **REQUIRED.** Type of the variable, either data or auxiliary. | +| cube:values | Array | An (ordered) list of all values, especially useful for [nominal](https://en.wikipedia.org/wiki/Level_of_measurement#Nominal_level) values. | + +**cube:type**: The Variable `cube:type` indicates whether what kind of variable is being described. It has two allowed values: + +1. `data`: a variable indicating some measured value, for example "precipitation", "temperature", etc. +2. `auxiliary`: a variable that contains coordinate data, but isn't a dimension in `cube:dimensions`. + For example, the values of the datacube might be provided in the projected coordinate reference system, but + the datacube could have a variable `lon` with dimensions `(y, x)`, giving the longitude at each point. + +See the [CF Conventions](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#terminology) +for more on auxiliary coordinates. + +The keys of `cube:dimensions` and `bands` should be unique together; a key like `lat` should not be both a dimension and a band. ### Dimension Object @@ -125,30 +147,6 @@ You can distinguish the "Temporal Dimension" from an "Additional Dimension" by c So if the `type` equals `temporal` and `extent` is an array of strings/null, then you have a "Temporal Dimension", otherwise you have an "Additional Dimension". -### Variable Object - -A *Variable Object* defines a variable (or a multi-dimensional array). The variable may have dimensions, which are described by [Dimension Objects](#dimension-object). - -| Field Name | Type | Description | -| ---------------- | -------------------------| ----------- | -| dimensions | \[string] | **REQUIRED.** The dimensions of the variable. This should refer to keys in the ``cube:dimensions`` object or be an empty list if the variable has no dimensions. | -| type | string | **REQUIRED.** Type of the variable, either `data` or `auxiliary`. | -| description | string | Detailed multi-line description to explain the variable. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | -| extent | \[number\|string\|null\] | If the variable consists of [ordinal](https://en.wikipedia.org/wiki/Level_of_measurement#Ordinal_scale) values, the extent (lower and upper bounds) of the values as two-element array. Use `null` for open intervals. | -| values | \[number\|string] | An (ordered) list of all values, especially useful for [nominal](https://en.wikipedia.org/wiki/Level_of_measurement#Nominal_level) values. | -| unit | string | The unit of measurement for the data, preferably compliant to [UCUM](https://ucum.org) (unit code) or [UDUNITS-2](https://ncics.org/portfolio/other-resources/udunits2/) (unit symbol or alternatively singular unit name). | -| nodata | number\|string | Value used to identify no-data, see [common metadata](https://github.com/radiantearth/stac-spec/blob/v1.1.0/commons/common-metadata.md#no-data) for more details. | -| data_type | string | The data type of the values in the datacube, see [common metadata](https://github.com/radiantearth/stac-spec/blob/v1.1.0/commons/common-metadata.md#data-types) for more details. | - -**type**: The Variable `type` indicates whether what kind of variable is being described. It has two allowed values: - -1. `data`: a variable indicating some measured value, for example "precipitation", "temperature", etc. -2. `auxiliary`: a variable that contains coordinate data, but isn't a dimension in `cube:dimensions`. - For example, the values of the datacube might be provided in the projected coordinate reference system, but - the datacube could have a variable `lon` with dimensions `(y, x)`, giving the longitude at each point. - -See the [CF Conventions](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#terminology) -for more on auxiliary coordinates. ## Contributing From b891eb471ad65890f23b594dbefb2f49464dfc4c Mon Sep 17 00:00:00 2001 From: rhysrevans3 Date: Thu, 16 Oct 2025 10:40:29 +0100 Subject: [PATCH 4/4] Spelling mistake fix for dimension_refs. --- json-schema/schema.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/json-schema/schema.json b/json-schema/schema.json index a282af8..b82eb78 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -254,7 +254,7 @@ ] } }, - "cube:dimensions_refs": { + "cube:dimension_refs": { "type": "array", "items": { "type": "string" @@ -532,7 +532,7 @@ }, "bands": { "required": [ - "cube:dimensions_refs", + "cube:dimension_refs", "cube:type" ], "$ref": "https://schemas.stacspec.org/v1.1.0/item-spec/json-schema/bands.json#bands"