New fields: stac_api_version and stac_api_extensions

[joshfix]

Looking at Staccato's root catalog (https://stac.boundlessgeo.io/), links are provided for collections, catalogs, and API endpoints, however, the top of the document displays a stac version field:

"stac_version": "1.0.0-beta.1"

If the API and STAC specs a split, should we introduce a stac_api_version field or something similar?

[m-mohr]

(Transferred to api-spec as it seems to be an API issue.) I think you are right, we need stac_* fields also in stac_api_* variants, but to be honest, I don't like that too much. Then our openEO landing page looks like this:

api_version: "1.0.0-rc.2", // openEO version
stac_version: "0.9.0",
stac_api_version: "0.9.0",
stac_extensions: [...],
stac_api_extensions: [...], // or do we follow OGCs conformance classes behavior?
...

[geospatial-jeff]

I think we need either stac_api_* fields as mentioned or to remove ambiguity from the api extensions. Paging is a perfect example. As currently written, if a client wants to use the same pagination logic across potentially multiple api implementations it isn't really possible because (1) an api may or may not implement paging and (2) the rel type used for the previous/next page (or equivalent) may be different across implementations (which unfortunately makes it hard to tell if an api implements paging to begin with). Preventing a client from consistently paginating across api implementations is a pretty big flaw in my opinion.

Here is a good example of a client having to deal with said ambiguity.

[m-mohr]

Another idea could be to re-use OGCs /conformances (not saying I like it), but that would be the OGC API way to specify the version. They don't do it in the landing page /.

(1) an api may or may not implement paging and

It would indeed be useful to specify what extensions are implemented.

(2) the rel type used for the previous/next page (or equivalent) may be different across implementations

I don't understand this. It should always be next for next page. If there's a difference it seems like a wrong implementation?! Can you give an example?

Here is a good example of a client having to deal with said ambiguity.

What exactly is the issue worked around there? I'm not used to read Python...

[geospatial-jeff]

Another idea could be to re-use OGCs /conformances (not saying I like it), but that would be the OGC API way to specify the version. They don't do it in the landing page /.

I think this is fine, isn't this the purpose of a conformance page? I would also be fine with a stac_api_extensions field at the top level of the landing page.

I don't understand this. It should always be next for next page.

Apologies I misread the spec, its the query param that can vary not the rel type.

What exactly is the issue worked around there? I'm not used to read Python...

This use case is simply paginating through a /search response until a certain number of items have been read. Ideally a client would be able to perform this operation on any stac compliant API but currently this isn't convenient because you can't tell whether or not an API implements paging without actually querying the /search endpoint and checking which rel types are available.

[m-mohr]

Only some old STAC versions had a query parameter predefined, but I think all of them had to use next/prev rel types anyway. So using these shouldn't be a problem, I assume. Nevertheless, you don't know without a query to /search whether pagination is a thing or not... Why would you want to know that in advance?

[cholmes]

Just dug into this a bit and I think the best option is probably to re-use OGC's conformance thing. It seems better to re-use it even if we don't love it, especially if no one has any ideas that are clearly a better approach.

We'll have to check with OGC, but I think we can probably just make our own 'conformance classes'? We probably won't define these quite as rigorously as OGC, with specific test assertions for each, but perhaps we could evolve to it.

So I think we'd have something lile:

{
  "conformsTo": [
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core",
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30",
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson"
    "http://stacspec.org/spec/api/1.0.0-beta.1/conf/stac-search"
    "http://stacspec.org/spec/api/1.0.0-beta.1/conf/fields"
    "http://stacspec.org/spec/api/1.0.0-beta.1/conf/sort"
    "http://stacspec.org/spec/api/1.0.0-beta.1/conf/context"
    "http://www.opengis.net/spec/ogcapi-features-3/1.0/req/filter"
    "http://www.opengis.net/spec/ogcapi-features-3/1.0/req/features-filter"
    "http://www.opengis.net/spec/ogcapi-features-3/1.0/req/simple-cql"
    "http://www.opengis.net/spec/ogcapi-features-3/1.0/req/simpletx"
    "http://stacspec.org/spec/api/1.0.0-beta.1/conf/versioning"
  ]
}

This assumes #48 and #51 land (likely a few tweaks). I'm not 100% sure if we name each beta version, but probably? And should check to make sure OGC is ok with us adding in our own conformance locations. My hope is still that many of those evolve to be part of OGC API, but we probably need clearer tests.

Thoughts? @m-mohr / @matthewhanson / @joshfix / @geospatial-jeff / @philvarner and anyone else?

[m-mohr]

Yes, sounds reasonable although I'm not a big fan of the flow with conformances and the landing page: opengeospatial/ogcapi-common#71 It means we need to visit /conformances with all clients before accessing the landing page, which we (usually) don't do yet (AFAIK)...
I don't think there's an issue with adding our own conformance classes to the array.

[jisantuc]

My only objection to re-use of conformance classes is that the documents behind those URLs are not guaranteed to be machine readable -- this would make clients responsible for some kind of string parsing? Or arbitrary HTML parsing? to figure out what the link is actually telling it it can do. It would be valuable for the STAC extensions to link to some JSON that describes the extension -- otherwise clients will have to condition on one of the URL or some data extracted from the page's structure, and those both seem like not great outcomes.

[cholmes]

@m-mohr - Just read that thread - fully agree with you. Could we just say in STAC that our landing page should include the conformance page json in line? We can implement /conformance/ for compatibility, but include the same json in our landing page.

@jisantuc That's an interesting point. I think in OGC land they're more just considered to be like URI's - a unique string that can be referenced. So I was imagining that clients wouldn't actually resolve them. They'd just be checking for the presence of a particular string. If you follow OGC links some redirect you to the html version of their standard, others are just not found.

But I'd potentially be up for doing better in STAC, as I always find it weird in OGC to have a link that does not go to some informative place. Would be nice if it was little or no work to maintain and public the machine readable info. It seems like the only real 'no work' option right now would be to use the openapi fragments in github, like https://raw.githubusercontent.com/radiantearth/stac-spec/v0.9.0/api-spec/extensions/transaction/transaction.fragment.yaml

That said we are publishing JSON Schemas for content extensions right now. So I suppose we could come up with some small JSON description for our OGC Features API extensions. I guess I'm not sure what exactly we'd want in it...

[jisantuc]

@cholmes I think the fragment link idea is interesting... in Franklin we render an OpenAPI spec from our endpoint definitions, so a client would be able to consult the difference between the conformance class and what Franklin will actually do. The only thing missing I think is the extension name, which I could imagine a STAC API browser wanting to get a hold of instead of passing a raw url to the user in the UI.

[m-mohr]

@m-mohr - Just read that thread - fully agree with you. Could we just say in STAC that our landing page should include the conformance page json in line? We can implement /conformance/ for compatibility, but include the same json in our landing page.

I think we can do that, yes.

[cholmes]

I'm going to try to specify this tomorrow. I'm leaning towards http://stacspec.org/spec/api/1.0.0-beta.1/stac-search and just pushing ahead to get it out. But then circling back and we can publish something (openapi fragment / json / html - perhaps all and return based on request type?) there so it actually resolves.

[m-mohr]

Would it make sense to specify multiple conformance classes?

• stac-search for /search
• stac-collections for /collections + id
• stac-items for /collections/id/items + id
• and one for each extension?

Related to discussions in #58

[cholmes]

Yeah, I think that makes sense. And then perhaps does make #58 a bit easier - we just say a compliant STAC API is some subset of the conformance classes.

Though what does '+ id' mean?

[m-mohr]

I'd like that, yes.

Though what does '+ id' mean?

I was lazy. It means for example "stac-collections for GET /collections + GET /collections/{id}"

[m-mohr]

We still need the conformsTo to the landing page OpenAPI schema (@m-mohr) and probably add further documentation (@cholmes ?)!

[cholmes]

I think I'll close this issue since we're 'close' and the bulk of the work is merged. And then we can make more informative ticket titles than 'new fields: stac_api_version...'

[cholmes]

created #74 and #75