API

General

This server allows import ad exporting metadata objects with schemas and ontological annotations based on a specific RO-Crate profile.

It is built on this profile: https://github.com/researchobjectschema/ro-crate-interoperability-profile/blob/main/0.2.x/spec.md

There is a openAPI specification for documentation purposes: https://github.com/paulscherrerinstitute/rocrate-api/blob/main/openapi.yaml Please note that the contents of the manifest are not deserialized as shown in the openAPI specification.

Endpoints

Currently, there are three endpoints

Export: export openBIS objects based on identifier, permID or annotated properties
Validate: check internal consistency of RO-Crate
Import: import RO-Crate into openBIS

Export

<openbis-url>/ro-crate-server/export

In the header, the following arguments are available

Header	Values	Required	Description
`Accept`	`application/ld+json` for the manifest, `application/zip` for the crate	Yes	HTTP Accept header
`Content-Type`	`application/json`	Yes	HTTP Content type header
`api-key`	openBIS session token or openBIS personal access token	Yes	Token for accessing openBIS
`openbis.identifier-annotations`	Semantic annotation for identifiers used in	No	Used
`openbis.with-levels-below`	Standard openBIS config option for export	No	openBIS setting for export
`openbis.with-objects-and-dataSets-parents`	Standard openBIS config option for export	No	openBIS setting for export
`openbis.with-objects-and-dataSets-other-spaces`	Standard openBIS config option for export	No	openBIS setting for export

The body of the request is an array of strings. These strings are identifiers. These can be

openBIS identifiers, e.g. /SPACE/PROJECT/ENTRY1
openBIS permIDs, e.g. 20250730131201280-261
an annotation to specify, defaults to . Properties annotated with this property are queried. All of these are searched and the results are written to the RO-Crate

Validate

<openbis-url>/ro-crate-server/validate

This performs internal validation of the RO-Crate. This means:

Checking that mandatory properties are present
Checking that the values of properties have the correct data types
Check that referenced objects are present

Header	Values	Required	Description
`Accept`	`application/json`	Yes	HTTP Accept header
`Content-Type`	`application/ld+json` for the manifest, `application/zip` for the crate	Yes	HTTP Content type header
`api-key`	openBIS session token or openBIS personal access token	Yes	Token for accessing openBIS

Feedback is provided by entities and properties with problems. It follows ch.ethz.sis.rocrateserver.openapi.v1.service.response.Validation.ValidationReport. Returns a validation report. It includes all issues found as well as all entities found.

Import

<openbis-url>/ro-crate-server/import

First, it performs the same checks as validate.

Header	Values	Required	Description
`Accept`	`application/json`	Yes	HTTP Accept header
`Content-Type`	`application/ld+json` for the manifest, `application/zip` for the crate	Yes	HTTP Content type header
`api-key`	openBIS session token or openBIS personal access token	Yes	Token for accessing openBIS
`openbis.import-mode`	Based on `ch.ethz.sis.openbis.generic.asapi.v3.dto.importer.options.ImportMode`, defaults to `UPDATE_IF_EXISTS`	No

Afterward, the import is converted into an openBIS excel. This is sent to the application server for the actual import. Feedback is a map of identifiers in the crate to identifiers of imported openBIS objects. ch.ethz.sis.rocrateserver.openapi.v1.service.delegates.ImportDelegate.OpenBisImportResult is the response type.