OBIS-0001: OBIS Document Lifecycle#

Status: Draft · Version: v1-draft · Date: 2026-05-19 · Editor: Bernhard Haslhofer

Abstract#

This document defines the lifecycle of OBIS standards documents: their states, the transitions between them, the rules governing identifiers and versioning, and the roles of editors, working group chairs, and contributors. It applies to itself.

1. Introduction#

OBIS standards are published as numbered documents under the identifier scheme OBIS-NNNN. Each document progresses through a defined sequence of states, from initial drafting to publication, and may be later superseded or withdrawn. This document specifies that sequence and the conditions for moving between states.

The lifecycle is intentionally lightweight. It is modelled on IETF RFC 2026 and the W3C Process Document, and informed by the Bitcoin BIP-2 and Ethereum EIP-1 processes that have run similar work in crypto-native communities for over a decade. The result is reduced to what is necessary for a small, public, openly-developed body of work.

2. States#

A document is at any time in exactly one of the following states.

  • Draft. Under active development. Content, structure, and scope may change without notice. No stability commitments.
  • Public Review. Content is frozen for a defined window during which the public is invited to submit comments. The default window is 30 days.
  • Published. The document has completed Public Review, substantive objections have been addressed, and the editor and (when present) the working group chair have signed off. The content and identifier are stable.
  • Superseded. A later Published version of the same OBIS-NNNN document has replaced this one. The superseded version remains accessible at its versioned URL.
  • Withdrawn. The document has been retired without replacement. A retention notice with the reason remains at its URL.

3. State transitions#

3.1 Draft → Public Review#

The editor opens a pull request titled Public Review: OBIS-NNNN v<n>. The PR description records:

  • the version under review,
  • the start and end dates of the comment window,
  • the URL declared in the document’s discussions-to preamble field, which is the canonical venue for comments during the review window.

The transition is announced on the OBIS site and in any active community channels at the start of the window.

3.2 Public Review → Published#

After the comment window closes:

  1. The editor responds publicly to each substantive comment received, indicating whether the comment was accepted, declined with rationale, or deferred.
  2. Changes resulting from accepted comments are merged.
  3. The editor and the working group chair for the document’s focus area sign off via PR approval.

The version is then tagged in git and the document URL is promoted to Published.

3.3 Solo-editor mode#

Until working group chairs are appointed for a focus area, the editor publishes after the 30-day Public Review window followed by a 7-day no-objection period announced at the close of review. This provision exists to enable an early body of published work to accumulate, and is removed for a focus area as soon as its working group chair is in place.

3.4 Published → Superseded#

A new Published version of the same OBIS-NNNN document supersedes the prior version. The superseded version retains its versioned URL and is marked with a Superseded badge linking to the current version.

3.5 Any → Withdrawn#

The editor may withdraw a document with documented reason. The original URL is retained and serves a Withdrawn notice in place of the body.

4. Identifiers#

Every OBIS document carries a permanent four-digit identifier of the form OBIS-NNNN, assigned in submission order at the time the document first enters the Draft state. Identifiers are never reused.

The identifier is independent of the document’s title and focus area; renaming or re-scoping a document does not change its identifier.

5. Versioning#

Versions within a single OBIS-NNNN document are numbered v1, v2, v3, … incrementing on each Published release. Within a version, the state-specific tags are:

  • v<n>-draft while in Draft,
  • v<n>-pr while in Public Review,
  • v<n> once Published.

Editorial corrections that do not alter normative content (typographical fixes, dead-link repair, formatting) do not bump the version. Any change to normative content requires a new version, which re-enters the lifecycle at Draft.

6. URLs#

  • Current Published version: https://obistandards.org/standards/OBIS-NNNN/
  • A specific historical version: https://obistandards.org/standards/OBIS-NNNN/v<n>/
  • The active draft, when one exists: https://obistandards.org/standards/OBIS-NNNN/draft/

The current-version URL always resolves to the most recent Published version, or — if no version is yet Published — to the document in its current pre-publication state.

7. Required document structure#

Every OBIS document MUST contain, in order:

  1. A title of the form OBIS-NNNN: <name>.
  2. A one-line status block: state, version, date, editor.
  3. An abstract of one paragraph.
  4. A numbered normative body.
  5. A references section.

Every OBIS document MUST also carry a discussions-to field in its front-matter, pointing at a single GitHub Discussion thread that serves as the canonical venue for public comments on the document. This convention is borrowed from the Ethereum EIP-1 preamble.

Documents MAY contain additional appendices, examples, and non-normative discussion. Normative content uses the keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in the sense of RFC 2119.

8. Roles#

  • Editor. Shepherds the document through its states, integrates contributions, and is responsible for the public response to Public Review comments. At founding, all documents are edited by Bernhard Haslhofer; editorship transfers to a working group chair once one is appointed for the focus area.
  • Working group chair. Owns a focus area, co-signs publication of documents within it, and resolves disputes between contributors. Vacant at founding.
  • Contributor. Any individual proposing edits via pull request on the source repository. No membership or credential is required.

9. Source of truth#

OBIS documents are authored in Markdown in the obi-standards/website repository under content/standards/OBIS-NNNN/. The git history of that path is the document’s editorial history. The rendered HTML at obistandards.org is derived; in the event of a discrepancy, the source repository prevails.

10. Amendments to this document#

This document is itself OBIS-0001 and progresses through the lifecycle it defines. Substantive amendments are issued as a new version under the same identifier and re-enter the lifecycle at Draft.

References#

  • IETF RFC 2026, The Internet Standards Process, Revision 3.
  • IETF RFC 2119, Key words for use in RFCs to Indicate Requirement Levels.
  • W3C, W3C Process Document.
  • Bitcoin, BIP-2, BIP process, revised.
  • Ethereum, EIP-1, EIP Purpose and Guidelines.
Backward Standards OBIS-0002: Address Attribution Data Model Forward