- Overview
- Documentation
- Requirements
- Installation
- Supported STAC Versions
- Usage
- Examples
- Deployment
- Testing
- Related Projects
- Sponsors and Supporters
- Contributing
- License
STAC Validator is a tool to validate STAC (SpatioTemporal Asset Catalog) json files against the official STAC specification. It provides both a command-line interface and a Python API for validating STAC objects.
For detailed documentation, please visit our GitHub Pages documentation site.
Validate STAC json files against the STAC spec.
$ stac-validator https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/extended-item.json[ { "version": "1.0.0", "path": "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/extended-item.json", "schema": [ "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/projection/v1.0.0/schema.json", "https://stac-extensions.github.io/scientific/v1.0.0/schema.json", "https://stac-extensions.github.io/view/v1.0.0/schema.json", "https://stac-extensions.github.io/remote-data/v1.0.0/schema.json", "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json" ], "valid_stac": true, "asset_type": "ITEM", "validation_method": "default" } ]- Python 3.8+
- Requests
- Click
- Jsonschema
Note: Stac-validator is also used in stac-check which adds linting messages based on the official STAC best practices document.
https://github.com/stac-utils/stac-check
$ pip install stac-validator$ pip install .or for local development
$ pip install -e '.[dev]'The Makefile has convenience commands if Make is installed.
$ make help| STAC |
|---|
| 0.8.0 |
| 0.8.1 |
| 0.9.0 |
| 1.0.0-beta.1 |
| 1.0.0-beta.2 |
| 1.0.0-rc.1 |
| 1.0.0-rc.2 |
| 1.0.0-rc.3 |
| 1.0.0-rc.4 |
| 1.0.0 |
| 1.1.0-beta.1 |
| 1.1.0 |
Basic Usage
$ stac-validator --helpUsage: stac-validator [OPTIONS] STAC_FILE Options: --core Validate core stac object only without extensions. --extensions Validate extensions only. --links Additionally validate links. Only works with default mode. --assets Additionally validate assets. Only works with default mode. -c, --custom TEXT Validate against a custom schema (local filepath or remote schema). -s, --schema-map <TEXT TEXT>... Schema path to replaced by (local) schema path during validation. Can be used multiple times. -r, --recursive Recursively validate all related stac objects. -m, --max-depth INTEGER Maximum depth to traverse when recursing. Omit this argument to get full recursion. Ignored if `recursive == False`. --collections Validate /collections response. --item-collection Validate item collection response. Can be combined with --pages. Defaults to one page. --no-assets-urls Disables the opening of href links when validating assets (enabled by default). --header <TEXT TEXT>... HTTP header to include in the requests. Can be used multiple times. -p, --pages INTEGER Maximum number of pages to validate via --item-collection. Defaults to one page. -t, --trace-recursion Enables verbose output for recursive mode. --no_output Do not print output to console. --log_file TEXT Save full recursive output to log file (local filepath). --pydantic Validate using stac-pydantic models for enhanced type checking and validation. --schema-config TEXT Path to a YAML or JSON schema config file. --verbose Enable verbose output. This will output additional information during validation. --help Show this message and exit.Remote source
from stac_validator import stac_validator stac = stac_validator.StacValidate("https://raw.githubusercontent.com/stac-utils/pystac/main/tests/data-files/examples/0.9.0/collection-spec/examples/landsat-collection.json") stac.run() print(stac.message)[ { "version": "0.9.0", "path": "https://raw.githubusercontent.com/stac-utils/pystac/main/tests/data-files/examples/0.9.0/collection-spec/examples/landsat-collection.json", "schema": [ "https://cdn.staclint.com/v0.9.0/collection.json" ], "valid_stac": true, "asset_type": "COLLECTION", "validation_method": "default" } ]Local file
from stac_validator import stac_validator stac = stac_validator.StacValidate("tests/test_data/1beta1/sentinel2.json", extensions=True) stac.run() print(stac.message)[ { "version": "1.0.0-beta.1", "path": "tests/test_data/1beta1/sentinel2.json", "schema": [ "https://cdn.staclint.com/v1.0.0-beta.1/collection.json" ], "valid_stac": true, "asset_type": "COLLECTION", "validation_method": "extensions" } ]Dictionary
from stac_validator import stac_validator stac = stac_validator.StacValidate() stac.validate_dict(dictionary) print(stac.message)Item Collection
from stac_validator import stac_validator stac = stac_validator.StacValidate() stac.validate_item_collection_dict(item_collection_dict) print(stac.message)The validator can run using docker containers.
$ docker build -t stac-validator . $ docker run stac-validator https://raw.githubusercontent.com/stac-extensions/projection/main/examples/item.json[ { "version": "1.0.0", "path": "https://raw.githubusercontent.com/stac-extensions/projection/main/examples/item.json", "schema": [ "https://stac-extensions.github.io/projection/v1.0.0/schema.json", "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json" ], "valid_stac": true, "asset_type": "ITEM", "validation_method": "default" } ]An example AWS CDK deployment is available in cdk-deployment
$ cd cdk-deployment $ cdk diff$ make test # or $ pytest -vSee the tests files for examples on different usages.
$ stac-validator https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/extended-item.json --core[ { "version": "1.0.0", "path": "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/extended-item.json", "schema": [ "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json" ], "valid_stac": true, "asset_type": "ITEM", "validation_method": "core" } ]$ stac-validator https://radarstac.s3.amazonaws.com/stac/catalog.json --custom https://cdn.staclint.com/v0.7.0/catalog.json[ { "version": "0.7.0", "path": "https://radarstac.s3.amazonaws.com/stac/catalog.json", "schema": [ "https://cdn.staclint.com/v0.7.0/catalog.json" ], "asset_type": "CATALOG", "validation_method": "custom", "valid_stac": true } ]$ stac-validator https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/extended-item.json --extensions[ { "version": "1.0.0", "path": "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/extended-item.json", "schema": [ "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/projection/v1.0.0/schema.json", "https://stac-extensions.github.io/scientific/v1.0.0/schema.json", "https://stac-extensions.github.io/view/v1.0.0/schema.json", "https://stac-extensions.github.io/remote-data/v1.0.0/schema.json" ], "valid_stac": true, "asset_type": "ITEM", "validation_method": "extensions" } ]$ stac-validator https://spot-canada-ortho.s3.amazonaws.com/catalog.json --recursive --max-depth 1 --trace-recursion[ { "version": "0.8.1", "path": "https://canada-spot-ortho.s3.amazonaws.com/canada_spot_orthoimages/canada_spot4_orthoimages/collection.json", "schema": "https://cdn.staclint.com/v0.8.1/collection.json", "asset_type": "COLLECTION", "validation_method": "recursive", "valid_stac": true }, { "version": "0.8.1", "path": "https://canada-spot-ortho.s3.amazonaws.com/canada_spot_orthoimages/canada_spot5_orthoimages/collection.json", "schema": "https://cdn.staclint.com/v0.8.1/collection.json", "asset_type": "COLLECTION", "validation_method": "recursive", "valid_stac": true }, { "version": "0.8.1", "path": "https://spot-canada-ortho.s3.amazonaws.com/catalog.json", "schema": "https://cdn.staclint.com/v0.8.1/catalog.json", "asset_type": "CATALOG", "validation_method": "recursive", "valid_stac": true } ]$ stac-validator https://earth-search.aws.element84.com/v0/collections/sentinel-s2-l2a/items --item-collection --pages 2$ stac-validator https://stac-catalog.eu/collections/sentinel-s2-l2a/items --header x-api-key $MY_API_KEY --header foo barSchema map allows stac-validator to replace a schema in a STAC json by a schema from another URL or local schema file. This is especially useful when developing a schema and testing validation against your local copy of the schema.
$ stac-validator https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0/examples/extended-item.json --extensions --schema-map https://stac-extensions.github.io/projection/v1.0.0/schema.json "tests/test_data/schema/v1.0.0/projection.json"[ { "version": "1.0.0", "path": "https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0/examples/extended-item.json", "schema": [ "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "tests/test_data/schema/v1.0.0/projection.json", "https://stac-extensions.github.io/scientific/v1.0.0/schema.json", "https://stac-extensions.github.io/view/v1.0.0/schema.json", "https://stac-extensions.github.io/remote-data/v1.0.0/schema.json" ], "valid_stac": true, "asset_type": "ITEM", "validation_method": "extensions" } ]This option is also capable of replacing URLs to subschemas:
$ stac-validator tests/test_data/v100/extended-item-local.json --custom tests/test_data/schema/v1.0.0/item_with_unreachable_url.json --schema-map https://geojson-wrong-url.org/schema/Feature.json https://geojson.org/schema/Feature.json --schema-map https://geojson-wrong-url.org/schema/Geometry.json https://geojson.org/schema/Geometry.json[ { "version": "1.0.0", "path": "tests/test_data/v100/extended-item-local.json", "schema": [ "tests/test_data/schema/v1.0.0/item_with_unreachable_url.json" ], "valid_stac": true, "asset_type": "ITEM", "validation_method": "custom" } ]The --schema-config option allows you to specify a YAML or JSON configuration file that maps remote schema URLs to local file paths. This is useful when you need to validate against multiple local schemas and want to avoid using multiple --schema-map arguments.
Example schema config file (YAML):
schemas: "https://schemas.stacspec.org/v1.0.0/collection-spec/json-schema/collection.json": "local_schemas/v1.0.0/collection.json" "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json": "local_schemas/v1.0.0/item.json" "https://stac-extensions.github.io/eo/v1.0.0/schema.json": "local_schemas/v1.0.0/eo.json"Usage:
$ stac-validator https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0/examples/extended-item.json --schema-config path/to/schema_config.yamlThe paths in the config file can be absolute or relative to the config file's location.
The --pydantic option provides enhanced validation using stac-pydantic models, which offer stronger type checking and more detailed error messages. To use this feature, you need to install the optional dependency:
$ pip install stac-validator[pydantic]Then you can validate your STAC objects using Pydantic models:
$ stac-validator https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/extended-item.json --pydantic[ { "version": "1.0.0", "path": "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/extended-item.json", "schema": [ "stac-pydantic Item model" ], "valid_stac": true, "asset_type": "ITEM", "validation_method": "pydantic", "extension_schemas": [ "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/projection/v1.0.0/schema.json", "https://stac-extensions.github.io/scientific/v1.0.0/schema.json", "https://stac-extensions.github.io/view/v1.0.0/schema.json", "https://stac-extensions.github.io/remote-data/v1.0.0/schema.json" ], "model_validation": "passed" } ]The following organizations have contributed time and/or funding to support the development of this project:
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the Apache License 2.0.