Files
paperspec/docs/package/guides/validate-a-package.md
T
alexmandClaude 30d310f64d Publish the package and its documentation, and move to the papers organization
Add the Zensical documentation of the Python package (docs/package, built by the docs
workflow), merge the standard publish workflow with the setuptools-scm tag check, add the
SPDX header rule to ruff, restructure the README, and point every repository and registry
address at the Gitea organization papers.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B8cL4zN4XpaQF5cBtASzfq
2026-10-19 04:23:49 -04:00

44 lines
2.5 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.