#257: Update OpenAPI definition to catalog / dataset definition

[m-mohr]

Fixing #257. Please review it carefully, not sure whether I missed something.

I'll also address #139 here and implement a title for links. This also makes links more consistent with assets.

It adopts to the smaller catalog spec and adds the collection/dataset fields to the WFS-based /collections/... endpoints.

[cholmes]

I'm +1 on merging, though I don't have an implementation that these drive, so it was a more superficial review.

There's two things that I think may be outside the scope of this PR, but would be good to address.

One is that the OpenAPI 'title' of WFS3+STAC document says '(standalone)' instead of 'WFS3'. See

stac-spec/api-spec/WFS3core+STAC.yaml

Line 3 in e22209d

title: The SpatioTemporal Asset Catalog API (standalone)

The other is that the /stac/ endpoint example could use a bit more explanation/text. It'd be good to explain that it can return a Catalog or a Dataset. And that the most common return would be a Catalog that has sub-catalogs of Datasets. And explain a bit that the intent is for users to browse with STAC Browser or for search engines to crawl. So all data exposed in search should be linked to from /stac/, organized in some way.

[m-mohr]

@cholmes I addressed both issues, but of course descriptions and explanations could still be improved further in a seperate PR.

We now have two reviews and would be ready to merge, but I'd still like @hgs-truthe01 to review this PR before as he was the person behind most of the work for the API spec. Do you have some spare time for this, Tim?

[ghost]

I think the basic idea is for the generated files to go in /api-spec/file.yaml and they should be generated from a file of the same name in /definitions/file.yaml. The yaml fragments that contribute to each definition would come from /extensions.

So I would probably move the collections fragment to /extensions.

The WFScore.fragment.yaml file kind of breaks the rule because it isn't really a STAC extension, but it is a fragment. I'm not sure I really like it in definitions, but I wasn't sure where else to put it.

Otherwise looks good to me.

Thanks and sorry I have not been as responsive!

[ghost]

I think I'm going to approve this as is. I think another discussion on fragment organization might be on the table, but I don't think that is needed for 0.6.

[m-mohr]

Okay, thanks.
I agree fragment organization doesn't seem very intuitive. I may just vote to put everything in one directory or so ;)