stac-pydantic

3.5.1 verified Sat May 09 auth: no python

Pydantic data models for the SpatioTemporal Asset Catalog (STAC) specification. Provides Python classes for validating and serializing STAC objects (Catalogs, Collections, Items, associated extensions) with strict conformance to the STAC spec. Version 3.5.1 supports Pydantic v2 and Python >=3.8.

pip install stac-pydantic

Common errors

error ValidationError: 1 validation error for Item ... Extra inputs are not permitted ↓

cause STAC Item contains fields not defined in the spec or extensions. The model is strict by default.

fix

Set model_config = {'extra': 'allow'} on a subclass or use strict=False when creating the model (if supported).

error TypeError: 'type' object is not subscriptable ↓

cause Using Pydantic v1 syntax like `Optional[str]` inside a `Field` with v2. stac-pydantic uses Pydantic v2.

fix

Upgrade to Pydantic v2 syntax: use str | None instead of Optional[str].

Warnings

breaking Version 3.0.0 dropped Pydantic v1 support. Use `model_dump()` instead of `dict()`, `model_validate()` instead of `parse_obj()`. ↓

fix Migrate to Pydantic v2 API: replace `.dict()` with `.model_dump()` and `parse_obj()` with `model_validate()`.

gotcha The `stac_extensions` field expects a list of URIs (strings), not objects. Passing extension objects will raise a validation error. ↓

fix Always pass extension URIs as strings, e.g., `['https://stac-extensions.github.io/eo/v1.0.0/schema.json']`.

deprecated The `from stac_pydantic.api import ItemCollection` and related API endpoints are deprecated and will be removed in 4.0. Use `stac_pydantic.collections.Collection` and `ItemCollection` from `stac_pydantic.links` instead. ↓

fix Import from `stac_pydantic.collections` and `stac_pydantic.links` as appropriate.

Imports

Catalog

wrong

from stac_pydantic.catalog import Catalog

correct

from stac_pydantic import Catalog

The top-level import is preferred and equivalent.

Quickstart

Create a basic STAC Catalog and dump to dict.

from stac_pydantic import Catalog, Collection, Item

catalog = Catalog(
    id='my-catalog',
    description='An example catalog',
    stac_version='1.0.0',
    stac_extensions=[],
    links=[]
)
print(catalog.model_dump())