propose adding context object for search metadata

[matthewhanson]

numberReturned, numberMatched, and limit are fields returned at the top level of a Feature API search, which provide metadata about the search request. They are not currently in Commons, only Feature API.

I'd propose adding this to Commons and combining these into a single context object containing search metadata fields, e.g.,

context = {
  "limit": 10,
  "returned": 10,
  "matched": 12
}

The reason for grouping them is that they are conceptually related and allows for adding other fields (e.g., page) without polluting the top level metadata.

We have this as an extension in STAC:
https://github.com/radiantearth/stac-spec/tree/master/api-spec/extensions/context

Example implementation:
https://fn8d3qzbhk.execute-api.us-west-2.amazonaws.com/omega/search

[cmheazel]

These fields have been added to common. Open issue is whether they should reside in a single element.

[jerstlouis]

Related to main issue #314 (reorganization of Simple Query into something more aligned with Records Local Resourc Catalog).

[rob-metalinkage]

note context is very similar to @context which will certainly be used in some applications to annotate as JSON-LD

• parameters might be a better choice.

[jerstlouis]

@rob-metalinkage The intent would be to follow the OGC API - Records Local Resource Catalogs approach.

Potentially this would mean having numberReturned and numberMatched directly as root property of the collections list response. I don't think limit (which is the one thing that is truly a supplied parameter) was ever returned as a property in Features or Records -- perhaps it was in STAC?. The limit is usually implied within the opaque next / prev links.

@pvretano @kalxas @tomkralidis
I am a bit confused how the 9.4. Requirements Class "Local Resources Catalog" (Deployment) could inherit these numberReturned and numberMatched fields, which may only be defined in OGC API - Features which is only a dependency of "9.3. Requirements Class "Searchable Catalog" (Deployment)" but not of 9.4. Requirements Class "Local Resources Catalog" (Deployment) ?

This is part of why I was suggesting that "9.3. Requirements Class "Searchable Catalog" (Deployment)" be called a "Record Collection" (where records are at /collections/{collectionId}/items/{recordId} and there is a dependency on OGC API - Features) rather than a "Searchable Catalog", because in fact catalogs of Collections, Processes and Scenes are also "searchable" (as indicated per the 9.4.5. Requirements Class "Local Resources Catalog - Sorting" (Deployment) and 9.4.6. Requirements Class "Local Resources Catalog - Filtering" (Deployment)).

If the parameters requirement classes (Core Query Parameters, Sorting, Filtering) were made orthogonal to the origins (Local Resource Catalogs or Record Collection), there may not be a need to define multiple sub-requirement classes inside each deployment requirement class (for filter (9.3.2, 9.4.6) and sort (9.3.1, 9.4.5)), or even to have separate Building Block (8.6, 8.7) vs. Deployment requirement class).
That was the essence of my original suggestion. In other words, I think the req. classes organization could still be simplified a lot (fewer req. classes) achieving the same degree of modularity / use cases.