SpatioTemporal Asset Catalog Validator

⚠️ IMPORTANT NOTICE: PyPI Package Renamed ⚠️

Due to an administrative transition, the PyPI package name for this project has changed. The stac-validator package on PyPI is no longer maintained.

To get the latest updates, bug fixes, and features (v4.2.0 and beyond), you must now install stac-valid.

🛠️ What you need to do

You only need to update your installation command or requirements.txt: ```bash

OLD

pip install stac-validator

NEW

pip install stac-valid ```

Your existing Python code and CLI scripts DO NOT need to change. > You will still use import stac_validator and the stac-validator CLI command exactly as you did before.

Table of Contents

• Overview
• Documentation
• Requirements
• Installation
• Supported STAC Versions
• Usage
• CLI
  • Legacy Validation
• Batch Validation
• Fast Validation
• API Server (FastAPI)
• Python
• Schema Cache Settings
• Performance Benchmarking
• Examples
• Core Validation
• Custom Schema
• Extensions Validation
• Recursive Validation
• Item Collection Validation
• Using Headers
• Schema Mapping
• Schema Config
• Pydantic Validation
• Deployment
• Docker
• AWS (CDK)
• Testing
• Related Projects
• Sponsors and Supporters
• Contributing
• License

Overview

STAC Validator is a tool to validate STAC (SpatioTemporal Asset Catalog) json files against the official STAC specification. It provides both a command-line interface and a Python API for validating STAC objects.

Documentation

For detailed documentation, please visit our GitHub Pages documentation site.

Validate STAC json files against the STAC spec.

$ stac-validator https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/extended-item.json

[
    {
        "version": "1.0.0",
        "path": "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/extended-item.json",
        "schema": [
            "https://stac-extensions.github.io/eo/v1.0.0/schema.json",
            "https://stac-extensions.github.io/projection/v1.0.0/schema.json",
            "https://stac-extensions.github.io/scientific/v1.0.0/schema.json",
            "https://stac-extensions.github.io/view/v1.0.0/schema.json",
            "https://stac-extensions.github.io/remote-data/v1.0.0/schema.json",
            "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json"
        ],
        "valid_stac": true,
        "asset_type": "ITEM",
        "validation_method": "default"
    }
]

Requirements

• Python 3.8+
• Requests
• Click
• Jsonschema

Related Projects

Note: Stac-validator is also used in stac-check which adds linting messages based on the official STAC best practices document.
https://github.com/stac-utils/stac-check

Install

Installation from PyPi

$ pip install stac-valid

Installation from Repo

$ pip install .

or for local development

$ pip install -e '.[dev]'

The Makefile has convenience commands if Make is installed.

$ make help

Versions supported

STAC
0.8.0
0.8.1
0.9.0
1.0.0-beta.1
1.0.0-beta.2
1.0.0-rc.1
1.0.0-rc.2
1.0.0-rc.3
1.0.0-rc.4
1.0.0
1.1.0-beta.1
1.1.0

Usage

CLI

Basic Usage

$ stac-validator --help

Usage: stac-validator [OPTIONS] COMMAND [ARGS]...

  STAC Validator - Validate STAC files against the STAC specification.

  Usage:
    stac-validator validate <file> [options]
    stac-validator batch <files> [options]
    stac-validator batch <file> --item-collection [options]


Options:
  --help  Show this message and exit.

Commands:
  batch     Validate multiple STAC files concurrently using all available...
  validate  Main function for the `stac-validator` command line tool.

Validate Command

$ stac-validator validate --help

Usage: stac-validator validate [OPTIONS] STAC_FILE

  Validate a STAC file against the STAC specification.

  Prints validation results to the console as JSON. Exits with status code 0
  if valid, 1 if invalid.

Options:
  --core                          Validate core stac object only without
                                  extensions.
  --extensions                    Validate extensions only.
  --links                         Additionally validate links. Only works with
                                  default mode.
  --assets                        Additionally validate assets. Only works
                                  with default mode.
  -c, --custom TEXT               Validate against a custom schema (local
                                  filepath or remote schema).
  -sc, --schema-config TEXT       Validate against a custom schema config
                                  (local filepath or remote schema config).
  -s, --schema-map <TEXT TEXT>...
                                  Schema path to replaced by (local) schema
                                  path during validation. Can be used multiple
                                  times.
  -r, --recursive                 Recursively validate all related stac
                                  objects.
  -m, --max-depth INTEGER         Maximum depth to traverse when recursing.
                                  Omit this argument to get full recursion.
                                  Ignored if `recursive == False`.
  --collections                   Validate /collections response.
  --item-collection               Validate item collection response. Can be
                                  combined with --pages. Defaults to one page.
  --no-assets-urls                Disables the opening of href links when
                                  validating assets (enabled by default).
  --header <TEXT TEXT>...         HTTP header to include in the requests. Can
                                  be used multiple times.
  -p, --pages INTEGER             Maximum number of pages to validate via
                                  --item-collection. Defaults to one page.
  -t, --trace-recursion           Enables verbose output for recursive mode.
  --no_output                     Do not print output to console.
  --log_file TEXT                 Save full recursive output to log file
                                  (local filepath).
  --pydantic                      Validate using stac-pydantic models for
                                  enhanced type checking and validation.
  --verbose                       Enable verbose output. This will output
                                  additional information during validation.
  --schema-cache-size INTEGER     Max number of schema entries to cache in
                                  memory. Use 0 to disable schema caching.
                                  Defaults to 16.
  --help                          Show this message and exit.

Batch Command

$ stac-validator batch --help

Usage: stac-validator batch [OPTIONS] FILES...

  Validate multiple STAC files concurrently using all available CPU cores.

  This command uses multiprocessing to validate STAC files in parallel,
  bypassing Python's Global Interpreter Lock (GIL) for maximum performance.
  Each CPU core gets its own schema cache, which is warmed up on the first
  file and reused for subsequent files.

  Examples:

      # Validate all JSON files in a directory
      $ stac-validator batch *.json

      # Validate specific files
      $ stac-validator batch file1.json file2.json file3.json

      # Validate a GeoJSON FeatureCollection (validates each feature individually)
      $ stac-validator batch --item-collection sample_data/sentinel-cogs_0_100.json

      # Use only 4 cores
      $ stac-validator batch *.json --cores 4

      # Disable progress bar
      $ stac-validator batch *.json --no-progress

Options:
  --cores INTEGER       Number of CPU cores to use for parallel validation.
                        Defaults to all available cores.
  --no-progress         Disable progress bar during validation.
  --no-output           Do not print output to console.
  --item-collection  Treat files as GeoJSON FeatureCollections and validate
                        each feature individually.
  --verbose             Show full JSON output for all items. By default, only
                        invalid items are shown.
  --schema-cache-size INTEGER  Max number of schema entries to cache
                             per worker process. Use 0 to disable
                             schema caching. Defaults to 16.
  --batch-size INTEGER         Batch size for chunked processing. Larger
                               batches use more memory but may be faster.
                               Defaults to 2000.
  --help                Show this message and exit.

Fast Command

$ stac-valid fast --help

Usage: stac-valid fast [OPTIONS] STAC_FILE

  High-speed validation using fastjsonschema and local caching.

Options:
  -q, --quiet    Suppress individual item logs.
  -v, --verbose  Show full validation logs for all items. By default, only
                 invalid items are shown.
    -r, --recursive  Recursively validate all child catalogs, collections,
                                     and items.
    -a, --api        Validate a STAC API catalog recursively (follows data,
                                     child, item, and items links).
    --limit INTEGER RANGE  Limit number of STAC objects to validate.
                                                 [x>=1]
  --help         Show this message and exit.

Legacy Validation

The validate command is the main legacy validation tool with comprehensive options:

# Basic single file validation
$ stac-validator validate path/to/stac_file.json

# Validate with custom schema
$ stac-validator validate item.json --custom /path/to/schema.json

# Recursively validate all related STAC objects
$ stac-validator validate catalog.json --recursive --max-depth 5

# Validate collections endpoint response
$ stac-validator validate https://example.com/collections --collections

# Validate item collection response
$ stac-validator validate https://example.com/search --item-collection --pages 10

# Validate with extensions and links
$ stac-validator validate item.json --extensions --links --assets

Options include: - --core - Validate core STAC only (skip extensions) - --extensions - Validate extensions only - --links - Validate link objects - --assets - Validate asset objects - --recursive - Recursively validate related STAC objects - --custom - Validate against custom schema - --schema-map - Replace schema URLs during validation - --collections - Validate /collections endpoint response - --item-collection - Validate item collection responses - --pydantic - Use Pydantic models for validation - --schema-cache-size - Configure schema cache size - --batch-size - Configure batch size for chunked processing (batch command only) - And more (see stac-validator validate --help)

Batch Validation

The batch command validates multiple STAC files concurrently using multiprocessing to bypass Python's Global Interpreter Lock (GIL). This enables 10-100x performance improvement over single-threaded validation by utilizing all available CPU cores.

Architecture:

• Multiprocessing: Each CPU core runs an independent Python process
• Per-worker schema cache: Each worker maintains its own LRU cache of downloaded schemas (default 16 per worker)
• Cache warmup: First file on each worker downloads schemas, subsequent files use cached copies
• Configurable cache: Use --schema-cache-size to adjust cache size per worker (0 = disabled)
• Linear scaling: Performance scales linearly with available cores (e.g., 8 cores = ~8x faster)
• Container-aware: Automatically detects Docker/ECS CPU limits via os.sched_getaffinity()

Basic Usage

```bash

Validate all JSON files in