Include link to original STAC as top level property?

[cholmes]

Great work on this tool - it's been helpful to use with https://beta.source.coop/planet/rapidai4eo

One thing that I think would be really useful is to pull out the 'self' link to the top level, and ideally to make sure it's an absolute link. That's the field I find myself wanting, to be able to just see the full STAC original STAC item easily, as it's seems nicer to look through the structure with that then digging into structs. It could just be an option, but I could see it being a useful default.

The related one that would be quite nice for usability is to link to a STAC Browser url, so I can just use that to see it on the map, download assets, etc. That could default to https://radiantearth.github.io/stac-browser/#/ but likely would be nice to make it easy for people to put other stac browser options.

If this sounds like a good idea then @m-mohr can likely take it on.

[m-mohr]

Please note that the STAC Browser instance at https://radiantearth.github.io/stac-browser/ is a demo instance and can break at any time. It's not meant for production use.

[TomAugspurger]

One thing that I think would be really useful is to pull out the 'self' link to the top level, and ideally to make sure it's an absolute link.

is the self link special here? Or does it make sense to expand all the links?

And are links special? Or should we expand other nested fields, like assets?

I struggled with this when initially developing this. At least in pandas, working with nested data like links and assets is possible, but challenging, which is why I have this section in our docs on stac-geoparquet. In the end I just decided to match geopandas' from_features method, which lifts properties to the top level, but doesn't expand nested properties.

I'm absolutely open to an option to expand the fields of the user's choice. And am open to the idea of changing the default.

The related one that would be quite nice for usability is to link to a STAC Browser url, so I can just use that to see it on the map, download assets, etc. That could default to https://radiantearth.github.io/stac-browser/#/ but likely would be nice to make it easy for people to put other stac browser options.

Just to make sure I understand, the idea would be to have a column where each row is a link to something like https://radiantearth.github.io/stac-browser/#/external/planetarycomputer.microsoft.com/api/stac/v1/collections/sentinel-2-l2a/items/S2B_MSIL2A_20230718T093549_R036_T41XNK_20230718T125439?

That should be doable as well. I imagine the API would be something like

def to_geoparquet(..., stacbrowser_link=None):
   ....

[m-mohr]

The self link is somewhat special as it gives a pointer back to source of truth. Expanding links and assets in general is not needed, I think.

The STAC Browser link can be constructed from the self link easily, so I don't see much use in providing it explicitly. It's basically the self link without protocol and a prefix such as https://radiantearth.github.io/stac-browser/#/external/. That's more something to have on the tooling side, I think. If you have a self hosted instance it's a bit more difficult and can't be implemented with a single parameter.

[cholmes]

The self link is somewhat special as it gives a pointer back to source of truth. Expanding links and assets in general is not needed, I think.

Agreed.

The STAC Browser link can be constructed from the self link easily, so I don't see much use in providing it explicitly. It's basically the self link without protocol and a prefix such as https://radiantearth.github.io/stac-browser/#/external/. That's more something to have on the tooling side, I think.

I think ideally it'd be an option in stac-geoparquet - not the default, but let users include it and construct the right stac browser for them, at least in the CLI. It's nice to have the url fully formed to just click on. Having it in well-documented tooling also would make sense.

[m-mohr]

Working on a PR for the self link right now.

Any proposal for a reasonable column name that doesn't conflict with potential STAC properties? I'm using __source for now.

Also, it only works if there are absolute self links in the STAC files. It doesn't try to create absolute links from a base URL or so. Is that something you want to have @cholmes ? I thought relative self links should be rare as that's actually not really a valid self link anyway.

[TomAugspurger]

Any proposal for a reasonable column name that doesn't conflict with potential STAC properties? I'm using __source for now.

My initial reaction was to just ask the user for a column name and not guess. But I suppose for consumers of these stac-geoparquet datasets, it'd be helpful to have a convention around these column names (assuming we don't want to go down the route of defining a standard around this and putting that in the parquet metadata, which I think is premature).

Personally, I would recommend something user-friendly like self_href as the default, even if that elevates the risk of collisions.

[m-mohr]

it'd be helpful to have a convention around these column names

I agree.

self_href

I also had that in mind, but wasn't sure whether non-STAC people would understand what that means. Maybe self_link or source_url?