← riVer  ·  v1 · draft · 2026-03-31 08:28Z  ·  raw

The riVer Specification v1_draft_20260331T082800Z

riVer (revision identifier versioning) is a standard for a simple and strict versioning scheme for textual content.

It is designed for agentic environments where AI agents both read and write versioned textual content, possibly under human supervision.

The standard draws inspiration from incremental revision numbers used in classic version control systems or word processors, book editions, and [CalVer]. It deliberately creates an alternative to [SemVer] to avoid the ambiguities around change significance.

The riVer specification is versioned according to the versioning scheme it defines.

Definitions

Revisions

A text is a (possibly empty) sequence of characters forming a connected piece of work (e.g. a file, webpage). The unique text consisting of the empty sequence of characters is called the empty text.

An edit is the fundamental and atomic action changing a text by either

  • inserting a non-empty, contiguous sequence of characters into it,
  • removing a non-empty, contiguous sequence of characters from it,
  • replacing a non-empty, contiguous sequence of characters from it with an unequal, non-empty contiguous sequence of characters.

A revision is the result of applying an edit to a text (i.e. a revision is a text). A new text is created by applying an edit (called the initial edit) to the empty text resulting in the so-called initial revision.

Revision Identifiers

A revision number is a non-zero natural number.

A revision status is a value from the enumeration

  1. draft
  2. ready
  3. final

A timestamp is a [ISO 8601]-compliant string in the format YYYYMMDDThhmmssZ (date and time with second precision in UTC using the basic format to maximize usability in filenames, URLs etc.).

Timestamps are totally ordered using their natural alphanumerical ordering. A timestamp is called later than another timestamp if it is greater, and earlier if it is smaller than the other timestamp.

A revision timestamp is either

  • a timestamp, or
  • the literal string now.

A revision timestamp is called indefinite if it is equal to now, and definite otherwise.

Revision timestamps are totally ordered by defining now to be smaller than any definite revision timestamp and use the total order of definite revision timestamps otherwise.

A revision tag is a string of the format v[REVISION_NUMBER]_[REVISION_STATUS]_[REVISION_TIMESTAMP].

A revision tag is called fixed if it has a definite revision_timestamp, and floating otherwise.

Revision tags are totally ordered by the lexicographical order of their constituents in order of appearance in the revision tag string, where revision numbers are ordered naturally (i.e. by numeric value), revision statuses are ordered by their enumeration ordinal, and revision timestamps are ordered as defined above.

A revision is called tagged (or a tagged revision) if it has an associated revision tag (called the revision identifier or simply identifier) which is contained in the revision’s character sequence. In case the revision’s character sequence contains more than one revision tag, the revision identifier must be the first occurence of a revision tag in the revision’s character sequence.

Documents

A modification is a triple consisting of

  • an edit,
  • a revision,
  • a timestamp.

The edit contained in a modification is called the modification edit, the contained revision is called the modification revision, and the contained timestamp is called the modification timestamp. A modification is called later than another modification if its modification timestamp is later than the other modification’s timestamp and earlier if its modification timestamp is earlier than the other modification’s timestamp.

A document is a non-empty sequence of modifications such that

  • the sequence of modification timestamps is strictly increasing,
  • the first modification contains an initial edit and the resulting initial revision,
  • for any two consecutive modifications the later modification’s revision is the result of applying the later modification’s edit to the earlier modification’s revision.

For two consecutive modifications of a document the later modification is said to be right after the earlier modification.

The first modification is also called the initial modification. For a given point in time the last modification of a document is called the current modification.

A new document is created by creating a text and using the resulting initial edit and initial revision together with the current point in time timestamp to form the document’s initial modification.

A document is modified by adding a new modification as its current modification to it with the current point in time timestamp as the modification timestamp.

A document is called tracked (or a tracked document) if

  • all its modification revisions are tagged,
  • the sequence of modification revision identifiers is increasing.

For a tracked document, its current modification revision identifier is called the document's revision identifier.

A tracked document is called floating if its revision identifier is floating.

A tracked document is called fixed if its revision identifier is fixed.

A floating tracked document is (or gets) stamped if it is modified such that the new modification edit replaces the document’s identifier timestamp (now) with the new modification timestamp (i.e. changing it to a fixed tracked document).

Resources

A document is called a copy of another document (called the source document) if its initial edit adds the entire character sequence of the source document’s current modification revision to its initial revision at the point of time given by its initial event timestamp. In this case the source document, the source document’s current modification, and the source document’s current modification revision are called copied.

A resource is a non-empty collection of documents consisting of exactly one distinguished document called the golden source and a (possibly empty) collection of documents which are all copies of the golden source such that each golden source modification is copied at most once.

A new resource is created by creating its golden source, i.e. a newly created resource consists exactly of its golden source, and the golden source consists exactly of its initial modification.

A resource is called tracked (or a tracked resource) if

  • all contained documents are tracked,
  • all modification revision identifiers of the golden source are floating,
  • every new copy of the golden source gets stamped right after its initial modification and does not get modified anymore afterwards.

A new tracked resource should be created with its golden source initial modification revision identifier set to v1_draft_now.

Terminology

A tracked resource is said to be (or to get) bumped if a modification of its golden source results in a strictly larger golden source revision identifier. In case this increase results from an increase of the identifier’s *revision status alone (i.e. the identifier’s revision number stays the same), the tracked resource is said to be (or to get) advanced. In case this increase results from an increase of the identifier’s revision number, the tracked resource is said to be (or to get) promoted.

A tracked resource is said to be (or to get) stamped if a new copy of its golden source is created and subsequently stamped.

Every copy contained in a tracked resource is called a resource publication (or publication for short). If the revision status of the revision identifier of such a copy equals draft, ready, or final respectively, the publication is called an intermediate, a candidate, or a release respectively (or resource intermediate, resource candidate, or resource relase respectively).

To publish a resource means to optionally bump and then stamp the resource to create a new resource publication. To publish an intermediate, a candidate, or a release respectively means to publish the resource** such that the resulting *resource publication is an intermediate, a candidate, or a release respectively.

For a resource, its publication, intermediate, candidate, or release respectively with the largest revision identifier of all its publications, intermediates, candidates, or releases respectively is called its latest (or current) publication, intermediate, candidate, or release respectively.

The latest (or current) version of a resource (also called the latest (or current) resource version) is the revision number of the revision identifier of its latest release (if it exists).

If the latest resource version does not change when a new resource release is published, this resource release is called an errata. To publish an errata means to publish a release that is an errata.