DOCSEARCHbyAlgolia
Submit Docs

STAC Specification

repository·master·Indexed 21 days ago

https://github.com/radiantearth/stac-spec

Standardized JSON-based format and RESTful API patterns for structuring and querying geospatial asset metadata. Includes specifications and JSON schemas for STAC Catalogs, Collections, Items, and shared common metadata, as well as guidelines for implementing and proposing STAC extensions.

Tokens
17.6K
Snippets
13
Records
91
Agent score
71%

What's inside stac-spec

  1. What is the SpatioTemporal Asset Catalog (STAC) specification?

    master

    The SpatioTemporal Asset Catalog (STAC) is a family of specifications designed to standardize how geospatial asset metadata (files representing Earth information at a specific place and time) is structured and queried.

    STAC is built around a minimal core of JSON object types connected by link relations, supporting a HATEOAS-style traversable interface and a RESTful API. It is designed to be flexible via an extension mechanism, allowing it to cover diverse data types such as satellite imagery, SAR, lidar, vector data, and machine learning labels.

  2. Understand STAC Commons shared components

    master

    STAC Commons contains specification components that are shared across different STAC entities, including Items, Catalogs, and Collections. When building or consuming STAC entities, you should refer to these shared definitions to ensure consistency across the specification.

    The core shared components are:

    • Assets: Data associated with Items or Collections that can be downloaded or streamed.
    • Links: Descriptions of relationships with other entities (e.g., other STAC entities or external resources).
    • Common Metadata: Fields used across all STAC entities (Items, Collections, Catalogs, Assets, Links, Bands, etc.).

  3. What is a SpatioTemporal Asset

    master

    A spatiotemporal asset is any file representing Earth information captured at a specific space and time.

    Examples include:

    • Imagery (satellite, plane, drone)
    • SAR (Synthetic Aperture Radar)
    • Point Clouds (LiDAR, Structure from Motion)
    • Data Cubes
    • Full Motion Video

    Important Note: In STAC, the GeoJSON Item is not the asset itself; it is an index that references the asset files via links. It is not recommended to use STAC to refer to traditional vector data layers (like shapefiles or GeoPackages) as assets, as they do not fit the conceptual model.

  4. What is a STAC Collection?

    master

    A STAC Collection is a JSON object used to describe a group of STAC Items that share common properties and metadata. It defines the characteristics of the entire dataset rather than individual observations.

    Key characteristics:

    • Shared Schema: It shares all fields with the STAC Catalog Specification, but uses different allowed values for type and stac_extensions.
    • Hierarchy: Collections can have parent Catalogs or Collections, and can contain child Items, Catalogs, or other Collections.
    • Compatibility: STAC Collections are compatible with the OGC API - Features Collection JSON, but include additional STAC-specific fields.
    • Validation: Any JSON object containing all required fields is considered both a valid STAC Collection and a valid STAC Catalog.

  5. What is a STAC Item?

    master

    A STAC Item is a GeoJSON Feature augmented with foreign members relevant to a STAC object. It serves as the core object in a STAC Catalog, providing the metadata necessary for clients to search or crawl online catalogs of spatial assets (such as satellite imagery, derived data, or DEMs).

    Key characteristics:

    • Format: Represented in JSON.
    • Flexibility: Any JSON object containing all required fields is a valid STAC Item.
    • Usage: The same definition is used in STAC Catalogs and Item-related API endpoints (e.g., OGC API - Features).
    • Structure: It identifies time ranges and assets associated with the spatial data.

  6. What is a STAC Catalog and how is it used?

    master

    A STAC Catalog is a JSON object that represents a logical grouping of other STAC objects, specifically other Catalogs (sub-catalogs), Collections, or Items.

    Its primary purpose is discovery:

    • For humans: It provides a structure that can be browsed to find data.
    • For machines: It provides a structure that can be crawled to build searchable indexes.

    While a Catalog can link directly to Items, it is strongly recommended to use the STAC Collection specification alongside a Catalog when publishing related spatiotemporal assets to provide better contextual information for discovery.

  7. Configure HTTP headers in a Link Object

    master

    The headers field in a Link Object is a dictionary of HTTP headers that a client must send when requesting the target resource.

    • Keys: Header names.
    • Values: Either a single string or an array of strings.
    • Multiple values: If a value is an array, the header is expected to be sent multiple times, once for each value in the array.

  8. Using Release Candidates (RC) for major specification changes

    master

    When introducing major changes, the STAC team uses a Release Candidate process to allow implementors to test the new spec before a full stable release.

    RC Workflow:

    1. Tagging: Use the format vX.Y.Z-rc.1.
    2. Community Testing: Encourage the community to update their implementations.
    3. Validation: At least two independent implementations (ideally including a client like STAC Browser) should be updated to the new specification to provide a sanity check.
    4. Iteration:
      • If feedback requires changes to the spec or schemas: Fix the issues and issue a new RC (e.g., vX.Y.Z-rc.2).
      • If feedback only requires fixes to examples or tooling: No additional RC is required; proceed to a standard release.
    5. Finalization: Once spec/schema changes are complete, perform the standard release process on the master branch.

  9. Recommended patterns for using arrays and objects in Item properties

    master

    When defining fields directly within an Item's properties object, follow these recommendations to ensure compatibility with legacy GeoJSON software and to avoid conflicts with STAC core logic:

    1. Avoid Nested Objects: Do not use objects for grouped attributes (e.g., "date_range": {"start": "...", "end": "..."}). This makes searching more complex and is harder for some software to display.
    2. Avoid Arrays for Data: Do not use arrays to represent structured data (e.g., "date_range": ["start", "end"]). This conflicts with STAC's summaries field, which treats arrays as unordered/sorted enumerations.
    3. Use Flattened Attributes (Recommended): Use multiple separate fields with a similar naming scheme (e.g., "date_range_start": "...", "date_range_end": "..."). This is the most compatible approach for GeoJSON-only software.

    Note: These restrictions apply specifically to the Item's properties object. For other levels (like the root of an Item or within an array like bands), you are free to use arrays of objects.

    // RECOMMENDED: Flattened fields
"properties": {
  "date_range_start": "2018-01-01",
  "date_range_end": "2018-01-31"
}

// DISCOURAGED: Nested object
"properties": {
  "date_range": {"start": "2018-01-01", "end": "2018-01-31"}
}

// DISCOURAGED: Array
"properties": {
  "date_range": ["2018-01-01", "2018-01-31"]
}

  10. Understand the core STAC component specifications

    master

    The SpatioTemporal Asset Catalog (STAC) specification is composed of three primary, interoperable components:

    1. Item: A GeoJSON Feature representing a single spatiotemporal asset (e.g., a satellite image at a specific time and place). It acts as an index to the actual data files.
    2. Catalog: A structural element used to group Items or other Catalogs. It functions similarly to a folder in a file system.
    3. Collection: A specialized type of Catalog that describes a group of related Items sharing common metadata (e.g., same sensor or constellation). Every Item in a Collection links back to its parent Collection.

    While these can be used independently, they are designed to work together to create a searchable, navigable hierarchy of geospatial data.

  11. Identify different types of STAC Catalogs

    master

    Implementors use the links structure to define specific roles for catalogs within a hierarchy:

    • Sub-catalog: A Catalog linked from another Catalog, used for organization (e.g., a Landsat collection containing sub-catalogs for specific Paths and Rows).
    • Root catalog: An entry point that typically only links to sub-catalogs. It may contain a STAC Collection definition or sub-catalogs providing various Collections.
    • Parent catalog: The Catalog directly above a sub-catalog in the hierarchy. Following parent links leads back to a root catalog.

  12. Understand STAC Commons: Assets, Links, and Metadata

    master

    The STAC specification includes a commons/ directory that defines shared components used across Items, Catalogs, and Collections. These include:

    • Assets: Definitions for the actual data files being described.
    • Links: The mechanism for connecting different STAC objects (HATEOAS-style).
    • Common Metadata: Shared attribute definitions used to ensure consistency across different object types.