Files
paperspec/docs/package/about/index.md
T
2026-10-19 04:33:03 -04:00

37 lines
2.3 KiB
Markdown

# 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](../reference/api.md) is written by hand from the code's docstrings.
- The package is not on Scienting's registry until a version tag is pushed. `[CHECK: no tag exists yet]`
- Thirteen formats are `provisional` and may still change.