RO-Crate: Packaging Research Data and Metadata for FAIR Reuse

RO-Crate (Research Object Crate) is a lightweight specification for packaging research data, software, and their associated metadata into a single, self-describing bundle that both people and machines can interpret. It was developed within the Research Object community — an initiative that grew out of earlier “research object” work at the University of Manchester and elsewhere aimed at making digital research outputs reproducible and citable as first-class objects — and is now maintained collaboratively, with the University of Technology Sydney and the University of Manchester holding copyright on the current specification text alongside a broader base of RO-Crate contributors. For anyone managing research data, RO-Crate matters because it gives a dataset, workflow, or software package a standard, machine-readable way to say what it contains, who made it, and how its parts relate to each other — the kind of rich description the FAIR data principles call for but that most ad hoc folder-and-README bundles never actually provide.

What Is RO-Crate?

At its core, RO-Crate is a convention for adding a single metadata file, ro-crate-metadata.json, to the root of any directory (a “crate”) of research data. That file is written in JSON-LD — JSON that carries an explicit, linked-data context — built primarily on schema.org vocabulary, with RO-Crate-specific terms layered on top where schema.org doesn’t cover a research-specific need (workflow inputs/outputs, computational environments, and so on). Because the metadata is JSON-LD, it is simultaneously easy for a person to read, easy for a script to parse, and interoperable with the broader linked-data and search-engine ecosystem that already understands schema.org.

Every RO-Crate has a designated Root Data Entity: the single entity in the metadata graph that represents the crate as a whole (typically typed as a schema.org Dataset), from which every other file, person, organization, and relationship described in the crate hangs off. That root entity is where a crate declares its own core FAIR-relevant metadata — name, description, license, and creators — before describing the individual files and how they relate.

RO-Crate does not require any particular storage or transport mechanism; a crate can be a plain folder, a zipped archive, or a directory deposited directly into a repository. This deliberately narrow scope — describe what’s in the package, don’t dictate how the package is stored or moved — is a large part of why it has been adopted across such different contexts: it can sit underneath a workflow run, a dataset deposit, or a software release without requiring any of those systems to change how they store files.

Build a Minimal Valid RO-Crate by Hand

The fastest way to understand RO-Crate is to build the smallest crate the specification will accept, then add to it. Everything below is checked against RO-Crate 1.3, which the specification index lists as the newest release as of 26 August 2026. RO-Crate is actively versioned — 1.0, 1.1, 1.2 and 1.3 are all published side by side — so check the specification index before building tooling, and note which version your crate declares.

The directory layout

An Attached RO-Crate Package is just a directory. The specification requires exactly one thing of it: a file named ro-crate-metadata.json in the root. Nothing else is mandatory, and the root directory’s own name is undefined — a directory is identifiable as an RO-Crate root purely by the presence of that file.

<RO-Crate root directory>/
|   ro-crate-metadata.json    # RO-Crate Metadata File - MUST be present
|   ro-crate-preview.html     # human-readable rendering - MAY be present
|   ro-crate-preview_files/   # MAY be present
|   [payload files and directories]  # 0 or more

This is the point most often missed: RO-Crate does not tell you how to store, compress or transmit the package. A crate can be a working folder, a zip, or a directory tree inside a repository deposit. The specification only governs the metadata document.

The two entities every crate must have

The ro-crate-metadata.json file must be valid JSON-LD 1.0 in flattened and compacted form, and it must reference the RO-Crate JSON-LD context by URL rather than inlining it. Its @graph array must describe two things before it describes anything else:

1. The RO-Crate Metadata Descriptor — a self-describing entity with the @id value ro-crate-metadata.json and @type CreativeWork. It must carry an about property referencing the Root Data Entity’s @id. This is the entity that tells a parser which of the other entities is the root.
2. The Root Data Entity — the single entity representing the crate as a whole, from which everything else hangs.

That about pointer is the whole discovery mechanism. A conformant parser does not guess at the root; it looks up the entity whose @id is ro-crate-metadata.json and follows its about reference:

metadata_entity = entity_map["ro-crate-metadata.json"]
root_entity = entity_map[metadata_entity["about"]["@id"]]

What the Root Data Entity must carry

The specification states that the Root Data Entity must have all of the following properties, each with its own constraint on the value:

Property	Requirement on the value
@type	MUST be Dataset, or an array containing Dataset.
@id	SHOULD be the string ./ (the directory containing ro-crate-metadata.json) or an absolute URI.
name	SHOULD identify the dataset well enough for a human to distinguish it from other crates.
description	SHOULD elaborate on the name and summarise the context that makes the dataset important.
datePublished	MUST be a single string in ISO 8601 date format, SHOULD be precise to at least a day, MAY go down to the millisecond.
license	SHOULD link to a contextual or data entity that itself has a name and description; MAY instead be a textual description of permitted use.

Note the distinction between MUST-be-present and SHOULD-be-a-particular-value. All six properties are required; most of their values are recommendations, which is why crates in the wild vary while still validating.

The complete minimal crate

Putting those requirements together gives a genuinely conformant ro-crate-metadata.json. Note that license resolves to a real contextual entity rather than a bare string, which is what satisfies the “name and description” recommendation above:

{
  "@context": "https://w3id.org/ro/crate/1.3/context",
  "@graph": [
    {
      "@id": "ro-crate-metadata.json",
      "@type": "CreativeWork",
      "about": {"@id": "./"},
      "conformsTo": {"@id": "https://w3id.org/ro/crate/1.3"}
    },
    {
      "@id": "./",
      "@type": "Dataset",
      "name": "Soil respiration measurements, Site 4, 2025 season",
      "description": "Hourly CO2 flux readings from four chambers, with the R script used to aggregate them to daily means.",
      "datePublished": "2026-03-14",
      "license": {"@id": "https://creativecommons.org/licenses/by/4.0/"}
    },
    {
      "@id": "https://creativecommons.org/licenses/by/4.0/",
      "@type": "CreativeWork",
      "name": "Creative Commons Attribution 4.0 International",
      "description": "Reuse permitted with attribution to the original creators."
    }
  ]
}

Drop that file into a folder and the folder is an RO-Crate. There is no build step, no validator you are required to run, and no registry you must notify.

Describing the payload: data entities and hasPart

A crate with no described files is valid but not very useful. Payload files become data entities when the root lists them under hasPart and each one gets its own entry. Files are typed File (the RO-Crate context supplies this as an alias for schema.org’s MediaObject); directories are typed Dataset and conventionally carry a trailing slash in the @id:

{
  "@id": "./",
  "@type": "Dataset",
  "name": "Soil respiration measurements, Site 4, 2025 season",
  "description": "Hourly CO2 flux readings from four chambers, with the R script used to aggregate them to daily means.",
  "datePublished": "2026-03-14",
  "license": {"@id": "https://creativecommons.org/licenses/by/4.0/"},
  "hasPart": [
    {"@id": "measurements.csv"},
    {"@id": "scripts/"}
  ]
},
{
  "@id": "measurements.csv",
  "@type": "File",
  "name": "Hourly CO2 flux readings",
  "encodingFormat": "text/csv",
  "contentSize": "184320"
},
{
  "@id": "scripts/",
  "@type": "Dataset",
  "name": "Aggregation scripts"
}

Two constraints worth internalising. First, the relative identifiers are resolved against the crate root, which is why ./ and plain relative paths work without any base URL. Second, if you add a ro-crate-preview.html rendering, the specification says it and its ro-crate-preview_files/ directory should not appear in hasPart — they describe the crate rather than forming part of its payload.

Anything that is neither the root nor a payload file — a person, an organisation, a funding award, a licence — is a contextual entity. The specification asks that contextual entities be described in the same document with the same identifier, and that each be linked from at least one other entity, so the graph stays connected rather than accumulating orphans.

Profiles: What Makes a Crate More Than a Zip File

The base specification is deliberately permissive: six required root properties and an open schema.org vocabulary. That is enough for interchange but not enough for a machine to know that a given crate represents, say, a completed workflow run with recoverable inputs and outputs. Profiles close that gap, and they are published as separate documents from the base specification — a distinction that matters when you cite them.

Where conformsTo goes — and the 1.1 trap

RO-Crate uses the same property, conformsTo, for two different assertions, distinguished by which entity carries it:

• On the Metadata Descriptor, conformsTo declares which version of the base specification the JSON-LD conforms to. In 1.3 it should have a single value, a versioned permalink starting https://w3id.org/ro/crate/.
• On the Root Data Entity, conformsTo declares which profile(s) the crate implements.

This is a real migration gotcha. In crates conforming to version 1.1 and earlier, conformsTo on the descriptor may be an array that includes profiles alongside the base specification. Under 1.3 that is no longer where profiles belong. If you are reading older crates or older examples, expect to find profile identifiers in the descriptor and do not treat that as the current pattern.

A profile is itself declared as an entity in the graph, typed as a Profile alongside CreativeWork or Dataset, and pointing back at the base specification it extends via isProfileOf:

{
  "@id": "./",
  "@type": "Dataset",
  "conformsTo": {"@id": "https://w3id.org/ro/wfrun/process/0.4"}
},
{
  "@id": "https://w3id.org/ro/wfrun/process/0.4",
  "@type": ["CreativeWork", "Profile"],
  "name": "Process Run crate profile",
  "version": "0.4.0",
  "isProfileOf": [
    {"@id": "https://w3id.org/ro/crate/1.3"}
  ]
}

The Workflow Run RO-Crate profile family

Workflow and provenance profiles are maintained by the Workflow Run RO-Crate (WRROC) working group, which is part of the wider RO-Crate community but publishes its own documents on its own release cycle. WRROC is a collection of profiles at increasing granularity, not a single specification:

• Process Run Crate — describes the execution of one or more computational tools. It does not assume a workflow engine at all, so it can be applied to work run by hand or by a script.
• Workflow Run Crate — describes the run of a computational workflow managed by a workflow system.
• Provenance Run Crate — adds provenance for the individual steps within a workflow run, rather than treating the run as a single opaque activity.

The Workflow Run and Provenance Run profiles extend the Workflow RO-Crate profile, which is a further separate document describing a workflow as a reusable object and is the format the WorkflowHub registry supports. So a crate deposited in WorkflowHub is conforming to a profile that extends a profile that extends the base specification — three documents, only one of which is the specification at researchobject.org/ro-crate.

Verification note: the profile identifier and version shown above (https://w3id.org/ro/wfrun/process/0.4, version 0.4.0) is the example carried in the RO-Crate 1.3 specification itself and was confirmed there directly. The WRROC profiles version independently of the base specification, so confirm the current version of each tier against the WRROC profile documents before pinning a conformsTo value in production tooling — do not assume the version in a base-specification example is the newest for that profile.

This layering is what separates RO-Crate from a zip file with a README. A zip tells a consumer nothing about its own structure; a profiled crate declares, in a resolvable identifier, exactly which shape of research object it claims to be — and therefore which properties a consuming tool is entitled to expect. That claim is machine-checkable, which is the practical difference between “packaged” and “machine-actionable”.

How RO-Crate Supports FAIR Data Practice

RO-Crate is not itself a FAIR-compliance framework, but it directly operationalizes several parts of the FAIR principles at the packaging level:

• Findable — a well-formed crate carries structured identifiers, titles, and descriptions in its root entity that make the package’s contents legible to indexing tools and search interfaces, rather than requiring a human to open and read a plain-text README.
• Accessible — because the metadata format is open, published, and versioned, any tool implementing the specification can retrieve and parse a crate’s description without proprietary software.
• Interoperable — JSON-LD grounded in schema.org means a crate’s metadata can be understood by any system that already speaks linked data, not just RO-Crate-aware tools specifically.
• Reusable — RO-Crate’s data model has explicit places to record licensing, provenance (who created what, from which inputs), and contextual entities like people, organizations, and funding — the detail a downstream reuser needs to evaluate and cite the work correctly.

Research-data managers evaluating whether a dataset meets funder or repository FAIR expectations can treat RO-Crate as one concrete, implementable answer to “how do I actually attach machine-readable metadata to this deposit,” alongside repository-level metadata schemas. See CASRAI’s step-by-step FAIR checklist for the broader compliance picture, and how to choose a metadata schema for a dataset for how RO-Crate compares with other schema choices at deposit time.

Core Use Cases

RO-Crate’s own documentation and example gallery point to a consistent set of use cases where the format has seen real implementation:

Workflow provenance and reproducibility

RO-Crate is widely used to package computational workflows together with their provenance record — which tools ran, in what order, on which inputs, in what computational environment. WorkflowHub, a registry for FAIR scientific workflows, uses RO-Crate as its packaging format so that a deposited workflow arrives with structured, machine-readable metadata rather than just source code and a description field. The Nextflow ecosystem’s nf-prov plugin similarly generates an RO-Crate as a structured provenance record of a completed pipeline run. This overlaps closely with CASRAI’s broader guides on data provenance and reproducibility infrastructure — RO-Crate is best understood as one concrete packaging mechanism for the provenance concepts those pages cover, expressed specifically as portable, deposit-ready metadata rather than a live system’s internal logs.

Dataset packaging and interchange

Beyond workflows, RO-Crate is used to bundle datasets — particularly heterogeneous collections of files — with rich descriptive and structural metadata for deposit or exchange between systems. The Language Data Commons of Australia (LDaCA) is a documented example of RO-Crate used this way, packaging linguistic and cultural data collections with the contextual metadata needed to interpret and reuse them responsibly.

Software and model packaging

RO-Crate has also been applied to packaging research software and computational models with their metadata, provenance, and dependencies attached — the Model Atlas of the Earth (M@TE) project is a documented example for scientific models specifically. This is a natural extension of the same core idea used for workflows: describing the software or model, its inputs/outputs, and its relationship to any associated data in one machine-readable bundle. Where software carries a formal citation record rather than just a description, that work connects to CASRAI’s coverage of the FAIR4RS Software Citation Principles and the FAIR Working Group’s software citation guidance.

Other documented implementations include AROMA (the ARP RO-Crate Manager) and use within the Open Microscopy Environment (OME) for structured data transfer — both concrete signals that RO-Crate adoption spans beyond a single discipline or infrastructure project, though the specification’s overall adoption should be understood as an active, growing community effort rather than a universal standard every repository already requires.

How RO-Crate Relates to Other Standards

RO-Crate sits alongside, rather than replaces, several standards research-data managers already work with:

• PROV-O, the W3C provenance ontology, defines a formal, general-purpose vocabulary for expressing provenance on the web. RO-Crate’s provenance modeling is built on schema.org rather than PROV-O directly, but the two are interoperable in intent — both are ways of answering “what produced this, and from what.”
• Workflow languages (CWL/WDL) describe how a computational pipeline executes; RO-Crate describes the resulting package of code, data, and provenance around a workflow run, and the two are frequently used together rather than as alternatives.
• DataCite’s metadata schema and repository-level schemas govern what a repository record must contain to register a persistent identifier; RO-Crate operates one level down, describing the internal structure and relationships of the deposited package itself, and the two can coexist on the same deposit.
• DMP Common Standard (RDA, JSON-LD) is a separate, machine-actionable JSON-LD standard for data management plans specifically, not data packages — both share JSON-LD as an underlying technology, illustrating a broader trend toward linked-data formats across the research data infrastructure.

How RO-Crate Compares With Adjacent Packaging Formats

RO-Crate is one of several schema.org/JSON-LD-based description formats a research data manager may encounter, and they are more complementary than competing:

• Frictionless Data / Data Package targets tabular data specifically, with column-level schema description. RO-Crate is domain-agnostic and describes composite objects, but says nothing about a CSV’s internal columns — the two can sit in the same deposit.
• Croissant describes ML-ready dataset structure (splits, record sets, feature roles) for machine-learning consumption. RO-Crate describes the research object and its provenance.
• Bioschemas is markup embedded in web pages for discovery by search engines and aggregators, rather than a package format. Notably, the Workflow RO-Crate profile is aligned with, and intends to strictly extend, the Bioschemas ComputationalWorkflow profile.
• FAIR Digital Objects operate at the identifier-and-typing layer above the package, addressing how objects are resolved and typed rather than how a directory describes itself.

For the workflow side specifically, a crate produced by a pipeline run pairs naturally with CASRAI’s coverage of Snakemake and Nextflow as workflow engines, and with how to cite the software and code a crate bundles. Broader context for this territory sits on the research data management pillar.

Adopting RO-Crate: Practical Considerations for Research Data Managers

For an institution or research-data management team weighing RO-Crate, a few practical points matter more than the technical spec itself:

• It’s additive, not a repository replacement. RO-Crate describes what’s inside a package; it doesn’t provide storage, access control, or long-term preservation. Those remain the job of the repository the crate is ultimately deposited into — see CASRAI’s guide on choosing an open data repository.
• It’s most valuable where a deposit is genuinely composite. A single flat dataset file may not need RO-Crate’s structure; a workflow run, a multi-file dataset with mixed provenance, or a software release with dependencies benefits far more from being able to declare relationships explicitly.
• Check whether your target repository or registry already expects it. Adoption is domain- and infrastructure-specific rather than universal; workflow registries like WorkflowHub build RO-Crate in as their native packaging format, while a general-purpose institutional repository may not have any built-in awareness of it. Confirm expectations with the receiving repository before assuming RO-Crate is required or even recognized.
• The specification is versioned and actively maintained. RO-Crate 1.3 is listed as the newest release on the specification index as of 26 August 2026, with 1.0, 1.1 and 1.2 still published alongside it. Because the version you declare in conformsTo determines how a parser reads your crate — and because the placement of profile declarations changed after 1.1 — confirm the current version and any breaking changes directly against the specification index before building tooling against it, rather than assuming a version number cited elsewhere is still current.

Frequently Asked Questions

Is RO-Crate the same thing as FAIR data?

No. FAIR is a set of principles for making data findable, accessible, interoperable, and reusable; RO-Crate is one concrete technical implementation that helps satisfy those principles at the packaging and metadata level. A dataset can be FAIR without using RO-Crate specifically, and a crate built with RO-Crate still needs to be deposited somewhere accessible, licensed appropriately, and documented well to actually be FAIR in practice.

Do I need special software to create an RO-Crate?

No. An RO-Crate’s core requirement is simply a correctly structured ro-crate-metadata.json file at the root of a directory, and for a simple deposit it is entirely reasonable to write it by hand — the complete minimal example above is a conformant crate in about twenty lines. Tooling earns its place at scale and for provenance capture: workflow registries and pipeline plugins generate crates automatically, and dedicated editors exist for authoring them interactively. Check the current tooling landscape at researchobject.org before committing to a particular workflow.

Does RO-Crate replace a Data Management Plan?

No. A Data Management Plan is a project-level planning document describing how data will be handled across a research project’s lifecycle. RO-Crate operates at the level of an individual data package, describing what that package actually contains once produced. They’re complementary: a DMP might commit to depositing data with rich, structured metadata, and RO-Crate is one way of fulfilling that commitment for composite or workflow-based outputs.

Who governs the RO-Crate specification?

RO-Crate is developed as a community specification by the Research Object community and RO-Crate contributors, with the University of Technology Sydney and the University of Manchester holding copyright on the published specification text. It is not a formal standards-body specification in the way an ISO or W3C Recommendation is, though it draws heavily on the W3C’s JSON-LD standard and schema.org vocabulary.

What is the minimum an RO-Crate must contain?

One file, ro-crate-metadata.json, in the root directory. Inside it, a JSON-LD graph describing two entities: the RO-Crate Metadata Descriptor (@id of ro-crate-metadata.json, @type CreativeWork, with an about property pointing at the root) and the Root Data Entity (@type Dataset, normally @id ./, carrying name, description, datePublished and license). Payload files are optional — a crate with zero data entities is still valid.

What is the difference between the RO-Crate specification and an RO-Crate profile?

The specification defines the base structure every crate shares. A profile is a separate document that constrains that structure for a particular kind of research object, so a consuming tool knows which additional properties to expect. They are declared in different places: the base specification version goes in conformsTo on the Metadata Descriptor, while profiles go in conformsTo on the Root Data Entity. The Workflow Run RO-Crate profiles and the Workflow RO-Crate profile are maintained separately from the base specification and version on their own cycles.