alexmandClaude
76d76353d9
- Rename manuspec to paperspec everywhere outside pixi.toml: prose, the tools, provenance tool names and the fixture key derivations, so every fixture and vector is rebuilt. - Move the namespace addresses under the site, mirroring the repository: schema $id https://paperspec.scient.ing/schemas/<file>, the JSON-LD context https://paperspec.scient.ing/context/scienting-1.jsonld, and term IRIs https://paperspec.scient.ing/vocab#<term>. Format identifiers (scienting-*) and URNs (urn:scienting:) are unchanged. - tools/site.py (standard library only) builds _site/: every file of the repository at its own path, each Markdown file rendered as a page with sidebar navigation, heading anchors matching the forge's, folder listings, a vocabulary page for the context's IRIs, a heading search and a 404 page; light and dark themes. - check.py builds the site and checks that every Markdown file has a page, every internal link and fragment resolves, no Markdown is left unrendered, and every $id, the context address and the vocabulary IRIs are files of the site. - deploy/: a Caddyfile with the media types and CORS the data needs, and a guide; .gitea/workflows/site.yml builds on main and publishes with rsync when the SITE_* secrets are set. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Fixtures
A reader, writer, converter or checker of stored papers needs files to test against, and a newcomer needs examples of what a stored paper looks like. This folder holds that example data of paperspec (https://git.scient.ing/infra/paperspec), version 0.1.0. All text is synthetic, written for these files and dedicated CC0; license fields inside the fixtures describe fictional works.
Three readers use these files. A newcomer learns what a stored paper looks like and what can go wrong with one. An implementer, who writes a reader, writer, converter or checker, tests it against the files. An expert reviewing the work finds which cases the tests pin and what the published keys do and do not prove.
Each format here has the status candidate or provisional in registry/formats.json.
A hash is a fixed-length fingerprint of data: any change to the data changes it. The hash used here is SHA-256, written in hexadecimal. A package is one document stored as a folder of files, with a manifest listing every file and its hash. A node is an addressable part of a document, such as a section, a sentence or a table cell. A witness is a source file a reading came from, such as a PDF. A receipt is a signed statement that a named person reviewed listed nodes.
Packages
Each package under packages/ is a valid document.
A conforming reader accepts each one and recomputes every hash it contains.
| Package | What it is for |
|---|---|
packages/hale2026harmonic/ |
The main example, followed step by step in the walkthrough: a chemistry paper that was read once with mistakes and then fixed by twelve corrections. It has a table with two levels of column headers and grouped rows, an equation inside a sentence, a footnote, a figure with text inside its panels and a real image, references, legacy aliases, boxes on fingerprinted pages, receipts in every state (counting, partly invalidated, spot-checked, revoked and suspended), the roster of public keys that checks their signatures, a dataset taken from the table, and derived MathML. |
packages/hale2026harmonic.checks-only/ |
The same document prepared for sharing within the team: text withheld, every hash an HMAC (a hash computed under a secret key) under the team key. The team key is derived from the team secret in keys/ (spec/05, spec/12 section 12.5). It shows how a team can share its checks on a paywalled paper without sharing the paper. |
packages/okafor2025open/ |
An open-access paper established from a JATS file (an XML format for journal articles) and a PDF that agree, so every leaf is at fidelity F2, corroborated by an independent witness. |
packages/smithlab2027charges/ |
A short draft written in Typst (a typesetting language). One of its sentences holds a cross-reference whose target is the address hale2026harmonic#r1gacps, a sentence of the main example. |
packages/tiny2026example/ |
A small document, the starting point of the correction vectors (vectors/corrections.jsonl) and of every broken package below. |
packages/tiny2026example.sct.zip |
The same document as a zipped package, written the way a producer makes a byte-identical archive: entries under one folder named by the key, sorted by path, stored, dated 1980-01-01, with no extra fields (spec/12 section 12.2). A reader unpacks it to exactly the folder beside it. |
Records
records/ holds a valid example of every other format that is a JSON file of its own.
Three formats have their example elsewhere: the stage requirements (scienting-stages/1) and the stamp rules (scienting-stamps/1) are in registry/, and a bundle (scienting-bundle/1) is a SQLite file that tools/load.py --bundle builds from the packages.
Each record is a single file, or a folder where a format needs several files.
| Files | What they are for |
|---|---|
anchor-span.json, anchor-leaf.json, anchor-cell.json, anchor-paragraph.json |
An anchor is an address pinned to a hash, with a quotation and context, so it can be found again after the text changes. These four anchors point at a span of a sentence, a sentence, a table cell and a paragraph of the main example. |
anchor-keyed.json |
An anchor that leaves the team, as in a public layer: its table context is stored as keyed hashes, so the labels cannot be read from it (spec/06 section 6.3). |
rights-open.json, rights-subscription.json, rights-collective.json |
A witness's license and what uses it allows, under an open license, a subscription and a collective license. |
policy.json |
A signed team decision that settles a use the rights record leaves unknown. |
backend-docling.json, backend-examplevendor.json |
The code and weight licenses of a conversion tool and the conditions attached to them. |
profile-acme.json, profile-smithlab.json |
What those conditions ask about a team: its purpose, its funding and whom it competes with. |
roster.json |
The keys that may sign, the role of each key's holder in the team, and what each key may sign. Ana is the owner, so she may revoke anyone's receipt. |
layer/ |
A layer of annotations on the main example (layer.json, annotations.jsonl) and the receipt that confirms them (receipt.json). |
submissions/, grades/ |
A student's answers to exercises in the layer, and the grader's result for each. |
suspect.json |
A doubtful reading raised for review: the converter's reading of an exponent in the main example, before the first correction answered it. |
qa-report.json |
Reviewer error bounds for a delivery that covers two of the main example's receipts, signed by the team's owner key. |
checklist/ |
A conformance checklist (checklist.json) for an accessible HTML export of the main example, checked against WCAG 2.1 AA criterion by criterion, and the receipt that covers it at its hash (receipt.json). The format is provisional. |
project.json, digitization.json, digitization-confirmation.json, datasets/, view.vl.json, snapshot.json, draft-ids.jsonl |
A team project; values read off the main example's figure by hand, the receipt that confirms them, and the dataset they yield; a Vega-Lite chart pinned to that dataset; what the draft cites, pinned; and the sentence IDs of the draft's Typst project. These formats are provisional. |
Broken packages
Each folder in invalid/ holds a package/ folder, or a package.sct.zip archive, that breaks exactly one rule, built from packages/tiny2026example/ by one edit, and an expect.json that names the rule.
A conforming implementation refuses every one of them and should report that rule.
registry/rules.json lists every rule ID with its meaning, and a validator reports each failure as path:line: rule: message (spec/22 section 22.2).
| Case | What is wrong | Rule |
|---|---|---|
alias-dangling/ |
An alias whose node does not exist. | doc.id.successor |
bad-id/ |
An ID that uses a letter Crockford base32 lacks (i, l, o or u). | package.schema |
checks-only-plain/ |
A checks-only package that still carries text and plain hashes. | doc.policy.withheld |
cite-not-reference/ |
A cite run names a node that is not a reference. | doc.run.cite |
counts-wrong/ |
document.json's counts are not the number of nodes and leaves. | doc.counts |
crlf/ |
A file whose lines end in CR LF, which is not the canonical form. | package.file.canonical |
empty-optional-file/ |
An optional JSONL file with no records. | package.file.empty |
hash-mismatch/ |
A node_hash that does not recompute. | doc.hash.node-hash |
heading-not-first/ |
A heading must be a section's first child. | doc.tree.child |
location-unknown-page/ |
A location on a page no witness has. | doc.location.page |
manifest-hash/ |
A file changed after the manifest was written. | package.manifest.hash |
manifest-key/ |
The manifest names another key than document.json. | package.manifest.key |
missing-required-file/ |
A required file is missing. | package.file.required |
not-canonical/ |
A line that is valid JSON but not canonical JSON (the fixed form of RFC 8785, which gives equal data identical bytes). | package.file.canonical |
receipt-root/ |
A receipt whose Merkle root (one hash that summarizes a list of hashes) does not recompute. | doc.receipt.root |
receipt-signature/ |
A receipt changed after it was signed. | doc.receipt.signature |
receipt-unsorted-nodes/ |
A receipt whose nodes are not sorted by ID. | doc.receipt.nodes |
retired-live/ |
An ID that is both live and retired. | doc.id.retired-live |
rev-without-corrections/ |
document.json's rev is not the number of corrections. | doc.correction.rev |
root-mismatch/ |
document.json's root is not the root node's node_hash. | doc.hash.root |
signer-mismatch/ |
A receipt whose signature was made with another key than the signer it names. | doc.receipt.signature |
style-sup-sub/ |
A run cannot be both a subscript and a superscript. | doc.run.style |
text-edited/ |
Text changed without its hashes. | doc.hash.text-hash |
unknown-kind/ |
Kinds outside the list are refused. | package.schema |
unlisted-file/ |
A file the manifest does not list. | package.manifest.unlisted |
unsafe-path/ |
The manifest lists a path that leaves the package. | package.path.unsafe |
zip-symlink/ |
A zipped package with an entry that is a symbolic link. | package.zip.entry |
zip-traversal/ |
A zipped package with an entry whose path leaves the package folder. | package.zip.entry |
Keys
keys/ holds the Ed25519 secret keys (ana, ben, cara, and ben-spot, whose signature picks the nodes of a spot-check) that signed the fixtures' receipts, and the team secret of the checks-only package.
Ed25519 is a signature scheme: the secret key makes a signature, and the public key in a roster verifies it.
These are published test keys.
Anyone can reproduce the signatures, so a signature made with these keys proves nothing about who made it.
Use them for nothing else.
Sources
src/ holds the hand-written descriptions of the three main documents, as first read; see src/README.md.
Everything else here is generated by python3 tools/build.py, so change the sources or the builder, never the generated files.