A portable research object is more than a folder of files
RO-Crate uses a small JSON-LD graph, a Root Data Entity and deliberately described relationships to keep data meaningful when it moves between people, repositories and tools.
A research output often arrives as a loose mixture of data, code, notes, images, licences and links. Copying the bytes may preserve the files while losing the story that makes them usable: which dataset is central, who created it, what software produced a figure, which licence applies, and which profile a receiving system should expect.
RO-Crate addresses that gap with a community specification for packaging a research object and its metadata. This guide uses version-aware language: RO-Crate 1.1 remains widely deployed, while 1.2 clarifies identifiers and moves profile declarations to the Root Data Entity. Always record the version you implement rather than blending requirements from different editions.
Chapter contents
- 1. Begin with the research object, not the archive format
- 2. Separate the metadata descriptor from the Root Data Entity
- 3. Read the JSON-LD as a graph
- 4. Distinguish Data Entities from Contextual Entities
- 5. Choose identifiers that survive movement
- 6. Describe files for both people and machines
- 7. Worked example: build a small reproducible study crate
- 8. Represent people, organisations and software without string drift
- 9. Use profiles as purpose-specific contracts
- 10. Validate syntax, graph shape and domain meaning separately
- 11. Version the crate and cite the right level
- 12. Package, preserve and exchange without confusing layers
Choose a reading route
- Route 1: Orient the crate — root, descriptor and graph
- Route 2: Model entities — data, context and identifiers
- Route 3: Work an example — people, software and provenance
- Route 4: Apply profiles — conformance, validation and exchange
- Route 5: Transfer and audit — versions, rights and preservation
How to use this guide
Start with the chapters that match your immediate decision, then return to the worked example and audit chapters. Each chapter separates a model from the evidence needed to use it responsibly. A claim is not strengthened merely by being technical; it is strengthened when assumptions, observations, alternatives and limits can be inspected.
| Layer | Question | Minimum record |
|---|---|---|
| Concept | What exactly is being represented? | Definitions and boundary |
| Method | How will the reasoning be carried out? | Steps, inputs and assumptions |
| Transfer | Would it work in a changed setting? | A deliberately altered case |
| Audit | What could prove it wrong? | Evidence, limits and revision trigger |
Chapter 1. Begin with the research object, not the archive format
The idea
An RO-Crate is a research object described as a Dataset. Its payload may be a directory, an archive or web resources, but the intellectual boundary is declared by metadata rather than inferred from the container.
A disciplined method
Name the purpose and intended users, inventory the resources needed for that purpose, and identify the Root Data Entity before choosing ZIP, BagIt or repository transport.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is whether a linked resource is inside the research object or merely contextual. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A study crate includes observations, code and a report. A lab website is described as context but is not asserted as payload.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Change the case to a teaching collection that links licensed readings which cannot be redistributed; keep links and rights statements without pretending the files are packaged.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: A crate can point to remote data that later changes or disappears.
Evidence to retain: the purpose statement, root identifier, payload inventory, exclusions and access dates
Common misconception: A ZIP file becomes a research object merely because it contains research files.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 2. Separate the metadata descriptor from the Root Data Entity
The idea
The metadata file describes the crate, while the Root Data Entity represents the research object as a whole. These are related but not interchangeable entities.
A disciplined method
Give the descriptor its required identity, type and conformsTo value for the RO-Crate specification; give the root its own Dataset identity, name, description and declared parts.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is which properties describe the metadata file and which describe the research object. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A descriptor records that it conforms to RO-Crate 1.2; the root records the study title, licence, creators and data parts.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Apply the distinction to a crate whose root uses a persistent URI rather than ./ and verify that local files still resolve correctly.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: Practices differ by specification version, so an example copied from 1.1 can be wrong for 1.2.
Evidence to retain: the specification version, descriptor node, root node and parser output
Common misconception: All metadata belongs on the descriptor because it is the metadata file.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 3. Read the JSON-LD as a graph
The idea
RO-Crate metadata is JSON-LD. The @graph contains nodes identified by @id and links between them; compact JSON presentation should not hide the underlying graph relationships.
A disciplined method
Expand the JSON-LD during validation, inspect node identities and datatypes, and check that every referenced local entity is described or intentionally external.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is whether two mentions share one identity or create two entities. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A person node is referenced as creator by both a dataset and a script; one @id preserves that shared identity instead of duplicating two name strings.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Change the context document or JSON key order and confirm that the expanded graph still expresses the same relationships.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: Graph equivalence does not guarantee byte equivalence, signature validity or identical human display.
Evidence to retain: the original JSON-LD, context URL or embedded context, expanded graph and comparison report
Common misconception: JSON key order or indentation determines the meaning of the crate.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
| Layer | Role | Check |
|---|---|---|
| JSON | Portable syntax | Parses |
| JSON-LD | Linked-data interpretation | Expands as intended |
| RO-Crate profile | Community constraints | Required entities present |
| Local policy | Project rules | Purpose-specific fields complete |
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 4. Distinguish Data Entities from Contextual Entities
The idea
Data Entities are payload files, directories or web-based data that form part of the object. Contextual Entities describe related people, organisations, places, licences, instruments and other things that make the data interpretable.
A disciplined method
Classify each entity by its role in this crate, not by whether its description is long. Link context to data through specific properties and avoid turning every cited object into payload.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is whether the object is part of the research object or explains it. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A CSV and a remote API snapshot are Data Entities; the technician, sensor model and licence are Contextual Entities.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Transfer the classification to a digitised manuscript whose physical volume is context while image files and transcription are data.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: One real-world thing can be data in one crate and context in another; the labels are crate-relative.
Evidence to retain: entity inventory, classification rationale, links and unresolved cases
Common misconception: People and licences are less important because they are “only context”.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 5. Choose identifiers that survive movement
The idea
Relative identifiers suit files inside a crate; absolute persistent identifiers suit external or globally identified things; fragment identifiers can name local contextual entities.
A disciplined method
Use relative paths only for payload that moves with the crate, absolute URIs for remote or persistent identities, and stable fragments for local entities without better identifiers. Test relocation and URI resolution.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is which identity must remain stable outside this crate. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A script is ./workflow/analyse.py, its author is an ORCID URI, and a locally described instrument is #spectrometer-1.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Move the crate under a different directory and domain; confirm local paths still work and external identities do not accidentally change.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: Persistent-looking URIs can still fail; identifiers need governance and should not be equated with verified identity.
Evidence to retain: identifier registry, resolution tests, redirects, ownership and collision checks
Common misconception: Every entity needs a DOI or every local identifier is unreliable.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 6. Describe files for both people and machines
The idea
A file node can carry name, media type, size, checksum-related context, licence, creator and provenance. Useful descriptions support discovery while retaining machine-actionable relationships.
A disciplined method
Record the properties required by the selected profile, add names and descriptions for human readers, and keep measured technical properties derived from the actual file.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is which facts are authoritative and which were inferred at packaging time. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A TIFF image records its media type, byte size, licence and generating action; the preview explains it without replacing the original.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Change the payload to a large remote object and record how size, fixity and access time will be verified without downloading it on every inspection.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: Schema.org properties do not replace specialised preservation, fixity or domain standards.
Evidence to retain: file bytes, measured size, media type inspection, licences and provenance links
Common misconception: A polished preview is sufficient evidence that the described files are intact.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 7. Worked example: build a small reproducible study crate
The idea
A compact crate can connect observations, code, an environment, outputs, people and an execution action without requiring a bespoke metadata system.
A disciplined method
Start with the root, add the five data entities, add people and software as context, then connect an action with object, instrument, agent, start time, end time and result.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is how to express what produced the result. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A fictional tide study links observations.csv and analyse.py to a CreateAction whose result is chart.png, performed by a researcher using Python 3.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Change the analysis so a web API supplies observations; add the query, access time and captured response needed to reproduce the result.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: The example demonstrates structure, not scientific validity; correct metadata cannot rescue flawed measurements or code.
Evidence to retain: the crate bytes, environment, command log, input fixity, action times and output fixity
Common misconception: Adding code proves that a result is reproducible.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
| Entity | Type | Key relationship |
|---|---|---|
| ./ | Dataset | hasPart payload |
| observations.csv | File | input to action |
| analyse.py | SoftwareSourceCode | instrument of action |
| #run-1 | CreateAction | object, instrument, result |
| chart.png | File | result of action |
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 8. Represent people, organisations and software without string drift
The idea
Context nodes let several data entities point to one described creator, publisher, funder or software application. Shared identity prevents inconsistent spellings from fragmenting the graph.
A disciplined method
Prefer maintained identifiers when appropriate, describe the local role, and keep attribution distinct from contact details and legal responsibility. Treat software versions as evidence, not decoration.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is whether two similar names refer to the same entity. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
One organisation node publishes the crate; two people have separate ORCID-linked nodes; Python and a package release are distinct software entities.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Transfer to historical data where no global identifier exists; use a local node with source-backed names and uncertainty rather than inventing certainty.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: An identifier authenticates neither a person nor every claim about them; privacy and data minimisation still apply.
Evidence to retain: identifier sources, version strings, role assignments, consent and redaction decisions
Common misconception: Replacing structured creator nodes with repeated name strings is harmless.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 9. Use profiles as purpose-specific contracts
The idea
A profile adds expectations for a community or workflow while the base specification supplies common structure. In RO-Crate 1.2, profile declarations belong on the Root Data Entity and are themselves described as Profile entities.
A disciplined method
Select profiles that match the intended exchange, read their required and recommended properties, declare conformance only after validation, and record profile versions.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is what conformance claim the evidence can support. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A workflow run crate declares a workflow-run profile and supplies the action, inputs, outputs and software required by that profile.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Change receiving systems: one understands only base RO-Crate, another the specialised profile. Confirm graceful degradation and identify lost features.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: Declaring conformsTo does not make a crate conform; multiple profiles can conflict or evolve.
Evidence to retain: profile URI and version, validation report, exceptions and receiving-system tests
Common misconception: A profile is merely a label for search and has no effect on required metadata.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 10. Validate syntax, graph shape and domain meaning separately
The idea
A crate can be valid JSON but invalid JSON-LD, valid JSON-LD but non-conformant RO-Crate, or conformant while describing the wrong research object.
A disciplined method
Run layered checks: JSON parsing, JSON-LD expansion, base/profile validation, payload existence and fixity, then responsible human review of boundary and meaning.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is which validation failure blocks exchange and which becomes a documented warning. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A crate passes JSON parsing but references a missing local file; another passes structural checks but names the wrong licence. Different gates expose different failures.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Apply validation to a remote-data crate where availability varies; separate temporary network failure from a false identifier or missing description.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: No automated validator can infer the intended boundary, consent or scientific truth from metadata alone.
Evidence to retain: tool versions, validation outputs, payload checks, reviewer sign-off and exception log
Common misconception: One green validator result proves the crate is complete and correct.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 11. Version the crate and cite the right level
The idea
Researchers may need to cite the conceptual project, a release, a dataset inside the release or a specific file. Versioning and citation should identify the level actually used.
A disciplined method
Mint stable identifiers according to repository policy, freeze released metadata and payload where promised, link versions explicitly, and include a cite-as relationship where the profile recommends it.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is whether a change creates a new release or corrects metadata in place. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
Version 1.1 adds a corrected description without changing payload; version 2 changes observations and code. The record explains the different treatment.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Change a remote dependency after publication and decide whether to capture it, record a new access event or issue a new crate release.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: Version links do not guarantee immutability; repository retention and fixity policies remain necessary.
Evidence to retain: release identifiers, dates, change log, fixity, repository policy and citation text
Common misconception: Citing the crate landing page always identifies the exact data and code used.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 12. Package, preserve and exchange without confusing layers
The idea
RO-Crate describes entities and relationships. ZIP, BagIt, repository deposits and transfer protocols address other concerns such as transport, inventory and fixity. The layers can complement one another.
A disciplined method
Choose a transport container, validate path and filename portability, pair metadata with BagIt or preservation manifests where needed, and test unpacking in a clean environment.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is which layer owns fixity, transfer completeness and semantic description. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A repository receives a BagIt bag whose payload includes an RO-Crate; BagIt verifies transfer inventory while RO-Crate explains the research object.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Transfer the same crate as a web publication with no archive and state which preservation and offline-use guarantees disappear.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: Combining standards adds operational complexity and does not automatically resolve conflicting identifiers or manifests.
Evidence to retain: package manifest, checksums, unpacking test, crate validation and custody receipt
Common misconception: RO-Crate replaces BagIt, PREMIS, OAI-ORE and every domain metadata standard.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Field workbook
Build a crate for one real or fictional output. Keep the first iteration small enough to inspect by eye, then run it through a clean-room transfer: give the package and its declared profile to another person or tool and record what they can and cannot recover.
- Write the decision question in one sentence and name the decision owner.
- List observations separately from interpretations, with dates and provenance.
- Record at least two plausible alternatives before choosing a preferred account.
- Run the changed-context test and note which assumptions fail.
- State the limit, confidence and next review trigger in plain language.
| Audit question | Pass evidence | Revision trigger |
|---|---|---|
| Can the root be identified? | One declared Dataset root | Ambiguous or duplicated root |
| Do links survive movement? | Relocation test | Broken relative path |
| Does the profile claim hold? | Versioned validation report | New profile or failed rule |
| Can a result be traced? | Input-action-output path | Missing version or agent |
Continue through the verified ecosystem
- OAI-ORE resource maps — model compound web objects and boundaries
- BagIt profiles — verify packaged transfer inventories
- PREMIS preservation evidence — record preservation events and agents
- Data citation — cite versioned data and subsets
- Canonical serialization — separate graph meaning from stable bytes
Frequently asked questions
Is RO-Crate only a ZIP file?
No. It is a way to describe a research object using JSON-LD. A directory or archive is common, but web-based data entities are also possible.
What is the Root Data Entity?
It is the Dataset representing the crate as a whole, distinct from the metadata descriptor that describes the crate.
Are Contextual Entities optional decoration?
No. They often carry the people, organisations, licences, places, instruments and software needed to interpret the data.
Does conformsTo prove conformance?
No. It declares a claim that should be backed by a versioned validator report and human review.
Can RO-Crate replace preservation metadata?
Usually not. It can link to preservation evidence, while standards such as PREMIS and BagIt address specialised needs.
Which RO-Crate version should I use?
Use the version required by your community and tools, declare it explicitly, and do not mix 1.1 and 1.2 rules without documenting the migration.
Authoritative sources and further reading
- RO-Crate Metadata Specification 1.2 — current specification
- RO-Crate metadata model — root, data and contextual entities
- RO-Crate profiles — profile declaration and conformance
- RO-Crate 1.1 JSON-LD appendix — JSON-LD implementation details
- What changed in RO-Crate 1.2 — migration guidance
This educational guide explains information modelling and exchange. It does not certify a crate, repository, licence or research result; apply the exact specification and community profile in force for your workflow.