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
57 lines
3.3 KiB
Markdown
57 lines
3.3 KiB
Markdown
# 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
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```json
|
|
{"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:
|
|
|
|
```sh
|
|
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.
|