Datacube Extension Specification

• Title: Datacube
• Identifier: https://stac-extensions.github.io/datacube/v2.2.0/schema.json
• Field Name Prefix: cube
• Scope: Item, Collection
• Extension Maturity Classification: Candidate
• Owner: @m-mohr

This document explains the Datacube Extension to the SpatioTemporal Asset Catalog (STAC) specification. It specifies datacube related metadata, especially their dimensions and potentially more in the future.

• Examples:
  • Item example: Shows the basic usage of the extension in a STAC Item
  • Collection example: Shows the basic usage of the extension in a STAC Collection
• JSON Schema
• Changelog

Fields

The following fields can be used in the following parts of a STAC document:

• Catalogs
• Collections
• Item Properties (incl. Summaries in Collections)
• Assets (both Collections and Items, incl. Item Asset Definitions in Collections)
• Links

Field Name	Type	Description
cube:dimensions	Map<string, Dimension Object>	REQUIRED. Uniquely named dimensions of the datacube.
cube:variables	Map<string, 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

A Dimension Object comes in different flavors, each of them is defined below. The fields define mostly very similar fields, but they differ slightly depending on their use case. All objects share the fields type and description with the same definition, but type may be restricted to certain values. The definition ofaxis is shared between the spatial dimensions, but restricted to certain values, too. extent, values and step share the same definition, but differ in the supported data types (number or string) depending on the type of dimension. Whenever it's useful to specify these fields, the objects add the additional fields reference_system and unit with very similar definitions across the objects.

Horizontal Spatial Raster Dimension Object

A spatial raster dimension in one of the horizontal (x or y) directions.

Field Name	Type	Description
type	string	REQUIRED. Type of the dimension, always spatial.
axis	string	REQUIRED. Axis of the spatial raster dimension (x, y).
description	string	Detailed multi-line description to explain the dimension. CommonMark 0.29 syntax MAY be used for rich text representation.
extent	[number]	REQUIRED. Extent (lower and upper bounds) of the dimension as two-element array. Open intervals with null are not allowed.
values	[number]	Optionally, an ordered list of all values.
step	number|null	The space between the values. Use null for irregularly spaced steps.
reference_system	string|number|object	The spatial reference system for the data, specified as numerical EPSG code, WKT2 (ISO 19162) string or PROJJSON object. Defaults to EPSG code 4326.

Vertical Spatial Dimension Object

A spatial dimension in vertical (z) direction.

Field Name	Type	Description
type	string	REQUIRED. Type of the dimension, always spatial.
axis	string	REQUIRED. Axis of the spatial dimension, always z.
description	string	Detailed multi-line description to explain the dimension. CommonMark 0.29 syntax MAY be used for rich text representation.
extent	[number|null]	If the dimension consists of ordinal values, the extent (lower and upper bounds) of the values as two-element array. Use null for open intervals.
values	[number|string]	An ordered list of all values, especially useful for nominal values.
step	number|null	If the dimension consists of interval values, the space between the values. Use null for irregularly spaced steps.
unit	string	The unit of measurement for the data, preferably compliant to UDUNITS-2 units (singular).
reference_system	string|number|object	The spatial reference system for the data, specified as numerical EPSG code, WKT2 (ISO 19162) string or PROJJSON object. Defaults to EPSG code 4326.

A Vertical Spatial Dimension Object MUST specify an extent or values. It MAY specify both.

Temporal Dimension Object

A temporal dimension based on the ISO 8601 standard. The temporal reference system for the data is expected to be ISO 8601 compliant (Gregorian calendar / UTC). Data not compliant with ISO 8601 can be represented as an Additional Dimension Object with type set to temporal.

Field Name	Type	Description
type	string	REQUIRED. Type of the dimension, always temporal.
description	string	Detailed multi-line description to explain the dimension. CommonMark 0.29 syntax MAY be used for rich text representation.
extent	[string|null]	REQUIRED. Extent (lower and upper bounds) of the dimension as two-element array. The dates and/or times must be strings compliant to ISO 8601. null is allowed for open date ranges.
values	[string]	If the dimension consists of an ordered list of specific values they can be listed here. The dates and/or times must be strings compliant to ISO 8601.
step	string|null	The space between the temporal instances as ISO 8601 duration, e.g. P1D. Use null for irregularly spaced steps.

Spatial Vector Dimension Object

A vector dimension that defines a spatial dimension based on geometries.

Field Name	Type	Description
type	string	REQUIRED. Type of the dimension, always geometry.
axes	[string]	Axes of the vector dimension as an ordered set of x, y and z. Defaults to x and y.
description	string	Detailed multi-line description to explain the dimension. CommonMark 0.29 syntax MAY be used for rich text representation.
bbox	[number]	REQUIRED. A single bounding box of the geometries as defined for STAC Collections, but not nested.
values	[string]	Optionally, a representation of the geometries. This could be a list of WKT strings or other identifiers.
geometry_types	[GeoJSON Types]	A set of geometry types. If not present, mixed geometry types must be assumed.
reference_system	string|number|object	The spatial reference system for the data, specified as numerical EPSG code, WKT2 (ISO 19162) string or PROJJSON object. Defaults to EPSG code 4326.

For a general explanation what a vector datacube and a vector dimension is, please read the article "Vector Data Cubes".

Additional Dimension Object

An additional dimension that is not spatial, but may be temporal if the data is not compliant with ISO 8601 (see below).

Field Name	Type	Description
type	string	REQUIRED. Custom type of the dimension, never spatial or geometry.
description	string	Detailed multi-line description to explain the dimension. CommonMark 0.29 syntax MAY be used for rich text representation.
extent	[number|null]	If the dimension consists of ordinal values, the extent (lower and upper bounds) of the values as two-element array. Use null for open intervals.
values	[number|string]	An ordered list of all values, especially useful for nominal values.
step	number|null	If the dimension consists of interval values, the space between the values. Use null for irregularly spaced steps.
unit	string	The unit of measurement for the data, preferably compliant to UDUNITS-2 units (singular).
reference_system	string	The reference system for the data.

An Additional Dimension Object MUST specify an extent or values. It MAY specify both.

Note on "Additional Dimension" with type temporal: You can distinguish the "Temporal Dimension" from an "Additional Dimension" by checking whether the extent exists and contains strings. 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.

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 syntax MAY be used for rich text representation.
extent	[number|string|null]	If the variable consists of ordinal values, the extent (lower and upper bounds) of the values as two-element array. Use null for open intervals.
values	[number|string]	An (ordered) list of all values, especially useful for nominal values.
unit	string	The unit of measurement for the data, preferably compliant to UDUNITS-2 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 for more on auxiliary coordinates.

Contributing

All contributions are subject to the STAC Specification Code of Conduct. For contributions, please follow the STAC specification contributing guide Instructions 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. To run tests locally, you'll need npm, which is a standard part of any node.js installation.

First you'll need to install everything with npm once. Just navigate to the root of this repository and on your command line run:

npm install

Then to check markdown formatting and test the examples against the JSON schema, you can run:

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:

npm run format-examples