`stac-check` documentation

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

Table of Contents

Documentation

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

Building Documentation Locally

To build the documentation locally:

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

# Build the documentation
make docs

The built documentation will be available in the docs/_build/html directory.

Alternatively, you can build the documentation using Docker:

# Build the Docker image and documentation
make docker-docs

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

Create local docs in the /docs folder:

$ pdoc --output-dir pdoc ./stac_check

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.

For more detailed documentation, please see the following pages:

Contents:

stac-check documentation