Skip to content Skip to footer

RO-Crate Metadata

Table of contents

  1. RO-Crate uses Linked Data principles
  2. Common principles for RO-Crate entities
  3. Base metadata standard: Schema.org
    1. Differences from Schema.org
  4. Additional metadata standards
  5. Custom RO-Crate terms
  6. Summary of Coverage
  7. Future coverage
  8. Recommended Identifiers

RO-Crate aims to capture and describe the Research Object using structured metadata. Specifically, an RO-Crate is described using JSON-LD by an RO-Crate Metadata Document. As explained in section RO-Crate Structure this may be stored in an RO-Crate Metadata File.

The RO-Crate Metadata Document contains the metadata that describes the RO-Crate and its content, in particular:

  • Root Data Entity - the RO-Crate Dataset itself, a gathering of data
  • Data Entities - the data payload, in the form of files and folders
  • Contextual Entities - related things in the world (e.g. people, organizations, places), providing provenance for the data entities and the RO-Crate.

This machine-readable metadata can also be represented for human consumption in the RO-Crate Website, linking to data and Web resources.

RO-Crate uses Linked Data principles

RO-Crate makes use of the Linked Data principles for its description. In particular:

  1. (Meta)data should be made available as Open Data on the web.
  2. (Meta)data should be machine-readable in a structured format.
  3. (Meta)data should not require proprietary software packages.
  4. (Meta)data should use open standards from W3C, such as RDF and SPARQL.
  5. (Meta)data should link to other people’s data to provide context, using URIs as global identifiers

RO-Crate realizes these principles using a particular set of technologies and best practices:

  1. The RO-Crate Metadata Document can be stored in an RO-Crate Metadata File. The RO-Crate Metadata File and an RO-Crate Website can be directly published on the web together with the RO-Crate payload. In addition, a data package (e.g. BagIt Zip archive) that contains the RO-Crate can also be published on the web.
  2. The RO-Crate Metadata Document is based on the structured data format JSON-LD.
  3. Multiple open source tools/libraries are available for JSON and for JSON-LD.
  4. The RO-Crate Website is HTML 5, and the RO-Crate Metadata Document is JSON-LD, one of the W3C RDF 1.1 formats.
  5. The RO-Crate Metadata Document reuses common vocabularies like Schema.org, and this specification recommends identifiers it should link to.

Common principles for RO-Crate entities

For all entities listed in an RO-Crate Metadata Document the following principles apply:

  1. The entity MUST have an @id (see Describing entities in JSON-LD).
  2. The entity MUST have a @type, which MAY be an array.
  3. The @type SHOULD include at least one Schema.org type that accurately describes the entity. Thing or CreativeWork are valid fallbacks if no alternative external or ad-hoc term is found (see Extending RO-Crate).
  4. The entity SHOULD have a human-readable name, in particular if its @id does not go to a human-readable Web page.
  5. The properties used on the entity SHOULD be applicable to the @type (or superclass) according to their definitions. For instance, the property publisher can be used on a Dataset as it applies to its superclass CreativeWork.
  6. Property references to other entities (e.g. author property to a Person entity) MUST use the { "@id": "..."} object form (see JSON-LD appendix).
  7. The entity SHOULD be ultimately referenceable from the root data entity (possibly through another reachable data entity or contextual entity).

Base metadata standard: Schema.org

Schema.org is the base metadata standard for RO-Crate. Schema.org was chosen because it is widely used on the World Wide Web and supported by search engines, on the assumption that discovery is likely to be maximized if search engines index the content.

RO-Crate relies heavily on Schema.org, using a constrained subset of JSON-LD, and this specification gives opinionated recommendations on how to represent the metadata using existing linked data best practices.

Differences from Schema.org

Generally, the standard type and property names (terms) from Schema.org should be used. However, RO-Crate uses variant names for some elements, specifically:

  • File is mapped to http://schema.org/MediaObject which was chosen as a compromise as it has many of the properties that are needed to describe a generic file. Future versions of Schema.org or a research data extension may re-define File.
  • Journal is mapped to http://schema.org/Periodical.

To simplify processing and avoid confusion with string values, the RO-Crate JSON-LD Context requires URIs and entity references to be given in the form "author": {"@id": "http://example.com/alice"}, even where Schema.org for some properties otherwise permit shorter forms like "author": "http://example.com/alice".

See the appendix RO-Crate JSON-LD for details.

Additional metadata standards

RO-Crate also uses the Portland Common Data Model (PCDM version https://pcdm.org/2016/04/18/models) to describe repositories or collections of digital objects and imports these terms:

RO-Crate uses the Profiles Vocabulary to describe profiles using these terms and definitions:

From Dublin Core Terms RO-Crate uses:

From the IANA link relations registry:

These terms are being proposed by Bioschemas profile ComputationalWorkflow 1.0-RELEASE and FormalParameter 1.0-RELEASE to be integrated into Schema.org:

To support geometry in Places, these terms from the GeoSPARQL ontology:

From CodeMeta 3.0:

Custom RO-Crate terms

The RO-Crate community maintains a common namespace for terms not covered by other vocabularies. This is mainly used by RO-Crate profiles, but the following term is included in the core RO-Crate context:

Summary of Coverage

RO-Crate is simply a way to make metadata assertions about a set of files and folders that make up a Dataset. These assertions can be made at two levels:

  • Assertions at the RO-Crate level: for an RO-Crate to be useful, some metadata should be provided about the dataset as a whole (see minimum requirements for different use-cases below). In the RO-Crate Metadata Document, we distinguish the Root Data Entity, which represents the RO-Crate as a whole, from other Data Entities (files and folders contained in the RO-Crate) and Contextual Entities, e.g. a person, organisation, place related to an RO-Crate Data Entity.
  • Assertions about files and folders contained in the RO-Crate: in addition to providing metadata about the RO-Crate as a whole, RO-Crate allows metadata assertions to be made about any other Data Entity.

This document has guidelines for ways to represent common requirements for describing data in a research context, e.g.:

  • Contact information for a data set.
  • Descriptive information for a dataset and the files within it and their contexts such as an abstract, spatial and temporal coverage.
  • Associated publications.
  • Funding relationships.
  • Provenance information of various kinds; who (people and organizations) and what (instruments and computer programs) created or contributed to the data set and individual files within it.
  • Workflows that operate on the data using standard workflow descriptions, including ‘single step workflows,’ executable files, or environments such as Singularity containers or Jupyter notebooks.

However, as RO-Crate uses the Linked Data principles, adopters of RO-Crate are free to supplement RO-Crate using Schema.org metadata and/or assertions using other Linked Data vocabularies (see Extending RO-Crate).

Future coverage

A future version of this specification will aim to cater for variable-level assertions: in some cases, e.g. for tabular data, additional metadata may be provided about the structure and variables within a given file. See the use case Describe a tabular data file directly in RO-Crate metadata for work-in-progress.

RO-Crate JSON-LD SHOULD use the following IDs where possible:

In the absence of the above, RO-Crates SHOULD contain stable persistent URIs to identify all entities wherever possible.