Skip to main content

Capabilities

Declares what an implementation supports — the spec version it targets, whether it provides the optional deposit surface, the registered extensions it implements, the sorts it offers, and the search features it provides.

apiVersionstringrequired

The version of this specification that the implementation targets.

Example: 0.4.0
extensions objectrequired

The registered extensions this implementation provides, as a map of extension identifier to a details object describing how the extension is provided. Presence of a key means the extension is implemented; the value is an empty object when the extension has no extra details to communicate.

Unregistered experimental extensions use an x- prefixed identifier and are outside the scope of this specification.

segmentsobject

Details the implementation communicates about its segments support. The extension currently has no extra details to communicate; the value is an empty object.

property name*object
deposit objectrequired

Declares whether the implementation provides the optional deposit surface, and on what terms. This block is REQUIRED in /capabilities: every implementation states its position explicitly, so a client never has to infer read-only-ness from a missing key.

supported is the single flag clients check. When it is true the implementation provides the deposit and RO-Crate endpoints, and idMinting and fileUpload MUST also be present. When it is false the implementation is read-only, the deposit and RO-Crate endpoints are not provided, and the remaining fields MUST be omitted.

Deletion behaviour is declared separately, in the top-level tombstonePolicy.

supportedbooleanrequired

Whether the implementation provides the deposit surface. true - deposits are accepted and the deposit and RO-Crate endpoints are available; false - the implementation is read-only.

Example: true
idMintingstring

How RO-Crate IDs are minted at deposit creation. client - the client MUST propose an ID; server - the server always mints one; both - the client MAY propose an ID and the server mints one when absent.

Possible values: [client, server, both]

Example: both
fileUploadstring[]

The file staging modes the implementation supports on PUT /deposit/{id}/file/{fileId}. inline - the file's bytes in the request body; presigned - transport metadata in the request, bytes uploaded directly to a returned target. New modes may be added by revision of this specification; clients MUST ignore values they do not recognise.

Possible values: [inline, presigned], >= 1

Example: ["inline","presigned"]
depositTtlSecondsinteger

How long an open deposit lives before expiring. When absent, expiry is implementation-defined and clients should not rely on any particular TTL.

Possible values: >= 1

Example: 604800
maxFileSizeBytesinteger<int64>

The largest file the implementation accepts in a deposit. When absent, no limit is declared.

Possible values: >= 1

Example: 5368709120
tombstonePolicystringrequired

What deleted resource URIs return. "410" - deleted URIs respond 410 Gone with a Tombstone body; "404" - deleted resources are indistinguishable from those that never existed. One policy covers RO-Crate, entity and file URIs alike; implementations MUST NOT mix them.

REQUIRED of every implementation, whether or not it provides the deposit surface: entities and files are mandatory core, so any catalog may hold a URI that no longer resolves.

Possible values: [410, 404]

Example: 410
sorts objectrequired

The sorts the implementation supports on POST /search and GET /entities, as a map of sort name to its declaration. A request using a sort not declared here MUST be rejected with a 400 ValidationError. Every sort supports both asc and desc order.

Every sort MUST give the same order on every page of the same request. The implementation chooses how to break ties (for example, by id).

id, the default for GET /entities, MUST be declared. relevance is not declared here: it is always available on POST /search, and never on GET /entities.

id objectrequired

Describes a sort the implementation supports.

labelstring

An optional human-readable display label for the sort.

Example: Name
property name* SortCapability

Describes a sort the implementation supports.

labelstring

An optional human-readable display label for the sort.

Example: Name
search objectrequired

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
Capabilities
{
"apiVersion": "0.4.0",
"extensions": {
"segments": {}
},
"deposit": {
"supported": true,
"idMinting": "both",
"fileUpload": [
"inline",
"presigned"
]
},
"tombstonePolicy": "410",
"sorts": {
"id": {
"label": "Identifier"
},
"name": {
"label": "Name"
},
"originatedOn": {
"label": "Origination date"
}
},
"search": {
"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": {}
}
}
}