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

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