Skip to main content

SearchCapability

Declares what the implementation's search endpoint supports — the search types, geo support, 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 (for a date facet, as a year range). Filter-only fields are permitted.

searchTypes objectrequired

The search types the implementation supports, as a map of search type to its details. Presence of a key means the search type is supported. basic is always present; advanced is optional.

A search request with a searchType not declared here MUST be rejected with a 400 ValidationError. New search types are added by revision of this specification; clients MUST ignore search types they do not recognise.

basicobjectrequired

Basic search. It has no details to communicate; the value is an empty object.

advanced object

Declares advanced search, and the fields an advanced query may name.

fields objectrequired

The fields an advanced query may name, as a map of field name to its declaration. Every advanced field matches as text. A query naming a field not declared here MUST be rejected with a 422.

property name* AdvancedFieldCapability

Describes a field an advanced query may name.

labelstring

An optional human-readable display label for the field.

Example: Title
geo objectrequired

Declares whether the implementation supports geo search: boundingBox and geohashPrecision in search requests, and geohashGrid in search responses. This block is REQUIRED: every implementation states its position explicitly.

When supported is false, a search request with boundingBox or geohashPrecision MUST be rejected with a 400 ValidationError.

supportedbooleanrequired

Whether geo search is provided.

Example: true
maxResultWindowinteger

The largest offset + limit that POST /search serves. A request past it MUST be rejected with a 400 ValidationError. Absent means no limit.

Possible values: >= 1

Example: 10000
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. A date value is either a calendar date (YYYY-MM-DD) or a full RFC 3339 date-time; see FilterRange for how each resolves, in exact values as well as in range bounds. 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, with type string, boolean or date; a number filter cannot be a facet. An implementation that supports no facets declares {}.

A date facet's buckets are UTC years. To filter on one, a client sends the year as a range: { "gte": "2001-01-01", "lte": "2001-12-31" }.

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
{
"searchTypes": {
"basic": {},
"advanced": {
"fields": {
"name": {
"label": "Title"
},
"description": {}
}
}
},
"geo": {
"supported": true
},
"maxResultWindow": 10000,
"filters": {
"inLanguage": {
"type": "string",
"label": "Language"
},
"mediaType": {
"type": "string"
},
"createdAt": {
"type": "date",
"label": "Date created"
}
},
"facets": {
"inLanguage": {
"label": "Language"
},
"mediaType": {}
}
}