STAC API Validator

Introduction

The STAC API Validator is the official validation suite for the STAC API family of specifications.

Documentation

See the stable or latest documentation pages.

Installation

STAC API Validator requires Python 3.10.

You can install STAC API Validator via pip from PyPI:

pip install stac-api-validator

and then run it:

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 and 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.

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 parameter 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 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/ 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, 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.