alexmandClaude
a09d158e16
Keys (spec/02 §2.4), the rule paperstack settled on:
- A work key is a Scholar-style citation key, a hyphen and the first four
Crockford base32 characters of SHA-256("scienting-key/1:" + identity),
where the identity is the first of doi, arxiv, isbn, pmid, pmcid and
openalex in same_as, else the folded title, year and family name. A
collision lengthens the later key by two characters; a key is minted
once and never recomputed. A document key adds .si, .v<seq> or .<type>
for versions other than the version of record.
- Every fixture key is now minted (hale2026harmonic-damb,
okafor2025solvent-acth, writer2027fixed-ynr7.v3, tiny2026tiny-j4qm), so
every node and record ID was re-minted and the docs rewritten to match.
The validator checks the document key against the work key and version
(doc.key.work) and the hash part against the identifier (doc.key.suffix).
vectors/keys.jsonl pins the cases paperstack's tests pin.
Review:
- Spot-check seeds are ECVRF-EDWARDS25519-SHA512-TAI proofs (RFC 9381),
implemented in tools/oracle/vrf.py in plain Python and reproduced
against the RFC's Example 16; the sample ranks by the VRF output. The
earlier Ed25519 seed could be ground by a dishonest checker.
- RFC 9162 inclusion and consistency proofs (crypto.inclusion_path,
verify_inclusion, consistency_proof, verify_consistency) with
scienting-proof/1, vectors/proofs.jsonl and two fixture records.
- document.json carries `history`, the root over the corrections, with
the empty-tree hash for none (spec/11 §11.5, rule doc.history).
- A provisional transparency log (spec/23): log entries, signed-note
checkpoints with key hashes as transparency logs share them, the rule
that a logged revocation beats a self-asserted time, and vectors.
- Reserved signature schemes cose and ml-dsa-65 (spec/08 §8.4).
Identifiers and text:
- urn:scienting: becomes tag:scient.ing,2026: (RFC 4151), since the URN
namespace was never registered.
- Unicode 16.0 is pinned for normalization and categories (spec/01 §1.4);
the checker refuses another version.
Checking:
- check.py: keys, proofs, VRF and checkpoint vectors; the proof and
checkpoint records; a check that every ID and hash the prose quotes
exists in the fixtures or vectors; three more broken packages
(history-wrong, key-suffix, key-work).
- stress.py: key, VRF, proof and checkpoint properties.
- Docs: a keys section in the concepts and FAQ, rationale entries for
keys, VRF, proofs, tag URIs and the Unicode pin, a "Looking ahead"
section, media-type registration and OCI distribution notes.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
4.2 KiB
4.2 KiB
The paperspec specification
This specification states exactly what each paperspec file holds and how every value in it is computed. The schemas, SQL, JSON-LD context, registries, vectors and fixtures are normative too, and each chapter says which of them it relies on. A chapter and a vector that disagree signal a bug, so please report it in the repository, https://git.scient.ing/infra/paperspec.
Two readers will get the most from it: implementers who build a reader, writer, converter or checker, and experts who want the precise rules. Newcomers should start with the guides, which explain what the formats are for. This text assumes you know why and tells you how.
Reading paths
Find the row for the job you are doing and read its chapters after those in the first row. Chapter numbers are those in the table below.
| If you are writing | Read |
|---|---|
| Anything at all | 0, 1, 3, 4 and 5: introduction, conventions, nodes, identity and the content values. |
| A reader of packages | Then 2, 6, 7 and 12: the model, anchors, geometry and the package. |
| A converter | Then 9, 10 and 11: figures and tables, references, and corrections with the gate. |
| A store or a server | Then 8, 13, 14 and 23: receipts, the database form, rights, and the transparency log. |
| A writer or reader of annotation, teaching or data files | Then 15 to 21. |
| A validator | Chapter 22, with registry/rules.json. |
Chapters
| Chapter | Subject |
|---|---|
| 0. Introduction | Scope, conformance, versions and status, and how the repository is arranged |
| 1. Shared conventions | Canonical JSON, numbers, hashes, normalization, offsets, times, determinism, IDs, keys, files and prose |
| 2. Works, versions, witnesses and documents | The four objects; document.json and witnesses.json |
| 3. Nodes | Nodes, their kinds and children, content, attributes, inline runs and the plain projection |
| 4. Identity | Minting IDs, permanence, retirement, aliases, ids.jsonl, store-qualified names and record IDs |
| 5. Content values | The five content values, the projections, alignment, suspects, keyed hashes and the metadata hash |
| 6. Addresses and anchors | Addresses, anchors and the five resolutions, with drift |
| 7. Geometry | Page fingerprints, stamp rules, pages.jsonl and locations.jsonl |
| 8. Fidelity, receipts and spot-checks | Fidelity levels, receipts, signatures, Merkle roots, the roster, revocations, spot-checks and error bounds |
| 9. Figures, tables and equations | Figures, panels, tables, cells and equations |
| 10. References and citations | Reference nodes, references.jsonl and its resolutions, and sentence-level citations |
| 11. Corrections | Corrections and the gate |
| 12. The package | The files of a package, paths, manifest, provenance, text policies and assets |
| 13. The database form and the bundle | The database form and the SQLite bundle |
| 14. Rights | Rights records, policies, stages and backends |
| 15. Datasets | Frictionless Data Packages with units, uncertainty and origin; anchors.jsonl; content hash |
| 16. Digitization records | How values were read off a figure panel: target, axes, series, method, verification and confirmation |
| 17. Views | Vega-Lite specifications that pin their data, and optional computations |
| 18. Layers and annotations | Layers and annotations |
| 19. Exercises, submissions and grades | Exercises, submissions and grades |
| 20. Projects | Members and roles, documents, reading paths, held layers, datasets, views and drafts, and settings |
| 21. Drafts | Drafts: snapshots and sentence-ID sidecars |
| 22. Conformance | Conformance, the suite and the rule catalog |
| 23. The transparency log | A team's log of receipts, revocations and rosters, its checkpoints, and what it settles |