[OpenSheaf] [specification] [use cases] [FAQ] [first archive]OpenSheaf

OpenSheaf: an open format for document archives and collections

Specification, version 0.1 (draft), 13 November 2026. OpenSheaf is a common, open format for archives of scholarly documents and for collections of them, built on the Oxford Common File Layout (OCFL 1.1) and the DataCite Metadata Schema (4.7). This version is experimental and may change in incompatible ways before version 1.0. The text is licensed under CC BY-SA 4.0; the JSON Schemas are dedicated to the public domain under CC0 1.0.
Warning. Draft. This version is a draft. Until version 1.0, any revision may change the format in incompatible ways, and archives and collections made now may have to be rebuilt or migrated. Do not rely on it yet for anything you cannot redo. Changes are listed in the changelog (section 17) and discussed in the issues.

1. Introduction (non-normative)

OpenSheaf is meant as a lean alternative to arXiv and to the usual publication infrastructure. Any author, group or institution can keep an archive of its documents as plain files, served as a static website, checkable by anyone, and composable with other archives:

Answers to common questions about the design are collected in the FAQ.

The name: a sheaf is a bundle of papers and, in mathematics, the structure in which local pieces glue into a whole, as archives kept and verified separately compose into collections. The home of the format is https://opensheaf.org/. The first OpenSheaf archive is https://mgubi.org/papers/; its values appear in the examples.

2. Conventions

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY and OPTIONAL in this document are to be interpreted as described in BCP 14 (RFC 2119 and RFC 8174) when, and only when, they appear in all capitals.

Sections marked non-normative, examples, notes and the appendices marked as such are informative. JSON means RFC 8259 JSON encoded in UTF-8 without a byte order mark. URLs are absolute unless stated otherwise; a relative URL in a JSON file is resolved against the URL of that file.

3. Terminology

4. Conformance

This specification defines the following conformance classes. An archive, object or program conforms to a class if it satisfies every MUST and MUST NOT of the sections listed for it.

The JSON files defined here (opensheaf.json, object.json, members.json) MUST validate against the JSON Schemas of appendix D for their declared format version.

5. Layout

An archive consists of:

Because OCFL does not allow directories other than objects and extensions inside a storage root, the storage root SHOULD be a dedicated folder (by convention ocfl/), and presentation files MUST NOT be placed inside it.

All files of the discovery document, the storage root and witnesses/ (if used) MUST be served byte for byte, as stored: no conversion of line endings or character sets, no compression that changes the bytes delivered after decoding. Archives kept in git SHOULD mark these files as binary (for instance with .gitattributes lines ocfl/** -text and opensheaf.json -text). Archives SHOULD be served over HTTPS and SHOULD allow cross-origin requests to these files (Access-Control-Allow-Origin: *), so that tools running in a browser can resolve members.

An archive MAY be kept in git and served by any static web server (GitHub Pages, object storage, a university server). A deployment guide, outside this specification, discusses hosting limits and practices.

6. Discovery and identity

6.1 The discovery document

The discovery document is the JSON file opensheaf.json at the base URL of the archive. It MUST contain:

It MUST also contain profiles, the list of profiles followed, from zenodo, texmacs, website (an empty list if none). It SHOULD contain mainCollection (the identifier of the collection that lists the archive's own documents) and contact (a URI). It MAY contain mirrors (base URLs of complete copies of the archive), tombstones (section 11.3), keys (section 13.2) and feed (the URL of an Atom feed of new object versions).

The discovery document is mutable: it is rewritten whenever an object is added or changed. It is a map, not a witness: what it states about objects (objects: kinds, head versions, digests, status) MUST be verifiable from the storage root. Digests are written in lowercase hexadecimal, here and in every file defined by this specification.

6.2 Archive identifiers

An archive identifier is a URI that does not change when the archive moves. It SHOULD be a tag: URI (RFC 4151) built from a domain or e-mail address controlled by the owner at the time of creation and a date, for instance tag:opensheaf.org,2026:mgubi. A DOI or another persistent URI MAY be used instead. Two different archives MUST NOT use the same archive identifier.

6.3 Object identifiers

An object identifier MUST match ^[a-z0-9]+(-[a-z0-9]+)*$ and MUST be at most 64 characters long. It is the OCFL id of the object and the name of its folder in the storage root. It MUST be unique in the archive and MUST NOT be reused, also after a takedown. Since it is permanent and appears in every URL of the object, it SHOULD be short (at most 32 characters), readable and chosen by the depositor, and SHOULD NOT be derived mechanically from the title, which may change between versions while the identifier cannot; tools importing documents propose identifiers and the depositor decides. The kind of an object is given by its object.json, never by its identifier. Outside the archive, an object is named by the pair (archive identifier, object identifier).

6.4 Resolution

To fetch an object version of a member, a client:

Any copy whose bytes match the pinned digest is acceptable: integrity comes from the pin, not from the place.

7. Objects

7.1 Common rules

Every object MUST be a valid OCFL 1.1 object. Its inventories MUST use sha512 as digest algorithm. Every object version MUST contain, in its content, the files object.json and datacite.json at the top level. Every version directory MUST contain a copy of the inventory as of that version, with its checksum file (OCFL makes this a recommendation; OpenSheaf requires it, so that each version can be pinned and fetched on its own). Version directories MUST NOT be zero-padded (v1, v2, …, not v001), which OCFL allows. OCFL recommends that object identifiers be URIs; OpenSheaf identifiers are short names (section 6.3), so OCFL validators may warn about them.

Each version in the inventory MUST have a user with a name, and SHOULD have an address (an ORCID iD, a mailto: URI or another URI identifying the depositor), and MUST have a message describing the change. The inventory is the record of deposits: the created date and the user of an object version are when and by whom it was deposited, and the deposit of a document version is that of the first object version holding it. They are not repeated in object.json.

Logical paths MUST be encoded in UTF-8 in Unicode normalisation form C, MUST NOT begin with /, and MUST NOT contain . or .. segments.

7.2 Documents

A document version contains, at the top level of its content unless a profile says otherwise:

HTML versions and other presentation files SHOULD NOT be deposited, since they depend on the presentation and are regenerated when it improves.

7.3 Document versions

Numbering. Document versions are numbered by the archive, from 1, without gaps, independently of any external numbering: a work whose versions 1, 3 and 4 are available on arXiv has document versions 1, 2 and 3. External labels (arXiv's v3) are recorded in external (section 9), and presentations SHOULD show them with the document version.

New versions. A new document version number is assigned exactly when files of the document's own (sources, renditions, change note) that were not deposited before are added, except when a version without sources is completed (below). An object version holding the same sources, renditions and change note as an earlier document version keeps its number.

Description-only versions. A description-only version holds an existing document version, with its files unchanged, and changes only its description (datacite.json, such as a DOI, a stage or a link to the published article), the state of the object or its notices. It MAY hold any document version, not only the current one, so that an earlier version can be described after later versions exist; tools otherwise hold the current version. If the object has history, its entry for that document version becomes the new object version.

Completion. A document version recorded without sources (section 9, sourcesMissing) MAY be completed later, keeping its number: the completing object version adds the sources, and MAY add renditions produced from them (for instance a PDF typeset from the added sources, beside the one received), but changes or removes no file of the version; until the sources are complete it keeps sourcesMissing and names no main source; the object version that completes them names the main source and removes sourcesMissing, after which the version is fixed like any other.

Other versions. A version that was not public at the time, such as the manuscript submitted to a journal, deposited later, is a document version like any other. A version published by someone else, such as the journal's version of record, is not a document version of the author's object: it is linked by a relation (section 8.1).

History. The order of the document versions in the history of the work is the order of their numbers, unless object.json has history (section 9): the list, in the order of the work, of the last object version holding each document version. The last object version is used because it carries the most complete description of that document version (a DOI added later, a corrected stage). An object version that deposits a document version out of order (an earlier version found later) MUST write history, and once an object version has history, every later object version MUST have it. A version whose place in the history is unknown goes just before the current version, and its object.json SHOULD say so in its change note. The history is read from the head version; earlier object versions keep the history as it was known when they were made.

Current version. The current version of a document is the last entry of the history of its head version (without history: the highest document version). The head may hold another document version, after an earlier version is deposited out of order or described by a description-only version; the current version stays where it was. Landing pages, indexes and citations use the current version, not the head; selections vet revisions explicitly (section 10.2).

Notices. A notice about a document version (for instance that a theorem of version 2 is wrong as stated, and is corrected in version 3) is written after that version, which cannot change. Notices are added to notices in object.json (section 9) by description-only versions. A notice present in an object version is present, unchanged, in every later object version; a notice is corrected or withdrawn by a later notice that says so. Presentations showing a document version SHOULD show the current notices about it.

Dates never order document versions and never decide the current version (section 8).

7.4 Collections

A collection version contains datacite.json, object.json and members.json (section 10), which states whether the collection is an archive collection or a selection. Its object.json declares kind collection; its document version counts the changes of the member list, and it has none of the fields specific to documents (mainSource, sourceFormat, sourcesMissing, renditions, toolchain, changes, stage, history, notices).

8. Description: datacite.json

Every object version MUST contain datacite.json, a JSON object with the DataCite 4.7 properties in the form of the attributes of a DOI in the DataCite REST API. It is the authoritative description of the object version. It MUST contain:

It SHOULD contain:

publisher is the archive's name, or the external service registering a DOI for the version (appendix A). publisher and affiliation SHOULD be written as objects (with name and, where available, an identifier); readers MUST also accept plain strings.

doi and url are OPTIONAL: they are present when the version has a DOI. types gives the kind of content: resourceTypeGeneral from DataCite's list (Preprint, JournalArticle, Book, Dissertation, Report, Text, Dataset, Software, Audiovisual and so on, and Collection for collections), with resourceType for detail (for instance "Lecture notes"). An author's versions of a work not published elsewhere are Preprint, also the accepted manuscript; the stage of a version is given by stage in object.json (section 9).

Dates. Dates are information for readers and services: they never order document versions (section 7.3). Each date type has one meaning:

Mathematics in titles and abstracts. Titles and abstracts are plain text in which mathematics MAY be written in LaTeX between single dollar signs ($\Phi^4_3$); a literal dollar sign is written \$. The LaTeX SHOULD use only the mathematical commands of LaTeX with the amsmath and amssymb packages, which common renderers (MathJax, KaTeX) display without the document's preamble; presentations render it, and readers that do not are left with readable LaTeX. Tools importing titles and abstracts from elsewhere SHOULD replace the authors' own macros (such as \R or \be) with standard LaTeX when their definitions are known, for instance from the preamble of the imported sources, and otherwise keep them unchanged; they MUST NOT invent definitions.

Dates MAY be approximate, as DataCite allows (2019, 2019-03, a range 2018/2019), with dateInformation explaining them (for instance "from file timestamps"); unknown dates are omitted.

8.1 Relations

9. The object: object.json

Every object version MUST contain object.json, OpenSheaf's record of the object as of that version: its identity, the structure of its content, its versions and its state. It MUST contain:

A document MUST also have mainSource (a logical path) and sourceFormat (the media type of the main source), and SHOULD have renditions (a list of objects with path, a logical path, and mediaType) and toolchain (a list of tools with name, version and, optionally, packages), enough to reproduce the renditions. A document version whose sources are not available instead has sourcesMissing, a note (see below) saying why (for instance "arXiv keeps only the PDF of this version"), no mainSource and sourceFormat, and at least one rendition; a rendition is never presented as a source.

A note is an object with text (a short plain text), or path and mediaType (a file of the content of the same object version), or both: the text serves feeds, indexes and external services, the file holds the full statement (with mathematics, or as a PDF). Files of notes are covered by the inventory like every file of the content.

A document MAY contain:

Any object MAY contain:

object.json is metadata and is placed under CC0 (section 16).

10. Collections: members.json

10.1 Archive collections and selections

Collections are of two kinds, which differ in how they treat the versions of their members.

Both kinds may contain collections as members (an archive of archives, a selection of issues). members.json states the kind.

10.2 The member list

A collection version MUST contain members.json with:

It MAY contain order, the rule by which tools maintaining the collection place members: manual (the default: tools append new members and never reorder), issued-desc or issued-asc (by the members' Issued date, then their Available date, members with neither last, ties broken by object identifier, so that the result is reproducible).

Each member MUST have:

Each member MAY have mirrors (base URLs of archives holding a mirror of the object, section 10.4), doi (the version DOI), conceptDoi and cite, a cached citation (title, creators as a list of names, year, and issued, the member's Issued date) so that the collection stays readable, and can be ordered, without resolving its members, also if they become unavailable. cite is not authoritative.

Members of an archive collection MUST have version, the pinned object version, and inventorySha512, the SHA-512 digest of that version's inventory file. Since the inventory of an object version lists every earlier version, the pin fixes the object with all its versions up to it. A member MAY have follow, "latest": a curation setting, not a floating reference. A followed member pins the head of the object when the collection version was made; a member without follow keeps the version its curator pinned, which MAY be earlier than the head, until the curator changes it. A tool maintaining the collection reads the member archive's discovery document (or its feed); when the followed object has a new head, the tool writes a new collection version pinning it, whatever the new head holds (a new document version, a description, a notice, a withdrawal): an archive collection does not judge the versions of its members. A withdrawn member stays, and presentations show the withdrawal. Presentations show the current version of each member, read from the history of the pinned version (section 7.3).

Members of a selection MUST have revisions: a non-empty list of the revisions vetted, in the order of the document's history, each with documentVersion, version (the object version vetted, which holds that document version: when several do, the last of them when the revision was vetted, which is its entry in the history, section 7.3) and inventorySha512 (the digest of its inventory file). They MUST NOT have version, inventorySha512 or follow themselves. The revision presented as the selection's is the last of the list. A revision pins the object version that was vetted: descriptions and notices added later by the document's archive are not vetted by the selection, and presentations that show them SHOULD say where they come from; a revision keeps its pin in later versions of the selection. If the document is withdrawn in its archive, the revisions stay vetted, and presentations show the withdrawal as section 11.1 asks, saying that it comes from the member's archive. Tools MUST NOT change revision sets on their own: adding a revision (for instance a corrected version, accepted after review), removing one, or adding or removing a member is a new version of the selection, made by its curator, recorded in the inventory (who and when) with a message saying what was decided. A revision set MAY hold several revisions of the same document, for instance a version accepted and its later correction.

Every member is pinned: a collection version states exactly which object versions it contains, whole objects up to a version in an archive collection, revisions in a selection. A collection version therefore fixes everything it contains, also across archives; since a pin fixes an inventory, which fixes all its files, collections are hash trees. Pins cannot form cycles.

10.3 Members of other archives

A member may belong to another archive. Nothing is copied: the member is resolved as in section 6.4. A reference (a pin without a copy) needs no permission. Copies are of two kinds: mirrors (section 10.4) and accepted copies (section 10.5).

10.4 Mirrors

An archive MAY mirror an object of another archive: copy the whole object, every version with its inventories and files, byte for byte, into its own storage root, under the same identifier (only if no object of its own has it). A mirror is the same object, not a new one: its object.json files keep naming the original archive, and the discovery document lists it with mirrorOf, the identifier of the original archive (section 6.1). A mirror is brought up to date only by copying the new versions of the original, which is possible because OCFL objects only grow; it MUST NOT be changed otherwise. Mirroring is allowed only if the licences of all the versions copied allow redistribution. An archive collection MAY list a mirror of a member in the member's mirrors. An archive that mirrors another archive entirely SHOULD be listed in the mirrors of that archive's discovery document, with the agreement of its owner.

Mirrors serve preservation and access (an institution keeping copies of its members' archives, an independent storage site): they are impartial, like archive collections, and carry every version.

10.5 Accepted copies

A selection MAY keep its own copy of a revision it vetted, as a document of the selection's archive, called an accepted copy, so that what it vetted stays available whatever happens to the original. Its first document version holds exactly the files of the vetted revision (every file except datacite.json and object.json), byte for byte; its object.json records the source in external, with role source, service OpenSheaf, record the URL of the source object version, label the source object identifier and object version (for instance "paper v2"), and files with one entry, inventory.json, whose sha512 is the pin of the source version; its datacite.json describes it with the selection's archive as publisher, keeps the relations of the source, and links the source version with IsIdenticalTo (a URL). Copying requires the right to redistribute only the revision copied.

Later document versions of an accepted copy are acts of the selection's curator (a corrected version accepted, a notice, a withdrawal); the authors' later versions change nothing in it. The selection lists the accepted copy as its member, a member of its own archive; it MAY list the original revision set as well. An accepted copy is not a mirror: it is another object, with its own inventories, and cannot stand for the original in the resolution of a pin (section 6.4), so it is never listed in mirrors.

A version that the selection makes itself, such as a journal's typeset version of record, is a document of the selection's archive like any other, with the selection as publisher, the authors' agreement in object.json (section 9), and relations to the authors' versions (sections 7.3 and 8.1).

10.6 Rights

The member list of a collection is placed under CC0. The licence of a collection never extends to its members. Mirrors and accepted copies keep the licences of what they copy.

11. Withdrawal and takedown

11.1 Withdrawal

A document or collection is withdrawn (for instance retracted by its authors) by a description-only version whose object.json has status withdrawn and a withdrawal object with a date and a reason (a note, section 9), and whose datacite.json has the same date as Withdrawn. The status belongs to the object, whatever document version its head holds. Its content is kept, its history remains verifiable, and the discovery document lists it with status withdrawn. Presentations MUST show the withdrawal notice with the document.

11.2 Takedown

When content must be removed (by law, or for a breach of rights), the object is deleted from the storage root and a tombstone MUST be added to the discovery document.

11.3 Tombstones

A tombstone records id, kind, lastVersion, inventorySha512 of that version, date and reason (plain text, since the discovery document has no content files). Identifiers of tombstoned objects MUST NOT be reused. Verifiers report a pin to a tombstoned object as "removed", not as a corruption. External copies (DOI records, snapshots) follow the rules of their services.

Note: OCFL 1.1 has no way to remove files from an object short of deleting and rebuilding it. Physical deletion of files, and the flagging of lost or corrupted files, are accepted as in scope for OCFL version 2, with a tombstone or status recorded in the inventory. When that mechanism is published, a later version of this specification will adopt it for takedowns of single files.

12. Versioning of this specification

This specification is versioned MAJOR.MINOR.PATCH, a form of semantic versioning adapted to a format:

Before version 1.0, any change of the minor version (0.1, 0.2, …) may be incompatible, as semantic versioning allows for initial development.

Every JSON file defined here declares its format version, and the discovery document and every object.json declare the version of this specification, both as MAJOR.MINOR only (for instance "opensheaf-object/0.1" and "0.1"): a patch version never changes what is valid, so files do not record it.

A reader that finds a major version it does not know (or, before 1.0, a minor version it does not know) SHOULD report it and MUST NOT silently treat the files as valid. A reader that finds a later minor version of a major version it knows (from 1.0) reads the files as that major version, ignoring properties it does not know, and SHOULD report the version. For this to work, readers MUST ignore unknown properties in files of a major version they know, and the schemas of this specification do not forbid additional properties.

While a version is a draft, successive drafts are identified by the date in the heading and by the changelog (section 17). The text of each version is published at https://opensheaf.org/opensheaf-specification-<MAJOR.MINOR>.md and is not changed after the version is final, except by patch versions, which are listed in its changelog.

13. Integrity and authenticity

13.1 Integrity

Integrity rests on OCFL digests: every file is fixed by its SHA-512 digest in the inventory, every inventory by its checksum file, and every collection version pins its members by inventory digest. Inventories MAY also record MD5 and SHA-256 digests in their fixity block; archives following the Zenodo binding MUST record MD5 (appendix A).

13.2 Authenticity and dates

Digests show that files were not changed; they do not show who made them or when. An archive MAY provide, for each object version:

These witness files SHOULD be kept in the object's extension folder extensions/opensheaf-witnesses/, so that they travel with the object when it is copied or mirrored. OCFL allows object extension folders, which are not part of any version; the extension name opensheaf-witnesses is not yet registered with OCFL, so validators may warn about it. An archive that does not modify object folders after a version is committed MAY instead keep them under witnesses/<object id>/, next to the discovery document. Witnesses can be added later, by the owner or by others, and replaced when a proof is upgraded (an OpenTimestamps proof is completed once its attestation is confirmed); they are not covered by the inventory digests, and need not be, since each one is checked directly against the checksum file it names, which the pins fix.

External deposits (appendix A) and software archive snapshots are further witnesses. Archives kept in git MAY also sign their commits or tags, but git hashes are not part of the integrity chain of this specification.

14. Verification

A verifier checking an archive MUST:

A verifier SHOULD check the witnesses it finds, and the requirements of the profiles the archive declares. It MUST NOT treat the presentation as authoritative. It SHOULD limit the depth and size of the collections it follows, and report when it stops.

15. Security considerations

16. Privacy and rights

17. Changelog

Appendix A. Zenodo binding (normative for archives declaring the profile zenodo)

Zenodo issues DataCite DOIs (prefix 10.5281) and keeps files permanently. Under this binding:

Appendix B. TeXmacs profile (normative for archives declaring the profile texmacs)

Appendix C. Website profile (normative for archives declaring the profile website)

Appendix D. JSON Schemas (normative)

The schemas (JSON Schema draft 2020-12) are published with this specification and dedicated to the public domain under CC0 1.0, so that they can be embedded in any software:

DataCite publishes its schema as an XML Schema only. datacite.json is validated by converting it to DataCite XML (following DataCite's mapping between the REST API's JSON and XML) and validating the result against the DataCite 4.7 XML Schema, together with the requirements of section 8.

Appendix E. Examples (non-normative)

The values below come from the first archive. Digests are shortened, and the DOIs and ORCID iDs are placeholders.

A discovery document: 

{
  "format": "opensheaf-archive/0.1",
  "specification": "0.1",
  "archiveId": "tag:opensheaf.org,2026:mgubi",
  "name": "Papers of Massimiliano Gubinelli",
  "contact": "https://orcid.org/0000-0000-0000-0000",
  "storageRoot": "ocfl/",
  "storageLayout": "0002-flat-direct-storage-layout",
  "mainCollection": "collection-papers",
  "profiles": ["zenodo", "texmacs", "website"],
  "objects": [
    { "id": "fractional-phi42-mass-gap", "kind": "document", "head": "v1",
      "inventorySha512": "9a0c…", "status": "active" },
    { "id": "collection-papers", "kind": "collection", "head": "v1",
      "inventorySha512": "51be…", "status": "active" }
  ]
}

An object.json of a document version: 

{
  "format": "opensheaf-object/0.1",
  "specification": "0.1",
  "kind": "document",
  "archiveId": "tag:opensheaf.org,2026:mgubi",
  "objectId": "fractional-phi42-mass-gap",
  "documentVersion": 1,
  "mainSource": "fractional-phi42-mass-gap.tm",
  "sourceFormat": "application/x-texmacs",
  "renditions": [ { "path": "paper.pdf", "mediaType": "application/pdf" } ],
  "toolchain": [ { "name": "TeXmacs", "version": "2.1.5" } ],
  "stage": { "scheme": "NISO-JAV", "value": "AO" },
  "agreement": { "by": ["P. Duch", "M. Gubinelli"], "date": "2026-11-12", "method": "by e-mail" },
  "external": [ { "role": "deposit", "service": "Zenodo", "record": "https://zenodo.org/records/1234567",
                  "doi": "10.5281/zenodo.1234567" } ],
  "status": "active"
}

The datacite.json of the same version: 

{
  "doi": "10.5281/zenodo.1234567",
  "url": "https://mgubi.org/papers/site/fractional-phi42-mass-gap/fractional-phi42-mass-gap.html",
  "version": "1",
  "types": { "resourceTypeGeneral": "Preprint" },
  "titles": [ { "title": "Mass gap for the fractional Phi^4_2 model" } ],
  "creators": [
    { "name": "Duch, P.", "nameType": "Personal", "givenName": "P.", "familyName": "Duch",
      "affiliation": [ { "name": "Institute of Mathematics, Polish Academy of Sciences" } ] },
    { "name": "Gubinelli, M.", "nameType": "Personal", "givenName": "M.", "familyName": "Gubinelli",
      "affiliation": [ { "name": "Mathematical Institute, University of Oxford" } ] } ],
  "publisher": { "name": "Zenodo" },
  "publicationYear": 2026,
  "dates": [ { "date": "2026-11-12", "dateType": "Issued" },
             { "date": "2026-11-12", "dateType": "Available" } ],
  "rightsList": [ { "rights": "Creative Commons Attribution 4.0 International",
                    "rightsUri": "https://creativecommons.org/licenses/by/4.0/",
                    "rightsIdentifier": "cc-by-4.0", "rightsIdentifierScheme": "SPDX" } ],
  "descriptions": [ { "description": "We present a new, simple …", "descriptionType": "Abstract" } ],
  "formats": [ "application/x-texmacs", "application/pdf" ],
  "relatedIdentifiers": [
    { "relatedIdentifier": "10.5281/zenodo.1234566", "relatedIdentifierType": "DOI", "relationType": "IsVersionOf" } ]
}

The object.json of a later version of a document whose arXiv version 2 was found and deposited after version 4 (document versions 1, 2, 3 for arXiv's v1, v3, v4, then 4 for arXiv's v2, placed between 1 and 2 in the history), with a notice about version 2 (arXiv's v3): 

{
  "format": "opensheaf-object/0.1",
  …
  "documentVersion": 3,
  "changes": { "text": "Corrected the proof of Lemma 2; 32 pages." },
  "stage": { "scheme": "NISO-JAV", "value": "AM" },
  "history": [ "v1", "v4", "v2", "v5" ],
  "notices": [ { "documentVersion": 2, "date": "2026-12-01",
                 "text": "Theorem 3 is wrong as stated; corrected in version 3.",
                 "path": "notices/erratum-v2.pdf", "mediaType": "application/pdf" } ],
  "external": [ { "role": "source", "service": "arXiv", "record": "https://arxiv.org/abs/2303.18112v4",
                  "doi": "10.48550/arXiv.2303.18112", "label": "v4" } ],
  "status": "active"
}

Object versions v1 to v3 deposited document versions 1 to 3; v4 deposited document version 4 (arXiv's v2) and wrote the history ["v1", "v4", "v2", "v3"], so that the current version stayed document version 3 although the head held version 4; v5, shown here, is a description-only version adding the notice, which holds the current version again. The current version is document version 3, the last in the history.

A members.json of an archive collection: the main collection of an archive, following its documents whole: 

{
  "format": "opensheaf-collection/0.1",
  "type": "archive",
  "order": "issued-desc",
  "members": [
    { "kind": "document",
      "archive": "tag:opensheaf.org,2026:mgubi",
      "archiveUrl": "https://mgubi.org/papers/",
      "id": "fractional-phi42-mass-gap",
      "version": "v3",
      "inventorySha512": "9a0c…",
      "follow": "latest",
      "cite": { "title": "Mass gap for the fractional $\\Phi^4_2$ model",
                "creators": ["P. Duch", "M. Gubinelli"], "year": 2026, "issued": "2026-11-12" } }
  ]
}

A members.json of a selection: an issue of a journal, with a paper vetted in its version 2 and, after a correction accepted by the editors, its version 3; an accepted copy kept by the journal; and a member that is itself a collection, vetted in one version: 

{
  "format": "opensheaf-collection/0.1",
  "type": "selection",
  "members": [
    { "kind": "document",
      "archive": "tag:example.org,2026:authors",
      "archiveUrl": "https://authors.example.org/",
      "id": "network-discrimination",
      "revisions": [
        { "documentVersion": 2, "version": "v2", "inventorySha512": "4f1e…" },
        { "documentVersion": 3, "version": "v4", "inventorySha512": "c07a…" } ],
      "cite": { "title": "Quantum network discrimination", "creators": ["C. Hirche"], "year": 2021 } },
    { "kind": "collection",
      "archive": "tag:example.org,2026:seminar",
      "archiveUrl": "https://seminar.example.org/",
      "id": "collection-seminar-2026",
      "revisions": [ { "documentVersion": 3, "version": "v3", "inventorySha512": "7d21…" } ] }
  ]
}

The object.json of the journal's accepted copy of the first member's version 2: 

{
  "format": "opensheaf-object/0.1",
  "specification": "0.1",
  "kind": "document",
  "archiveId": "tag:example.org,2026:journal",
  "objectId": "network-discrimination",
  "documentVersion": 1,
  "mainSource": "paper.tex",
  "sourceFormat": "application/x-tex",
  "renditions": [ { "path": "paper.pdf", "mediaType": "application/pdf" } ],
  "stage": { "scheme": "NISO-JAV", "value": "VoR" },
  "external": [ { "role": "source", "service": "OpenSheaf",
                  "record": "https://authors.example.org/ocfl/network-discrimination/v2/",
                  "label": "network-discrimination v2",
                  "files": [ { "name": "inventory.json", "sha512": "4f1e…" } ] } ],
  "status": "active"
}

Appendix F. Rationale (non-normative)

Appendix G. References