Add conformance class information #60
Conversation
|
@m-mohr - Ok, I'm still working through this, but was curious on feedback, as I don't think I have it right. I've got the three conformance classes as you laid them out. But I said STAC Collections 'depends' on OGC API - Features core. But I don't think that's right, since you don't fully implement 'core', since it has items and you don't? I wanted to say a valid STAC is either /search or /collections. But that doesn't seem to work. So it's implement either STAC Collections or (STAC search or STAC Items)? Which seems a bit complicated to explain. And then I'm also not sure how to handle / in STAC, where that fits in. We say it 'Extends / from OAFeat to return a full STAC catalog.' It feels like the easy thing may be to just drop our notion that /search would be implemented without implementing OGC API - Features... We could tell people if they wanted to just have a single endpoint to put all their features under a single collections/collectionsId endpoint. I'll keep working away on fleshing this out... |
|
Ah, interesting, looking at https://earthengine.openeo.org/v1.0 I see that you do have conformance/ and it says you implement http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core. So I guess we could say STAC Collections depends on core, and then STAC Items would depend on GeoJSON. Hrm, though it looks like you don't actually implement the /service-desc endpoint. Looking at all the OGC requirements again does make me want to be able to offer something simpler - like just the /search/ endpoint and /conformance with a hardcoded value. Or /collections without more overhead. Perhaps we have a stac-core that is the landing page (stac catalog and conformance/ (borrowed from / compatible to OAFeat) and collections/ ? With /search optional, and you can use the collectionId's to limit your search, but you don't have to implement collections/{id}/items for all collections - that'd be the stac-items class? |
|
It's already weekend here, but just quickly some remarks regarding conformance classes: https://earthengine.openeo.org/v1.0 is likely not 100% compliant with Features Core. As you said, service-desc is missing (service-doc as well). It was always a pain that OGC requires them and personally I think they are usually not very useful anyway. But regardless, although I have copy&pasted http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core into the /conformances, it is not conformant as I have not implemened the .../items/... endpoints, but those are required by core, I think. Its just there because there's nothing else to put there yet. Once we have the STAC conformance classes, I'll likely just list stac-collections and drop the features conformance or replace it with OGC API Commons conformance classes...
Unfortunately, I think it doesn't work that way... Maybe it's better to base things on OGC API Commons in general and make featues conformance optional, because that is actually only implemented if you have met all Features requirements, which not many STAC APIs actually have. +1 on simplcity. Maybe we can discuss a bit more on Monday during this late call? |
You mean the one at 1pm pacific I was going to do with Matt? That'd be great if you could join, though that is quite late. I could also try to get up early, like 6am, and call before Lumi (hopefully) wakes up. |
|
Thanks for the late-night thoughts, it's helpful to me. I'll see if I can come up with something, though may not find much work time between now and monday. Digging into OGC Common a bit it seems like they don't have the simplicity we're hoping for. Which is a bummer because I got excited about that idea: They seem to require /api on the very core - http://docs.opengeospatial.org/DRAFTS/19-072.html#resource-requirements-section And then the collections conformance class seems to talk about items and querying them: http://docs.opengeospatial.org/DRAFTS/20-024.html#rc_collections-section Why oh why? So I think we should just probably decide what our 'core' is, layer on /search, and have optional OAFeat conformance classes. But yeah, would be good to talk through what our 'core' is - could be more than one conformance class potentially. I do feel it does hit up against the core structure of child vs collection stuff, but maybe we can get a plan for it, or figure out how to get an iterative step out now. |
|
I don't think the documents you are referring to are up-to-date. Afaik, /api is not required itself, although service-desc/doc are required als links, which must point to something that was previously at /api. It's basically the same, just not at a specific location. Unfortunately, this is also required in Features (and most of us ignore that), so there's no real difference between Features and Commons, I think. |
|
Still trying to wrap my head around this, so based on our conversation Monday there should be a conformance class for STAC root catalog, and the bare minimum STAC "API" would conform to this + GeoJSON conf class...right? Also, technically as we discussed, these two conf classes could apply to a static catalog as well. So conf classes can't "depend" on others? |
|
My notes from monday are we'd do:
stac-search - Is a conformance class for the search endpoints. Matthias said we could split into post and get. I'm inclined to have the conformance class require GET, with POST optional. It seems like clients could discover on their own if POST was supported. ogc api commons part 2: collections - Conformance class if you support collections. ogc api features - for collections/{collectionId}/items and querying that. Would be features core, features geojson and features openapi conformance classes. stac-spec - If implementing OGC API collections and/or commons this is used to say that the returned collections and items are STAC compliant. I remember us talking about the geojson requirement class in our 'core', but I think that may not be right - need to understand if OGC API - Features geojson requirements class is truly stand alone and reusable, or if it depends on core. As for conf classes 'depending' on others, I'd guess the clearest is to declare them all, so a client can look for what it needs, instead of having to know somehow that the class they're looking for is implicitly declared in another class. |
|
Ok, this sounds good to me, an example landing page would be useful inline here, to indicate what links would match up with which conformance classes. |
|
We could theoretically have stac core only have conformance at /, but I think it probably makes sense to have it at / and /conformance. I think it totally makes sense to just have / in core and leave /conformance to OGC, saying that if OGC API - Features is implemented, /conformance should reflect the conformances in /. I don't see any benefit to have it in core.
I think I'd split them as they are quite a bit different and it's easier to discover, but it's not a strong preference. I also don't have a better argument yet. ;-)
No, it's geojson that is implcitly (or explicitly) defined through stac-search and stac-spec. Core itself has no relation with geojson (the landing page is just a catalog).
Yeah, I think I agree... but not 100% sure yet. ;-) Could we quickly come up with a full list of names/URLs here? I think it would be useful to structure the repo and OpenAPI files etc... |
Cool, I'm convinced.
I think I'd prefer to start with less conformance classes then expand.
Ah, right, I forgot that just collections wouldn't have any geojson.
That'll be my priority for tonight, will try to at least commit a rough draft. Then will circle back from there tomorrow and flesh out the text. Good idea on structuring the openapi files. |
|
Ok, didn't quite get as far as I wanted, but hopefully there's enough to give feedback on - I'm sure I had some things off. I was most unsure about the dependency on commons. @m-mohr - I couldn't figure out if the commons collection conformance meant you needed to implement /conformance. The other thing I'm not sure about is how you would have a server that had OGC API features collections where some were STAC and some were just Features (like buildings - something without assets). The way that made sense to me is that all are valid features, and then some would be STAC, and you could have them all on the same landing page / collection list. But it seems like with our 'stac response' (what I named 'stac spec', since that seemed ambiguous, but I'm open to other names), then that wouldn't be possible? Since you'd declare the stac response conformance class, and then clients would expect that everything conforms to STAC. Unless you listed them from another landing page. Then I wonder if it's really necessary, etc. Any feedback is welcome, I'm not attached to anything here, just trying to get down what we talked about, and I'm sure some things are off. |
|
@m-mohr + @matthewhanson - ok, made more progress, redid the overview to try to give a good intro to things as we discussed. I'll continue on, but would be great to review that, and the conformance classes at the bottom (I'll move them up somewhere most likely) |
api-spec.md
Outdated
| fields](stac-spec/collection-spec/collection-spec.md#collection-fields). STAC API's are expected to return STAC | ||
| compliant Collections. | ||
|
|
||
| Some STAC API implementations just use it to describe their Collections, without providing search of individual |
There was a problem hiding this comment.
"just use "it to describe their collections....not clear what "it" refers to, the data rel type? Collections endpoint?
There was a problem hiding this comment.
Will clarify, but yes - just use the collections endpoint (linked to with the data rel type) to describe collections, without returning items.
api-spec.md
Outdated
| to navigate down to additional Catalogs, Collections & Items. | ||
| - The `links` section is a required part of STAC Catalog, and serves as the list of API endpoints. These can live at any location, the | ||
| client must inspect the the `rel` to understand what capabilities are offered at each location. | ||
| - The `conformsTo` section follows exactly the structure of OGC API - Features [declaration of conformance |
There was a problem hiding this comment.
I'm not completely sold on breaking from OGC API, how many users are really going to use the conformance classes enough so they should be at landing page? Don't the provided links indicate what capabilities are provided? I'm not sure it's worth doing something different.
There was a problem hiding this comment.
I can still go either way. Was compelled by @m-mohr's arguments, I think the main ones are opengeospatial/ogcapi-common#71 I tend to think about being nicer to clients, particularly javascript ones, and saving an extra request just to get conformance seems nice. I wouldn't say it's 'breaking' with OGC API, it's just a nice shortcut if OGC API is implemented, and if it's not implemented then it's a straightforward path.
There was a problem hiding this comment.
Oh, and the point to me isn't users - it's programmatic clients, that read the conformance classes to figure out the capabilities. Like can it make a 'sort' or 'fields' query, or does it have to request everything and do sort / fields on the client side? Is CQL supported? Etc. I think most API clients will want to know what extensions are available, so let them do it with their first request.
|
Ok, I think I'm to a decent draft, though still need to do the 'extensions' section, which should be easy. @m-mohr + @matthewhanson - the one area that didn't work so well was the Collections and STAC Response (what I called the conformance class that says this returns STAC). Collections felt really lame since OGC hasn't released any drafts, so to be sure I got the right version I'd link to https://github.com/opengeospatial/ogcapi-common/blob/cc8ca2f011d7e1b19721268c4bf2b97c163d160a/20-024.pdf or https://github.com/opengeospatial/ogcapi-common/tree/cc8ca2f011d7e1b19721268c4bf2b97c163d160a/collections I'm strongly leaning towards not declaring a dependency on OGC API Commons Part 2: Collections, but just sub-setting the OGC API Features collection section, specifying it in STAC, and noting that we aim to align with OGC API Common when it is released. I'm also thinking about just eliminating the STAC Response / stac-spec thing. Not sure if you saw my comment above:
I think the conformance is all about the API capabilities, and these are really about the content response. Perhaps at some point OGC will have a way to indicate content response compliance. I wonder in the meantime if we could just add a But for now I'm inclined to just leave it off of 'conformance'. Making our own Collection conformance class makes this easier - |
|
I've restructured again as discussed with Matt, there's now fragments and extensions. Don't have the time right now to explain it in detail, let's discuss later. I've continued to fix OpenAPI files, I still need to work on Transactions and Version at least. |
This reverts commit f691ca2. # Conflicts: # overview.md
|
Okay, I managed to restructure/fix all the OpenAPI files. @matthewhanson You can start with the CI work. |
…vely useless with the introduction of conformance classes and is partly migrated to other documents)
|
This is now the chance to add an ItemCollection fragment in a place where it really fits (fragments/item-collection), see #25 We can easily move the itemCollection schema from commons and then add the old ItemCollection.md from the Git history. |
|
+1 on getting ItemCollection right. I redid f691ca2 and then cleaned it up so it only talks about search. It was weird to me it talked about other stuff, so that's why I put it in overview, where it's cool to touch on everything. So just made it so it makes sense in this file. May do some sort of http section in the overview. |
|
@matthewhanson @cholmes I've moved folders and fixed the OpenAPI refs, now there are likely some broken links. Some thoughts:
|
|
Awesome, thanks!
I get it, but can't yet think of any other good alternatives. Could put core,item-search,etc in 'spec' or something, but then not sure that helps.
So search and query live in fragments? But then the item search openapi.yaml includes those fragments? It seems like an ideal could be an openapi.yaml that's just the core, and openapi-ext.yaml that includes them? But if that's not possible I think it's ok.
One level up like ogcapi-features/transactions and ogcapi-features/version instead of ogcapi-features/extension/transaction? I'd lean towards ogcapi-features/extensions/ that has transactions.md & transactions.yaml in it. Not set on any of it though.
I can do that. @m-mohr or @matthewhanson - can one of you approve so I'm able to merge? I'll fix the links to get CI building, and do some clean up before I merge. But want to be able to do it today and have us shift to PR's that are easier to review, as discussed. |
Related Issue(s): #12, #25, #27, #58
Proposed Changes:
PR Checklist:
npm run generate-allto update the generated OpenAPI files.