Is this where I would go to discuss how I created a custom STAC API extension

[Robert Dennett]

I created a custom STAC API extension last week which I don't think would necessarily be of use to the community, but I did want to see if I implemented it as one would expect.  Is this forum the correct place to do that?  If not, can you recommend an alternative venue?

[Ian Cooke]

Hi Robert, 

Sharing here is totally fine.  Or you are welcome to join the community call, every other Monday at 11a us-east on google-meet via the STAC-community google calendar. The steering committee is looking into updating the default discussion location (slack, gitter, github, discourse, ...).  So, look for an update on a default discussion space soon at stacspec.org.  (That site currently suggest discourse, but it has been _very_ quite there).

Look forward to seeing your extension,

++ Ian 

[Robert Dennett]

The purpose of this extension is to return Collections belonging to a certain category, along with the counts of any collections in the results which belong to second, third, etc. category.  This extension is build to service a particular need we have in our UI, and I don't know that it would be helpful for others.  

Since I was unable to find instructions on how to actually implement an API extension, I created a project with a Dockerfile which installs stac-fastapi-pgstac.  The code in the project contains a python script which defines a ConformanceClasses class, a child of the Collections class, a child of the CoreCrudClient class and a child of the APIExtension class.  The parent classes are those found in stac-fastapi-pgstac.  Additionally, there is a .sql file which contains the DDL for a Postgres function which actually performs the business logic, similar to the other functions defined by pgstac.

The extension only supports collections and so the ConformanceClasses class only defines a URL for Collections.  It's currently a placeholder since I note that a number of conformance class URLs return 404 errors when you try to follow them.

My collections class adds another field which contains the counts of other categories.

The CoreCrudClient child adds a method which causes a new endpoint to link to the PG function.  It closely mimics the method which serves the /collections endpoint

The APIExtension child defines the methods necessary to register the client method as responding to the endpoint which we're calling /facets.

Does this sound reasonable/in line with how you might implement an extension?  Are there other things I need to create that I may have missed?  It works in my testing, but I am winging it here and am not sure I did it right.

Thanks,

Rob

[matt...@mohr.ws]

Hey, 

where can I read your extension? I might have a similar usecase and would like to have a closer look :-)

Best,
Matthias

[Francis Charette Migneault]

Is the mentioned /facets endpoint aligned with the OGC API Records  - Part 2: Facets definition (ie: https://github.com/opengeospatial/ogcapi-records/blob/master/extensions/facets/standard/clause_7_simple_facets.adoc) ?

I could see this as being more "core" STAC than an API extension if that is the case.

[Francis Charette Migneault]

The facets and buckets terms seem aligned with the envisioned logical groups:

https://github.com/opengeospatial/ogcapi-records/blob/master/extensions/facets/standard/clause_4_terms_and_definitions.adoc

If I had to implement this, I would create a "facets" directory for the generic definition under https://github.com/stac-utils/stac-fastapi/tree/main/stac_fastapi/extensions/stac_fastapi/extensions/core

And provide the corresponding pgstac-specific implementation under https://github.com/stac-utils/stac-fastapi-pgstac/tree/main/stac_fastapi/pgstac/extensions

A dedicated "facets" repository for the spec details would be created under https://github.com/stac-api-extensions/

And it would point to external OGC API Records conformance definitions, similar to what filter does: https://github.com/stac-api-extensions/filter#overview

[Robert Dennett]

I haven't created a repo for it yet.  Were you looking for the implementation or the spec?  I haven't created a spec at all yet.  The extension is custom for our needs and so I wasn't clear if a spec was required if you weren't planning on making it public.

Thanks,

Rob

[Matthias Mohr]

I'd be looking for the spec, ideally. But looking at examples often also helps to get a better understanding. I'm just trying to understand whether what you are doing might also make sense for us, we are also currently looking into "categorizing" collections.

Best,
Matthias

moreGeo GmbH

Wienburgstraße 207
D-48159 Münster

Telefon: +49 251 2039 8725
Homepage: moregeo.it

Sitz der Gesellschaft: Münster

Registergericht: Amtsgericht Münster, HRB 22852

Geschäftsführer: Matthias Mohr

------ Originalnachricht ------

Von "Robert Dennett" <rtem...@gmail.com>

An "STAC Community" <stac-co...@cloudnativegeo.org>

Cc "matt...@mohr.ws" <matt...@mohr.ws>; "Robert Dennett" <rtem...@gmail.com>; "ico...@element84.com" <ico...@element84.com>; "STAC Community" <stac-co...@cloudnativegeo.org>; "rob.d...@twdb.texas.gov" <rob.d...@twdb.texas.gov>

Datum 12.11.2025 16:13:59

Betreff Re: Is this where I would go to discuss how I created a custom STAC API extension

[Robert Dennett]

I am not entirely sure if I understand that definition.  For our implementation, facets is only applicable to collections, e.g. whether a collection is in the DEM bucket or the Imagery bucket or both.  For us, the items are spatial subunits of the collection, e.g. a quarter quad.  Is that applicable to this?

[Robert Dennett]

If I did that, I gather it would require the approval of a PR for both the stac-fastapi and stac-fastapi-pgstac projects, correct?

[Francis Charette Migneault]

To categorize at the collection level, then Facets/Buckets are not ideal.

Maybe https://github.com/stac-extensions/themes would be more adequate for it?