Mention ItemCollection in Markdown

[matthewhanson]

ItemCollection is being removed from core, discuss if it belongs here.

[geospatial-jeff]

I think it should be included in the api spec. I can't come up with a better replacement for representing groups of items in /collections/{collectionId}/items and /search responses. Having a feature collection just makes sense since items extend geojson features.

The most atomic response is just an array of stac items, but there is value in adding the extra top level fields to create a feature collection for client compatibility.

I also think keeping the top level response as an object is valuable for adding other fields (ex. context/paging extension).

[matthewhanson]

Discussed in Sprint 6, decided we don't need both JSON schema and OpenAPI.

OpenAPI docs should define the search response, closing.

[philvarner]

Discussed in Sprint 6, decided we don't need both JSON schema and OpenAPI.

OpenAPI docs should define the search response, closing.

@matthewhanson we do need to add the markdown description of ItemCollection and the sample files, correct? I'll do this, but wanted to check before creating a PR.

[philvarner]

@matthewhanson also related to this is using https://github.com/sparkgeo/stac-validator requires JSON schema definitions, and it would be useful to be able to validate API responses using this in addition to Catalogs and Items.

[m-mohr]

OpenAPI files are basically JSON Schema with the nullable exception, but some JSON Schema validators even understand that.

And I don't think we need a markdown description. It's described in the (rendered) OpenAPI Files, too. Also, I don't see why we would need it for that particular response, but not the others (e.g. /collections).

Generally, we are in the API part here and not in STAC core spec. So here we use OpenAPI, not JSON Schema and markdown files like in the core spec.

[cholmes]

I'm re-opening this, since I think we need at least some reference somewhere in the markdown. There are a couple references in the API spec, and it'd be weird to dump people straight into an OpenAPI document. I think it can be a brief reference, but I'd like something to link to.

[cholmes]

@m-mohr - was your thumbs down that I shouldn't include a reference in the API spec?