Files
paperspec/docs/package/guides/validate-a-package.md
T
alexmandClaude 4fb8b4f5a7 Add paperspec correct, check math forms and datasets, and give the tools public names
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
2026-10-20 22:10:17 -04:00

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.