paperspec/spec/02-model.md

2. Works, versions, witnesses and documents

2.1 Four objects

Object	Is	Identified by
Work	The intellectual work, across all its versions.	A key, and same_as identifiers: doi:, arxiv:, isbn:, pmid:, pmcid:, url: or lode:.
Version	One expression of the work: a preprint, an accepted manuscript, the version of record, an erratum, Supporting Information, a draft.	The work's key and a version type, with an optional sequence number and date.
Witness	One file of a version: a PDF, JATS XML, a LaTeX source archive, an HTML page, an EPUB, a Typst project.	The SHA-256 of its bytes.
Document	The text established for one version from one or more witnesses.	A key, and a root hash per revision.

A document's key is its work's key, with a suffix for anything other than the version of record: cornell1995second, cornell1995second.si, dong2026machine.v2. Supporting Information is its own document, with its own pages, numbering and references, related to its article by supplement-of. A textbook is a work whose chapters are documents related by part-of. A draft is a document of kind draft.

Keys are immutable once a document is shared. A renamed document keeps its old keys in aliases.

2.2 document.json

Property	Required	Holds
format	Yes	scienting-doc/1.
key	Yes	The document key.
store	No	The store that holds it, when the package says so.
aliases	No	Earlier keys.
kind	Yes	article, supplement, chapter, book, thesis, report, draft, course-material or other.
work	Yes	{key, same_as}.
version	Yes	{type, seq?, date?}, where type is preprint, submitted, accepted, version-of-record, erratum, retraction, supplement, draft or other.
relations	Yes	A list of {type, target}; type is supplement-of, part-of, version-of, erratum-of, retraction-of or translation-of, and target a key, optionally store-qualified.
meta	Yes	The version's bibliographic record, as one CSL-JSON item.
language	Yes	A BCP 47 tag.
license	No	The document's license as stated: {spdx?, text?, url?}. Rights are per witness (14).
policy	Yes	The text policy: full, or checks-only (12.5).
hashing	Yes	How content values are computed: {scheme: "plain"}, a team HMAC or a page-derived key (5.8).
root	Yes	The root node's node_hash.
meta_hash	Yes	The metadata hash (5.9).
rev	Yes	The revision: the index of the last correction applied, or 0.
counts	Yes	{nodes, leaves}.
fidelity	Yes	{lowest, counts}: the lowest level among leaves, or null when there are none, and the number of leaves at each level, computed as 8.2 defines.

The schema is document.schema.json.

2.3 witnesses.json

witnesses.json is an object with one property, witnesses, a non-empty list in which each witness is:

Property	Required	Holds
id	Yes	The witness ID: seven letter-first base32 characters encoding the SHA-256, as 4.6 defines.
sha256	Yes	The SHA-256 of the file.
size	Yes	Its size in bytes.
kind	Yes	pdf, jats, latex, html, epub, typst, xml, image or other.
media_type	Yes	Its media type.
pages	No	The number of pages, for a witness that has pages.
text_layer	No	Whether a PDF has a text layer; a scan has none.
version_label	No	The version as the witness labels it.
origin	Yes	{source, url?, doi?, retrieved_at?, note?}, where source is publisher, repository, preprint-server, author, team, licensed-delivery, library or other.
rights	Yes	The rights record, scienting-rights/1 (14).

The witness's bytes are not part of the package; they live in the team's asset store, by SHA-256. The SHA-256 is the exact identity of one file. Because publishers stamp each download, two copies of one paper rarely share it; page fingerprints identify their pages instead (7).