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
3.3 KiB
Validate a package
A package is a folder, or a zipped package (.sct.zip), that holds one document.
paperspec validate checks it against every rule of the specification's conformance chapter and works anywhere the package is installed with its tools extra.
Check one or several packages
paperspec validate fixtures/packages/hale2026harmonic-damb
paperspec validate fixtures/packages/tiny2026tiny-j4qm.sct.zip fixtures/packages/tiny2026tiny-j4qm
Each valid package prints PACKAGE: valid and the exit status is 0.
A failure goes to standard error as package: where: rule: message, the exit status is 1, and nothing else prints.
A usage error, such as no package at all, exits with status 2.
A zipped package is unpacked under the specification's path rules before anything else happens: a path that leaves the folder, a symbolic link and an oversize archive are refused.
--max-size BYTES sets the largest size an archive may expand to; the default is 1 GiB.
Read a refusal
The rule ID names the rule that failed.
https://paperspec.scient.ing/registry/rules.json lists every ID with the chapter of the specification that states it, which is where to read why.
The folder fixtures/invalid/ holds one package for each of many rules; its expect.json says which rules the package must trigger.
Try a correction before making it
A correction changes one node of a document and records why. Before a tool writes one, it can run the proposal through the gate, which needs only the package's current state:
paperspec validate --correction fix.json fixtures/packages/tiny2026tiny-j4qm
fix.json holds one proposal as a JSON object, or several as JSON Lines, applied in order:
{"format":"scienting-correction/1","op":"emend","target":"j663d4h","find":"second","replace":"next","kind":"wording","status":"proposed","evidence":[{"kind":"person","by":"ana","note":"The editor prefers a plainer word."}],"author":{"key":"ana"},"reason":"The authors misuse the ordinal; the paragraph follows the first.","at":"2026-10-03T10:00:00Z"}
The command prints the record the correction would append to corrections.jsonl, with its computed index, id, path, before and after, and writes nothing.
A refused proposal prints file:N node: rule: message on standard error and stops: with this proposal, changing second to 2nd is refused with correction.digits, because an emendation changes no digit.
--correction takes exactly one package, and it refuses a package that withholds its text.
Apply the correction
When the proposal passes, paperspec correct applies it and writes the corrected package:
paperspec correct --correction fix.json --out fixed/tiny2026tiny-j4qm fixtures/packages/tiny2026tiny-j4qm
It runs the same gate, then rewrites every file the correction touches: the nodes and their values, corrections.jsonl, ids.jsonl, references.jsonl, locations.jsonl, suspects.jsonl, document.json and the manifest.
The corrected package is validated before it is written; without --out it replaces the package given.
The printed record is the one validate --correction printed.
A leaf the correction changed drops to F1 when the evidence includes a crop of the page, and to F0 otherwise; an emendation like this one keeps the leaf's level.