alexmandClaude
88379d152c
The six console scripts (paperspec-check, -build, -validate, -load, -stress, -site) become subcommands of a single `paperspec` command: paperspec validate, load, check, build, stress and site. `python -m paperspec COMMAND` runs the same thing. - paperspec/cli/main.py builds the whole parser, apart from the commands, so `paperspec --help` and `paperspec COMMAND --help` work without a checkout or the tools extra; a command's module is imported only when it runs. - `paperspec` with no command prints the overview: what each command does, examples, and which work anywhere (validate, load) and which need a checkout (check, build, stress, site). Each command's help has a description with advice, and worked examples; a misspelled command gets a suggestion (argparse suggest_on_error); `--version` prints the version and the pinned Unicode version. - Each command module exposes run(args) and returns the exit status. Arguments that parse but do not fit together raise UsageError, which prints the command's usage and exits 2: load now also refuses --built-from or --store without --bundle. - The failure messages say what to do: install paperspec[tools], clone the repository, rerun stress with the printed seed, or run paperspec build when the rebuild check differs. check and stress say how many failures they did not list. - check runs the rebuild as `python -m paperspec build`. - pyproject installs one script, `paperspec`; the pixi tasks and the docs use the subcommands. pixi run check passes (run here as `python -m paperspec check` with src/ on the path); the rebuild is byte-identical. pixi.lock still needs `pixi lock`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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 |