Introduction

  • RO-Crate provides a structure to make FAIR data packages
  • schema.org in JSON-LD provides a controlled vocabulary for FAIR metadata
  • Each entity of the crate is described separately
  • Cross-references between entities create a graph
  • The RO-Crate specification recommends which types and keys to use

Turning a folder into an RO-Crate

  • Adding a RO-Crate Metadata file to a folder turns it into an RO-Crate
  • The RO-Crate Root is the top-level folder of the crate
  • RO-Crate uses schema.org as base vocabulary
  • The JSON-LD context enables optional Linked Data processing
  • Descriptions are listed flatly as entities in the @graph array

Declaring the root folder

  • The RO-Crate Root is the top-level object of the RO-Crate
  • The root identifier is commonly just ./ for the current folder, but can be a URL
  • The root is always typed as a Dataset, but can have additional types

Describing the root entity

  • Name, description, date published and license are required for the RO-Crate Root
  • RO-Crate allows multiple licenses for different parts

Making a metadata descriptor

  • The RO-Crate Metadata Descriptor describes the JSON-LD file itself
  • RO-Crate specifications are versioned
  • The version of RO-Crate is indicated using the conformsTo property

Adding cross-references

  • The @id uniquely identifies the entity within the RO-Crate
  • Flattened JSON-LD helps keep each entity self-contained
  • Reuse of @id avoids duplication and enables linking

Data entities

  • Data entities are files & folders within the root, as well as external Web references
  • Required properties for files are name and encodingFormat

Contextual entities

  • Contextual entities are not considered part of the crate’s file structure
  • Instruments, software, and projects can be described as contextual entities
  • Contextual entities can provide provenance about data capture and processing

Authorship in crates

  • Authors are described as separate entities
  • Organization entities can be shared by multiple persons having the same affiliation
  • Crate authors made (some) of the crate’s content
  • Publishers of an RO-Crate are typically organizations

Validating JSON-LD

  • RO-Crate metadata files are valid JSON-LD
  • The JSON-LD Playground can do basic validation and visualization
  • Further use of RO-Crate as Linked Data is possible, but may require handling of relative URI references

Converting JSON-LD to triples

  • The JSON-LD @context maps JSON keys to schema.org vocabulary
  • A @base URI is needed to make absolute URIs
  • arcp and UUID can be used for RO-Crates that are not exposed on the Web

Visualizing a crate as HTML preview

  • RO-Crate can be rendered into a HTML preview
  • RO-Crate previews tend to show each entity separately
  • The preview HTML can be added as part of the RO-Crate

Completed RO-Crate

  • A single RO-Crate lists all the entities
  • The order of entities in the @graph array is not important

Avoiding Common pitfalls

  • Include a metadata descriptor with @id: “ro-crate-metadata.json” and @type: “CreativeWork”
  • Ensure each referenced @id is also defined as an entity in @graph
  • Use unique identifiers for each entity
  • Ensure every entity has an @id and a meaningful @type
  • Use tools like JSON validators and JSON-LD playgrounds to check your metadata

Next steps