How to use the library.


Using ro-crate-java is done easily using wide-spread build managers. To find the instructions, visit the maven search page for ro-crate-java and select the latest version. It has up-to-date definitions for a wide range of package managers and offers also manual JAR downloads.

As a visual cue, here is how it looks like for Gradle and Maven. Note that the version number might be outdated.

Example: Gradle

In your build.gradle file, add this line to the dependency section:

implementation 'edu.kit.datamanager:ro-crate-java:1.0.4'

Example: Maven

The configuration in maven is similar:



Please choose the latest version on this page to find more detailed instructions.


Example for a basic crate from RO-Crate website

RoCrate roCrate = new RoCrateBuilder("name", "description").build();

Example adding a File (Data Entity) and a context pair

RoCrate roCrate = new RoCrateBuilder("name", "description")
    .addValuePairToContext("Station", "")
      new FileEntity.FileEntityBuilder()
        .addProperty("name", "Survey responses")
        .addProperty("contentSize", "26452")
        .addProperty("encodingFormat", "text/csv")

Note: Adding an entity with an ID (“@id”) which is already being used by another entity in the crate, the old entity will be overwritten.

The library currently comes with three specialized DataEntities:

  1. DataSetEntity
  2. FileEntity (used in the example above)
  3. WorkflowEntity

If another type of DataEntity is required, the base class DataEntity can be used. Example:

new DataEntity.DataEntityBuilder()
    .addProperty("property from", "value")

Note that here you are supposed to add the type of your DataEntity because it is not known.

A DataEntity and its subclasses can have a local file associated with them, instead of one located on the web (which link is the ID of the data entity). Example:

Example adding file:

new FileEntity.FileEntityBuilder()
    .setSource(new File("file"))
    .addProperty("description", "my new file that I added")

Contextual Entities

Contextual entities cannot be associated with a file (they are pure metadata).

To add a contextual entity to a crate you use the function .addContextualEntity(ContextualEntity entity). Some types of derived/specializes entities are:

  1. OrganizationEntity
  2. PersonEntity
  3. PlaceEntity

If you need another type of contextual entity, use the base class ContextualEntity.

The library provides a way to automatically create contextual entities from external providers. Currently, support for ORCID and ROR is implemented. Example:

PersonEntity person = ORCIDProvider.getPerson("*")
OrganizationEntity organization = RORProvider.getOrganization("*");

Writing Crate to folder or zip file

Writing to folder:

RoCrateWriter folderRoCrateWriter = new RoCrateWriter(new FolderWriter());, "destination");

Writing to zip file:

RoCrateWriter roCrateZipWriter = new RoCrateWriter(new ZipWriter());, "destination");

More writing strategies can be implemented, if required.

Reading / importing Crate from folder or zip

Reading from folder:

RoCrateReader roCrateFolderReader = new RoCrateReader(new FolderReader());
RoCrate res = roCrateFolderReader.readCrate("source");

Reading from zip file:

RoCrateReader roCrateFolderReader = new RoCrateReader(new ZipReader());
RoCrate crate = roCrateFolderReader.readCrate("source");

RO-Crate Website (HTML preview file)

By setting the preview to an AutomaticPreview, the library will automatically create a preview using the ro-crate-html-js tool. It has to be installed using npm install --global ro-crate-html-js in order to use it. If you want to use a custom-made preview, you can set it using the CustomPreview class. AutomaticPreview is currently not set by default.

RoCrate roCrate = new RoCrateBuilder("name", "description")
    .setPreview(new AutomaticPreview())

RO-Crate validation (machine-readable crate profiles)

Right now, the only implemented way of validating a RO-crate is to use a JSON-Schema that the crates metadata JSON file should match. JSON-Schema is an established standard and therefore a good choice for a crate profile. Example:

Validator validator = new Validator(new JsonSchemaValidation("./schema.json"));
boolean valid = validator.validate(crate);