Metadata

stac-catalog generates STAC Collections and Items from structured raster metadata. Metadata is read from CSV files or a Google Sheet; both are normalized into the same internal tables before generation, so the output model is identical regardless of source.

Metadata tables

Three logical tables are supported:

Table	Required
collections	Yes
providers	No
catalogs	No

CSV input uses one file per table:

input/
├── collections.csv   # required
├── providers.csv     # optional
└── catalogs.csv      # optional

Google Sheets uses tabs with the same names. Only collections.csv / the collections tab is required.

Raster filename convention

For the best automatic metadata extraction, follow the preferred filename structure:

<product>[.tN]_<stat>_<gsd><m|km>_<depth>_<YYYYMMDD>[_<YYYYMMDD>]_<region>_epsg.<EPSG>_v<version>.<tif|tiff|vrt>

A typical example:

ampl.season1_clms.mrvpp_m_500m_s_20000101_20001231_eu_epsg.3035_v20250805.tif

From this, stac-catalog derives:

product:    ampl.season1_clms.mrvpp
statistic:  mean
resolution: 500 m
start:      2000-01-01
end:        2000-12-31
region:     Europe
EPSG:       3035
version:    20250805

The parser also accepts some older/fallback patterns, but new datasets should use the preferred structure.

Statistic tokens

Token	Meaning
c	class
m	mean
p	probability
std	standard deviation
pNN	quantile NN (e.g. p16, p50, p84)

Region tokens

Token	Region
go, g	global
eu, eumap	Europe
na	North America
sa	South America
af	Africa
as	Asia
oc	Oceania

Depth tokens

Common normalized depth tokens (and the value they produce):

0..0cm        → 0-0
b0cm..20cm    → 0-20
b20cm..50cm   → 20-50
b0t20cm       → 0-20
b30cm         → 0-30

The single-letter depth tokens s and a are also supported.

Collections

Each row of collections describes a raster dataset, or one variable of a grouped dataset.

Required fields

Field	Description
id	Dataset or grouped-variable identifier
main_url	Raster URL, or a raster URL template

Minimal example:

id,main_url
temperature,https://example.org/temperature_m_100m_s_20250101_20251231_eu_epsg.3035_v1.tif

The input validator checks required values only on rows that are eligible for processing (see Operational filtering).

URL template validation

Some fields become required when their placeholder appears in main_url:

Placeholder	Required field	Purpose
{dt}	start_date	date expansion
{dp}	depth_list	depth expansion
{var}	var_list	statistic/variant expansion

Example:

id,start_date,end_date,date_step,date_unit,main_url
temperature,2020-01-01,2024-12-31,1,years,https://example.org/temperature_m_100m_s_{dt}_eu_epsg.3035_v1.tif

An invalid template is rejected before generation — e.g. {dt} present but start_date missing.

Grouped Data Cubes

Rows that share a non-empty group_id are generated as one Collection.

id,group_id,group_title,label,layer_unit,main_url
soil.ph,soil_properties,Soil Properties,Soil pH,pH,https://example.org/soil.ph_m_30m_b0cm..20cm_20220101_20241231_eu_epsg.3035_v1.tif
soil.oc,soil_properties,Soil Properties,Soil organic carbon,kg/m3,https://example.org/soil.oc_m_30m_b0cm..20cm_20220101_20241231_eu_epsg.3035_v1.tif

If group_id is absent or blank, each id becomes its own Collection.

Useful grouped fields:

Field	Description
group_id	Groups rows into one Collection
group_title	Grouped Collection title
group_desc	Grouped Collection description
label	Variable description
layer_unit	Variable unit
depth_list	Collection depth values
var_list	Statistics or variants

Depth

depth_list uses the filename depth-token convention. Values such as b0cm..20cm, b20cm..50cm produce a spatial z axis:

{
  "type": "spatial",
  "axis": "z",
  "values": ["0-20", "20-50"],
  "unit": "cm"
}

Individual raster assets can also derive their own depth from their filename.

Positional statistics and variants

var_list can represent positional statistics or other variants.

Token	STAC value
m	mean
std	standard deviation
p16	quantile 16
p50	quantile 50
p84	quantile 84

Other values can be represented using a Data Cube variant dimension, e.g. m,p16,p84.

Dates

Date expansion uses these optional fields:

Field	Description
start_date	First date
end_date	Final date
date_step	Step size
date_offset	Additional offset between slices
date_coverage	Coverage in years for supported monthly datasets
date_unit	years, months, or a static/other unit
date_style	Formatting used for {dt}

Supported date styles:

Value	Result
interval	YYYYMMDD_YYYYMMDD
interval_b	YYYY.MM.DD..YYYY.MM.DD
date	YYYYMMDD
year	YYYY

Example:

start_date,end_date,date_step,date_unit,date_style
2020-01-01,2024-12-31,1,years,interval

Operational filtering

readyness is optional. If the column is absent, all rows are processed. If it is present, only rows where readyness = 1 are processed — inactive rows are also ignored by input validation.

Optional collection metadata

Common optional fields:

Field	Description
title	Collection title
description	Collection description
class	Dataset class
keywords_list	Keywords
version	Version override
doi	DOI
citation	Citation
license	License
contact_name	Contact name
contact_email	Contact email
providers_list	Provider identifiers (comma-separated)
collection_id	Explicit Collection ID override

Where possible, metadata that is not supplied explicitly is derived from the raster filename or the raster itself.

Styles

Optional style columns:

qml_url_1  qml_url_2  sld_url_1  sld_url_2

QML and SLD files are added as STAC style assets and linked to matching raster variables.

Additional assets

Optional additional-asset columns (url_1 … url_13). Their asset type and roles are inferred where possible.

Raster expressions and scaling

Optional fields:

Field	Description
expression	Raster expression
scale	Explicit scale
offset	Explicit offset

Raster metadata can also supply scale and offset automatically.

Derived metadata

From the filename: product, region, version, GSD, EPSG, start/end date, statistic, quantile, depth, variant, and variable.

From raster inspection: CRS, bounding box, geometry, projected bounding box, shape, transform, resolution, data type, nodata, scale, offset, file size, and checksum. Deriving these avoids duplicating raster properties in the input table.

Providers

providers.csv / the providers tab is optional.

name,roles_list,description,url
example_provider,producer,Example data provider,https://example.org

Field	Required
name	Yes
roles_list	No (defaults to producer when omitted)
description	No
url	No

Collections reference providers using providers_list.

Catalogs

catalogs.csv / the catalogs tab is optional.

id,title,description
example,Example Catalog,Example STAC catalog

Field	Required
id	Yes
title	No
description	No

Collections can be associated with a catalog using the catalog field. If no catalog is supplied, generated Collections and Items do not contain catalog_id.

Source independence

CSV and Google Sheets are source adapters only:

CSV ────────────┐
                ├──> normalized DataFrames → same builders → same STAC
Google Sheets ──┘

Changing the metadata source does not change the output model.