SearchCapability

Declares what the implementation's search endpoint supports — the filters that may be used in search requests and the facets returned in search responses.

Every field declared in facets MUST also be declared in filters, so that clients can always turn a facet value the user clicks into a filter on the next request. Filter-only fields (for example date fields, which are filterable but not meaningful as facets) are permitted.

filters objectrequired

The fields that may be used in the search request's filters object, as a map of field name to a declaration of the field's type and display label. Requests using a field not declared here MUST be rejected with a 400 ValidationError.

property name* FilterCapability

Describes a search filter field the implementation supports. The type tells clients which UI element suits the field (e.g. a date picker for date, a toggle for boolean) and which request syntax the field accepts: date and number filters accept a single range object or a non-empty array of range objects (matched as an OR of the ranges) as well as an array of values; string and boolean filters accept an array of values only.

New filter types are added by revision of this specification; clients MUST hide filters with a type value they do not recognise rather than fail.

typestringrequired

The filter's value type. date values are ISO 8601 strings. boolean values are the strings "true" and "false".

Possible values: [string, date, number, boolean]

Example: date

labelstring

An optional human-readable display label for the filter field.

Example: Date created

facets objectrequired

The facet fields the implementation supports in search responses, as a map of facet field name to its declaration. Every field listed here MUST also appear in filters.

property name* FacetCapability

Describes a search facet field the implementation supports.

labelstring

An optional human-readable display label for the facet field.

Example: Language

SearchCapability

{
  "filters": {
    "inLanguage": {
      "type": "string",
      "label": "Language"
    },
    "mediaType": {
      "type": "string"
    },
    "createdAt": {
      "type": "date",
      "label": "Date created"
    }
  },
  "facets": {
    "inLanguage": {
      "label": "Language"
    },
    "mediaType": {}
  }
}