paperspec/docs/glossary.md

# Glossary

A scientific paper changes after it is published: errata appear, readings get corrected, annotations pile up. paperspec is a set of file formats for scientific papers that keeps each sentence findable through those changes (repository: <https://git.scient.ing/infra/paperspec>).
This glossary defines its terms for readers from newcomer to expert, implementers included.
Each entry gives the plain meaning, then the precise one, then the chapter that defines it.

A hash is a fixed-length fingerprint of data; changing one character changes it.
SHA-256 is the hash function the formats use.
The specification is at version 0.1.0, and each format is `candidate` or `provisional` in `registry/formats.json`.
Format names begin with `scienting-`, as in `scienting-doc/1`; that prefix is the formats' namespace, a separate matter from the repository's name. "Outside term" marks a standard from another project.

Address
:   A string that names one node, optionally pinned to its state by the first six digits of its `node_hash` and narrowed to a span of code points (numbered characters of text): `key#id@hash6[start:end]`. ([6.1](../spec/06-anchors.md#61-addresses))

Alias
:   A legacy ID kept so that old references still lead to the node that now holds their text. ([4.3](../spec/04-identity.md#43-permanence-retirement-and-aliases))

Align key
:   A hash of a node's lossy projection, used only to propose that two readings hold the same sentence; it never certifies anything. ([5.1](../spec/05-hashes.md#51-the-five-values))

Anchor
:   The stored form of a pinned address, with its quotation and context, so that a reference can be found again after the text changes.
It resolves as current, changed below, moved, reattached or stale. ([6.2](../spec/06-anchors.md#62-the-anchor), [6.5](../spec/06-anchors.md#65-resolution))

Asset store
:   Where a team keeps files by SHA-256: witnesses, images, crops and withheld text. ([12.6](../spec/12-package.md#126-assets))

Bundle
:   One SQLite file with every table and a full-text index, which a reader or a store queries.
Format `scienting-bundle/1`, `provisional`. ([13.5](../spec/13-database.md#135-the-bundle))

Changed below
:   The resolution of an anchor on a container that is unchanged in itself while something inside it changed. ([6.5](../spec/06-anchors.md#65-resolution))

Checklist
:   A record of checking an export, such as accessible HTML, against a named standard, criterion by criterion; it is covered by the receipt of the person who checked.
Format `scienting-checklist/1`, `provisional`. ([8.11](../spec/08-fidelity.md#811-checklists))

Correction
:   An operation on an established document, with its evidence and author; never edited, only appended. ([11](../spec/11-corrections.md))

Description
:   An annotation that describes a figure, panel or table for readers who cannot see it, as a short text equivalent (`alt`) or a full description (`long`); an accessible export uses confirmed descriptions only. ([18.4](../spec/18-layers.md#184-bodies))

Document
:   The text established for one version of one work, from one or more witnesses, as a tree of nodes. ([2.1](../spec/02-model.md#21-four-objects), [3](../spec/03-nodes.md))

Drift
:   The amount that has changed below a container since an anchor on it was made, counted from the corrections: the share of the container's leaves touched by later corrections.
It is reported as `none`, `low` or `high`, with a default threshold of a quarter. ([6.6](../spec/06-anchors.md#66-drift))

Exercise
:   An annotation whose body holds a prompt, an answer key and a grading rule.
The key is anchors, a verdict, a chain, a value or planted errors, by exercise kind. ([19.1](../spec/19-exercises.md#191-exercises))

Fidelity level
:   How far a leaf's text was checked against its source, from F0 converted to F3 proofread. ([8.1](../spec/08-fidelity.md#81-levels-of-fidelity))

JATS
:   Outside term.
Journal Article Tag Suite, ANSI/NISO Z39.96-2024, an XML format in which publishers and archives exchange journal content ([the NISO page](https://www.niso.org/publications/z3996-2024-jats)).
In paperspec, `jats` is a witness kind: the fixture `okafor2025open` was established from a JATS file and a PDF that agree.
The formats ingest JATS and do not replace it. ([2.3](../spec/02-model.md#23-witnessesjson))

Keyed hash
:   A content value computed as an HMAC (a hash mixed with a secret key) under a team key or a key derived from page fingerprints, so a short text cannot be recovered by hashing guesses. ([5.8](../spec/05-hashes.md#58-keyed-hashes))

Layer
:   A named set of annotations with one purpose, audience, visibility and license. ([18.2](../spec/18-layers.md#182-the-layer))

Leaf
:   A node that holds text itself: a sentence, cell, reference, author line, keyword line, equation, equation line, code or algorithm.
A leaf anchor points at one whole. ([6.4](../spec/06-anchors.md#64-four-kinds-of-anchor))

Lossy projection
:   A node's text with scripts flattened, citation marks, whitespace and dashes removed, and case folded; used for proposing alignments. ([5.5](../spec/05-hashes.md#55-the-lossy-projection))

Match hash
:   A hash of a node's strict projection.
Two readings agree only when their match hashes are equal and their complex-notation keys are equal.
A complex-notation key is `notation:source` for a piece of math too complex for the formats to normalize, with the source's whitespace removed ([5.3](../spec/05-hashes.md#53-the-strict-projection)). ([5.1](../spec/05-hashes.md#51-the-five-values), [5.3](../spec/05-hashes.md#53-the-strict-projection))

Node
:   An addressable part of a document: a section, paragraph, sentence, figure, panel, caption, table, row, cell, equation, footnote, reference and the rest.
Each node has a permanent ID and five content values; table columns and figure-text items have IDs and are not nodes. ([3](../spec/03-nodes.md), [4.2](../spec/04-identity.md#42-minting-node-ids))

Own hash
:   A hash of a node's own content without its children, used to judge anchors on containers that have content of their own.
The `node_hash` is a hash of the own hash and the children's node hashes. ([5.1](../spec/05-hashes.md#51-the-five-values), [5.2](../spec/05-hashes.md#52-own-content))

Package
:   A document as a folder, or a zip of one, of canonical JSON (a plain-text data format) and JSON Lines (one JSON value per line) files, with a manifest whose hash pins them all. ([12](../spec/12-package.md))

Page fingerprint
:   A hash of a page's size, its text with download stamps removed, and its images, so that differently stamped downloads share their pages. ([7.1](../spec/07-geometry.md#71-page-fingerprints))

Plain projection
:   A node's text as one string, on which offsets, quotations and text hashes are defined. ([3.6](../spec/03-nodes.md#36-the-plain-projection))

Policy
:   A project owner's signed decision that settles rights a record leaves unknown.
It never overrides a use the record sets to true or false. ([14.2](../spec/14-rights.md#142-effective-uses))

Project
:   A team's curated set of documents, with its members, layers, data, reading paths and drafts.
Format `scienting-project/1`, `provisional`. ([20](../spec/20-projects.md))

Receipt
:   One signature over a Merkle root of what a person reviewed in a sitting.
The signature sets the fidelity level of what it lists.
A Merkle root is a single hash that commits to a list of items; receipts build it as RFC 6962 (an internet standards document) describes, a tree that [RFC 9162](https://www.rfc-editor.org/rfc/rfc9162) obsoletes and defines identically. ([8.3](../spec/08-fidelity.md#83-receipts), [8.5](../spec/08-fidelity.md#85-merkle-roots))

Revision
:   The index of the last correction applied to a document, or 0 when there is none; anchors and receipts record it. ([11](../spec/11-corrections.md))

Revocation
:   A signed record that withdraws a receipt, or every receipt by one signer in a period. ([8.7](../spec/08-fidelity.md#87-revocations-and-the-roster))

Rights record
:   A witness's license, the basis on which the team holds it, and the uses that basis allows. ([14.1](../spec/14-rights.md#141-the-rights-record))

Roster
:   The list of keys that may sign, with the person who holds each, that person's role in the team, and what the key may sign. ([8.7](../spec/08-fidelity.md#87-revocations-and-the-roster))

Selector
:   Outside term.
In the W3C Web Annotation Data Model, the part of an annotation's target that says where in the source resource the annotation applies.
The model defines `TextQuoteSelector` (exact text, with optional prefix and suffix) and `TextPositionSelector` (offsets, which the model calls very brittle), among others ([the W3C model](https://www.w3.org/TR/annotation-model/)).
Layers use a custom `AnchorSelector`, which carries an anchor, followed by a `TextQuoteSelector` for tools that do not know it; they use neither `TextPositionSelector` nor `FragmentSelector`. ([18.3](../spec/18-layers.md#183-the-annotation))

Spot-check
:   A second reviewer's check of a sample of a receipt's nodes, drawn from a seed nobody can steer: the checker's deterministic signature over the receipt's record hash. ([8.8](../spec/08-fidelity.md#88-spot-checks))

Stamp rule
:   A pattern that recognizes a publisher's download stamp in a page's text, so that fingerprints ignore it. ([7.2](../spec/07-geometry.md#72-stamp-rules))

Strict projection
:   A node's text with notation folded to one canonical form and structure kept; used for certifying agreement. ([5.3](../spec/05-hashes.md#53-the-strict-projection))

Suspect
:   A doubtful reading raised for a person or a review session to answer. ([5.7](../spec/05-hashes.md#57-suspects))

Targeted F3
:   Proofreading the nodes a team's claims, quotations and datasets rest on, rather than every node.
The target set also includes the leaves of every anchored container, every equation and, under the project's digit rule (`all`, `anchored-sections` or `none`), sentences and cells with a digit in a text or math run (an inline stretch of plain text, or of TeX or Typst math, within the node; [3.5](../spec/03-nodes.md#35-inline-runs)). ([8.10](../spec/08-fidelity.md#810-targeted-f3))

Text leaf
:   A leaf whose text a container's projections are made of: any leaf except an equation line, or an equation inside a sentence, whose text is already part of its equation or its sentence. ([3.6](../spec/03-nodes.md#36-the-plain-projection))

Text policy
:   Whether a package carries its text (`full`) or withholds it (`checks-only`). ([12.5](../spec/12-package.md#125-text-policies))

Verdict
:   A judgment of whether a cited passage supports a citing sentence: supports, partly, does not, or cannot tell. ([19.2](../spec/19-exercises.md#192-verdicts))

Version
:   One expression of a work: a preprint, the version of record, an erratum, the Supporting Information. ([2.1](../spec/02-model.md#21-four-objects))

Web Annotation
:   Outside term.
The W3C Recommendation of 23 February 2017 for annotations with a body, a target and a motivation ([the W3C model](https://www.w3.org/TR/annotation-model/)).
It gives sentences no permanent IDs and reports no outcomes such as current or stale; for annotation in general, it and its clients are the better choice.
Layers are Web Annotations. ([18](../spec/18-layers.md))

Witness
:   One file of one version of a work, identified by its SHA-256. ([2.1](../spec/02-model.md#21-four-objects), [2.3](../spec/02-model.md#23-witnessesjson))

Work
:   A piece of scholarship across all its versions. ([2.1](../spec/02-model.md#21-four-objects))