Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/stac-utils/stac-api-validator
A STAC API validation client
https://github.com/stac-utils/stac-api-validator
Last synced: 3 months ago
JSON representation
A STAC API validation client
- Host: GitHub
- URL: https://github.com/stac-utils/stac-api-validator
- Owner: stac-utils
- License: other
- Created: 2021-05-19T19:54:36.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-06-17T12:59:28.000Z (5 months ago)
- Last Synced: 2024-07-01T06:14:22.515Z (4 months ago)
- Language: Python
- Homepage:
- Size: 949 KB
- Stars: 17
- Watchers: 6
- Forks: 8
- Open Issues: 34
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-earthobservation-code - stac-api-validator - A STAC API validation client `Python` (`Python` processing of optical imagery (non deep learning) / Cloud Native Geospatial)
README
# STAC API Validator
[][pypi_]
[][status]
[][python version]
[][license]
[][read the docs]
[][tests]
[][codecov]
[][pre-commit]
[][black]
[pypi_]: https://pypi.org/project/stac-api-validator/
[status]: https://pypi.org/project/stac-api-validator/
[python version]: https://pypi.org/project/stac-api-validator
[read the docs]: https://stac-api-validator.readthedocs.io/en/latest
[tests]: https://github.com/stac-utils/stac-api-validator/actions?workflow=Tests
[codecov]: https://app.codecov.io/gh/stac-utils/stac-api-validator
[pre-commit]: https://github.com/pre-commit/pre-commit
[black]: https://github.com/psf/black
## Introduction
The STAC API Validator is the official validation suite for the
[STAC API](https://github.com/radiantearth/stac-api-spec/) family of specifications.
## Documentation
See the [stable](https://stac-api-validator.readthedocs.io/en/stable/) or
[latest](https://stac-api-validator.readthedocs.io/en/latest) documentation pages.
## Installation
STAC API Validator requires Python 3.10.
You can install _STAC API Validator_ via [pip] from [PyPI]:
```console
pip install stac-api-validator
```
and then run it:
```console
stac-api-validator \
--root-url https://planetarycomputer.microsoft.com/api/stac/v1/ \
--conformance core \
--conformance features \
--conformance item-search \
--collection sentinel-2-l2a \
--geometry '{"type": "Polygon", "coordinates": [[[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]]]}'
```
## Contributing
Contributions are very welcome.
To learn more, see the [Contributor Guide].
## Usage
Please see the [Command-line Reference] for details.
The conformance class validations to run are selected with the `--conformance` parameters. This parameter
can be used more than once to specify multiple conformance classes to validate. The `STAC API - Core` conformance
class will always be validated, even if not specified.
If `item-search`, `collections`, and/or `features` are specified, the `--collection` and `--geometry` parameters must also
be specified. The `--collection` parameter specifies the name of a collection to use for some of the validations.
The `--geometry` should specify an AOI over which there are between 100 and 20,000 results for the collection (more
results means longer time to run).
## Features
**Work in Progress** -- this currently only validates a subset of behavior
This validation suite focuses on validating STAC API interactions. Tools such as
[pystac](https://github.com/stac-utils/pystac) and [stac4s](https://github.com/azavea/stac4s) do a
good job of validating STAC objects (Catalog, Collection, Item). This suite focuses on the STAC API behavior
validation.
The three key concepts within a STAC API are:
1. _Conformance classes_ advertising the capabilities of the API
2. _Link relations_ between resources within the web API (hypermedia)
3. _Parameters_ that filter search results
The conformance classes, as defined in the `conformsTo` field of the Landing Page (root, `/`), advertise to
clients which capabilities are available in the API. Without this field, a client would not even be able to tell that a
root URI was a STAC API.
The link relations define how to navigate a STAC catalog through parent-child links and find resources such as the OpenAPI specification. While many OGC API and STAC API endpoint have a fixed value (e.g., `/collections`), it is preferable for clients discover the paths via hypermedia.
The parameters that filter results apply to the Items resource and Item Search endpoints.
The current validity status of several popular STAC API implementations can be found [here](COMPLIANCE_REPORT.md).
## Command-line Reference
Usage:
```
Usage: stac-api-validator [OPTIONS]
STAC API Validator.
Options:
--version Show the version and exit.
--log-level TEXT Logging level, one of DEBUG, INFO, WARN,
ERROR, CRITICAL
--root-url TEXT STAC API Root / Landing Page URL [required]
--collection TEXT The name of the collection to use for item-
search, collections, and features tests.
--geometry TEXT The GeoJSON geometry to use for intersection
tests.
--conformance [core|browseable|item-search|features|collections|children|filter]
The conformance classes to validate.
[required]
--auth-bearer-token TEXT Authorization Bearer token value to append
to all requests.
--auth-query-parameter TEXT Query pararmeter key and value to pass for
authorization, e.g., 'key=xyz'.
--help Show this message and exit.
```
Conformance classes item-search, features, and collections require the `--collection` parameter with the id of a
collection to run some tests on.
Conformance class `item-search` requires `--geometry` with a GeoJSON geometry that returns some items for
the specified collection.
Example:
```
stac-api-validator \
--root-url https://planetarycomputer.microsoft.com/api/stac/v1/ \
--conformance core \
--conformance item-search \
--conformance features \
--collection sentinel-2-l2a \
--geometry '{"type": "Polygon", "coordinates": [[[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]]]}'
```
Example output:
```
Validating https://cmr.earthdata.nasa.gov/stac/LARC_ASDC ...
STAC API - Core conformance class found.
STAC API - Item Search conformance class found.
warnings: none
errors:
- service-desc (https://api.stacspec.org/v1.0.0-beta.1/openapi.yaml): should have content-type header 'application/vnd.oai.openapi+json;version=3.0'', actually 'text/yaml'
- service-desc (https://api.stacspec.org/v1.0.0-beta.1/openapi.yaml): should return JSON, instead got non-JSON text
- GET Search with bbox=100.0, 0.0, 105.0, 1.0 returned status code 400
- POST Search with bbox:[100.0, 0.0, 105.0, 1.0] returned status code 502
- GET Search with bbox=100.0,0.0,0.0,105.0,1.0,1.0 returned status code 400
- POST Search with bbox:[100.0, 0.0, 0.0, 105.0, 1.0, 1.0] returned status code 400
```
Example with authorization using parameters:
```
stac-api-validator --root-url https://api.radiant.earth/mlhub/v1 --conformance core --auth-query-parameter 'key=xxx'
```
## Validating OGC API Features - Part 1 compliance
A STAC API that conforms to the "STAC API - Features" conformance class will also be a valid implementation
of OGC API Features - Part 1. In general, this validator focuses on those aspects of API behavior that are
different between STAC and OGC. It is recommended that implementers also use the [OGC API Features - Part 1
validation test suite](https://cite.opengeospatial.org/teamengine/about/ogcapi-features-1.0/1.0/site/) to
validate conformance.
Full instructions are available at the link above, but the simplest way to run this is with:
```
docker run -p 8081:8080 ogccite/ets-ogcapi-features10
```
Then, open [http://localhost:8081/teamengine/](http://localhost:8081/teamengine/) and login with the
username and password `ogctest`, `Create a new session`, with Organization `OGC`, Specification `OGC API - Features`, `Start a new test session`, input he root URL for the service, and `Start`.
## Common Mistakes
- incorrect `conformsTo` in the Landing Page. This was added between STAC API 0.9 and 1.0. It should be the same as the value in the `conformsTo` in the OAFeat `/conformance` endpoint.
- OGC API Features uses `data` relation link relation at the root to point to the Collections endpoint (`/collections`), not `collections` relation
- media type for link relation `service-desc` and endpoint is `application/vnd.oai.openapi+json;version=3.0` (not `application/json`) and link relation `search` and endpoint is `application/geo+json` (not `application/json`)
- Use of OCG API "req" urls instead of "conf" urls, e.g. `http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core` should be used, not `http://www.opengis.net/spec/ogcapi-features-1/1.0/req/core`
## License
Distributed under the terms of the [Apache 2.0 license][license],
_STAC API Validator_ is free and open source software.
## Issues
If you encounter any problems,
please [file an issue] along with a detailed description.
## Credits
This project was generated from [@cjolowicz]'s [Hypermodern Python Cookiecutter] template.
[@cjolowicz]: https://github.com/cjolowicz
[pypi]: https://pypi.org/
[hypermodern python cookiecutter]: https://github.com/cjolowicz/cookiecutter-hypermodern-python
[file an issue]: https://github.com/stac-utils/stac-api-validator/issues
[pip]: https://pip.pypa.io/
[license]: https://github.com/stac-utils/stac-api-validator/blob/main/LICENSE
[contributor guide]: https://github.com/stac-utils/stac-api-validator/blob/main/CONTRIBUTING.md
[command-line reference]: https://stac-api-validator.readthedocs.io/en/latest/usage.html