Status: Draft
OpenResearchWorkspace (ORW) is a workspace format/contract plus reference implementations. The specification defines what an ORW-compatible workspace is without requiring a particular hosting provider, UI, archive service or AI system.
ORW adopts the ISA Investigation–Study–Assay abstract model as the normative scientific hierarchy for experimental research. ORW MUST NOT redefine Investigation, Study or Assay with incompatible meanings.
For experimental projects:
- an ORW workspace normally represents one ISA Investigation;
- an Investigation contains one or more Studies;
- a Study contains zero or more Assays, with one or more expected when analytical measurements/tests are represented.
Investigation captures overall project context and grouping. Study captures study design, subjects/sources and samples, factors/treatments and protocols. Assay captures a measurement/test, measurement and technology type, relevant processing/protocol provenance and resulting data relationships.
ORW MAY support projects where Assay is not scientifically applicable (for example some literature or purely computational work). Implementations MUST NOT create scientifically meaningless Assays merely to satisfy a folder template.
An ORW workspace has one canonical scientific project description:
.research/project.yml
This record MUST preserve the Investigation → Study → Assay relationships. Human-facing documents, citation files, ISA serializations, repository metadata, archival metadata and agent context SHOULD be generated from or synchronized with the canonical record rather than independently maintained.
Implementation/lifecycle metadata MUST NOT be mixed into the scientific model; it belongs in .research/workspace.yml. Capability state belongs in .research/capabilities.yml.
ORW's scientific model SHOULD be capable of deterministic mapping to ISA concepts. ISA-JSON and ISA-Tab are interoperability representations, not additional sources of truth that ordinary researchers must manually maintain.
A future conforming ISA interoperability capability SHOULD provide validated export and import and SHOULD test semantic round trips where technically possible.
ORW-specific metadata outside ISA's scope MAY coexist with the ISA-aligned scientific model but MUST NOT alter ISA semantics.
ORW treats RO-Crate as an interoperability, packaging, and publication/export layer, not as a second editable project model.
The canonical scientific source of truth remains .research/project.yml. A conforming implementation MAY generate ro-crate-metadata.json and an RO-Crate package from the canonical ORW record, workspace layout, and selected local or external resources. Researchers SHOULD NOT be required to maintain generated RO-Crate metadata manually.
The first ORW exporter SHOULD target RO-Crate 1.3 and MUST declare the RO-Crate version it supports. Generated crates MUST satisfy the supported RO-Crate specification before being presented as valid exports.
An ORW → RO-Crate export SHOULD:
- represent the ORW Investigation as the exported research object/root dataset;
- preserve Studies and Assays explicitly rather than flattening scientific structure into filenames;
- map contributors and persistent identifiers where available;
- represent included files as data entities when appropriate;
- preserve links/PIDs to authoritative external data without requiring duplication;
- include the canonical ORW project record so the package remains identifiable as an ORW export.
ORW MUST NOT claim conformance to a dedicated ORW RO-Crate profile until that profile has a documented, versioned mapping and validated implementation evidence.
See docs/ro-crate.md for the export design and planned validation strategy.
The primary GitHub implementation maps the scientific hierarchy to:
README.md # Investigation
studies/<study-id>/ # Study
studies/<study-id>/assays/<assay-id>/ # Assay
references/ # Investigation-wide scholarly context
project-docs/ # Investigation-wide project context
Study and Assay folders MAY contain pragmatic workspace subfolders such as data, analysis, results and protocols. Paths are a human interface; canonical metadata MUST explicitly represent scientific relationships rather than relying only on folder inference.
Authoritative data MAY live outside GitHub and be referenced by location or persistent identifier.
ORW specification version.
The canonical overall scientific project context. It SHOULD support an identifier, title, description, contacts/contributors, publications, related identifiers and Studies.
Research units belonging to the Investigation. Each Study MUST have a stable workspace identifier and SHOULD describe design context, subjects/sources/samples, factors, protocols and Assays as appropriate.
Measurements/tests belonging to a Study. Each Assay SHOULD identify what is measured, the technology/method, relevant protocol/process context and associated data.
ORW MAY describe workspace resources and outputs not fully represented by ISA, including software, documentation, manuscripts, models and workflows. These MUST be related to the relevant Investigation, Study or Assay when scientifically applicable.
ORW SHOULD progressively preserve ISA-compatible subject/sample/process/data relationships. A simplified conceptual flow is:
Investigation
→ Study
→ subjects/sources/samples
→ processes + protocols + factors
→ Assay
→ data
→ analysis
→ results/publication
Source evidence SHOULD NOT be silently overwritten. Derived data and outputs SHOULD be traceable to their inputs and methods as reproducibility capabilities mature.
Profiles are initialization conveniences, not alternate scientific models. Experimental and mixed profiles MUST preserve ISA hierarchy. Other profiles MAY use a meaningful subset and MUST NOT invent fake ISA entities.
.research/workspace.yml records ORW implementation/version state. .research/capabilities.yml records optional capabilities such as archival publication, FAIR enrichment, reproducibility, AI-ready context or agent support.
Capabilities MUST NOT redefine ISA or Core semantics.
ORW implementations MUST NOT require a specific forge. A valid ORW workspace remains valid without Git, GitHub, GitLab, or any hosted collaboration service.
The current GitHub template is a supported reference implementation and adapter. Its intended workflow is:
Use template
→ create Investigation workspace
→ first-time setup
→ describe Investigation
→ create initial Study
→ create Assay/measurement where applicable
→ collaborate/work
→ publish intentionally
The beginner UI SHOULD automatically create a sensible one-Investigation/one-Study structure and ask about Assays only in scientifically understandable language such as "What measurements or tests are you performing?".
Provider-neutral implementations SHOULD converge on one normalized generation contract so that CLI, browser, and forge adapters produce semantically equivalent canonical project records. The planned CLI and browser generator are described in docs/portable-implementations.md.
Implementations SHOULD NOT require ordinary researchers to understand Git, YAML, ISA-Tab, ISA-JSON, CI/CD, tags or GitHub Actions. ISA semantics should be captured through researcher-facing language and forms.
Publication MUST be intentional. Automated validation MAY determine readiness, but routine edits MUST NOT automatically create permanent scientific releases.
Extensions and agents MUST consume the canonical ISA-aligned project model rather than create parallel scientific truth. Agent-specific instructions are not part of Core v0.1, but agents should eventually be able to distinguish Investigation, Study, Assay, subjects/samples, processes, data and derived outputs explicitly.
A conforming project record MUST validate against schema/project.schema.json. The schema will evolve from the current draft toward stronger ISA alignment and validated ISA import/export. Until that mapping is complete, ORW MUST describe itself as ISA-aligned rather than claiming full ISA serialization conformance.