Source-linked AI summary
Packaging research artefacts with RO-Crate
Stian Soiland-Reyes, Peter Sefton, Mercè Crosas, Leyla Jael Castro, Frederik Coppens, José M. Fernández, Daniel Garijo, Björn Grüning, Marco La Rosa, Simone Leo, Eoghan Ó Carragáin, Marc Portier, Ana Trisovic, RO-Crate Community, Paul Groth, Carole Goble
TL;DR
Research publications often inadequately connect and describe the datasets, software, methods, and dependencies needed for reproducibility and machine processing. The paper introduces RO-Crate, a lightweight community approach that packages research artefacts with structured metadata and relationships. RO-Crate supports FAIR data exchange, preservation, and use across diverse domains, while provenance completeness remains constrained by gaps in source systems and dependency reproducibility.
Problem
Research artefacts and their dependencies need to be published together, but existing approaches can be difficult to interconnect, access programmatically, and adopt.
Method
RO-Crate packages research artefacts with structured metadata and relationships using lightweight Linked Data practices and open community tooling.
Results
RO-Crate supports data and metadata exchange, long-term preservation, repository integration, and use by individual researchers across varied scholarly contexts.
Takeaways & Limitations
RO-Crate offers a general-purpose way to make research outputs FAIR through accessible packaging, community-supported profiles, and continuously expanding tools.
Takeaways & Limitations
Complete provenance representation is ideal rather than guaranteed, because gaps in data sources, workflows, engines, and dependencies remain.
Abstract
from arXiv · showhide
An increasing number of researchers support reproducibility by including pointers to and descriptions of datasets, software and methods in their publications. However, scientific articles may be ambiguous, incomplete and difficult to process by automated systems. In this paper we introduce RO-Crate, an open, community-driven, and lightweight approach to packaging research artefacts along with their metadata in a machine readable manner. RO-Crate is based on Schema$.$org annotations in JSON-LD, aiming to establish best practices to formally describe metadata in an accessible and practical way for their use in a wide variety of situations. An RO-Crate is a structured archive of all the items that contributed to a research outcome, including their identifiers, provenance, relations and annotations. As a general purpose packaging approach for data and their metadata, RO-Crate is used across multiple areas, including bioinformatics, digital humanities and regulatory sciences. By applying "just enough" Linked Data standards, RO-Crate simplifies the process of making research outputs FAIR while also enhancing research reproducibility. An RO-Crate for this article is available at https://w3id.org/ro/doi/10.5281/zenodo.5146227
1. Introduction
Open Science has increased demand for publishing research artefacts, but connecting and describing these resources for reproducibility and machine processing remains difficult. RO-Crate is introduced as a simpler, community-developed approach to aggregate artefacts with metadata and relationships for FAIR research.
- Computational research increasingly requires publishing software, datasets, and experiment dependencies alongside research outputs.
- FAIR principles guide artefact publication, but do not prescribe a particular implementation strategy.
- Existing platforms support metadata-rich publication and reproducible software, yet greater emphasis is needed on interconnecting research artefacts.
- Research Objects aggregate distributed resources with semantic annotations describing artefact context and relationships.
- Existing Research Object implementations can require large technology stacks, platform-specific designs, and expertise beyond typical end-users.
- RO-Crate packages research artefacts with metadata and relationships, introduces the approach and ecosystem, and demonstrates usage across communities.
2. RO-Crate
RO-Crate packages inter-related research materials with metadata so that archives are both human-readable and programmatically usable. It addresses adoption barriers through conceptual simplicity, integration tooling, best-practice guidance, and familiar Web standards.
- RO-Crate groups inter-related outputs, code, data, reports, and metadata in an accessible research package.
- Compressed archives solve packaging but do not guarantee programmatic access or descriptions of each artefact’s role.
- Metadata approaches across research and library systems often require schema knowledge, specialised annotation systems, or complex software stacks.
- RO-Crate seeks conceptual simplicity, strong integration tooling, opinionated best-practice guidance, and widely used Web standards.
2.1. Development Methodology
RO-Crate’s development methodology prioritised developer friendliness through close collaboration with early adopters. User-facing simplicity is addressed through interactive tools, domain discussions, and extensible profiles.
- Simplicity was defined for both platform developers and data practitioners using those platforms.
- The methodology used a small group, rapid feedback loops, and early adopters from multiple disciplines, initially prioritising developer friendliness.
- The design assumed developers familiar with Web applications and JSON, shaping JSON-level documentation and RO-Crate serialization.
- Interactive tools, Jupyter notebooks, and discussions with domain scientists support data-practitioner understanding and user-driven profiles.
2.2. Conceptual Definition
RO-Crate realizes Research Objects as self-described packages that combine artefacts, metadata, provenance and relationships using Linked Data identifiers. Its model supports embedded or externally referenced resources, multiple packaging formats, and bounded, practical description practices.
- Linked Data foundation: RO-Crate uses a metadata file and Linked Data identifiers to describe a Research Object, its contents, relationships and provenance.The model uses IRIs for the crate, constituent parts, metadata descriptions, properties and classes.
- Packaging and access: RO-Crates can be stored, transferred or published as BagIt, OCFL, ZIP archives, dedicated repositories, or directly on the Web.This supports varied storage and access requirements across scientific domains, including large genomic datasets and restricted cultural-heritage records.
- Entity model: Data entities may be files, directories, Web resources or restricted data, while contextual entities describe people, workflows and other resources through metadata.The distinction between data and contextual entities can be blurred because both are identified by IRIs and may have Web presences.
- Self-described container: A RO-Crate root is a directory identified by ro-crate-metadata.json, which describes the crate, its content and related metadata in JSON-LD.The metadata file is human-readable JSON and supports data exchange through available programming-language tooling.
- Recommended practices and profiles: The specification applies existing standards as recommended practices, while formalization emphasizes a bounded structure represented as a depth-limited tree.RO-Crate profiles can further formalize expectations and conformance for particular communities or use cases.
2.3. Technical implementation of the RO-Crate model
RO-Crate constrains JSON-LD into a developer-oriented, flattened JSON representation while retaining Linked Data semantics. Its versioned context and extensibility support simpler processing and integration with domain vocabularies and open community tooling.
- Design rationale: RO-Crate realizes its conceptual model using JSON-LD and Schema.org in a prescriptive form to simplify developer use.JSON-LD expresses Linked Data as JSON, lowering the barrier relative to other RDF syntaxes.
- Design rationale: Because unrestricted JSON-LD has too many degrees of freedom, RO-Crate specifies an acceptable subset of JSON structures.This constraint is intended to make reliable production and consumption possible without specialized expertise or large RDF frameworks.
- Flattened JSON-LD: RO-Crate mandates flattened, compacted JSON-LD in ro-crate-metadata.json, with one @graph array containing all data and contextual entities.Entities are cross-referenced through @id values in the flat graph.
- Flattened JSON-LD: The flat @graph lets applications process and edit entities as pure JSON through simple @id lookup while preserving graph relationships.Lifting entities to one level also emphasizes context and provenance alongside data.
- Contexts and extensibility: RO-Crate uses a versioned JSON-LD context mapping Schema.org terms and allowing additional vocabularies such as PCDM and Bioschemas.Profiles may extend the context with domain-specific ontologies.
- Community and tooling: Open development platforms support specification access, implementation discussion and evolving best practices needed to build and consume FAIR research artefacts.The community also uses interactive tools and domain discussions to address practitioner needs.
3. RO-Crate Tooling
RO-Crate tooling spans programming languages, research environments, and user types, but most implementations remain at the Beta stage as the specification stabilizes.
- Implementations support commonly used languages including Python, JavaScript, and Ruby.
- The tooling integrates with research environments through command-line utilities, human-readable previews, and end-user platforms.
- Most tools are in the Beta stage, partly because the RO-Crate specification only recently reached version 1.0.Version 1.0 was reached in November 2019, while version 1.1 stabilized the specification in October 2020.
- Initial tooling primarily targeted developers and research data managers handling and curating large amounts of data.
- Table 1 catalogs RO-Crate applications and libraries for different users and programming languages, with maturity ordered from Alpha through Release.
4. Profiles of RO-Crate in use
RO-Crate is applied across bioinformatics, regulatory science, and cultural heritage as a packaging and interoperability layer for workflows, artefacts, metadata, and provenance.
- RO-Crate is evaluated across Bioinformatics, Regulatory Science, and Cultural Heritage, with potential roles in machine-actionable data management plans and institutional repositories.
- WorkflowHub: WorkflowHub adopts RO-Crate to package related files from diverse workflow systems and annotate the constituent workflow files.
- WorkflowHub: RO-Crate acts as an interoperability layer between registries, repositories, and users, with iterative development informing workflow profiles, specifications, and libraries.
- WorkflowHub: WorkflowHub’s planned Workflow Run RO-Crate profile will contain both an executable workflow definition and a particular execution with test results.
- WorkflowHub: High-level Schema.org provenance records workflow input/output boundaries across workflow languages, while detailed traces can remain separate PROV artefacts.
- WorkflowHub: WorkflowHub DOIs lower the barrier to citing workflows as computational methods alongside their FAIR metadata captured in RO-Crate.
- Workflow monitoring: Workflow and software decay can reduce reusability and reproducibility when dependencies, services, or workflow implementations change or fail.
- Workflow monitoring: LifeMonitor uses a Workflow Testing RO-Crate profile to support periodic workflow testing and early detection of software collapse.
4.3. Digital Humanities: Cultural Heritage
RO-Crate supports preservation, discovery, interoperability, and planning across cultural-heritage repositories and institutional data infrastructures by packaging metadata and linking research assets.
- PARADISEC maintains more than 500,000 files across more than 16,000 items documenting endangered languages collected and digitized over many years.
- The Modern PARADISEC demonstrator uses RO-Crate to describe repository structure and capture each item’s metadata, exposing entries through a Web portal.
- RO-Crate makes PARADISEC’s transcribed metadata independent of the platform so it can be archived, preserved, and processed separately.
- OCFL organizes RO-Crate metadata files while supporting file integrity and versioning on a shared file system.
- Linked Data software can query multiple RO-Crates across the corpus using SPARQL triple patterns.
- Machine-actionable planning: Mappings between RO-Crates and machine-actionable Data Management Plans support conversion in either direction and enable skeleton plans from existing datasets.
- Institutional data repositories: Data Commons integrate research data, management, archival practices, computational infrastructure, repositories, and tools for collaboration and reuse.
- Institutional data repositories: Harvard Data Commons objectives include transferring large datasets, supporting research workflows, and packaging code and workflows for reproducibility and reuse.
5. Related Work
Related work frames RO-Crate as a simpler way to connect and package research artefacts than earlier Research Object implementations and workflow packaging systems. It addresses barriers involving complex technology stacks, fragmented metadata, and incomplete reproducibility information.
- Research Objects: Research Objects bundle datasets, workflows, scripts, results, and dissemination materials while typing, describing, and relating the resources.Their purpose is to preserve the context of computational research as a machine-readable compound object.
- Research Objects: Earlier Research Object implementations were difficult to adopt because they required large technology stacks, platform-specific tooling, and specialized knowledge.The Wf4Ever model also reused multiple overlapping vocabularies, increasing documentation and Semantic Web development burdens.
- Packaging approaches: RO Bundles and BagIt-based archives improved packaging, but container and package systems capture little metadata and omit semantic relationships between contents.Opaque tools can also leave functionality, licensing, and attribution unclear.
- Workflow reproducibility: Computational workflows require recording their execution environment, dependencies, analytical purpose, versions, licences, attributions, and identifiers—not merely their files.Text-only descriptions can otherwise force researchers to reconstruct pipelines, install dependencies, and retrieve reference datasets manually.
- Workflow reproducibility: Containers enable workflow execution on relatively blank machines, but image retention policies and unrecorded transitive dependency versions can still undermine reproducibility.The passage specifically identifies Docker Hub retention and Conda dependency updates as risks.
6. Conclusion
The conclusion presents RO-Crate as a community-developed packaging approach that combines structured metadata, Linked Data, and flexible profiles. It supports FAIR archives across repositories, exchanges, preservation, and individual research use.
- Conclusion: RO-Crate packages digital research artefacts with structured metadata to help developers and researchers produce and consume FAIR research archives.The conclusion states this as the established role of the approach.
- Conclusion: Community-developed best practices use “just enough” Linked Data standards, a rich base vocabulary, and extensibility for domain- and application-specific metadata.RO-Crate is described as both a structured data archive and a multimodal scholarly knowledge graph.
- Conclusion: Simple Web technologies supported rapid development of diverse open-source tools and libraries around RO-Crate.The ecosystem includes profiles and tools that help adopters find examples and support for their use cases.
- Conclusion: RO-Crate can serve as a data and metadata exchange mechanism, support long-term archival preservation, integrate with repository platforms, and operate at individual-researcher scale.The conclusion lists these as application settings rather than a single deployment model.
- Strictness vs flexibility: RO-Crate balances flexibility and strictness through common syntactic requirements, extensible domain profiles, and user-selectable semantic detail levels.This design follows a principle of graceful degradation.
7. Future Work
Future work is organized around community outreach, training, tooling maturity, usage studies, and stronger alignment with related metadata initiatives. Planned specification changes include formal profiles and additional entity types.
- Community and tooling: The community plans further outreach, training materials, an entry-level tutorial, and maturation of reference implementation libraries.Future examples will include Jupyter Notebooks that query multiple crates using knowledge graphs.
- Community and tooling: User studies and feedback from linked-data and EOSC communities will assess practical usage and differences from related efforts.The stated goal is to improve the specification and tools while reducing divergence among emerging profiles.
- Specification development: The upcoming RO-Crate 1.2 release is planned to formalize profiles for different categories of crates.Profiles are intended to capture differences in use and detail level across applications.
- Specification development: Requested future entity types include workflow runs, business workflows, containers, software packages, and tabular data structures.The community notes that existing schema.org types do not always match these entities well.
- Related initiatives: Future alignment will continue with CodeMeta, Science-on-schema.org, FAIR Digital Objects, and EOSC interoperability activities.These collaborations target software metadata, datasets, digital objects, and interoperability frameworks.
8.1. Contributions
The paper credits a large contributor group spanning conceptualization, methodology, software, investigation, data curation, visualization, writing, and review. Additional contributors supplied software, methodology, writing, and visualization support.
- Author contributions: Stian Soiland-Reyes contributed across conceptualization, data curation, formal analysis, methodology, software, visualization, and writing.The listed roles also include funding acquisition and project administration.
- Author contributions: Peter Sefton contributed conceptualization, investigation, methodology, project administration, resources, software, and writing review.These roles are listed in the article’s contribution statement.
- Author contributions: Several co-authors contributed methodology, software, investigation, or writing review, including Leyla Jael Castro, José M. Fernández, Daniel Garijo, Björn Grüning, Marco La Rosa, Simone Leo, and Eoghan Ó Carragáin.The contribution statement distributes these roles across the named authors.
- Acknowledgements: The article acknowledges additional contributors for software, methodology, writing review, and visualization.Named contributors include Finn Bacall, Herbert Van de Sompel, Ignacio Eguinoa, Nick Juty, Oscar Corcho, Stuart Owen, and Laura Rodríguez-Navas.
Appendix A. Formalizing RO-Crate in First Order Logic
Appendix A formalizes RO-Crate as a first-order-logic language whose entities, properties, classes, relations, and values can be mapped into serializations. It specifies a minimal RO-Crate structure, illustrates its shallow-tree representation, and describes mappings and production rules for JSON-LD.
- A.1. Language: The formal language defines RO-Crate descriptions using properties, classes, values, real numbers, and strings over IRI identifiers.The domain of discourse is the set of IRI identifiers, with numbers and literal strings as additional descriptions.
- A.1. Language: Any representation that gathers descriptions, properties, classes, and literal attributes can interpret the formalized RO-Crate language.
- A.2. Minimal RO-Crate: A minimal RO-Crate is a self-described Root Data Entity containing data entities described through contextual entities.
- A.2. Minimal RO-Crate: The root data entity must provide a name, description, publication date, and license-identifying contextual entity.Entities must have at least one class, while contextual entities must also have a name.
- A.2. Minimal RO-Crate: RO-Crate metadata uses subject–predicate–object patterns to relate entities or assign literal values within a single crate.The formalization treats R as a constant for one RO-Crate and includes described entities in its serialization.
- A.3. Example of formalized RO-Crate: The formalized example represents a RO-Crate as a shallow tree, with root aggregations, data-entity properties, and contextual-entity attributes.The formal model is depth 2, while the JSON-LD metadata serialization is equivalent but reaches depth 3 because of the JSON-LD preamble.
- A.4. Mapping to RDF with schema.org: The formalization maps to RDF and uses JSON-LD contexts to associate classes and properties with schema.org IRIs.The simplified RDF language covers strings and decimal real numbers, while the formalization omits other RDF literal datatypes and languages.
- A.5. RO-Crate 1.1 Metadata File Descriptor: The metadata file descriptor makes the serialization self-describing by identifying the root data entity and the RO-Crate specification version.The metadata file is a contextual entity rather than a contained data entity and does not affect the crate's depth limit.