{"id":13735312,"url":"https://github.com/stac-utils/stac-pydantic","last_synced_at":"2025-06-23T17:11:51.139Z","repository":{"id":40533925,"uuid":"246169093","full_name":"stac-utils/stac-pydantic","owner":"stac-utils","description":"Pydantic data models for the STAC spec","archived":false,"fork":false,"pushed_at":"2024-10-14T12:45:28.000Z","size":319,"stargazers_count":60,"open_issues_count":6,"forks_count":24,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-10-14T13:01:10.445Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stac-utils.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-10T00:10:57.000Z","updated_at":"2024-10-14T12:44:22.000Z","dependencies_parsed_at":"2023-12-18T20:13:30.336Z","dependency_job_id":"fc6adb8a-cbb8-4e7f-8f9e-e952b1fffc49","html_url":"https://github.com/stac-utils/stac-pydantic","commit_stats":{"total_commits":172,"total_committers":14,"mean_commits":"12.285714285714286","dds":0.2965116279069767,"last_synced_commit":"f28081ad3ed066e13a826cb305666730659e8a90"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-pydantic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-pydantic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-pydantic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-pydantic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stac-utils","download_url":"https://codeload.github.com/stac-utils/stac-pydantic/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224727180,"owners_count":17359532,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T03:01:05.399Z","updated_at":"2024-11-15T03:31:41.183Z","avatar_url":"https://github.com/stac-utils.png","language":"Python","funding_links":[],"categories":["`Python` processing of optical imagery (non deep learning)"],"sub_categories":["Cloud Native Geospatial"],"readme":"# stac-pydantic\n\n[![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/stac-utils/stac-pydantic/cicd.yml?style=for-the-badge)](https://github.com/stac-utils/stac-pydantic/actions/workflows/cicd.yml)\n\n[Pydantic](https://pydantic-docs.helpmanual.io/) models for [STAC](https://github.com/radiantearth/stac-spec) Catalogs, Collections, Items, and the [STAC API](https://github.com/radiantearth/stac-api-spec) spec.\nInitially developed by [arturo-ai](https://github.com/arturo-ai).\n\nThe main purpose of this library is to provide reusable request/response models for tools such as [fastapi](https://fastapi.tiangolo.com/).\nFor more comprehensive schema validation and robust extension support, use [pystac](https://github.com/stac-utils/pystac).\n\n## Installation\n\n```shell\npython -m pip install stac-pydantic\n\n# or\n\npython -m pip install stac-pydantic[\"validation\"]\n```\n\nFor local development:\n\n```shell\npython -m pip install -e '.[dev,lint]'\n```\n\n| stac-pydantic | STAC Version | STAC API Version | Pydantic Version |\n|--------------|---------------|------------------|-----------------|\n| 1.2.x         | 1.0.0-beta.1 | \u003c1* | ^1.6 |\n| 1.3.x         | 1.0.0-beta.2 | \u003c1* | ^1.6 |\n| 2.0.x         | 1.0.0        | \u003c1* | ^1.6 |\n| 3.0.x         | 1.0.0        | 1.0.0 | ^2.4 |\n| 3.1.x         | 1.0.0        | 1.0.0 | ^2.4 |\n\n\\* various beta releases, specs not fully implemented\n\n## Development\n\nInstall the [pre-commit](https://pre-commit.com/) hooks:\n\n```shell\npre-commit install\n```\n\n## Testing\n\nEnsure you have all Python versions installed that the tests will be run against. If using pyenv, run:\n\n```shell\npyenv install 3.8.18\npyenv install 3.9.18\npyenv install 3.10.13\npyenv install 3.11.5\npyenv local 3.8.18 3.9.18 3.10.13 3.11.5\n```\n\nRun the entire test suite:\n\n```shell\ntox\n```\n\nRun a single test case using the standard pytest convention:\n\n```shell\npython -m pytest -v tests/test_models.py::test_item_extensions\n```\n\n## Usage\n\n### Loading Models\n\nLoad data into models with standard pydantic:\n\n```python\nfrom stac_pydantic import Catalog\n\nstac_catalog = {\n  \"type\": \"Catalog\",\n  \"stac_version\": \"1.0.0\",\n  \"id\": \"sample\",\n  \"description\": \"This is a very basic sample catalog.\",\n  \"links\": [\n    {\n      \"href\": \"item.json\",\n      \"rel\": \"item\"\n    }\n  ]\n}\n\ncatalog = Catalog(**stac_catalog)\nassert catalog.id == \"sample\"\nassert catalog.links[0].href == \"item.json\"\n```\n\n### Extensions\n\nSTAC defines many extensions which let the user customize the data in their catalog. `stac-pydantic.extensions.validate_extensions` gets the JSON schemas from the URLs provided in the `stac_extensions` property (caching the last fetched ones), and will validate a `dict`, `Item`, `Collection` or `Catalog` against those fetched schemas:\n\n```python\nfrom stac_pydantic import Item\nfrom stac_pydantic.extensions import validate_extensions\n\nstac_item = {\n    \"id\": \"12345\",\n    \"type\": \"Feature\",\n    \"stac_extensions\": [\n        \"https://stac-extensions.github.io/eo/v1.0.0/schema.json\"\n    ],\n    \"geometry\": { \"type\": \"Point\", \"coordinates\": [0, 0] },\n    \"bbox\": [0.0, 0.0, 0.0, 0.0],\n    \"properties\": {\n        \"datetime\": \"2020-03-09T14:53:23.262208+00:00\",\n        \"eo:cloud_cover\": 25,\n    },\n    \"links\": [],\n    \"assets\": {},\n}\n\nmodel = Item(**stac_item)\nvalidate_extensions(model, reraise_exception=True)\nassert getattr(model.properties, \"eo:cloud_cover\") == 25\n```\n\nThe complete list of current STAC Extensions can be found [here](https://stac-extensions.github.io/).\n\n#### Vendor Extensions\n\nThe same procedure described above works for any STAC Extension schema as long as it can be loaded from a public url.\n\n### STAC API\n\nThe [STAC API Specs](https://github.com/radiantearth/stac-api-spec) extent the core STAC specification for implementing dynamic catalogs. STAC Objects used in an API context should always import models from the `api` subpackage. This package extends\nCatalog, Collection, and Item models with additional fields and validation rules and introduces Collections and ItemCollections models and Pagination/ Search Links.\nIt also implements models for defining ItemSeach queries.\n\n```python\nfrom stac_pydantic.api import Item, ItemCollection\n\nstac_item = Item(**{\n    \"id\": \"12345\",\n    \"type\": \"Feature\",\n    \"stac_extensions\": [],\n    \"geometry\": { \"type\": \"Point\", \"coordinates\": [0, 0] },\n    \"bbox\": [0.0, 0.0, 0.0, 0.0],\n    \"properties\": {\n        \"datetime\": \"2020-03-09T14:53:23.262208+00:00\",\n    },\n    \"collection\": \"CS3\",\n    \"links\": [\n          {\n            \"rel\": \"self\",\n            \"href\": \"http://stac.example.com/catalog/collections/CS3-20160503_132130_04/items/CS3-20160503_132130_04.json\"\n          },\n          {\n            \"rel\": \"collection\",\n            \"href\": \"http://stac.example.com/catalog/CS3-20160503_132130_04/catalog.json\"\n          },\n          {\n            \"rel\": \"root\",\n            \"href\": \"http://stac.example.com/catalog\"\n          }],\n    \"assets\": {},\n    })\n\nstac_item_collection = ItemCollection(**{\n    \"type\": \"FeatureCollection\",\n    \"features\": [stac_item],\n    \"links\": [\n          {\n            \"rel\": \"self\",\n            \"href\": \"http://stac.example.com/catalog/search?collection=CS3\",\n            \"type\": \"application/geo+json\"\n          },\n          {\n            \"rel\": \"root\",\n            \"href\": \"http://stac.example.com/catalog\",\n            \"type\": \"application/json\"\n          }],\n    })\n```\n\n### Exporting Models\n\nMost STAC extensions are namespaced with a colon (ex `eo:gsd`) to keep them distinct from other extensions.  Because\nPython doesn't support the use of colons in variable names, we use [Pydantic aliasing](https://pydantic-docs.helpmanual.io/usage/model_config/#alias-generator)\nto add the namespace upon model export.  This requires [exporting](https://pydantic-docs.helpmanual.io/usage/exporting_models/)\nthe model with the `by_alias = True` parameter. Export methods (`model_dump()` and `model_dump_json()`) for models in this library have `by_alias` and `exclude_unset` st to `True` by default:\n\n```python\nitem_dict = item.model_dump()\nassert item_dict['properties']['landsat:row'] == item.properties.row == 250\n```\n\n### CLI\n\n```text\nUsage: stac-pydantic [OPTIONS] COMMAND [ARGS]...\n\n  stac-pydantic cli group\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  validate-item  Validate STAC Item\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstac-utils%2Fstac-pydantic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstac-utils%2Fstac-pydantic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstac-utils%2Fstac-pydantic/lists"}