# stac-check
stac-check: STAC spec validation and linting tool
Please upgrade from version 0.9.0 to version 1.1.0!
Validator: stac-validator 4.2.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
```bash
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 4.2.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
```bash
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 4.2.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
```bash
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 4.2.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
```bash
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 4.2.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
```bash
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 4.2.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
### Fast Validation
For large STAC collections or when you need maximum validation speed, use the `--fast` or `--fast-linting` flags to enable FastJSONSchema validation. Both modes skip geometry checks for maximum performance.
**Two Fast Validation Modes:**
- **`--fast`**: Fastest mode - skips geometry checks and best practices linting, focuses only on STAC spec compliance
- **`--fast-linting`**: Fast mode with linting - skips geometry checks but includes best practices checks for code quality
**Fast Validation (Spec Only) of a Large Item Collection:**
```bash
stac-check large_collection.json --fast
```
stac-check: STAC spec validation and linting tool
Validator: stac-valid 4.2.1
Validation method: FastJSONSchema
Validation Summary
✅ Passed: 998/1000
❌ Failed: 2/1000
⚡ Timing Information:
Total Validation Time: 245.67 ms
Average per Object: 0.246 ms
Schemas checked:
https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json
https://stac-extensions.github.io/eo/v1.0.0/schema.json
https://stac-extensions.github.io/projection/v1.0.0/schema.json
Validation Errors
❌ STAC Spec Violation: Missing {'rel': 'collection'} in links array.
Affected Items: 2 | Examples: item_1, item_2
**Fast Validation with Best Practices Linting:**
Use `--fast-linting` to include best practices checks while maintaining fast performance:
```bash
stac-check large_collection.json --fast-linting
```
This will show both validation errors and best practices warnings in a compact, grouped format.
**Performance Comparison:**
- **`--fast` mode**: ~0.25ms per item (spec compliance only)
- **`--fast-linting` mode**: ~0.5ms per item (spec + best practices)
- **Regular mode**: ~1-2ms per item (includes geometry checks)
- **Speedup**: 4-8x faster for large collections with `--fast`
Use `--fast` when:
- Validating large collections (100+ items)
- You only need STAC spec compliance
- You want maximum validation speed
Use `--fast-linting` when:
- Validating large collections with best practices checks
- You want to ensure code quality without geometry validation
- You need a balance between speed and thoroughness
- Performance is critical
### 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:**
```bash
stac-check https://stac.geobon.org/collections/chelsa-clim/items --item-collection
```
stac-check: STAC spec validation and linting tool
Validator: stac-validator 4.2.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:**
```bash
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 4.2.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:**
```bash
stac-check https://stac.geobon.org/collections --collections
```
stac-check: STAC spec validation and linting tool
Validator: stac-validator 4.2.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](https://stac-utils.github.io/stac-check/).
To build the documentation locally (for development or testing), you'll need to install the development dependencies first:
```bash
# 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:
```bash
# 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:
- [Healy Hyperspatial](https://healy-hyperspatial.github.io/)
- [Radiant Earth Foundation](https://radiant.earth/)
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
1. **Fork the repository** - Create your own fork of the project
2. **Create a feature branch** - `git checkout -b feature/your-feature-name`
3. **Commit your changes** - Make sure to write clear, concise commit messages
4. **Push to your branch** - `git push origin feature/your-feature-name`
5. **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](https://github.com/stac-utils/stac-check/issues).
## License
This project is licensed under the Apache License 2.0.