alexmandClaude
516148146f
Publishing - .gitea/workflows/publish.yml publishes paperspec to the instance's PyPI registry (/api/packages/infra/pypi) when a v* tag is pushed: it checks the repository, builds the sdist and wheel, refuses to upload unless the built version equals the tag, runs twine check --strict, and uploads with the secrets PACKAGE_USER and PACKAGE_TOKEN (--skip-existing, so a rerun on the same tag is safe). Run by hand, it refuses anything but a tag. - pixi dev environment: twine >= 6.1 (the first that reads Metadata 2.4), and `dist` (sdist and wheel) replaces the `wheel` task. - deploy/README.md: how to set up the secrets, release a version, and install from the registry with pixi, uv or pip, tying paperspec to the registry where the installer allows it. - CONTRIBUTING.md "Releasing": a tag versions the package; a format change takes the new format version as the top CHANGELOG heading, and a code-only release takes the next patch as a subsection, as 0.1.1 does. - pyproject: fallback_version 0+unknown for source trees without git; the license expression is Apache-2.0 AND CC0-1.0, for the code and the data the wheel carries. Cleanup (from an audit of every reference to the package) - spec/00 lists src/ (the package) and tools/ (how to run it), and no longer says the reference implementation is not a library. - Stale explanations fixed in pixi.toml, .gitignore, the Caddyfile, the vectors, context, sql and tools READMEs, docs/examples.md, docs/faq.md, spec/01, docs/rationale.md and docs/comparison.md: the commands, what they need (the tools extra), the fixture folder hale2026harmonic-damb, and three lines that held two sentences. - tools/README.md counts all six commands, says what needs which extra (package.validate and corrections.gate need [schema]), and that the vectors ship but the fixtures they name do not. - The CLI's install and clone hints point at the registry instructions and an https clone URL; schema.py raises an ImportError naming paperspec[schema], as crypto.py does for [crypto]. - check's Unicode check now guards the package's pinned constant. - site skips build/, dist/ and *.egg-info. - CHANGELOG 0.1.1 describes the final state. pixi run check passes (as `python -m paperspec check`); the rebuild is byte-identical. pixi.lock needs `pixi lock` for twine before pushing: the publish workflow installs with --locked. 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 |