Files
paperspec/docs/package/about/index.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.3 KiB

About

Status

The formats are at version 0.1.0. Of the 32 formats, 19 are candidate and 13 are provisional; registry/formats.json in the repository lists each with its media type, schema, status and chapter. The Python package is at an alpha stage (the Development Status :: 3 - Alpha classifier). Its version comes from git tags, so a tag v0.1.1 builds as 0.1.1 and later commits as 0.1.2.devN.

Design commitments

  • The code defines the expected values. No expected value in a vector or fixture is typed by hand: the oracle computes it, and paperspec check rebuilds everything and compares it byte for byte.
  • Standard library first. Every module imports with the standard library alone. Schema validation and the Ed25519 and HKDF functions import jsonschema, referencing and cryptography on first use, through the package's extras.
  • Clarity over speed. The oracle is a slow, plain program. The verifiable random function (RFC 9381) and ML-DSA-65 (FIPS 204) are written out in Python and checked against those standards' own test vectors.
  • One Python. The specification pins the Unicode 16.0 character data that normalization and the character classes come from, so the package refuses to import on a Python with another version. Python 3.14 is the only one that matches.

Known limits and unfinished parts

This documentation describes what the code does. Where an older guide, a doc comment or the --help text says something different, the code wins, and this section lists the differences.

  • The package is an oracle, not a production reader or writer. It has not been measured for speed or for large corpora; the formats are built for a team-scale corpus of hundreds of documents.
  • Only validate and load work on an installed package. check, build, stress and site need a checkout of the repository.
  • paperspec validate --correction reports a proposals file that is not valid JSON with a Python traceback, not a one-line message.
  • The Python API has no generated reference yet: the API page is written by hand from the code's docstrings.
  • The package is not on the studio's registry until a version tag is pushed. [CHECK: no tag exists yet]
  • Thirteen formats are provisional and may still change.