[OpenSheaf] [specification] [use cases] [FAQ] [first archive]OpenSheaf
Source: the specification and this site are kept in the GitHub repository opensheaf/opensheaf.github.io, which is also the place to discuss them (see below).
Scholarly documents now live in a few central places: preprint servers such as arXiv, publishers' platforms, institutional repositories. They work, but authors depend on them for something that could be much simpler, and what they keep is often only a PDF.
OpenSheaf proposes a lean common format instead:
Archives kept by their authors. Anyone (a person, a group, an institution) can keep an archive of their documents as plain files on a static website. No server software, no central service, no permission needed.
Sources, not only PDFs. Each deposit keeps the sources of a document together with its PDF, so that the work can be read, checked and reused in the form in which it was written.
Fixed, verifiable versions. Every version of every document is fixed by content hashes and never changes once deposited. Corrections are new versions, and anyone can check the whole history from the files alone.
Standards, not inventions. Storage follows the Oxford Common File Layout (OCFL), used by research libraries for long-term preservation; description follows the DataCite metadata of DOIs. OpenSheaf only adds what these leave open.
Collections that compose. Archives keep documents whole, every version, impartially; selections (a journal, a digest, a review journal, a reading list) vet particular versions, and change only by an act of their curator. Both are versioned objects pinning their members by digest, also across archives, and compose without copying, as local pieces glue into a sheaf. The use cases show how authors, archives and selections use them.
Compatible with existing infrastructure. Documents can also be on arXiv, get DOIs and be archived on Zenodo, and be found by Google Scholar; none of these is required.
A sheaf is a bundle of papers, or of stalks of wheat tied together. In mathematics, a sheaf is the structure that attaches data to each part of a space so that local pieces, which agree where they overlap, glue into a whole. OpenSheaf works the same way: archives are kept and verified separately, each by its owner, and collections glue them together without copying, while every piece stays checkable on its own.
This repository is the place to discuss OpenSheaf and to propose changes:
Questions and problems: open an issue, for instance when something in the specification is unclear, contradictory or hard to implement.
Ideas and open-ended discussion: use the Discussions.
Amendments: propose changes to the text as pull requests on opensheaf-specification-0.1.md, with an explanation of the motivation; larger changes are best discussed in an issue first.
Implementations: if you build an archive, a tool or a verifier for OpenSheaf, open an issue so that it can be added to the list below.
Archives
Papers of Massimiliano Gubinelli (repository mgubi/papers): the first OpenSheaf archive, following version 0.1, with TeXmacs sources, HTML versions and PDFs (profile texmacs).
Tools: opensheaf-py (Python, the osheaf command, written as a literate program that explains it along the specification): deposits documents as OCFL objects with DataCite and OpenSheaf metadata (any source with its PDF, or TeXmacs sources typeset by the archive), keeps document versions, history and collections, writes the discovery document and a website with landing pages, deposits on Zenodo, imports from arXiv, and verifies an archive (also with the JSON Schemas and the ocfl-py validator).
Templates: archive-template, a ready repository for your own archive of papers, and collection-template, for a curated collection of papers from any archive; both are published with GitHub Pages ("Use this template", then osheaf init), and both are testing grounds that run every workflow of the tools on every push.
Test data: example-papers, papers to deposit (invented ones, TeXmacs papers and slides, real openly licensed preprints from arXiv and slides from Zenodo) with their metadata.
opensheaf-specification-0.1.md: the specification, in Markdown, its only source.
FAQ.md: answers to common questions about the design.
README.md: this text, also the home page of the site.
schemas/: the JSON Schemas of the files defined by the specification, also published at https://opensheaf.org/schemas/: opensheaf-archive-0.1.schema.json for opensheaf.json, opensheaf-object-0.1.schema.json for object.json and opensheaf-collection-0.1.schema.json for members.json.
index.tm/index.html, opensheaf-specification-0.1.tm/.html, faq.tm/faq.html: the pages of the site, generated from the Markdown files (for TeXmacs and for the web); do not edit them.
notes-meta.ts: the TeXmacs style package of the page; resources/: its stylesheets, scripts and fonts.
resources/brand/: the logo (dot mark and lettering), the symbol, the wordmark and the favicon, as self-contained SVG files (with PNG and PDF copies of the logo); see its README. The lettering is outlined from Geist Serif (SIL Open Font License).
tools/build.py: converts the Markdown files to TeXmacs (tools/md2tm.py) and exports them to HTML with TeXmacs. It needs the notes and max-html TeXmacs plugins, linked in ~/.TeXmacs/plugins.
.agents/skills/opensheaf-style/: the conventions of the site's style and build, for people and agents.
CNAME: the GitHub Pages custom domain, opensheaf.org.
The text of the specification and of the FAQ is licensed under the Creative Commons Attribution-ShareAlike 4.0 International licence (CC BY-SA 4.0): it may be copied and adapted with attribution, and adapted versions must be shared under the same licence. The JSON Schemas in schemas/ are dedicated to the public domain under CC0 1.0, so that they can be embedded in any software. The tools and style files are licensed under the GNU General Public License, version 3 or later. The fonts in resources/fonts/ keep their own licence (SIL Open Font License).
Editor: Massimiliano Gubinelli (Mathematical Institute, University of Oxford).