Files
paperspec/spec
alexmandClaude 4fb8b4f5a7 Add paperspec correct, check math forms and datasets, and give the tools public names
The work the other paper tools planned for paperspec (paperdesk PLAN M5.4,
paperform PLAN 4.2):

- paperspec correct and paperspec.revision apply proposed corrections to a
  package, folder or zip, and write it only once it validates.
- doc.math.form is checked: label and style commands always, the form's own
  spelling when papermath is installed or forms= is passed.
- paperspec.datasets and seven doc.dataset.* rules check a package's datasets.
- fixtures/invalid gains suspect-witness and math-form-label (33 in all).
- Canonical JSON reads numbers as doubles, so 1e20 round-trips.
- The registries and the JSON-LD context ship in the wheel.
- Public names for what paperdesk and paperform imported as private ones,
  with the old names kept as aliases.
- The text and lossy-projection functions are about three times faster
  through the gate, tested equal to the old code on every code point.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013XwDhn4LkrKQfw4ArDEr2E
2026-10-20 22:10:17 -04:00
..
2026-10-12 07:55:22 -04:00
2026-10-11 23:45:29 -04:00
2026-10-12 07:55:22 -04:00
2026-10-12 07:55:22 -04:00

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/papers/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