Important Update to CMR-STAC: New Identifier and Search Parameter Format

[LP DAAC - jwilson]

A new version of NASA’s CMR-STAC was deployed on September 4, 2024, introducing an important update to the identifier and search parameter format.

Key Change

The collection identifier and search parameter format has been changed from shortname.'v'versionId to shortname_versionId, replacing the current '.v' delimiter with a '_' (see below)
Example:

Old link: https://cmr.earthdata.nasa.gov/stac/LPCLOUD/collections/HLSL30.v2.0
New link: https://cmr.earthdata.nasa.gov/stac/LPCLOUD/collections/HLSL30_2.0
Action Required

All users of CMR-STAC must update to the new collection identifier format to ensure continued access to CMR-STAC resources.

If you have further questions or concerns, please reach out to LP DAAC User Services at lpdaac@usgs.gov or summit a post to NASA’s Earthdata Forum for assistance.
https://lpdaac.usgs.gov/news/important-update-to-cmr-stac-new-identifier-and-search-parameter-format/

[ircwaves]

Thanks for the post notifying about the release and changes to the collection IDs. It is probably also worth noting that the returned items have now also changed. In particular the asset keys have changed. Where an old MOD21A1D STAC Item reported principal asset as:

Code: Select all

    "data": {
      "href": "https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/MOD21A1D.061/MOD21A1D.A2023174.h08v05.061.2023176032101/MOD21A1D.A2023174.h08v05.061.2023176032101.hdf",
      "title": "Download MOD21A1D.A2023174.h08v05.061.2023176032101.hdf"
    },

This is now reported as:

Code: Select all

    "2023176032101": {
      "href": "https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/MOD21A1D.061/MOD21A1D.A2023174.h08v05.061.2023176032101/MOD21A1D.A2023174.h08v05.061.2023176032101.hdf",
      "title": "Direct Download",
      "description": "Download MOD21A1D.A2023174.h08v05.061.2023176032101.hdf",
      "roles": [
        "data"
      ]
    }

The addition of the `role` is welcome, but the use of the processing timestamp as the assets key unnecessarily complicates client code, by replacing an O(1) LUT access to the STAC Asset desired, with an O(n) list filter-on-role operation to get zero-or-more STAC Assets. This also requires further inspection to check that the result is the desired one (vs none, or multiple as with `role=thumbnail`).

Also, in the case of the `role=thumbnail` for this STAC Item, the filtering results in two assets, and the selection must be done by href or description comparison to get the desired href.

Code: Select all

    "thumbnail_0": {
      "href": "https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-public/MOD21A1D.061/MOD21A1D.A2023174.h08v05.061.2023176032101/BROWSE.MOD21A1D.A2023174.h08v05.061.2023175232101.1.jpg",
      "title": "Thumbnail [0]",
      "description": "Download BROWSE.MOD21A1D.A2023174.h08v05.061.2023175232101.1.jpg",
      "roles": [
        "thumbnail"
      ]
    },
    "thumbnail_1": {
      "href": "s3://lp-prod-public/MOD21A1D.061/MOD21A1D.A2023174.h08v05.061.2023176032101/BROWSE.MOD21A1D.A2023174.h08v05.061.2023175232101.1.jpg",
      "title": "Thumbnail [1]",
      "description": "This link provides direct download access via S3 to the granule",
      "roles": [
        "thumbnail"
      ]
    },

In this case, use of the Alternate Assets STAC Extension would be preferable to including two thumbnails, as they are the same data, via different access patterns:

Code: Select all

    "thumbnail": {
      "href": "https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-public/MOD21A1D.061/MOD21A1D.A2023174.h08v05.061.2023176032101/BROWSE.MOD21A1D.A2023174.h08v05.061.2023175232101.1.jpg",
      "title": "Thumbnail [0]",
      "description": "Download BROWSE.MOD21A1D.A2023174.h08v05.061.2023175232101.1.jpg",
      "roles": [
        "thumbnail"
      ],
      "alternate": {
        "s3": {
          "href": "s3://lp-prod-public/MOD21A1D.061/MOD21A1D.A2023174.h08v05.061.2023176032101/BROWSE.MOD21A1D.A2023174.h08v05.061.2023175232101.1.jpg"
        }
      }
    },

This is the status today, but I would welcome reversion back to the old asset keys, along with use of the Alternate Assets extension, with much confetti.

[aaleman]

Just in case there are folks still watching this post, I want to share an important update regarding the communication of changes and releases, as well as reporting and tracking issues for CMR-STAC...

• Release notes are now available in the CMR-STAC GitHub repo: https://github.com/nasa/cmr-stac/releases. The production release cadence for CMR-STAC is typically every two weeks on Wednesday, and release notes will be posted 2 weeks ahead of scheduled release dates. The next scheduled release to production is 11/20/2024.

• The CMR-STAC GitHub repo will also be The Place for reporting and tracking the status of issues and feature requests going forward. You can check the current list of open issues here: https://github.com/nasa/cmr-stac/issues.

I'm hopeful this streamlined approach to communications will make it easier for everyone to report and track the status of issues, fixes, and new feature requests for CMR-STAC. Please reach out if you have questions or concerns.

[ircwaves]

Thanks Alicia!

A question about the release versions. I see that they are off the form rX.Y.Z.

Do the respective numbers conveying anything about changes in API schema? As a user/system integrator, I'm looking to know if the release is going to include breaking changes like the asset key changes I mentioned a few posts back.

Thanks again. This be process is promising.

++ Ian

[dschuck]

ircwaves wrote:
> Thanks for the post notifying about the release and changes to the
> collection IDs. It is probably also worth noting that the returned items
> have now also changed. In particular the asset keys have changed. Where
> an old MOD21A1D STAC Item reported principal asset as:
>
> [code]
> "data": {
> "href":
> "https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/MOD21A1D.061/MOD21A1D.A2023174.h08v05.061.2023176032101/MOD21A1D.A2023174.h08v05.061.2023176032101.hdf",
> "title": "Download
> MOD21A1D.A2023174.h08v05.061.2023176032101.hdf"
> },
> [/code]
>
> This is now reported as:
>
> [code]
> "2023176032101": {
> "href":
> "https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/MOD21A1D.061/MOD21A1D.A2023174.h08v05.061.2023176032101/MOD21A1D.A2023174.h08v05.061.2023176032101.hdf",
> "title": "Direct Download",
> "description": "Download
> MOD21A1D.A2023174.h08v05.061.2023176032101.hdf",
> "roles": [
> "data"
> ]
> }
> [/code]
>
> The addition of the `role` is welcome, but the use of the processing
> timestamp as the assets key unnecessarily complicates client code, by
> replacing an [i]O(1)[/i] LUT access to the STAC Asset desired, with an
> [i]O(n)[/i] list filter-on-role operation to get zero-or-more STAC Assets.
> This also requires further inspection to check that the result is the
> desired one (vs none, or multiple as with `role=thumbnail`).
>
> Also, in the case of the `role=thumbnail` for this STAC Item, the filtering
> results in two assets, and the selection must be done by href or
> description comparison to get the desired href.
>
> [code]
> "thumbnail_0": {
> "href":
> "https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-public/MOD21A1D.061/MOD21A1D.A2023174.h08v05.061.2023176032101/BROWSE.MOD21A1D.A2023174.h08v05.061.2023175232101.1.jpg",
> "title": "Thumbnail [0]",
> "description": "Download
> BROWSE.MOD21A1D.A2023174.h08v05.061.2023175232101.1.jpg",
> "roles": [
> "thumbnail"
> ]
> },
> "thumbnail_1": {
> "href":
> "s3://lp-prod-public/MOD21A1D.061/MOD21A1D.A2023174.h08v05.061.2023176032101/BROWSE.MOD21A1D.A2023174.h08v05.061.2023175232101.1.jpg",
> "title": "Thumbnail [1]",
> "description": "This link provides direct download
> access via S3 to the granule",
> "roles": [
> "thumbnail"
> ]
> },
> [/code]
>
> In this case, use of the
> [url=https://github.com/stac-extensions/alternate-assets]Alternate Assets
> STAC Extension[/url] would be preferable to including two thumbnails, as
> they are the same data, via different access patterns:
>
> [code]
> "thumbnail": {
> "href":
> "https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-public/MOD21A1D.061/MOD21A1D.A2023174.h08v05.061.2023176032101/BROWSE.MOD21A1D.A2023174.h08v05.061.2023175232101.1.jpg",
> "title": "Thumbnail [0]",
> "description": "Download
> BROWSE.MOD21A1D.A2023174.h08v05.061.2023175232101.1.jpg",
> "roles": [
> "thumbnail"
> ],
> "alternate": {
> "s3": {
> "href":
> "s3://lp-prod-public/MOD21A1D.061/MOD21A1D.A2023174.h08v05.061.2023176032101/BROWSE.MOD21A1D.A2023174.h08v05.061.2023175232101.1.jpg"
> }
> }
> },
> [/code]
>
> This is the status today, but I would welcome reversion back to the old
> asset keys, along with use of the Alternate Assets extension, with much
> confetti.

I strongly agree with what ircwaves suggests. Any thoughts on making this a reality? The current format is highly problematic as ircwaves points out.

[aaleman]

A question about the release versions. I see that they are off the form rX.Y.Z.

Do the respective numbers conveying anything about changes in API schema? As a user/system integrator, I'm looking to know if the release is going to include breaking changes like the asset key changes I mentioned a few posts back.

No, not strictly. But, the content of the release notes will communicate if/when there are known breaking changes included in a release.