Create a STAC catalog: production guide for organizing spatiotemporal assets

What you are building

A static STAC catalog is a set of JSON documents connected by links. The root Catalog points to child Catalogs, Collections, or Items. A Collection is appropriate when a group of Items shares higher-level metadata such as a license, provider, spatial extent, temporal extent, keywords, or summaries. An Item is the leaf-level record for an individual spatiotemporal asset and includes geometry, time, properties, links, and an assets dictionary. (github.com)

The distinction matters operationally. A Catalog can act like a navigable directory, while a Collection gives clients context about the dataset as a whole. For example, a catalog might contain a Collection for orthophotography, another for elevation products, and another for vegetation observations. Individual Items might represent one image scene, one tile, one point-cloud acquisition, or one dated observation. The correct unit depends on what users need to search, retrieve, and process.

• •Catalog: organizes and links related STAC resources.
• •Collection: describes a related set of Items with shared context.
• •Item: identifies one spatiotemporal asset and its metadata.
• •Asset: points to the downloadable or streamable data, thumbnail, mask, metadata file, or other supporting resource.
• •Link: expresses relationships such as self, root, parent, child, item, collection, or asset.

Prerequisites and design decisions

Before writing code, define the unit represented by an Item. For imagery, it may be one scene or tile. For repeated measurements, it may be one acquisition or observation. For point clouds, it may be one flight strip, tile, or collection of files. Avoid creating Items whose meaning changes from record to record; inconsistent granularity makes later search and comparison harder.

Choose a stable identifier policy. The STAC best-practices guidance recommends identifiers that are useful for discovery and compatible with filenames and links. Decide whether identifiers come from the source provider, a processing pipeline, a tile index, an acquisition timestamp, or a deterministic combination of those fields. Do not silently change IDs when regenerating metadata unless you are intentionally publishing a new version.

• •Python 3 and a virtual environment.
• •PySTAC for constructing and saving STAC objects.
• •A sample geographic asset with a durable path or URL.
• •A valid spatial extent and acquisition time for each Item.
• •A license, provider, and contact or provenance policy for the Collection.
• •A validation step in CI or before publication.

Step 1: create the environment and install tools

Create an isolated Python environment and install PySTAC. Pin the versions used by your production pipeline rather than allowing an unreviewed dependency update to change serialization or validation behavior.

• •The PySTAC documentation provides the Catalog, Collection, Item, layout, and save APIs used in this workflow. (pystac.readthedocs.io)
• •The STAC validation ecosystem includes tools for validating STAC JSON against the official schemas and for checking best practices. The validator project currently documents `stac-valid` as the PyPI package name while retaining the `stac-validator` command. (github.com)

Step 2: create a Collection and Item with PySTAC

The following example creates a Collection for a small set of aerial imagery and adds one Item. The geometry is written in GeoJSON coordinate order, longitude first and latitude second. The Item's `datetime` is expressed as an aware UTC datetime. The example uses a placeholder asset URL; replace it with a real object-storage or HTTP location.

• •A Collection requires meaningful spatial and temporal extents, a license, and descriptive metadata.
• •An Item should have a stable ID, a geometry, a bounding box, a UTC datetime, and an asset link.
• •Use the `data` role for the primary asset and `thumbnail` for a browse image when one exists. STAC recommends linking the main data file and commonly recommends a thumbnail for preview. (github.com)

Step 3: create the root Catalog and normalize the layout

After constructing the Collection and Item, attach the Collection to a root Catalog. PySTAC tracks self links and can normalize the HREFs for the entire tree according to a chosen layout strategy. The default best-practices layout creates conventional paths for the root catalog, collections, and items. PySTAC also supports template and custom layout strategies when a dataset needs a different partitioning scheme. (pystac.readthedocs.io)

Do not publish the in-memory object graph before setting its HREFs. A catalog can appear correct in Python while still containing missing or unresolved links. Normalize against the directory or URL root that will actually be published, then inspect the saved JSON files.

• •Use relative links when the catalog should be portable between environments.
• •Use absolute links when clients will consume the catalog from a fixed public location and the publication root is stable.
• •Keep asset URLs independent from local build paths.
• •If the archive is large, partition it consistently by collection, date, geography, or another searchable dimension.
• •Use link titles where helpful so clients can display readable names without opening every target document. (github.com)

Step 4: validate objects, links, assets, and semantics

Validation should happen at several levels. First validate the JSON against the STAC schema. Then validate extensions if you use them. Then check links and assets, including whether the referenced documents and data files can actually be retrieved. Finally run dataset-specific checks: geometry validity, ID uniqueness, time ordering, expected asset roles, file existence, content types, and consistency between Collection extents and the Items they contain.

The STAC validator documents single-file, batch, recursive, extension, link, and asset validation modes. The separate `stac-check` project adds linting based on STAC best practices, which can catch issues that are not necessarily schema failures, such as naming and layout choices. (github.com)

• •Schema validation: required fields, data types, and allowed structures.
• •Extension validation: fields declared by EO, projection, raster, scientific, view, or other extensions.
• •Link validation: self, root, parent, child, collection, item, and asset targets.
• •Asset validation: URL reachability, expected media type, permissions, and file integrity.
• •Geographic validation: valid geometry, bounding-box consistency, coordinate order, and expected CRS conventions.
• •Catalog validation: unique IDs, no broken relative paths, and consistent Collection extents.

Step 5: publish and operate the catalog

A static STAC catalog can be published from ordinary web hosting or object storage as long as clients can retrieve the linked JSON documents and assets. Treat the generated catalog as a versioned build artifact. Generate it from source metadata, validate it, publish it to a new release location, and promote that release only after link and asset checks pass.

Keep metadata generation separate from asset processing. A pipeline may transform imagery, generate cloud-optimized files, calculate thumbnails, or derive statistics in one stage, then create or update STAC Items in another. This separation makes it easier to identify whether a failure is in the geographic data, the asset file, or the catalog metadata.

• •Generate into a temporary directory.
• •Run schema, link, asset, and domain-specific checks.
• •Publish atomically or promote a versioned directory.
• •Record the source-data version and processing code version.
• •Monitor link failures and asset availability after publication.
• •Retain previous catalog releases when reproducibility matters.