2. Works, versions, witnesses and documents

2.1 Four objects#

A document's key is its work's key, with a suffix for anything other than the version of record: cornell1995second-saqk, cornell1995second-saqk.si, dong2026machine-1ard.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#

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:

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).

2.4 Work and document keys#

A work key names a work the way a reader would, and never collides: a Scholar-style citation key, a hyphen, and the first characters of a hash of the work's identity.

vaswani2017attention-a241
└─── Scholar part ──┘ └hash┘

The Scholar part is built as Google Scholar builds its BibTeX keys, from the CSL-JSON meta of the version:

1. the first author's family name: family, or the part of a literal name before a comma, else its last word that is not a suffix such as Jr. or III; folded to ASCII with NFKD, lower-cased, letters only, so Müller gives muller and O'Brien gives obrien; no author, or a name with no Latin letters, gives anon;
2. the year of issued, when it has four digits, else nothing;
3. the first word of title that is not a stop word, folded the same way, letters and digits only, with apostrophes removed and other punctuation splitting words; no such word gives nothing.

The stop words are a an the of on in for to and or at by with from as into onto about toward towards via is are be its it this that these those.

The identity is the work's first identifier among doi, arxiv, isbn, pmid, pmcid and openalex in same_as, in that order, written <kind>:<value> with a DOI's ASCII letters lower-cased. A work with none has the identity meta:<title words>|<year>|<family> from the same folded parts. url: and lode: identifiers name copies and claims, not the work, and never enter the identity.

The hash part is the leading bits of SHA-256 of scienting-key/1: followed by the identity, in UTF-8, written in lowercase Crockford base32, five bits a character: four characters, or, when another work in the store already holds that key, six, eight and so on until the key is free. A key is minted once, when the work enters a store, and never recomputed: a corrected title or a year revised later leaves it alone, while the hash of an identifier still shows which work the key names. A work key matches ^[a-z][a-z0-9]*-[0-9a-hjkmnp-tv-z]{4,51}$.

The document key is the work key for the version of record, and the work key with a suffix for any other version: .si for Supporting Information, .v<seq> for a preprint, submitted, accepted or draft version with a sequence number, else a dot and the version type: cornell1995second-saqk, cornell1995second-saqk.si, dong2026machine-1ard.v2. A validator checks that the document key is the work key with the version's suffix (doc.key.work), and that a key whose identity is an identifier carries that identifier's hash (doc.key.suffix); a metadata identity may have been corrected since the key was minted, so it is not held to the key. Store, project and source keys keep the form ^[a-z0-9][a-z0-9._-]*$, as do legacy document keys kept in aliases. keys.jsonl pins the Scholar parts, identities, hashes and document keys, with accented names, name suffixes, missing years and authors, and the lengthening that settles a collision.

Source: spec/02-model.md · raw