Versioning Indicators Extension Specification

• Title: Versioning Indicators
• Identifier: https://stac-extensions.github.io/version/v1.2.0/schema.json
• Field Name Prefix: -
• Scope: Item, Collection
• Extension Maturity Classification: Candidate
• Owner: @m-mohr

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

This extension allows to version STAC Collections and STAC Items. Therefore, it also allows to deprecate legacy versions. Only fields and possible link relation types are defined in this extension, but it does NOT suggest any versioning best practices to structure static or dynamic catalogs. Instead check the Versioning Best Practices for Catalogs.

• Examples:
  • Item example: Shows the basic usage of the extension in a STAC Item
  • Collection example: Shows the basic usage of the extension in a STAC Collection
• JSON Schema
• Changelog

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
version	string	Version of the context this fields is used in (e.g. Asset or Collection).
deprecated	boolean	Specifies that the context this field is used in (e.g. Asset or Collection) is deprecated with the potential to be removed. Defaults to false. It should be transitioned out of usage as soon as possible and users should refrain from using it in new projects. A link with relation type latest-version SHOULD be added to the links and MUST refer to the resource that can be used instead.
experimental	boolean	Specifies that the context this field is used in (e.g. Asset or Collection) is experimental with the potential to break or be unstable. Defaults to false.

These fields have different meaning depending on where they are used. When used as an Item properties or top-level Collection field, they refer to the version or deprecation of all data referenced in the Item or Collection, which may include the metadata itself. When used in an Asset Object, they refer to the version or deprecation of the particular data asset linked to in the Asset Object.

Relation types

The following types should be used as applicable rel types for the Link Object to reference the latest version, the predecessor version and successor versions. These are all following RFC 5829.

Type	Description
latest-version	This link points to a STAC resource containing the latest (e.g., current) version. A maximum of one link can use this relation type per STAC resource.
predecessor-version	One or multiple links can point to STAC resources that are predecessor versions in the version history.
successor-version	One or multiple links can point to STAC resources that are successor versions in the version history.
version-history	This link points to a version history or changelog. This can be for example a Markdown file with the corresponding media type or a STAC Catalog or Collection.

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