stac-check

A linting and validation tool for STAC assets

The intent of this project is to provide a validation tool that also follows the official STAC Best Practices document

Documentation

The documentation is hosted on GitHub Pages at stac-utils.github.io/stac-check.

For development and building the documentation locally, see the Development section below.

Installation

Pip

$ pip install stac-check

For local development:

$ pip install -e '.[dev]'

Docker

$ make build
$ make shell

Usage

CLI Usage

Usage: stac-check [OPTIONS] FILE

Options:
  --version                Show the version and exit.
  -l, --links              Validate links for format and response.
  -a, --assets             Validate assets for format and response.
  -m, --max-depth INTEGER  Maximum depth to traverse when recursing. Omit this
                           argument to get full recursion. Ignored if
                           `recursive == False`.
  -r, --recursive          Recursively validate all related stac objects.
  --no-assets-urls         Disables the opening of href links when validating assets
                           (enabled by default).
  --header KEY VALUE       HTTP header to include in the requests. Can be used
                           multiple times.
  --pydantic               Use stac-pydantic for enhanced validation with Pydantic models.
  --verbose                Show verbose error messages.
  -o, --output FILE        Save output to the specified file.
  --item-collection        Validate item collection response. Can be combined with
                           --pages. Defaults to one page.
  --collections            Validate collections endpoint response. Can be combined with
                           --pages. Defaults to one page.
  -p, --pages INTEGER      Maximum number of pages to validate via --item-collection
                           or --collections. Defaults to one page.
  --help                   Show this message and exit.

Configuration

stac-check uses a configuration file to control which validation checks are performed. By default, it uses the built-in configuration at stac_check/stac-check.config.yml. You can customize the validation behavior by creating your own configuration file.

The configuration file has three main sections:

linting: Controls which general best practices checks are enabled
geometry_validation: Controls geometry-specific validation checks [BETA]
settings: Configures thresholds for certain checks

Here's an example of the configuration options:

linting:
  # Identifiers should consist of only lowercase characters, numbers, '_', and '-'
  searchable_identifiers: true
  # Item name '{self.object_id}' should not contain ':' or '/'
  percent_encoded: true
  # Item file names should match their ids
  item_id_file_name: true
  # Collections and catalogs should be named collection.json and catalog.json
  catalog_id_file_name: true
  # A STAC collection should contain a summaries field
  check_summaries: true
  # Datetime fields should not be set to null
  null_datetime: true
  # best practices - check unlocated items to make sure bbox field is not set
  check_unlocated: true
  # best practices - recommend items have a geometry
  check_geometry: true
  # check to see if there are too many links
  bloated_links: true
  # best practices - check for bloated metadata in properties
  bloated_metadata: true
  # best practices - ensure thumbnail is a small file size ["png", "jpeg", "jpg", "webp"]
  check_thumbnail: true
  # best practices - ensure that links in catalogs and collections include a title field
  links_title: true
  # best practices - ensure that links in catalogs and collections include self link
  links_self: true

geometry_validation:
  # Master switch to enable/disable all geometry validation checks
  enabled: true
  # check if geometry coordinates are potentially ordered incorrectly (longitude, latitude)
  geometry_coordinates_order: true
  # check if geometry coordinates contain definite errors (latitude > ±90°, longitude > ±180°)
  geometry_coordinates_definite_errors: true
  # check if bbox matches the bounds of the geometry
  bbox_geometry_match: true
  # check if a bbox that crosses the antimeridian is correctly formatted
  bbox_antimeridian: true

settings:
  # number of links before the bloated links warning is shown
  max_links: 20
  # number of properties before the bloated metadata warning is shown
  max_properties: 20

To use a custom configuration file, set the STAC_CHECK_CONFIG environment variable to the path of your configuration file:

export STAC_CHECK_CONFIG=/path/to/your/config.yml
stac-check sample_files/1.0.0/core-item.json

Geometry Validation

Geometry validation is a feature of stac-check that allows you to validate the geometry of your STAC items. This feature is enabled by default, but can be disabled by setting geometry_validation.enabled to false in your configuration file.

The geometry validation feature checks for the following:

Geometry coordinates are potentially ordered incorrectly (longitude, latitude)
Geometry coordinates contain definite errors (latitude > ±90°, longitude > ±180°)
Bbox matches the bounds of the geometry
Bbox that crosses the antimeridian is correctly formatted

You can customize the geometry validation behavior by setting the following options in your configuration file:

geometry_validation.geometry_coordinates_order: Check if geometry coordinates are potentially ordered incorrectly (longitude, latitude)
geometry_validation.geometry_coordinates_definite_errors: Check if geometry coordinates contain definite errors (latitude > ±90°, longitude > ±180°)
geometry_validation.bbox_geometry_match: Check if bbox matches the bounds of the geometry
geometry_validation.bbox_antimeridian: Check if a bbox that crosses the antimeridian is correctly formatted

Python API Usage

from stac_check.lint import Linter

linter = Linter('<json_path>')

for k, v in linter.create_best_practices_dict().items():
    print(k, ":", v)

Examples

Basic Validation

stac-check sample_files/0.9.0/landsat8-sample.json

stac-check: STAC spec validation and linting tool

Please upgrade from version 0.9.0 to version 1.1.0!

Validator: stac-validator 3.9.1

Valid ITEM: True

Schemas validated:
    https://cdn.staclint.com/v0.9.0/extension/eo.json
    https://cdn.staclint.com/v0.9.0/extension/view.json
    https://cdn.staclint.com/v0.9.0/item.json

STAC Best Practices:
    Item name 'LC81530252014153LGN00' should only contain Searchable identifiers
    Identifiers should consist of only lowercase characters, numbers, '_', and '-'
    https://github.com/radiantearth/stac-spec/blob/master/best-practices.md#searchable-identifiers

    Item file names should match their ids: 'landsat8-sample' not equal to 'LC81530252014153LGN00

    A link to 'self' in links is strongly recommended


This object has 4 links

Recursive Validation

stac-check https://raw.githubusercontent.com/stac-utils/pystac/main/tests/data-files/examples/0.9.0/collection-spec/examples/landsat-collection.json --recursive

stac-check: STAC spec validation and linting tool

Please upgrade from version 0.9.0 to version 1.1.0!

Validator: stac-validator 3.9.1


Recursive: Validate all assets in a collection or catalog
Max-depth = None
-------------------------
Asset 1 Validated: https://raw.githubusercontent.com/stac-utils/pystac/main/tests/data-files/examples/0.9.0/collection-spec/examples/landsat-collection.json

Valid COLLECTION: True

Schemas validated:
    https://cdn.staclint.com/v0.9.0/collection.json

STAC Best Practices:
    Object should be called 'collection.json' not 'landsat-collection.json'

    A STAC collection should contain a summaries field
    It is recommended to store information like eo:bands in summaries

    Links in catalogs and collections should always have a 'title' field

This object has 4 links

-------------------------
Asset 2 Validated: https://landsat-stac.s3.amazonaws.com/landsat-8-l1/paths/catalog.json

Valid: False
Schemas validated:
    https://cdn.staclint.com/v0.9.0/collection.json
Error Type: JSONDecodeError
Error Message: Expecting value: line 1 column 1 (char 0)
-------------------------

Asset Validation

stac-check sample_files/1.0.0/core-item.json --assets

stac-check: STAC spec validation and linting tool

Please upgrade from version 1.0.0 to version 1.1.0!

Validator: stac-validator 3.9.1

Valid ITEM: True

Schemas validated:
    https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json

STAC Best Practices:
    Item name '20201211_223832_CS2' should only contain Searchable identifiers
    Identifiers should consist of only lowercase characters, numbers, '_', and '-'
    https://github.com/radiantearth/stac-spec/blob/master/best-practices.md#searchable-identifiers

    Item file names should match their ids: 'core-item' not equal to '20201211_223832_CS2

    Please avoid setting the datetime field to null, many clients search on this field

    A link to 'self' in links is strongly recommended


No ASSET format errors!

ASSET request errors:
    http://cool-sat.com/catalog/20201211_223832_CS2/20201211_223832_CS2.EPH

This object has 4 links

Link and Asset Validation

stac-check sample_files/1.0.0/core-item-bad-links.json --links --assets

stac-check: STAC spec validation and linting tool

Please upgrade from version 1.0.0 to version 1.1.0!

Validator: stac-validator 3.9.1

Valid ITEM: True

Schemas validated:
    https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json

STAC Best Practices:
    Item name '20201211_223832_CS2' should only contain Searchable identifiers
    Identifiers should consist of only lowercase characters, numbers, '_', and '-'
    https://github.com/radiantearth/stac-spec/blob/master/best-practices.md#searchable-identifiers

    Item file names should match their ids: 'core-item-bad-links' not equal to '20201211_223832_CS2

    Please avoid setting the datetime field to null, many clients search on this field

    A link to 'self' in links is strongly recommended


ASSET format errors:
    https:/storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2.jpg

ASSET request errors:
    https:/storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2.jpg
    http://cool-sat.com/catalog/20201211_223832_CS2/20201211_223832_CS2.EPH

LINK format errors:
    http:/remotdata.io/catalog/20201211_223832_CS2/index.html

LINK request errors:
    http://catalog/collection.json
    http:/remotdata.io/catalog/20201211_223832_CS2/index.html

This object has 4 links

Invalid STAC

stac-check sample_files/0.9.0/bad-item.json

stac-check: STAC spec validation and linting tool

Please upgrade from version 0.9.0 to version 1.1.0!

Validator: stac-validator 3.9.1

Valid : False

Schemas validated:
    https://cdn.staclint.com/v0.9.0/item.json

STAC Best Practices:
    A link to 'self' in links is strongly recommended

Validation error type:
    ValidationError
Validation error message:
    'id' is a required property of the root of the STAC object

This object has 5 links

Using HTTP Headers

stac-check https://stac-catalog.eu/collections/sentinel-s2-l2a/items/item1 --assets --no-assets-urls --header x-api-key $MY_API_KEY --header foo bar

stac-check: STAC spec validation and linting tool

Please upgrade from version 1.0.0 to version 1.1.0!

Validator: stac-validator 3.9.1

Valid ITEM: True

Schemas validated: 
    https://stac-extensions.github.io/timestamps/v1.1.0/schema.json
    https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json

STAC Best Practices: 
    A STAC collection should contain a summaries field
    It is recommended to store information like eo:bands in summaries


No ASSET format errors!

This object has 4 links

STAC API Validation

stac-check can validate STAC API endpoints, including item collections and collections endpoints. It supports pagination and can validate multiple pages of results.

Validating an Item Collection Endpoint:

stac-check https://stac.geobon.org/collections/chelsa-clim/items --item-collection

stac-check: STAC spec validation and linting tool

Validator: stac-validator 3.9.1

Item Collection: Validate all assets in a feature collection
Pages = 1

Valid ITEM: True

Schemas validated:
    https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json

This object has 10 items

Validating Multiple Pages of an Item Collection:

stac-check https://stac.geobon.org/collections/chelsa-clim/items --item-collection --pages 3

stac-check: STAC spec validation and linting tool

Validator: stac-validator 3.9.1

Item Collection: Validate all assets in a feature collection
Pages = 3

Valid ITEM: True

Schemas validated:
    https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json

This object has 30 items

Validating a Collections Endpoint:

stac-check https://stac.geobon.org/collections --collections

stac-check: STAC spec validation and linting tool

Validator: stac-validator 3.9.1

Collections: Validate all collections in a STAC API
Pages = 1

Valid COLLECTION: True

Schemas validated:
    https://schemas.stacspec.org/v1.0.0/collection-spec/json-schema/collection.json

This object has 5 collections

Development

Building Documentation

Documentation is automatically built and published to GitHub Pages on every push to the main branch. You can view the latest version at stac-utils.github.io/stac-check.

To build the documentation locally (for development or testing), you'll need to install the development dependencies first:

# Install the package with documentation dependencies
pip install -e ".[docs]"

# Build the documentation
make docs

# Open the built documentation
xdg-open docs/_build/html/index.html  # On Linux
open docs/_build/html/index.html    # On macOS
start docs/_build/html/index.html   # On Windows

Or using Docker:

# Build the Docker image and documentation
make docker-docs

The documentation is built using Sphinx with the following extensions:

sphinx.ext.autodoc for API documentation
sphinx_click for CLI documentation
sphinx_rtd_theme for the ReadTheDocs theme
myst_parser for Markdown support

Sponsors and Supporters

The following organizations have contributed time and/or funding to support the development of this project:

We are grateful for the support of our sponsors who help make this project possible. If your organization uses stac-check and would like to become a sponsor, please reach out to us!

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

How to Contribute

Fork the repository - Create your own fork of the project
Create a feature branch - git checkout -b feature/your-feature-name
Commit your changes - Make sure to write clear, concise commit messages
Push to your branch - git push origin feature/your-feature-name
Open a Pull Request - Describe your changes in detail

Development Guidelines

Follow the existing code style
Add tests for new features
Update documentation as needed
Make sure all tests pass before submitting a PR

Reporting Issues

If you find a bug or have a feature request, please open an issue on the GitHub repository.

License

This project is licensed under the Apache License 2.0.

Name		Name	Last commit message	Last commit date
Latest commit History 621 Commits
.github/workflows		.github/workflows
assets		assets
docs		docs
sample_files		sample_files
stac_check		stac_check
tests		tests
.env-example		.env-example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.readthedocs.yml		.readthedocs.yml
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
Makefile		Makefile
README.md		README.md
best-practices.md		best-practices.md
conftest.py		conftest.py
setup.py		setup.py

Uh oh!

License

Uh oh!

stac-utils/stac-check

Folders and files

Latest commit

History

Repository files navigation

stac-check

A linting and validation tool for STAC assets

Table of Contents

Documentation

Installation

Pip

Docker

Usage

CLI Usage

Configuration

Geometry Validation

Python API Usage

Examples

Basic Validation

Recursive Validation

Asset Validation

Link and Asset Validation

Invalid STAC

Using HTTP Headers

STAC API Validation

Development

Building Documentation

Sponsors and Supporters

Contributing

How to Contribute

Development Guidelines

Reporting Issues

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 23

Packages 0

Uh oh!

Contributors 6

Languages

Packages