Validity Extension Specification

• Title: Validity
• Identifier: https://pdssp.github.io/STAC-Validity-Extension/v1.0.0/schema.json
• Field Name Prefix: validity
• Scope: Item, Collection
• Extension Maturity Classification: Proposal
• Owner: @your-gh-handle

This document explains the Validity Extension to the SpatioTemporal Asset Catalog (STAC) specification.

The Validity Extension defines the temporal interval during which a STAC Item (or Collection) is considered valid, applicable, or the current reference product. It targets derived products such as maps, mosaics, composites, classifications, and models, where the period during which the product should be used can differ from the acquisition period of the source observations it was built from.

The extension complements the existing STAC temporal fields by separating two concepts that STAC core does not distinguish:

• the temporal extent of the source data used to generate the product (already covered by datetime / start_datetime / end_datetime);
• the temporal validity of the resulting product, i.e. the period during which it is the applicable reference (covered by the fields added here).

A product may remain valid until it is replaced, deprecated, or superseded by a newer or more accurate version.

• Examples:
  • Item example: a land cover map with an open-ended validity interval.
  • Item example with versioning: two successive land cover maps, showing how the validity interval closes when a product is superseded.
  • Raw acquisition example: a source satellite scene, where the validity interval mirrors the acquisition datetime (see Best Practices).
  • Collection example: a collection of land cover maps using the extension at the Collection level and in summaries.
• JSON Schema
• Changelog

Motivation

The STAC temporal model is well suited for observation datasets, where the Item datetime represents the acquisition time of the data. For derived products, the temporal meaning is more complex: a map generated from multiple observations has at least two distinct temporal dimensions.

Source observation period : The period covered by the observations used to create the product. This is already expressible with the core start_datetime / end_datetime fields.

Product validity period : The period during which the product should be considered applicable and returned by temporal searches. This is what this extension adds.

For example, a land cover map generated from satellite observations acquired between May 1 and May 8, 2024, and published on May 15, 2024, may remain the reference product until a newer version is released. The acquisition period and the validity period are different concepts, and a STAC Item currently has no way to express the second one.

Fields

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)
• Links

Field Name	Type	Description
validity:start_datetime	string (date-time)	The beginning of the period during which the Item is valid.
validity:end_datetime	string (date-time)|null	The end of the period during which the Item is valid.

Both fields are optional individually, but at least one of them MUST be present for the extension to apply to a given STAC document (see JSON Schema).

Additional Field Information

validity:start_datetime

The beginning of the period during which the product is considered valid. Not required.

{
  "validity:start_datetime": "2024-05-15T00:00:00Z"
}

This means the product is considered valid from 15 May 2024.

validity:end_datetime

The end of the period during which the product is considered valid. Not required.

If this field is absent, null, or not present at all, the validity interval is considered open-ended: the product remains valid until it is replaced, deprecated, revoked, or explicitly invalidated. The absence of validity:end_datetime does not mean that the validity period is unknown — it means that no end date is currently defined.

{
  "validity:start_datetime": "2024-05-15T00:00:00Z",
  "validity:end_datetime": null
}

An open-ended validity interval is common for reference maps, operational products, continuously maintained datasets, and official versions of geographic information.

Example

A land cover map generated from Sentinel-2 observations:

{
  "type": "Feature",
  "properties": {
    "start_datetime": "2024-05-01T00:00:00Z",
    "end_datetime": "2024-05-08T00:00:00Z",

    "validity:start_datetime": "2024-05-15T00:00:00Z",
    "validity:end_datetime": null
  }
}

Interpretation:

• The source observations used to create the map were acquired between May 1 and May 8, 2024.
• The map was published on May 15, 2024.
• The map remains the reference product until superseded.

Relation to other STAC concepts and extensions

This extension does not redefine existing STAC temporal fields, and it does not duplicate what other extensions already provide. It adds one additional temporal dimension that is missing from STAC core: the applicability period of a derived or versioned product.

Field(s)	Meaning
datetime	Temporal instant associated with the Item.
start_datetime / end_datetime	Temporal extent of the Item or of the source observations.
validity:start_datetime / validity:end_datetime	Period during which the product is considered valid.

Relation to the Timestamps Extension

The Timestamps Extension expires field is similar in spirit to validity:end_datetime, but describes the lifecycle of the metadata record or data file itself ("date and time the corresponding data expires"), not the applicability window of the product for temporal search. It also has no counterpart to validity:start_datetime. Use the Timestamps Extension to describe when a STAC entity was published, updated, or removed from a catalog; use this extension to describe which period a product should be considered the correct answer for. The two extensions can be used together; when they are, keep validity:end_datetime and timestamps:expires consistent to avoid contradicting search results.

Relation to the Version Extension

The Version Extension tracks which Item replaced another one, through the deprecated field and the latest-version / predecessor-version / successor-version link relations. This extension tracks when an Item stopped being the valid one. The two are complementary: when a product is superseded, set validity:end_datetime on the outgoing Item to the date the replacement became valid, mark it "deprecated": true, and link to the replacement with a latest-version (or successor-version) link, as shown in examples/item-versioned.json.

Best Practices

A single-field temporal query only works across an entire catalog if every Item populates that field. It is RECOMMENDED that all Items in a catalog declare this extension and populate validity:start_datetime / validity:end_datetime — not only the derived products — so that a client can always query on validity:start_datetime / validity:end_datetime (e.g. through the Filter Extension) instead of datetime / start_datetime / end_datetime, regardless of whether an Item is a raw acquisition or a derived product:

• For a derived or versioned product (map, mosaic, composite, model output), validity:start_datetime / validity:end_datetime describe its own applicability period, as shown in the examples above.
• For a raw acquisition Item (e.g. a single satellite scene), the product is the observation itself: it is never superseded by a newer observation of the same event, so its validity period is the same as its own temporal extent. Set validity:start_datetime / validity:end_datetime to the same values as start_datetime / end_datetime (or to datetime, for an instantaneous acquisition), as shown in examples/item-acquisition.json.

This keeps the query field consistent catalog-wide while preserving correct results: a query for a given date still only matches the acquisitions taken on that date, and any derived product still applicable at that date.

Contributing

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.

Running tests

The same checks that run as checks on PR's 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