Add cube:variables definition

CHANGELOG.md

@@ -10,6 +10,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Updated examples to STAC 1.0.0
+- Added the `cube:variable` object for describing NetCDF-style multi-dimensional arrays in a datacube [#6](https://github.com/stac-extensions/datacube/pull/6)
+
 ### Deprecated
 
 ### Removed

README.md

@@ -21,9 +21,12 @@ It specifies datacube related metadata, especially their dimensions and potentia
 These fields may be added to either [Item](https://github.com/radiantearth/stac-spec/tree/master/item-spec/item-spec.md) 
 Properties or a [Collection](https://github.com/radiantearth/stac-spec/tree/master/collection-spec/collection-spec.md).
 
-| Field Name      | Type                                               | Description                                 |
-| --------------- | -------------------------------------------------- | ------------------------------------------- |
-| cube:dimensions | Map<string, [Dimension Object](#dimension-object)> | **REQUIRED.** Uniquely named dimensions of the datacube. |
+| Field Name       | Type                                               | Description                                 |
+| ---------------- | -------------------------------------------------- | ------------------------------------------- |
+| cube:dimensions  | Map<string, [Dimension Object](#dimension-object)> | **REQUIRED.** Uniquely named dimensions of the datacube. |
+| cube:variables   | Map<string, [Variable Object](#variable-object)>   | Uniquely named variables of the datacube. |
+
+The keys of `cube:dimensions` and `cube:variables` should be unique together; a key like `lat` should not be both a dimension and a variable.
 
 ### Dimension Object
 
@@ -99,6 +102,29 @@ You can distinguish the "Temporal Dimension" from an "Additional Dimension" by c
 So if the `type` equals `temporal` and `extent` is an array of strings/null, then you have a "Temporal Dimension",
 otherwise you have an "Additional Dimension".
 
+### Variable Object
+
+A *Variable Object* defines a variable (or a multi-dimensional array). The variable may have dimensions, which are described by [Dimension Objects](#dimension-object).
+
+| Field Name       | Type                         | Description |
+| ---------------- | -----------------------------| ----------- |
+| dimensions       | \[string]                    | **REQUIRED.** The dimensions of the variable. This should refer to keys in the ``cube:dimensions`` object or be an empty list if the variable has no dimensions. |
+| type             | string                       | **REQUIRED.** Type of the variable, either `data` or `auxiliary`. | 
+| description      | string                       | Detailed multi-line description to explain the variable. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. |
+| extent           | \[number\|string\|null]      | If the variable consists of [ordinal](https://en.wikipedia.org/wiki/Level_of_measurement#Ordinal_scale) values, the extent (lower and upper bounds) of the values as two-dimensional array. Use `null` for open intervals. |
+| values           | \[number\|string]            | A set of all potential values, especially useful for [nominal](https://en.wikipedia.org/wiki/Level_of_measurement#Nominal_level) values. |
+| unit             | string                       | The unit of measurement for the data, preferably compliant to [UDUNITS-2](https://ncics.org/portfolio/other-resources/udunits2/) units (singular). |
+
+**type**: The Variable `type` indicates whether what kind of variable is being described. It has two allowed values:
+
+1. `data`: a variable indicating some measured value, for example "precipitation", "temperature", etc.
+2. `auxiliary`: a variable that contains coordinate data, but isn't a dimension in `cube:dimensions`.
+  For example, the values of the datacube might be provided in the projected coordinate reference system, but
+  the datacube could have a variable `lon` with dimensions `(y, x)`, giving the longitude at each point.
+
+See the [CF Conventions](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#terminology)
+for more on auxiliary coordinates.
+
 ## Contributing
 
 All contributions are subject to the

examples/collection.json

@@ -1,5 +1,5 @@
 {
-  "stac_version": "1.0.0-rc.1",
+  "stac_version": "1.0.0",
   "stac_extensions": [
     "https://stac-extensions.github.io/datacube/v1.0.0/schema.json"
   ],

examples/daymet-hi-annual.json

@@ -0,0 +1,187 @@
+{
+  "stac_version": "1.0.0",
+  "stac_extensions": [
+    "https://stac-extensions.github.io/datacube/v1.0.0/schema.json"
+  ],
+  "type": "Collection",
+  "id": "daymet-hi-annual",
+  "title": "Daymet Hawaii Annual",
+  "description": "Daymet is a data product derived from a collection of algorithms and computer software designed to interpolate and extrapolate from daily meteorological observations to produce gridded estimates of daily weather parameters. Weather parameters generated include daily surfaces of minimum and maximum temperature, precipitation, vapor pressure, radiation, snow water equivalent, and day length produced on a 1 km x 1 km gridded surface. The motivation for producing Daymet is to provide measurements of near-surface meteorological conditions where no instrumentation exists. Having estimates of these surfaces is critical to understanding many processes in the terrestrial biogeochemical system.",
+  "license": "proprietary",
+  "extent": {
+    "spatial": {
+      "bbox": [
+        [
+          -160.3056,
+          17.9539,
+          -154.772,
+          23.5186
+        ]
+      ]
+    },
+    "temporal": {
+      "interval": [
+        [
+          "1980-01-01T12:00:00Z",
+          "2019-12-31T12:00:00Z"
+        ]
+      ]
+    }
+  },
+  "links": [],
+  "assets": {
+    "data": {
+      "href": "abfs://daymet-zarr/annual/hi.zarr",
+      "title": "Annual Hawaii Daymet zarr root",
+      "description": "The root of the annual Hawaii Daymet Zarr Group on Azure Blob Storage.",
+      "roles": [
+        "data",
+        "zarr-root",
+        "azure-blob-storge"
+      ]
+    }
+  },
+  "cube:dimensions": {
+    "time": {
+      "type": "temporal",
+      "extent": [
+        "1980:00:00T00:00:00Z",
+        "2020:00:00T00:00:00Z"
+      ],
+      "description": "Annual",
+      "step": "P1Y"
+    },
+    "x": {
+      "type": "spatial",
+      "axis": "x",
+      "description": "North American Lambert Conformal Conic, 1KM grid.",
+      "extent": [
+        -622000,
+        -5519250
+      ],
+      "step": 1000,
+      "reference_system": "PROJCRS[\"undefined\",BASEGEOGCRS[\"undefined\",DATUM[\"undefined\",ELLIPSOID[\"undefined\",6378137,298.257223563,LENGTHUNIT[\"metre\",1,ID[\"EPSG\",9001]]]],PRIMEM[\"Greenwich\",0,ANGLEUNIT[\"degree\",0.0174532925199433],ID[\"EPSG\",8901]]],CONVERSION[\"unknown\",METHOD[\"Lambert Conic Conformal (2SP)\",ID[\"EPSG\",9802]],PARAMETER[\"Latitude of 1st standard parallel\",25,ANGLEUNIT[\"degree\",0.0174532925199433],ID[\"EPSG\",8823]],PARAMETER[\"Latitude of 2nd standard parallel\",60,ANGLEUNIT[\"degree\",0.0174532925199433],ID[\"EPSG\",8824]],PARAMETER[\"Latitude of false origin\",42.5,ANGLEUNIT[\"degree\",0.0174532925199433],ID[\"EPSG\",8821]],PARAMETER[\"Longitude of false origin\",-100,ANGLEUNIT[\"degree\",0.0174532925199433],ID[\"EPSG\",8822]],PARAMETER[\"Easting at false origin\",0,LENGTHUNIT[\"metre\",1],ID[\"EPSG\",8826]],PARAMETER[\"Northing at false origin\",0,LENGTHUNIT[\"metre\",1],ID[\"EPSG\",8827]]],CS[Cartesian,2],AXIS[\"(E)\",east,ORDER[1],LENGTHUNIT[\"metre\",1,ID[\"EPSG\",9001]]],AXIS[\"(N)\",north,ORDER[2],LENGTHUNIT[\"metre\",1,ID[\"EPSG\",9001]]]]"
+    },
+    "y": {
+      "type": "spatial",
+      "axis": "y",
+      "description": "North American Lambert Conformal Conic, 1KM grid.",
+      "extent": [
+        -5802250,
+        -39000
+      ],
+      "step": 1000,
+      "reference_system": "PROJCRS[\"undefined\",BASEGEOGCRS[\"undefined\",DATUM[\"undefined\",ELLIPSOID[\"undefined\",6378137,298.257223563,LENGTHUNIT[\"metre\",1,ID[\"EPSG\",9001]]]],PRIMEM[\"Greenwich\",0,ANGLEUNIT[\"degree\",0.0174532925199433],ID[\"EPSG\",8901]]],CONVERSION[\"unknown\",METHOD[\"Lambert Conic Conformal (2SP)\",ID[\"EPSG\",9802]],PARAMETER[\"Latitude of 1st standard parallel\",25,ANGLEUNIT[\"degree\",0.0174532925199433],ID[\"EPSG\",8823]],PARAMETER[\"Latitude of 2nd standard parallel\",60,ANGLEUNIT[\"degree\",0.0174532925199433],ID[\"EPSG\",8824]],PARAMETER[\"Latitude of false origin\",42.5,ANGLEUNIT[\"degree\",0.0174532925199433],ID[\"EPSG\",8821]],PARAMETER[\"Longitude of false origin\",-100,ANGLEUNIT[\"degree\",0.0174532925199433],ID[\"EPSG\",8822]],PARAMETER[\"Easting at false origin\",0,LENGTHUNIT[\"metre\",1],ID[\"EPSG\",8826]],PARAMETER[\"Northing at false origin\",0,LENGTHUNIT[\"metre\",1],ID[\"EPSG\",8827]]],CS[Cartesian,2],AXIS[\"(E)\",east,ORDER[1],LENGTHUNIT[\"metre\",1,ID[\"EPSG\",9001]]],AXIS[\"(N)\",north,ORDER[2],LENGTHUNIT[\"metre\",1,ID[\"EPSG\",9001]]]]"
+    },
+    "nv": {
+      "type": "count",
+      "description": "Size of time_bnds.",
+      "values": [
+        0,
+        1
+      ]
+    }
+  },
+  "cube:variables": {
+    "lat": {
+      "type": "auxiliary",
+      "extent": [
+        17.960035,
+        23.512327
+      ],
+      "description": "latitude coordinate",
+      "unit": "degrees_north",
+      "dimensions": [
+        "y",
+        "x"
+      ]
+    },
+    "lon": {
+      "type": "auxiliary",
+      "extent": [
+        -160.29884,
+        -154.77806
+      ],
+      "description": "longitude coordinate",
+      "unit": "degrees_east",
+      "dimensions": [
+        "y",
+        "x"
+      ]
+    },
+    "prcp": {
+      "type": "data",
+      "description": "The total accumulated precipitation over the monthly period of the daily total precipitation. Sum of all forms of precipitation converted to a water-equivalent depth.",
+      "extent": [
+        0,
+        null
+      ],
+      "unit": "mm",
+      "dimensions": [
+        "time",
+        "y",
+        "x"
+      ]
+    },
+    "swe": {
+      "type": "data",
+      "description": "The average of the daily snow water equivalent (the amount of water contained within the snowpack) in kilograms per square meter over the monthly period.",
+      "extent": [
+        0,
+        null
+      ],
+      "unit": "kg/m2",
+      "dimensions": [
+        "time",
+        "y",
+        "x"
+      ]
+    },
+    "tmin": {
+      "type": "data",
+      "description": "The average minimum temperature for a daily period over the entire monthly period.",
+      "unit": "degrees C",
+      "dimensions": [
+        "time",
+        "y",
+        "x"
+      ]
+    },
+    "tmax": {
+      "type": "data",
+      "description": "The average maximum temperature for a daily period over the entire monthly period.",
+      "unit": "degrees C",
+      "dimensions": [
+        "time",
+        "y",
+        "x"
+      ]
+    },
+    "vp": {
+      "type": "data",
+      "description": "The average of the daily average partial pressure of water vapor over the monthly period.",
+      "unit": "Pa",
+      "dimensions": [
+        "time",
+        "y",
+        "x"
+      ]
+    },
+    "time_bnds": {
+      "type": "data",
+      "description": "",
+      "dimensions": [
+        "time",
+        "nv"
+      ]
+    },
+    "lambert_conformal_conic": {
+      "type": "data",
+      "description": "Lambert Conformal Conic.",
+      "values": [
+        -32767
+      ],
+      "dimensions": []
+    }
+  }
+}

examples/item.json

@@ -1,5 +1,5 @@
 {
-  "stac_version": "1.0.0-rc.1",
+  "stac_version": "1.0.0",
   "stac_extensions": [
     "https://stac-extensions.github.io/datacube/v1.0.0/schema.json"
   ],
@@ -99,6 +99,26 @@
       }
     }
   },
+  "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",

json-schema/schema.json

@@ -115,6 +115,12 @@
               }
             ]
           }
+        },
+       "cube:variables": {
+          "type": "object",
+          "additionalProperties": {
+              "$ref": "#/definitions/variable"
+          }
         }
       }
     },
@@ -171,6 +177,14 @@
         },
         "reference_system": {
           "type": "string"
+        },
+        "dimensions": {
+          "type": "array",
+          "items": {
+            "type": [
+              "string"
+            ]
+          }
         }
       }
     },
@@ -298,6 +312,50 @@
         }
       }
     },
+    "variable": {
+      "title": "Variable Object",
+      "type": "object",
+      "required": [
+        "dimensions"
+      ],
+      "properties": {
+        "variable_type": {
+          "type": "string",
+          "enum": [
+            "data",
+            "auxiliary"
+          ]
+        },
+        "description": {
+          "$ref": "#/definitions/description"
+        },
+        "dimensions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "values": {
+          "type": "array",
+          "minItems": 1
+        },
+        "extent": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 2,
+          "items": {
+            "type": [
+              "string",
+              "number",
+              "null"
+            ]
+          }
+        },
+        "unit": {
+          "$ref": "#/definitions/unit"
+        }
+      }
+    },
     "type_spatial": {
       "type": "string",
       "const": "spatial"