• 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

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

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.

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.

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

A spatial dimension in vertical (z) direction.

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

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.

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

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

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

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".

A Variable Object defines a variable (or a multi-dimensional array). The variable may have dimensions, which are described by Dimension Objects.

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.

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.

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