stac-migrate

A library to update STAC files to the latest version (1.1.0 at the moment of writing). Supports updating STAC versions 0.6.0 and later; documents without a stac_version are assumed to be 0.6.0.

Version of this library:

Usage

JavaScript / Node

Add to your project with npm install @radiantearth/stac-migrate --save

Import the library: const Migrate = require('@radiantearth/stac-migrate');

• Migrate (auto-detection): Migrate.stac(stac: object, updateVersionNumber: boolean = true) => object

  This method does not migrate the Commons extension - use Migrate.item if you have used the Commons extension.

• Migrate a STAC Collection: Migrate.collection(collection: object, updateVersionNumber: boolean = true) => object

• Migrate a STAC Catalog: Migrate.catalog(catalog: object, updateVersionNumber: boolean = true) => object

• Migrate a STAC Item: Migrate.item(item: object, collection: object = null, updateVersionNumber: boolean = true) => object

  The collection parameter is only required to migrate the Commons extension. Otherwise, you don't need to pass this paramater.

• Migrate a STAC CollectionCollection: Migrate.collectionCollection(apiCollections: object, updateVersionNumber: boolean = true) => object

• Migrate a STAC ItemCollection: Migrate.itemCollection(apiItems: object, updateVersionNumber: boolean = true) => object

Note: All changes will be applied in-place! If you don't want the input object to change, make a deep clone before. If you don't have a library which supports this (e.g. lodash) you can simply use var clone = JSON.parse(JSON.stringify(object));.

CLI

You can also use the CLI to migrate a single file. The commands follow the different methods above and has the same "restrictions" as above.

• Migrate (auto-detection, override): npx stac-migrate <source_path>
• Migrate (auto-detection, save to a different file with 4 spaces indentation): npx stac-migrate <source_path> --dest <dest_path> --indent 4
• Migrate a STAC Collection: npx stac-migrate <source_path> --dest <dest_path> --collection
• Migrate a STAC Catalog: npx stac-migrate <source_path> --dest <dest_path> --catalog
• Migrate a STAC Item: npx stac-migrate <source_path> --dest <dest_path> --item --collection_path <collection_path>
• Migrate a STAC Item Collection: npx stac-migrate <source_path> --dest <dest_path> --item_collection
• Migrate a STAC Collection Collection: npx stac-migrate <source_path> --dest <dest_path> --collections

Supported Extensions

• Checksum (legacy)

  Pre-0.9 checksum:sha2 / checksum:sha3 are assumed to be sha2-256 / sha3-256; other lengths convert incorrectly.

• CF 1.0.0

• Classification 2.0.0

  A missing class name (required since 2.0.0) is filled from the class description.

• Collection Assets (legacy)

• Commons (legacy)

  A non-standalone Collection (with child/item links) migrated on its own drops its shared properties; pass the Items via Migrate.item(item, collection) to keep them.

• Contacts 1.0.1

  Migrates from 0.1.0 onwards. The structure of 0.0.1 is not converted.

• Data Cube 2.3.0

  A cube:dimensions reference_system given as a PROJ4 or WKT string is not converted to the 2.0.0 representation.

• Datetime Range (legacy)

• Electro-Optical 2.0.0

  eo:bands and raster:bands are merged into bands (1.1.0) by array index, assuming matching order. Pre-1.0.0 index-based eo:bands are resolved against properties.bands.

• File 2.1.0 (and 1.0.0 for nodata)

  file:nodata maps to the single-valued nodata (first value kept); extra values are copied to a non-standard nodata:values.

• Instruments 0.2.0

• Item Asset Definition 1.0.0 (legacy)

• Label 1.0.1

• Order 1.1.0

• Point Cloud 2.0.0

  pc:encoding is not rewritten and left in place.

• Processing 1.3.0

• Product 1.1.0

  The deprecated product:status value qualitydegraded becomes accepted with product:quality_status set to degraded.

• Projection 2.1.0

• Raster 2.0.0

• SAR 1.3.2

• Satellite 1.2.0

• Scientific Citation 1.0.0

• Sentinel-1 0.2.0

  s1:resolution, s1:product_identifier and s1:product_timeliness are not migrated, as they have no 1:1 replacement.

• Sentinel-3 0.2.0

  s3:product_name, s3:processing_timeliness, s3:lrm_mode, s3:sar_mode and the s3:gsd objects are not migrated, as they have no 1:1 replacement.

• Sentinel-5P 0.2.0

  s5p:product_name, s5p:spatial_resolution and the product-specific objects are not migrated, as they have no 1:1 replacement.

• Single Item

• Table 1.3.0

• Timestamps 1.1.0

• Versioning Indicators 1.2.0

• View Geometry 1.1.0

Unsupported Extensions

The following extensions are not migrated:

• Authentication

  The removed scheme types planetaryComputer and earthdata (1.1.0) are not rewritten to signedUrl. They stay valid as custom type values.

• Storage

Development

• Run the tests: npm test
• Run the linter: npm run lint
• Format the code: npm run format