Better error messages when a link is expected to resolve to a STAC object but doesn't

[ggiuliani]

Dear,

I'm currently trying to create a simple example based using the version extension.
It uses the following code:
import pystac
from pystac.extensions.version import *

item = pystac.Item(id='local-image-version',
geometry=footprint,
bbox=bbox,
datetime=datetime.utcnow(),
properties={})

vr = VersionExtension.ext(item, add_if_missing=True)

item.stac_extensions

#add version information
vr.version = '2.0'
vr.deprecated = 'FALSE'
vr.latest = 'https://doi.org/10.26037/yareta:kpmscrogqbdhvjeuev2ydrzk7y'
vr.predecessor = 'https://doi.org/10.26037/yareta:rnx7kq3z4rglzlzbp4i3asny7i'
vr.successor = 'https://doi.org/10.26037/yareta:voy277qzczgzbgeiyrcldztuti'

#save catalog
catalog = pystac.Catalog(id='tutorial-catalog', description='This Catalog is a basic demonstration Catalog to teach the use of the Version Extension.')

catalog.add_item(item)

catalog.normalize_and_save(root_href=os.path.join('catalog/', 'stac-VRextension'), catalog_type=pystac.CatalogType.SELF_CONTAINED)

and I get an error (in attachement)
error.txt
that I'm not able to understand as I'm new in pystac.

Thanks in advance for your appreciated help.

[gadomski]

Your issue is that the version extension expects that the latest, predecessor, and successor links refer to STAC objects. Since your links are not STAC objects, but are HTML pages, pystac fails when trying to resolve the objects.

The error message is pretty bad, so I'm going to keep this issue open and modify the title a bit to capture how we might make this better for folks. Basically, we should say "we expected this link to be a STAC object but it's not".

[ggiuliani]

Thank you Pete for your appreciate help.
As I'm new to pystac I'm a bit lost with the syntax; should I do something like:
vr.latest = item.add_link('https://doi.org/10.26037/yareta:kpmscrogqbdhvjeuev2ydrzk7y')

Thanks

Greg

[gadomski]

The DOI for your item is best represented with the scientific extension. So, here's what your original example might look like (with some tweaks):

import datetime
import os.path

from pystac import Catalog, CatalogType, Item
from pystac.extensions.scientific import ScientificExtension

item = Item(
    id="local-image-version",
    geometry={"type": "Point", "coordinates": [-105.1019, 40.1672]},
    bbox=[-105.1019, 40.1672, -105.1019, 40.1672],
    datetime=datetime.datetime.now(datetime.timezone.utc),
    properties={},
)

latest = item.clone()
latest.id = "latest"
# Turns out the new `ext` iterface doesn't support the scientific extension for items, which is a bug (@gadomski will open an issue)
ScientificExtension.ext(
    latest, add_if_missing=True
).doi = "https://doi.org/10.26037/yareta:kpmscrogqbdhvjeuev2ydrzk7y"

predecessor = item.clone()
predecessor.id = "predecessor"
ScientificExtension.ext(
    predecessor, add_if_missing=True
).doi = "https://doi.org/10.26037/yareta:rnx7kq3z4rglzlzbp4i3asny7i"

successor = item.clone()
successor.id = "successor"
ScientificExtension.ext(
    successor, add_if_missing=True
).doi = "https://doi.org/10.26037/yareta:voy277qzczgzbgeiyrcldztuti"

item.ext.add("version")
item.ext.version.version = "2.0"
item.ext.version.deprecated = False
item.ext.version.latest = latest
item.ext.version.predecessor = predecessor
item.ext.version.successor = successor

# save catalog
catalog = Catalog(
    id="tutorial-catalog",
    description=(
        "This Catalog is a basic demonstration Catalog to teach the use of "
        "the Version Extension."
    ),
)
catalog.add_item(item)
catalog.add_item(latest)
catalog.add_item(predecessor)
catalog.add_item(successor)
catalog.normalize_and_save(
    root_href=os.path.join("catalog/", "stac-VRextension"),
    catalog_type=CatalogType.SELF_CONTAINED,
)

That produces a file heirarchy like this:

$ tree catalog 
catalog
└── stac-VRextension
    ├── catalog.json
    ├── latest
    │   └── latest.json
    ├── local-image-version
    │   └── local-image-version.json
    ├── predecessor
    │   └── predecessor.json
    └── successor
        └── successor.json

[ggiuliani]

Thank you very much for your appreciated support.
It works now :-)