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. This document defines the OEP process and the workflow for submitting proposals.

Motivation

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

A formalised proposal process ensures that:

Ideas are welcomed early: Contributors can share rough ideas without needing a complete specification.
Discussion is centred: Every proposal has a clear place for community feedback.
Rationale is preserved: Future maintainers understand why a decision was made.
Implementations can diverge: By specifying the protocol separately from implementations, we enable compliant software in any language.

Specification

OEP Lifecycle

The lifecycle of an OEP is managed via Pull Requests to the opensciencearchive/oeps repository. An OEP progresses through states as it matures from idea to ratification.

            ┌─────────────────────────────────────────────┐
            │              Pull Request                   │
            │                                             │
            │   ┌───────────┐       ┌────────────┐       │
   Create   │   │           │       │            │       │
   ───────▶ │   │  Ideation │──────▶│ Discussion │       │
     PR     │   │           │       │            │       │
            │   └───────────┘       └─────┬──────┘       │
            │                             │              │
            └─────────────────────────────┼──────────────┘
                                          │
                                          ▼ merge
            ┌─────────────────────────────────────────────┐
            │              Main Branch                    │
            │                                             │
            │   ┌──────────┐        ┌──────────┐         │
            │   │ Accepted │        │  Living  │         │
            │   └──────────┘        └──────────┘         │
            │                                             │
            │   ┌───────────┐                            │
            │   │ Abandoned │                            │
            │   └───────────┘                            │
            └─────────────────────────────────────────────┘

States

Ideation A placeholder for an idea worth exploring. The document may contain only a problem statement or rough sketch. No active revision is expected—this state signals "I think this is interesting" and invites early feedback.

Discussion The proposal is actively being developed and discussed. The author is iterating on the design based on community feedback in the PR. This is the primary collaborative phase.

Accepted The proposal has been ratified and merged. It is now part of the official specification. Accepted OEPs are considered stable; changes require a new OEP or amendment process.

Living A special status for OEPs that are continuously updated. Living OEPs are accepted but expected to evolve over time (e.g., this document). They remain open to refinement without requiring new proposals.

Abandoned The proposal is no longer being pursued. This may happen if the idea proves non-viable, is superseded by another approach, or the author loses interest. Abandoned OEPs are merged to preserve the historical record and discussion.

Workflow

Create a PR with your OEP in oeps/OEP-XXXX.md. Start with status: ideation if you have a rough idea, or status: discussion if you have a more complete proposal.
Iterate in the PR. Respond to feedback, refine the proposal, and update the document. The PR is the centre of discussion.
Move to discussion when ready. If you started in ideation, update to status: discussion when you want active review.
Merge when accepted. When consensus is reached, update to status: accepted (or status: living for continuously-updated documents) and merge the PR.

At any point, a proposal may be marked status: abandoned if it is no longer viable.

OEP Format

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 (zero-padded to 4 digits).

Header Preamble

Each OEP MUST begin with a YAML frontmatter block:

---
oep: 0005
title: Your Proposal Title
type: technical | process | informational
status: ideation | discussion | accepted | living | abandoned
authors: Your Name <email@example.com>
created: 2025-12-07
discussion: https://github.com/opensciencearchive/oeps/pull/5
labels: storage, encryption
requires: 0002, 0003
supersedes: 0001
---

Required fields:

oep — The OEP number, zero-padded to 4 digits
title — A concise, descriptive title
type — Category: technical, process, or informational
status — Current state (see above)
authors — Author name(s) and email address(es)
created — Date created in ISO 8601 format (YYYY-MM-DD)

Optional fields:

discussion — URL to the PR or discussion thread
labels — Comma-separated list of topic labels for discoverability
requires — OEP numbers this proposal depends on
supersedes — OEP numbers this proposal replaces

Types

Every OEP must have one of three types:

Technical — Proposes changes to the protocol, data formats, APIs, or implementation requirements. Most OEPs are technical.
Process — Proposes changes to governance, workflows, or community guidelines. This OEP is a process OEP.
Informational — Provides context, best practices, or explanatory content without proposing changes.

Labels

Labels are free-form tags that aid discovery and filtering. Use lowercase, hyphenated terms. Some common labels:

protocol — Core protocol specifications
storage — Data storage and retrieval
metadata — Metadata schemas and standards
cryptography — Signatures, hashes, encryption
api — Interface definitions
archival — Long-term preservation concerns

Required Sections

Abstract — A short (~200 word) description of the issue being addressed.
Motivation — The problem description, including both scientific context (why this helps research) and technical context.
Specification — The technical details. Should be detailed enough to allow interoperable implementations.
Rationale — Why this design was chosen. Describe alternatives considered and related work.
Backwards Compatibility — Any breaking changes and how they will be handled.
Security & Privacy — Security and privacy implications of the proposal.
Open Issues — Unresolved questions or future work (may be empty for accepted OEPs).

Auxiliary Files

OEPs may include diagrams, schemas, or examples. Place these in assets/oep-XXXX/.

Rationale

This process is inspired by Oxide's RFD process, adapted for the needs of an open protocol specification.

Key design decisions:

Types and labels. OEPs have both a fixed type (technical, process, informational) and free-form labels. The type categorises what kind of change is being proposed, while labels aid discovery and filtering by topic.

Ideation as a first-class state. Lowering the barrier to contribution means accepting rough ideas. The ideation state signals "this isn't ready for detailed review, but feedback on the direction is welcome."

Discussion-centred workflow. The PR is the canonical location for discussion. Every OEP links to its discussion, making it easy for newcomers to understand the context and reasoning.

Living documents. Some OEPs (like this one) need to evolve continuously. The living status acknowledges this reality and avoids the overhead of creating new OEPs for minor process updates.

Backwards Compatibility

N/A — this is a process document.

Security & Privacy

This OEP defines a governance process and has no direct security or privacy implications.

Open Issues

Should we adopt a "3-5 business days" comment period before merging, as Oxide does?
Should accepted OEPs be given DOIs for academic citation?