Skip to content

Validate STAC

Check your STAC metadata before publishing. Give the endpoint the URL of your catalog, collection, or item — it reads it, follows the links to everything inside, and tells you what would block publication on EDITO.

Endpoint

POST /v1/stac/validations

Authentication: Authorization: Bearer <access_token>.

Usage

For catalogs large enough to risk gateway timeouts, run the same validation as a background EPT job runner run and poll for the result instead of holding the request open.

curl -X POST "${EPT_API_URL}/v1/stac/validations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d '{"stac_url": "'$STAC_URL'"}' | jq . > catalog-1-validation-results.json

Python (httpx)

import json
import os

import httpx

response = httpx.post(
    f"{os.environ['EPT_API_URL']}/v1/stac/validations",
    headers={"Authorization": f"Bearer {os.environ['ACCESS_TOKEN']}"},
    json={
        "stac_url": "https://minio.dive.edito.eu/oidc-myusername/project-id/catalog-1/catalog.json"
    },
    timeout=120.0,
)
response.raise_for_status()

with open("catalog-1-validation-results.json", "w") as f:
    json.dump(response.json(), f, indent=4)

Request

The only field you need is stac_url:

{
  "stac_url": "https://minio.dive.edito.eu/oidc-myusername/project-id/catalog-1/catalog.json"
}

Three optional overrides (defaults shown):

{
  "stac_url": "https://...",
  "validate_children": true,
  "max_depth": 3,
  "max_objects": 5000
}

validate_children turns child validation off, max_depth caps recursion (1–10), max_objects caps how many objects are scanned per run. When the object limit is reached the report includes a traversal_limit warning.

Response

You get a report. Validation problems do not cause an error — they are listed in the report:

{
  "root_url": "https://.../catalog.json",
  "root_type": "catalog",
  "stac_is_valid": false,
  "total_objects_checked": 12,
  "summary": {
    "total_objects": 12,
    "valid_objects": 11,
    "invalid_objects": 1,
    "error_count": 1,
    "warning_count": 0,
    "by_type": {"catalog": {"total": 1, "valid": 1, "invalid": 0}},
    "errors_by_rule": {"edito_asset_href_not_public_https": 1}
  },
  "errors": [
    {
      "level": "error",
      "object_type": "item",
      "object_id": "item-1",
      "location": "https://example.com/item-1.json",
      "rule": "edito_asset_href_not_public_https",
      "message": "EDITO item asset hrefs must be public https:// URLs"
    }
  ],
  "warnings": [],
  "validation_tree": {
    "url": "https://.../catalog.json",
    "object_type": "catalog",
    "object_id": "root-catalog",
    "object_is_valid": true,
    "children": ["...each object below it, with its own issues..."],
    "issues": []
  }
}

How to read it:

  • stac_is_valid — run-level verdict: true only if no ERROR-level issue exists anywhere in the tree (warnings such as traversal_limit do not invalidate).
  • validation_tree[].object_is_valid — per-object verdict; it does not propagate from children (a valid collection stays valid even if its items are invalid).
  • root_url / root_type / total_objects_checked — what was scanned and how much.
  • summary — how many objects were checked, how many passed, and which rules were broken most often.
  • errors / warnings — every finding, with the object, its location, the rule, and a message.
  • validation_tree — your catalog as a tree, so you can see where each problem sits.

Good to know

  • What is checked:
  • STAC spec — every object is validated against the official STAC schemas (rule stac-core-schema).
  • EDITO publishing rules:
    • edito_item_not_in_collection — items must sit inside a collection.
    • edito_collection_in_collection — collections nested in collections are not supported.
    • edito_asset_href_not_public_https — item asset links must be public http(s) URLs without embedded credentials.
  • A link that cannot be read is reported as an error and the scan continues, so one broken link does not hide the rest of the report.
  • A typical workflow: validate first, then publish.