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.
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.
An optional human-readable display label for the field.
Titlegeo 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.
Whether geo search is provided.
trueThe 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
10000filters 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.
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]
dateAn optional human-readable display label for the filter field.
Date createdfacets 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.
An optional human-readable display label for the facet field.
Language{
"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": {}
}
}