{"id":13735287,"url":"https://github.com/stac-utils/stac-api-validator","last_synced_at":"2025-08-17T21:33:48.376Z","repository":{"id":37477740,"uuid":"368986042","full_name":"stac-utils/stac-api-validator","owner":"stac-utils","description":"A STAC API validation client","archived":false,"fork":false,"pushed_at":"2025-04-29T12:19:39.000Z","size":2712,"stargazers_count":21,"open_issues_count":32,"forks_count":7,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-29T13:34:55.308Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stac-utils.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-05-19T19:54:36.000Z","updated_at":"2025-04-29T12:19:44.000Z","dependencies_parsed_at":"2023-11-29T04:40:00.373Z","dependency_job_id":"7f996cef-7e6a-4235-8b27-3ea86cc304d3","html_url":"https://github.com/stac-utils/stac-api-validator","commit_stats":{"total_commits":227,"total_committers":9,"mean_commits":25.22222222222222,"dds":0.5506607929515419,"last_synced_commit":"7d661398fa4c59cb2cb057a3dec3773c272b0f69"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-api-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-api-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-api-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-api-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stac-utils","download_url":"https://codeload.github.com/stac-utils/stac-api-validator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253059270,"owners_count":21847246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T03:01:05.105Z","updated_at":"2025-08-17T21:33:48.357Z","avatar_url":"https://github.com/stac-utils.png","language":"Python","funding_links":[],"categories":["`Python` processing of optical imagery (non deep learning)"],"sub_categories":["Cloud Native Geospatial"],"readme":"# STAC API Validator\n\n[![PyPI](https://img.shields.io/pypi/v/stac-api-validator.svg)][pypi_]\n[![Status](https://img.shields.io/pypi/status/stac-api-validator.svg)][status]\n[![Python Version](https://img.shields.io/pypi/pyversions/stac-api-validator)][python version]\n[![License](https://img.shields.io/pypi/l/stac-api-validator)][license]\n\n[![Read the documentation at https://stac-api-validator.readthedocs.io/](https://img.shields.io/readthedocs/stac-api-validator/latest.svg?label=Read%20the%20Docs)][read the docs]\n[![Tests](https://github.com/stac-utils/stac-api-validator/workflows/Tests/badge.svg)][tests]\n[![Codecov](https://codecov.io/gh/stac-utils/stac-api-validator/branch/main/graph/badge.svg)][codecov]\n\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white)][pre-commit]\n[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)][black]\n\n[pypi_]: https://pypi.org/project/stac-api-validator/\n[status]: https://pypi.org/project/stac-api-validator/\n[python version]: https://pypi.org/project/stac-api-validator\n[read the docs]: https://stac-api-validator.readthedocs.io/en/latest\n[tests]: https://github.com/stac-utils/stac-api-validator/actions?workflow=Tests\n[codecov]: https://app.codecov.io/gh/stac-utils/stac-api-validator\n[pre-commit]: https://github.com/pre-commit/pre-commit\n[black]: https://github.com/psf/black\n\n## Introduction\n\nThe STAC API Validator is the official validation suite for the\n[STAC API](https://github.com/radiantearth/stac-api-spec/) family of specifications.\n\n## Documentation\n\nSee the [stable](https://stac-api-validator.readthedocs.io/en/stable/) or\n[latest](https://stac-api-validator.readthedocs.io/en/latest) documentation pages.\n\n## Installation\n\nSTAC API Validator requires Python 3.11.\n\nYou can install _STAC API Validator_ via [pip] from [PyPI]:\n\n```console\npip install stac-api-validator\n```\n\nand then run it:\n\n```console\nstac-api-validator \\\n    --root-url https://planetarycomputer.microsoft.com/api/stac/v1/ \\\n    --conformance core \\\n    --conformance features \\\n    --conformance item-search \\\n    --collection sentinel-2-l2a \\\n    --geometry '{\"type\": \"Polygon\", \"coordinates\": [[[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]]]}'\n```\n\n## Contributing\n\nContributions are very welcome.\nTo learn more, see the [Contributor Guide].\n\n## Usage\n\nPlease see the [Command-line Reference] for details.\n\nThe conformance class validations to run are selected with the `--conformance` parameters. This parameter\ncan be used more than once to specify multiple conformance classes to validate. The `STAC API - Core` conformance\nclass will always be validated, even if not specified.\n\nIf `item-search`, `collections`, and/or `features` are specified, the `--collection` parameter must also\nbe set. It specifies the name of a collection to use for some of the validations.\nThe `--geometry` parameter should also be set to perform intersection tests.\nIt should specify an AOI over which there are between 100 and 20,000 results for the collection (more\nresults means longer time to run).\n\n## Features\n\n**Work in Progress** -- this currently only validates a subset of behavior\n\nThis validation suite focuses on validating STAC API interactions. Tools such as\n[pystac](https://github.com/stac-utils/pystac) and [stac4s](https://github.com/azavea/stac4s) do a\ngood job of validating STAC objects (Catalog, Collection, Item). This suite focuses on the STAC API behavior\nvalidation.\n\nThe three key concepts within a STAC API are:\n\n1. _Conformance classes_ advertising the capabilities of the API\n2. _Link relations_ between resources within the web API (hypermedia)\n3. _Parameters_ that filter search results\n\nThe conformance classes, as defined in the `conformsTo` field of the Landing Page (root, `/`), advertise to\nclients which capabilities are available in the API. Without this field, a client would not even be able to tell that a\nroot URI was a STAC API.\n\nThe 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.\n\nThe parameters that filter results apply to the Items resource and Item Search endpoints.\n\nThe current validity status of several popular STAC API implementations can be found [here](COMPLIANCE_REPORT.md).\n\n## Command-line Reference\n\nUsage:\n\n```text\nUsage: stac-api-validator [OPTIONS]\n\n  STAC API Validator.\n\nOptions:\n  --version                       Show the version and exit.\n  --log-level TEXT                Logging level, one of DEBUG, INFO, WARN,\n                                  ERROR, CRITICAL\n  --root-url TEXT                 STAC API Root / Landing Page URL  [required]\n  --collection TEXT               The name of the collection to use for item-\n                                  search, collections, and features tests.\n  --geometry TEXT                 The GeoJSON geometry to use for intersection\n                                  tests.\n  --conformance [core|browseable|item-search|features|collections|children|filter]\n                                  The conformance classes to validate.\n                                  [required]\n  --auth-bearer-token TEXT        Authorization Bearer token value to append\n                                  to all requests.\n  --auth-query-parameter TEXT     Query parameter key and value to pass for\n                                  authorization, e.g., 'key=xyz'.\n  --help                          Show this message and exit.\n```\n\nConformance classes item-search, features, and collections require the `--collection` parameter with the id of a\ncollection to run some tests on.\n\nConformance class `item-search` supports `--geometry` with a GeoJSON geometry that returns some items for\nthe specified collection.\n\nExample:\n\n```shell\nstac-api-validator \\\n    --root-url https://planetarycomputer.microsoft.com/api/stac/v1/ \\\n    --conformance core \\\n    --conformance item-search \\\n    --conformance features \\\n    --collection sentinel-2-l2a \\\n    --geometry '{\"type\": \"Polygon\", \"coordinates\": [[[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]]]}'\n```\n\nExample output:\n\n```text\nValidating https://cmr.earthdata.nasa.gov/stac/LARC_ASDC ...\nSTAC API - Core conformance class found.\nSTAC API - Item Search conformance class found.\nwarnings: none\nerrors:\n- 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'\n- service-desc (https://api.stacspec.org/v1.0.0-beta.1/openapi.yaml): should return JSON, instead got non-JSON text\n- GET Search with bbox=100.0, 0.0, 105.0, 1.0 returned status code 400\n- POST Search with bbox:[100.0, 0.0, 105.0, 1.0] returned status code 502\n- GET Search with bbox=100.0,0.0,0.0,105.0,1.0,1.0 returned status code 400\n- POST Search with bbox:[100.0, 0.0, 0.0, 105.0, 1.0, 1.0] returned status code 400\n```\n\nExample with authorization using parameters:\n\n```shell\nstac-api-validator --root-url https://api.radiant.earth/mlhub/v1 --conformance core --auth-query-parameter 'key=xxx'\n```\n\n## Validating OGC API Features - Part 1 compliance\n\nA STAC API that conforms to the \"STAC API - Features\" conformance class will also be a valid implementation\nof OGC API Features - Part 1. In general, this validator focuses on those aspects of API behavior that are\ndifferent between STAC and OGC. It is recommended that implementers also use the [OGC API Features - Part 1\nvalidation test suite](https://cite.opengeospatial.org/teamengine/about/ogcapi-features-1.0/1.0/site/) to\nvalidate conformance.\n\nFull instructions are available at the link above, but the simplest way to run this is with:\n\n```shell\ndocker run -p 8081:8080 ogccite/ets-ogcapi-features10\n```\n\nThen, open [http://localhost:8081/teamengine/](http://localhost:8081/teamengine/) and login with the\nusername 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`.\n\n## Common Mistakes\n\n- 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.\n- OGC API Features uses `data` relation link relation at the root to point to the Collections endpoint (`/collections`), not `collections` relation\n- 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`)\n- 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`\n\n## License\n\nDistributed under the terms of the [Apache 2.0 license][license],\n_STAC API Validator_ is free and open source software.\n\n## Issues\n\nIf you encounter any problems,\nplease [file an issue] along with a detailed description.\n\n## Credits\n\nThis project was generated from [@cjolowicz]'s [Hypermodern Python Cookiecutter] template.\n\n[@cjolowicz]: https://github.com/cjolowicz\n[pypi]: https://pypi.org/\n[hypermodern python cookiecutter]: https://github.com/cjolowicz/cookiecutter-hypermodern-python\n[file an issue]: https://github.com/stac-utils/stac-api-validator/issues\n[pip]: https://pip.pypa.io/\n\n\u003c!-- github-only --\u003e\n\n[license]: https://github.com/stac-utils/stac-api-validator/blob/main/LICENSE\n[contributor guide]: https://github.com/stac-utils/stac-api-validator/blob/main/CONTRIBUTING.md\n[command-line reference]: https://stac-api-validator.readthedocs.io/en/latest/usage.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstac-utils%2Fstac-api-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstac-utils%2Fstac-api-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstac-utils%2Fstac-api-validator/lists"}