stac-validator documentation¶
stac-validator is a library and cli tool for validating SpatioTemporal Asset Catalogs (STAC). It is written in Python and can be used to validate STAC Items, Collections, and Catalogs.
stac-validator was first developed by Sparkgeo. It later received support from the Radiant Earth Foundation as part of the work done for stac-check, which uses the stac-validator library and adds linting functionality. The stac-validator CLI tool offers more validation options compared to stac-check. Recent development on stac-validator has been supported by Sparkgeo as well as other open-source contributors.
Installation¶
stac-validator can be installed from PyPI:
$ pip install stac-validator
CLI Usage¶
stac-validator can be used as a library or as a command line tool.
$ stac-validator --help
Usage: stac-validator [OPTIONS] STAC_FILE
The `stac-validator` command line tool. Validates a STAC
file against the STAC specification and prints the validation results to the
console.
Args:
stac_file (str): Path to the STAC file to be validated.
item_collection (bool): Whether to validate item collection responses.
pages (int): Maximum number of pages to validate via `item_collection`.
recursive (bool): Whether to recursively validate all related STAC objects.
max_depth (int): Maximum depth to traverse when recursing.
core (bool): Whether to validate core STAC objects only.
extensions (bool): Whether to validate extensions only.
links (bool): Whether to additionally validate links. Only works with default mode.
assets (bool): Whether to additionally validate assets. Only works with default mode.
custom (str): Path to a custom schema file to validate against.
verbose (bool): Whether to enable verbose output for recursive mode.
no_output (bool): Whether to print output to console.
log_file (str): Path to a log file to save full recursive output.
Returns:
None
Raises:
SystemExit: Exits the program with a status code of 0 if the STAC file is valid, or 1 if it is invalid.
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).
-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`.
--item-collection Validate item collection response. Can be combined with --pages. Defaults to one page.
-p, --pages INTEGER Maximum number of pages to validate via --item-collection. Defaults to one page.
-v, --verbose 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).
--version Show the version and exit.
--help Show this message and exit.
stac-validator can be used to validate local or remotely-hosted STAC objects. The tool will return a list of validation errors if the STAC object is invalid.
Library¶
stac-validator can be used as a library to validate STAC Items, Collections, and Catalogs.
It can be used with local or remotely-hosted STAC objects as well as STAC objects represented as a Python dictionary.
The library will return a list of validation errors if the STAC object is invalid.
Examples¶
python dictionary
from stac_validator import stac_validator
stac = stac_validator.StacValidate()
stac.validate_dict(dictionary)
print(stac.message)
python item-collection
from stac_validator import stac_validator
stac = stac_validator.StacValidate()
stac.validate_item_collection_dict(item_collection_dict)
print(stac.message)
Versions supported¶
stac-validator supports the following versions of the STAC specification:
[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]