STAC Embedding Extension Specification

• Title: Embeddings
• Identifier: https://stac-extensions.github.io/embeddings/v1.0.0/schema.json
• Field Name Prefix: emb
• Scope: Item, Collection
• Extension Maturity Classification: Proposal
• Owner: @matthewhanson

This document explains the Embedding Extension to the SpatioTemporal Asset Catalog (STAC) specification. It defines metadata for geospatial embedding products generated by running a geospatial foundation model on Earth observation data. It describes the produced embeddings and does not redefine STAC core objects.

• Examples:
  • Item example: Item-level embedding metadata
  • Collection example: Collection-level embedding metadata and relation links
• JSON Schema
• Changelog

• STAC Item Spec: https://github.com/radiantearth/stac-spec/tree/master/item-spec
• STAC Collection Spec: https://github.com/radiantearth/stac-spec/tree/master/collection-spec
• STAC Common Metadata: https://github.com/radiantearth/stac-spec/blob/master/commons/common-metadata.md
• STAC Item JSON Schema: https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json
• STAC Collection JSON Schema: https://schemas.stacspec.org/v1.0.0/collection-spec/json-schema/collection.json
• STAC MLM Extension: https://github.com/stac-extensions/mlm
• STAC Projection Extension: https://github.com/stac-extensions/projection

The fields in the table below can be used in these parts of STAC documents:

• Catalogs
• Collections
• Item Properties (incl. Summaries in Collections)
• Assets (for both Collections and Items, incl. Item Asset Definitions in Collections and Asset Templates)
• Links (incl. Link Templates)
• Bands

Items MUST include at least one asset with the role embeddings. This asset contains the actual embedding data (e.g., a GeoParquet file, COG, or Zarr store). An Item may have multiple embeddings assets. Collections SHOULD describe the expected embeddings assets in item_assets.

emb:grid_id should use one of the grid designations from the Grid Extension. A link to the grid definition can be provided with the emb:grid relation type.

The following types may be used as applicable rel types in the Link Object. None are required.

Source data used to produce the embeddings SHOULD be linked with the derived_from relation type.

These recommendations are non-normative.

The STAC MLM Extension describes the model itself: its architecture, inputs, outputs, and available parameters. This extension describes the embeddings produced by running that model. Link to the model with the emb:encoder_model relation type, ideally pointing to a STAC MLM Item.

Geospatial embeddings fall into two categories (per arXiv:2601.13134):

The embedding type drives storage format, resolution, and cost trade-offs. A pixel product at 10m resolution for Africa is ~38-77 TB; a chip product for the same area can be under 4 GB.

Always provide data_type for the stored embeddings (e.g. float32, int8), so that users can read them without inspecting the data.

Use gsd for the ground sample distance or spatial extent per embedding, in meters.

For quantized embeddings, data_type is the stored (quantized) type. Use emb:original_data_type for the type before quantization, and the Raster Extension raster:scale and raster:offset fields for dequantization.

Consider using these extensions alongside this one:

• Processing Extension:
  • processing:datetime for when the embeddings were generated
  • processing:version for the source data processing baseline (e.g. Sentinel-2 processing baseline)
  • processing:software for the libraries and versions used to generate the embeddings
• Scientific Extension: sci:doi, sci:citation, and sci:publications for papers describing the model or embedding product
• Projection Extension: CRS and geometry of pixel embeddings

All contributions are subject to the STAC Specification Code of Conduct. For contributions, please follow the STAC specification contributing guide Instructions for running tests are copied here for convenience.

The same checks that run as checks on PRs are part of the repository and can be run locally to verify that changes are valid. To run tests locally, you'll need npm, which is a standard part of any node.js installation.

First you'll need to install everything with npm once. Just navigate to the root of this repository and on your command line run:

npm install

Then to check markdown formatting and test the examples against the JSON schema, you can run:

npm test

This will spit out the same texts that you see online, and you can then go and fix your markdown or examples.

If the tests reveal formatting problems with the examples, you can fix them with:

npm run format-examples