Create a STAC catalog: a practical guide to organizing geospatial assets

What you are building—and what STAC does not do

A minimal STAC Catalog is a JSON document with a STAC version, object type, identifier, description, and links. Its links lead to child Catalogs, Collections, or Items. The structure is intentionally flexible: catalogs can be organized by date, geography, provider, product family, processing version, or another meaningful hierarchy. The STAC tutorial describes a Catalog as a starting point for navigating a tree of STAC objects, rather than as a rigid database schema. (stacspec.org)

An Item is the atomic record for an asset or inseparable group of assets. It uses a GeoJSON Feature shape and normally includes an identifier, geometry, bounding box, temporal properties, links, and an assets object. The Asset entries point to the files or services that users actually want to download or read. For example, one imagery Item might expose a primary GeoTIFF, a thumbnail, a cloud-optimized copy, and a metadata document as separate assets.

• •Good fit: static publishing, object-storage inventories, dataset exchange, reproducible releases, and machine-readable discovery.
• •Not sufficient by itself: raster processing, vector analysis, routing, geocoding, authentication, data transformation, or high-volume interactive search.
• •STAC metadata should describe the underlying asset accurately; it should not imply that the catalog contains a copy of the asset.

Prerequisites and design decisions

Before writing code, identify the assets you will publish and decide what one Item represents. For imagery, an Item often represents one scene at one acquisition time, while individual bands or representations become Assets. For a time series, an Item might represent one observation date. For a derived product, it might represent one tile, one model run, or one processing result. The correct granularity depends on how users will search, compare, and consume the data.

You also need a stable identifier policy. Item identifiers should remain stable when the underlying observation or product has not changed. If a new processing version creates a materially different product, encode that distinction in the identifier or in documented properties. Avoid generating identifiers from temporary filenames or local directory paths.

• •Python 3 and a virtual environment.
• •The PySTAC package for creating and writing STAC objects.
• •A footprint or bounding box for each Item.
• •An asset location, such as a local path, HTTPS URL, or object-storage URL.
• •A license and provenance policy for the data you are publishing.
• •Optional: stac-validator for recursive validation of catalogs, Items, Collections, links, and assets.

Step 1: install PySTAC and create the catalog

PySTAC is a Python library for reading and writing STAC objects. The basic workflow is to create a Catalog, create one or more Items, attach Assets, add the Items to the Catalog or Collection, normalize the file layout, and save the result. PySTAC’s tutorial documents this in-memory-to-filesystem workflow and explains that normalization sets the self links used when saving objects. (stacspec.org)

• •Create an isolated environment and install the library:

Step 2: create an Item with geometry, time, and an asset

The following example creates a small catalog for one geospatial file. The geometry is a simple polygon footprint; replace it with the actual footprint of your asset. The example uses an HTTPS asset URL, but the same field can point to a local file or object-storage location.

• •Use a UTC datetime and attach descriptive metadata:

Step 3: add a Collection when the dataset has shared metadata

A Collection is useful when all Items belong to a known product family or dataset. It lets you put shared information—such as license, providers, keywords, and overall spatial or temporal extents—at the collection level instead of duplicating it on every Item. Items still need their own geometry, temporal information, identifiers, and assets.

For a catalog containing many unrelated products, create multiple Collections under one root Catalog. For a single homogeneous dataset, one Collection under a root Catalog is often enough. This structure also gives future API implementations a natural unit for discovery and filtering.

• •Use a Collection when users will ask questions such as: which observations belong to this product, who produced them, what license applies, or what time and geographic range does the dataset cover?
• •Use a plain Catalog for navigation when the children are primarily other catalogs or collections and there is no single shared dataset description.

Step 4: normalize links and save a publishable layout

Objects created in memory do not automatically have useful self links. Call normalize_hrefs with a root directory before saving. PySTAC then assigns predictable paths such as catalog.json at the root and an Item JSON file below an Item-specific directory. The official tutorial demonstrates both self-contained catalogs with relative links and absolute-published catalogs with absolute links. (stacspec.org)

For a portable archive, use relative links and keep the catalog JSON files together. For a public deployment, absolute links can make the catalog independent of its serving location, but they require a stable publishing domain or object-storage namespace. Do not mix assumptions casually: a catalog that works on a local filesystem may fail when uploaded if asset links point to local paths.

• •A typical save sequence is:
• •After saving, inspect catalog.json and at least one Item JSON manually. Confirm that root, parent, collection, item, and self links point to the intended locations.
• •If assets should be relative to the Item file, make the asset HREFs relative before saving. Otherwise, preserve absolute URLs for a deliberately published catalog.

Step 5: validate the catalog and test the real links

Validation should happen before publication and in continuous integration. The STAC specification provides schemas for its core objects and extensions, while stac-validator can validate Items, Collections, and Catalogs and can recursively inspect related objects. Its command-line options include recursive traversal, link validation, asset validation, extension checks, and maximum-depth controls. (stac-validator.readthedocs.io)

Schema validation is necessary but not sufficient. Also test that every asset URL resolves, every geometry is valid for the intended footprint, every timestamp is parseable, the declared license is accurate, and the published data has the permissions and retention characteristics users expect. A catalog can be structurally valid while pointing to expired signed URLs, private buckets, moved files, or assets with the wrong coordinate reference system.

• •Example validation command:
• •Check both the root catalog and a representative Item directly.
• •If you use extensions, ensure the extension identifiers are declared and that extension fields follow the relevant extension specification.

Operating the catalog as the dataset grows

A small static catalog can be served from ordinary web hosting or object storage. As the number of Items grows, the filesystem tree and JSON traversal model may become less convenient for users and applications. At that point, consider exposing the same STAC objects through a STAC API or indexing the metadata in a purpose-built catalog service. STAC API supports browsing and querying Items and Collections, including search across collections, while keeping STAC Items as the returned geographic records. (docs.ogc.org)

Keep the publishing process reproducible. Generate catalog files from a source manifest, record the source-data version and processing version, and publish a release atomically so that the root catalog does not point to a mixture of old and new files. If assets are immutable, content-addressed, or versioned, say so in your documentation. If assets can change in place, document that too, because a stable Item identifier does not guarantee stable bytes.

• •Start with static STAC when publishing and portability matter more than interactive query.
• •Add a STAC API when users need dynamic spatial, temporal, or property filtering.
• •Keep processing and analysis outside the catalog layer unless you are deliberately integrating a separate raster, vector, database, or workflow system.