JSON schemas for endpoints

[matthewhanson]

/ returns a STAC catalog
/collections/{cid} returns a Collection
/collections/{cid}/items/{id} returns an Item

So those can all be validated with the schemas in stac-spec

However:
/collections
/collections/{cid}/items
/search

Don't have any schemas and so can't be validated, those should be added here.

Related to #25

[matthewhanson]

Also note that
/collections/{cid}/items and /search would have the same schema for the response.

[m-mohr]

The OpenAPI basically contains a Schema. Why not validate against the OpenAPI file?

[matthewhanson]

@m-mohr I was wondering if that would work, but wasn't sure...can we use existing validator that you wrote? Would it validate each Item in a search response as well?

[m-mohr]

@m-mohr I was wondering if that would work, but wasn't sure...

There are OpenAPI validators out there, we use a Go-based one in openEO, but it seems not that easy than JSON Schema validation.

can we use existing validator that you wrote?

No, OpenAPI Schema still slightly diverges from JSON Schema and OpenAPI has more things to be checked (e.g. headers).

Would it validate each Item in a search response as well?

No, but a OpenAPI tool would do some checks. Issue is that the OpenAPI is not as detailed as our JSON Schemas (common metadata and extensions are missing for example), but on the other hand it would be a pain to (create and) update both JSON Schemas and OpenAPI files. In the long run we really need JSON Schema support in OpenAPI: https://apisyouwonthate.com/blog/openapi-v31-and-json-schema-2019-09
That makes things in the API so much easier as we could just refer from the API spec back to the STAC JSON Schemas. That's so much more lightweight then...

Related to #8, too

[matthewhanson]

Do not need to duplicate info in JSON Schemas and Open API.

API will define responses in Open API docs, not JSON Schema

[m-mohr]

@m-mohr I was wondering if that would work, but wasn't sure...can we use existing validator that you wrote? Would it validate each Item in a search response as well?

@matthewhanson Yes, it does that since today.