From 979e5f252b5e5bcd4821e3fcc3ebdf19b0afe3d1 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Tue, 25 Mar 2025 16:43:10 +1300 Subject: [PATCH 01/32] Use of CF names for fields. Adding a vertical definition object --- README.md | 25 +++++++++++---- examples/collection.json | 50 +++++++++++++++++------------ examples/item.json | 24 ++++++++------ examples/standalone_collection.json | 36 ++++++++++++++++----- json-schema/schema.json | 49 +++++++++++++++++++++++++--- 5 files changed, 136 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 725efee..5b8008e 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # CF Extension Specification - **Title:** CF -- **Identifier:** +- **Identifier:** - **Field Name Prefix:** cf - **Scope:** Item, Collection - **Extension [Maturity Classification](https://github.com/radiantearth/stac-spec/tree/master/extensions/README.md#extension-maturity):** Proposal @@ -36,7 +36,7 @@ The fields in the table below can be used in these parts of STAC documents: #### cf:parameter The `cf:parameter` array is used to describe the parameters in an Asset or Collection. -It requires at least one entry with a non-empty name. +It requires at least one entry with a non-empty standard_name and units entry. This enables clients to read the file and understand which parameters are available. If assets with a `cf:parameter` array are provided, the field may optionally be used in the @@ -50,13 +50,26 @@ clients should rely on the `cf:parameter` of each asset, if available. #### CF Object +This object should contain a standard_name variable from the [CF list](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) and where applicable a unit from the [UDUNITS-2 database](https://docs.unidata.ucar.edu/udunits/current/) + +| Field Name | Type | Description | +| ------------------ | ------ | ----------- | +| standard_name | string | **REQUIRED**. Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html). | +| long_name | string | The long_name attribute is defined by the [NUG] to contain a long descriptive name which may, for example, be used for labeling plots. See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. | +| units | string | **REQUIRED**. The units attribute can be recognized by the UDUNITS package [UDUNITS](https://cfconventions.org/cf-conventions/cf-conventions.html#UDUNITS). If the variable is dimensionless then the value is set to 1. See [CF Units](https://cfconventions.org/cf-conventions/cf-conventions.html#units) for more details. | +| cell_methods | string | This is a string attribute comprising a list of blank-separated words of the form "name: method". Each "name: method" pair indicates that for an axis identified by name, the cell values representing the field have been determined or derived by the specified method. For example, if data values have been generated by computing time means, then this could be indicated with cell_methods="t: mean", assuming here that the name of the time dimension variable is "t". See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. | +| vertical_dimension | [Vertical Dimension Object](#Vertical-Dimension-object) | | + +#### Vertical Dimension Object + This object should contain a variable name from the [CF list](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) and where applicable a unit from the [UDUNITS-2 database](https://docs.unidata.ucar.edu/udunits/current/) -| Field Name | Type | Description | -| ---------- | ------ | ----------- | -| name | string | **REQUIRED**. Should be a non-empty value from the CF standard names list | -| unit | string | Indicates the unit, preferably available in the database from the UDUNITS-2 package (unidata) | +| Field Name | Type | Description | +| ----------------- | ------ | ----------- | +| standard_name | string | **REQUIRED**. As per \[[CF Object](#CF-object)\] definition above. | +| long_name | string | As per \[[CF Object](#CF-object)\] definition above. | +| units | string | **REQUIRED**. As per \[[CF Object](#CF-object)\] definition above. | ## Contributing diff --git a/examples/collection.json b/examples/collection.json index 3b69ed5..68432f3 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -33,25 +33,27 @@ "type": "application/netcdf", "cf:parameter": [ { - "name": "sea_surface_temperature", - "unit": "K" - }, - { - "name": "depth", - "unit": "m" + "standard_name": "sea_surface_temperature", + "long_name": "Average temperature on sea surface for preceding 24 hours", + "units": "K", + "cell_methods": "t: mean (interval: -24h)" } ] }, - "sea_ice_surface_temperature": { + "f10_1h_min": { "type": "application/netcdf", "cf:parameter": [ { - "name": "sea_ice_surface_temperature", - "unit": "K" - }, - { - "name": "depth", - "unit": "m" + "standard_name": "wind_speed", + "long_name": "minimum wind speed in 1 hour at 10 m agl", + "units": "kt", + "cell_methods": "t: minimum (interval: -1 h)", + "vertical_dimension": { + "standard_name": "height", + "long_name": "Height above ground level", + "units": "m", + "vertical_distance": "10" + } } ] } @@ -63,16 +65,22 @@ }, "cf:parameter": [ { - "name": "sea_surface_temperature", - "unit": "K" + "standard_name": "sea_surface_temperature", + "long_name": "Average temperature on sea surface for preceding 24 hours", + "units": "K", + "cell_methods": "t: mean (interval: -24h)" }, { - "name": "sea_ice_surface_temperature", - "unit": "K" - }, - { - "name": "depth", - "unit": "m" + "standard_name": "wind_speed", + "long_name": "minimum wind speed in 1 hour at 10 m agl", + "units": "kt", + "cell_methods": "t: minimum (interval: -1 h)", + "vertical_dimension": { + "standard_name": "height", + "long_name": "Height above ground level", + "units": "m", + "vertical_distance": "10" + } } ] }, diff --git a/examples/item.json b/examples/item.json index 582dc9c..6f1dd59 100644 --- a/examples/item.json +++ b/examples/item.json @@ -42,18 +42,24 @@ "datetime": "2020-12-11T22:38:32Z", "cf:parameter": [ { - "name": "sea_surface_temperature", - "unit": "K" + "standard_name": "sea_surface_temperature", + "long_name": "Average temperature on sea surface for preceding 24 hours", + "units": "K", + "cell_methods": "t: mean (interval: -24h)" }, { - "name": "sea_ice_surface_temperature", - "unit": "K" - }, - { - "name": "depth", - "unit": "m" + "standard_name": "wind_speed", + "long_name": "minimum wind speed in 1 hour at 10 m agl", + "units": "kt", + "cell_methods": "t: minimum (interval: -1 h)", + "vertical_dimension": { + "standard_name": "height", + "long_name": "Height above ground level", + "units": "m", + "vertical_distance": "10" + } } - ] + ] }, "links": [ { diff --git a/examples/standalone_collection.json b/examples/standalone_collection.json index c90c181..260dc04 100644 --- a/examples/standalone_collection.json +++ b/examples/standalone_collection.json @@ -30,12 +30,22 @@ }, "cf:parameter": [ { - "name": "sea_surface_temperature", - "unit": "K" + "standard_name": "sea_surface_temperature", + "long_name": "Average temperature on sea surface for preceding 24 hours", + "units": "K", + "cell_methods": "t: mean (interval: -24h)" }, { - "name": "depth", - "unit": "m" + "standard_name": "wind_speed", + "long_name": "minimum wind speed in 1 hour at 10 m agl", + "units": "kt", + "cell_methods": "t: minimum (interval: -1 h)", + "vertical_dimension": { + "standard_name": "height", + "long_name": "Height above ground level", + "units": "m", + "vertical_distance": "10" + } } ], "assets": { @@ -43,12 +53,22 @@ "href": "https://example.com/examples/example.nc", "cf:parameter": [ { - "name": "sea_surface_temperature", - "unit": "K" + "standard_name": "sea_surface_temperature", + "long_name": "Average temperature on sea surface for preceding 24 hours", + "units": "K", + "cell_methods": "t: mean (interval: -24h)" }, { - "name": "depth", - "unit": "m" + "standard_name": "wind_speed", + "long_name": "minimum wind speed in 1 hour at 10 m agl", + "units": "kt", + "cell_methods": "t: minimum (interval: -1 h)", + "vertical_dimension": { + "standard_name": "height", + "long_name": "Height above ground level", + "units": "m", + "vertical_distance": "10" + } } ] } diff --git a/json-schema/schema.json b/json-schema/schema.json index a950413..6a5899c 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -134,16 +134,33 @@ "items": { "type": "object", "required": [ - "name" + "standard_name", + "units" ], "properties": { - "name": { + "standard_name": { + "title": "CF standard_name field", "type": "string", "minLength": 1 }, - "unit": { - "type": "string" + "long_name": { + "title": "CF long_name field", + "type": "string", + "minLength": 1 + }, + "units": { + "type": "string", + "minLength": 1 + }, + "cell_methods": { + "type": "string", + "minLength": 1 + }, + "vertical_dimension": { + "$ref": "#/definitions/vertical_dimension" + } + } } } @@ -154,6 +171,30 @@ } }, "additionalProperties": false + }, + "vertical_dimension": { + "title": "Vertical Dimension Object", + "type": "object", + "items": { + "required": [ + "standard_name", + "units" + ], + "properties":{ + "standard_name": { + "type": "string" + }, + "long_name": { + "type": "string" + }, + "units": { + "type": "string" + }, + "vertical_distance": { + "type": "number" + } + } + } } } } From fe04f1e8ce6a22793943baf431415ebe081c4253 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Tue, 25 Mar 2025 17:10:54 +1300 Subject: [PATCH 02/32] Changed vertical dimension values to array. --- README.md | 18 +++++------ examples/collection.json | 8 +++-- examples/item.json | 46 ++++++++++++++++++++++------- examples/standalone_collection.json | 8 +++-- json-schema/schema.json | 7 +++-- 5 files changed, 62 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 5b8008e..98e2b85 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ clients should rely on the `cf:parameter` of each asset, if available. #### CF Object -This object should contain a standard_name variable from the [CF list](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) and where applicable a unit from the [UDUNITS-2 database](https://docs.unidata.ucar.edu/udunits/current/) +This object should contain a standard_name variable from the [CF list](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) and wa unit from the [UDUNITS-2 database](https://docs.unidata.ucar.edu/udunits/current/) | Field Name | Type | Description | | ------------------ | ------ | ----------- | @@ -58,18 +58,18 @@ This object should contain a standard_name variable from the [CF list](https://c | long_name | string | The long_name attribute is defined by the [NUG] to contain a long descriptive name which may, for example, be used for labeling plots. See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. | | units | string | **REQUIRED**. The units attribute can be recognized by the UDUNITS package [UDUNITS](https://cfconventions.org/cf-conventions/cf-conventions.html#UDUNITS). If the variable is dimensionless then the value is set to 1. See [CF Units](https://cfconventions.org/cf-conventions/cf-conventions.html#units) for more details. | | cell_methods | string | This is a string attribute comprising a list of blank-separated words of the form "name: method". Each "name: method" pair indicates that for an axis identified by name, the cell values representing the field have been determined or derived by the specified method. For example, if data values have been generated by computing time means, then this could be indicated with cell_methods="t: mean", assuming here that the name of the time dimension variable is "t". See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. | -| vertical_dimension | [Vertical Dimension Object](#Vertical-Dimension-object) | | +| vertical_dimension | [Vertical Dimension Object](#Vertical-Dimension-object) | This object describes the vertical dimension using CF convention. | #### Vertical Dimension Object -This object should contain a variable name from the [CF list](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) -and where applicable a unit from the [UDUNITS-2 database](https://docs.unidata.ucar.edu/udunits/current/) +This object describes the vertical dimension for the variable in the CF Object if required. This object also should contain a variable name from the [CF list](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) and a unit from the [UDUNITS-2 database](https://docs.unidata.ucar.edu/udunits/current/) -| Field Name | Type | Description | -| ----------------- | ------ | ----------- | -| standard_name | string | **REQUIRED**. As per \[[CF Object](#CF-object)\] definition above. | -| long_name | string | As per \[[CF Object](#CF-object)\] definition above. | -| units | string | **REQUIRED**. As per \[[CF Object](#CF-object)\] definition above. | +| Field Name | Type | Description | +| ----------------- | -------- | ----------- | +| standard_name | string | **REQUIRED**. As per [CF Object](#CF-object) definition above. | +| long_name | string | As per [CF Object](#CF-object) definition above. | +| units | string | **REQUIRED**. As per [CF Object](#CF-object) definition above. | +| values | [number] | The vertical values as per vertical dimenions definition. | ## Contributing diff --git a/examples/collection.json b/examples/collection.json index 68432f3..7581efc 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -52,7 +52,9 @@ "standard_name": "height", "long_name": "Height above ground level", "units": "m", - "vertical_distance": "10" + "values": [ + "10" + ] } } ] @@ -79,7 +81,9 @@ "standard_name": "height", "long_name": "Height above ground level", "units": "m", - "vertical_distance": "10" + "values": [ + "10" + ] } } ] diff --git a/examples/item.json b/examples/item.json index 6f1dd59..b6a3a66 100644 --- a/examples/item.json +++ b/examples/item.json @@ -56,10 +56,12 @@ "standard_name": "height", "long_name": "Height above ground level", "units": "m", - "vertical_distance": "10" + "values": [ + "10" + ] } } - ] + ] }, "links": [ { @@ -85,12 +87,24 @@ "type": "application/netcdf", "cf:parameter": [ { - "name": "sea_surface_temperature", - "unit": "K" + "standard_name": "sea_surface_temperature", + "long_name": "Average temperature on sea surface for preceding 24 hours", + "units": "K", + "cell_methods": "t: mean (interval: -24h)" }, { - "name": "depth", - "unit": "m" + "standard_name": "wind_speed", + "long_name": "minimum wind speed in 1 hour at 10 m agl", + "units": "kt", + "cell_methods": "t: minimum (interval: -1 h)", + "vertical_dimension": { + "standard_name": "height", + "long_name": "Height above ground level", + "units": "m", + "values": [ + "10" + ] + } } ] }, @@ -99,12 +113,24 @@ "type": "application/netcdf", "cf:parameter": [ { - "name": "sea_ice_surface_temperature", - "unit": "K" + "standard_name": "sea_surface_temperature", + "long_name": "Average temperature on sea surface for preceding 24 hours", + "units": "K", + "cell_methods": "t: mean (interval: -24h)" }, { - "name": "depth", - "unit": "m" + "standard_name": "wind_speed", + "long_name": "minimum wind speed in 1 hour at 10 m agl", + "units": "kt", + "cell_methods": "t: minimum (interval: -1 h)", + "vertical_dimension": { + "standard_name": "height", + "long_name": "Height above ground level", + "units": "m", + "values": [ + "10" + ] + } } ] } diff --git a/examples/standalone_collection.json b/examples/standalone_collection.json index 260dc04..0560c28 100644 --- a/examples/standalone_collection.json +++ b/examples/standalone_collection.json @@ -44,7 +44,9 @@ "standard_name": "height", "long_name": "Height above ground level", "units": "m", - "vertical_distance": "10" + "values": [ + "10" + ] } } ], @@ -67,7 +69,9 @@ "standard_name": "height", "long_name": "Height above ground level", "units": "m", - "vertical_distance": "10" + "values": [ + "10" + ] } } ] diff --git a/json-schema/schema.json b/json-schema/schema.json index 6a5899c..f87452b 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -190,8 +190,11 @@ "units": { "type": "string" }, - "vertical_distance": { - "type": "number" + "values": { + "type": "array", + "items": { + "type": "number" + } } } } From 1960a0e974536d3560b9b9621b8098b0dd985b69 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Wed, 26 Mar 2025 11:32:15 +1300 Subject: [PATCH 03/32] enriching collection example --- examples/collection.json | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/examples/collection.json b/examples/collection.json index 7581efc..af14370 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -37,12 +37,32 @@ "long_name": "Average temperature on sea surface for preceding 24 hours", "units": "K", "cell_methods": "t: mean (interval: -24h)" + }, + { + "standard_name": "air_temperature", + "long_name": "24-hour maximum air temperature at 2 m agl", + "units": "degC", + "cell_methods": "t: maximum (interval: -24 h)", + "vertical_dimension": { + "standard_name": "height", + "long_name": "Height above ground level", + "units": "m", + "values": [ + "2" + ] + } } ] }, - "f10_1h_min": { + "observation_time_series": { "type": "application/netcdf", "cf:parameter": [ + { + "standard_name": "sea_surface_temperature", + "long_name": "Average temperature on sea surface for preceding 24 hours", + "units": "K", + "cell_methods": "t: mean (interval: -24h)" + }, { "standard_name": "wind_speed", "long_name": "minimum wind speed in 1 hour at 10 m agl", From 2c0f630c73446637d09f29ffd92d426298981c1e Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Wed, 26 Mar 2025 11:35:02 +1300 Subject: [PATCH 04/32] added link to NetCDF Users Guide --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 98e2b85..c28354c 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ This object should contain a standard_name variable from the [CF list](https://c | Field Name | Type | Description | | ------------------ | ------ | ----------- | | standard_name | string | **REQUIRED**. Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html). | -| long_name | string | The long_name attribute is defined by the [NUG] to contain a long descriptive name which may, for example, be used for labeling plots. See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. | +| long_name | string | The long_name attribute is defined by the [NUG](https://docs.unidata.ucar.edu/nug/current/index.html) to contain a long descriptive name which may, for example, be used for labeling plots. See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. | | units | string | **REQUIRED**. The units attribute can be recognized by the UDUNITS package [UDUNITS](https://cfconventions.org/cf-conventions/cf-conventions.html#UDUNITS). If the variable is dimensionless then the value is set to 1. See [CF Units](https://cfconventions.org/cf-conventions/cf-conventions.html#units) for more details. | | cell_methods | string | This is a string attribute comprising a list of blank-separated words of the form "name: method". Each "name: method" pair indicates that for an axis identified by name, the cell values representing the field have been determined or derived by the specified method. For example, if data values have been generated by computing time means, then this could be indicated with cell_methods="t: mean", assuming here that the name of the time dimension variable is "t". See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. | | vertical_dimension | [Vertical Dimension Object](#Vertical-Dimension-object) | This object describes the vertical dimension using CF convention. | From 5cbcdaf19788d2e2c5238d8738b74f8e3aebbcc0 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Wed, 26 Mar 2025 11:40:46 +1300 Subject: [PATCH 05/32] description of CF Object --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c28354c..a238993 100644 --- a/README.md +++ b/README.md @@ -27,9 +27,9 @@ The fields in the table below can be used in these parts of STAC documents: - [x] Assets (for both Collections and Items, incl. Item Asset Definitions in Collections) - [ ] Links -| Field Name | Type | Description | -| ------------ | --------------------------- | ------------------------------------ | -| cf:parameter | \[[CF Object](#CF-object)\] | **REQUIRED**. CF Standard Name Table | +| Field Name | Type | Description | +| ------------ | --------------------------- | ----------------------------------------------------------------------------------- | +| cf:parameter | \[[CF Object](#CF-object)\] | **REQUIRED**. Describes attributes of an environmental variable using CF convention | ### Additional Field Information From 7aaa04a92cc9b4d88805d7d9aa1d8b3db965d6f7 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Mon, 31 Mar 2025 12:09:48 +1300 Subject: [PATCH 06/32] add asset_variable_name and schema.json based on schema_template.json --- README.md | 14 +- examples/collection.json | 9 +- examples/item.json | 8 +- examples/standalone_collection.json | 50 +++--- json-schema/schema.json | 243 ++++++++++++++++------------ 5 files changed, 191 insertions(+), 133 deletions(-) diff --git a/README.md b/README.md index a238993..151f4cf 100644 --- a/README.md +++ b/README.md @@ -50,27 +50,31 @@ clients should rely on the `cf:parameter` of each asset, if available. #### CF Object -This object should contain a standard_name variable from the [CF list](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) and wa unit from the [UDUNITS-2 database](https://docs.unidata.ucar.edu/udunits/current/) +This object should contain a standard_name variable from the [CF list](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) +and a unit from the [UDUNITS-2 database](https://docs.unidata.ucar.edu/udunits/current/) | Field Name | Type | Description | | ------------------ | ------ | ----------- | -| standard_name | string | **REQUIRED**. Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html). | +| standard_name | string | Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html). This is a required field unless a variable does not have a standard_name in the CF conventions. In this case the long_name is a required field. | | long_name | string | The long_name attribute is defined by the [NUG](https://docs.unidata.ucar.edu/nug/current/index.html) to contain a long descriptive name which may, for example, be used for labeling plots. See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. | | units | string | **REQUIRED**. The units attribute can be recognized by the UDUNITS package [UDUNITS](https://cfconventions.org/cf-conventions/cf-conventions.html#UDUNITS). If the variable is dimensionless then the value is set to 1. See [CF Units](https://cfconventions.org/cf-conventions/cf-conventions.html#units) for more details. | | cell_methods | string | This is a string attribute comprising a list of blank-separated words of the form "name: method". Each "name: method" pair indicates that for an axis identified by name, the cell values representing the field have been determined or derived by the specified method. For example, if data values have been generated by computing time means, then this could be indicated with cell_methods="t: mean", assuming here that the name of the time dimension variable is "t". See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. | +| asset_variable_name | string | The variable name used in the asset that corresponds to this element described by the CF attributes. Highly recommended to specify if the asset itself does not use CF convention itself to describe the elements but rather ambiguous and/or cryptic variable names. | | vertical_dimension | [Vertical Dimension Object](#Vertical-Dimension-object) | This object describes the vertical dimension using CF convention. | #### Vertical Dimension Object -This object describes the vertical dimension for the variable in the CF Object if required. This object also should contain a variable name from the [CF list](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) and a unit from the [UDUNITS-2 database](https://docs.unidata.ucar.edu/udunits/current/) +This object describes the vertical dimension for the variable in the CF Object if required. +This object also should contain a variable name from the [CF list](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) +and a unit from the [UDUNITS-2 database](https://docs.unidata.ucar.edu/udunits/current/) | Field Name | Type | Description | | ----------------- | -------- | ----------- | -| standard_name | string | **REQUIRED**. As per [CF Object](#CF-object) definition above. | +| standard_name | string | As per [CF Object](#CF-object) definition above. | | long_name | string | As per [CF Object](#CF-object) definition above. | | units | string | **REQUIRED**. As per [CF Object](#CF-object) definition above. | | values | [number] | The vertical values as per vertical dimenions definition. | - +| asset_variable_name | string | The variable name used in the asset that corresponds to this vertical dimension, if present. | ## Contributing All contributions are subject to the diff --git a/examples/collection.json b/examples/collection.json index af14370..5094b08 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -43,6 +43,7 @@ "long_name": "24-hour maximum air temperature at 2 m agl", "units": "degC", "cell_methods": "t: maximum (interval: -24 h)", + "asset_variable_name": "ws_min_1h", "vertical_dimension": { "standard_name": "height", "long_name": "Height above ground level", @@ -61,13 +62,15 @@ "standard_name": "sea_surface_temperature", "long_name": "Average temperature on sea surface for preceding 24 hours", "units": "K", - "cell_methods": "t: mean (interval: -24h)" + "cell_methods": "t: mean (interval: -24h)", + "asset_variable_name": "sst" }, { "standard_name": "wind_speed", "long_name": "minimum wind speed in 1 hour at 10 m agl", "units": "kt", "cell_methods": "t: minimum (interval: -1 h)", + "asset_variable_name": "ws_min_1h", "vertical_dimension": { "standard_name": "height", "long_name": "Height above ground level", @@ -90,13 +93,15 @@ "standard_name": "sea_surface_temperature", "long_name": "Average temperature on sea surface for preceding 24 hours", "units": "K", - "cell_methods": "t: mean (interval: -24h)" + "cell_methods": "t: mean (interval: -24h)", + "asset_variable_name": "sst" }, { "standard_name": "wind_speed", "long_name": "minimum wind speed in 1 hour at 10 m agl", "units": "kt", "cell_methods": "t: minimum (interval: -1 h)", + "asset_variable_name": "ws_min_1h", "vertical_dimension": { "standard_name": "height", "long_name": "Height above ground level", diff --git a/examples/item.json b/examples/item.json index b6a3a66..283c76c 100644 --- a/examples/item.json +++ b/examples/item.json @@ -90,13 +90,15 @@ "standard_name": "sea_surface_temperature", "long_name": "Average temperature on sea surface for preceding 24 hours", "units": "K", - "cell_methods": "t: mean (interval: -24h)" + "cell_methods": "t: mean (interval: -24h)", + "asset_variable_name": "sst" }, { "standard_name": "wind_speed", "long_name": "minimum wind speed in 1 hour at 10 m agl", "units": "kt", "cell_methods": "t: minimum (interval: -1 h)", + "asset_variable_name": "ws_min_1h", "vertical_dimension": { "standard_name": "height", "long_name": "Height above ground level", @@ -116,13 +118,15 @@ "standard_name": "sea_surface_temperature", "long_name": "Average temperature on sea surface for preceding 24 hours", "units": "K", - "cell_methods": "t: mean (interval: -24h)" + "cell_methods": "t: mean (interval: -24h)", + "asset_variable_name": "sst" }, { "standard_name": "wind_speed", "long_name": "minimum wind speed in 1 hour at 10 m agl", "units": "kt", "cell_methods": "t: minimum (interval: -1 h)", + "asset_variable_name": "ws_min_1h", "vertical_dimension": { "standard_name": "height", "long_name": "Height above ground level", diff --git a/examples/standalone_collection.json b/examples/standalone_collection.json index 0560c28..a7db6a7 100644 --- a/examples/standalone_collection.json +++ b/examples/standalone_collection.json @@ -28,28 +28,32 @@ ] } }, - "cf:parameter": [ - { - "standard_name": "sea_surface_temperature", - "long_name": "Average temperature on sea surface for preceding 24 hours", - "units": "K", - "cell_methods": "t: mean (interval: -24h)" - }, - { - "standard_name": "wind_speed", - "long_name": "minimum wind speed in 1 hour at 10 m agl", - "units": "kt", - "cell_methods": "t: minimum (interval: -1 h)", - "vertical_dimension": { - "standard_name": "height", - "long_name": "Height above ground level", - "units": "m", - "values": [ - "10" - ] + "summaries": { + "cf:parameter": [ + { + "standard_name": "sea_surface_temperature", + "long_name": "Average temperature on sea surface for preceding 24 hours", + "units": "K", + "cell_methods": "t: mean (interval: -24h)", + "asset_variable_name": "sst" + }, + { + "standard_name": "wind_speed", + "long_name": "minimum wind speed in 1 hour at 10 m agl", + "units": "kt", + "cell_methods": "t: minimum (interval: -1 h)", + "asset_variable_name": "ws_min_1h", + "vertical_dimension": { + "standard_name": "height", + "long_name": "Height above ground level", + "units": "m", + "values": [ + "10" + ] + } } - } - ], + ] + }, "assets": { "example": { "href": "https://example.com/examples/example.nc", @@ -58,13 +62,15 @@ "standard_name": "sea_surface_temperature", "long_name": "Average temperature on sea surface for preceding 24 hours", "units": "K", - "cell_methods": "t: mean (interval: -24h)" + "cell_methods": "t: mean (interval: -24h)", + "asset_variable_name": "sst" }, { "standard_name": "wind_speed", "long_name": "minimum wind speed in 1 hour at 10 m agl", "units": "kt", "cell_methods": "t: minimum (interval: -1 h)", + "asset_variable_name": "ws_min_1h", "vertical_dimension": { "standard_name": "height", "long_name": "Height above ground level", diff --git a/json-schema/schema.json b/json-schema/schema.json index f87452b..8804923 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -1,131 +1,168 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://stac-extensions.github.io/cf/v0.2.0/schema.json#", - "title": "CF Extension", + "$id": "https://stac-extensions.github.io/template/v1.0.0/schema.json#", + "title": "Climate and Forecasting Convention Extension", "description": "STAC CF Extension for STAC Items and STAC Collections.", - "type": "object", - "required": [ - "stac_extensions" - ], - "properties": { - "stac_extensions": { - "type": "array", - "contains": { - "const": "https://stac-extensions.github.io/cf/v0.2.0/schema.json" - } - }, - "assets": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/fields" - } - } - }, "oneOf": [ { - "$comment": "Schema for Collections", - "type": "object", - "required": [ - "type" - ], - "properties": { - "type": { - "const": "Collection" + "$comment": "This is the schema for STAC Items. Remove this object if this extension only applies to Collections.", + "allOf": [ + { + "$ref": "#/definitions/stac_extensions" }, - "item_assets": { + { "type": "object", - "additionalProperties": { - "$ref": "#/definitions/fields" + "required": [ + "type", + "properties", + "assets" + ], + "properties": { + "type": { + "const": "Feature" + }, + "properties": { + "allOf": [ + { + "$comment": "Require fields here for Item Properties.", + "required": [ + ] + }, + { + "$ref": "#/definitions/fields" + } + ] + }, + "assets": { + "$comment": "This validates the fields in Item Assets, but does not require them.", + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/fields" + } + } + } + } + ] + }, + { + "$comment": "This is the schema for STAC Collections.", + "type": "object", + "allOf": [ + { + "required": [ + "type" + ], + "properties": { + "type": { + "const": "Collection" + } } }, - "summaries": { - "oneOf": [ + { + "$ref": "#/definitions/stac_extensions" + } + ], + "anyOf": [ + { + "$comment": "This is the schema for the top-level fields in a Collection. Remove this if this extension does not define top-level fields for Collections.", + "allOf": [ { - "$ref": "#/definitions/fields" + "$comment": "Require fields here for Collections (top-level).", + "required": [ + ] }, { - "$comment": "JSON Schema summary", + "$ref": "#/definitions/fields" + } + ] + }, + { + "$comment": "This validates the fields in Collection Assets, but does not require them.", + "required": [ + "assets" + ], + "properties": { + "assets": { "type": "object", - "properties": { - "cf:parameter": { - "type": "object", - "properties": { - "type": { - "const": "array" - } + "not": { + "additionalProperties": { + "not": { + "allOf": [ + { + "$ref": "#/definitions/require_any_field" + }, + { + "$ref": "#/definitions/fields" + } + ] } } - }, - "patternProperties": { - "^(?!cf:)": { - "$comment": "Above, change `cf` to the prefix of this extension" - } - }, - "additionalProperties": false + } } - ] - } - }, - "allOf": [ + } + }, { - "$ref": "#/definitions/fields" - } - ] - }, - { - "$comment": "Schema for Items", - "type": "object", - "required": [ - "type" - ], - "properties": { - "type": { - "const": "Feature" + "$comment": "This is the schema for the fields in Item Asset Definitions. It doesn't require any fields.", + "required": [ + "item_assets" + ], + "properties": { + "item_assets": { + "type": "object", + "not": { + "additionalProperties": { + "not": { + "allOf": [ + { + "$ref": "#/definitions/require_any_field" + }, + { + "$ref": "#/definitions/fields" + } + ] + } + } + } + } + } }, - "properties": { - "$ref": "#/definitions/fields" - } - }, - "allOf": [ { - "$ref": "#/definitions/cf_in_assets" + "$comment": "This is the schema for the fields in Summaries. By default, only checks the existence of the properties, but not the schema of the summaries.", + "required": [ + "summaries" + ], + "properties": { + "summaries": { + "$ref": "#/definitions/require_any_field" + } + } } ] } ], "definitions": { - "cf_in_assets": { + "stac_extensions": { + "type": "object", "required": [ - "assets" + "stac_extensions" ], "properties": { - "assets": { - "not": { - "additionalProperties": { - "not": { - "allOf": [ - { - "required": [ - "cf:parameter" - ] - }, - { - "$ref": "#/definitions/fields" - } - ] - } - } + "stac_extensions": { + "type": "array", + "contains": { + "const": "https://stac-extensions.github.io/cf/v0.2.0/schema.json" } } } }, - "forbid_fields": { - "patternProperties": { - "^(?!cf:)": {} - }, - "additionalProperties": false + "require_any_field": { + "$comment": "Please list all fields here so that we can force the existence of one of them in other parts of the schemas.", + "anyOf": [ + {"required": ["cf:parameter"]} + ] }, "fields": { + "$comment": "Add your new fields here. Don't require them here, do that above in the corresponding schema.", "type": "object", "properties": { "cf:parameter": { @@ -134,7 +171,6 @@ "items": { "type": "object", "required": [ - "standard_name", "units" ], "properties": { @@ -156,24 +192,26 @@ "type": "string", "minLength": 1 }, + "asset_variable_name": { + "type": "string", + "minLength": 1 + }, "vertical_dimension": { "$ref": "#/definitions/vertical_dimension" - } - } } } }, "patternProperties": { "^(?!cf:)": { - "$comment": "Above, change `cf` to the prefix of this extension" + "$comment": "Above, change `template` to the prefix of this extension" } }, "additionalProperties": false }, "vertical_dimension": { - "title": "Vertical Dimension Object", + "title": "Vertical Dimension", "type": "object", "items": { "required": [ @@ -190,7 +228,7 @@ "units": { "type": "string" }, - "values": { + "value": { "type": "array", "items": { "type": "number" @@ -199,5 +237,6 @@ } } } + } -} +} \ No newline at end of file From 940f6acb95753d4964848f98cc738d3473133741 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Mon, 31 Mar 2025 12:14:46 +1300 Subject: [PATCH 07/32] Follow STAC Item readme for conditional required field --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 151f4cf..753b729 100644 --- a/README.md +++ b/README.md @@ -55,8 +55,8 @@ and a unit from the [UDUNITS-2 database](https://docs.unidata.ucar.edu/udunits/c | Field Name | Type | Description | | ------------------ | ------ | ----------- | -| standard_name | string | Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html). This is a required field unless a variable does not have a standard_name in the CF conventions. In this case the long_name is a required field. | -| long_name | string | The long_name attribute is defined by the [NUG](https://docs.unidata.ucar.edu/nug/current/index.html) to contain a long descriptive name which may, for example, be used for labeling plots. See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. | +| standard_name | string | **REQUIRED if variable has a standard_name definition in the CF convention.** Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html). | +| long_name | string | **REQUIRED if standard_name does not exist for variable in CF convention.** The long_name attribute is defined by the [NUG](https://docs.unidata.ucar.edu/nug/current/index.html) to contain a long descriptive name which may, for example, be used for labeling plots. See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. | | units | string | **REQUIRED**. The units attribute can be recognized by the UDUNITS package [UDUNITS](https://cfconventions.org/cf-conventions/cf-conventions.html#UDUNITS). If the variable is dimensionless then the value is set to 1. See [CF Units](https://cfconventions.org/cf-conventions/cf-conventions.html#units) for more details. | | cell_methods | string | This is a string attribute comprising a list of blank-separated words of the form "name: method". Each "name: method" pair indicates that for an axis identified by name, the cell values representing the field have been determined or derived by the specified method. For example, if data values have been generated by computing time means, then this could be indicated with cell_methods="t: mean", assuming here that the name of the time dimension variable is "t". See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. | | asset_variable_name | string | The variable name used in the asset that corresponds to this element described by the CF attributes. Highly recommended to specify if the asset itself does not use CF convention itself to describe the elements but rather ambiguous and/or cryptic variable names. | @@ -70,8 +70,8 @@ and a unit from the [UDUNITS-2 database](https://docs.unidata.ucar.edu/udunits/ | Field Name | Type | Description | | ----------------- | -------- | ----------- | -| standard_name | string | As per [CF Object](#CF-object) definition above. | -| long_name | string | As per [CF Object](#CF-object) definition above. | +| standard_name | string | **REQUIRED if vertical variable has a standard_name definition in the CF convention.** As per [CF Object](#CF-object) definition above. | +| long_name | string | **REQUIRED if standard_name does not exist for vertical variable in CF convention.** As per [CF Object](#CF-object) definition above. | | units | string | **REQUIRED**. As per [CF Object](#CF-object) definition above. | | values | [number] | The vertical values as per vertical dimenions definition. | | asset_variable_name | string | The variable name used in the asset that corresponds to this vertical dimension, if present. | From 9b4db609da3cfa9c384b6dbbdbcd0763426355a6 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Mon, 31 Mar 2025 13:18:45 +1300 Subject: [PATCH 08/32] Schema now enforces the updated Readme better --- README.md | 4 +- json-schema/schema.json | 95 ++++++++++++++++++++++++++++------------- 2 files changed, 67 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 753b729..8c2b452 100644 --- a/README.md +++ b/README.md @@ -55,8 +55,8 @@ and a unit from the [UDUNITS-2 database](https://docs.unidata.ucar.edu/udunits/c | Field Name | Type | Description | | ------------------ | ------ | ----------- | -| standard_name | string | **REQUIRED if variable has a standard_name definition in the CF convention.** Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html). | -| long_name | string | **REQUIRED if standard_name does not exist for variable in CF convention.** The long_name attribute is defined by the [NUG](https://docs.unidata.ucar.edu/nug/current/index.html) to contain a long descriptive name which may, for example, be used for labeling plots. See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. | +| standard_name | string | **REQUIRED** Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) if variable has a standard_name definition in the CF convention. Otherwise standard_name remains an empty value. | +| long_name | string | **REQUIRED if standard_name does not exist for variable in CF convention and is an empty value.** The long_name attribute is defined by the [NUG](https://docs.unidata.ucar.edu/nug/current/index.html) to contain a long descriptive name which may, for example, be used for labeling plots. See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. | | units | string | **REQUIRED**. The units attribute can be recognized by the UDUNITS package [UDUNITS](https://cfconventions.org/cf-conventions/cf-conventions.html#UDUNITS). If the variable is dimensionless then the value is set to 1. See [CF Units](https://cfconventions.org/cf-conventions/cf-conventions.html#units) for more details. | | cell_methods | string | This is a string attribute comprising a list of blank-separated words of the form "name: method". Each "name: method" pair indicates that for an axis identified by name, the cell values representing the field have been determined or derived by the specified method. For example, if data values have been generated by computing time means, then this could be indicated with cell_methods="t: mean", assuming here that the name of the time dimension variable is "t". See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. | | asset_variable_name | string | The variable name used in the asset that corresponds to this element described by the CF attributes. Highly recommended to specify if the asset itself does not use CF convention itself to describe the elements but rather ambiguous and/or cryptic variable names. | diff --git a/json-schema/schema.json b/json-schema/schema.json index 8804923..14507be 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -167,39 +167,74 @@ "properties": { "cf:parameter": { "type": "array", - "minItems": 1, "items": { - "type": "object", - "required": [ - "units" - ], - "properties": { - "standard_name": { - "title": "CF standard_name field", - "type": "string", - "minLength": 1 - }, - "long_name": { - "title": "CF long_name field", - "type": "string", - "minLength": 1 - }, - "units": { - "type": "string", - "minLength": 1 - }, - "cell_methods": { - "type": "string", - "minLength": 1 - }, - "asset_variable_name": { - "type": "string", - "minLength": 1 + "allOf": [ + { + "oneOf": [ + { + "type": "object", + "required": [ + "standard_name", + "long_name" + ], + "properties": { + "standard_name": { + "title": "CF standard_name field", + "type": "string", + "minLength": 0, + "maxLength": 0 + }, + "long_name": { + "title": "CF long_name field", + "type": "string", + "minLength": 1 + } + } + }, + { + "type": "object", + "required": [ + "standard_name" + ], + "properties": { + "standard_name": { + "title": "CF standard_name field", + "type": "string", + "minLength": 1 + }, + "long_name": { + "title": "CF long_name field", + "type": "string", + "minLength": 1 + } + } + } + ] }, - "vertical_dimension": { - "$ref": "#/definitions/vertical_dimension" + { + "type": "object", + "required": [ + "units" + ], + "properties": { + "units": { + "type": "string", + "minLength": 1 + }, + "cell_methods": { + "type": "string", + "minLength": 1 + }, + "asset_variable_name": { + "type": "string", + "minLength": 1 + }, + "vertical_dimension": { + "$ref": "#/definitions/vertical_dimension" + } + } } - } + ] } } }, From f291e6f64a53d2b95988662657bff41ae5bec0ce Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Mon, 9 Jun 2025 14:50:28 +1200 Subject: [PATCH 09/32] Using datacube with CF extension --- README.md | 47 +------- examples/collection.json | 164 +++++++++++++++------------- examples/item.json | 108 +++--------------- examples/standalone_collection.json | 92 ---------------- json-schema/schema.json | 164 +++++++++++----------------- package.json | 4 +- 6 files changed, 173 insertions(+), 406 deletions(-) delete mode 100644 examples/standalone_collection.json diff --git a/README.md b/README.md index 8c2b452..2d78ab2 100644 --- a/README.md +++ b/README.md @@ -29,52 +29,15 @@ The fields in the table below can be used in these parts of STAC documents: | Field Name | Type | Description | | ------------ | --------------------------- | ----------------------------------------------------------------------------------- | -| cf:parameter | \[[CF Object](#CF-object)\] | **REQUIRED**. Describes attributes of an environmental variable using CF convention | +| cf:standard_name | string | **REQUIRED** Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) if variable has a standard_name definition in the CF convention. Otherwise standard_name remains an empty value. | +| cf:long_name | string | **REQUIRED if standard_name does not exist for variable in CF convention and is an empty value.** The long_name attribute is defined by the [NUG](https://docs.unidata.ucar.edu/nug/current/index.html) to contain a long descriptive name which may, for example, be used for labeling plots. See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. | +| cf:units | string | **REQUIRED**. The units attribute can be recognized by the UDUNITS package [UDUNITS](https://cfconventions.org/cf-conventions/cf-conventions.html#UDUNITS). If the variable is dimensionless then the value is set to 1. See [CF Units](https://cfconventions.org/cf-conventions/cf-conventions.html#units) for more details. | +| cell_methods | string | This is a string attribute comprising a list of blank-separated words of the form "name: method". Each "name: method" pair indicates that for an axis identified by name, the cell values representing the field have been determined or derived by the specified method. For example, if data values have been generated by computing time means, then this could be indicated with cell_methods="t: mean", assuming here that the name of the time dimension variable is "t". See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. | +| cf:asset_variable_name | string | The variable name used in the asset that corresponds to this element described by the CF attributes. Highly recommended to specify if the asset itself does not use CF convention itself to describe the elements but rather ambiguous and/or cryptic variable names. | ### Additional Field Information -#### cf:parameter - -The `cf:parameter` array is used to describe the parameters in an Asset or Collection. -It requires at least one entry with a non-empty standard_name and units entry. -This enables clients to read the file and understand which parameters are available. - -If assets with a `cf:parameter` array are provided, the field may optionally be used in the -Item Properties or Collection and it must summarize the available parameters in the assets. -This must be the 'union' of all the possible parameters represented in assets. -If no assets are provided in a Collection, the field can be used freely to describe the Collection for e.g. search. -An Item is only allowed to use `cf:parameter` in its Properties if it has at least one asset with a defined parameter array. - -The `cf:parameter` list in Item Properties or Collections should be considered merely informative - -clients should rely on the `cf:parameter` of each asset, if available. -#### CF Object - -This object should contain a standard_name variable from the [CF list](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) -and a unit from the [UDUNITS-2 database](https://docs.unidata.ucar.edu/udunits/current/) - -| Field Name | Type | Description | -| ------------------ | ------ | ----------- | -| standard_name | string | **REQUIRED** Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) if variable has a standard_name definition in the CF convention. Otherwise standard_name remains an empty value. | -| long_name | string | **REQUIRED if standard_name does not exist for variable in CF convention and is an empty value.** The long_name attribute is defined by the [NUG](https://docs.unidata.ucar.edu/nug/current/index.html) to contain a long descriptive name which may, for example, be used for labeling plots. See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. | -| units | string | **REQUIRED**. The units attribute can be recognized by the UDUNITS package [UDUNITS](https://cfconventions.org/cf-conventions/cf-conventions.html#UDUNITS). If the variable is dimensionless then the value is set to 1. See [CF Units](https://cfconventions.org/cf-conventions/cf-conventions.html#units) for more details. | -| cell_methods | string | This is a string attribute comprising a list of blank-separated words of the form "name: method". Each "name: method" pair indicates that for an axis identified by name, the cell values representing the field have been determined or derived by the specified method. For example, if data values have been generated by computing time means, then this could be indicated with cell_methods="t: mean", assuming here that the name of the time dimension variable is "t". See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. | -| asset_variable_name | string | The variable name used in the asset that corresponds to this element described by the CF attributes. Highly recommended to specify if the asset itself does not use CF convention itself to describe the elements but rather ambiguous and/or cryptic variable names. | -| vertical_dimension | [Vertical Dimension Object](#Vertical-Dimension-object) | This object describes the vertical dimension using CF convention. | - -#### Vertical Dimension Object - -This object describes the vertical dimension for the variable in the CF Object if required. -This object also should contain a variable name from the [CF list](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) -and a unit from the [UDUNITS-2 database](https://docs.unidata.ucar.edu/udunits/current/) - -| Field Name | Type | Description | -| ----------------- | -------- | ----------- | -| standard_name | string | **REQUIRED if vertical variable has a standard_name definition in the CF convention.** As per [CF Object](#CF-object) definition above. | -| long_name | string | **REQUIRED if standard_name does not exist for vertical variable in CF convention.** As per [CF Object](#CF-object) definition above. | -| units | string | **REQUIRED**. As per [CF Object](#CF-object) definition above. | -| values | [number] | The vertical values as per vertical dimenions definition. | -| asset_variable_name | string | The variable name used in the asset that corresponds to this vertical dimension, if present. | ## Contributing All contributions are subject to the diff --git a/examples/collection.json b/examples/collection.json index 5094b08..a23725c 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -1,11 +1,12 @@ { "stac_version": "1.0.0", "stac_extensions": [ - "https://stac-extensions.github.io/cf/v0.2.0/schema.json" + "https://stac-extensions.github.io/item-assets/v1.0.0/schema.json", + "https://stac-extensions.github.io/template/v1.0.0/schema.json" ], "type": "Collection", "id": "collection", - "title": "Collection with an Item", + "title": "A title", "description": "A description", "license": "Apache-2.0", "extent": { @@ -28,59 +29,18 @@ ] } }, + "assets": { + "example": { + "href": "https://example.com/examples/file.xyz", + "template:new_field": "test" + } + }, "item_assets": { - "sea_surface_temperature": { - "type": "application/netcdf", - "cf:parameter": [ - { - "standard_name": "sea_surface_temperature", - "long_name": "Average temperature on sea surface for preceding 24 hours", - "units": "K", - "cell_methods": "t: mean (interval: -24h)" - }, - { - "standard_name": "air_temperature", - "long_name": "24-hour maximum air temperature at 2 m agl", - "units": "degC", - "cell_methods": "t: maximum (interval: -24 h)", - "asset_variable_name": "ws_min_1h", - "vertical_dimension": { - "standard_name": "height", - "long_name": "Height above ground level", - "units": "m", - "values": [ - "2" - ] - } - } - ] - }, - "observation_time_series": { - "type": "application/netcdf", - "cf:parameter": [ - { - "standard_name": "sea_surface_temperature", - "long_name": "Average temperature on sea surface for preceding 24 hours", - "units": "K", - "cell_methods": "t: mean (interval: -24h)", - "asset_variable_name": "sst" - }, - { - "standard_name": "wind_speed", - "long_name": "minimum wind speed in 1 hour at 10 m agl", - "units": "kt", - "cell_methods": "t: minimum (interval: -1 h)", - "asset_variable_name": "ws_min_1h", - "vertical_dimension": { - "standard_name": "height", - "long_name": "Height above ground level", - "units": "m", - "values": [ - "10" - ] - } - } - ] + "data": { + "roles": [ + "data" + ], + "template:new_field": "test" } }, "summaries": { @@ -88,30 +48,80 @@ "minimum": "2015-06-23T00:00:00Z", "maximum": "2019-07-10T13:44:56Z" }, - "cf:parameter": [ - { - "standard_name": "sea_surface_temperature", - "long_name": "Average temperature on sea surface for preceding 24 hours", - "units": "K", - "cell_methods": "t: mean (interval: -24h)", - "asset_variable_name": "sst" + "cube:dimensions": { + "time_interval1": { + "type": "temporal", + "description": "time interval that cell_methods is applied over", + "values": [ + -24 + ], + "unit": "h" }, - { - "standard_name": "wind_speed", - "long_name": "minimum wind speed in 1 hour at 10 m agl", + "vertical_dimension1": { + "type": "spatial", + "axis": "z", + "cf:standard_name": "height", + "description": "Height above ground level", + "unit": "m", + "values": [ + 10 + ] + }, + "time_interval2": { + "type": "temporal", + "description": "time interval that cell_methods is applied over", + "values": [ + -60 + ], + "unit": "min" + }, + "vertical_dimension2": { + "type": "spatial", + "axis": "z", + "cf:standard_name": "height", + "description": "Air pressure", + "cf:long_name": "", + "unit": "hPa", + "values": [ + 500 + ] + } + }, + "cube:variables": { + "sea_surface_temperature": { + "type": "data", + "cf:standard_name": "sea_surface_temperature", + "description": "Average temperature on sea surface for preceding 24 hours", + "cf:long_name": "Average temperature on sea surface for preceding 24 hours", + "unit": "K", + "cf:cell_methods": "time: mean", + "dimensions": [ + "time_interval1" + ] + }, + "wind_speed_at_10m": { + "type": "data", + "cf:standard_name": "wind_speed", + "description": "minimum wind speed in 1 hour at 10 m agl", + "cf:long_name": "minimum wind speed in 1 hour at 10 m agl", "units": "kt", - "cell_methods": "t: minimum (interval: -1 h)", - "asset_variable_name": "ws_min_1h", - "vertical_dimension": { - "standard_name": "height", - "long_name": "Height above ground level", - "units": "m", - "values": [ - "10" - ] - } + "cf:cell_methods": "time: minimum", + "dimensions": [ + "vertical_dimension1", + "time_interval2" + ] + }, + "temp_at_500hPa": { + "type": "data", + "cf:standard_name": "air_temperature", + "description": "air temperature at 500 hPa", + "cf:long_name": "air temperature at 500 hPa", + "units": "degC", + "dimensions": [ + "vertical_dimension2" + ] } - ] + } }, "links": [ { @@ -119,8 +129,8 @@ "rel": "self" }, { - "href": "./item.json", + "href": "https://example.com/examples/item.json", "rel": "item" } ] -} \ No newline at end of file +} diff --git a/examples/item.json b/examples/item.json index 283c76c..cf19370 100644 --- a/examples/item.json +++ b/examples/item.json @@ -1,7 +1,7 @@ { "stac_version": "1.0.0", "stac_extensions": [ - "https://stac-extensions.github.io/cf/v0.2.0/schema.json" + "https://stac-extensions.github.io/template/v1.0.0/schema.json" ], "type": "Feature", "id": "item", @@ -40,104 +40,28 @@ }, "properties": { "datetime": "2020-12-11T22:38:32Z", - "cf:parameter": [ - { - "standard_name": "sea_surface_temperature", - "long_name": "Average temperature on sea surface for preceding 24 hours", - "units": "K", - "cell_methods": "t: mean (interval: -24h)" - }, - { - "standard_name": "wind_speed", - "long_name": "minimum wind speed in 1 hour at 10 m agl", - "units": "kt", - "cell_methods": "t: minimum (interval: -1 h)", - "vertical_dimension": { - "standard_name": "height", - "long_name": "Height above ground level", - "units": "m", - "values": [ - "10" - ] - } - } + "template:new_field": "test", + "template:xyz": { + "x": 1, + "y": 2, + "z": 3 + }, + "template:another_one": [ + 1, + 2, + 3 ] }, "links": [ { "href": "https://example.com/examples/item.json", "rel": "self" - }, - { - "href": "./collection.json", - "rel": "collection" - }, - { - "href": "./collection.json", - "rel": "parent" - }, - { - "href": "./collection.json", - "rel": "root" } ], "assets": { - "sea_surface_temperature": { - "href": "https://example.com/examples/sea_surface_temperature.nc", - "type": "application/netcdf", - "cf:parameter": [ - { - "standard_name": "sea_surface_temperature", - "long_name": "Average temperature on sea surface for preceding 24 hours", - "units": "K", - "cell_methods": "t: mean (interval: -24h)", - "asset_variable_name": "sst" - }, - { - "standard_name": "wind_speed", - "long_name": "minimum wind speed in 1 hour at 10 m agl", - "units": "kt", - "cell_methods": "t: minimum (interval: -1 h)", - "asset_variable_name": "ws_min_1h", - "vertical_dimension": { - "standard_name": "height", - "long_name": "Height above ground level", - "units": "m", - "values": [ - "10" - ] - } - } - ] - }, - "sea_ice_surface_temperature": { - "href": "https://example.com/examples/sea_ice_surface_temperature.nc", - "type": "application/netcdf", - "cf:parameter": [ - { - "standard_name": "sea_surface_temperature", - "long_name": "Average temperature on sea surface for preceding 24 hours", - "units": "K", - "cell_methods": "t: mean (interval: -24h)", - "asset_variable_name": "sst" - }, - { - "standard_name": "wind_speed", - "long_name": "minimum wind speed in 1 hour at 10 m agl", - "units": "kt", - "cell_methods": "t: minimum (interval: -1 h)", - "asset_variable_name": "ws_min_1h", - "vertical_dimension": { - "standard_name": "height", - "long_name": "Height above ground level", - "units": "m", - "values": [ - "10" - ] - } - } - ] + "data": { + "href": "https://example.com/examples/file.xyz", + "template:new_field": "test" } - }, - "collection": "collection" -} \ No newline at end of file + } +} diff --git a/examples/standalone_collection.json b/examples/standalone_collection.json deleted file mode 100644 index a7db6a7..0000000 --- a/examples/standalone_collection.json +++ /dev/null @@ -1,92 +0,0 @@ -{ - "stac_version": "1.0.0", - "stac_extensions": [ - "https://stac-extensions.github.io/cf/v0.2.0/schema.json" - ], - "type": "Collection", - "id": "standalone_collection", - "title": "Collection without Items", - "description": "A description", - "license": "Apache-2.0", - "extent": { - "spatial": { - "bbox": [ - [ - 172.9, - 1.3, - 173, - 1.4 - ] - ] - }, - "temporal": { - "interval": [ - [ - "2015-06-23T00:00:00Z", - null - ] - ] - } - }, - "summaries": { - "cf:parameter": [ - { - "standard_name": "sea_surface_temperature", - "long_name": "Average temperature on sea surface for preceding 24 hours", - "units": "K", - "cell_methods": "t: mean (interval: -24h)", - "asset_variable_name": "sst" - }, - { - "standard_name": "wind_speed", - "long_name": "minimum wind speed in 1 hour at 10 m agl", - "units": "kt", - "cell_methods": "t: minimum (interval: -1 h)", - "asset_variable_name": "ws_min_1h", - "vertical_dimension": { - "standard_name": "height", - "long_name": "Height above ground level", - "units": "m", - "values": [ - "10" - ] - } - } - ] - }, - "assets": { - "example": { - "href": "https://example.com/examples/example.nc", - "cf:parameter": [ - { - "standard_name": "sea_surface_temperature", - "long_name": "Average temperature on sea surface for preceding 24 hours", - "units": "K", - "cell_methods": "t: mean (interval: -24h)", - "asset_variable_name": "sst" - }, - { - "standard_name": "wind_speed", - "long_name": "minimum wind speed in 1 hour at 10 m agl", - "units": "kt", - "cell_methods": "t: minimum (interval: -1 h)", - "asset_variable_name": "ws_min_1h", - "vertical_dimension": { - "standard_name": "height", - "long_name": "Height above ground level", - "units": "m", - "values": [ - "10" - ] - } - } - ] - } - }, - "links": [ - { - "href": "https://example.com/examples/standalone_collection.json", - "rel": "self" - } - ] -} \ No newline at end of file diff --git a/json-schema/schema.json b/json-schema/schema.json index 14507be..86da606 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -150,7 +150,7 @@ "stac_extensions": { "type": "array", "contains": { - "const": "https://stac-extensions.github.io/cf/v0.2.0/schema.json" + "const": "https://stac-extensions.github.io/template/v1.0.0/schema.json" } } } @@ -158,84 +158,74 @@ "require_any_field": { "$comment": "Please list all fields here so that we can force the existence of one of them in other parts of the schemas.", "anyOf": [ - {"required": ["cf:parameter"]} + { + "oneOf": [ + { + "type": "object", + "required": [ + "standard_name", + "long_name" + ], + "properties": { + "standard_name": { + "title": "CF standard_name field", + "type": "string", + "minLength": 0, + "maxLength": 0 + }, + "long_name": { + "title": "CF long_name field", + "type": "string", + "minLength": 1 + } + } + }, + { + "type": "object", + "required": [ + "standard_name" + ], + "properties": { + "standard_name": { + "title": "CF standard_name field", + "type": "string", + "minLength": 1 + }, + "long_name": { + "title": "CF long_name field", + "type": "string", + "minLength": 1 + } + } + } + ] + } ] }, "fields": { "$comment": "Add your new fields here. Don't require them here, do that above in the corresponding schema.", "type": "object", "properties": { - "cf:parameter": { - "type": "array", - "items": { - "allOf": [ - { - "oneOf": [ - { - "type": "object", - "required": [ - "standard_name", - "long_name" - ], - "properties": { - "standard_name": { - "title": "CF standard_name field", - "type": "string", - "minLength": 0, - "maxLength": 0 - }, - "long_name": { - "title": "CF long_name field", - "type": "string", - "minLength": 1 - } - } - }, - { - "type": "object", - "required": [ - "standard_name" - ], - "properties": { - "standard_name": { - "title": "CF standard_name field", - "type": "string", - "minLength": 1 - }, - "long_name": { - "title": "CF long_name field", - "type": "string", - "minLength": 1 - } - } - } - ] - }, - { - "type": "object", - "required": [ - "units" - ], - "properties": { - "units": { - "type": "string", - "minLength": 1 - }, - "cell_methods": { - "type": "string", - "minLength": 1 - }, - "asset_variable_name": { - "type": "string", - "minLength": 1 - }, - "vertical_dimension": { - "$ref": "#/definitions/vertical_dimension" - } - } - } - ] - } + "cf:standard_name": { + "title": "CF standard_name", + "type": "string" + }, + "cf:long_name": { + "title": "CF long_name field", + "type": "string", + "minLength": 1 + }, + "cf:units": { + "type": "string", + "minLength": 1 + }, + "cf:cell_methods": { + "type": "string", + "minLength": 1 + }, + "cf:asset_variable_name": { + "type": "string", + "minLength": 1 } }, "patternProperties": { @@ -244,34 +234,6 @@ } }, "additionalProperties": false - }, - "vertical_dimension": { - "title": "Vertical Dimension", - "type": "object", - "items": { - "required": [ - "standard_name", - "units" - ], - "properties":{ - "standard_name": { - "type": "string" - }, - "long_name": { - "type": "string" - }, - "units": { - "type": "string" - }, - "value": { - "type": "array", - "items": { - "type": "number" - } - } - } - } } - } } \ No newline at end of file diff --git a/package.json b/package.json index cf73c2c..efd2122 100644 --- a/package.json +++ b/package.json @@ -4,8 +4,8 @@ "scripts": { "test": "npm run check-markdown && npm run check-examples", "check-markdown": "remark . -f -r .github/remark.yaml", - "check-examples": "stac-node-validator . --lint --verbose --schemaMap https://stac-extensions.github.io/cf/v0.2.0/schema.json=./json-schema/schema.json", - "format-examples": "stac-node-validator . --format --schemaMap https://stac-extensions.github.io/cf/v0.2.0/schema.json=./json-schema/schema.json" + "check-examples": "stac-node-validator . --lint --verbose --schemaMap https://stac-extensions.github.io/template/v1.0.0/schema.json=./json-schema/schema.json", + "format-examples": "stac-node-validator . --format --schemaMap https://stac-extensions.github.io/template/v1.0.0/schema.json=./json-schema/schema.json" }, "dependencies": { "remark-cli": "^8.0.0", From dc9e64fbe289920404d7767504e25252c4fd286d Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Mon, 9 Jun 2025 14:51:04 +1200 Subject: [PATCH 10/32] some backup files, for deletion later. --- examples/collection.jsonbackup | 131 ++++++++++++ examples/item.jsonbackup | 141 +++++++++++++ examples/item_asset.jsonbackup | 141 +++++++++++++ examples/standalone_collection.jsonbackup | 93 +++++++++ json-schema/schema.json_cf | 195 ++++++++++++++++++ json-schema/schema.json_orig | 202 +++++++++++++++++++ json-schema/schema_business.json | 231 ++++++++++++++++++++++ 7 files changed, 1134 insertions(+) create mode 100644 examples/collection.jsonbackup create mode 100644 examples/item.jsonbackup create mode 100644 examples/item_asset.jsonbackup create mode 100644 examples/standalone_collection.jsonbackup create mode 100644 json-schema/schema.json_cf create mode 100644 json-schema/schema.json_orig create mode 100644 json-schema/schema_business.json diff --git a/examples/collection.jsonbackup b/examples/collection.jsonbackup new file mode 100644 index 0000000..b9e6dd6 --- /dev/null +++ b/examples/collection.jsonbackup @@ -0,0 +1,131 @@ +{ + "stac_version": "1.0.0", + "stac_extensions": [ + "https://stac-extensions.github.io/cf/v0.2.0/schema.json", + "https://stac-extensions.github.io/datacube/v2.2.0/schema.json" + ], + "type": "Collection", + "id": "Sentinel2-L1C", + "title": "Atmospheric time series data", + "description": "Time series with elements described in CF nomenclature including height and aggregation methods.", + "license": "proprietary", + "extent": { + "spatial": { + "bbox": [ + [ + -180, + -56, + 180, + 83 + ] + ] + }, + "temporal": { + "interval": [ + [ + "2015-06-23T00:00:00Z", + "2019-07-10T13:44:56Z" + ] + ] + } + }, + "cf:standard_name": "height ", + "cf:long_name": "a long name", + "cube:dimensions": { + "time_interval1": { + "type": "temporal", + "description": "time interval that cell_methods is applied over", + "values": [ + -24 + ], + "unit": "h" + }, + "vertical_dimension1": { + "type": "spatial", + "axis": "z", + "cf:standard_name": "height", + "description": "Height above ground level", + "unit": "m", + "values": [ + 10 + ] + }, + "time_interval2": { + "type": "temporal", + "description": "time interval that cell_methods is applied over", + "values": [ + -60 + ], + "unit": "min" + }, + "vertical_dimension2": { + "type": "spatial", + "axis": "z", + "cf:standard_name": "height", + "description": "Air pressure", + "cf:long_name": "", + "unit": "hPa", + "values": [ + 500 + ] + } + }, + "cube:variables": { + "sea_surface_temperature": { + "type": "data", + "cf:standard_name": "sea_surface_temperature", + "description": "Average temperature on sea surface for preceding 24 hours", + "cf:long_name": "Average temperature on sea surface for preceding 24 hours", + "unit": "K", + "cf:cell_methods": "time: mean", + "dimensions": [ + "time_interval1" + ] + }, + "wind_speed_at_10m": { + "type": "data", + "cf:standard_name": "wind_speed", + "description": "minimum wind speed in 1 hour at 10 m agl", + "cf:long_name": "minimum wind speed in 1 hour at 10 m agl", + "units": "kt", + "cf:cell_methods": "time: minimum", + "dimensions": [ + "vertical_dimension1", + "time_interval2" + ] + }, + "temp_at_500hPa": { + "type": "data", + "cf:standard_name": "air_temperature", + "description": "air temperature at 500 hPa", + "cf:long_name": "air temperature at 500 hPa", + "units": "degC", + "dimensions": [ + "vertical_dimension2" + ] + } + }, + "summaries": { + "datetime": { + "minimum": "2015-06-23T00:00:00Z", + "maximum": "2019-07-10T13:44:56Z" + }, + "cf:standard_name": "height", + "cf:long_name": "a long name" + }, + "assets": { + "cf:standard_name": "height", + "cf:long_name": "a long name" + }, + "links": [ + { + "rel": "self", + "href": "https://example.sentinel2-hub.com/stac/example-collection.json" + }, + { + "rel": "license", + "href": "https://scihub.copernicus.eu/twiki/pub/SciHubWebPortal/TermsConditions/Sentinel_Data_Terms_and_Conditions.pdf", + "title": "Legal notice on the use of Copernicus Sentinel Data and Service Information" + } + ] +} \ No newline at end of file diff --git a/examples/item.jsonbackup b/examples/item.jsonbackup new file mode 100644 index 0000000..614ba2b --- /dev/null +++ b/examples/item.jsonbackup @@ -0,0 +1,141 @@ +{ + "stac_version": "1.0.0", + "stac_extensions": [ + "https://stac-extensions.github.io/cf/v0.2.0/schema.json" + ], + "id": "datacube-123", + "type": "Feature", + "geometry": { + "type": "Polygon", + "coordinates": [ + [ + [ + -122.308150179, + 37.488035566 + ], + [ + -122.597502109, + 37.538869539 + ], + [ + -122.576687533, + 37.613537207 + ], + [ + -122.2880486, + 37.562818007 + ], + [ + -122.308150179, + 37.488035566 + ] + ] + ] + }, + "bbox": [ + -122.59750209, + 37.48803556, + -122.2880486, + 37.613537207 + ], + "properties": { + "title": "Multi-dimensional data cube 123 in a STAC Item.", + "datetime": "2016-05-03T13:21:30.040Z", + "cf:standard_name": "", + "cube:dimensions": { + "x": { + "type": "spatial", + "axis": "x", + "extent": [ + -122.59750209, + -122.2880486 + ], + "reference_system": 4326 + }, + "y": { + "type": "spatial", + "axis": "y", + "extent": [ + 37.48803556, + 37.613537207 + ], + "reference_system": 4326 + }, + "pressure_levels": { + "type": "spatial", + "axis": "z", + "extent": [ + 0, + 1000 + ], + "step": 100, + "unit": "Pa" + }, + "metered_levels": { + "type": "spatial", + "axis": "z", + "values": [ + 0, + 10, + 25, + 50, + 100, + 1000 + ], + "unit": "m" + }, + "time": { + "type": "temporal", + "values": [ + "2016-05-03T13:21:30.040Z" + ] + }, + "spectral": { + "type": "bands", + "values": [ + "red", + "green", + "blue" + ] + } + }, + "cube:variables": { + "temp": { + "dimensions": [ + "time", + "y", + "x", + "pressure_levels" + ], + "type": "data" + }, + "color": { + "dimensions": [], + "type": "auxiliary", + "values": [ + "red", + "green", + "blue" + ] + } + } + }, + "assets": { + "data": { + "href": "http://cool-sat.com/catalog/datacube-123/data.nc", + "type": "application/netcdf", + "title": "netCDF Data cube" + }, + "thumbnail": { + "href": "http://cool-sat.com/catalog/datacube-123/thumbnail.png", + "type": "image/png", + "title": "Thumbnail" + } + }, + "links": [ + { + "rel": "self", + "href": "http://cool-sat.com/catalog/datacube-123/item.json" + } + ] +} \ No newline at end of file diff --git a/examples/item_asset.jsonbackup b/examples/item_asset.jsonbackup new file mode 100644 index 0000000..06c0ac8 --- /dev/null +++ b/examples/item_asset.jsonbackup @@ -0,0 +1,141 @@ +{ + "stac_version": "1.0.0", + "stac_extensions": [ + "https://stac-extensions.github.io/cf/v0.2.0/schema.json", + "https://stac-extensions.github.io/datacube/v2.2.0/schema.json" + ], + "id": "datacube-123", + "type": "Feature", + "geometry": { + "type": "Polygon", + "coordinates": [ + [ + [ + -122.308150179, + 37.488035566 + ], + [ + -122.597502109, + 37.538869539 + ], + [ + -122.576687533, + 37.613537207 + ], + [ + -122.2880486, + 37.562818007 + ], + [ + -122.308150179, + 37.488035566 + ] + ] + ] + }, + "bbox": [ + -122.59750209, + 37.48803556, + -122.2880486, + 37.613537207 + ], + "properties": { + "title": "Multi-dimensional data cube 123 in a STAC Item.", + "datetime": "2016-05-03T13:21:30.040Z" + }, + "assets": { + "data": { + "href": "http://cool-sat.com/catalog/datacube-123/data.nc", + "type": "application/netcdf", + "title": "netCDF Data cube", + "cube:dimensions": { + "x": { + "type": "spatial", + "axis": "x", + "extent": [ + -122.59750209, + -122.2880486 + ], + "reference_system": 4326 + }, + "y": { + "type": "spatial", + "axis": "y", + "extent": [ + 37.48803556, + 37.613537207 + ], + "reference_system": 4326 + }, + "pressure_levels": { + "type": "spatial", + "axis": "z", + "extent": [ + 0, + 1000 + ], + "step": 100, + "unit": "Pa" + }, + "metered_levels": { + "type": "spatial", + "axis": "z", + "values": [ + 0, + 10, + 25, + 50, + 100, + 1000 + ], + "unit": "m" + }, + "time": { + "type": "temporal", + "values": [ + "2016-05-03T13:21:30.040Z" + ] + }, + "spectral": { + "type": "bands", + "values": [ + "red", + "green", + "blue" + ] + } + }, + "cube:variables": { + "temp": { + "dimensions": [ + "time", + "y", + "x", + "pressure_levels" + ], + "type": "data" + }, + "color": { + "dimensions": [], + "type": "auxiliary", + "values": [ + "red", + "green", + "blue" + ] + } + } + }, + "thumbnail": { + "href": "http://cool-sat.com/catalog/datacube-123/thumbnail.png", + "type": "image/png", + "title": "Thumbnail" + } + }, + "links": [ + { + "rel": "self", + "href": "http://cool-sat.com/catalog/datacube-123/item.json" + } + ] +} \ No newline at end of file diff --git a/examples/standalone_collection.jsonbackup b/examples/standalone_collection.jsonbackup new file mode 100644 index 0000000..4a02942 --- /dev/null +++ b/examples/standalone_collection.jsonbackup @@ -0,0 +1,93 @@ +{ + "stac_version": "1.0.0", + "stac_extensions": [ + "https://stac-extensions.github.io/cf/v0.2.0/schema.json" + ], + "type": "Collection", + "id": "standalone_collection", + "title": "Collection without Items", + "description": "A description", + "license": "Apache-2.0", + "extent": { + "spatial": { + "bbox": [ + [ + 172.9, + 1.3, + 173, + 1.4 + ] + ] + }, + "temporal": { + "interval": [ + [ + "2015-06-23T00:00:00Z", + null + ] + ] + } + }, + "cf:standard_name": "height", + "summaries": { + "cf:parameter": [ + { + "standard_name": "sea_surface_temperature", + "long_name": "Average temperature on sea surface for preceding 24 hours", + "units": "K", + "cell_methods": "t: mean (interval: -24h)", + "asset_variable_name": "sst" + }, + { + "standard_name": "wind_speed", + "long_name": "minimum wind speed in 1 hour at 10 m agl", + "units": "kt", + "cell_methods": "t: minimum (interval: -1 h)", + "asset_variable_name": "ws_min_1h", + "vertical_dimension": { + "standard_name": "height", + "long_name": "Height above ground level", + "units": "m", + "values": [ + "10" + ] + } + } + ] + }, + "assets": { + "example": { + "href": "https://example.com/examples/example.nc", + "cf:parameter": [ + { + "standard_name": "sea_surface_temperature", + "long_name": "Average temperature on sea surface for preceding 24 hours", + "units": "K", + "cell_methods": "t: mean (interval: -24h)", + "asset_variable_name": "sst" + }, + { + "standard_name": "wind_speed", + "long_name": "minimum wind speed in 1 hour at 10 m agl", + "units": "kt", + "cell_methods": "t: minimum (interval: -1 h)", + "asset_variable_name": "ws_min_1h", + "vertical_dimension": { + "standard_name": "height", + "long_name": "Height above ground level", + "units": "m", + "values": [ + "10" + ] + } + } + ] + } + }, + "links": [ + { + "href": "https://example.com/examples/standalone_collection.json", + "rel": "self" + } + ] +} \ No newline at end of file diff --git a/json-schema/schema.json_cf b/json-schema/schema.json_cf new file mode 100644 index 0000000..b24eeec --- /dev/null +++ b/json-schema/schema.json_cf @@ -0,0 +1,195 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://stac-extensions.github.io/template/v1.0.0/schema.json#", + "title": "Climate and Forecasting Convention Extension", + "description": "STAC CF Extension for STAC Items and STAC Collections.", + "oneOf": [ + { + "$comment": "This is the schema for STAC Items. Remove this object if this extension only applies to Collections.", + "allOf": [ + { + "$ref": "#/definitions/stac_extensions" + }, + { + "type": "object", + "required": [ + "type", + "properties", + "assets" + ], + "properties": { + "type": { + "const": "Feature" + }, + "properties": { + "allOf": [ + { + "$comment": "Require fields here for Item Properties.", + "required": [ + ] + }, + { + "$ref": "#/definitions/fields" + } + ] + }, + "assets": { + "$comment": "This validates the fields in Item Assets, but does not require them.", + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/fields" + } + } + } + } + ] + }, + { + "$comment": "This is the schema for STAC Collections.", + "type": "object", + "allOf": [ + { + "required": [ + "type" + ], + "properties": { + "type": { + "const": "Collection" + } + } + }, + { + "$ref": "#/definitions/stac_extensions" + } + ], + "anyOf": [ + { + "$comment": "This is the schema for the top-level fields in a Collection. Remove this if this extension does not define top-level fields for Collections.", + "allOf": [ + { + "$comment": "Require fields here for Collections (top-level).", + "required": [ + ] + }, + { + "$ref": "#/definitions/fields" + } + ] + }, + { + "$comment": "This validates the fields in Collection Assets, but does not require them.", + "required": [ + "assets" + ], + "properties": { + "assets": { + "type": "object", + "not": { + "additionalProperties": { + "not": { + "allOf": [ + { + "$ref": "#/definitions/require_any_field" + }, + { + "$ref": "#/definitions/fields" + } + ] + } + } + } + } + } + }, + { + "$comment": "This is the schema for the fields in Item Asset Definitions. It doesn't require any fields.", + "required": [ + "item_assets" + ], + "properties": { + "item_assets": { + "type": "object", + "not": { + "additionalProperties": { + "not": { + "allOf": [ + { + "$ref": "#/definitions/require_any_field" + }, + { + "$ref": "#/definitions/fields" + } + ] + } + } + } + } + } + }, + { + "$comment": "This is the schema for the fields in Summaries. By default, only checks the existence of the properties, but not the schema of the summaries.", + "required": [ + "summaries" + ], + "properties": { + "summaries": { + "$ref": "#/definitions/require_any_field" + } + } + } + ] + } + ], + "definitions": { + "stac_extensions": { + "type": "object", + "required": [ + "stac_extensions" + ], + "properties": { + "stac_extensions": { + "type": "array", + "contains": { + "const": "https://stac-extensions.github.io/cf/v0.2.0/schema.json" + } + } + } + }, + "require_any_field": { + "$comment": "Please list all fields here so that we can force the existence of one of them in other parts of the schemas." + }, + "fields": { + "$comment": "Add your new fields here. Don't require them here, do that above in the corresponding schema.", + "type": "object", + "properties": { + "cf:standard_name": { + "title": "CF standard_name", + "type": "string" + }, + "cf:long_name": { + "title": "CF long_name field", + "type": "string", + "minLength": 1 + }, + "cf:units": { + "type": "string", + "minLength": 1 + }, + "cf:cell_methods": { + "type": "string", + "minLength": 1 + }, + "cf:asset_variable_name": { + "type": "string", + "minLength": 1 + } + }, + "patternProperties": { + "^(?!cf:)": { + "$comment": "Above, change `template` to the prefix of this extension" + } + }, + "additionalProperties": false + } + } +} \ No newline at end of file diff --git a/json-schema/schema.json_orig b/json-schema/schema.json_orig new file mode 100644 index 0000000..293013d --- /dev/null +++ b/json-schema/schema.json_orig @@ -0,0 +1,202 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://stac-extensions.github.io/cf/v0.2.0/schema.json#", + "title": "CF Extension", + "description": "STAC CF Extension for STAC Items and STAC Collections.", + "type": "object", + "required": [ + "stac_extensions" + ], + "properties": { + "stac_extensions": { + "type": "array", + "contains": { + "const": "https://stac-extensions.github.io/cf/v0.2.0/schema.json" + } + }, + "assets": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/fields" + } + } + }, + "oneOf": [ + { + "$comment": "Schema for Collections", + "type": "object", + "required": [ + "type" + ], + "properties": { + "type": { + "const": "Collection" + }, + "item_assets": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/fields" + } + }, + "summaries": { + "oneOf": [ + { + "$ref": "#/definitions/fields" + }, + { + "$comment": "JSON Schema summary", + "type": "object", + "properties": { + "cf:parameter": { + "type": "object", + "properties": { + "type": { + "const": "array" + } + } + } + }, + "patternProperties": { + "^(?!cf:)": { + "$comment": "Above, change `cf` to the prefix of this extension" + } + }, + "additionalProperties": false + } + ] + } + }, + "allOf": [ + { + "$ref": "#/definitions/fields" + } + ] + }, + { + "$comment": "Schema for Items", + "type": "object", + "required": [ + "type" + ], + "properties": { + "type": { + "const": "Feature" + }, + "properties": { + "$ref": "#/definitions/fields" + } + }, + "allOf": [ + { + "$ref": "#/definitions/cf_in_assets" + } + ] + } + ], + "definitions": { + "cf_in_assets": { + "required": [ + "assets" + ], + "properties": { + "assets": { + "not": { + "additionalProperties": { + "not": { + "allOf": [ + { + "required": [ + "cf:parameter" + ] + }, + { + "$ref": "#/definitions/fields" + } + ] + } + } + } + } + } + }, + "forbid_fields": { + "patternProperties": { + "^(?!cf:)": {} + }, + "additionalProperties": false + }, + "fields": { + "type": "object", + "properties": { + "cf:parameter": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "required": [ + "units" + ], + "properties": { + "standard_name": { + "title": "CF standard_name field", + "type": "string", + "minLength": 1 + }, + "long_name": { + "title": "CF long_name field", + "type": "string", + "minLength": 1 + }, + "units": { + "type": "string", + "minLength": 1 + }, + "cell_methods": { + "type": "string", + "minLength": 1 + }, + "vertical_dimension": { + "$ref": "#/definitions/vertical_dimension" + + } + + } + } + } + }, + "patternProperties": { + "^(?!cf:)": { + "$comment": "Above, change `cf` to the prefix of this extension" + } + }, + "additionalProperties": false + }, + "vertical_dimension": { + "title": "Vertical Dimension Object", + "type": "object", + "items": { + "required": [ + "standard_name", + "units" + ], + "properties":{ + "standard_name": { + "type": "string" + }, + "long_name": { + "type": "string" + }, + "units": { + "type": "string" + }, + "values": { + "type": "array", + "items": { + "type": "number" + } + } + } + } + } + } +} diff --git a/json-schema/schema_business.json b/json-schema/schema_business.json new file mode 100644 index 0000000..688ce5d --- /dev/null +++ b/json-schema/schema_business.json @@ -0,0 +1,231 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://stac-extensions.github.io/template/v1.0.0/schema.json#", + "title": "Business Extension", + "description": "STAC Business Extension for STAC Items and STAC Collections.", + "oneOf": [ + { + "$comment": "This is the schema for STAC Items. Remove this object if this extension only applies to Collections.", + "allOf": [ + { + "$ref": "#/definitions/stac_extensions" + }, + { + "type": "object", + "required": [ + "type", + "properties", + "assets" + ], + "properties": { + "type": { + "const": "Feature" + }, + "properties": { + "allOf": [ + { + "$comment": "Require fields here for Item Properties.", + "required": [ + ] + }, + { + "$ref": "#/definitions/fields" + } + ] + }, + "assets": { + "$comment": "This validates the fields in Item Assets, but does not require them.", + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/fields" + } + } + } + } + ] + }, + { + "$comment": "This is the schema for STAC Collections.", + "type": "object", + "allOf": [ + { + "required": [ + "type" + ], + "properties": { + "type": { + "const": "Collection" + } + } + }, + { + "$ref": "#/definitions/stac_extensions" + } + ], + "anyOf": [ + { + "$comment": "This is the schema for the top-level fields in a Collection. Remove this if this extension does not define top-level fields for Collections.", + "allOf": [ + { + "$comment": "Require fields here for Collections (top-level).", + "required": [ + ] + }, + { + "$ref": "#/definitions/fields" + } + ] + }, + { + "$comment": "This validates the fields in Collection Assets, but does not require them.", + "required": [ + "assets" + ], + "properties": { + "assets": { + "type": "object", + "not": { + "additionalProperties": { + "not": { + "allOf": [ + { + "$ref": "#/definitions/require_any_field" + }, + { + "$ref": "#/definitions/fields" + } + ] + } + } + } + } + } + }, + { + "$comment": "This is the schema for the fields in Item Asset Definitions. It doesn't require any fields.", + "required": [ + "item_assets" + ], + "properties": { + "item_assets": { + "type": "object", + "not": { + "additionalProperties": { + "not": { + "allOf": [ + { + "$ref": "#/definitions/require_any_field" + }, + { + "$ref": "#/definitions/fields" + } + ] + } + } + } + } + } + }, + { + "$comment": "This is the schema for the fields in Summaries. By default, only checks the existence of the properties, but not the schema of the summaries.", + "required": [ + "summaries" + ], + "properties": { + "summaries": { + "$ref": "#/definitions/require_any_field" + } + } + } + ] + } + ], + "definitions": { + "stac_extensions": { + "type": "object", + "required": [ + "stac_extensions" + ], + "properties": { + "stac_extensions": { + "type": "array", + "contains": { + "const": "https://stac-extensions.github.io/template/v1.0.0/schema.json" + } + } + } + }, + "require_any_field": { + "$comment": "Please list all fields here so that we can force the existence of one of them in other parts of the schemas.", + "anyOf": [ + {"required": ["business:data_owner"]}, + {"required": ["business:content_data_steward"]}, + {"required": ["business:technical_data_steward"]}, + {"required": ["business:retain_for"]}, + {"required": ["business:retain_until"]}, + {"required": ["business:transition"]}, + {"required": ["business:approved_for"]}, + {"required": ["business:sensitivity"]} + ] + }, + "fields": { + "$comment": "Add your new fields here. Don't require them here, do that above in the corresponding schema.", + "type": "object", + "properties": { + "business:data_owner": { + "type": "string" + }, + "business:content_data_steward": { + "type": "string" + }, + "business:technical_data_steward": { + "type": "string" + }, + "business:retain_for": { + "type": "string" + }, + "business:retain_until": { + "type": "string", + "format": "datetime" + }, + "business:transition": { + "type": "string", + "enum": [ + "expiration", + "Archives NZ" + ] + }, + "business:approved_for": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "Aviation 24/7", + "24/7", + "Development", + "Project", + "Research", + "AI" + ] + } + }, + "business:sensitivity": { + "type": "string", + "enum": [ + "personal", + "public", + "internal use only", + "confidential", + "highly confidential" + ] + } + }, + "patternProperties": { + "^(?!business:)": { + "$comment": "Above, change `template` to the prefix of this extension" + } + }, + "additionalProperties": false + } + } +} From f96d3180443f2f9ef568a8d8ebd5ad934d3cab6d Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Mon, 7 Jul 2025 16:26:37 +1200 Subject: [PATCH 11/32] Update examples/collection.json Co-authored-by: Emmanuel Mathot --- examples/collection.json | 1 - 1 file changed, 1 deletion(-) diff --git a/examples/collection.json b/examples/collection.json index a23725c..8c8c353 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -1,7 +1,6 @@ { "stac_version": "1.0.0", "stac_extensions": [ - "https://stac-extensions.github.io/item-assets/v1.0.0/schema.json", "https://stac-extensions.github.io/template/v1.0.0/schema.json" ], "type": "Collection", From c3dceecb7ef3784a2863236bf5690db0a8c2b34e Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Thu, 23 Oct 2025 14:35:05 +1300 Subject: [PATCH 12/32] Reduced to defining fields, and making long_name and units optional --- README.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 2d78ab2..54ae3c6 100644 --- a/README.md +++ b/README.md @@ -29,14 +29,22 @@ The fields in the table below can be used in these parts of STAC documents: | Field Name | Type | Description | | ------------ | --------------------------- | ----------------------------------------------------------------------------------- | -| cf:standard_name | string | **REQUIRED** Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) if variable has a standard_name definition in the CF convention. Otherwise standard_name remains an empty value. | -| cf:long_name | string | **REQUIRED if standard_name does not exist for variable in CF convention and is an empty value.** The long_name attribute is defined by the [NUG](https://docs.unidata.ucar.edu/nug/current/index.html) to contain a long descriptive name which may, for example, be used for labeling plots. See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. | -| cf:units | string | **REQUIRED**. The units attribute can be recognized by the UDUNITS package [UDUNITS](https://cfconventions.org/cf-conventions/cf-conventions.html#UDUNITS). If the variable is dimensionless then the value is set to 1. See [CF Units](https://cfconventions.org/cf-conventions/cf-conventions.html#units) for more details. | -| cell_methods | string | This is a string attribute comprising a list of blank-separated words of the form "name: method". Each "name: method" pair indicates that for an axis identified by name, the cell values representing the field have been determined or derived by the specified method. For example, if data values have been generated by computing time means, then this could be indicated with cell_methods="t: mean", assuming here that the name of the time dimension variable is "t". See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. | -| cf:asset_variable_name | string | The variable name used in the asset that corresponds to this element described by the CF attributes. Highly recommended to specify if the asset itself does not use CF convention itself to describe the elements but rather ambiguous and/or cryptic variable names. | +| cf:standard_name | string | Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) if variable has a standard_name definition in the CF convention. Otherwise standard_name remains an empty value. | +| cf:cell_methods | [string] | This is a list of string attributes that describe the "method" applied to the data as defined in the CF conventions. | +| cf:long_name | string | When using this extension within another extension that does not have a "description" field defined, this field name can be used. | +| cf:units | string | The units attribute can be recognized by the UDUNITS package [UDUNITS](https://cfconventions.org/cf-conventions/cf-conventions.html#UDUNITS). If the variable is dimensionless then the value is set to 1. See [CF Units](https://cfconventions.org/cf-conventions/cf-conventions.html#units) for more details. | ### Additional Field Information +#### cf:cell_methods +The cell_methods attribute in the CF (Climate and Forecast) convention is designed to describe how the values in a data variable were derived with respect to one or more axes (e.g., time, latitude, longitude). Each "method" represents the statistical or computational operations applied to data along specific axes. For example, if data values have been generated by computing time means, then this could be indicated with cell_methods="t: mean", assuming here that the name of the time dimension variable is "t". See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. + +#### cf:long_name +The use of this field is conditional that there is no "description" field already defined as part of another extension that is used. For example the datacube extension has a "description" field defined which would take priority in use over this field. However, if there is no "description" field defined within an extension then this field name can be used. +The long_name attribute is defined by the [NUG](https://docs.unidata.ucar.edu/nug/current/index.html) to contain a long descriptive name which may, for example, be used for labeling plots. See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. + +#### cf:units +The use of this field is conditional that there is no "unit" field already defined as part of another extension that is used. For example, the [datacube extension](https://github.com/stac-extensions/datacube) has a "unit" field defined that also requires UDUNITS compliance, which would take priority in use over this field. For example, in a datacube asset definition: ## Contributing From f02e48b75ac424e60832e0b9fa0248043600c280 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Thu, 23 Oct 2025 17:59:10 +1300 Subject: [PATCH 13/32] reducing to defining the essential fields, meant to embed in other extensions like datacube --- README.md | 33 +++-- examples/collection.json | 14 +-- examples/item.json | 72 ++++++++++- .../standalone_collection.json_notworking | 115 ++++++++++++++++++ examples/standalone_collection.jsonbackup | 93 -------------- json-schema/schema.json | 61 ++-------- package.json | 2 +- 7 files changed, 226 insertions(+), 164 deletions(-) create mode 100644 examples/standalone_collection.json_notworking delete mode 100644 examples/standalone_collection.jsonbackup diff --git a/README.md b/README.md index 54ae3c6..c54d77e 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,6 @@ It adds a field to provide the Standard Name Table based on the [CF metadata con - Examples: - [Item](examples/item.json) and [Collection](examples/collection.json): Shows the basic usage of the extension in a STAC Item and a corresponding summarizing STAC Collection - - [Standalone Collection](examples/standalone_collection.json): - Shows the basic usage of the extension in a STAC Collection without items - [JSON Schema](json-schema/schema.json) - [Changelog](./CHANGELOG.md) @@ -29,22 +27,37 @@ The fields in the table below can be used in these parts of STAC documents: | Field Name | Type | Description | | ------------ | --------------------------- | ----------------------------------------------------------------------------------- | -| cf:standard_name | string | Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) if variable has a standard_name definition in the CF convention. Otherwise standard_name remains an empty value. | -| cf:cell_methods | [string] | This is a list of string attributes that describe the "method" applied to the data as defined in the CF conventions. | -| cf:long_name | string | When using this extension within another extension that does not have a "description" field defined, this field name can be used. | -| cf:units | string | The units attribute can be recognized by the UDUNITS package [UDUNITS](https://cfconventions.org/cf-conventions/cf-conventions.html#UDUNITS). If the variable is dimensionless then the value is set to 1. See [CF Units](https://cfconventions.org/cf-conventions/cf-conventions.html#units) for more details. | +| cf:standard_name | string | Should be a non-empty value from the +[CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) if variable +has a standard_name definition in the CF convention. Otherwise standard_name remains an empty value. | +| cf:cell_methods | \[string] | This is a list of string attributes that describe the "method" applied to the data as +defined in the CF conventions. | +| cf:long_name | string | When using this CF extension within another extension that does not have a "description" +field defined, this field name can be used for a long descriptive name of the variable as defined in the CF conventions. | +| cf:units | string | When using this CF extension within another extension that does not have a "unit" field +defined, this field name can be used for specifying the unit of the variable. | ### Additional Field Information #### cf:cell_methods -The cell_methods attribute in the CF (Climate and Forecast) convention is designed to describe how the values in a data variable were derived with respect to one or more axes (e.g., time, latitude, longitude). Each "method" represents the statistical or computational operations applied to data along specific axes. For example, if data values have been generated by computing time means, then this could be indicated with cell_methods="t: mean", assuming here that the name of the time dimension variable is "t". See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. +The cell_methods attribute in the CF (Climate and Forecast) convention is designed to describe how the values in a data variable +were derived with respect to one or more axes (e.g., time, latitude, longitude). Each "method" represents the statistical or +computational operations applied to data along specific axes. For example, if data values have been generated by computing time +means, then this could be indicated with cell_methods="t: mean", assuming here that the name of the time dimension variable is "t". +See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. #### cf:long_name -The use of this field is conditional that there is no "description" field already defined as part of another extension that is used. For example the datacube extension has a "description" field defined which would take priority in use over this field. However, if there is no "description" field defined within an extension then this field name can be used. -The long_name attribute is defined by the [NUG](https://docs.unidata.ucar.edu/nug/current/index.html) to contain a long descriptive name which may, for example, be used for labeling plots. See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. +The use of this field is conditional that there is no "description" field already defined as part of another extension that is used. +For example the datacube extension has a "description" field defined which would take priority in use over this field. +However, if there is no "description" field defined within an extension then this field name can be used. +The long_name attribute is defined by the [NUG](https://docs.unidata.ucar.edu/nug/current/index.html) to contain a long descriptive +name which may, for example, be used for labeling plots. +See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. #### cf:units -The use of this field is conditional that there is no "unit" field already defined as part of another extension that is used. For example, the [datacube extension](https://github.com/stac-extensions/datacube) has a "unit" field defined that also requires UDUNITS compliance, which would take priority in use over this field. For example, in a datacube asset definition: +The use of this field is conditional that there is no "unit" field already defined as part of another extension that is used. +For example, the [datacube extension](https://github.com/stac-extensions/datacube) has a "unit" field defined that also +requires UDUNITS compliance, which would take priority in use over this field. ## Contributing diff --git a/examples/collection.json b/examples/collection.json index 8c8c353..3480007 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -30,16 +30,14 @@ }, "assets": { "example": { - "href": "https://example.com/examples/file.xyz", - "template:new_field": "test" + "href": "https://example.com/examples/file.xyz" } }, "item_assets": { "data": { "roles": [ "data" - ], - "template:new_field": "test" + ] } }, "summaries": { @@ -79,7 +77,6 @@ "axis": "z", "cf:standard_name": "height", "description": "Air pressure", - "cf:long_name": "", "unit": "hPa", "values": [ 500 @@ -91,7 +88,6 @@ "type": "data", "cf:standard_name": "sea_surface_temperature", "description": "Average temperature on sea surface for preceding 24 hours", - "cf:long_name": "Average temperature on sea surface for preceding 24 hours", "unit": "K", "cf:cell_methods": "time: mean", "dimensions": [ @@ -102,8 +98,7 @@ "type": "data", "cf:standard_name": "wind_speed", "description": "minimum wind speed in 1 hour at 10 m agl", - "cf:long_name": "minimum wind speed in 1 hour at 10 m agl", - "units": "kt", + "unit": "kt", "cf:cell_methods": "time: minimum", "dimensions": [ "vertical_dimension1", @@ -114,8 +109,7 @@ "type": "data", "cf:standard_name": "air_temperature", "description": "air temperature at 500 hPa", - "cf:long_name": "air temperature at 500 hPa", - "units": "degC", + "unit": "degC", "dimensions": [ "vertical_dimension2" ] diff --git a/examples/item.json b/examples/item.json index cf19370..00f0632 100644 --- a/examples/item.json +++ b/examples/item.json @@ -50,7 +50,77 @@ 1, 2, 3 - ] + ], + "cube:dimensions": { + "time_interval1": { + "type": "temporal", + "description": "time interval that cell_methods is applied over", + "values": [ + -24 + ], + "unit": "h" + }, + "vertical_dimension1": { + "type": "spatial", + "axis": "z", + "cf:standard_name": "height", + "description": "Height above ground level", + "unit": "m", + "values": [ + 10 + ] + }, + "time_interval2": { + "type": "temporal", + "description": "time interval that cell_methods is applied over", + "values": [ + -60 + ], + "unit": "min" + }, + "vertical_dimension2": { + "type": "spatial", + "axis": "z", + "cf:standard_name": "height", + "description": "Air pressure", + "unit": "hPa", + "values": [ + 500 + ] + } + }, + "cube:variables": { + "sea_surface_temperature": { + "type": "data", + "cf:standard_name": "sea_surface_temperature", + "description": "Average temperature on sea surface for preceding 24 hours", + "unit": "K", + "cf:cell_methods": "time: mean", + "dimensions": [ + "time_interval1" + ] + }, + "wind_speed_at_10m": { + "type": "data", + "cf:standard_name": "wind_speed", + "description": "minimum wind speed in 1 hour at 10 m agl", + "unit": "kt", + "cf:cell_methods": "time: minimum", + "dimensions": [ + "vertical_dimension1", + "time_interval2" + ] + }, + "temp_at_500hPa": { + "type": "data", + "cf:standard_name": "air_temperature", + "description": "air temperature at 500 hPa", + "unit": "degC", + "dimensions": [ + "vertical_dimension2" + ] + } + } }, "links": [ { diff --git a/examples/standalone_collection.json_notworking b/examples/standalone_collection.json_notworking new file mode 100644 index 0000000..a8534c2 --- /dev/null +++ b/examples/standalone_collection.json_notworking @@ -0,0 +1,115 @@ +{ + "stac_version": "1.0.0", + "stac_extensions": [ + "https://stac-extensions.github.io/cf/v0.2.0/schema.json" + ], + "type": "Collection", + "id": "standalone_collection", + "title": "Collection without Items", + "description": "A description", + "license": "Apache-2.0", + "extent": { + "spatial": { + "bbox": [ + [ + 172.9, + 1.3, + 173, + 1.4 + ] + ] + }, + "temporal": { + "interval": [ + [ + "2015-06-23T00:00:00Z", + null + ] + ] + } + }, + "summaries": { + "cf:standard_name": "height", + "cube:dimensions": { + "time_interval1": { + "type": "temporal", + "description": "time interval that cell_methods is applied over", + "values": [ + -24 + ], + "unit": "h" + }, + "vertical_dimension1": { + "type": "spatial", + "axis": "z", + "cf:standard_name": "height", + "description": "Height above ground level", + "unit": "m", + "values": [ + 10 + ] + }, + "time_interval2": { + "type": "temporal", + "description": "time interval that cell_methods is applied over", + "values": [ + -60 + ], + "unit": "min" + }, + "vertical_dimension2": { + "type": "spatial", + "axis": "z", + "cf:standard_name": "height", + "description": "Air pressure", + "unit": "hPa", + "values": [ + 500 + ] + } + }, + "cube:variables": { + "sea_surface_temperature": { + "type": "data", + "cf:standard_name": "sea_surface_temperature", + "description": "Average temperature on sea surface for preceding 24 hours", + "unit": "K", + "cf:cell_methods": "time: mean", + "dimensions": [ + "time_interval1" + ] + }, + "wind_speed_at_10m": { + "type": "data", + "cf:standard_name": "wind_speed", + "description": "minimum wind speed in 1 hour at 10 m agl", + "unit": "kt", + "cf:cell_methods": "time: minimum", + "dimensions": [ + "vertical_dimension1", + "time_interval2" + ] + }, + "temp_at_500hPa": { + "type": "data", + "cf:standard_name": "air_temperature", + "description": "air temperature at 500 hPa", + "unit": "degC", + "dimensions": [ + "vertical_dimension2" + ] + } + } + }, + "assets": { + "example": { + "href": "https://example.com/examples/example.nc" + } + }, + "links": [ + { + "href": "https://example.com/examples/standalone_collection.json", + "rel": "self" + } + ] +} \ No newline at end of file diff --git a/examples/standalone_collection.jsonbackup b/examples/standalone_collection.jsonbackup deleted file mode 100644 index 4a02942..0000000 --- a/examples/standalone_collection.jsonbackup +++ /dev/null @@ -1,93 +0,0 @@ -{ - "stac_version": "1.0.0", - "stac_extensions": [ - "https://stac-extensions.github.io/cf/v0.2.0/schema.json" - ], - "type": "Collection", - "id": "standalone_collection", - "title": "Collection without Items", - "description": "A description", - "license": "Apache-2.0", - "extent": { - "spatial": { - "bbox": [ - [ - 172.9, - 1.3, - 173, - 1.4 - ] - ] - }, - "temporal": { - "interval": [ - [ - "2015-06-23T00:00:00Z", - null - ] - ] - } - }, - "cf:standard_name": "height", - "summaries": { - "cf:parameter": [ - { - "standard_name": "sea_surface_temperature", - "long_name": "Average temperature on sea surface for preceding 24 hours", - "units": "K", - "cell_methods": "t: mean (interval: -24h)", - "asset_variable_name": "sst" - }, - { - "standard_name": "wind_speed", - "long_name": "minimum wind speed in 1 hour at 10 m agl", - "units": "kt", - "cell_methods": "t: minimum (interval: -1 h)", - "asset_variable_name": "ws_min_1h", - "vertical_dimension": { - "standard_name": "height", - "long_name": "Height above ground level", - "units": "m", - "values": [ - "10" - ] - } - } - ] - }, - "assets": { - "example": { - "href": "https://example.com/examples/example.nc", - "cf:parameter": [ - { - "standard_name": "sea_surface_temperature", - "long_name": "Average temperature on sea surface for preceding 24 hours", - "units": "K", - "cell_methods": "t: mean (interval: -24h)", - "asset_variable_name": "sst" - }, - { - "standard_name": "wind_speed", - "long_name": "minimum wind speed in 1 hour at 10 m agl", - "units": "kt", - "cell_methods": "t: minimum (interval: -1 h)", - "asset_variable_name": "ws_min_1h", - "vertical_dimension": { - "standard_name": "height", - "long_name": "Height above ground level", - "units": "m", - "values": [ - "10" - ] - } - } - ] - } - }, - "links": [ - { - "href": "https://example.com/examples/standalone_collection.json", - "rel": "self" - } - ] -} \ No newline at end of file diff --git a/json-schema/schema.json b/json-schema/schema.json index 86da606..2a5f09e 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -157,49 +157,13 @@ }, "require_any_field": { "$comment": "Please list all fields here so that we can force the existence of one of them in other parts of the schemas.", - "anyOf": [ - { - "oneOf": [ - { - "type": "object", - "required": [ - "standard_name", - "long_name" - ], - "properties": { - "standard_name": { - "title": "CF standard_name field", - "type": "string", - "minLength": 0, - "maxLength": 0 - }, - "long_name": { - "title": "CF long_name field", - "type": "string", - "minLength": 1 - } - } - }, - { - "type": "object", - "required": [ - "standard_name" - ], - "properties": { - "standard_name": { - "title": "CF standard_name field", - "type": "string", - "minLength": 1 - }, - "long_name": { - "title": "CF long_name field", - "type": "string", - "minLength": 1 - } - } - } - ] - } + "anyOf": [ + {"required": [ + "cf:standard_name", + "cf:long_name", + "cf:units", + "cf:cell_methods" + ]} ] }, "fields": { @@ -220,12 +184,11 @@ "minLength": 1 }, "cf:cell_methods": { - "type": "string", - "minLength": 1 - }, - "cf:asset_variable_name": { - "type": "string", - "minLength": 1 + "type": "array", + "items": { + "type": "string", + "minLength": 1 + } } }, "patternProperties": { diff --git a/package.json b/package.json index efd2122..6440ca0 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,7 @@ "format-examples": "stac-node-validator . --format --schemaMap https://stac-extensions.github.io/template/v1.0.0/schema.json=./json-schema/schema.json" }, "dependencies": { - "remark-cli": "^8.0.0", + "remark-cli": "^12.0.1", "remark-lint": "^7.0.0", "remark-lint-no-html": "^2.0.0", "remark-preset-lint-consistent": "^3.0.0", From 2d812c21940cdd964e7872c1218ac8fbbd98f3f0 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Fri, 24 Oct 2025 08:09:19 +1300 Subject: [PATCH 14/32] Fix markdown issue with breaking long lines --- README.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index c54d77e..b55d9ba 100644 --- a/README.md +++ b/README.md @@ -27,15 +27,11 @@ The fields in the table below can be used in these parts of STAC documents: | Field Name | Type | Description | | ------------ | --------------------------- | ----------------------------------------------------------------------------------- | -| cf:standard_name | string | Should be a non-empty value from the -[CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) if variable -has a standard_name definition in the CF convention. Otherwise standard_name remains an empty value. | +| cf:standard_name | string | Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) if variable has a standard_name definition in the CF convention. Otherwise standard_name remains an empty value. | | cf:cell_methods | \[string] | This is a list of string attributes that describe the "method" applied to the data as defined in the CF conventions. | -| cf:long_name | string | When using this CF extension within another extension that does not have a "description" -field defined, this field name can be used for a long descriptive name of the variable as defined in the CF conventions. | -| cf:units | string | When using this CF extension within another extension that does not have a "unit" field -defined, this field name can be used for specifying the unit of the variable. | +| cf:long_name | string | When using this CF extension within another extension that does not have a "description" field defined, this field name can be used for a long descriptive name of the variable as defined in the CF conventions. | +| cf:units | string | When using this CF extension within another extension that does not have a "unit" field defined, this field name can be used for specifying the unit of the variable. | ### Additional Field Information From 25a98823190b35782d7552906bbe109a2c3a4ec8 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Mon, 3 Nov 2025 15:20:27 +1300 Subject: [PATCH 15/32] fix line break --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index b55d9ba..28e7a4b 100644 --- a/README.md +++ b/README.md @@ -28,8 +28,7 @@ The fields in the table below can be used in these parts of STAC documents: | Field Name | Type | Description | | ------------ | --------------------------- | ----------------------------------------------------------------------------------- | | cf:standard_name | string | Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) if variable has a standard_name definition in the CF convention. Otherwise standard_name remains an empty value. | -| cf:cell_methods | \[string] | This is a list of string attributes that describe the "method" applied to the data as -defined in the CF conventions. | +| cf:cell_methods | \[string] | This is a list of string attributes that describe the "method" applied to the data as defined in the CF conventions. | | cf:long_name | string | When using this CF extension within another extension that does not have a "description" field defined, this field name can be used for a long descriptive name of the variable as defined in the CF conventions. | | cf:units | string | When using this CF extension within another extension that does not have a "unit" field defined, this field name can be used for specifying the unit of the variable. | From 25b58bc9ca774d3c63ad172c22475ff04673c18f Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Tue, 4 Nov 2025 06:55:14 +1300 Subject: [PATCH 16/32] update after STAC community meeting --- README.md | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 28e7a4b..b860ca4 100644 --- a/README.md +++ b/README.md @@ -28,31 +28,37 @@ The fields in the table below can be used in these parts of STAC documents: | Field Name | Type | Description | | ------------ | --------------------------- | ----------------------------------------------------------------------------------- | | cf:standard_name | string | Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) if variable has a standard_name definition in the CF convention. Otherwise standard_name remains an empty value. | -| cf:cell_methods | \[string] | This is a list of string attributes that describe the "method" applied to the data as defined in the CF conventions. | -| cf:long_name | string | When using this CF extension within another extension that does not have a "description" field defined, this field name can be used for a long descriptive name of the variable as defined in the CF conventions. | -| cf:units | string | When using this CF extension within another extension that does not have a "unit" field defined, this field name can be used for specifying the unit of the variable. | +| cf:cell_methods | \[string] | This is a list of string attributes that describe the "method" applied to the data as defined in the CF conventions. | +| description string | This field contains the [CF "long_name"](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/build/ch03s02.html) information. | +| unit | string | This field contains the [CF "units" information]{https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#units} information. | ### Additional Field Information #### cf:cell_methods The cell_methods attribute in the CF (Climate and Forecast) convention is designed to describe how the values in a data variable were derived with respect to one or more axes (e.g., time, latitude, longitude). Each "method" represents the statistical or -computational operations applied to data along specific axes. For example, if data values have been generated by computing time -means, then this could be indicated with cell_methods="t: mean", assuming here that the name of the time dimension variable is "t". +computational operations applied to data along specific axes. For example, if used within the datacube extension then the order of cell_methods aligns with the order of spatial and temporal extensions. +``` +"cube:variables": { + "some_variable": { + "cf:cell_methods": [null, "minimum"], + "dimensions": [ + "vertical_dimension1", + "time_interval2" + ] + } +} +``` +In this case no method is applied over the vertical_dimension1 but the "minimum" method is applied over the temporal dimension time_interval2. See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. -#### cf:long_name -The use of this field is conditional that there is no "description" field already defined as part of another extension that is used. -For example the datacube extension has a "description" field defined which would take priority in use over this field. -However, if there is no "description" field defined within an extension then this field name can be used. -The long_name attribute is defined by the [NUG](https://docs.unidata.ucar.edu/nug/current/index.html) to contain a long descriptive +#### description +The description field as defined by the [NUG](https://docs.unidata.ucar.edu/nug/current/index.html) is meant to contain a long descriptive name which may, for example, be used for labeling plots. See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. -#### cf:units -The use of this field is conditional that there is no "unit" field already defined as part of another extension that is used. -For example, the [datacube extension](https://github.com/stac-extensions/datacube) has a "unit" field defined that also -requires UDUNITS compliance, which would take priority in use over this field. +#### unit +The unit of measurement for the values, 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). ## Contributing From 0ac091e67b50515764249deabd458dce34975902 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Tue, 4 Nov 2025 07:04:36 +1300 Subject: [PATCH 17/32] further alignment with meeting outcome --- README.md | 1 + json-schema/schema.json | 8 ++++---- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index b860ca4..c7590b8 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,7 @@ See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.htm #### unit The unit of measurement for the values, 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). +Unit is not required for dimensionless quantities. A variable with no unit attribute is assumed to be dimensionless. The conforming unit for quantities that represent fractions, or parts of a whole, is "1". Descriptive information about dimensionless quantities, such as sea-ice concentration, cloud fraction, probability, etc., should be given in the "description" attribute rather than the unit field. ## Contributing diff --git a/json-schema/schema.json b/json-schema/schema.json index 2a5f09e..aca1d85 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -160,8 +160,8 @@ "anyOf": [ {"required": [ "cf:standard_name", - "cf:long_name", - "cf:units", + "description", + "unit", "cf:cell_methods" ]} ] @@ -174,12 +174,12 @@ "title": "CF standard_name", "type": "string" }, - "cf:long_name": { + "description": { "title": "CF long_name field", "type": "string", "minLength": 1 }, - "cf:units": { + "unit": { "type": "string", "minLength": 1 }, From 86762e47897612cd3118b4bc9a4c1752670ee987 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Tue, 4 Nov 2025 07:13:05 +1300 Subject: [PATCH 18/32] align examples and markdown fixes --- README.md | 13 +++++++++---- examples/collection.json | 4 ++-- examples/item.json | 4 ++-- 3 files changed, 13 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index c7590b8..c70a7c5 100644 --- a/README.md +++ b/README.md @@ -37,8 +37,9 @@ The fields in the table below can be used in these parts of STAC documents: #### cf:cell_methods The cell_methods attribute in the CF (Climate and Forecast) convention is designed to describe how the values in a data variable were derived with respect to one or more axes (e.g., time, latitude, longitude). Each "method" represents the statistical or -computational operations applied to data along specific axes. For example, if used within the datacube extension then the order of cell_methods aligns with the order of spatial and temporal extensions. -``` +computational operations applied to data along specific axes. For example, if used within the datacube extension then the +order of cell_methods aligns with the order of spatial and temporal extensions. +```json "cube:variables": { "some_variable": { "cf:cell_methods": [null, "minimum"], @@ -58,8 +59,12 @@ name which may, for example, be used for labeling plots. See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. #### unit -The unit of measurement for the values, 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). -Unit is not required for dimensionless quantities. A variable with no unit attribute is assumed to be dimensionless. The conforming unit for quantities that represent fractions, or parts of a whole, is "1". Descriptive information about dimensionless quantities, such as sea-ice concentration, cloud fraction, probability, etc., should be given in the "description" attribute rather than the unit field. +The unit of measurement for the values, 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). +Unit is not required for dimensionless quantities. A variable with no unit attribute is assumed to be +dimensionless. The conforming unit for quantities that represent fractions, or parts of a whole, is "1". +Descriptive information about dimensionless quantities, such as sea-ice concentration, cloud fraction, +probability, etc., should be given in the "description" attribute rather than the unit field. ## Contributing diff --git a/examples/collection.json b/examples/collection.json index 3480007..4bf1b0b 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -89,7 +89,7 @@ "cf:standard_name": "sea_surface_temperature", "description": "Average temperature on sea surface for preceding 24 hours", "unit": "K", - "cf:cell_methods": "time: mean", + "cf:cell_methods": ["mean"], "dimensions": [ "time_interval1" ] @@ -99,7 +99,7 @@ "cf:standard_name": "wind_speed", "description": "minimum wind speed in 1 hour at 10 m agl", "unit": "kt", - "cf:cell_methods": "time: minimum", + "cf:cell_methods": [null, "minimum"], "dimensions": [ "vertical_dimension1", "time_interval2" diff --git a/examples/item.json b/examples/item.json index 00f0632..bcbd8d2 100644 --- a/examples/item.json +++ b/examples/item.json @@ -95,7 +95,7 @@ "cf:standard_name": "sea_surface_temperature", "description": "Average temperature on sea surface for preceding 24 hours", "unit": "K", - "cf:cell_methods": "time: mean", + "cf:cell_methods": ["mean"], "dimensions": [ "time_interval1" ] @@ -105,7 +105,7 @@ "cf:standard_name": "wind_speed", "description": "minimum wind speed in 1 hour at 10 m agl", "unit": "kt", - "cf:cell_methods": "time: minimum", + "cf:cell_methods": ["minimum"], "dimensions": [ "vertical_dimension1", "time_interval2" From e11748eb54e9a285590382882a76a55c7bf42af3 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Tue, 4 Nov 2025 07:14:20 +1300 Subject: [PATCH 19/32] typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c70a7c5..1ac1ac6 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ The fields in the table below can be used in these parts of STAC documents: | ------------ | --------------------------- | ----------------------------------------------------------------------------------- | | cf:standard_name | string | Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) if variable has a standard_name definition in the CF convention. Otherwise standard_name remains an empty value. | | cf:cell_methods | \[string] | This is a list of string attributes that describe the "method" applied to the data as defined in the CF conventions. | -| description string | This field contains the [CF "long_name"](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/build/ch03s02.html) information. | +| description | string | This field contains the [CF "long_name"](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/build/ch03s02.html) information. | | unit | string | This field contains the [CF "units" information]{https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#units} information. | ### Additional Field Information From aed66d336ae331a3447bc3cbb6f53c7392fc8a27 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Tue, 4 Nov 2025 07:17:17 +1300 Subject: [PATCH 20/32] markdown typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1ac1ac6..eb066b2 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ The fields in the table below can be used in these parts of STAC documents: | cf:standard_name | string | Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) if variable has a standard_name definition in the CF convention. Otherwise standard_name remains an empty value. | | cf:cell_methods | \[string] | This is a list of string attributes that describe the "method" applied to the data as defined in the CF conventions. | | description | string | This field contains the [CF "long_name"](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/build/ch03s02.html) information. | -| unit | string | This field contains the [CF "units" information]{https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#units} information. | +| unit | string | This field contains the [CF "units" information](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#units) information. | ### Additional Field Information From 5785fd57cca4323be259bf6c2b41fdc2b68c3d4e Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Mon, 10 Nov 2025 07:21:10 +1300 Subject: [PATCH 21/32] markdown typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index eb066b2..0622a8c 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ order of cell_methods aligns with the order of spatial and temporal extensions. } } ``` -In this case no method is applied over the vertical_dimension1 but the "minimum" method is applied over the temporal dimension time_interval2. +In this case no method is applied over the vertical_dimension1 but the "minimum" method is applied over the temporal dimension time_interval2. These dimensions are defined in the cube:dimensions fields. See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. #### description From 7c5327b15d2ecd901a70fd9333cc098db1395b68 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Mon, 10 Nov 2025 07:34:37 +1300 Subject: [PATCH 22/32] cell_methods exemptions --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index 0622a8c..4687779 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,11 @@ order of cell_methods aligns with the order of spatial and temporal extensions. } ``` In this case no method is applied over the vertical_dimension1 but the "minimum" method is applied over the temporal dimension time_interval2. These dimensions are defined in the cube:dimensions fields. + +If a data value is representative of variation over a combination of axes this approach is not sufficient \(e.g. the standard +deviation of topographic height within a longitude-latitude gridbox would have `cell_methods="lat: lon: standard_deviation"`\). +Such `cell_methods` cannot be described in per dimension in an array and would need a plain string representation. + See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. #### description From 95532b2771c0923c2eddedea857b907c317d5ea9 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Mon, 10 Nov 2025 07:47:59 +1300 Subject: [PATCH 23/32] links pointing to latest CF version --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4687779..cccea19 100644 --- a/README.md +++ b/README.md @@ -29,8 +29,8 @@ The fields in the table below can be used in these parts of STAC documents: | ------------ | --------------------------- | ----------------------------------------------------------------------------------- | | cf:standard_name | string | Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) if variable has a standard_name definition in the CF convention. Otherwise standard_name remains an empty value. | | cf:cell_methods | \[string] | This is a list of string attributes that describe the "method" applied to the data as defined in the CF conventions. | -| description | string | This field contains the [CF "long_name"](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/build/ch03s02.html) information. | -| unit | string | This field contains the [CF "units" information](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#units) information. | +| description | string | This field contains the [CF "long_name"](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) information. | +| unit | string | This field contains the [CF "units" information]https://cfconventions.org/cf-conventions/cf-conventions.html#units) information. | ### Additional Field Information @@ -54,7 +54,7 @@ In this case no method is applied over the vertical_dimension1 but the "minimum" If a data value is representative of variation over a combination of axes this approach is not sufficient \(e.g. the standard deviation of topographic height within a longitude-latitude gridbox would have `cell_methods="lat: lon: standard_deviation"`\). -Such `cell_methods` cannot be described in per dimension in an array and would need a plain string representation. +Such `cell_methods` cannot be described as per dimension methods in an array and would need a plain string representation. See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. @@ -70,6 +70,7 @@ Unit is not required for dimensionless quantities. A variable with no unit attri dimensionless. The conforming unit for quantities that represent fractions, or parts of a whole, is "1". Descriptive information about dimensionless quantities, such as sea-ice concentration, cloud fraction, probability, etc., should be given in the "description" attribute rather than the unit field. +See [CF Units](https://cfconventions.org/cf-conventions/cf-conventions.html#dimensionless-units) for more details. ## Contributing From 3632de337540a0ecb1ec2cda21338df4db9d5d63 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Mon, 10 Nov 2025 07:52:31 +1300 Subject: [PATCH 24/32] lost a bracket --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index cccea19..9b6145d 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ The fields in the table below can be used in these parts of STAC documents: | cf:standard_name | string | Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) if variable has a standard_name definition in the CF convention. Otherwise standard_name remains an empty value. | | cf:cell_methods | \[string] | This is a list of string attributes that describe the "method" applied to the data as defined in the CF conventions. | | description | string | This field contains the [CF "long_name"](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) information. | -| unit | string | This field contains the [CF "units" information]https://cfconventions.org/cf-conventions/cf-conventions.html#units) information. | +| unit | string | This field contains the [CF "units" information](https://cfconventions.org/cf-conventions/cf-conventions.html#units) information. | ### Additional Field Information From 86804b3ffd22e6882a5bccf4646d4ec56ce349dd Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Mon, 10 Nov 2025 07:56:14 +1300 Subject: [PATCH 25/32] typos --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9b6145d..b8b02b6 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ The fields in the table below can be used in these parts of STAC documents: | cf:standard_name | string | Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) if variable has a standard_name definition in the CF convention. Otherwise standard_name remains an empty value. | | cf:cell_methods | \[string] | This is a list of string attributes that describe the "method" applied to the data as defined in the CF conventions. | | description | string | This field contains the [CF "long_name"](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) information. | -| unit | string | This field contains the [CF "units" information](https://cfconventions.org/cf-conventions/cf-conventions.html#units) information. | +| unit | string | This field contains the [CF "units"](https://cfconventions.org/cf-conventions/cf-conventions.html#units) information. | ### Additional Field Information @@ -61,7 +61,7 @@ See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.ht #### description The description field as defined by the [NUG](https://docs.unidata.ucar.edu/nug/current/index.html) is meant to contain a long descriptive name which may, for example, be used for labeling plots. -See [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. +See [CF "long_name"](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. #### unit The unit of measurement for the values, preferably compliant to [UCUM](https://ucum.org/[) (unit code) @@ -70,7 +70,7 @@ Unit is not required for dimensionless quantities. A variable with no unit attri dimensionless. The conforming unit for quantities that represent fractions, or parts of a whole, is "1". Descriptive information about dimensionless quantities, such as sea-ice concentration, cloud fraction, probability, etc., should be given in the "description" attribute rather than the unit field. -See [CF Units](https://cfconventions.org/cf-conventions/cf-conventions.html#dimensionless-units) for more details. +See [CF "units"](https://cfconventions.org/cf-conventions/cf-conventions.html#dimensionless-units) for more details. ## Contributing From 01db5343c129d5b738a2d8dbcc0b3c3ae406c521 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Tue, 11 Nov 2025 15:38:41 +1300 Subject: [PATCH 26/32] Tidy up of interim files that were added to the git repo --- examples/collection.jsonbackup | 131 ---------- examples/item.jsonbackup | 141 ----------- examples/item_asset.jsonbackup | 141 ----------- .../standalone_collection.json_notworking | 115 --------- json-schema/schema.json_cf | 195 --------------- json-schema/schema.json_orig | 202 --------------- json-schema/schema_business.json | 231 ------------------ 7 files changed, 1156 deletions(-) delete mode 100644 examples/collection.jsonbackup delete mode 100644 examples/item.jsonbackup delete mode 100644 examples/item_asset.jsonbackup delete mode 100644 examples/standalone_collection.json_notworking delete mode 100644 json-schema/schema.json_cf delete mode 100644 json-schema/schema.json_orig delete mode 100644 json-schema/schema_business.json diff --git a/examples/collection.jsonbackup b/examples/collection.jsonbackup deleted file mode 100644 index b9e6dd6..0000000 --- a/examples/collection.jsonbackup +++ /dev/null @@ -1,131 +0,0 @@ -{ - "stac_version": "1.0.0", - "stac_extensions": [ - "https://stac-extensions.github.io/cf/v0.2.0/schema.json", - "https://stac-extensions.github.io/datacube/v2.2.0/schema.json" - ], - "type": "Collection", - "id": "Sentinel2-L1C", - "title": "Atmospheric time series data", - "description": "Time series with elements described in CF nomenclature including height and aggregation methods.", - "license": "proprietary", - "extent": { - "spatial": { - "bbox": [ - [ - -180, - -56, - 180, - 83 - ] - ] - }, - "temporal": { - "interval": [ - [ - "2015-06-23T00:00:00Z", - "2019-07-10T13:44:56Z" - ] - ] - } - }, - "cf:standard_name": "height ", - "cf:long_name": "a long name", - "cube:dimensions": { - "time_interval1": { - "type": "temporal", - "description": "time interval that cell_methods is applied over", - "values": [ - -24 - ], - "unit": "h" - }, - "vertical_dimension1": { - "type": "spatial", - "axis": "z", - "cf:standard_name": "height", - "description": "Height above ground level", - "unit": "m", - "values": [ - 10 - ] - }, - "time_interval2": { - "type": "temporal", - "description": "time interval that cell_methods is applied over", - "values": [ - -60 - ], - "unit": "min" - }, - "vertical_dimension2": { - "type": "spatial", - "axis": "z", - "cf:standard_name": "height", - "description": "Air pressure", - "cf:long_name": "", - "unit": "hPa", - "values": [ - 500 - ] - } - }, - "cube:variables": { - "sea_surface_temperature": { - "type": "data", - "cf:standard_name": "sea_surface_temperature", - "description": "Average temperature on sea surface for preceding 24 hours", - "cf:long_name": "Average temperature on sea surface for preceding 24 hours", - "unit": "K", - "cf:cell_methods": "time: mean", - "dimensions": [ - "time_interval1" - ] - }, - "wind_speed_at_10m": { - "type": "data", - "cf:standard_name": "wind_speed", - "description": "minimum wind speed in 1 hour at 10 m agl", - "cf:long_name": "minimum wind speed in 1 hour at 10 m agl", - "units": "kt", - "cf:cell_methods": "time: minimum", - "dimensions": [ - "vertical_dimension1", - "time_interval2" - ] - }, - "temp_at_500hPa": { - "type": "data", - "cf:standard_name": "air_temperature", - "description": "air temperature at 500 hPa", - "cf:long_name": "air temperature at 500 hPa", - "units": "degC", - "dimensions": [ - "vertical_dimension2" - ] - } - }, - "summaries": { - "datetime": { - "minimum": "2015-06-23T00:00:00Z", - "maximum": "2019-07-10T13:44:56Z" - }, - "cf:standard_name": "height", - "cf:long_name": "a long name" - }, - "assets": { - "cf:standard_name": "height", - "cf:long_name": "a long name" - }, - "links": [ - { - "rel": "self", - "href": "https://example.sentinel2-hub.com/stac/example-collection.json" - }, - { - "rel": "license", - "href": "https://scihub.copernicus.eu/twiki/pub/SciHubWebPortal/TermsConditions/Sentinel_Data_Terms_and_Conditions.pdf", - "title": "Legal notice on the use of Copernicus Sentinel Data and Service Information" - } - ] -} \ No newline at end of file diff --git a/examples/item.jsonbackup b/examples/item.jsonbackup deleted file mode 100644 index 614ba2b..0000000 --- a/examples/item.jsonbackup +++ /dev/null @@ -1,141 +0,0 @@ -{ - "stac_version": "1.0.0", - "stac_extensions": [ - "https://stac-extensions.github.io/cf/v0.2.0/schema.json" - ], - "id": "datacube-123", - "type": "Feature", - "geometry": { - "type": "Polygon", - "coordinates": [ - [ - [ - -122.308150179, - 37.488035566 - ], - [ - -122.597502109, - 37.538869539 - ], - [ - -122.576687533, - 37.613537207 - ], - [ - -122.2880486, - 37.562818007 - ], - [ - -122.308150179, - 37.488035566 - ] - ] - ] - }, - "bbox": [ - -122.59750209, - 37.48803556, - -122.2880486, - 37.613537207 - ], - "properties": { - "title": "Multi-dimensional data cube 123 in a STAC Item.", - "datetime": "2016-05-03T13:21:30.040Z", - "cf:standard_name": "", - "cube:dimensions": { - "x": { - "type": "spatial", - "axis": "x", - "extent": [ - -122.59750209, - -122.2880486 - ], - "reference_system": 4326 - }, - "y": { - "type": "spatial", - "axis": "y", - "extent": [ - 37.48803556, - 37.613537207 - ], - "reference_system": 4326 - }, - "pressure_levels": { - "type": "spatial", - "axis": "z", - "extent": [ - 0, - 1000 - ], - "step": 100, - "unit": "Pa" - }, - "metered_levels": { - "type": "spatial", - "axis": "z", - "values": [ - 0, - 10, - 25, - 50, - 100, - 1000 - ], - "unit": "m" - }, - "time": { - "type": "temporal", - "values": [ - "2016-05-03T13:21:30.040Z" - ] - }, - "spectral": { - "type": "bands", - "values": [ - "red", - "green", - "blue" - ] - } - }, - "cube:variables": { - "temp": { - "dimensions": [ - "time", - "y", - "x", - "pressure_levels" - ], - "type": "data" - }, - "color": { - "dimensions": [], - "type": "auxiliary", - "values": [ - "red", - "green", - "blue" - ] - } - } - }, - "assets": { - "data": { - "href": "http://cool-sat.com/catalog/datacube-123/data.nc", - "type": "application/netcdf", - "title": "netCDF Data cube" - }, - "thumbnail": { - "href": "http://cool-sat.com/catalog/datacube-123/thumbnail.png", - "type": "image/png", - "title": "Thumbnail" - } - }, - "links": [ - { - "rel": "self", - "href": "http://cool-sat.com/catalog/datacube-123/item.json" - } - ] -} \ No newline at end of file diff --git a/examples/item_asset.jsonbackup b/examples/item_asset.jsonbackup deleted file mode 100644 index 06c0ac8..0000000 --- a/examples/item_asset.jsonbackup +++ /dev/null @@ -1,141 +0,0 @@ -{ - "stac_version": "1.0.0", - "stac_extensions": [ - "https://stac-extensions.github.io/cf/v0.2.0/schema.json", - "https://stac-extensions.github.io/datacube/v2.2.0/schema.json" - ], - "id": "datacube-123", - "type": "Feature", - "geometry": { - "type": "Polygon", - "coordinates": [ - [ - [ - -122.308150179, - 37.488035566 - ], - [ - -122.597502109, - 37.538869539 - ], - [ - -122.576687533, - 37.613537207 - ], - [ - -122.2880486, - 37.562818007 - ], - [ - -122.308150179, - 37.488035566 - ] - ] - ] - }, - "bbox": [ - -122.59750209, - 37.48803556, - -122.2880486, - 37.613537207 - ], - "properties": { - "title": "Multi-dimensional data cube 123 in a STAC Item.", - "datetime": "2016-05-03T13:21:30.040Z" - }, - "assets": { - "data": { - "href": "http://cool-sat.com/catalog/datacube-123/data.nc", - "type": "application/netcdf", - "title": "netCDF Data cube", - "cube:dimensions": { - "x": { - "type": "spatial", - "axis": "x", - "extent": [ - -122.59750209, - -122.2880486 - ], - "reference_system": 4326 - }, - "y": { - "type": "spatial", - "axis": "y", - "extent": [ - 37.48803556, - 37.613537207 - ], - "reference_system": 4326 - }, - "pressure_levels": { - "type": "spatial", - "axis": "z", - "extent": [ - 0, - 1000 - ], - "step": 100, - "unit": "Pa" - }, - "metered_levels": { - "type": "spatial", - "axis": "z", - "values": [ - 0, - 10, - 25, - 50, - 100, - 1000 - ], - "unit": "m" - }, - "time": { - "type": "temporal", - "values": [ - "2016-05-03T13:21:30.040Z" - ] - }, - "spectral": { - "type": "bands", - "values": [ - "red", - "green", - "blue" - ] - } - }, - "cube:variables": { - "temp": { - "dimensions": [ - "time", - "y", - "x", - "pressure_levels" - ], - "type": "data" - }, - "color": { - "dimensions": [], - "type": "auxiliary", - "values": [ - "red", - "green", - "blue" - ] - } - } - }, - "thumbnail": { - "href": "http://cool-sat.com/catalog/datacube-123/thumbnail.png", - "type": "image/png", - "title": "Thumbnail" - } - }, - "links": [ - { - "rel": "self", - "href": "http://cool-sat.com/catalog/datacube-123/item.json" - } - ] -} \ No newline at end of file diff --git a/examples/standalone_collection.json_notworking b/examples/standalone_collection.json_notworking deleted file mode 100644 index a8534c2..0000000 --- a/examples/standalone_collection.json_notworking +++ /dev/null @@ -1,115 +0,0 @@ -{ - "stac_version": "1.0.0", - "stac_extensions": [ - "https://stac-extensions.github.io/cf/v0.2.0/schema.json" - ], - "type": "Collection", - "id": "standalone_collection", - "title": "Collection without Items", - "description": "A description", - "license": "Apache-2.0", - "extent": { - "spatial": { - "bbox": [ - [ - 172.9, - 1.3, - 173, - 1.4 - ] - ] - }, - "temporal": { - "interval": [ - [ - "2015-06-23T00:00:00Z", - null - ] - ] - } - }, - "summaries": { - "cf:standard_name": "height", - "cube:dimensions": { - "time_interval1": { - "type": "temporal", - "description": "time interval that cell_methods is applied over", - "values": [ - -24 - ], - "unit": "h" - }, - "vertical_dimension1": { - "type": "spatial", - "axis": "z", - "cf:standard_name": "height", - "description": "Height above ground level", - "unit": "m", - "values": [ - 10 - ] - }, - "time_interval2": { - "type": "temporal", - "description": "time interval that cell_methods is applied over", - "values": [ - -60 - ], - "unit": "min" - }, - "vertical_dimension2": { - "type": "spatial", - "axis": "z", - "cf:standard_name": "height", - "description": "Air pressure", - "unit": "hPa", - "values": [ - 500 - ] - } - }, - "cube:variables": { - "sea_surface_temperature": { - "type": "data", - "cf:standard_name": "sea_surface_temperature", - "description": "Average temperature on sea surface for preceding 24 hours", - "unit": "K", - "cf:cell_methods": "time: mean", - "dimensions": [ - "time_interval1" - ] - }, - "wind_speed_at_10m": { - "type": "data", - "cf:standard_name": "wind_speed", - "description": "minimum wind speed in 1 hour at 10 m agl", - "unit": "kt", - "cf:cell_methods": "time: minimum", - "dimensions": [ - "vertical_dimension1", - "time_interval2" - ] - }, - "temp_at_500hPa": { - "type": "data", - "cf:standard_name": "air_temperature", - "description": "air temperature at 500 hPa", - "unit": "degC", - "dimensions": [ - "vertical_dimension2" - ] - } - } - }, - "assets": { - "example": { - "href": "https://example.com/examples/example.nc" - } - }, - "links": [ - { - "href": "https://example.com/examples/standalone_collection.json", - "rel": "self" - } - ] -} \ No newline at end of file diff --git a/json-schema/schema.json_cf b/json-schema/schema.json_cf deleted file mode 100644 index b24eeec..0000000 --- a/json-schema/schema.json_cf +++ /dev/null @@ -1,195 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://stac-extensions.github.io/template/v1.0.0/schema.json#", - "title": "Climate and Forecasting Convention Extension", - "description": "STAC CF Extension for STAC Items and STAC Collections.", - "oneOf": [ - { - "$comment": "This is the schema for STAC Items. Remove this object if this extension only applies to Collections.", - "allOf": [ - { - "$ref": "#/definitions/stac_extensions" - }, - { - "type": "object", - "required": [ - "type", - "properties", - "assets" - ], - "properties": { - "type": { - "const": "Feature" - }, - "properties": { - "allOf": [ - { - "$comment": "Require fields here for Item Properties.", - "required": [ - ] - }, - { - "$ref": "#/definitions/fields" - } - ] - }, - "assets": { - "$comment": "This validates the fields in Item Assets, but does not require them.", - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/fields" - } - } - } - } - ] - }, - { - "$comment": "This is the schema for STAC Collections.", - "type": "object", - "allOf": [ - { - "required": [ - "type" - ], - "properties": { - "type": { - "const": "Collection" - } - } - }, - { - "$ref": "#/definitions/stac_extensions" - } - ], - "anyOf": [ - { - "$comment": "This is the schema for the top-level fields in a Collection. Remove this if this extension does not define top-level fields for Collections.", - "allOf": [ - { - "$comment": "Require fields here for Collections (top-level).", - "required": [ - ] - }, - { - "$ref": "#/definitions/fields" - } - ] - }, - { - "$comment": "This validates the fields in Collection Assets, but does not require them.", - "required": [ - "assets" - ], - "properties": { - "assets": { - "type": "object", - "not": { - "additionalProperties": { - "not": { - "allOf": [ - { - "$ref": "#/definitions/require_any_field" - }, - { - "$ref": "#/definitions/fields" - } - ] - } - } - } - } - } - }, - { - "$comment": "This is the schema for the fields in Item Asset Definitions. It doesn't require any fields.", - "required": [ - "item_assets" - ], - "properties": { - "item_assets": { - "type": "object", - "not": { - "additionalProperties": { - "not": { - "allOf": [ - { - "$ref": "#/definitions/require_any_field" - }, - { - "$ref": "#/definitions/fields" - } - ] - } - } - } - } - } - }, - { - "$comment": "This is the schema for the fields in Summaries. By default, only checks the existence of the properties, but not the schema of the summaries.", - "required": [ - "summaries" - ], - "properties": { - "summaries": { - "$ref": "#/definitions/require_any_field" - } - } - } - ] - } - ], - "definitions": { - "stac_extensions": { - "type": "object", - "required": [ - "stac_extensions" - ], - "properties": { - "stac_extensions": { - "type": "array", - "contains": { - "const": "https://stac-extensions.github.io/cf/v0.2.0/schema.json" - } - } - } - }, - "require_any_field": { - "$comment": "Please list all fields here so that we can force the existence of one of them in other parts of the schemas." - }, - "fields": { - "$comment": "Add your new fields here. Don't require them here, do that above in the corresponding schema.", - "type": "object", - "properties": { - "cf:standard_name": { - "title": "CF standard_name", - "type": "string" - }, - "cf:long_name": { - "title": "CF long_name field", - "type": "string", - "minLength": 1 - }, - "cf:units": { - "type": "string", - "minLength": 1 - }, - "cf:cell_methods": { - "type": "string", - "minLength": 1 - }, - "cf:asset_variable_name": { - "type": "string", - "minLength": 1 - } - }, - "patternProperties": { - "^(?!cf:)": { - "$comment": "Above, change `template` to the prefix of this extension" - } - }, - "additionalProperties": false - } - } -} \ No newline at end of file diff --git a/json-schema/schema.json_orig b/json-schema/schema.json_orig deleted file mode 100644 index 293013d..0000000 --- a/json-schema/schema.json_orig +++ /dev/null @@ -1,202 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://stac-extensions.github.io/cf/v0.2.0/schema.json#", - "title": "CF Extension", - "description": "STAC CF Extension for STAC Items and STAC Collections.", - "type": "object", - "required": [ - "stac_extensions" - ], - "properties": { - "stac_extensions": { - "type": "array", - "contains": { - "const": "https://stac-extensions.github.io/cf/v0.2.0/schema.json" - } - }, - "assets": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/fields" - } - } - }, - "oneOf": [ - { - "$comment": "Schema for Collections", - "type": "object", - "required": [ - "type" - ], - "properties": { - "type": { - "const": "Collection" - }, - "item_assets": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/fields" - } - }, - "summaries": { - "oneOf": [ - { - "$ref": "#/definitions/fields" - }, - { - "$comment": "JSON Schema summary", - "type": "object", - "properties": { - "cf:parameter": { - "type": "object", - "properties": { - "type": { - "const": "array" - } - } - } - }, - "patternProperties": { - "^(?!cf:)": { - "$comment": "Above, change `cf` to the prefix of this extension" - } - }, - "additionalProperties": false - } - ] - } - }, - "allOf": [ - { - "$ref": "#/definitions/fields" - } - ] - }, - { - "$comment": "Schema for Items", - "type": "object", - "required": [ - "type" - ], - "properties": { - "type": { - "const": "Feature" - }, - "properties": { - "$ref": "#/definitions/fields" - } - }, - "allOf": [ - { - "$ref": "#/definitions/cf_in_assets" - } - ] - } - ], - "definitions": { - "cf_in_assets": { - "required": [ - "assets" - ], - "properties": { - "assets": { - "not": { - "additionalProperties": { - "not": { - "allOf": [ - { - "required": [ - "cf:parameter" - ] - }, - { - "$ref": "#/definitions/fields" - } - ] - } - } - } - } - } - }, - "forbid_fields": { - "patternProperties": { - "^(?!cf:)": {} - }, - "additionalProperties": false - }, - "fields": { - "type": "object", - "properties": { - "cf:parameter": { - "type": "array", - "minItems": 1, - "items": { - "type": "object", - "required": [ - "units" - ], - "properties": { - "standard_name": { - "title": "CF standard_name field", - "type": "string", - "minLength": 1 - }, - "long_name": { - "title": "CF long_name field", - "type": "string", - "minLength": 1 - }, - "units": { - "type": "string", - "minLength": 1 - }, - "cell_methods": { - "type": "string", - "minLength": 1 - }, - "vertical_dimension": { - "$ref": "#/definitions/vertical_dimension" - - } - - } - } - } - }, - "patternProperties": { - "^(?!cf:)": { - "$comment": "Above, change `cf` to the prefix of this extension" - } - }, - "additionalProperties": false - }, - "vertical_dimension": { - "title": "Vertical Dimension Object", - "type": "object", - "items": { - "required": [ - "standard_name", - "units" - ], - "properties":{ - "standard_name": { - "type": "string" - }, - "long_name": { - "type": "string" - }, - "units": { - "type": "string" - }, - "values": { - "type": "array", - "items": { - "type": "number" - } - } - } - } - } - } -} diff --git a/json-schema/schema_business.json b/json-schema/schema_business.json deleted file mode 100644 index 688ce5d..0000000 --- a/json-schema/schema_business.json +++ /dev/null @@ -1,231 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://stac-extensions.github.io/template/v1.0.0/schema.json#", - "title": "Business Extension", - "description": "STAC Business Extension for STAC Items and STAC Collections.", - "oneOf": [ - { - "$comment": "This is the schema for STAC Items. Remove this object if this extension only applies to Collections.", - "allOf": [ - { - "$ref": "#/definitions/stac_extensions" - }, - { - "type": "object", - "required": [ - "type", - "properties", - "assets" - ], - "properties": { - "type": { - "const": "Feature" - }, - "properties": { - "allOf": [ - { - "$comment": "Require fields here for Item Properties.", - "required": [ - ] - }, - { - "$ref": "#/definitions/fields" - } - ] - }, - "assets": { - "$comment": "This validates the fields in Item Assets, but does not require them.", - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/fields" - } - } - } - } - ] - }, - { - "$comment": "This is the schema for STAC Collections.", - "type": "object", - "allOf": [ - { - "required": [ - "type" - ], - "properties": { - "type": { - "const": "Collection" - } - } - }, - { - "$ref": "#/definitions/stac_extensions" - } - ], - "anyOf": [ - { - "$comment": "This is the schema for the top-level fields in a Collection. Remove this if this extension does not define top-level fields for Collections.", - "allOf": [ - { - "$comment": "Require fields here for Collections (top-level).", - "required": [ - ] - }, - { - "$ref": "#/definitions/fields" - } - ] - }, - { - "$comment": "This validates the fields in Collection Assets, but does not require them.", - "required": [ - "assets" - ], - "properties": { - "assets": { - "type": "object", - "not": { - "additionalProperties": { - "not": { - "allOf": [ - { - "$ref": "#/definitions/require_any_field" - }, - { - "$ref": "#/definitions/fields" - } - ] - } - } - } - } - } - }, - { - "$comment": "This is the schema for the fields in Item Asset Definitions. It doesn't require any fields.", - "required": [ - "item_assets" - ], - "properties": { - "item_assets": { - "type": "object", - "not": { - "additionalProperties": { - "not": { - "allOf": [ - { - "$ref": "#/definitions/require_any_field" - }, - { - "$ref": "#/definitions/fields" - } - ] - } - } - } - } - } - }, - { - "$comment": "This is the schema for the fields in Summaries. By default, only checks the existence of the properties, but not the schema of the summaries.", - "required": [ - "summaries" - ], - "properties": { - "summaries": { - "$ref": "#/definitions/require_any_field" - } - } - } - ] - } - ], - "definitions": { - "stac_extensions": { - "type": "object", - "required": [ - "stac_extensions" - ], - "properties": { - "stac_extensions": { - "type": "array", - "contains": { - "const": "https://stac-extensions.github.io/template/v1.0.0/schema.json" - } - } - } - }, - "require_any_field": { - "$comment": "Please list all fields here so that we can force the existence of one of them in other parts of the schemas.", - "anyOf": [ - {"required": ["business:data_owner"]}, - {"required": ["business:content_data_steward"]}, - {"required": ["business:technical_data_steward"]}, - {"required": ["business:retain_for"]}, - {"required": ["business:retain_until"]}, - {"required": ["business:transition"]}, - {"required": ["business:approved_for"]}, - {"required": ["business:sensitivity"]} - ] - }, - "fields": { - "$comment": "Add your new fields here. Don't require them here, do that above in the corresponding schema.", - "type": "object", - "properties": { - "business:data_owner": { - "type": "string" - }, - "business:content_data_steward": { - "type": "string" - }, - "business:technical_data_steward": { - "type": "string" - }, - "business:retain_for": { - "type": "string" - }, - "business:retain_until": { - "type": "string", - "format": "datetime" - }, - "business:transition": { - "type": "string", - "enum": [ - "expiration", - "Archives NZ" - ] - }, - "business:approved_for": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "Aviation 24/7", - "24/7", - "Development", - "Project", - "Research", - "AI" - ] - } - }, - "business:sensitivity": { - "type": "string", - "enum": [ - "personal", - "public", - "internal use only", - "confidential", - "highly confidential" - ] - } - }, - "patternProperties": { - "^(?!business:)": { - "$comment": "Above, change `template` to the prefix of this extension" - } - }, - "additionalProperties": false - } - } -} From 858b8a9663d25475fa54c2c58e1e5e40b5f554b7 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Tue, 11 Nov 2025 16:10:32 +1300 Subject: [PATCH 27/32] suggested changes from review --- examples/collection.json | 11 ++++++++--- examples/item.json | 10 +++++++--- json-schema/schema.json | 18 ++++++++---------- package.json | 4 ++-- 4 files changed, 25 insertions(+), 18 deletions(-) diff --git a/examples/collection.json b/examples/collection.json index 4bf1b0b..b1429b3 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -1,7 +1,7 @@ { "stac_version": "1.0.0", "stac_extensions": [ - "https://stac-extensions.github.io/template/v1.0.0/schema.json" + "https://stac-extensions.github.io/cf/v0.3.0/schema.json" ], "type": "Collection", "id": "collection", @@ -89,7 +89,9 @@ "cf:standard_name": "sea_surface_temperature", "description": "Average temperature on sea surface for preceding 24 hours", "unit": "K", - "cf:cell_methods": ["mean"], + "cf:cell_methods": [ + "mean" + ], "dimensions": [ "time_interval1" ] @@ -99,7 +101,10 @@ "cf:standard_name": "wind_speed", "description": "minimum wind speed in 1 hour at 10 m agl", "unit": "kt", - "cf:cell_methods": [null, "minimum"], + "cf:cell_methods": [ + null, + "minimum" + ], "dimensions": [ "vertical_dimension1", "time_interval2" diff --git a/examples/item.json b/examples/item.json index bcbd8d2..c2d5d02 100644 --- a/examples/item.json +++ b/examples/item.json @@ -1,7 +1,7 @@ { "stac_version": "1.0.0", "stac_extensions": [ - "https://stac-extensions.github.io/template/v1.0.0/schema.json" + "https://stac-extensions.github.io/cf/v0.3.0/schema.json" ], "type": "Feature", "id": "item", @@ -95,7 +95,9 @@ "cf:standard_name": "sea_surface_temperature", "description": "Average temperature on sea surface for preceding 24 hours", "unit": "K", - "cf:cell_methods": ["mean"], + "cf:cell_methods": [ + "mean" + ], "dimensions": [ "time_interval1" ] @@ -105,7 +107,9 @@ "cf:standard_name": "wind_speed", "description": "minimum wind speed in 1 hour at 10 m agl", "unit": "kt", - "cf:cell_methods": ["minimum"], + "cf:cell_methods": [ + "minimum" + ], "dimensions": [ "vertical_dimension1", "time_interval2" diff --git a/json-schema/schema.json b/json-schema/schema.json index aca1d85..fd6ff4d 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -1,6 +1,6 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://stac-extensions.github.io/template/v1.0.0/schema.json#", + "$id": "https://stac-extensions.github.io/cf/v0.3.0/schema.json#", "title": "Climate and Forecasting Convention Extension", "description": "STAC CF Extension for STAC Items and STAC Collections.", "oneOf": [ @@ -150,7 +150,7 @@ "stac_extensions": { "type": "array", "contains": { - "const": "https://stac-extensions.github.io/template/v1.0.0/schema.json" + "const": "https://stac-extensions.github.io/cf/v0.3.0/schema.json" } } } @@ -180,20 +180,18 @@ "minLength": 1 }, "unit": { - "type": "string", - "minLength": 1 + "type": "string" }, "cf:cell_methods": { - "type": "array", - "items": { - "type": "string", - "minLength": 1 - } + "anyOf": [ + { "type": "string", "minLength": 1 }, + { "type": "null" } + ] } }, "patternProperties": { "^(?!cf:)": { - "$comment": "Above, change `template` to the prefix of this extension" + "$comment": "Above, change `cf` to the prefix of this extension" } }, "additionalProperties": false diff --git a/package.json b/package.json index 6440ca0..6e433e1 100644 --- a/package.json +++ b/package.json @@ -4,8 +4,8 @@ "scripts": { "test": "npm run check-markdown && npm run check-examples", "check-markdown": "remark . -f -r .github/remark.yaml", - "check-examples": "stac-node-validator . --lint --verbose --schemaMap https://stac-extensions.github.io/template/v1.0.0/schema.json=./json-schema/schema.json", - "format-examples": "stac-node-validator . --format --schemaMap https://stac-extensions.github.io/template/v1.0.0/schema.json=./json-schema/schema.json" + "check-examples": "stac-node-validator . --lint --verbose --schemaMap https://stac-extensions.github.io/cf/v0.3.0/schema.json=./json-schema/schema.json", + "format-examples": "stac-node-validator . --format --schemaMap https://stac-extensions.github.io/cf/v0.3.0/schema.json=./json-schema/schema.json" }, "dependencies": { "remark-cli": "^12.0.1", From 95a5ed24bde3c64b94a949ed04e63fc5bc1917eb Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Tue, 11 Nov 2025 16:14:19 +1300 Subject: [PATCH 28/32] tweak to readme --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b8b02b6..24afe2b 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,8 @@ order of cell_methods aligns with the order of spatial and temporal extensions. } } ``` -In this case no method is applied over the vertical_dimension1 but the "minimum" method is applied over the temporal dimension time_interval2. These dimensions are defined in the cube:dimensions fields. +In this case no method is applied over the first dimension `vertical_dimension1` but the "minimum" method is applied over the second +dimension `time_interval2`. These dimensions are defined in the cube:dimensions fields. If a data value is representative of variation over a combination of axes this approach is not sufficient \(e.g. the standard deviation of topographic height within a longitude-latitude gridbox would have `cell_methods="lat: lon: standard_deviation"`\). From 0156dc733a2fea6ca554ed695a94d4a918cc3034 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 1 Dec 2025 17:46:12 +0100 Subject: [PATCH 29/32] Fix Markdown and item example --- .github/remark.yaml | 2 +- README.md | 53 ++++++++++++++++++++++++++++++--------------- examples/item.json | 14 +----------- 3 files changed, 38 insertions(+), 31 deletions(-) diff --git a/.github/remark.yaml b/.github/remark.yaml index 564baf8..d4aa71e 100644 --- a/.github/remark.yaml +++ b/.github/remark.yaml @@ -12,7 +12,7 @@ plugins: - remark-lint-blockquote-indentation - remark-lint-no-consecutive-blank-lines - - remark-lint-maximum-line-length - - 150 + - 170 # Code - remark-lint-fenced-code-flag - remark-lint-fenced-code-marker diff --git a/README.md b/README.md index 24afe2b..6f7bfb8 100644 --- a/README.md +++ b/README.md @@ -19,26 +19,39 @@ It adds a field to provide the Standard Name Table based on the [CF metadata con ## Fields The fields in the table below can be used in these parts of STAC documents: + - [ ] Catalogs - [x] Collections - [x] Item Properties (incl. Summaries in Collections) - [x] Assets (for both Collections and Items, incl. Item Asset Definitions in Collections) +- [x] Bands +- [x] Data Cube Extension (`cube:variables`, `cube:dimensions`) - [ ] Links -| Field Name | Type | Description | -| ------------ | --------------------------- | ----------------------------------------------------------------------------------- | -| cf:standard_name | string | Should be a non-empty value from the [CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html) if variable has a standard_name definition in the CF convention. Otherwise standard_name remains an empty value. | -| cf:cell_methods | \[string] | This is a list of string attributes that describe the "method" applied to the data as defined in the CF conventions. | -| description | string | This field contains the [CF "long_name"](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) information. | -| unit | string | This field contains the [CF "units"](https://cfconventions.org/cf-conventions/cf-conventions.html#units) information. | +| Field Name | Type | Description | +| ---------------- | --------- | ----------- | +| cf:standard_name | string | Corresponds to the [CF Standard Name](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html). | +| cf:cell_methods | \[string] | A list of string attributes that describe the "method" applied to the data as defined in the CF conventions. | +| description | string | Corresponds to the [CF `long_name`](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name). | +| unit | string | Corresponds to the [CF `units`](https://cfconventions.org/cf-conventions/cf-conventions.html#units). | ### Additional Field Information +#### cf:standard_name + +The CF standard name is a controlled vocabulary term used in Climate and Forecast (CF) metadata conventions +to unambiguously describe the physical quantity represented by a variable in climate and geophysical data files. +If variable has a standard_name definition in the CF convention, it must be a non-empty value from the +[CF Standard Name Table](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html). +Otherwise `cf:standard_name` is an empty value. + #### cf:cell_methods -The cell_methods attribute in the CF (Climate and Forecast) convention is designed to describe how the values in a data variable -were derived with respect to one or more axes (e.g., time, latitude, longitude). Each "method" represents the statistical or -computational operations applied to data along specific axes. For example, if used within the datacube extension then the + +The cell_methods attribute in the CF (Climate and Forecast) convention is designed to describe how the values in a data variable +were derived with respect to one or more axes (e.g., time, latitude, longitude). Each "method" represents the statistical or +computational operations applied to data along specific axes. For example, if used within the datacube extension then the order of cell_methods aligns with the order of spatial and temporal extensions. + ```json "cube:variables": { "some_variable": { @@ -50,26 +63,29 @@ order of cell_methods aligns with the order of spatial and temporal extensions. } } ``` + In this case no method is applied over the first dimension `vertical_dimension1` but the "minimum" method is applied over the second dimension `time_interval2`. These dimensions are defined in the cube:dimensions fields. -If a data value is representative of variation over a combination of axes this approach is not sufficient \(e.g. the standard +If a data value is representative of variation over a combination of axes this approach is not sufficient \(e.g. the standard deviation of topographic height within a longitude-latitude gridbox would have `cell_methods="lat: lon: standard_deviation"`\). Such `cell_methods` cannot be described as per dimension methods in an array and would need a plain string representation. See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. #### description + The description field as defined by the [NUG](https://docs.unidata.ucar.edu/nug/current/index.html) is meant to contain a long descriptive name which may, for example, be used for labeling plots. See [CF "long_name"](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name) for more details. #### unit -The unit of measurement for the values, 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). -Unit is not required for dimensionless quantities. A variable with no unit attribute is assumed to be -dimensionless. The conforming unit for quantities that represent fractions, or parts of a whole, is "1". -Descriptive information about dimensionless quantities, such as sea-ice concentration, cloud fraction, + +The unit of measurement for the values, 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). +Unit is not required for dimensionless quantities. A variable with no unit attribute is assumed to be +dimensionless. The conforming unit for quantities that represent fractions, or parts of a whole, is "1". +Descriptive information about dimensionless quantities, such as sea-ice concentration, cloud fraction, probability, etc., should be given in the "description" attribute rather than the unit field. See [CF "units"](https://cfconventions.org/cf-conventions/cf-conventions.html#dimensionless-units) for more details. @@ -83,16 +99,18 @@ for running tests are copied here for convenience. ### Running tests -The same checks that run as checks on PR's are part of the repository and can be run locally to verify that changes are valid. +The same checks that run as checks on PR's are part of the repository and can be run locally to verify that changes are valid. To run tests locally, you'll need `npm`, which is a standard part of any [node.js installation](https://nodejs.org/en/download/). -First you'll need to install everything with npm once. Just navigate to the root of this repository and on +First you'll need to install everything with npm once. Just navigate to the root of this repository and on your command line run: + ```bash npm install ``` Then to check markdown formatting and test the examples against the JSON schema, you can run: + ```bash npm test ``` @@ -100,6 +118,7 @@ npm test This will spit out the same texts that you see online, and you can then go and fix your markdown or examples. If the tests reveal formatting problems with the examples, you can fix them with: + ```bash npm run format-examples ``` diff --git a/examples/item.json b/examples/item.json index c2d5d02..897c52d 100644 --- a/examples/item.json +++ b/examples/item.json @@ -40,17 +40,6 @@ }, "properties": { "datetime": "2020-12-11T22:38:32Z", - "template:new_field": "test", - "template:xyz": { - "x": 1, - "y": 2, - "z": 3 - }, - "template:another_one": [ - 1, - 2, - 3 - ], "cube:dimensions": { "time_interval1": { "type": "temporal", @@ -134,8 +123,7 @@ ], "assets": { "data": { - "href": "https://example.com/examples/file.xyz", - "template:new_field": "test" + "href": "https://example.com/examples/file.xyz" } } } From 6c6897e0574573ea59479ba52394a91d08d5d1f5 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Fri, 5 Dec 2025 09:25:41 +1300 Subject: [PATCH 30/32] Either cell_method is used or not. No need for enforcing its existence with a null value. --- json-schema/schema.json | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/json-schema/schema.json b/json-schema/schema.json index fd6ff4d..aa755f0 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -176,17 +176,13 @@ }, "description": { "title": "CF long_name field", - "type": "string", - "minLength": 1 + "type": "string" }, "unit": { "type": "string" }, "cf:cell_methods": { - "anyOf": [ - { "type": "string", "minLength": 1 }, - { "type": "null" } - ] + "type": "string" } }, "patternProperties": { From 7d0bc929754b2a06f7090bcabe31ff3a755f6067 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Fri, 5 Dec 2025 09:40:47 +1300 Subject: [PATCH 31/32] aligned example. scheme and README on use of cf:cell_methods with null values --- README.md | 2 +- examples/item.json | 1 + json-schema/schema.json | 13 ++++++++++--- 3 files changed, 12 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 6f7bfb8..682f9ab 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ The fields in the table below can be used in these parts of STAC documents: | Field Name | Type | Description | | ---------------- | --------- | ----------- | | cf:standard_name | string | Corresponds to the [CF Standard Name](https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html). | -| cf:cell_methods | \[string] | A list of string attributes that describe the "method" applied to the data as defined in the CF conventions. | +| cf:cell_methods | \[string|null] | A list of string or `null` attributes that describe the "method" applied to the data as defined in the CF conventions. | | description | string | Corresponds to the [CF `long_name`](https://cfconventions.org/cf-conventions/cf-conventions.html#long-name). | | unit | string | Corresponds to the [CF `units`](https://cfconventions.org/cf-conventions/cf-conventions.html#units). | diff --git a/examples/item.json b/examples/item.json index 897c52d..17ff380 100644 --- a/examples/item.json +++ b/examples/item.json @@ -97,6 +97,7 @@ "description": "minimum wind speed in 1 hour at 10 m agl", "unit": "kt", "cf:cell_methods": [ + null, "minimum" ], "dimensions": [ diff --git a/json-schema/schema.json b/json-schema/schema.json index aa755f0..dcf2b14 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -176,13 +176,20 @@ }, "description": { "title": "CF long_name field", - "type": "string" + "type": "string", + "minLength": 1 }, "unit": { "type": "string" - }, + }, "cf:cell_methods": { - "type": "string" + "type": "array", + "items": { + "anyOf": [ + { "type": "string", "minLength": 1 }, + { "type": "null" } + ] + } } }, "patternProperties": { From 8456ba70c0f7cb5ad52d002166fe753f0b60f5c8 Mon Sep 17 00:00:00 2001 From: Andy Ziegler Date: Wed, 10 Dec 2025 09:10:21 +1300 Subject: [PATCH 32/32] added more info how to use cell_methods --- README.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 682f9ab..83ef40f 100644 --- a/README.md +++ b/README.md @@ -64,13 +64,26 @@ order of cell_methods aligns with the order of spatial and temporal extensions. } ``` -In this case no method is applied over the first dimension `vertical_dimension1` but the "minimum" method is applied over the second -dimension `time_interval2`. These dimensions are defined in the cube:dimensions fields. +In this case `null` indicates that no method is applied over the first dimension `vertical_dimension1` but +the `minimum` method is applied over the second dimension `time_interval2`. +These dimensions would be defined in the `cube:dimensions` fields. If a data value is representative of variation over a combination of axes this approach is not sufficient \(e.g. the standard -deviation of topographic height within a longitude-latitude gridbox would have `cell_methods="lat: lon: standard_deviation"`\). +deviation of topographic height within a longitude-latitude gridbox would have `cell_methods="latitude: longitude: standard_deviation"`\). Such `cell_methods` cannot be described as per dimension methods in an array and would need a plain string representation. +```json +"cube:variables": { + "some_variable": { + "cf:cell_methods": "latitude: longitude: standard_deviation", + "dimensions": [ + "latitude", + "longitude" + ] + } +} +``` + See [CF Cell Methods](https://cfconventions.org/cf-conventions/cf-conventions.html#cell-methods) for more details. #### description