Abstract

Open Science Archive Enhancement Proposals (OEPs) are the primary mechanism for proposing new features, collecting community input, and documenting the design decisions that shape the Open Science Archive (OSA) protocol. Because the OSA is a standard intended for long-term preservation and interoperability, OEPs serve as the historical record of the protocol's evolution.

This document defines the OEP process, the role of the OEP Editors, and the workflow for submitting and ratifying proposals.

Motivation

For the Open Science Archive to succeed as an open, neutral standard, its development must be transparent, inclusive, and rigorous. We cannot rely on implicit knowledge or ad-hoc decisions committed to a codebase.

A formalised proposal process ensures that:

Design precedes Implementation: Architectural risks are identified before code is written.
Rationale is Preserved: Future maintainers understand why a decision was made, preventing Chesterton's Fence violations.
Ecosystems can Diverge: By specifying the protocol separately from the reference implementation (Python), we enable compliant implementations in other languages (Rust, Go) and hardware.

Specification

OEP Types

There are three primary types of OEPs:

Technical These describe a new feature or implementation for the OSA protocol. They are normative.
Informational These describe a design issue, general guidelines, or information to the community, but do not propose a new feature. They do not necessarily represent a community consensus or recommendation.
Process These describe a process surrounding OSA, or propose a change to (or an event in) a process. They are like Technical OEPs but apply to areas other than the OSA protocol itself (e.g., this document).

The OEP Lifecycle

The lifecycle of an OEP is managed via Pull Requests to the opensciencearchive/oeps repository. An OEP remains as a PR during its development and review phases, and is only merged once a final decision has been reached.

1. Draft

An OEP begins as a Pull Request with status: draft in the preamble. This indicates work-in-progress that is not yet ready for community review. Draft OEPs are not shown on the public website.

The author iterates on the proposal, collecting early feedback from collaborators in the PR comments.

2. Review

When the author believes the OEP is stable and complete, they update the status to review. This signals to the community that the proposal is ready for formal scrutiny and appears in the "Under Review" section of the website.

The review period allows for:

Community feedback and discussion in PR comments
Technical review by OEP Editors
Revisions by the author in response to feedback

The OEP remains as an open PR throughout this phase.

3. Final States

When a decision is reached, the author (or an Editor) updates the status to one of the final states, and the PR is merged:

Accepted The proposal has been ratified. The OEP becomes part of the official specification. For Technical OEPs, a reference implementation SHOULD accompany acceptance.

Rejected The Editors have determined the proposal is technically unsound, misaligned with the OSA mission, or lacks sufficient community support. The OEP is merged for posterity, preserving the discussion and rationale.

Withdrawn The author has voluntarily withdrawn the proposal. This may happen if the author loses interest, the problem is solved another way, or circumstances have changed. The OEP is merged to preserve the historical record.

4. Living

A special status for OEPs that are continuously updated and never reach a final state (e.g., this document, OEP-0001). Living OEPs are merged but may receive ongoing amendments.

Workflow Summary

                    ┌─────────────────────────────────────┐
                    │           Pull Request              │
                    │                                     │
   ┌────────┐       │   ┌────────┐       ┌────────┐      │
   │  New   │──────▶│   │ Draft  │──────▶│ Review │      │
   │   PR   │       │   └────────┘       └────┬───┘      │
   └────────┘       │                         │          │
                    └─────────────────────────┼──────────┘
                                              │
                                              ▼ merge
                    ┌─────────────────────────────────────┐
                    │           Main Branch               │
                    │                                     │
                    │   ┌──────────┐  ┌──────────┐       │
                    │   │ Accepted │  │ Rejected │       │
                    │   └──────────┘  └──────────┘       │
                    │   ┌───────────┐ ┌──────────┐       │
                    │   │ Withdrawn │ │  Living  │       │
                    │   └───────────┘ └──────────┘       │
                    └─────────────────────────────────────┘

Editor Merge Workflow

Because PRs may originate from forks where Editors cannot push directly, the following process applies:

Decision is reached — The Editors communicate acceptance, rejection, or the author decides to withdraw.
Status is updated — The author updates the frontmatter status. If the author is unresponsive, an Editor may:
- Push to the PR branch (if "Allow edits from maintainers" is enabled), or
- Merge the PR and later change the status on the main branch.
PR is merged — The Editor merges the PR, completing the process.

OEP Format and Template

All OEPs MUST be written in Markdown. The file MUST be located in the oeps/ directory and named OEP-XXXX.md, where XXXX is the assigned number (padded with zeros).

Header Preamble

Each OEP MUST begin with an RFC 822 style YAML header:

---
oep: <OEP number, zero-padded>
title: <OEP title>
status: <draft | review | accepted | withdrawn | rejected | living>
type: <technical | informational | process>
author: <list of authors' real names and email addresses>
created: <date created on, in ISO 8601 (YYYY-MM-DD) format>
requires: <OEP numbers> (optional)
replaces: <OEP numbers> (optional)
---

Required Sections

Abstract: A short (~200 word) description of the technical issue being addressed.
Motivation: The problem description. This section MUST address the Scientific Context (why this helps research) separate from the Technical Context.
Specification: The technical syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations.
Rationale: The flesh of the specification. It should describe what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work.
Backwards Compatibility: All OEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The OSA protocol emphasises long-term preservation; breaking changes are strongly discouraged.
Rejected Alternatives: Explanation of the alternative solutions considered, and the reasons for their rejection.
Security & Privacy: A discussion of the security and privacy implications of the change.
Open Issues: Description of the known bugs, future work, or yet-unclarified questions relating to the proposal.

OEP Editors

The OEP Editors are responsible for the administrative and editorial aspects of the OEP workflow. They do not determine scientific merit, but ensure technical completeness and adherence to the process.

Current Editors:

Rory Byrne (rory@rory.bio)

Auxiliary Files

OEPs may include auxiliary files such as diagrams, JSON schemas, or example datasets. These files should be placed in a subdirectory named assets/oep-XXXX/.

Rationale

OSA adopts this process to balance the need for rigorous standardisation with the agility required by modern software development.

We examined the processes of Python (PEPs), Rust (RFCs), and Ethereum (EIPs).

We adopted the YAML Preamble from EIPs for machine readability on the oeps.opensciencearchive.org website.
We adopted the Reference Implementation requirement from Python to ensure no "vaporware" standards are ratified.
We added the specific requirement for Scientific Context in the Motivation section to ensure the protocol remains grounded in the needs of researchers, not just software engineers.

Rejected Alternatives

Open Issues

Should accepted OEPs be given DOIs?