alexmandClaude
607062056f
Python and Unicode
- requires-python is >=3.14,<3.15: 3.14 is the only Python with the
Unicode 16.0 data the specification pins (3.13 has 15.1, 3.15 has 17.0).
- `import paperspec` raises ImportError unless unicodedata reports
paperspec.UNICODE_VERSION (16.0.0), so a source checkout or an install
that bypasses requires-python cannot compute values on other data.
Commands
- tools/{check,build,validate,load,stress,site}.py move with history to
src/paperspec/cli/ and install as paperspec-check, -build, -validate,
-load, -stress and -site; each also runs as `python -m paperspec.cli.X`.
- paperspec.cli.require() exits with "install paperspec[tools]" when
cryptography or jsonschema is missing; paperspec.cli.checkout() finds
the repository the check, build, stress and site commands work on (the
editable install's own checkout, else the one around the current
folder) and exits with a message outside one. tools/__init__.py is gone.
- validate and load read the schemas and SQL through the new
paperspec.resources.path(), which finds them in a wheel and in an
editable install alike, so they work anywhere the package is installed.
- check runs the rebuild as `python -m paperspec.cli.build`.
- build still writes the provenance tool label "paperspec tools/build.py":
it is part of every hashed and signed fixture.
- pixi tasks and the check workflow run the commands; tools/README.md
documents them, and the other docs name the commands instead of paths.
License
- LICENSE.md gives `src/` Apache-2.0 alongside `tools/`. Since the
previous commit moved the code to src/, no row had covered it.
pixi run check passes (run as `python -m paperspec.cli.check` with src/ on
the path, since this environment cannot install the entry points); the
byte-for-byte rebuild matches, so no fixture or vector changed.
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 |