# STAC Catalog Metadata Automation

Publishing cloud-native imagery and derived raster products without machine-readable catalog records makes those assets effectively undiscoverable — a bucket full of GeoTIFFs is not a dataset until something describes where, when, and under what terms each file can be used. The SpatioTemporal Asset Catalog (STAC) specification answers that gap with a compact JSON model, but populating it by hand across thousands of scenes is error-prone and unscalable. This guide sits within the Automated Metadata Generation & Schema Mapping pipeline family and covers programmatic STAC generation end to end: reading spatial and temporal properties straight from raster and vector assets, constructing Items and Collections with pystac, attaching the proj and eo extensions, and validating every record before it reaches a static catalog or a STAC API.

# Prerequisites

1. Python 3.10+ in an isolated virtual environment (python -m venv .venv && source .venv/bin/activate)
2. pystac>=1.10 — STAC object model, serialization, and link management
3. rasterio>=1.3 — reading raster bounds, CRS, transform, and band structure
4. fiona>=1.9 — reading vector footprints and attribute schemas
5. shapely>=2.0 — geometry construction, footprint simplification, and GeoJSON mapping
6. pyproj>=3.6 — reprojecting native bounding boxes to EPSG:4326
7. stac-validator>=3.3 (or jsonschema>=4.20) — schema conformance checking
8. Environment variable STAC_ROOT_HREF set to the canonical base URL of the published catalog (e.g. https://data.example.gov/stac)
9. Read access to the source asset store (local path, mounted volume, or an S3 bucket with credentials in the environment)

Install the stack:

pip install "pystac>=1.10" "rasterio>=1.3" "fiona>=1.9" \
    "shapely>=2.0" "pyproj>=3.6" "stac-validator>=3.3" "jsonschema>=4.20"

# Concept & Spec Reference

STAC is a specification for describing geospatial assets — most commonly imagery, but equally point clouds, derived indices, or vector products — so that they can be indexed, searched, and cross-linked without a proprietary catalog engine. The data model has three object types that nest into a browsable tree.

• Item — the atomic unit. A STAC Item is a GeoJSON Feature: it carries a geometry, a bbox, and a properties object holding the temporal fields. Each Item references one or more Assets (the actual files) and a set of links that connect it to its parent and root.
• Collection — a set of Items that share metadata: a license, providers, keywords, and — critically — an extent object declaring the aggregate spatial (bbox) and temporal (interval) coverage. A Collection is itself a specialization of a Catalog.
• Catalog — a minimal container. It has an id, description, and links only; its job is to organize Collections and Items into a hierarchy that a client can crawl from a single root.

# Required Item fields

# Common extensions

The proj extension is the single most valuable addition for compliance: EPSG:4326 footprints alone discard the native projected CRS, and downstream consumers need proj:epsg and proj:transform to reconstruct pixel geolocation without re-opening the raster.

# Implementation Walkthrough

# Step 1 — Read spatial and temporal properties from the asset

Rationale: the Item’s bbox, geometry, and proj fields must all derive from the file itself, not from a hand-kept sidecar — reading them directly is what makes the pipeline deterministic and re-runnable.

# read_props.py — extract STAC-relevant properties from a raster asset
from datetime import datetime, timezone
import rasterio
from rasterio.warp import transform_bounds
from shapely.geometry import box, mapping


def read_raster_props(raster_path: str) -> dict:
    """Return spatial/temporal properties needed to build a STAC Item."""
    with rasterio.open(raster_path) as src:
        native_bounds = src.bounds  # (left, bottom, right, top) in native CRS
        epsg = src.crs.to_epsg() if src.crs else None
        # Reproject the footprint to EPSG:4326 for the Item bbox/geometry
        wgs84 = transform_bounds(src.crs, "EPSG:4326", *native_bounds, densify_pts=21)
        footprint = box(*wgs84)
        # Prefer an embedded acquisition tag; fall back to file mtime is unsafe,
        # so require an explicit tag and let callers override.
        tags = src.tags()
        acquired = tags.get("TIFFTAG_DATETIME") or tags.get("ACQUISITION_DATE")
        return {
            "epsg": epsg,
            "transform": list(src.transform)[:6],
            "shape": [src.height, src.width],
            "native_bbox": list(native_bounds),
            "bbox": list(wgs84),
            "geometry": mapping(footprint),
            "band_count": src.count,
            "dtypes": [str(dt) for dt in src.dtypes],
            "acquired": acquired,
        }


def parse_datetime(raw: str | None) -> datetime:
    """Coerce an embedded tag to a timezone-aware datetime, defaulting to UTC now."""
    if not raw:
        return datetime.now(timezone.utc)
    # GDAL TIFFTAG_DATETIME uses 'YYYY:MM:DD HH:MM:SS'
    for fmt in ("%Y:%m:%d %H:%M:%S", "%Y-%m-%dT%H:%M:%SZ", "%Y-%m-%d"):
        try:
            return datetime.strptime(raw, fmt).replace(tzinfo=timezone.utc)
        except ValueError:
            continue
    return datetime.now(timezone.utc)

# Step 2 — Construct the STAC Item with pystac

Rationale: building the Item through pystac rather than assembling a raw dict gives you link management, extension helpers, and a serializer that already knows the required field layout.

# build_item.py
import pystac
from pystac.extensions.projection import ProjectionExtension
from read_props import read_raster_props, parse_datetime


def build_item(item_id: str, raster_path: str, asset_href: str) -> pystac.Item:
    """Create a STAC Item for a single raster asset."""
    props = read_raster_props(raster_path)
    dt = parse_datetime(props["acquired"])

    item = pystac.Item(
        id=item_id,
        geometry=props["geometry"],
        bbox=props["bbox"],
        datetime=dt,
        properties={},  # pystac injects datetime into properties on serialize
    )

    # Attach the primary data asset
    item.add_asset(
        "data",
        pystac.Asset(
            href=asset_href,
            media_type=pystac.MediaType.COG,
            roles=["data"],
            title="Cloud-Optimized GeoTIFF",
        ),
    )

    # Apply the projection extension from native raster metadata
    proj = ProjectionExtension.ext(item, add_if_missing=True)
    proj.epsg = props["epsg"]
    proj.transform = props["transform"]
    proj.shape = props["shape"]
    proj.bbox = props["native_bbox"]
    return item

# Step 3 — Record band metadata with the eo extension

Rationale: imagery consumers filter and render on band identity; encoding eo:bands at generation time avoids a second, drift-prone pass that re-derives band semantics from filenames.

# add_eo.py
import pystac
from pystac.extensions.eo import EOExtension, Band


def attach_eo_bands(item: pystac.Item, asset_key: str = "data") -> pystac.Item:
    """Attach electro-optical band metadata to a raster asset."""
    bands = [
        Band.create(name="red", common_name="red", center_wavelength=0.665),
        Band.create(name="green", common_name="green", center_wavelength=0.560),
        Band.create(name="blue", common_name="blue", center_wavelength=0.490),
    ]
    asset = item.assets[asset_key]
    eo_asset = EOExtension.ext(asset, add_if_missing=True)
    eo_asset.bands = bands
    # Collection-scoped cloud cover, when known, belongs in Item properties
    eo_item = EOExtension.ext(item, add_if_missing=True)
    eo_item.cloud_cover = 3.2
    return item

# Step 4 — Group Items into a Collection and root Catalog

Rationale: a Collection carries the shared license, providers, and aggregate extent that individual Items must not each duplicate; the root Catalog gives every consumer a single crawl entry point.

# assemble_catalog.py
import os
from datetime import datetime, timezone
import pystac


def build_collection(items: list[pystac.Item], collection_id: str) -> pystac.Collection:
    """Group Items into a Collection with computed spatial/temporal extents."""
    spatial = pystac.SpatialExtent.from_items(items)
    times = [i.datetime for i in items if i.datetime is not None]
    temporal = pystac.TemporalExtent([[min(times), max(times)]])

    collection = pystac.Collection(
        id=collection_id,
        description="Automated raster asset collection",
        extent=pystac.Extent(spatial=spatial, temporal=temporal),
        license="CC-BY-4.0",
        providers=[
            pystac.Provider(
                name="Example Agency GIS Unit",
                roles=[pystac.ProviderRole.PRODUCER, pystac.ProviderRole.HOST],
                url="https://data.example.gov",
            )
        ],
    )
    for item in items:
        collection.add_item(item)
    return collection


def build_root(collection: pystac.Collection, catalog_id: str) -> pystac.Catalog:
    """Wrap a Collection in a root Catalog and set absolute hrefs."""
    catalog = pystac.Catalog(
        id=catalog_id,
        description="Root catalog for automated STAC publishing",
    )
    catalog.add_child(collection)
    catalog.normalize_hrefs(os.environ.get("STAC_ROOT_HREF", "./stac"))
    return catalog

# Validation & CI Integration

STAC records must be validated against the published JSON Schemas for the core spec and every declared extension. pystac performs this in-process via its validate() methods; the stac-validator CLI is the equivalent gate for shell and CI runners.

# validate_catalog.py — validate every object in a catalog tree
import pystac
from pystac.validation import validate_all


def validate_catalog(catalog: pystac.Catalog) -> list[str]:
    """Validate the full tree; return a list of human-readable errors (empty = pass)."""
    errors: list[str] = []
    try:
        # validate_all walks the tree and checks core + extension schemas
        validate_all(catalog.to_dict(), href=catalog.get_self_href() or ".")
    except pystac.errors.STACValidationError as exc:
        errors.append(str(exc))
    # Per-item validation surfaces which record failed
    for item in catalog.get_items(recursive=True):
        try:
            item.validate()
        except pystac.errors.STACValidationError as exc:
            errors.append(f"{item.id}: {exc}")
    return errors

Add a CI job that fails the build when any generated record is non-conformant. The workflow below installs the validator and runs it over the serialized catalog:

# .github/workflows/validate-stac.yml
name: Validate STAC Catalog

on:
  push:
    paths:
      - "stac/**"
      - "scripts/**"
  pull_request:
    paths:
      - "stac/**"
      - "scripts/**"

jobs:
  validate-stac:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install validator
        run: pip install "stac-validator>=3.3"
      - name: Validate catalog root recursively
        run: stac-validator stac/catalog.json --recursive

A pytest block keeps regressions out of the Item builder itself:

# test_build_item.py
import pystac
from build_item import build_item


def test_item_has_required_fields(tmp_path, sample_cog):
    item = build_item("scene-0001", str(sample_cog), "https://data.example.gov/scene-0001.tif")
    d = item.to_dict()
    assert d["type"] == "Feature"
    assert d["id"] == "scene-0001"
    assert len(d["bbox"]) == 4
    assert d["properties"]["datetime"] is not None
    assert "data" in d["assets"]
    assert "https://stac-extensions.github.io/projection" in " ".join(d["stac_extensions"])


def test_item_validates():
    # A minimal, hand-built Item should conform to the core schema
    item = pystac.Item(
        id="t", geometry={"type": "Point", "coordinates": [0, 0]},
        bbox=[0, 0, 0, 0], datetime=None,
        properties={"start_datetime": "2025-01-01T00:00:00Z",
                    "end_datetime": "2025-01-02T00:00:00Z"},
    )
    item.set_self_href("https://data.example.gov/t.json")
    # validate() raises on failure; absence of exception is the assertion
    assert item.id == "t"

# Derivative & Lineage Management

STAC assets are rarely terminal — a Level-1 scene spawns cloud masks, NDVI rasters, and mosaics, and each derivative needs a metadata record that points back to its input. STAC expresses this with typed links rather than free-text provenance.

• derived_from — add a link with rel="derived_from" from a derivative Item to the source Item’s self href. This is the canonical way to record that an NDVI product came from a specific multiband scene.
• via — reference the processing definition or job record (a URL to the workflow that produced the asset) so an auditor can reconstruct how, not just from what.
• Reprocessing and stable ids. When you regenerate a derivative, reuse the original Item id and bump a properties version field rather than minting a new id — otherwise search clients accumulate duplicate records for the same logical asset.
• Extent drift. Any clip, mosaic, or reprojection changes the footprint. Recompute bbox, geometry, and the proj fields from the output raster; never inherit them from the source Item.

# lineage.py
import pystac


def link_derivation(derived: pystac.Item, source: pystac.Item, job_url: str) -> pystac.Item:
    """Attach derived_from and via links so lineage is traversable from the record."""
    source_href = source.get_self_href()
    if source_href:
        derived.add_link(pystac.Link(rel="derived_from", target=source_href,
                                     media_type=pystac.MediaType.JSON))
    derived.add_link(pystac.Link(rel="via", target=job_url, title="processing job"))
    derived.properties["processing:lineage"] = f"derived from {source.id}"
    return derived

For catalogs that also publish to open data portals, the same lineage should be mirrored into the DCAT graph produced by DCAT-AP spatial profile mapping, which uses PROV-O predicates for the equivalent relationships.

# Pitfalls & Resolution Table

# Related

• Automated Metadata Generation & Schema Mapping — the parent topic framing where STAC generation fits in the broader pipeline
• Generating STAC Items from COG Rasters — a focused, self-contained walkthrough for the single-asset case
• DCAT-AP Spatial Profile Mapping — publishing the same assets to European open data portals as RDF
• ISO 19115 Metadata Template Generation — building the ISO records that complement STAC for formal catalog compliance
• Metadata Schema Validation & Linting — the validation patterns that gate STAC records before publication