65 lines
4.3 KiB
Markdown
65 lines
4.3 KiB
Markdown
# 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](14-rights.md)). |
|
|
| `policy` | Yes | The text policy: `full`, or `checks-only` ([12.5](12-package.md#125-text-policies)). |
|
|
| `hashing` | Yes | How content values are computed: `{scheme: "plain"}`, a team HMAC or a page-derived key ([5.8](05-hashes.md#58-keyed-hashes)). |
|
|
| `root` | Yes | The root node's `node_hash`. |
|
|
| `meta_hash` | Yes | The metadata hash ([5.9](05-hashes.md#59-the-metadata-hash)). |
|
|
| `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](08-fidelity.md#82-levels) 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](04-identity.md#46-record-ids) 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](14-rights.md)). |
|
|
|
|
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](07-geometry.md)).
|