Compare commits
17
Commits
7890fa1ad7
...
bc7d461dcd
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
bc7d461dcd
|
||
|
|
03b4722023
|
||
|
|
105896a18b
|
||
|
|
f262337eac
|
||
|
|
7c0f837713
|
||
|
|
c3145f8495
|
||
|
|
4fb8b4f5a7
|
||
|
|
8c07dd7c15
|
||
|
|
a8fc7237ae
|
||
|
|
30d310f64d
|
||
|
|
bdbf03ebee
|
||
|
|
21e6d31de1
|
||
|
|
2ec1e013e5
|
||
|
|
2cfa080393
|
||
|
|
b5f88d0177
|
||
|
|
6025ea3f79
|
||
|
|
3ab96d653f
|
No files matched your search
+23
@@ -0,0 +1,23 @@
|
||||
[run]
|
||||
branch = True
|
||||
source = paperspec
|
||||
relative_files = True
|
||||
|
||||
[report]
|
||||
fail_under = 90
|
||||
precision = 1
|
||||
show_missing = True
|
||||
skip_covered = True
|
||||
skip_empty = True
|
||||
exclude_also =
|
||||
if TYPE_CHECKING:
|
||||
raise NotImplementedError
|
||||
@(abc\.)?abstractmethod
|
||||
if __name__ == .__main__.:
|
||||
\.\.\.$
|
||||
|
||||
[html]
|
||||
directory = htmlcov
|
||||
|
||||
[xml]
|
||||
output = coverage.xml
|
||||
+5
-66
@@ -1,81 +1,20 @@
|
||||
# EditorConfig: https://editorconfig.org
|
||||
# In VS Code, install the "EditorConfig for VS Code" extension (EditorConfig.EditorConfig).
|
||||
|
||||
# https://editorconfig.org
|
||||
root = true
|
||||
|
||||
[*]
|
||||
charset = utf-8
|
||||
end_of_line = lf
|
||||
indent_style = space
|
||||
indent_size = 4
|
||||
insert_final_newline = true
|
||||
trim_trailing_whitespace = true
|
||||
|
||||
[*.{py,pyi}]
|
||||
indent_size = 4
|
||||
max_line_length = 88
|
||||
|
||||
[*.{mojo,🔥}]
|
||||
indent_size = 4
|
||||
max_line_length = 88
|
||||
|
||||
[*.rs]
|
||||
indent_size = 4
|
||||
max_line_length = 100
|
||||
|
||||
[{Cargo.toml,Cargo.lock,rustfmt.toml,.rustfmt.toml,clippy.toml}]
|
||||
indent_size = 4
|
||||
|
||||
[{mojoproject.toml,pixi.toml,pixi.lock}]
|
||||
indent_size = 4
|
||||
|
||||
[*.{yml,yaml}]
|
||||
indent_size = 2
|
||||
|
||||
[*.{json,jsonc,json5}]
|
||||
indent_size = 2
|
||||
|
||||
[*.sql]
|
||||
indent_style = space
|
||||
indent_size = 2
|
||||
|
||||
[*.{js,jsx,mjs,cjs,ts,tsx,css,scss,less,html,vue,svelte}]
|
||||
indent_size = 2
|
||||
|
||||
[*.{toml,ini,cfg}]
|
||||
indent_size = 4
|
||||
|
||||
[*.xml]
|
||||
[*.{yml,yaml,json,toml,md}]
|
||||
indent_size = 2
|
||||
|
||||
[*.{md,markdown}]
|
||||
indent_size = 2
|
||||
[*.md]
|
||||
trim_trailing_whitespace = false
|
||||
|
||||
[*.{sh,bash,zsh}]
|
||||
indent_size = 2
|
||||
|
||||
[{Makefile,makefile,*.mk}]
|
||||
indent_style = tab
|
||||
|
||||
[*.go]
|
||||
indent_style = tab
|
||||
|
||||
[*.{bat,cmd,ps1}]
|
||||
end_of_line = crlf
|
||||
|
||||
[{Dockerfile,Dockerfile.*,*.dockerfile}]
|
||||
indent_size = 4
|
||||
|
||||
[*.{tf,tfvars,hcl}]
|
||||
indent_size = 2
|
||||
|
||||
[LICENSE*]
|
||||
[*.{csv,tsv}]
|
||||
trim_trailing_whitespace = false
|
||||
insert_final_newline = false
|
||||
|
||||
[*.{diff,patch}]
|
||||
trim_trailing_whitespace = false
|
||||
|
||||
[*.min.{js,css}]
|
||||
insert_final_newline = unset
|
||||
trim_trailing_whitespace = unset
|
||||
+10
-3
@@ -1,7 +1,14 @@
|
||||
# Normalize line endings; keep data files byte-for-byte.
|
||||
* text=auto eol=lf
|
||||
# Generated data: exact bytes matter, and diffs are by line.
|
||||
*.csv -text
|
||||
*.tsv -text
|
||||
*.gz binary
|
||||
# Scripts must keep LF endings to run.
|
||||
*.sh text eol=lf
|
||||
# Gitea (and GitHub): collapse generated files in diffs, keep pixi.lock out of language stats.
|
||||
pixi.lock merge=binary linguist-language=YAML linguist-generated=true -diff
|
||||
# paperspec-specific: generated data whose exact bytes matter (the broken packages include CRLF and
|
||||
# empty files on purpose), diffed by line.
|
||||
vectors/** -text diff
|
||||
fixtures/** -text diff
|
||||
fixtures/**/*.png binary
|
||||
# The pixi lock file: generated, highlighted as YAML, never merged line by line.
|
||||
pixi.lock merge=binary linguist-language=YAML linguist-generated=true
|
||||
@@ -1,21 +0,0 @@
|
||||
# Forgejo and Gitea Actions both read .github/workflows when their own folder is absent.
|
||||
# On Forgejo, if the runner's default action mirror lacks setup-pixi, write it as
|
||||
# https://github.com/prefix-dev/setup-pixi@v0.9.4.
|
||||
# The tools need Python 3.14, which pixi.toml pins, so one environment covers every supported Python.
|
||||
name: check
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
|
||||
jobs:
|
||||
check:
|
||||
runs-on: linux-base
|
||||
container:
|
||||
image: git.scient.ing/infra/linux-base:26.10.7
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Check the repository
|
||||
run: pixi run check
|
||||
- name: Stress the reference implementation
|
||||
run: pixi run stress
|
||||
@@ -0,0 +1,50 @@
|
||||
# Continuous integration on Gitea Actions.
|
||||
#
|
||||
# Runner labels: `linux-base` is the label of Scienting's runner. If your
|
||||
# runner registers different labels, change the `os` matrix.
|
||||
# Forgejo and Gitea Actions both read .github/workflows when their own folder is absent.
|
||||
# On Forgejo, if the runner's default action mirror lacks setup-pixi, write it as
|
||||
# https://github.com/prefix-dev/setup-pixi@v0.9.4.
|
||||
# The checks need Python 3.14, which pixi.toml pins, so one environment covers every supported Python.
|
||||
name: ci
|
||||
on:
|
||||
push:
|
||||
branches: [main, dev]
|
||||
pull_request:
|
||||
workflow_dispatch:
|
||||
|
||||
# Cancels superseded runs on the same branch (Gitea 1.26+; older versions do
|
||||
# not cancel).
|
||||
concurrency:
|
||||
group: ${{ gitea.workflow }}-${{ gitea.event_name }}-${{ gitea.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
check:
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
os: [linux-base]
|
||||
runs-on: ${{ matrix.os }}
|
||||
# pixi comes with the job image, as in the site and publish workflows.
|
||||
container:
|
||||
image: git.scient.ing/infra/linux-base:26.10.7
|
||||
timeout-minutes: 30
|
||||
env:
|
||||
PYTEST_ADDOPTS: --maxfail=0 # report every failure in CI
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- run: pixi run fmt-check
|
||||
- run: pixi run lint
|
||||
- run: pixi run typecheck
|
||||
- run: pixi run cov
|
||||
# paperspec-specific: the repository checks the oracle exists to run.
|
||||
- name: Lint the Markdown
|
||||
run: pixi run lint-md
|
||||
- name: Check the repository
|
||||
run: pixi run verify
|
||||
- name: Stress the reference implementation
|
||||
run: pixi run stress
|
||||
@@ -0,0 +1,56 @@
|
||||
# Builds the Zensical documentation strictly (a broken link or a page missing from the navigation fails the job) and,
|
||||
# on main, copies it to /srv/www/docs/paperspec, which serves https://docs.scient.ing/paperspec/.
|
||||
# The linux-base runner mounts the host's /srv/www into its job containers, so publishing is a local copy.
|
||||
name: docs
|
||||
on:
|
||||
push:
|
||||
branches: [main, dev]
|
||||
paths:
|
||||
- "docs/**"
|
||||
- "zensical.toml"
|
||||
- "README.md"
|
||||
- "CHANGELOG.md"
|
||||
- "src/**"
|
||||
- ".gitea/workflows/docs.yml"
|
||||
workflow_dispatch:
|
||||
permissions:
|
||||
contents: read
|
||||
concurrency:
|
||||
group: docs-${{ gitea.ref }}
|
||||
cancel-in-progress: true
|
||||
defaults:
|
||||
run:
|
||||
shell: bash
|
||||
env:
|
||||
SITE_ROOT: /srv/www/docs
|
||||
SITE_SLUG: paperspec
|
||||
jobs:
|
||||
docs:
|
||||
runs-on: linux-base
|
||||
container:
|
||||
image: git.scient.ing/infra/linux-base:26.10.7
|
||||
timeout-minutes: 15
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
persist-credentials: false
|
||||
- name: Build the documentation, strictly
|
||||
run: pixi run --locked -e docs docs-build
|
||||
- name: Publish the documentation
|
||||
if: github.ref == 'refs/heads/main'
|
||||
run: |
|
||||
if [ ! -d "$SITE_ROOT" ]; then
|
||||
echo "$SITE_ROOT is not mounted on this runner, so the docs were built but not published."
|
||||
exit 0
|
||||
fi
|
||||
case "$SITE_SLUG" in
|
||||
''|*/*|.*) echo "SITE_SLUG must be a plain folder name, not '$SITE_SLUG'." >&2; exit 1 ;;
|
||||
esac
|
||||
if [ ! -f build/docs/index.html ] || [ ! -f build/docs/404.html ]; then
|
||||
echo "build/docs has no index.html or 404.html, so it was not published." >&2
|
||||
exit 1
|
||||
fi
|
||||
# Same copy as the other studio sites: unchanged files keep their Last-Modified and ETag, and the
|
||||
# changes apply together at the end of the copy.
|
||||
rsync --recursive --links --perms --chmod=D755,F644 --checksum --delay-updates --delete-delay --stats \
|
||||
build/docs/ "$SITE_ROOT/$SITE_SLUG/"
|
||||
@@ -1,16 +1,18 @@
|
||||
# Publishes the paperspec Python package to this instance's PyPI registry when a version tag (v0.1.1) is
|
||||
# pushed; see deploy/README.md for the secrets it needs and how to install from the registry.
|
||||
# The package version comes from the tag through setuptools-scm, so the job refuses to upload unless the
|
||||
# built version equals the tag. Run it by hand only on a tag, for example after adding the secrets.
|
||||
# Publishes the paperspec wheel and sdist to this Gitea instance's PyPI registry when a version tag (v1.2.3) is pushed,
|
||||
# and creates the Gitea release with both files attached. The version is the tag's: setuptools-scm computes it
|
||||
# from git (hence the full-history checkout), and the job refuses to upload unless the built version equals the
|
||||
# tag, so tag the commit you mean to release. Run it by hand only on a tag.
|
||||
# Needs the organization secrets PACKAGE_USER and PACKAGE_TOKEN (a token with the write:package scope).
|
||||
# Install side: README.md ("Installing") and deploy/README.md name the registry index.
|
||||
name: publish
|
||||
on:
|
||||
push:
|
||||
tags: ["v*"]
|
||||
tags: ["v[0-9]*"]
|
||||
workflow_dispatch:
|
||||
permissions:
|
||||
contents: read
|
||||
concurrency:
|
||||
group: publish-${{ github.ref }}
|
||||
group: publish-${{ gitea.ref }}
|
||||
cancel-in-progress: false
|
||||
defaults:
|
||||
run:
|
||||
@@ -23,14 +25,14 @@ jobs:
|
||||
timeout-minutes: 30
|
||||
env:
|
||||
REGISTRY: ${{ github.server_url }}/api/packages/${{ github.repository_owner }}/pypi
|
||||
API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
|
||||
steps:
|
||||
- name: Require a version tag
|
||||
run: |
|
||||
if [[ "$GITHUB_REF" != refs/tags/v* ]]; then
|
||||
echo "Publish runs on a version tag such as v0.1.1; $GITHUB_REF is not one."
|
||||
echo "Publish runs on a version tag such as v1.2.3; $GITHUB_REF is not one."
|
||||
exit 1
|
||||
fi
|
||||
# The whole history, so setuptools-scm finds the tag and computes the release version.
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
@@ -38,7 +40,7 @@ jobs:
|
||||
- name: Check the repository
|
||||
run: pixi run --locked check
|
||||
- name: Build the sdist and wheel
|
||||
run: pixi run --locked -e dev dist
|
||||
run: pixi run --locked -e release dist
|
||||
- name: Confirm the built version is the tag
|
||||
run: |
|
||||
tag="${GITHUB_REF_NAME#v}"
|
||||
@@ -50,7 +52,7 @@ jobs:
|
||||
exit 1
|
||||
fi
|
||||
- name: Check the package metadata
|
||||
run: pixi run --locked -e dev twine check --strict dist/*
|
||||
run: pixi run --locked -e release twine check --strict dist/*
|
||||
# --skip-existing makes a rerun on the same tag succeed instead of failing on the files already there.
|
||||
- name: Upload to the package registry
|
||||
env:
|
||||
@@ -62,5 +64,21 @@ jobs:
|
||||
echo "The secrets PACKAGE_USER and PACKAGE_TOKEN are not set; deploy/README.md says how."
|
||||
exit 1
|
||||
fi
|
||||
pixi run --locked -e dev twine upload --non-interactive --skip-existing dist/*
|
||||
pixi run --locked -e release twine upload --non-interactive --skip-existing dist/*
|
||||
echo "Published to $REGISTRY: pip install --index-url $REGISTRY/simple/ paperspec"
|
||||
- name: Create the release and attach the files
|
||||
env:
|
||||
TOKEN: ${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
|
||||
run: |
|
||||
# A release is a "## 0.1.0" or "### 0.1.1" heading in CHANGELOG.md; its notes run to the next heading.
|
||||
notes="$(awk -v v="${GITHUB_REF_NAME#v}" '
|
||||
/^##+ / { if (found) exit; if (index($0, v)) found = 1; next }
|
||||
found { print }' CHANGELOG.md)"
|
||||
body="$(printf '%s\n' "${notes:-See CHANGELOG.md.}" | jq -Rs .)"
|
||||
release_id="$(curl -fsS -X POST "$API/releases" \
|
||||
-H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
|
||||
-d "{\"tag_name\": \"$GITHUB_REF_NAME\", \"name\": \"$GITHUB_REF_NAME\", \"body\": $body}" | jq .id)"
|
||||
for f in dist/*; do
|
||||
curl -fsS -X POST "$API/releases/$release_id/assets?name=$(basename "$f")" \
|
||||
-H "Authorization: token $TOKEN" -F "attachment=@$f"
|
||||
done
|
||||
+29
-15
@@ -1,17 +1,18 @@
|
||||
__pycache__/
|
||||
*.pyc
|
||||
*.db
|
||||
*.db.assets/
|
||||
|
||||
# the package version, written by setuptools-scm when the package is built or installed
|
||||
/src/paperspec/_version.py
|
||||
|
||||
# the website, built by `paperspec site`
|
||||
/_site/
|
||||
|
||||
# pixi environments
|
||||
# Project
|
||||
.venv/
|
||||
.pixi/*
|
||||
!.pixi/config.toml
|
||||
.hypothesis/
|
||||
.coverage
|
||||
htmlcov/
|
||||
dist/
|
||||
coverage.xml
|
||||
*.egg-info/
|
||||
logs/
|
||||
.env
|
||||
!.env.example
|
||||
# Claude Code personal settings (sandbox, hooks)
|
||||
.claude/settings.local.json
|
||||
|
||||
|
||||
# Created by https://www.toptal.com/developers/gitignore/api/osx,python,pycharm,windows,visualstudio,visualstudiocode,zsh,jetbrains,jupyternotebooks
|
||||
@@ -255,7 +256,6 @@ venv/
|
||||
ENV/
|
||||
env.bak/
|
||||
venv.bak/
|
||||
.claude
|
||||
|
||||
# Spyder project settings
|
||||
.spyderproject
|
||||
@@ -761,7 +761,21 @@ FodyWeavers.xsd
|
||||
|
||||
# End of https://www.toptal.com/developers/gitignore/api/osx,python,pycharm,windows,visualstudio,visualstudiocode,zsh,jetbrains,jupyternotebooks
|
||||
|
||||
# The Visual Studio rules above ignore every packages/ and log/ folder; these hold fixtures that `paperspec check`
|
||||
# compares byte for byte, so keep them.
|
||||
# paperspec-specific
|
||||
|
||||
# SQLite databases that `paperspec load` writes, and the folder of asset files beside each
|
||||
*.db
|
||||
*.db.assets/
|
||||
|
||||
# the package version, written by setuptools-scm when the package is built or installed
|
||||
/src/paperspec/_version.py
|
||||
|
||||
# the website, built by `paperspec site`
|
||||
/_site/
|
||||
|
||||
# the Visual Studio rules above ignore every packages/ and log/ folder; these hold fixtures that
|
||||
# `paperspec check` compares byte for byte, so keep them
|
||||
!/fixtures/packages/*
|
||||
!/fixtures/records/log/
|
||||
# notes and scratch files for this machine, never published
|
||||
work/
|
||||
@@ -0,0 +1,45 @@
|
||||
# Install once with `pixi run hooks`. Ruff and ty run through pixi so hooks use
|
||||
# exactly the same versions and settings as `pixi run check`.
|
||||
# Test fixtures are deliberately messy inputs, so hooks leave them alone.
|
||||
exclude: ^tests/fixtures/
|
||||
repos:
|
||||
- repo: https://github.com/pre-commit/pre-commit-hooks
|
||||
rev: v6.0.0
|
||||
hooks:
|
||||
- id: check-added-large-files
|
||||
args: [--maxkb=1000]
|
||||
- id: check-merge-conflict
|
||||
- id: check-toml
|
||||
- id: check-yaml
|
||||
exclude: ^src/.*\.ya?ml$
|
||||
- id: end-of-file-fixer
|
||||
exclude: \.(csv|tsv)$
|
||||
- id: trailing-whitespace
|
||||
exclude: \.(csv|tsv|md)$
|
||||
- id: mixed-line-ending
|
||||
args: [--fix=lf]
|
||||
|
||||
- repo: https://github.com/python-jsonschema/check-jsonschema
|
||||
rev: 0.38.2
|
||||
hooks:
|
||||
- id: check-github-workflows
|
||||
files: ^\.gitea/workflows/.+\.ya?ml$
|
||||
|
||||
- repo: local
|
||||
hooks:
|
||||
- id: ruff-format
|
||||
name: ruff format
|
||||
entry: pixi run ruff format
|
||||
language: system
|
||||
types_or: [python, pyi]
|
||||
- id: ruff-check
|
||||
name: ruff check
|
||||
entry: pixi run ruff check --fix --exit-non-zero-on-fix
|
||||
language: system
|
||||
types_or: [python, pyi]
|
||||
- id: ty
|
||||
name: ty check
|
||||
entry: pixi run ty check
|
||||
language: system
|
||||
types: [python]
|
||||
pass_filenames: false
|
||||
+51
@@ -0,0 +1,51 @@
|
||||
[pytest]
|
||||
minversion = 8.4
|
||||
required_plugins = pytest-cov hypothesis
|
||||
testpaths =
|
||||
tests
|
||||
src
|
||||
# Lets tests import shared helpers (conftest constants, fakes) directly.
|
||||
pythonpath = tests
|
||||
norecursedirs =
|
||||
*.egg
|
||||
.eggs
|
||||
dist
|
||||
build
|
||||
docs
|
||||
.tox
|
||||
.git
|
||||
.pixi
|
||||
.venv
|
||||
node_modules
|
||||
__pycache__
|
||||
.hypothesis
|
||||
.pytest_cache
|
||||
.ruff_cache
|
||||
htmlcov
|
||||
python_files = test_*.py
|
||||
doctest_optionflags =
|
||||
NUMBER
|
||||
NORMALIZE_WHITESPACE
|
||||
IGNORE_EXCEPTION_DETAIL
|
||||
ELLIPSIS
|
||||
# The default run skips the slow and networked suites; `-m live` on the
|
||||
# command line replaces this selection.
|
||||
addopts =
|
||||
--strict-markers
|
||||
--strict-config
|
||||
--import-mode=importlib
|
||||
--tb=short
|
||||
--doctest-modules
|
||||
--doctest-continue-on-failure
|
||||
--maxfail=2
|
||||
-ra
|
||||
-m "not live"
|
||||
markers =
|
||||
live: hits real public services; needs network (and any API keys it names)
|
||||
xfail_strict = true
|
||||
empty_parameter_set_mark = fail_at_collect
|
||||
# Turn every warning into an error so deprecations surface immediately.
|
||||
filterwarnings =
|
||||
error
|
||||
# Dump tracebacks of all threads if a single test hangs this long.
|
||||
faulthandler_timeout = 300
|
||||
+126
@@ -0,0 +1,126 @@
|
||||
# Ruff linter + formatter. https://docs.astral.sh/ruff/settings/
|
||||
target-version = "py314"
|
||||
line-length = 88
|
||||
indent-width = 4
|
||||
src = ["src", "tests"]
|
||||
required-version = ">=0.14"
|
||||
|
||||
# Ruff already skips .git, .venv, venv, build, dist, caches, node_modules,
|
||||
# site-packages, and the other usual suspects (`ruff check --show-settings`),
|
||||
# and respects .gitignore. Only list what is specific to this project.
|
||||
extend-exclude = [".pixi", "htmlcov"]
|
||||
|
||||
[lint]
|
||||
preview = true
|
||||
# Preview *behavior* is on, but preview-only rules must be selected by code,
|
||||
# so upgrading ruff never silently turns on unstable rules.
|
||||
explicit-preview-rules = true
|
||||
select = [
|
||||
"F", # pyflakes
|
||||
"E", # pycodestyle errors
|
||||
"W", # pycodestyle warnings
|
||||
"I", # isort
|
||||
"N", # pep8-naming
|
||||
"D", # pydocstyle
|
||||
"UP", # pyupgrade
|
||||
"ANN", # annotations
|
||||
"S", # bandit (security)
|
||||
"BLE", # blind except
|
||||
"FBT", # boolean traps
|
||||
"B", # bugbear
|
||||
"C4", # comprehensions
|
||||
"DTZ", # timezone-aware datetimes
|
||||
"T20", # print statements
|
||||
"PT", # pytest style
|
||||
"RET", # return statements
|
||||
"SIM", # simplify
|
||||
"TID", # tidy imports
|
||||
"ARG", # unused arguments
|
||||
"PTH", # prefer pathlib
|
||||
"ERA", # commented-out code
|
||||
"PGH", # pygrep hooks (specific noqa / type: ignore codes)
|
||||
"PL", # pylint
|
||||
"TRY", # tryceratops
|
||||
"PERF", # performance
|
||||
"LOG", # logging
|
||||
"G", # logging format strings
|
||||
"PIE", # misc lints
|
||||
"INP", # implicit namespace packages
|
||||
"RUF", # ruff-specific
|
||||
"CPY001", # every Python file opens with the license header (preview rule, so selected by code)
|
||||
]
|
||||
ignore = [
|
||||
"D105", # magic-method docstrings
|
||||
"D107", # __init__ docstrings (documented on the class)
|
||||
"PLR0911", # too many returns: decision tables read best flat
|
||||
"PLR0912", # too many branches: same
|
||||
"PLR0913", # too many arguments: config-driven constructors
|
||||
"PLR0915", # too many statements: same
|
||||
"PLR0917", # too many positional arguments
|
||||
"PLR2004", # magic values: thresholds live in config
|
||||
"TRY003", # long exception messages are deliberate
|
||||
"ANN401", # Any is used for raw API payloads
|
||||
"FBT001", # boolean positional args in small helpers
|
||||
"FBT002",
|
||||
]
|
||||
fixable = ["ALL"]
|
||||
dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
|
||||
|
||||
[lint.per-file-ignores]
|
||||
"tests/**/*.py" = [
|
||||
"S101", # assert is the point of tests
|
||||
"D", # test docstrings are optional
|
||||
"ANN", # fixtures and tests need no annotations
|
||||
"INP001", # tests are not a package
|
||||
"ARG", # fixtures are often requested only for side effects
|
||||
"FBT",
|
||||
"PLR2004",
|
||||
"PLC0415", # local imports keep heavy fixtures lazy
|
||||
"S105",
|
||||
"S106",
|
||||
"S311", # pseudo-random data is fine in tests
|
||||
"S603", # tests drive git with fixed argument lists
|
||||
"S607",
|
||||
"DTZ",
|
||||
"E501", # dense fixtures
|
||||
"PT018",
|
||||
"BLE001", # deliberate fault injection
|
||||
"T20",
|
||||
]
|
||||
"src/paperspec/cli.py" = ["T201"] # the CLI prints by design
|
||||
"**/__init__.py" = ["F401"] # re-exports
|
||||
"src/paperspec/cli/*.py" = ["T201"] # paperspec-specific: the commands are a package, and they print by design
|
||||
|
||||
[lint.flake8-copyright]
|
||||
# paperspec-specific: the code is Apache-2.0 (LICENSE.md), not Prosperity, so the header is an SPDX identifier.
|
||||
notice-rgx = "SPDX-License-Identifier: Apache-2\\.0"
|
||||
min-file-size = 0
|
||||
|
||||
[lint.pycodestyle]
|
||||
# The formatter wraps code at 88; allow unbreakable strings/URLs up to 100.
|
||||
max-line-length = 100
|
||||
|
||||
[lint.pydocstyle]
|
||||
convention = "google"
|
||||
|
||||
[lint.isort]
|
||||
known-first-party = ["paperspec"]
|
||||
combine-as-imports = true
|
||||
|
||||
[lint.flake8-tidy-imports]
|
||||
ban-relative-imports = "all"
|
||||
|
||||
[lint.flake8-pytest-style]
|
||||
fixture-parentheses = false
|
||||
mark-parentheses = false
|
||||
|
||||
[lint.flake8-annotations]
|
||||
allow-star-arg-any = true
|
||||
|
||||
[format]
|
||||
quote-style = "double"
|
||||
indent-style = "space"
|
||||
skip-magic-trailing-comma = false
|
||||
line-ending = "lf"
|
||||
docstring-code-format = true
|
||||
docstring-code-line-length = "dynamic"
|
||||
+82
-11
@@ -11,7 +11,7 @@ The first release.
|
||||
- Tables for SQLite, Dolt and PostgreSQL, a team's store, and the SQLite bundle with full-text search.
|
||||
- The JSON-LD context for layers, and registries of formats, rules, download-stamp rules and default stage requirements.
|
||||
- Test vectors for every computed value, from canonical JSON to anchor resolution, grading and the target set of targeted F3.
|
||||
- Example packages (a converted chemistry paper with corrections and receipts, its checks-only export, an open-access paper, a Typst draft and a tiny document, also as a zip), a record of every other format, and 31 broken packages, each breaking one named rule.
|
||||
- Example packages (a converted chemistry paper with corrections and receipts, its checks-only export, an open-access paper, a Typst draft and a tiny document, also as a zip), a record of every other format, and 33 broken packages, each breaking one named rule.
|
||||
- Work keys minted from a Scholar-style citation key and a hash of the work's identity, with document keys for versions; `tag:` URIs for layers, annotations and documents.
|
||||
- Spot-check seeds as VRF proofs (RFC 9381), RFC 9162 inclusion and consistency proofs, a history root over every document's corrections, and a provisional transparency log with signed checkpoints.
|
||||
- Signed QA reports, a conformance checklist covered by a receipt, and a `description` annotation for the figure descriptions an accessible export needs.
|
||||
@@ -38,14 +38,14 @@ Packaging, commands and lazy imports only; the formats stay at 0.1.0, and no com
|
||||
|
||||
### Unreleased
|
||||
|
||||
Two changes asked for by the first producer that compares a converted reading with a second witness (paperform with a JATS file).
|
||||
Two changes asked for by the first producer that compares a converted reading with a second witness (PaperForms with a JATS file).
|
||||
Both are minor changes in the sense of [spec/00](spec/00-introduction.md): no valid file becomes invalid, and no hash, ID or key changes; the next release numbers them.
|
||||
|
||||
- Alignment has a substitution step ([spec/05 §5.6](spec/05-hashes.md#56-alignment), step 3): in each stretch between pairs, an unpaired sentence of the first reading is paired with the first unpaired sentence of the second whose similarity (2*L* / (|*a*| + |*b*|) over code points of the lossy projections, *L* their longest common subsequence) is at least 0.8, both of prose length 20 or more.
|
||||
A sentence one reading misread is now one `number`, `equation` or `word` suspect rather than a `dropped` and an `added` one, so a producer re-aligning the same two readings can get different suspects than before; the pairs and suspects of readings with no such sentence are unchanged, as the first alignment vector is.
|
||||
`paperspec.align` gains `lcs_length` (bit-parallel, Hyyrö 2004) and `similarity`, and `alignment.jsonl` a second case, `substitutions`: a misread number, a misread word, a sentence too short to be paired this way and two sentences too unlike to be one.
|
||||
- A suspect may name the witness its second reading came from (`witness`, a witness ID; [spec/05 §5.7](spec/05-hashes.md#57-suspects), `suspect.schema.json`), and a package whose suspect names a witness it does not have breaks `doc.suspect.witness`.
|
||||
No broken package exercises the rule yet: adding one changes the count of broken packages that the 0.1.0 entry above states, so it waits for the release.
|
||||
`fixtures/invalid/suspect-witness/` exercises the rule (see the last section).
|
||||
|
||||
Four more, asked for by editors who correct and discuss papers rather than readings.
|
||||
They are minor changes too: new operations, enumeration values and optional properties, with no valid file made invalid, no value of an existing file computed differently, and no existing vector case or package changed.
|
||||
@@ -62,7 +62,7 @@ They are minor changes too: new operations, enumeration values and optional prop
|
||||
- The rules `correction.emend`, `correction.relink`, `correction.resolve` and `doc.correction.resolution` are registered, the `corrections` table's CHECK takes the three operations ([sql/doc.sql](sql/doc.sql)), `corrections.State` carries the reference records, and `paperspec stress` walks the three operations with their invariants.
|
||||
`corrections.jsonl` gains thirteen cases and `projections.jsonl` and `projection-groups.jsonl` two each; no existing case changes.
|
||||
|
||||
Four more, asked for by papermath, which defines the math form `scienting-math/1`, and by paperclaim, the claim store whose claims and symbols layers point at.
|
||||
Four more, asked for by PaperMath, which defines the math form `scienting-math/1`, and by PaperClaim, the claim store whose claims and symbols layers point at.
|
||||
The first two are minor changes: an optional property, a derived file and its schema, with no hash, ID or key of an existing file changed.
|
||||
The last two make some files that were valid invalid, which [spec/00](spec/00-introduction.md) calls breaking; they are made now because no release of `scienting-doc/1` or `scienting-layer/1` has been tagged, and a reference worth changing is changed before one is ([CONTRIBUTING.md](CONTRIBUTING.md#releasing), item 4).
|
||||
|
||||
@@ -70,15 +70,15 @@ The last two make some files that were valid invalid, which [spec/00](spec/00-in
|
||||
A consumer may rely on the source being canonical and idempotent, carrying no label, and on everything else being derived from it.
|
||||
`form` enters no content value ([spec/05 §5.2](spec/05-hashes.md#52-own-content)): own content leaves it out of math runs (`paperspec.hashing`), an equation's own content never held more than its notation and source, and no projection reads it, so adding `form` to a source already in the form changes no hash, ID or anchor, while respelling a source changes it as any edit does.
|
||||
Because a complex formula's key compares sources, a producer aligning a reading in a form with another reading respells the other's math first.
|
||||
`hashes.jsonl` gains a case, `math-form`, whose values `paperspec check` also computes without `form`; the rule `doc.math.form` is registered for validators that implement the form, which the reference validator does not.
|
||||
- `derived/math.jsonl` ([spec/12 §12.7](spec/12-package.md#127-derived-files), [spec/09 §9.4](spec/09-figures-tables-equations.md#94-the-math-form), `math.schema.json`): one line per formula, `{node, run, tool, form, tree, symbols, complete, issues, label?}`, papermath's reading without the canonical TeX, which is the source; `run` is null for an equation, as in `derived/mathml.jsonl`, and `label` is omitted when the source has no `\tag`.
|
||||
`hashes.jsonl` gains a case, `math-form`, whose values `paperspec check` also computes without `form`; the rule `doc.math.form` is registered for validators that implement the form, which the reference validator now does in part (see the last section).
|
||||
- `derived/math.jsonl` ([spec/12 §12.7](spec/12-package.md#127-derived-files), [spec/09 §9.4](spec/09-figures-tables-equations.md#94-the-math-form), `math.schema.json`): one line per formula, `{node, run, tool, form, tree, symbols, complete, issues, label?}`, PaperMath's reading without the canonical TeX, which is the source; `run` is null for an equation, as in `derived/mathml.jsonl`, and `label` is omitted when the source has no `\tag`.
|
||||
A tree node is an array whose first item is its kind; the schema takes any lowercase kind and issue code, so the form can add some in a minor version, and lists the 49 kinds and six codes of version 1.
|
||||
The validator now checks derived files: each line against its schema, that it names a formula of the package (`doc.derived.node`), that a math line's formula is TeX and its `complete` and `symbols` agree with its tree (`doc.derived.math`), and that a checks-only package carries none (`doc.policy.withheld`), since a tree or MathML reads the withheld text.
|
||||
The main example gains `derived/math.jsonl`, papermath 0.1.0's reading of its equation and of two math runs, copied by hand because the oracle does not implement the form; `paperspec check` validates fourteen variants of it, and no fixture's hashes change.
|
||||
The main example gains `derived/math.jsonl`, PaperMath 0.1.0's reading of its equation and of two math runs, copied by hand because the oracle does not implement the form; `paperspec check` validates fourteen variants of it, and no fixture's hashes change.
|
||||
There are now 43 schemas, which the 0.1.0 entry above, held to the repository by `paperspec check`, states too.
|
||||
- Claim references ([spec/18 §18.4](spec/18-layers.md#184-bodies), [spec/02 §2.4](spec/02-model.md#24-work-and-document-keys), [spec/20](spec/20-projects.md), `claimRef` and `claimPin` in `common.schema.json`): the `source` of a `claim-link` or `symbol` body, a `claim:` identifier in `same_as`, and a project's claim step are paperclaim references, `claim:<tag>` or `claim:<host>/<tag>` with the tag eight Crockford base32 capitals, and a `pin` is the reference, `@` and six lowercase hex digits of the claim's statement hash, as paperclaim writes them; a project names its claim namespace as `claims.paperclaim`.
|
||||
A reference by slug, such as `amber/k-bond`, which paperclaim may rename, or under any other prefix, was valid before and is not now.
|
||||
The fixtures' slug reference and `illustrative-pin` become `claim:272XTX7C` and `claim:272XTX7C@02f47b`, the claim `amber/k-bond` of paperclaim's example store, which changes the claim link's and the symbol's record IDs, the layer receipt and `project.json`.
|
||||
- Claim references ([spec/18 §18.4](spec/18-layers.md#184-bodies), [spec/02 §2.4](spec/02-model.md#24-work-and-document-keys), [spec/20](spec/20-projects.md), `claimRef` and `claimPin` in `common.schema.json`): the `source` of a `claim-link` or `symbol` body, a `claim:` identifier in `same_as`, and a project's claim step are PaperClaim references, `claim:<tag>` or `claim:<host>/<tag>` with the tag eight Crockford base32 capitals, and a `pin` is the reference, `@` and six lowercase hex digits of the claim's statement hash, as PaperClaim writes them; a project names its claim namespace as `claims.paperclaim`.
|
||||
A reference by slug, such as `amber/k-bond`, which PaperClaim may rename, or under any other prefix, was valid before and is not now.
|
||||
The fixtures' slug reference and `illustrative-pin` become `claim:272XTX7C` and `claim:272XTX7C@02f47b`, the claim `amber/k-bond` of PaperClaim's example store, which changes the claim link's and the symbol's record IDs, the layer receipt and `project.json`.
|
||||
The main example's two targeted receipts take the scope `targeted:paperclaim`, which changes their IDs and signatures, Ben's spot-check of the second (its seed and its sample of ten, still without errors), the QA report, the inclusion proof, the transparency log's checkpoint and tiles, and the signature, spot-check, VRF and checkpoint vectors built from them; no node's level or the report's counts change.
|
||||
- Symbol keys ([spec/18 §18.4](spec/18-layers.md#184-bodies), `annotation.schema.json`, the `key` term of the JSON-LD context, `sct:symbolKey`): a `symbol` body names its symbol by `key`, its `scienting-math/1` key, besides the span its target selects, so a symbol is found across papers and matched to its claim by key; a `symbol` body without `key` was valid before and is not now.
|
||||
The example layer gains a proposed symbol annotation on `$K_r$`, with the key `K_{r}`.
|
||||
@@ -88,7 +88,7 @@ The last two make some files that were valid invalid, which [spec/00](spec/00-in
|
||||
The third was the stress harness's own: a truncation could cut a file at its full length, leaving the package unchanged and valid, so it now always shortens the file.
|
||||
So was a fourth, with 1000 rounds: the random walk of corrections could delete the body section, leaving nothing to correct and too few corrections accepted, so a delete now leaves at least eight nodes.
|
||||
|
||||
One more, asked for by paperdesk, which lets a reader follow a citation to the passage it rests on.
|
||||
One more, asked for by PaperDesk, which lets a reader follow a citation to the passage it rests on.
|
||||
It is a minor change in the sense of [spec/00](spec/00-introduction.md): a new body kind, optional properties and two rules, with no valid file made invalid, no computed value changed and no existing vector case or package changed.
|
||||
|
||||
- Traced citations ([spec/18 §18.5](spec/18-layers.md#185-traced-citations), `annotation.schema.json`, the `note` and `proposer` terms of the JSON-LD context): a `trace` body follows one citation of a sentence of a citing paper to a passage of the cited paper.
|
||||
@@ -102,3 +102,74 @@ It is a minor change in the sense of [spec/00](spec/00-introduction.md): a new b
|
||||
- `fixtures/records/traces/` is a second layer, on the Typst draft, with a model's confirmed trace to the main example's abstract and its receipt, a rejected candidate, a person's trace to Table 1 and a reply that disputes the first, and `vectors/traces.jsonl` has 29 cases that correct either paper and show every outcome and both rules.
|
||||
`paperspec check` runs both layers through the record checks and the store.
|
||||
The example project holds the new layer, which changes `project.json`; no other fixture changes.
|
||||
|
||||
One more, asked for by PaperChem and PaperBio, which tie molecules and sequences to the words of a paper.
|
||||
It is a minor change in the sense of [spec/00](spec/00-introduction.md): two new body kinds, optional properties and seven rules, with no valid file made invalid and no computed value changed; the example layers, the traces and every receipt are as they were.
|
||||
|
||||
- Chemical structures ([spec/18 §18.6](spec/18-layers.md#186-chemical-structures), `annotation.schema.json`): a `structure` body ties a SMILES or SMARTS to a span, with a `role` (`names`, `depicts`, `parametrizes` or `uses`), an `identity` that finds the same structure however it was written (the InChIKey of a SMILES, else `smiles:` or `smarts:` and twelve hex digits of the SHA-256 of the value), the paper's own `written` notation, a `label`, outside `accessions` and `terms`: the bonds, angles, torsions and impropers a paper gives constants for.
|
||||
A group, a fragment with open positions (`R-OH` is `[*:1]-[OX2H]`) and a pattern of atom types are SMARTS, and SMILES text a toolkit would refuse is kept as one rather than dropped.
|
||||
A term cites atoms by number, from 0 in the order the value writes them and with no number for a hydrogen that is not written, so the numbers are a rule of the text and a producer needs no toolkit to check them.
|
||||
- Sequences ([spec/18 §18.7](spec/18-layers.md#187-sequences), `annotation.schema.json`): a `sequence` body ties protein, DNA or RNA residues to a span, with an `alphabet`, a `role` (`names`, `depicts`, `uses` or `reports`), an `identity` (the alphabet and sixteen hex digits of the SHA-256 of the residues without gaps), a `start` so a fragment is numbered as the whole molecule is, a `label`, an `organism`, `accessions`, `regions` and `variants`.
|
||||
The schema holds each alphabet's letters; a stop (`*`) belongs to protein only.
|
||||
- `paperspec.structures` and `paperspec.sequences` and the rules `layer.structure.value`, `layer.structure.identity`, `layer.structure.term`, `layer.sequence.value`, `layer.sequence.identity`, `layer.sequence.region` and `layer.sequence.variant` ([spec/22 §22.4](spec/22-conformance.md#224-rules)).
|
||||
`structures.scan` reads the atoms and bonds of a SMILES or SMARTS with the standard library, so a term's atoms are checked to exist and to be joined as the kind needs (a chain for a bond, angle or torsion, a star for an improper); it gave RDKit's atom count and bonds for a corpus of fifty-five SMILES and SMARTS and for three thousand random SMILES, and refused the malformed texts RDKit refuses.
|
||||
Valence, aromaticity and the InChIKey need a toolkit, which a producer SHOULD use for them.
|
||||
- `body_kind` of the store's `annotations` table takes `structure` and `sequence` ([sql/store.sql](sql/store.sql)).
|
||||
A store made before this change has the old CHECK, so a consumer migrates it by rebuilding the table; the table's columns do not change.
|
||||
- The JSON-LD context gains nine terms: `identity`, `written`, `alphabet`, `organism`, `start`, and `accessions`, `terms` (as `sct:structureTerms`), `regions` and `variants` as JSON literals.
|
||||
- `fixtures/records/chemistry/`, on the main example, and `fixtures/records/biology/`, on the draft, with `vectors/structures.jsonl` (64 cases) and `vectors/sequences.jsonl` (31): scans, identities, annotations that break no rule and one that breaks each.
|
||||
The example project holds the two layers, which changes `project.json`.
|
||||
The draft gains a last sentence, which the biology layer is about, so the draft package, its draft IDs and the one traces vector that anchors its paragraph change; the traces layer's anchors, its receipt and every other vector are as they were.
|
||||
- The prose check's UK spelling pattern no longer takes `organism` for a form of `organise`.
|
||||
|
||||
One more, asked for by PaperData, which finds data by its kind and by the molecules and sequences it is about.
|
||||
It is a minor change in the sense of [spec/00](spec/00-introduction.md): one new body kind, optional properties and four rules, with no valid file made invalid and no computed value changed; the other layers, the traces and every receipt are as they were.
|
||||
|
||||
- Data ([spec/18 §18.8](spec/18-layers.md#188-data), `annotation.schema.json`): a `data` body says what kind of data a span presents, with a `data_type` from a fixed list of fifteen, a `role` (`reports` or `uses`), the `dataset` that holds the values, the `quantities` its fields measure (a field, a name and the dataset's unit), the `subjects` it is about (the identities of `structure` and `sequence` bodies), a `method`, a `label` and outside `accessions`, so that a term of an ontology can say more than the list does.
|
||||
A dataset's `origin` already says whether its values were reported, digitized, computed or measured, so the body does not.
|
||||
- `paperspec.data` and the rules `layer.data.type`, `layer.data.quantity`, `layer.data.subject` and `layer.data.dataset` ([spec/22 §22.4](spec/22-conformance.md#224-rules)).
|
||||
`data.problems` compares a quantity's unit with its dataset's as a string and parses no unit; a producer with a unit library SHOULD also check that each unit parses and has the dimension its quantity needs.
|
||||
- `body_kind` of the store's `annotations` table takes `data` ([sql/store.sql](sql/store.sql)).
|
||||
A store made before this change has the old CHECK, so a consumer migrates it by rebuilding the table; the table's columns do not change.
|
||||
- The JSON-LD context gains five terms: `data_type`, `dataset`, `method`, and `quantities` and `subjects` as JSON literals.
|
||||
- `fixtures/records/data/`, on the main example, with `vectors/data.jsonl` (35 cases): a valid case for each kind of data, annotations that break no rule and one or more that break each.
|
||||
The layer ties the caption of Table 1 to its dataset as force-field parameters for ethane, water and the CT–CT pattern, the caption of Figure 1a to the dataset read from it as an energy profile of ethane, and the sentence that introduces Table 1 to the same dataset as a model's proposal.
|
||||
The example project holds the layer, which changes `project.json`; no other fixture or vector changes.
|
||||
|
||||
Tooling and code quality only; no computed value, vector, fixture, schema or SQL file changes.
|
||||
|
||||
- The Python code meets Scienting's standard: `ruff format`, `ruff check` with the full rule set, and `ty check` pass on `src/paperspec`, every function is annotated and documented, and `tests/` holds a pytest suite, driven by the vectors and fixtures, with branch coverage that fails under 90%.
|
||||
`paperspec check` (with the byte-for-byte rebuild) and `paperspec stress` give the same results as before.
|
||||
- Fixed: `structures.scan` raised an unrelated `ValueError` ("unsupported format character") for a malformed ring closure such as `C%1`, because its message was an invalid format string; the message is now "% needs two digits at N".
|
||||
- Fixed: `paperspec site --out /` passed the check that the output folder does not contain the repository and went on to delete the folder it was given; it is now refused as a usage error.
|
||||
A site built into a folder inside the checkout also no longer copies that folder's subfolders into itself.
|
||||
- Fixed: `receipts.verify_signature`, documented never to raise, raised `KeyError` for a record without a `format`; it now returns false.
|
||||
- Fixed: `traces.DOC_TAG` matched a document tag followed by a line feed, because it ended in `$`; it now ends at the end of the string.
|
||||
- Fixed: `paperspec load` and `paperspec check` left their SQLite connections open; they now close them.
|
||||
- The pixi tasks follow the standard (`fmt`, `fmt-check`, `lint` for ruff, `typecheck`, `test`, `cov`, `hooks`); the Markdown lint is `lint-md`, `paperspec check` is also `verify`, and `check` runs them all.
|
||||
The build environment is `release` (was `dev`), and `docs` builds the package documentation.
|
||||
- The package documentation, for the Python package and its command, is built with Zensical from `docs/package/` and published at <https://docs.scient.ing/paperspec/>; the format documentation stays in `docs/` and on <https://paperspec.scient.ing>.
|
||||
- The repository lives in the Gitea organization `papers`: the repository and registry addresses change from `infra` to `papers`.
|
||||
- The publish workflow also creates the Gitea release, with the files attached and the notes taken from this changelog; CI runs Scienting's checks (`.gitea/workflows/ci.yml`) on `main`, `dev` and pull requests.
|
||||
- Python files open with an `SPDX-License-Identifier: Apache-2.0` header, which ruff and a test check.
|
||||
- The checker and the site builder skip `work/`, caches and build output.
|
||||
|
||||
One more, the work the other paper tools planned for PaperSpec (PaperDesk's plan, item M5.4, and PaperForms's, §4.2): a command that applies corrections, two checks the validator had left to producers, and public names for what the tools had been importing as private ones.
|
||||
It is a minor change in the sense of [spec/00](spec/00-introduction.md): new rules, functions and a command, with no fixture package made invalid and no computed value changed.
|
||||
|
||||
- `paperspec correct` and `paperspec.revision` apply proposed corrections to a package, a folder or a zip, through the gate ([spec/11](spec/11-corrections.md)), and write the package they make, in place or to `--out`, only once it validates.
|
||||
A changed leaf becomes F1 when a crop of it is the evidence and F0 otherwise ([spec/08 §8.1](spec/08-fidelity.md#81-levels-of-fidelity)), and an `emend`, `relink` or `resolve` keeps its level.
|
||||
A retired node's locations move to its successor, suspects at removed nodes and those named by `--answered` are dropped, derived lines and datasets that read the corrected text are left out and reported, and provenance gains a `review` stage.
|
||||
With no corrections it writes every example package and every valid package of PaperForms's bench back byte for byte (`test_revision.py`, `test_cli_correct.py`).
|
||||
- `doc.math.form` is checked ([spec/03 §3.7](spec/03-nodes.md#37-math-forms)).
|
||||
The validator refuses a source in the form that holds a label or style command the form never holds, such as `\tag`, `\label`, `\nonumber`, `\displaystyle` or `\dfrac`.
|
||||
When PaperMath is installed, or a caller passes `forms=`, it also refuses a source that is not the form's own spelling or that the form cannot read (`test_math_form.py`).
|
||||
- The validator checks a package's datasets ([spec/15](spec/15-datasets.md), `paperspec.datasets`): the descriptor against its schema, the folder named by the ID, a unique primary key, each value anchor resolving as current to the text the CSV holds, and every numeric value of a reported resource anchored.
|
||||
These are the rules `doc.dataset.schema`, `.id`, `.file`, `.key`, `.anchor`, `.value` and `.unanchored` (`test_datasets.py`).
|
||||
- `fixtures/invalid/` gains `suspect-witness` and `math-form-label`, so there are 33 broken packages, which the 0.1.0 entry above states too (`paperspec check`).
|
||||
- Canonical JSON reads numbers as doubles, so `1e20` is read back as it was written (`test_jcs.py`).
|
||||
- The registries and the JSON-LD context ship in the wheel as `paperspec.registry` and `paperspec.context`, with `paperspec.resources.registry` and `paperspec.fingerprint.published_rules` for the download-stamp rules (`test_resources.py`, `test_fingerprint.py`).
|
||||
- Public names, with the old private names kept as aliases: `package.parse_canonical`, `parse_json`, `parse_jsonl`, `check_zip_entries` and `read_zip_files`; `tree.flatten` and `establish_with_side`, which keeps a producer's private keys; `hashing.strict_runs`; and `corrections.OPS` and `EMEND_KINDS` (`test_public_api.py`).
|
||||
Also `anchors.follow` and `resolve_address`, `claims.parse_ref`, `parse_pin`, `format_ref` and `format_pin`, `layers.annotation_id`, `anchors_of` and the lists of body kinds, categories, verdicts and statuses, and `db.load_layer`, `read_state`, `delete` and `upgrade` (`test_anchors.py`, `test_claims.py`, `test_layers.py`, `test_db.py`).
|
||||
- `text.collapse_ws`, `trim`, `remove_ws` and `digits` and `hashing.lossy_from_strict` are rewritten for speed, so a correction goes through the gate about three times faster, and are tested equal to the old code on every code point (`test_text.py`, `test_hashing.py`).
|
||||
- The private aliases kept for the siblings are gone, now that PaperDesk and PaperForms use the public names: `package._canonical_bytes`, `package._zip_entries`, `anchors._follow` and `traces._anchors` (`tests/test_public_api.py::test_parse_canonical_reads_doubles_and_refuses_what_is_not_canonical`, `::test_check_zip_entries_returns_the_folder_without_reading`, `tests/test_anchors.py::TestFollow::test_follow_has_no_alias_under_its_old_private_name`).
|
||||
+13
-5
@@ -1,7 +1,7 @@
|
||||
# Contributing
|
||||
|
||||
This page is for anyone who wants to fix the specification, change a format or add an example.
|
||||
Propose a change as a pull request on the repository at <https://git.scient.ing/infra/paperspec>.
|
||||
Propose a change as a pull request on the repository at <https://git.scient.ing/papers/paperspec>.
|
||||
|
||||
## What a change needs
|
||||
|
||||
@@ -16,10 +16,18 @@ The schemas, SQL, registries, vectors and fixtures then follow the chapter ([spe
|
||||
Change the oracle in [src/paperspec/](src/paperspec/) to apply the rule, and add the case that shows it to [src/paperspec/cli/build.py](src/paperspec/cli/build.py): a vector, a fixture or a broken package in `fixtures/invalid/`.
|
||||
Then run `pixi run build`, which rewrites `fixtures/` and `vectors/`.
|
||||
4. **Run the checks.**
|
||||
`pixi run check` must end with `All checks pass.`
|
||||
Without pixi, install the checkout with `pip install -e ".[tools]"` on Python 3.14, then run `paperspec check`.
|
||||
`pixi run check` must pass and end with `All checks pass.`
|
||||
Without pixi, install the checkout with `pip install -e ".[tools]" --group dev` on Python 3.14, then run `paperspec check` and the commands in [How the checks run](#how-the-checks-run).
|
||||
5. **Record the change** in [CHANGELOG.md](CHANGELOG.md).
|
||||
|
||||
## How the checks run
|
||||
|
||||
The Python code follows Scienting's standard: ruff formats and lints it with `.ruff.toml`, ty checks its types with `ty.toml`, and pytest tests it with `.pytest.ini` and `.coveragerc`.
|
||||
`pixi run check` runs, in order, `fmt-check` (ruff format), `lint` (ruff check), `typecheck` (ty), `lint-md` (markdownlint), `test` (pytest) and `verify` (`paperspec check`, the repository's own checker).
|
||||
`pixi run fmt` and `pixi run lint-fix` apply the formatter and the safe lint fixes, and `pixi run hooks` installs the git hooks that run the same tools before each commit.
|
||||
The tests in `tests/` take their data from the vectors and fixtures, so a rule change that a vector or a fixture covers shows up in both the suite and `paperspec check`.
|
||||
CI runs `fmt-check`, `lint`, `typecheck` and `cov` (the suite with branch coverage, which fails under 90%), then `lint-md`, `verify` and `stress`.
|
||||
|
||||
## Versions
|
||||
|
||||
A change that makes a valid file invalid, or that changes a computed value, is a breaking change and needs a new major version of the format, with a migration.
|
||||
@@ -40,7 +48,7 @@ A release that changes only the code takes the next patch version and records it
|
||||
Pushing the tag publishes the package to the Gitea package registry ([deploy/](deploy/README.md#publish-the-python-package)).
|
||||
Before tagging:
|
||||
|
||||
1. `pixi run check` passes on Linux and macOS, which the workflow in `.gitea/workflows/` runs on every push.
|
||||
1. `pixi run check` passes, on macOS as well as on Linux, where the workflow `.gitea/workflows/ci.yml` runs the checks on every push to `main` and `dev` and on every pull request.
|
||||
The check also confirms that every count the prose states (formats, schemas, vectors, broken packages) matches the repository, and that `pixi.toml`, the registries and `src/paperspec/cli/build.py` state the same version.
|
||||
2. `paperspec stress` passes with its default seed, and with one or two others.
|
||||
3. The website is published from the release ([deploy/](deploy/README.md)), and the JSON-LD context at `https://paperspec.scient.ing/context/scienting-1.jsonld` and a schema at its `$id` both answer with their media types.
|
||||
@@ -51,7 +59,7 @@ Before tagging:
|
||||
## Writing
|
||||
|
||||
The checker enforces two rules on every Markdown file: one sentence per line, and US spelling.
|
||||
`pixi run lint` runs markdownlint with the repository's settings.
|
||||
`pixi run lint-md` runs markdownlint with the repository's settings.
|
||||
Define each term where it first appears, because the guides and READMEs are written for newcomers as well as implementers.
|
||||
|
||||
All fixture text is synthetic, written for the fixtures.
|
||||
|
||||
+4
-2
@@ -4,14 +4,16 @@
|
||||
| --- | --- | --- |
|
||||
| `spec/`, `docs/`, `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md` and the other prose | Creative Commons Attribution 4.0 International | `CC-BY-4.0` |
|
||||
| `schemas/`, `sql/`, `context/`, `registry/`, `vectors/`, `fixtures/` | Creative Commons Zero 1.0 Universal | `CC0-1.0` |
|
||||
| `src/` (the `paperspec` package and its commands), `tools/` | Apache License 2.0 | `Apache-2.0` |
|
||||
| `src/` (the `paperspec` package and its commands), `tests/`, `tools/` | Apache License 2.0 | `Apache-2.0` |
|
||||
|
||||
The legal texts are at <https://creativecommons.org/licenses/by/4.0/legalcode>, <https://creativecommons.org/publicdomain/zero/1.0/legalcode> and <https://www.apache.org/licenses/LICENSE-2.0>.
|
||||
|
||||
Source Code: <https://git.scient.ing/papers/paperspec>
|
||||
|
||||
The formats are open so that anyone may implement them, in any product, without asking.
|
||||
|
||||
All text in the fixtures is synthetic, written for them.
|
||||
License fields inside fixtures describe fictional works, not the fixtures.
|
||||
The keys in `fixtures/keys/` are public test keys and must never sign anything else.
|
||||
|
||||
Copyright 2026 the Scientific Computing Studio.
|
||||
Copyright 2026 Scienting.
|
||||
@@ -1,4 +1,4 @@
|
||||
# paperspec
|
||||
# PaperSpec
|
||||
|
||||
**The data formats for storing a team's scientific papers once, correcting them once, addressing them down to the sentence, and keeping them.**
|
||||
|
||||
@@ -6,7 +6,7 @@ This page is for three readers.
|
||||
A newcomer should read straight through; each term is explained where it first appears.
|
||||
The tables below point an implementer, who will write a reader, writer, converter or checker, to the chapters, test vectors and fixtures that define exact behavior.
|
||||
The sections on status and on differences give an expert in the neighboring standards the version, the maturity of each format and the comparison.
|
||||
The documentation and every file of the specification are published at <https://paperspec.scient.ing>, and the repository is at <https://git.scient.ing/infra/paperspec>.
|
||||
The specification and every file of the formats are published at <https://paperspec.scient.ing>, the documentation of the Python package is at <https://docs.scient.ing/paperspec/>, and the repository is at <https://git.scient.ing/papers/paperspec>.
|
||||
|
||||
A research team usually cares about a few dozen papers it understands completely, not the world's literature.
|
||||
Those papers deserve better than a folder of PDFs.
|
||||
@@ -37,19 +37,6 @@ If a different converter reads the paper, each sentence it reads identically kee
|
||||
Nothing changes until a correction with its evidence is accepted ([spec/04](spec/04-identity.md), [spec/05 §5.6](spec/05-hashes.md#56-alignment)).
|
||||
The address grammar is in [spec/06 §6.1](spec/06-anchors.md#61-addresses), and [vectors/addresses.jsonl](vectors/addresses.jsonl) holds valid and invalid examples.
|
||||
|
||||
## Start here
|
||||
|
||||
| If you want to | Read |
|
||||
| --- | --- |
|
||||
| Understand what the project is and how the parts fit | [docs/overview.md](docs/overview.md) |
|
||||
| Learn the ideas one at a time, each with an example | [docs/concepts.md](docs/concepts.md) |
|
||||
| Follow one paper from its first reading to a signed document | [docs/walkthrough.md](docs/walkthrough.md) |
|
||||
| Run something in the next five minutes | [docs/examples.md](docs/examples.md) |
|
||||
| Implement a reader or writer | [spec/](spec/README.md), then [vectors/](vectors/README.md) |
|
||||
| Know why a rule is the way it is | [docs/rationale.md](docs/rationale.md) |
|
||||
| Look up a term | [docs/glossary.md](docs/glossary.md) |
|
||||
| Compare with neighboring standards | [docs/comparison.md](docs/comparison.md) |
|
||||
|
||||
## What is in the repository
|
||||
|
||||
| Folder | Holds |
|
||||
@@ -63,36 +50,104 @@ The address grammar is in [spec/06 §6.1](spec/06-anchors.md#61-addresses), and
|
||||
| [fixtures/](fixtures/README.md) | Example packages and records, deliberately broken packages, and the test keys that signed them. |
|
||||
| [tools/](tools/README.md) | How to run the commands that build and check everything above. |
|
||||
| [src/paperspec/](src/paperspec/) | The reference implementation of every rule and those commands, installable as the Python package `paperspec`. |
|
||||
| [docs/](docs/README.md) | Guides for people getting to know the project. |
|
||||
| [deploy/](deploy/README.md) | How the website at <https://paperspec.scient.ing> is built and served. |
|
||||
| [tests/](tests/) | The pytest suite for the reference implementation, which takes its data from the vectors and fixtures. |
|
||||
| [docs/](docs/README.md) | Guides to the formats for people getting to know the project, and the Python package's documentation in `docs/package/`. |
|
||||
| [deploy/](deploy/README.md) | How the website at <https://paperspec.scient.ing> is built and served, and how the package is published. |
|
||||
|
||||
## Try it
|
||||
## Installing
|
||||
|
||||
With [pixi](https://pixi.sh), one command sets up a pinned environment and checks everything:
|
||||
The formats need no installation: they are files.
|
||||
The Python package `paperspec` needs Python 3.14 and, for the `paperspec` command, the `tools` extra (`jsonschema`, `referencing` and `cryptography`).
|
||||
|
||||
### From Scienting's package registry
|
||||
|
||||
The registry does not mirror PyPI, so an installer needs two indexes: the registry for `paperspec`, and PyPI for the packages it depends on.
|
||||
Tie `paperspec` to the registry wherever the installer allows it, so that a package of the same name on PyPI is never chosen instead.
|
||||
`[CHECK: no version tag has been pushed, so the registry holds no release yet]`
|
||||
|
||||
With pixi, in `pixi.toml`:
|
||||
|
||||
```toml
|
||||
[pypi-dependencies]
|
||||
paperspec = { version = ">=0.1.1", extras = ["tools"], index = "https://git.scient.ing/api/packages/papers/pypi/simple" }
|
||||
```
|
||||
|
||||
With uv, in `pyproject.toml`:
|
||||
|
||||
```toml
|
||||
[[tool.uv.index]]
|
||||
name = "scienting"
|
||||
url = "https://git.scient.ing/api/packages/papers/pypi/simple"
|
||||
explicit = true
|
||||
|
||||
[tool.uv.sources]
|
||||
paperspec = { index = "scienting" }
|
||||
```
|
||||
|
||||
With pip, which cannot tie a package to an index and takes the highest version from either:
|
||||
|
||||
```sh
|
||||
pip install --index-url https://git.scient.ing/api/packages/papers/pypi/simple/ --extra-index-url https://pypi.org/simple/ "paperspec[tools]"
|
||||
```
|
||||
|
||||
[deploy/](deploy/README.md#install-from-the-registry) says what a private registry needs.
|
||||
|
||||
### From a checkout
|
||||
|
||||
```sh
|
||||
git clone https://git.scient.ing/papers/paperspec
|
||||
pixi install
|
||||
pixi run check
|
||||
```
|
||||
|
||||
Without pixi, install the checkout as the package with `pip install -e ".[tools]" --group dev` on Python 3.14, then run `paperspec check`.
|
||||
|
||||
## Quick start
|
||||
|
||||
With [pixi](https://pixi.sh), one command sets up a pinned environment and runs every check:
|
||||
|
||||
```sh
|
||||
pixi run check
|
||||
```
|
||||
|
||||
The checker validates every schema, record and package.
|
||||
It first checks the Python code: formatting and lint with ruff, types with ty, and the pytest suite.
|
||||
Then it lints the Markdown.
|
||||
Last it runs `paperspec check`, the repository's own checker, which you can also run alone with `pixi run verify`.
|
||||
That checker validates every schema, record and package.
|
||||
It confirms that every broken package is refused for the stated reason.
|
||||
It recomputes every test vector, and it rebuilds everything and compares it byte for byte.
|
||||
Last, it loads every package into SQLite and back, and checks the prose and the links.
|
||||
Pixi lints the Markdown first.
|
||||
It also loads every package into SQLite and back, and checks the prose and the links.
|
||||
The run ends with `All checks pass.`
|
||||
`pixi task list` shows the other tasks: `quick`, `build`, `lint`, `load`, `validate` and `stress`.
|
||||
`pixi run site` builds the website into `_site/` ([deploy/](deploy/README.md)).
|
||||
|
||||
The commands need Python 3.14 and the package's `tools` extra (`jsonschema`, `referencing` and `cryptography`), which pixi installs along with markdownlint for the Markdown.
|
||||
Without pixi, install the checkout as the package with `pip install -e ".[tools]"` on Python 3.14, then run `paperspec check`.
|
||||
`paperspec --help` lists the commands, and each command's `--help` gives advice and examples ([tools/](tools/README.md)).
|
||||
|
||||
To explore a worked package, load the example paper (a synthetic chemistry paper with 12 corrections) into SQLite and query it; [docs/examples.md](docs/examples.md) has queries to start from.
|
||||
To validate the example paper, a synthetic chemistry paper with 12 corrections, and load it into SQLite to query it:
|
||||
|
||||
```sh
|
||||
pixi run validate fixtures/packages/hale2026harmonic-damb
|
||||
pixi run load --sqlite lab.db fixtures/packages/hale2026harmonic-damb
|
||||
```
|
||||
|
||||
[docs/examples.md](docs/examples.md) has queries to start from.
|
||||
To correct a package, try the proposal with `paperspec validate --correction fix.json PACKAGE`, then apply it with `paperspec correct --correction fix.json PACKAGE`, which writes the corrected package.
|
||||
`paperspec --help` lists the commands, and each command's `--help` gives advice and examples ([tools/](tools/README.md)).
|
||||
`pixi run site` builds the website into `_site/` ([deploy/](deploy/README.md)).
|
||||
|
||||
## Documentation
|
||||
|
||||
The documentation of the Python package and its command is at <https://docs.scient.ing/paperspec/>: how to install it, guides for validating a package, loading it into SQLite, using the library and checking the repository, the command line and the modules.
|
||||
Its source is in `docs/package/`, and `pixi run docs-build` builds it.
|
||||
The guides to the formats are at <https://paperspec.scient.ing/docs/>:
|
||||
|
||||
| If you want to | Read |
|
||||
| --- | --- |
|
||||
| Understand what the project is and how the parts fit | [docs/overview.md](docs/overview.md) |
|
||||
| Learn the ideas one at a time, each with an example | [docs/concepts.md](docs/concepts.md) |
|
||||
| Follow one paper from its first reading to a signed document | [docs/walkthrough.md](docs/walkthrough.md) |
|
||||
| Run something in the next five minutes | [docs/examples.md](docs/examples.md) |
|
||||
| Implement a reader or writer | [spec/](spec/README.md), then [vectors/](vectors/README.md) |
|
||||
| Know why a rule is the way it is | [docs/rationale.md](docs/rationale.md) |
|
||||
| Look up a term | [docs/glossary.md](docs/glossary.md) |
|
||||
| Compare with neighboring standards | [docs/comparison.md](docs/comparison.md) |
|
||||
|
||||
## Format names
|
||||
|
||||
Every format is named `scienting-<name>/<major>`, such as `scienting-doc/1` or `scienting-anchor/1`.
|
||||
@@ -101,19 +156,6 @@ A format is named after what it holds, never after a product or a repository, an
|
||||
Schemas use the identifier base `https://paperspec.scient.ing/schemas/`.
|
||||
[registry/formats.json](registry/formats.json) lists every format with its media type, schema, status and chapter.
|
||||
|
||||
## Status and limits
|
||||
|
||||
This is version 0.1.0.
|
||||
Of the 32 formats, 19 are `candidate` and 13 are `provisional`.
|
||||
The `provisional` formats are project, bundle, dataset, digitization, view, snapshot, draft-ids, exercise, submission, grade, checklist, log-entry and checkpoint; where those are described, they are marked as such.
|
||||
The repository includes a reference checker, test vectors and fixtures.
|
||||
|
||||
The formats are built for a team-scale corpus of hundreds of documents, not hundreds of millions of papers.
|
||||
They do not replace publisher interchange formats.
|
||||
They do not fix what a converter reads wrongly; they record it and make it checkable.
|
||||
Not every addressable thing is a node with five hashes (the content values `text_hash`, `match_hash`, `align_key`, `own_hash` and `node_hash`, explained in [docs/concepts.md](docs/concepts.md)).
|
||||
Table columns and figure-text items have IDs and are not nodes ([spec/04 §4.2](spec/04-identity.md), [spec/09](spec/09-figures-tables-equations.md)).
|
||||
|
||||
## How it differs from neighboring standards
|
||||
|
||||
- JATS is the XML format in which publishers and archives exchange journal content ([NISO Z39.96-2024](https://www.niso.org/publications/z3996-2024-jats)).
|
||||
@@ -129,9 +171,67 @@ Table columns and figure-text items have IDs and are not nodes ([spec/04 §4.2](
|
||||
It identifies items by position in a list, such as `#/texts/12` ([schema](https://raw.githubusercontent.com/docling-project/docling-core/main/docs/DoclingDocument.json)).
|
||||
Here, IDs do not depend on position, and a second converter's reading is aligned with the first and compared.
|
||||
|
||||
## Development
|
||||
|
||||
The pixi tasks:
|
||||
|
||||
| Task | Does |
|
||||
| --- | --- |
|
||||
| `fmt`, `fmt-check` | Format the code with ruff, or check the formatting. |
|
||||
| `lint`, `lint-fix` | Lint with ruff, or lint and apply the safe fixes. |
|
||||
| `typecheck` | Type-check `src/` with ty. |
|
||||
| `test`, `cov` | Run the pytest suite, or run it with branch coverage that fails under 90%. |
|
||||
| `check` | Every check CI runs, then the repository's own checker (`verify`). |
|
||||
| `hooks` | Install the git pre-commit hooks. |
|
||||
| `docs-build`, `docs-serve` | Build the package documentation strictly into `build/docs`, or preview it. |
|
||||
| `dist` | Build the sdist and wheel into `dist/` (the `release` environment). |
|
||||
|
||||
Work happens on the `dev` branch.
|
||||
A release is a tag `vX.Y.Z` on the commit to release, and the package version is the tag, which setuptools-scm reads.
|
||||
Add the release's section to [CHANGELOG.md](CHANGELOG.md), tag the commit and push the tag; CI checks the repository, builds the package, confirms the built version is the tag's, publishes it to the package registry and creates the release ([CONTRIBUTING.md](CONTRIBUTING.md#releasing), [deploy/](deploy/README.md#publish-the-python-package)).
|
||||
|
||||
## Built with LLM assistance
|
||||
|
||||
Large language models (Anthropic's Claude, through Claude Code) write much of this code, its tests and its documentation.
|
||||
A person reviews every change, `pixi run check` gates it, and each assisted commit carries a `Co-Authored-By` trailer.
|
||||
|
||||
## Status and known limits
|
||||
|
||||
This is version 0.1.0.
|
||||
Of the 32 formats, 19 are `candidate` and 13 are `provisional`.
|
||||
The `provisional` formats are project, bundle, dataset, digitization, view, snapshot, draft-ids, exercise, submission, grade, checklist, log-entry and checkpoint; where those are described, they are marked as such.
|
||||
The repository includes a reference checker, test vectors and fixtures.
|
||||
|
||||
The formats are built for a team-scale corpus of hundreds of documents, not hundreds of millions of papers.
|
||||
They do not replace publisher interchange formats.
|
||||
They do not fix what a converter reads wrongly; they record it and make it checkable.
|
||||
Not every addressable thing is a node with five hashes (the content values `text_hash`, `match_hash`, `align_key`, `own_hash` and `node_hash`, explained in [docs/concepts.md](docs/concepts.md)).
|
||||
Table columns and figure-text items have IDs and are not nodes ([spec/04 §4.2](spec/04-identity.md), [spec/09](spec/09-figures-tables-equations.md)).
|
||||
|
||||
The Python package is an oracle, not a production reader or writer: it favors clarity over speed, and its VRF and ML-DSA-65 are written out in plain Python ([tools/](tools/README.md#about-the-oracle)).
|
||||
It needs Python 3.14, the only version with the Unicode 16.0 character data the specification pins, and refuses to import on any other.
|
||||
Only `paperspec validate`, `paperspec correct` and `paperspec load` work anywhere the package is installed; `check`, `build`, `stress` and `site` work on a checkout of this repository.
|
||||
`paperspec correct` cannot rebuild what pinned tools derived from the text: it leaves out the lines of `derived/` files and the datasets that read corrected text, and says which, for the tool that made them to rebuild.
|
||||
The validator checks the math form `scienting-math/1` in full only when PaperMath is installed; without it, it refuses only what the form never holds, such as a `\tag`.
|
||||
It accepts more than one location record for a node on one page, which [spec/07 §7.4](spec/07-geometry.md#74-locationsjsonl) rules out.
|
||||
|
||||
## Licenses
|
||||
|
||||
The specification and other prose are CC BY 4.0, so anyone may implement the formats.
|
||||
Schemas, SQL, the JSON-LD context, the registries, the vectors and the fixtures are CC0 1.0.
|
||||
The code, the `paperspec` package in `src/` with its commands, is Apache-2.0.
|
||||
The code, the `paperspec` package in `src/` with its commands and its tests, is Apache-2.0, and its Python files open with an SPDX header that says so.
|
||||
This repository does not use Scienting's usual Prosperity license, because the formats are meant to be implemented by anyone without asking.
|
||||
See [LICENSE.md](LICENSE.md).
|
||||
|
||||
## Credits
|
||||
|
||||
The reference implementation leaves the cryptography and the schema validation to established packages: [cryptography](https://cryptography.io) for Ed25519 and HKDF, and [jsonschema](https://python-jsonschema.dev) with [referencing](https://referencing.readthedocs.io) for JSON Schema.
|
||||
Canonical JSON follows [RFC 8785](https://www.rfc-editor.org/rfc/rfc8785).
|
||||
The verifiable random function follows [RFC 9381](https://www.rfc-editor.org/rfc/rfc9381), and ML-DSA-65 follows [FIPS 204](https://csrc.nist.gov/pubs/fips/204/final); both are checked against those standards' own test vectors.
|
||||
The annotation layers build on the [W3C Web Annotation Data Model](https://www.w3.org/TR/annotation-model/).
|
||||
[pixi](https://pixi.sh), [ruff](https://docs.astral.sh/ruff/), [ty](https://docs.astral.sh/ty/), [pytest](https://pytest.org) and [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) run the checks, and [Zensical](https://zensical.org) builds the package documentation.
|
||||
|
||||
## Contributing
|
||||
|
||||
Propose a change as a pull request; [CONTRIBUTING.md](CONTRIBUTING.md) says what a change needs, from the chapter to the vectors.
|
||||
`[CHECK: Scienting's contributor license agreement does not exist yet; CONTRIBUTING.md invites pull requests as it did before]`
|
||||
+23
-7
@@ -29,7 +29,7 @@ Every layer and every annotation lists both contexts, Web Annotation first:
|
||||
```
|
||||
|
||||
The `scienting-` prefix is the formats' namespace, as in `scienting-layer/1` and `scienting-anchor/1`.
|
||||
The repository's name, paperspec, is a separate matter.
|
||||
The repository's name, PaperSpec, is a separate matter.
|
||||
|
||||
## An example from the fixtures
|
||||
|
||||
@@ -57,14 +57,14 @@ This context defines `kind`, `status`, `audience`, `AnchorSelector` and `anchor`
|
||||
|
||||
## What it defines
|
||||
|
||||
The file defines 27 terms.
|
||||
Twenty-six map to IRIs under `https://paperspec.scient.ing/vocab#`: `format`, `kind`, `status`, `receipt`, `layer`, `audience`, `visibility`, `purpose`, `project`, `docs`, `pin`, `role`, `symbol`, `key`, `verdict`, `reason`, `reference`, `note`, `proposer`, `for`, `category`, `generator`, `exercise`, `anchor`, `rights_use` and the class `AnchorSelector`.
|
||||
Five are renamed: `key`, the key of a `symbol` body's symbol, is `sct:symbolKey`, `for` is `sct:questionFor`, `generator` is `sct:generatedBy`, `proposer`, the tool that found a trace, is `sct:proposedBy`, and `rights_use` is `sct:rightsUse`.
|
||||
The twenty-seventh, `total`, maps to `totalItems` in the ActivityStreams namespace.
|
||||
The file defines 41 terms.
|
||||
Forty map to IRIs under `https://paperspec.scient.ing/vocab#`: `format`, `kind`, `status`, `receipt`, `layer`, `audience`, `visibility`, `purpose`, `project`, `docs`, `pin`, `role`, `symbol`, `key`, `verdict`, `reason`, `reference`, `note`, `proposer`, `identity`, `written`, `alphabet`, `organism`, `start`, `accessions`, `terms`, `regions`, `variants`, `data_type`, `dataset`, `method`, `quantities`, `subjects`, `for`, `category`, `generator`, `exercise`, `anchor`, `rights_use` and the class `AnchorSelector`.
|
||||
Seven are renamed: `key`, the key of a `symbol` body's symbol, is `sct:symbolKey`, `for` is `sct:questionFor`, `generator` is `sct:generatedBy`, `proposer`, the tool that found a trace, is `sct:proposedBy`, `terms`, the force-field terms of a structure, is `sct:structureTerms`, `data_type`, the kind of data a `data` body names, is `sct:dataType`, and `rights_use` is `sct:rightsUse`.
|
||||
The forty-first, `total`, maps to `totalItems` in the ActivityStreams namespace.
|
||||
Two terms carry a type rule.
|
||||
A processor reads `layer` as an IRI, and it always reads `docs` as a set, so a one-element list stays a list.
|
||||
|
||||
The file declares `anchor`, `exercise` and `proposer` as JSON literals (`"@type": "@json"`, a JSON-LD 1.1 feature, which is why the file sets `"@version": 1.1`).
|
||||
The file declares `anchor`, `exercise`, `proposer`, `accessions`, `terms`, `regions`, `variants`, `quantities` and `subjects` as JSON literals (`"@type": "@json"`, a JSON-LD 1.1 feature, which is why the file sets `"@version": 1.1`).
|
||||
A JSON-LD processor then keeps a `scienting-anchor/1` record intact instead of expanding it.
|
||||
An anchor holds hashes (fixed-length fingerprints of text) and a `span`, a pair of character offsets whose order carries meaning.
|
||||
Expansion would drop the anchor's unmapped field names ([JSON-LD 1.1 API, expansion step 13.3](https://www.w3.org/TR/json-ld11-api/#alg-expand-each-key-value)) and would give its arrays no order ([JSON-LD 1.1 §4.3](https://www.w3.org/TR/json-ld11/#sets-and-lists)).
|
||||
@@ -97,6 +97,22 @@ A `trace` body ([spec/18 §18.5](../spec/18-layers.md#185-traced-citations)) fol
|
||||
The Web Annotation context defines `source` and `selector` for a body as it does for a target, so a trace's selector list puts the `AnchorSelector` first and the `TextQuoteSelector` after it, as a target's does.
|
||||
This context adds the rest of the body: `reference`, the reference of the draft that the sentence cites, `note`, `verdict` and `proposer`, which a processor keeps whole, as it keeps an anchor, because its model's hashes and its score are values and not terms.
|
||||
|
||||
## Bodies that hold a structure or a sequence
|
||||
|
||||
A `structure` body ([spec/18 §18.6](../spec/18-layers.md#186-chemical-structures)) ties a molecule, a group or a pattern to a span, and a `sequence` body ([§18.7](../spec/18-layers.md#187-sequences)) ties a protein, DNA or RNA sequence to one.
|
||||
Both are text bodies, so the Web Annotation context supplies `value` and this one adds the rest: `identity`, the key that finds the same structure or sequence however it was written, `written`, `alphabet`, `organism` and `start`.
|
||||
`accessions`, `terms`, `regions` and `variants` are lists of objects whose field names mean nothing outside their body, so the context declares them JSON literals, as it does an anchor, and a processor keeps them whole.
|
||||
`terms` maps to `sct:structureTerms`, because the word alone is too general for a vocabulary that other kinds of body may join.
|
||||
[`fixtures/records/chemistry/annotations.jsonl`](../fixtures/records/chemistry/annotations.jsonl) and [`fixtures/records/biology/annotations.jsonl`](../fixtures/records/biology/annotations.jsonl) hold four structures on the example paper and three sequences on the draft.
|
||||
|
||||
## Bodies that hold data
|
||||
|
||||
A `data` body ([spec/18 §18.8](../spec/18-layers.md#188-data)) says what kind of data a table, a figure panel or a passage presents and what it is about.
|
||||
It is a text body, so the Web Annotation context supplies `value`, and this one adds `data_type`, `dataset` and `method`.
|
||||
`data_type` maps to `sct:dataType`, as `rights_use` maps to `sct:rightsUse`.
|
||||
`quantities` and `subjects` are lists of objects, so the context declares them JSON literals, as it does `accessions`, and a processor keeps them whole.
|
||||
[`fixtures/records/data/annotations.jsonl`](../fixtures/records/data/annotations.jsonl) holds three on the example paper.
|
||||
|
||||
## Using the context
|
||||
|
||||
- Writer: Put both URLs (web addresses), in the order shown, in `@context` of `layer.json` and of every line of `annotations.jsonl`. [Chapter 18](../spec/18-layers.md) defines layers (§18.2), annotations (§18.3) and bodies (§18.4).
|
||||
@@ -104,7 +120,7 @@ This context adds the rest of the body: `reference`, the reference of the draft
|
||||
The file `vectors/resolve.jsonl` resolves seventeen anchors against `fixtures/packages/hale2026harmonic-damb` and gives every outcome.
|
||||
- JSON-LD processor: Use a JSON-LD 1.1 processor; the context relies on `@json` and `@version` 1.1.
|
||||
- Checker: `schemas/annotation.schema.json` and `schemas/layer.schema.json` validate the files.
|
||||
`paperspec check` also checks that each annotation's ID derives from its content and that the receipt of its layer, at `fixtures/records/layer/receipt.json` or `fixtures/records/traces/receipt.json`, covers each `confirmed` annotation.
|
||||
`paperspec check` also checks that each annotation's ID derives from its content and that the receipt of its layer, in the `receipt.json` beside `fixtures/records/layer/`, `traces/`, `chemistry/` or `biology/`, covers each `confirmed` annotation.
|
||||
|
||||
The traps:
|
||||
|
||||
|
||||
@@ -30,6 +30,38 @@
|
||||
"@id": "sct:proposedBy",
|
||||
"@type": "@json"
|
||||
},
|
||||
"identity": "sct:identity",
|
||||
"written": "sct:written",
|
||||
"alphabet": "sct:alphabet",
|
||||
"organism": "sct:organism",
|
||||
"start": "sct:start",
|
||||
"accessions": {
|
||||
"@id": "sct:accessions",
|
||||
"@type": "@json"
|
||||
},
|
||||
"terms": {
|
||||
"@id": "sct:structureTerms",
|
||||
"@type": "@json"
|
||||
},
|
||||
"regions": {
|
||||
"@id": "sct:regions",
|
||||
"@type": "@json"
|
||||
},
|
||||
"variants": {
|
||||
"@id": "sct:variants",
|
||||
"@type": "@json"
|
||||
},
|
||||
"data_type": "sct:dataType",
|
||||
"dataset": "sct:dataset",
|
||||
"method": "sct:method",
|
||||
"quantities": {
|
||||
"@id": "sct:quantities",
|
||||
"@type": "@json"
|
||||
},
|
||||
"subjects": {
|
||||
"@id": "sct:subjects",
|
||||
"@type": "@json"
|
||||
},
|
||||
"for": "sct:questionFor",
|
||||
"category": "sct:category",
|
||||
"generator": "sct:generatedBy",
|
||||
|
||||
+16
-8
@@ -1,6 +1,6 @@
|
||||
# Deploying the website and the Python package
|
||||
|
||||
This folder holds what it takes to serve the paperspec website at <https://paperspec.scient.ing>.
|
||||
This folder holds what it takes to serve the PaperSpec website at <https://paperspec.scient.ing>.
|
||||
The last sections say how the Python package `paperspec` is published to the Gitea package registry, and how other repositories install it from there.
|
||||
The site is static: `paperspec site` builds it into `_site/`, and any web server can serve that folder.
|
||||
|
||||
@@ -56,16 +56,16 @@ The environment in `.pixi/envs` is cached between runs under the hash of `pixi.l
|
||||
## Publish the Python package
|
||||
|
||||
The Python package `paperspec` holds the reference implementation and the `paperspec` command.
|
||||
The workflow `.gitea/workflows/publish.yml` publishes it to the PyPI registry of the Gitea instance, `https://git.scient.ing/api/packages/infra/pypi`, when a version tag such as `v0.1.1` is pushed.
|
||||
It checks the repository, builds the sdist and the wheel with `pixi run -e dev dist`, confirms that the version setuptools-scm computed is the tag's, checks the metadata with twine, and uploads both files.
|
||||
The workflow `.gitea/workflows/publish.yml` publishes it to the PyPI registry of the Gitea instance, `https://git.scient.ing/api/packages/papers/pypi`, when a version tag such as `v0.1.1` is pushed.
|
||||
It checks the repository with `pixi run check` (the code checks, the Markdown lint and `paperspec check`), builds the sdist and the wheel with `pixi run -e release dist`, confirms that the version setuptools-scm computed is the tag's, checks the metadata with twine, uploads both files, and creates the Gitea release with the files attached and the notes taken from the section of `CHANGELOG.md` whose heading contains the version.
|
||||
The package version is the version of this code; the formats keep the version that `CHANGELOG.md` and `pixi.toml` state.
|
||||
|
||||
### Set it up once
|
||||
|
||||
1. Pick the account the workflow publishes as, a bot account or your own, and make it a member of a team in the `infra` organization with write access to packages.
|
||||
1. Pick the account the workflow publishes as, a bot account or your own, and make it a member of a team in the `papers` organization with write access to packages.
|
||||
2. Signed in as that account, create an access token under Settings, Applications, with the `write:package` scope.
|
||||
3. In this repository's Settings, Actions, Secrets, add `PACKAGE_USER` with the account's user name and `PACKAGE_TOKEN` with the token.
|
||||
Organization secrets work as well, for every repository in `infra`.
|
||||
Organization secrets work as well, for every repository in `papers`.
|
||||
Gitea refuses secret names that start with `GITEA_` or `GITHUB_`.
|
||||
4. After the first upload, link the package to this repository in the package's settings, so it shows on the repository's Packages tab.
|
||||
|
||||
@@ -91,7 +91,7 @@ With pixi, in `pixi.toml`:
|
||||
|
||||
```toml
|
||||
[pypi-dependencies]
|
||||
paperspec = { version = ">=0.1.1", extras = ["tools"], index = "https://git.scient.ing/api/packages/infra/pypi/simple" }
|
||||
paperspec = { version = ">=0.1.1", extras = ["tools"], index = "https://git.scient.ing/api/packages/papers/pypi/simple" }
|
||||
```
|
||||
|
||||
With uv, in `pyproject.toml`:
|
||||
@@ -99,7 +99,7 @@ With uv, in `pyproject.toml`:
|
||||
```toml
|
||||
[[tool.uv.index]]
|
||||
name = "scienting"
|
||||
url = "https://git.scient.ing/api/packages/infra/pypi/simple"
|
||||
url = "https://git.scient.ing/api/packages/papers/pypi/simple"
|
||||
explicit = true
|
||||
|
||||
[tool.uv.sources]
|
||||
@@ -109,12 +109,20 @@ paperspec = { index = "scienting" }
|
||||
With pip, which cannot tie a package to an index and takes the highest version from either:
|
||||
|
||||
```sh
|
||||
pip install --index-url https://git.scient.ing/api/packages/infra/pypi/simple/ --extra-index-url https://pypi.org/simple/ "paperspec[tools]"
|
||||
pip install --index-url https://git.scient.ing/api/packages/papers/pypi/simple/ --extra-index-url https://pypi.org/simple/ "paperspec[tools]"
|
||||
```
|
||||
|
||||
If the organization or the package is private, the installer also needs a token with the `read:package` scope, for example in a `~/.netrc` entry for `git.scient.ing`.
|
||||
A git pin to a commit, as `pixi.toml` and `pyproject.toml` can also express, keeps working and needs no registry.
|
||||
|
||||
## Publish the package documentation
|
||||
|
||||
The pages for the Python package and its command are in `docs/package/` and are built with Zensical, separately from the format site above.
|
||||
The workflow `.gitea/workflows/docs.yml` builds them strictly with `pixi run -e docs docs-build` into `build/docs` on every push to `main` and `dev`, and on `main` copies them to `/srv/www/docs/paperspec`, which serves <https://docs.scient.ing/paperspec/>.
|
||||
A broken link, or a page missing from the navigation in `zensical.toml`, fails the build.
|
||||
The copy is local, like the site's: the runner mounts the host's `/srv/www`.
|
||||
Serving `/srv/www/docs` at `docs.scient.ing` is the same kind of Caddy entry as [Caddyfile](Caddyfile), and not part of this repository.
|
||||
|
||||
## Distributing document packages
|
||||
|
||||
A zipped package is an ordinary file, and the site serves the fixtures as such.
|
||||
|
||||
+4
-4
@@ -1,18 +1,18 @@
|
||||
# Guides
|
||||
|
||||
These guides explain paperspec to someone meeting it for the first time.
|
||||
These guides explain PaperSpec to someone meeting it for the first time.
|
||||
They serve three readers: a newcomer who has not seen the problem before, an implementer who will write a reader, writer, converter or checker, and an expert who knows the neighboring standards.
|
||||
The [specification](../spec/README.md) says exactly what each format is.
|
||||
The guides say what each format is for, with examples drawn from the fixtures.
|
||||
|
||||
| Guide | For |
|
||||
| --- | --- |
|
||||
| [Overview](overview.md) | What paperspec is, who it serves, and how its parts fit together. |
|
||||
| [Overview](overview.md) | What PaperSpec is, who it serves, and how its parts fit together. |
|
||||
| [Concepts](concepts.md) | The ideas behind the formats, one at a time, each with a real example. |
|
||||
| [Walkthrough](walkthrough.md) | One paper, from a flawed first reading to a corrected, reviewed and signed document. |
|
||||
| [Examples](examples.md) | Things to run: checking hashes by hand, reading a package with a few lines of Python, querying a database. |
|
||||
| [Rationale](rationale.md) | Why the formats look the way they do, and the questions they leave open. |
|
||||
| [Comparison](comparison.md) | How paperspec compares with JATS, TEI, W3C Web Annotation and other schemas. |
|
||||
| [Comparison](comparison.md) | How PaperSpec compares with JATS, TEI, W3C Web Annotation and other schemas. |
|
||||
| [*FAQ*](faq.md) | Short answers to the questions people ask first. |
|
||||
| [Glossary](glossary.md) | Every term, in a sentence. |
|
||||
|
||||
@@ -27,7 +27,7 @@ Next, run the section "Test your implementation against a vector" in the example
|
||||
Check your work against the [vectors](../vectors/README.md) and the [fixtures](../fixtures/README.md).
|
||||
Chapter 22 of the specification defines conformance.
|
||||
|
||||
**Expert.** Read the overview for scope and for what paperspec is not, then the comparison for how it differs from existing standards.
|
||||
**Expert.** Read the overview for scope and for what PaperSpec is not, then the comparison for how it differs from existing standards.
|
||||
After that, read the rationale for the reason behind each rule and the questions it leaves open.
|
||||
It ends with a list of limits.
|
||||
Section 0.4 of the specification and [registry/formats.json](../registry/formats.json) give the status of each format: the version is 0.1.0, and each format is `candidate` or `provisional`.
|
||||
+53
-53
@@ -1,16 +1,16 @@
|
||||
# How paperspec compares with other schemas and standards
|
||||
# How PaperSpec compares with other schemas and standards
|
||||
|
||||
A newcomer, such as a student who knows what a scientific paper and a citation are and has not met hashes, JSON-LD or annotation standards, can read each section's first paragraph and stop.
|
||||
An implementer, who will write a reader, writer, converter or checker, gets the chapter that defines each behavior and the places where the formats differ from a neighbor in ways that cause bugs.
|
||||
An expert, such as a researcher, standards author or reviewer who knows the neighboring standards, gets stated limits, the status of every format, and where the other standard is the better choice.
|
||||
|
||||
The repository is at <https://git.scient.ing/infra/paperspec>.
|
||||
The repository is at <https://git.scient.ing/papers/paperspec>.
|
||||
This page was checked against the repository, at the version given under "Limits and status".
|
||||
Every statement about another standard links to the page it was read on, and those pages were read on 2026-10-12, so versions and dates are as of that day and may have moved.
|
||||
Where the checked sources say nothing, this page says "not seen", "not specified" or "not in scope", and each phrase keeps one meaning: "not in scope" means the standard's own stated purpose excludes the feature, "not seen" means it was not found in the pages read (which is not proof it is absent), and "not specified" means the page read does not define it.
|
||||
|
||||
A note on names.
|
||||
The project is called paperspec.
|
||||
The project is called PaperSpec.
|
||||
Its formats are named `scienting-<name>/<major>`, for example `scienting-doc/1` and `scienting-anchor/1`.
|
||||
That prefix is the formats' namespace, and the repository's name is a separate matter; formats are named after what they hold, never after a product or a repository.
|
||||
The identifiers appear inside hashed data and test vectors, so they are not renamed.
|
||||
@@ -27,7 +27,7 @@ The pointer has four parts:
|
||||
- After `@`, the first six digits of the node's hash, `76e06b`, so the pointer names the sentence as it then read.
|
||||
- In brackets, the code-point range of the words inside the sentence, `[111:130]`.
|
||||
It also wants to know who compared a passage with the page image, and how far.
|
||||
That is the problem paperspec's formats solve: they store a paper as a package of files in which every sentence, table cell and equation has a permanent address and every correction is recorded with its evidence.
|
||||
That is the problem PaperSpec's formats solve: they store a paper as a package of files in which every sentence, table cell and equation has a permanent address and every correction is recorded with its evidence.
|
||||
Each level of checking is tied to the exact text it was checked against.
|
||||
|
||||
Most of the standards below solve different problems, so this page compares by problem solved, not by rank.
|
||||
@@ -47,11 +47,11 @@ The next table maps each job to the standard to start with and the section that
|
||||
| Linking into a PDF, text or web page | RFC 8118, Media Fragments, RFC 5147, Text Fragments | [Fragment identifiers](#fragment-identifiers-and-pandoc) |
|
||||
| Exchanging text-mining annotations, bibliographies, books | BioC, CSL-JSON, EPUB 3 | [BioC, CSL-JSON and EPUB 3](#bioc-csl-json-and-epub-3) |
|
||||
|
||||
## What paperspec is, in the terms used below
|
||||
## What PaperSpec is, in the terms used below
|
||||
|
||||
A few terms recur.
|
||||
A hash is a fixed-length fingerprint computed from content, so any change to the content changes the hash; paperspec uses SHA-256, written as 64 lowercase hexadecimal digits ([spec/01 §1.3](../spec/01-conventions.md#13-hashes)).
|
||||
Canonical JSON is a rule for writing JSON so that equal data always gives identical bytes, which is what makes a hash of JSON repeatable; paperspec uses the JSON Canonicalization Scheme of RFC 8785 ([spec/01 §1.1](../spec/01-conventions.md#11-canonical-json)).
|
||||
A hash is a fixed-length fingerprint computed from content, so any change to the content changes the hash; PaperSpec uses SHA-256, written as 64 lowercase hexadecimal digits ([spec/01 §1.3](../spec/01-conventions.md#13-hashes)).
|
||||
Canonical JSON is a rule for writing JSON so that equal data always gives identical bytes, which is what makes a hash of JSON repeatable; PaperSpec uses the JSON Canonicalization Scheme of RFC 8785 ([spec/01 §1.1](../spec/01-conventions.md#11-canonical-json)).
|
||||
A witness is one file of a paper, such as the publisher's PDF or a JATS XML file, identified by the SHA-256 of its bytes; a document is the text established from one or more witnesses ([spec/02 §2.1](../spec/02-model.md#21-four-objects)).
|
||||
A package is a folder of canonical JSON files, or the same folder zipped as `.sct.zip`, with a manifest that lists every other file with its SHA-256 and size ([spec/12](../spec/12-package.md)).
|
||||
|
||||
@@ -76,12 +76,12 @@ The design choices that matter for comparison:
|
||||
## Summary table
|
||||
|
||||
Each row summarizes the pages read for that standard.
|
||||
Cells keep the wording of the verified source; the paperspec row is checked against the repository.
|
||||
Cells keep the wording of the verified source; the PaperSpec row is checked against the repository.
|
||||
Maturity is left to the sections below, because a single word hides too much.
|
||||
|
||||
| Standard | Sentence-level permanent IDs | Content hashes | Anchors or selectors | Correction history | Fidelity or signatures | Per-file rights | Numeric data anchors | Full-text structure |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| **paperspec 0.1.0** | yes: 7-character IDs minted once, retired with a successor (spec/04) | yes: five SHA-256 values per node, plus keyed HMAC (hash-based message authentication code) forms (spec/05) | yes: ID, hash, quote, span, five outcomes with drift (spec/06) | yes: append-only, evidence-gated (spec/11) | yes: F0 to F3, signed receipts, spot-checks, error bounds (spec/08) | yes: per witness, with AI purpose and processor (spec/14) | yes: dataset values anchored to cells (spec/15; format `provisional`) | yes: sections to cells, equations, references (spec/03, 09) |
|
||||
| **PaperSpec 0.1.0** | yes: 7-character IDs minted once, retired with a successor (spec/04) | yes: five SHA-256 values per node, plus keyed HMAC (hash-based message authentication code) forms (spec/05) | yes: ID, hash, quote, span, five outcomes with drift (spec/06) | yes: append-only, evidence-gated (spec/11) | yes: F0 to F3, signed receipts, spot-checks, error bounds (spec/08) | yes: per witness, with AI purpose and processor (spec/14) | yes: dataset values anchored to cells (spec/15; format `provisional`) | yes: sections to cells, equations, references (spec/03, 09) |
|
||||
| [JATS standard page](https://www.niso.org/publications/z3996-2024-jats) (Z39.96-2024, v1.4) | not seen: no sentence element in the list shown | not seen | not in scope as an annotation model | not seen | not seen | partly: `permissions` and `license` elements exist | not seen | yes |
|
||||
| [TEI P5](https://tei-c.org/guidelines/P5/) (v4.12.0) | partly: `<s>` and author-assigned `xml:id` | not seen | partly: `xml:id` pointers, XPointer schemes | partly: `<corr>`, `<sic>`, `<choice>` | not seen | not seen | not seen | yes |
|
||||
| [GROBID TEI output](https://grobid.readthedocs.io/en/latest/Grobid-service/) | partly: optional sentence elements; IDs not described | not seen | partly: optional PDF coordinates | no | no; reports F1 figures | not in scope | not seen | partly: header, references, citation contexts, full text |
|
||||
@@ -126,12 +126,12 @@ JATS4R is a NISO working group that publishes tagging recommendations and a vali
|
||||
It models journal-article structure and metadata: sections, paragraphs, table wrappers and cells, reference lists, related articles, footnotes, display formulas, supplementary material, permissions and licenses ([1.4 tag library](https://jats.nlm.nih.gov/archiving/tag-library/1.4/)).
|
||||
Crossref's 5.4.0 deposit schema imports JATS ([Crossref](https://www.crossref.org/documentation/schema-library/metadata-deposit-schema-5-4-0/)), and a toolkit for S2ORC has a script for PMC JATS XML ([allenai/s2orc-doc2json](https://github.com/allenai/s2orc-doc2json)).
|
||||
|
||||
*How paperspec differs.*
|
||||
*How PaperSpec differs.*
|
||||
JATS has `<permissions>` and `<license>` elements; where they may be placed was not verified, so no per-file rights comparison is made.
|
||||
|
||||
*Where JATS is the better choice.*
|
||||
For publisher and archive exchange of journal content, and for the JATS4R recommendations on tagging consistency.
|
||||
paperspec is not a publisher interchange format and does not replace JATS ([spec/02 §2.3](../spec/02-model.md#23-witnessesjson)).
|
||||
PaperSpec is not a publisher interchange format and does not replace JATS ([spec/02 §2.3](../spec/02-model.md#23-witnessesjson)).
|
||||
|
||||
*Interoperation.*
|
||||
JATS is an input.
|
||||
@@ -153,8 +153,8 @@ Pointers use `xml:id`, recommended "For durability in the presence of editing",
|
||||
GROBID extracts header metadata, references, citation contexts and full text with coordinates, and reports, in its own documentation's documentation, an F1 of about 0.87 for references on a PubMed Central set and 0.76 to 0.91 for citation contexts; it describes itself as production ready ([introduction](https://grobid.readthedocs.io/en/latest/Introduction/)).
|
||||
Its `segmentSentences` option splits paragraphs into sentence elements, and `teiCoordinates=s` adds a bounding box to each ([service documentation](https://grobid.readthedocs.io/en/latest/Grobid-service/)).
|
||||
|
||||
*How paperspec differs.*
|
||||
TEI's `xml:id` is author-assigned and durable by recommendation ([TEI pointers chapter](https://tei-c.org/release/doc/tei-p5-doc/en/html/SA.html)); paperspec IDs are minted by a rule and retired by recorded successor.
|
||||
*How PaperSpec differs.*
|
||||
TEI's `xml:id` is author-assigned and durable by recommendation ([TEI pointers chapter](https://tei-c.org/release/doc/tei-p5-doc/en/html/SA.html)); PaperSpec IDs are minted by a rule and retired by recorded successor.
|
||||
GROBID's output is an automatic reading with the accuracy figures above, not a corrected, reviewed text ([introduction](https://grobid.readthedocs.io/en/latest/Introduction/)).
|
||||
|
||||
*Where they are the better choice.*
|
||||
@@ -163,7 +163,7 @@ GROBID as a PDF-to-structure converter for the reference and citation-context ta
|
||||
|
||||
*Interoperation.*
|
||||
TEI from GROBID could be one reading of a PDF.
|
||||
paperspec has no `tei` witness kind, so that reading would be recorded as `xml` ([spec/02 §2.3](../spec/02-model.md#23-witnessesjson)).
|
||||
PaperSpec has no `tei` witness kind, so that reading would be recorded as `xml` ([spec/02 §2.3](../spec/02-model.md#23-witnessesjson)).
|
||||
The mechanism for comparing that reading with another is sentence alignment, which pairs sentences, keeps the first reading's IDs for paired sentences, and turns every disagreement into a suspect for review ([spec/05 §5.6](../spec/05-hashes.md#56-alignment)).
|
||||
No TEI or GROBID mapping is defined in the repository.
|
||||
|
||||
@@ -185,19 +185,19 @@ Targets are narrowed by selectors ([model](https://www.w3.org/TR/annotation-mode
|
||||
Hypothesis stores a range selector (XPaths plus offsets), a position selector and a quote selector with 32 characters of context, and reattaches in four steps: range, position, context-first fuzzy match, then selector-only fuzzy match ([post](https://web.hypothes.is/blog/fuzzy-anchoring/)).
|
||||
It identifies a PDF by an embedded fingerprint, which "persists across copies of the same document, but not across variants" ([Hypothesis help](https://web.hypothes.is/help/annotations-not-syncing-across-copies-of-a-pdf/)).
|
||||
|
||||
*How paperspec differs.*
|
||||
*How PaperSpec differs.*
|
||||
Hypothesis's post lists its own limits: it assumes the system can tell two formats are the same document, mapping text to the DOM (the browser's tree of page elements) is slow on long documents, and mappings update only when Hypothesis itself changes the DOM ([post](https://web.hypothes.is/blog/fuzzy-anchoring/)).
|
||||
paperspec defines exact resolution outcomes and a hash pin where Hypothesis uses fuzzy matching.
|
||||
PaperSpec defines exact resolution outcomes and a hash pin where Hypothesis uses fuzzy matching.
|
||||
|
||||
*Where they are the better choice.*
|
||||
The Web Annotation model and vocabulary for annotation in general, existing Web Annotation tools, and Hypothesis as a working annotation service on web pages and PDFs.
|
||||
|
||||
*Interoperation.*
|
||||
A paperspec layer is a set of W3C Web Annotations whose target lists a custom `AnchorSelector` carrying a `scienting-anchor/1` record, optionally followed by a standard `TextQuoteSelector` "for tools that do not know ours" ([spec/18 §18.3](../spec/18-layers.md#183-the-annotation)).
|
||||
A PaperSpec layer is a set of W3C Web Annotations whose target lists a custom `AnchorSelector` carrying a `scienting-anchor/1` record, optionally followed by a standard `TextQuoteSelector` "for tools that do not know ours" ([spec/18 §18.3](../spec/18-layers.md#183-the-annotation)).
|
||||
The layers do not use `TextPositionSelector` or `FragmentSelector`.
|
||||
The JSON-LD context (a file that maps the added terms to IRIs (internationalized web identifiers), so linked-data tools can read them) is at `https://paperspec.scient.ing/context/scienting-1.jsonld` ([context/README.md](../context/README.md)); whether that address resolves was not checked.
|
||||
Whether a generic Web Annotation client displays an `AnchorSelector` was not verified.
|
||||
Both Hypothesis and paperspec store a quote with 32 characters of prefix and suffix ([spec/06 §6.2](../spec/06-anchors.md#62-the-anchor)).
|
||||
Both Hypothesis and PaperSpec store a quote with 32 characters of prefix and suffix ([spec/06 §6.2](../spec/06-anchors.md#62-the-anchor)).
|
||||
|
||||
## Docling, MinerU and Marker
|
||||
|
||||
@@ -211,7 +211,7 @@ Docling's schema (version 1.10.0 on `main`) covers texts, pictures, tables, grou
|
||||
Docling uses AI models for layout analysis and table structure recognition and is reported integrated with LangChain, LlamaIndex and spaCy ([abstract](https://arxiv.org/abs/2501.17887)).
|
||||
MinerU describes locators of the form `doc:{id}/tier:{tier}/page:{n}/block:{n}/char:{offset}` ([MinerU](https://github.com/opendatalab/MinerU)); Marker's JSON is a tree of blocks with an `id`, a `section_hierarchy` and `images` ([Marker](https://github.com/datalab-to/marker)).
|
||||
|
||||
*How paperspec differs.*
|
||||
*How PaperSpec differs.*
|
||||
The Docling `TextItem` field list has no per-item hash and its `label` enum has no sentence value, so items are block-grained ([schema](https://raw.githubusercontent.com/docling-project/docling-core/main/docs/DoclingDocument.json)).
|
||||
Identifiers in all three are positional: `self_ref` indexes into lists, Marker's example IDs embed a page number, and MinerU's locators embed page and block numbers.
|
||||
MinerU's guide says to preserve locators for citation.
|
||||
@@ -221,10 +221,10 @@ It is not a pinned, quote-verified anchor with resolution outcomes.
|
||||
|
||||
*Where they are the better choice.*
|
||||
For converting PDFs and other formats, layout analysis, table structure recognition, integrations, and one-shot structured output.
|
||||
paperspec does not read PDFs; extracting lines from a PDF is outside its text ([spec/07 §7.1](../spec/07-geometry.md#71-page-fingerprints)).
|
||||
PaperSpec does not read PDFs; extracting lines from a PDF is outside its text ([spec/07 §7.1](../spec/07-geometry.md#71-page-fingerprints)).
|
||||
|
||||
*Interoperation.*
|
||||
These are converters, which paperspec treats as backends.
|
||||
These are converters, which PaperSpec treats as backends.
|
||||
A backend declaration records the tool's code and weight licenses, and a stage may run only if they pass the gate ([spec/14 §14.4](../spec/14-rights.md#144-backends-and-profiles)); `provenance.json` records the backends and cached readings used ([spec/12 §12.4](../spec/12-package.md#124-provenance)).
|
||||
Docling appears in the repository only as data: an illustrative declaration, version `illustrative`, in `fixtures/records/backend-docling.json` and `vectors/rights.jsonl`.
|
||||
Their JSON output is not a named witness kind.
|
||||
@@ -242,17 +242,17 @@ Scale, and citation-mention linking across papers: the paper, an arXiv preprint,
|
||||
The schema classes include `Paper`, with `pdf_hash`, `metadata`, `body_text`, `bib_entries` and `ref_entries`, and `Paragraph`, with `cite_spans`, `ref_spans` and `eq_spans` given as `start`, `end` and `text` ([s2orc.py](https://raw.githubusercontent.com/allenai/s2orc-doc2json/master/doc2json/s2orc.py)).
|
||||
Sources are PDF via GROBID, PMC JATS XML and arXiv LaTeX ([doc2json](https://github.com/allenai/s2orc-doc2json)).
|
||||
|
||||
*How paperspec differs.*
|
||||
*How PaperSpec differs.*
|
||||
Table cells are not nodes ([s2orc.py](https://raw.githubusercontent.com/allenai/s2orc-doc2json/master/doc2json/s2orc.py)).
|
||||
The paper states limitations, among them GROBID-derived inline-citation errors, linking that depends on titles, and LaTeX-derived metadata "worse than those extracted from PDF" ([arXiv:1911.02782](https://arxiv.org/pdf/1911.02782)).
|
||||
The release formats "have changed over time" ([doc2json](https://github.com/allenai/s2orc-doc2json)).
|
||||
|
||||
*Where they are the better choice.*
|
||||
Corpus-scale text mining and citation-graph work across the literature, which paperspec explicitly does not target.
|
||||
Corpus-scale text mining and citation-graph work across the literature, which PaperSpec explicitly does not target.
|
||||
|
||||
*Interoperation.*
|
||||
The purposes and scales differ.
|
||||
S2ORC-style JSON could be a source of text readings. paperspec has no S2ORC witness kind.
|
||||
S2ORC-style JSON could be a source of text readings. PaperSpec has no S2ORC witness kind.
|
||||
The `same_as` list takes `doi:`, `arxiv:`, `isbn:`, `pmid:`, `pmcid:` and `url:` among its prefixes and has no Semantic Scholar identifier ([spec/02 §2.1](../spec/02-model.md#21-four-objects)).
|
||||
|
||||
## Nanopublications and micropublications
|
||||
@@ -268,17 +268,17 @@ Micropublications are a semantic model for claims, evidence, arguments and annot
|
||||
A claim-sized unit with machine-readable provenance and publication metadata, with an integrity check on the unit.
|
||||
Micropublications add a claim, its supporting representations as a directed acyclic graph rooted at the claim, and challenges; the paper says they aim to present primary evidence while nanopublications "model only the indicated statement" ([paper](https://jbiomedsem.biomedcentral.com/articles/10.1186/2041-1480-5-28)).
|
||||
|
||||
*How paperspec differs.*
|
||||
*How PaperSpec differs.*
|
||||
These models do not store the paper's text.
|
||||
The guidelines read do not describe pinning a passage, and they do not mention signatures; a Java library's README shows RSA public-key signing; the signature structure was not verified ([nanopub-java](https://github.com/Nanopublication/nanopub-java)).
|
||||
|
||||
*Where they are the better choice.*
|
||||
Publishing a claim as a citable, hash-verifiable, linked-data object, and representing support and challenge among claims.
|
||||
paperspec does not define claim semantics; a statement true independently of one paper belongs outside this repository, and a statement about reading the paper belongs in a layer ([spec/18 §18.1](../spec/18-layers.md#181-one-rule-decides-what-is-a-claim-and-what-is-a-layer)).
|
||||
PaperSpec does not define claim semantics; a statement true independently of one paper belongs outside this repository, and a statement about reading the paper belongs in a layer ([spec/18 §18.1](../spec/18-layers.md#181-one-rule-decides-what-is-a-claim-and-what-is-a-layer)).
|
||||
|
||||
*Interoperation.*
|
||||
A layer annotation can say that a span states, uses or disputes a claim kept elsewhere ([spec/18 §18.4](../spec/18-layers.md#184-bodies)).
|
||||
A nanopublication's provenance could point at a paperspec address, since an address is a URL fragment (`…#node`, [spec/06 §6.1](../spec/06-anchors.md#61-addresses)); that is an inference, and no such mapping is defined in either project.
|
||||
A nanopublication's provenance could point at a PaperSpec address, since an address is a URL fragment (`…#node`, [spec/06 §6.1](../spec/06-anchors.md#61-addresses)); that is an inference, and no such mapping is defined in either project.
|
||||
|
||||
## Packaging: Frictionless Data Package, RO-Crate and BagIt
|
||||
|
||||
@@ -289,8 +289,8 @@ It is "a simple container format for describing a coherent collection of data in
|
||||
A resource's `hash` is MD5 by default, with other algorithms written as `algorithm:value` ([data resource](https://datapackage.org/standard/data-resource/)).
|
||||
It describes tabular files and their schemas portably.
|
||||
Not seen: hashing that covers descriptor and files in canonical form, per-value anchors to a source text, units and uncertainty.
|
||||
It remains the right choice for the tabular container and its tooling, which paperspec adopts: a `scienting-dataset/1` is a Data Package plus units (strings a unit parser called Pint can read), uncertainty and an `origin`, with reported values anchored to the table cells or sentences that print them ([spec/15](../spec/15-datasets.md)).
|
||||
The Data Package version paperspec uses is not stated in spec/15.
|
||||
It remains the right choice for the tabular container and its tooling, which PaperSpec adopts: a `scienting-dataset/1` is a Data Package plus units (strings a unit parser called Pint can read), uncertainty and an `origin`, with reported values anchored to the table cells or sentences that print them ([spec/15](../spec/15-datasets.md)).
|
||||
The Data Package version PaperSpec uses is not stated in spec/15.
|
||||
The dataset format is `provisional` ([registry/formats.json](../registry/formats.json)).
|
||||
|
||||
*RO-Crate.*
|
||||
@@ -298,14 +298,14 @@ It is "a community effort to establish a lightweight approach to packaging resea
|
||||
Version 1.2 is a Recommendation published 2025-06-04, and the site calls 1.3 the newest ([1.2](https://www.researchobject.org/ro-crate/specification/1.2/index.html)).
|
||||
It describes a folder's contents in `ro-crate-metadata.json`, and file entities should include `contentSize` ([data entities](https://www.researchobject.org/ro-crate/specification/1.2/data-entities.html)).
|
||||
Use it for general research-object description and discovery with schema.org vocabularies.
|
||||
A paperspec package folder could be described by an RO-Crate.
|
||||
A PaperSpec package folder could be described by an RO-Crate.
|
||||
No such mapping exists in either project.
|
||||
|
||||
*BagIt.*
|
||||
RFC 8493 defines a bag: `bagit.txt`, a `data/` payload of opaque octet streams, and at least one `manifest-<algorithm>.txt`; BagIt 1.0 tools must support SHA-256 and SHA-512 ([RFC 8493](https://www.rfc-editor.org/rfc/rfc8493)).
|
||||
The RFC says it "is not designed to be secure against active attacks", and it has no signatures, content-level structure or payload semantics.
|
||||
BagIt fits fixity and transfer of arbitrary payloads, archives and repositories.
|
||||
paperspec's `MANIFEST.json` plays a similar fixity role, with a path, SHA-256 and size per file, and the hash of the manifest pins the package; the file layout differs ([spec/12 §12.3](../spec/12-package.md#123-the-manifest)).
|
||||
PaperSpec's `MANIFEST.json` plays a similar fixity role, with a path, SHA-256 and size per file, and the hash of the manifest pins the package; the file layout differs ([spec/12 §12.3](../spec/12-package.md#123-the-manifest)).
|
||||
A package could be a bag's payload, since payload files are opaque (an inference).
|
||||
|
||||
## Metadata: schema.org, Crossref and DataCite
|
||||
@@ -320,14 +320,14 @@ Bibliographic and identification metadata.
|
||||
schema.org's `CreativeWork` has `text`, `citation`, `hasPart`, `version`, `license` and a `correction` property ([CreativeWork](https://schema.org/CreativeWork)), and `MediaObject` has `sha256` ([MediaObject](https://schema.org/MediaObject)).
|
||||
Crossref's Crossmark lets publishers show whether an item was corrected, retracted or updated, including to readers holding an older download ([Crossmark](https://www.crossref.org/documentation/crossmark/)).
|
||||
|
||||
*How paperspec differs.*
|
||||
*How PaperSpec differs.*
|
||||
These are record-level.
|
||||
A correction is flagged on the work, not on a sentence with evidence for each changed digit; the body has no node hashes; there are no fidelity levels or signed receipts; and rights are license-level information about the work, not per-file use grants with an AI purpose and processor.
|
||||
None of the schema pages read describes body text, and the extent of Crossref's license and text-mining fields was not verified ([Crossref 5.4.0](https://www.crossref.org/documentation/schema-library/metadata-deposit-schema-5-4-0/)).
|
||||
|
||||
*Where they are the better choice.*
|
||||
Identifying and describing works and datasets with DOIs (digital object identifiers), discovery, registering corrections and retractions at the work level, and structured data on web pages.
|
||||
paperspec is not a citation index and imports from Crossref, OpenAlex, PubMed Central and arXiv and never depends on them ([docs/overview.md](../docs/overview.md#what-it-is-not)).
|
||||
PaperSpec is not a citation index and imports from Crossref, OpenAlex, PubMed Central and arXiv and never depends on them ([docs/overview.md](../docs/overview.md#what-it-is-not)).
|
||||
|
||||
*Interoperation.*
|
||||
The document's `meta` is a CSL-JSON item and `same_as` holds a DOI.
|
||||
@@ -339,24 +339,24 @@ No mapping from `meta` to Crossref, DataCite or schema.org is defined.
|
||||
*PROV-O.*
|
||||
It is a W3C Recommendation of 30 April 2013 that expresses the PROV Data Model in OWL2, with the classes Entity, Activity and Agent and properties such as `wasGeneratedBy`, `wasDerivedFrom` and `wasInvalidatedBy` ([PROV-O Recommendation](https://www.w3.org/TR/prov-o/)).
|
||||
It is a general vocabulary and defines no node hashes, anchor resolution, corrections or receipts.
|
||||
paperspec does not use it: provenance is a file, `provenance.json`, defined in the repository ([spec/12 §12.4](../spec/12-package.md#124-provenance)).
|
||||
PaperSpec does not use it: provenance is a file, `provenance.json`, defined in the repository ([spec/12 §12.4](../spec/12-package.md#124-provenance)).
|
||||
PROV-O is the better choice for linked-data provenance that other systems can query generically.
|
||||
A mapping of stages and corrections to Activity and Entity is possible.
|
||||
Nothing in either project defines one.
|
||||
|
||||
*RFC 8785 (JSON Canonicalization Scheme).*
|
||||
Published June 2020 as an Informational RFC, it sorts object properties recursively in UTF-16 code unit order, keeps array order, writes numbers by ECMAScript rules, uses no whitespace, outputs UTF-8, and does not normalize Unicode strings ([RFC 8785](https://www.rfc-editor.org/rfc/rfc8785)).
|
||||
It is a building block that defines no document model, and paperspec uses it: every hash of JSON is over RFC 8785 output.
|
||||
paperspec adds rules on top: a decimal that carries meaning is a string, so `310.0` and `1.5260` keep their printed digits, and a document with a lone surrogate, `NaN` or an infinity has no canonical form and is invalid ([spec/01 §1.1 and §1.2](../spec/01-conventions.md#11-canonical-json)).
|
||||
It is a building block that defines no document model, and PaperSpec uses it: every hash of JSON is over RFC 8785 output.
|
||||
PaperSpec adds rules on top: a decimal that carries meaning is a string, so `310.0` and `1.5260` keep their printed digits, and a document with a lone surrogate, `NaN` or an infinity has no canonical form and is invalid ([spec/01 §1.1 and §1.2](../spec/01-conventions.md#11-canonical-json)).
|
||||
|
||||
*RFC 6962 and RFC 9162 (Merkle trees).*
|
||||
A Merkle tree hashes items pairwise up to one root, so one short value commits to all of them.
|
||||
RFC 6962 (Certificate Transparency, June 2013, Experimental) is obsolete; RFC 9162 (Certificate Transparency Version 2.0, published December 9, 2021, Experimental) "obsoletes RFC 6962" ([RFC 6962](https://www.rfc-editor.org/rfc/rfc6962), [RFC 9162](https://www.rfc-editor.org/rfc/rfc9162)).
|
||||
Both give the same Merkle Tree Hash: a leaf is `HASH(0x00 || d)`, an interior node is `HASH(0x01 || left || right)`, and a list splits at the largest power of two smaller than n.
|
||||
paperspec's receipts use this construction with SHA-256 and cite RFC 6962 ([spec/08 §8.5](../spec/08-fidelity.md#85-merkle-roots)).
|
||||
They differ in one rule: a receipt with no items is invalid in paperspec, while the RFC defines the hash of an empty list.
|
||||
PaperSpec's receipts use this construction with SHA-256 and cite RFC 6962 ([spec/08 §8.5](../spec/08-fidelity.md#85-merkle-roots)).
|
||||
They differ in one rule: a receipt with no items is invalid in PaperSpec, while the RFC defines the hash of an empty list.
|
||||
The citation is to the obsolete RFC; the tree it defines is the one RFC 9162 also defines.
|
||||
paperspec's `node_hash` is not this construction (see "Limits and status" below).
|
||||
PaperSpec's `node_hash` is not this construction (see "Limits and status" below).
|
||||
|
||||
## Content addressing: IPFS CIDs and SWHIDs
|
||||
|
||||
@@ -366,7 +366,7 @@ It gives verifiable, location-independent identity to immutable data.
|
||||
A CID covers the root block of a DAG (directed acyclic graph), "not a direct hash of the file's bytes", so chunk size, layout, codec, version and hash all change the CID for the same file.
|
||||
Identity and content are the same thing, so an edit makes a new identifier; the page describes no ID that survives edits, no sentence granularity, corrections or fidelity.
|
||||
Keep using CIDs for storage and distribution of immutable blobs.
|
||||
paperspec's asset store names files by SHA-256, not CID ([spec/12 §12.6](../spec/12-package.md#126-assets)).
|
||||
PaperSpec's asset store names files by SHA-256, not CID ([spec/12 §12.6](../spec/12-package.md#126-assets)).
|
||||
|
||||
*Software Heritage SWHID.*
|
||||
ISO/IEC 18670:2025 specifies the SoftWare Hash IDentifier, version 1.2, published April 2025 ([ISO catalog page](https://www.iso.org/standard/89985.html); [swhid.org](https://www.swhid.org/specification/v1.2/)).
|
||||
@@ -376,8 +376,8 @@ Keep using SWHIDs for persistent, content-derived identification and archiving o
|
||||
|
||||
*The contrast.*
|
||||
A CID or SWHID is a function of content at all times.
|
||||
A paperspec node ID is derived from content once, at minting, and then frozen; the content hashes live separately in `node_hash`, so the pair of ID and hash tells whether the text has changed ([spec/04 §4.2 and §4.3](../spec/04-identity.md#42-minting-node-ids), [spec/05 §5.1](../spec/05-hashes.md#51-the-five-values)).
|
||||
paperspec's hashes are SHA-256 ([spec/01 §1.3](../spec/01-conventions.md#13-hashes)).
|
||||
A PaperSpec node ID is derived from content once, at minting, and then frozen; the content hashes live separately in `node_hash`, so the pair of ID and hash tells whether the text has changed ([spec/04 §4.2 and §4.3](../spec/04-identity.md#42-minting-node-ids), [spec/05 §5.1](../spec/05-hashes.md#51-the-five-values)).
|
||||
PaperSpec's hashes are SHA-256 ([spec/01 §1.3](../spec/01-conventions.md#13-hashes)).
|
||||
The cost of the choice: because the ID is minted from the text hash, two independent conversions that read a sentence differently by one character mint different IDs for it.
|
||||
|
||||
## Fragment identifiers and Pandoc
|
||||
@@ -386,7 +386,7 @@ A fragment identifier is the part of a URL after `#` that says where to look ins
|
||||
|
||||
- **PDF fragments (RFC 8118):** Informational, March 2017.
|
||||
Parameters include `page`, `nameddest`, `structelem`, `zoom`, `viewrect`, `highlight` and `search`; none selects text by character offset, `search` "selects the first matching word in the document", and `highlight` takes rectangle coordinates ([RFC 8118](https://www.rfc-editor.org/rfc/rfc8118)).
|
||||
Keep using it to open a PDF at a page, destination or region. paperspec's `locations.jsonl` stores per-node page boxes as `[x0, y0, x1, y1]` in PDF points against page fingerprints ([spec/07 §7.4](../spec/07-geometry.md#74-locationsjsonl)), so a tool could build an RFC 8118 link; the repository does not define that.
|
||||
Keep using it to open a PDF at a page, destination or region. PaperSpec's `locations.jsonl` stores per-node page boxes as `[x0, y0, x1, y1]` in PDF points against page fingerprints ([spec/07 §7.4](../spec/07-geometry.md#74-locationsjsonl)), so a tool could build an RFC 8118 link; the repository does not define that.
|
||||
- **Media Fragments URI 1.0:** A W3C Recommendation of 25 September 2012 that defines time (`t=`) and spatial (`xywh=`) fragments for audio, video and images, and says nothing about text ([Media Fragments](https://www.w3.org/TR/media-frags/)).
|
||||
It is a weak fit for text passages.
|
||||
- **RFC 5147 (text/plain):** A Proposed Standard of April 2008 with `char=` and `line=` positions counted from zero and integrity checks `length=` and `md5=`, "to detect whether the resource has changed" ([RFC 5147](https://www.rfc-editor.org/rfc/rfc5147)).
|
||||
@@ -394,11 +394,11 @@ A fragment identifier is the part of a URL after `#` that says where to look ins
|
||||
- **Text Fragments:** A WICG Draft Community Group Report, not a W3C standard; the version read is dated 13 December 2023 and may not be the latest.
|
||||
The syntax is `#:~:text=[prefix-,]start[,end][,-suffix]`, it matches the first exact occurrence, and it is restricted to top-level navigations ([WICG draft report](https://wicg.github.io/scroll-to-text-fragment/)).
|
||||
- **DOM and XPath approaches:** W3C `XPathSelector` and `RangeSelector` ([model](https://www.w3.org/TR/annotation-model/)), TEI's `xpath()` scheme ([TEI pointers chapter](https://tei-c.org/release/doc/tei-p5-doc/en/html/SA.html)) and Hypothesis's first strategy, which "fails if the XPath expressions can no longer be applied" ([post](https://web.hypothes.is/blog/fuzzy-anchoring/)).
|
||||
Path addressing breaks when structure changes; paperspec's display paths are never stored or cited ([spec/04 §4.3](../spec/04-identity.md#43-permanence-retirement-and-aliases)).
|
||||
Path addressing breaks when structure changes; PaperSpec's display paths are never stored or cited ([spec/04 §4.3](../spec/04-identity.md#43-permanence-retirement-and-aliases)).
|
||||
- **Pandoc:** The pandoc-types library defines the `Pandoc` document type with modules for building, walking and JSON conversion; the latest on Hackage is 1.23.1, uploaded 2023-08-06 ([Hackage](https://hackage.haskell.org/package/pandoc-types)).
|
||||
Its Block and Inline types and its treatment of identifiers were not verified. `latex` is a paperspec witness kind ([spec/02 §2.3](../spec/02-model.md#23-witnessesjson)); Pandoc is not mentioned in the repository.
|
||||
Its Block and Inline types and its treatment of identifiers were not verified. `latex` is a PaperSpec witness kind ([spec/02 §2.3](../spec/02-model.md#23-witnessesjson)); Pandoc is not mentioned in the repository.
|
||||
|
||||
On the web, a paperspec node ID is the URL fragment, so `…#k3m9q2a` lands on the sentence ([spec/06 §6.1](../spec/06-anchors.md#61-addresses)).
|
||||
On the web, a PaperSpec node ID is the URL fragment, so `…#k3m9q2a` lands on the sentence ([spec/06 §6.1](../spec/06-anchors.md#61-addresses)).
|
||||
This is a plain HTML fragment, not a registered fragment scheme; the chapters define no fragment syntax for the package media type.
|
||||
|
||||
## BioC, CSL-JSON and EPUB 3
|
||||
@@ -408,27 +408,27 @@ BioC is a simple extensible XML format for sharing text documents and annotation
|
||||
Its model has collection, source, document, passage, optional sentence, annotation and relation, with `infon` key-value pairs, and an annotation's location is an offset and length relative to the whole document.
|
||||
Its authors state that it "targets tool developers and not end users" and "focuses on text data rather than other media".
|
||||
Keep using it to exchange text-mining annotations among biomedical natural-language-processing (NLP) tools.
|
||||
Offsets would need conversion, since paperspec counts Unicode code points ([spec/01 §1.5](../spec/01-conventions.md#15-character-offsets)) and the length unit in BioC was taken from a page summary and not confirmed.
|
||||
Offsets would need conversion, since PaperSpec counts Unicode code points ([spec/01 §1.5](../spec/01-conventions.md#15-character-offsets)) and the length unit in BioC was taken from a page summary and not confirmed.
|
||||
No BioC mapping is defined.
|
||||
|
||||
*CSL-JSON.*
|
||||
It is a JSON format for bibliographic items consumed by Citation Style Language (CSL) processors; items require `id` and `type`, `author` is an array of name objects, and `issued` uses `date-parts` or `raw` ([markup page of the CSL-JSON documentation](https://citeproc-js.readthedocs.io/en/latest/csl-json/markup.html)).
|
||||
Its schema is described as "not yet fully normative" ([CSL schema](https://github.com/citation-style-language/schema)).
|
||||
Keep using it for bibliographic interchange with citation processors and reference managers.
|
||||
paperspec embeds CSL-JSON as the document's `meta` and as the optional parsed `csl` of each reference ([spec/02 §2.2](../spec/02-model.md#22-documentjson), [spec/10](../spec/10-references.md)).
|
||||
PaperSpec embeds CSL-JSON as the document's `meta` and as the optional parsed `csl` of each reference ([spec/02 §2.2](../spec/02-model.md#22-documentjson), [spec/10](../spec/10-references.md)).
|
||||
|
||||
*EPUB 3.*
|
||||
EPUB 3.3 is a W3C Recommendation, "a distribution and interchange format for digital publications and documents": a ZIP container with a package document listing a manifest and a spine, and XHTML or SVG content documents ([EPUB 3.3](https://www.w3.org/TR/epub-33/)).
|
||||
It suits reflowable publications.
|
||||
Keep using it as a reading and distribution format.
|
||||
`epub` is a paperspec witness kind ([spec/02 §2.3](../spec/02-model.md#23-witnessesjson)), and the zip package rules (UTF-8 names, one top-level folder, no symlinks) are the package's own ([spec/12 §12.2](../spec/12-package.md#122-paths)).
|
||||
`epub` is a PaperSpec witness kind ([spec/02 §2.3](../spec/02-model.md#23-witnessesjson)), and the zip package rules (UTF-8 names, one top-level folder, no symlinks) are the package's own ([spec/12 §12.2](../spec/12-package.md#122-paths)).
|
||||
|
||||
## Limits and status
|
||||
|
||||
*Status.*
|
||||
The specification is version 0.1.0.
|
||||
`registry/formats.json` lists 32 formats: 19 are `candidate` (complete, with vectors and fixtures, ready to implement) and 13 are `provisional` (complete; expected to change as implementations gain experience): project, bundle, dataset, digitization, view, snapshot, draft-ids, exercise, submission, grade, checklist, log-entry and checkpoint ([spec/00 §0.4](../spec/00-introduction.md#04-status)).
|
||||
The repository holds 24 chapters, 43 JSON Schemas, 26 vector files, five valid fixture packages, one of them also zipped, and 31 invalid ones, each naming the rule it breaks, and a reference checker, `paperspec check`.
|
||||
The repository holds 24 chapters, 43 JSON Schemas, 29 vector files, five valid fixture packages, one of them also zipped, and 33 invalid ones, each naming the rule it breaks, and a reference checker, `paperspec check`.
|
||||
Licenses: prose CC BY 4.0; schemas, SQL, the JSON-LD context, registries, vectors and fixtures CC0 1.0; the code in `src/` Apache-2.0 ([README.md](../README.md#licenses)).
|
||||
|
||||
*No adoption claim.*
|
||||
@@ -437,9 +437,9 @@ The repository names no outside adopter and no independent implementation, and t
|
||||
*Scope of this comparison.*
|
||||
|
||||
The pages read cover no ORKG, DocBook, PubAnnotation, OpenAlex or PMC OA XML material, so those are not compared.
|
||||
A statement that no single comparator combines paperspec's features describes the pages read and surveys no other systems.
|
||||
A statement that no single comparator combines PaperSpec's features describes the pages read and surveys no other systems.
|
||||
|
||||
*What paperspec does not do.*
|
||||
*What PaperSpec does not do.*
|
||||
|
||||
- It is not a publisher interchange format; it ingests JATS and other formats as witnesses and does not replace them ([spec/02 §2.3](../spec/02-model.md#23-witnessesjson)).
|
||||
- It is not a search engine, a citation index, a recommendation feed or a chat-with-a-PDF tool ([docs/overview.md](../docs/overview.md#what-it-is-not)).
|
||||
@@ -474,7 +474,7 @@ These are the places where the guides and the specification differ, and this pag
|
||||
Of the 32 formats, 13 are `provisional`, including `scienting-dataset/1`, which the datasets paragraphs in `docs/concepts.md` present without that qualifier.
|
||||
|
||||
*The distinguishing combination, and what it costs.*
|
||||
paperspec puts in one package permanent sentence- and cell-level IDs, five hashes per node, anchors with explicit resolution outcomes and drift, append-only evidence-gated corrections, signed fidelity receipts with spot-check bounds, per-witness rights with AI-use axes, and value-to-cell anchors.
|
||||
PaperSpec puts in one package permanent sentence- and cell-level IDs, five hashes per node, anchors with explicit resolution outcomes and drift, append-only evidence-gated corrections, signed fidelity receipts with spot-check bounds, per-witness rights with AI-use axes, and value-to-cell anchors.
|
||||
Individual pieces have precedents in the comparators: TEI correction markup, Web Annotation selectors, RFC 5147 integrity checks, RFC 6962 Merkle trees, BagIt manifests and Frictionless packaging.
|
||||
No single comparator in the pages read combines them.
|
||||
The price is weight: five hashes per node, a gate on corrections, signed records and a custom selector type.
|
||||
|
||||
+12
-4
@@ -16,8 +16,8 @@ It defines 32 formats, 19 of them `candidate` and 13 `provisional`, as [registry
|
||||
The provisional ones are the project, bundle, dataset, digitization, view, snapshot, draft-ids, exercise, submission, grade, checklist, log-entry and checkpoint formats; the sections below say so where they describe them.
|
||||
|
||||
Format identifiers such as `scienting-anchor/1` and `scienting-correction/1` begin with `scienting-`, which is the formats' namespace.
|
||||
The repository's name, paperspec, is a separate matter, and the formats are named after what they hold.
|
||||
The repository is at <https://git.scient.ing/infra/paperspec>.
|
||||
The repository's name, PaperSpec, is a separate matter, and the formats are named after what they hold.
|
||||
The repository is at <https://git.scient.ing/papers/paperspec>.
|
||||
|
||||
## Hashes and canonical JSON
|
||||
|
||||
@@ -103,7 +103,7 @@ Page breaks, running heads and columns are not nodes; they are geometry ([chapte
|
||||
See [chapter 3](../spec/03-nodes.md).
|
||||
|
||||
Close relatives: [JATS 1.4](https://www.niso.org/publications/z3996-2024-jats) is an XML format in which publishers and archives exchange journal content, and TEI is a set of guidelines for encoding scholarly text.
|
||||
Each is the better choice for its own job, and the paperspec formats do not replace them; a JATS file can be one witness of a document.
|
||||
Each is the better choice for its own job, and the PaperSpec formats do not replace them; a JATS file can be one witness of a document.
|
||||
The element list in the [JATS 1.4 archiving tag library](https://jats.nlm.nih.gov/archiving/tag-library/1.4/) shows sections, paragraphs, table wrappers and cells and has no sentence element, while [TEI has an `<s>` element](https://tei-c.org/release/doc/tei-p5-doc/en/html/ref-s.html).
|
||||
Here the sentence is the unit that gets an ID and hashes.
|
||||
See [the comparison page](comparison.md).
|
||||
@@ -378,8 +378,16 @@ Model-written text is always a `generated` annotation, never source, and a model
|
||||
Whether a generic Web Annotation client displays an `AnchorSelector` has not been tested; the fallback exists so that it can still use the quote.
|
||||
A `trace` annotation follows a citation to the passage it rests on: it targets the citing sentence and its body names the reference, the cited paper and the passage in it.
|
||||
Whether a trace still leads there is computed from both papers rather than stored: `current`, `changed`, `stale`, `unlinked` or `misresolved`.
|
||||
A `structure` annotation ties a chemical structure to the words that name it, and a `sequence` annotation does the same for a protein, DNA or RNA sequence.
|
||||
Nothing finds a molecule in free text, so a person ties each one by hand and the words stay the paper's.
|
||||
A structure is a SMILES for a molecule or a SMARTS for a group, a fragment with open positions (`R-OH`) or a pattern of atom types, and it may carry the bonds, angles and torsions the paper gives force-field constants for, citing atoms by their numbers in the text.
|
||||
A sequence has an alphabet, an optional numbering that starts where the fragment does, regions and variants checked against the residues.
|
||||
Both carry an `identity` that finds the same structure or sequence however it was written.
|
||||
A `data` annotation says what kind of data a table, a figure panel or a passage presents, from a fixed list of fifteen kinds such as `binding-affinity`, `energy-profile` or `force-field-parameters`.
|
||||
It names the dataset that holds the values, what each of its fields measures with the dataset's own unit, and the molecules and sequences the data is about by their identities, so data can be found by its kind and by its subject.
|
||||
A kind that the list lacks is carried by an outside term in `accessions`, and where the values came from stays the dataset's `origin`.
|
||||
Layers are `candidate`.
|
||||
Pinned by the layer records in `fixtures/records/layer/` and `fixtures/records/traces/`, and by [vectors/traces.jsonl](../vectors/traces.jsonl).
|
||||
Pinned by the layer records in `fixtures/records/layer/`, `traces/`, `chemistry/`, `biology/` and `data/`, and by [vectors/traces.jsonl](../vectors/traces.jsonl), [vectors/structures.jsonl](../vectors/structures.jsonl), [vectors/sequences.jsonl](../vectors/sequences.jsonl) and [vectors/data.jsonl](../vectors/data.jsonl).
|
||||
See [chapter 18](../spec/18-layers.md).
|
||||
|
||||
## Exercises
|
||||
|
||||
+142
-18
@@ -7,7 +7,7 @@ The last sections point implementers (anyone writing a reader, writer, converter
|
||||
This page makes no comparison with the neighboring standards.
|
||||
The formats are version 0.1.0, and each is `candidate` or `provisional` in `registry/formats.json`.
|
||||
|
||||
Run every command from the root of the repository, <https://git.scient.ing/infra/paperspec>.
|
||||
Run every command from the root of the repository, <https://git.scient.ing/papers/paperspec>.
|
||||
With [pixi](https://pixi.sh), `pixi run <task>` sets up the environment first.
|
||||
Every command also works without pixi once the checkout is installed with `pip install -e ".[tools]"` on Python 3.14, given standard command-line tools (the `sed` command in the last section is the GNU version of `sed`).
|
||||
|
||||
@@ -19,10 +19,10 @@ This shows how to confirm that the repository's specification, fixtures and test
|
||||
pixi run check
|
||||
```
|
||||
|
||||
`pixi run check` lints the Markdown, then runs `paperspec check`, the repository's reference checker.
|
||||
`pixi run check` checks the Python code and lints the Markdown, then runs `paperspec check`, the repository's reference checker.
|
||||
Each section prints how many checks it ran, and the last line is `All checks pass.`
|
||||
`pixi run quick`, or `paperspec check --quick`, skips the slowest part, which rebuilds everything and compares it byte for byte.
|
||||
Without pixi, the Markdown lint is a separate step (`markdownlint-cli2`); `paperspec check` does not run it.
|
||||
Without pixi, the code checks and the Markdown lint (`markdownlint-cli2`) are separate steps; `paperspec check` does not run them.
|
||||
|
||||
## Recompute a hash by hand
|
||||
|
||||
@@ -102,7 +102,11 @@ def text(n):
|
||||
for n in nodes:
|
||||
if n["kind"] == "section":
|
||||
heading = children[n["id"]][0]
|
||||
print(n["id"], n.get("label", ""), " ".join(text(s) for s in children[heading["id"]]))
|
||||
print(
|
||||
n["id"],
|
||||
n.get("label", ""),
|
||||
" ".join(text(s) for s in children[heading["id"]]),
|
||||
)
|
||||
elif n["kind"] in ("figure", "table", "equation"):
|
||||
print(n["id"], " ", n["kind"], n.get("label", ""))
|
||||
```
|
||||
@@ -163,29 +167,41 @@ import json, sqlite3
|
||||
db = sqlite3.connect("lab.db")
|
||||
|
||||
# Sentences the converter left below F2. Receipts can raise them; see below.
|
||||
for row in db.execute("SELECT id, fidelity FROM nodes WHERE doc_key = 'hale2026harmonic-damb' "
|
||||
"AND kind = 'sentence' AND fidelity IN ('F0', 'F1') ORDER BY seq"):
|
||||
for row in db.execute(
|
||||
"SELECT id, fidelity FROM nodes WHERE doc_key = 'hale2026harmonic-damb' "
|
||||
"AND kind = 'sentence' AND fidelity IN ('F0', 'F1') ORDER BY seq"
|
||||
):
|
||||
print(row)
|
||||
|
||||
# Every sentence that cites reference 2: the citation graph is sentence-level.
|
||||
for row in db.execute("SELECT c.sentence FROM citations c JOIN refs r "
|
||||
for row in db.execute(
|
||||
"SELECT c.sentence FROM citations c JOIN refs r "
|
||||
"ON r.doc_key = c.doc_key AND r.node = c.ref_node "
|
||||
"WHERE c.doc_key = 'hale2026harmonic-damb' AND r.label = '2'"):
|
||||
"WHERE c.doc_key = 'hale2026harmonic-damb' AND r.label = '2'"
|
||||
):
|
||||
print(row)
|
||||
|
||||
# Who signed what.
|
||||
for row in db.execute("SELECT r.signer, r.scope, COUNT(*) FROM receipts r "
|
||||
"JOIN receipt_nodes rn ON rn.receipt = r.id GROUP BY r.id ORDER BY r.made_at"):
|
||||
for row in db.execute(
|
||||
"SELECT r.signer, r.scope, COUNT(*) FROM receipts r "
|
||||
"JOIN receipt_nodes rn ON rn.receipt = r.id GROUP BY r.id ORDER BY r.made_at"
|
||||
):
|
||||
print(row)
|
||||
|
||||
# Table 1's body, row by row.
|
||||
rows = db.execute("SELECT r.id FROM nodes r JOIN nodes b ON b.doc_key = r.doc_key AND b.id = r.parent "
|
||||
rows = db.execute(
|
||||
"SELECT r.id FROM nodes r JOIN nodes b ON b.doc_key = r.doc_key AND b.id = r.parent "
|
||||
"WHERE r.doc_key = 'hale2026harmonic-damb' AND r.kind = 'row' AND b.kind = 'table-body' "
|
||||
"ORDER BY r.seq").fetchall()
|
||||
"ORDER BY r.seq"
|
||||
).fetchall()
|
||||
for (row,) in rows:
|
||||
cells = db.execute("SELECT content FROM nodes WHERE doc_key = 'hale2026harmonic-damb' AND parent = ? ORDER BY ord",
|
||||
(row,)).fetchall()
|
||||
print(" | ".join("".join(r.get("text", "") for r in json.loads(c)) for (c,) in cells))
|
||||
cells = db.execute(
|
||||
"SELECT content FROM nodes WHERE doc_key = 'hale2026harmonic-damb' AND parent = ? ORDER BY ord",
|
||||
(row,),
|
||||
).fetchall()
|
||||
print(
|
||||
" | ".join("".join(r.get("text", "") for r in json.loads(c)) for (c,) in cells)
|
||||
)
|
||||
```
|
||||
|
||||
```text
|
||||
@@ -225,12 +241,19 @@ from paperspec import package, traces
|
||||
|
||||
draft = package.read_state("fixtures/packages/writer2027fixed-ynr7.v3")
|
||||
paper = package.read_state("fixtures/packages/hale2026harmonic-damb")
|
||||
same_as = json.load(open("fixtures/packages/hale2026harmonic-damb/document.json"))["work"]["same_as"]
|
||||
annotations = [json.loads(line) for line in open("fixtures/records/traces/annotations.jsonl", encoding="utf-8")]
|
||||
same_as = json.load(open("fixtures/packages/hale2026harmonic-damb/document.json"))[
|
||||
"work"
|
||||
]["same_as"]
|
||||
annotations = [
|
||||
json.loads(line)
|
||||
for line in open("fixtures/records/traces/annotations.jsonl", encoding="utf-8")
|
||||
]
|
||||
for a in annotations:
|
||||
if a["body"]["kind"] == "trace":
|
||||
r = traces.resolve(a, draft, paper, same_as)
|
||||
print(a["status"], r["result"], r["open"], traces.disputed(a["id"], annotations))
|
||||
print(
|
||||
a["status"], r["result"], r["open"], traces.disputed(a["id"], annotations)
|
||||
)
|
||||
```
|
||||
|
||||
```text
|
||||
@@ -244,6 +267,107 @@ The first trace is disputed by a reply that says the table is the better passage
|
||||
The outcomes here are all `current`; [vectors/traces.jsonl](../vectors/traces.jsonl) corrects the draft or the paper and shows the others: `changed` when the passage was reworded but is still found, `stale` when it is gone, `unlinked` when the sentence no longer cites the reference, and `misresolved` when the reference now resolves to another paper.
|
||||
Resolving a trace also lists the citations inside the passage, so a chain of "as previously reported" is followed one trace at a time.
|
||||
|
||||
## Read the structures and sequences tied to a paper's words
|
||||
|
||||
This shows how a molecule or a sequence is tied to the words that name it, and how the layer checks what it holds.
|
||||
Nothing finds a molecule in free text, so a person ties each one: a `structure` annotation holds a SMILES or SMARTS, a `sequence` annotation holds residues, and the span is the annotation's target ([chapter 18](../spec/18-layers.md#186-chemical-structures)).
|
||||
The main example has a layer of four structures and the draft a layer of three sequences, and `paperspec.structures` and `paperspec.sequences` check each against the rules, with the standard library alone:
|
||||
|
||||
```python
|
||||
import json
|
||||
from paperspec import sequences, structures
|
||||
|
||||
for name, module in (("chemistry", structures), ("biology", sequences)):
|
||||
for line in open(f"fixtures/records/{name}/annotations.jsonl", encoding="utf-8"):
|
||||
a = json.loads(line)
|
||||
quote = a["target"]["selector"][1]["exact"]
|
||||
print(
|
||||
a["status"],
|
||||
a["body"]["role"],
|
||||
a["body"]["identity"],
|
||||
repr(quote),
|
||||
module.problems(a),
|
||||
)
|
||||
|
||||
atoms, bonds = structures.scan("O([H])[H]")
|
||||
print(atoms, sorted(bonds))
|
||||
```
|
||||
|
||||
```text
|
||||
confirmed names OTMSDBZUPAUEDD-UHFFFAOYSA-N 'ethane' []
|
||||
proposed names XLYOFNOQVPJJNP-UHFFFAOYSA-N 'Water' []
|
||||
confirmed parametrizes smarts:2e2a923f840c 'CT–CT' []
|
||||
confirmed parametrizes XLYOFNOQVPJJNP-UHFFFAOYSA-N 'OW–HW' []
|
||||
confirmed names protein:5807fcbf6d5567ca 'villin headpiece subdomain HP35' []
|
||||
confirmed depicts protein:5807fcbf6d5567ca 'LSDEDFKAVFGMTRSAFANLPLWKQQNLKKEKGLF' []
|
||||
proposed reports protein:5807fcbf6d5567ca 'N68H' []
|
||||
3 [(0, 1), (0, 2)]
|
||||
```
|
||||
|
||||
Each line gives the annotation's status, what its span does with the structure, the identity, the words, and the rules it breaks, none here.
|
||||
The identity finds the same thing however it was written: the name a model proposed for water, `O`, and the `O([H])[H]` that Table 1's OW–HW constants are given on are one molecule, and all three annotations of the peptide share one identity.
|
||||
The last line is the rule that lets a term cite atoms without a chemistry toolkit: `O([H])[H]` writes three atoms, numbered from 0 as it writes them, and the oxygen (0) is bonded to each hydrogen (1 and 2) and the hydrogens are not bonded to each other, so a bond term on atoms 1 and 2, or an angle on atoms 0, 1 and 2, is refused.
|
||||
[vectors/structures.jsonl](../vectors/structures.jsonl) and [vectors/sequences.jsonl](../vectors/sequences.jsonl) show every rule broken.
|
||||
|
||||
## Find data by its kind and by what it is about
|
||||
|
||||
This shows how a table or a figure panel is tagged with the kind of data it presents, and how that tag is checked against the dataset and found by a molecule.
|
||||
A `data` annotation names the dataset that holds the values, the quantities its fields measure, and the molecules and sequences it is about by the identities that `structure` and `sequence` annotations carry ([chapter 18](../spec/18-layers.md#188-data)).
|
||||
`paperspec.data` checks an annotation against the rules, and against the dataset's descriptor when it is given one, with the standard library alone:
|
||||
|
||||
```python
|
||||
import json
|
||||
from paperspec import data
|
||||
|
||||
descriptors = {}
|
||||
for folder in (
|
||||
"fixtures/packages/hale2026harmonic-damb/datasets/ds-hale-bond-params",
|
||||
"fixtures/records/datasets/ds-hale-ctct-scan",
|
||||
):
|
||||
with open(folder + "/datapackage.json", encoding="utf-8") as f:
|
||||
d = json.load(f)
|
||||
descriptors[d["id"]] = d
|
||||
|
||||
annotations = [
|
||||
json.loads(line)
|
||||
for line in open("fixtures/records/data/annotations.jsonl", encoding="utf-8")
|
||||
]
|
||||
for a in annotations:
|
||||
b = a["body"]
|
||||
quote = a["target"]["selector"][1]["exact"]
|
||||
about = [s["label"] for s in b.get("subjects", [])]
|
||||
print(
|
||||
a["status"],
|
||||
b["role"],
|
||||
b["data_type"],
|
||||
b.get("dataset"),
|
||||
repr(quote),
|
||||
about,
|
||||
data.problems(a, descriptors.get(b.get("dataset"))),
|
||||
)
|
||||
|
||||
ethane = "OTMSDBZUPAUEDD-UHFFFAOYSA-N"
|
||||
for a in annotations:
|
||||
b = a["body"]
|
||||
if b["data_type"] == "force-field-parameters" and any(
|
||||
s["identity"] == ethane for s in b.get("subjects", [])
|
||||
):
|
||||
print([(q["name"], q["unit"]) for q in b["quantities"]])
|
||||
```
|
||||
|
||||
```text
|
||||
confirmed reports force-field-parameters ds-hale-bond-params 'Fitted harmonic bond parameters.' ['ethane', 'water', 'CT–CT'] []
|
||||
confirmed reports energy-profile ds-hale-ctct-scan '(a) The scan.' ['ethane'] []
|
||||
proposed uses force-field-parameters ds-hale-bond-params 'Table 1 lists the fitted constants for both parameter sets.' [] []
|
||||
[('harmonic bond force constant', 'kcal / mol / angstrom ** 2'), ('equilibrium bond length', 'angstrom')]
|
||||
```
|
||||
|
||||
Each of the first three lines gives the annotation's status, what its span does with the data, the kind, the dataset, the words, the subjects and the rules it breaks, none here.
|
||||
The caption of Table 1 and the sentence that introduces it lead to one dataset: the caption `reports` it, and the sentence `uses` it and is a model's proposal that a person has not yet confirmed.
|
||||
The subjects are the identities of the chemistry layer, so a search for force-field parameters about ethane, the last line, finds the table by the molecule and not by the word, and gives the units as the dataset spells them.
|
||||
The unit is compared as a string and never parsed, so a checker that wants to know that `kcal / mol / angstrom ** 2` is a force constant needs a unit library of its own.
|
||||
[vectors/data.jsonl](../vectors/data.jsonl) shows every rule broken, among them a quantity whose unit is not its dataset's.
|
||||
|
||||
## Test your implementation against a vector
|
||||
|
||||
A test vector is a recorded input together with the output every correct implementation must produce.
|
||||
|
||||
+5
-5
@@ -1,9 +1,9 @@
|
||||
# FAQ
|
||||
|
||||
This page answers questions about paperspec, a set of file formats that give every sentence and table cell of a scientific paper a permanent address.
|
||||
This page answers questions about PaperSpec, a set of file formats that give every sentence and table cell of a scientific paper a permanent address.
|
||||
Newcomers, implementers of a reader, writer, converter or checker, and experts who know JATS (Journal Article Tag Suite), TEI (Text Encoding Initiative) or W3C Web Annotations can all use it.
|
||||
Each answer gives the plain statement first, then the precise one, then the chapter that defines it.
|
||||
The repository is <https://git.scient.ing/infra/paperspec>, and the formats are at version 0.1.0.
|
||||
The repository is <https://git.scient.ing/papers/paperspec>, and the formats are at version 0.1.0.
|
||||
|
||||
## Can I read these files without special software?
|
||||
|
||||
@@ -88,13 +88,13 @@ Whether a team may share notes on a paper this way is a question for its own cou
|
||||
|
||||
They overlap in subject, not in job.
|
||||
|
||||
JATS, the [Journal Article Tag Suite](https://www.niso.org/publications/z3996-2024-jats) (ANSI/NISO Z39.96-2024), is an XML format for publishers and archives to exchange journal content. paperspec does not replace it.
|
||||
JATS, the [Journal Article Tag Suite](https://www.niso.org/publications/z3996-2024-jats) (ANSI/NISO Z39.96-2024), is an XML format for publishers and archives to exchange journal content. PaperSpec does not replace it.
|
||||
A JATS file is one kind of witness (a source file), an input from which a document is established.
|
||||
None of the 312 elements in the [JATS 1.4 Archiving tag library](https://jats.nlm.nih.gov/archiving/tag-library/1.4/) marks a sentence; its smallest text unit is the paragraph, `<p>`.
|
||||
|
||||
TEI, the Text Encoding Initiative, has a sentence-like [`<s>` element](https://tei-c.org/release/doc/tei-p5-doc/en/html/ref-s.html) and keeps both readings of a corrected passage with [`<corr>` and `<sic>`](https://tei-c.org/release/doc/tei-p5-doc/en/html/ref-corr.html).
|
||||
The encoder assigns its `xml:id`, and the guidelines [recommend it for durability](https://tei-c.org/release/doc/tei-p5-doc/en/html/SA.html).
|
||||
paperspec mints and retires IDs by rule, keeps corrections as separate records with evidence, and hashes each node.
|
||||
PaperSpec mints and retires IDs by rule, keeps corrections as separate records with evidence, and hashes each node.
|
||||
|
||||
Keep JATS for publisher and archive exchange and TEI for general scholarly text encoding.
|
||||
A TEI file is a witness of kind `xml` ([spec/02 §2.3](../spec/02-model.md)).
|
||||
@@ -107,7 +107,7 @@ A `candidate` format is complete, with vectors and fixtures, and ready to implem
|
||||
A `provisional` one is complete and expected to change as implementations gain experience.
|
||||
The provisional formats are dataset, digitization, view, project, bundle, snapshot, draft-ids, exercise, submission, grade, checklist, log-entry and checkpoint.
|
||||
|
||||
The repository holds a reference checker (`paperspec check`), 26 vector files, five valid packages, one of them also as a zip, and 31 deliberately broken packages ([spec/00 §0.4](../spec/00-introduction.md#04-status), [spec/22](../spec/22-conformance.md)).
|
||||
The repository holds a reference checker (`paperspec check`), 29 vector files, five valid packages, one of them also as a zip, and 33 deliberately broken packages ([spec/00 §0.4](../spec/00-introduction.md#04-status), [spec/22](../spec/22-conformance.md)).
|
||||
|
||||
## What does it not do?
|
||||
|
||||
|
||||
+16
-4
@@ -1,6 +1,6 @@
|
||||
# Glossary
|
||||
|
||||
A scientific paper changes after it is published: errata appear, readings get corrected, annotations pile up. paperspec is a set of file formats for scientific papers that keeps each sentence findable through those changes (repository: <https://git.scient.ing/infra/paperspec>).
|
||||
A scientific paper changes after it is published: errata appear, readings get corrected, annotations pile up. PaperSpec is a set of file formats for scientific papers that keeps each sentence findable through those changes (repository: <https://git.scient.ing/papers/paperspec>).
|
||||
This glossary defines its terms for readers from newcomer to expert, implementers included.
|
||||
Each entry gives the plain meaning, then the precise one, then the chapter that defines it.
|
||||
|
||||
@@ -44,6 +44,10 @@ Format `scienting-checkpoint/1`, `provisional`. ([23.2](../spec/23-log.md#232-ch
|
||||
Correction
|
||||
: An operation on an established document, with its evidence and author; never edited, only appended. ([11](../spec/11-corrections.md))
|
||||
|
||||
Data
|
||||
: What kind of data a table, a figure panel or a passage presents, tied to its words by a `data` annotation: one of fifteen kinds, the dataset that holds the values, what each field measures and the molecules and sequences it is about.
|
||||
The kind is one reader's reading and a model's stays `proposed`; where the values came from is the dataset's `origin`. ([18.8](../spec/18-layers.md#188-data))
|
||||
|
||||
Description
|
||||
: An annotation that describes a figure, panel or table for readers who cannot see it, as a short text equivalent (`alt`) or a full description (`long`); an accessible export uses confirmed descriptions only. ([18.4](../spec/18-layers.md#184-bodies))
|
||||
|
||||
@@ -79,7 +83,7 @@ History root
|
||||
JATS
|
||||
: Outside term.
|
||||
Journal Article Tag Suite, ANSI/NISO Z39.96-2024, an XML format in which publishers and archives exchange journal content ([the NISO page](https://www.niso.org/publications/z3996-2024-jats)).
|
||||
In paperspec, `jats` is a witness kind: the fixture `okafor2025solvent-acth` was established from a JATS file and a PDF that agree.
|
||||
In PaperSpec, `jats` is a witness kind: the fixture `okafor2025solvent-acth` was established from a JATS file and a PDF that agree.
|
||||
The formats ingest JATS and do not replace it. ([2.3](../spec/02-model.md#23-witnessesjson))
|
||||
|
||||
Keyed hash
|
||||
@@ -102,7 +106,7 @@ A complex-notation key is `notation:source` for a piece of math too complex for
|
||||
|
||||
Math form
|
||||
: A standard spelling of formulas, so that one formula is written alike in every paper and claim.
|
||||
`scienting-math/1` is canonical TeX, with a tree read from it and a key for each symbol; papermath implements it.
|
||||
`scienting-math/1` is canonical TeX, with a tree read from it and a key for each symbol; PaperMath implements it.
|
||||
An equation or math run in the form says so with `form`, which enters no hash, and its tree lives in `derived/math.jsonl`. ([3.7](../spec/03-nodes.md#37-math-forms), [9.4](../spec/09-figures-tables-equations.md#94-the-math-form))
|
||||
|
||||
ML-DSA-65
|
||||
@@ -165,6 +169,10 @@ In the W3C Web Annotation Data Model, the part of an annotation's target that sa
|
||||
The model defines `TextQuoteSelector` (exact text, with optional prefix and suffix) and `TextPositionSelector` (offsets, which the model calls very brittle), among others ([the W3C model](https://www.w3.org/TR/annotation-model/)).
|
||||
Layers use a custom `AnchorSelector`, which carries an anchor, followed by a `TextQuoteSelector` for tools that do not know it; they use neither `TextPositionSelector` nor `FragmentSelector`. ([18.3](../spec/18-layers.md#183-the-annotation))
|
||||
|
||||
Sequence
|
||||
: The residues of a protein, DNA or RNA, tied to the words that name, show or report a variant of them by a `sequence` annotation.
|
||||
Its identity is a hash of the residues with the gaps taken out, and its residues are numbered from the `start` the body gives, so a fragment is numbered as the whole molecule is. ([18.7](../spec/18-layers.md#187-sequences))
|
||||
|
||||
Spot-check
|
||||
: A second reviewer's check of a sample of a receipt's nodes, drawn from a seed nobody can steer: the checker's deterministic signature over the receipt's record hash. ([8.8](../spec/08-fidelity.md#88-spot-checks))
|
||||
|
||||
@@ -174,12 +182,16 @@ Stamp rule
|
||||
Strict projection
|
||||
: A node's text with notation folded to one canonical form and structure kept; used for certifying agreement. ([5.3](../spec/05-hashes.md#53-the-strict-projection))
|
||||
|
||||
Structure
|
||||
: A chemical structure tied to the words that name, draw, parametrize or use it by a `structure` annotation: a SMILES for a molecule, or a SMARTS for a group, a fragment with open positions or a pattern of atom types.
|
||||
Atoms are numbered from 0 in the order the text writes them, and the bonds, angles and torsions a paper gives constants for cite them by number. ([18.6](../spec/18-layers.md#186-chemical-structures))
|
||||
|
||||
Suspect
|
||||
: A doubtful reading raised for a person or a review session to answer. ([5.7](../spec/05-hashes.md#57-suspects))
|
||||
|
||||
Symbol key
|
||||
: The name of a symbol in a formula, its canonical TeX with `\mathrm` spelled `\text`: `K_{r}` for `K_r`.
|
||||
A paper's symbols and a paperclaim claim's have one key, so a `symbol` annotation names its symbol by it. ([9.4](../spec/09-figures-tables-equations.md#94-the-math-form), [18.4](../spec/18-layers.md#184-bodies))
|
||||
A paper's symbols and a PaperClaim claim's have one key, so a `symbol` annotation names its symbol by it. ([9.4](../spec/09-figures-tables-equations.md#94-the-math-form), [18.4](../spec/18-layers.md#184-bodies))
|
||||
|
||||
Targeted F3
|
||||
: Proofreading the nodes a team's claims, quotations and datasets rest on, rather than every node.
|
||||
|
||||
+9
-9
@@ -1,4 +1,4 @@
|
||||
# The paperspec formats
|
||||
# The PaperSpec formats
|
||||
|
||||
This page serves three readers.
|
||||
A student new to the problem will find each term defined where it first appears.
|
||||
@@ -15,7 +15,7 @@ Scientists who rely on a paper keep asking two questions.
|
||||
Where did this number come from, and how far was it checked? A force constant in a table, a value read off a plot, a parameter in a model: each should lead back to the cell or sentence it came from, with a record of who compared it with the page.
|
||||
|
||||
Most tools for scientific literature aggregate.
|
||||
They index hundreds of millions of papers and answer questions over all of them, shallowly. paperspec does the opposite.
|
||||
They index hundreds of millions of papers and answer questions over all of them, shallowly. PaperSpec does the opposite.
|
||||
|
||||
A team working on a focused question cares more about fifty papers it understands completely than about the world's literature.
|
||||
Those fifty papers deserve to be converted once, corrected once, split down to the sentence, annotated by the people who know them, linked to checked claims, and kept.
|
||||
@@ -24,8 +24,8 @@ A model can summarize a paper.
|
||||
It cannot give you a signed statement that a named person checked a passage, IDs that never move, or a store its owner controls.
|
||||
The formats supply those three, and they are worth most at the scale of one team.
|
||||
|
||||
paperspec is a set of file formats for scientific papers that have been converted, split into addressable pieces and checked.
|
||||
The repository is at <https://git.scient.ing/infra/paperspec>.
|
||||
PaperSpec is a set of file formats for scientific papers that have been converted, split into addressable pieces and checked.
|
||||
The repository is at <https://git.scient.ing/papers/paperspec>.
|
||||
It is version 0.1.0 and defines 32 formats; in [registry/formats.json](../registry/formats.json), 19 are `candidate` and 13 are `provisional`.
|
||||
|
||||
## Who it is for
|
||||
@@ -56,8 +56,8 @@ It appears inside hashed data and test vectors, and it is separate from the repo
|
||||
| [registry/](../registry/README.md) | The list of formats, the rule IDs a checker reports, download-stamp rules, and default rights requirements. |
|
||||
| [tools/](../tools/README.md) | How to run the reference commands: `paperspec check` checks everything, `paperspec build` rebuilds the fixtures and vectors, and `paperspec load` loads packages into SQLite. |
|
||||
| [src/paperspec/](../src/paperspec/) | The oracle, a compact implementation of every rule, which the other repositories of the project install as the Python package `paperspec`. |
|
||||
| [vectors/](../vectors/README.md) | 26 files of test vectors: inputs and the exact outputs every implementation must compute. |
|
||||
| [fixtures/](../fixtures/README.md) | Five valid example packages, one of them also as a zip, 31 deliberately broken ones that each break one named rule, example records, and the test keys that signed them. All text is synthetic. |
|
||||
| [vectors/](../vectors/README.md) | 29 files of test vectors: inputs and the exact outputs every implementation must compute. |
|
||||
| [fixtures/](../fixtures/README.md) | Five valid example packages, one of them also as a zip, 33 deliberately broken ones that each break one named rule, example records, and the test keys that signed them. All text is synthetic. |
|
||||
| [sql/](../sql/README.md) | Tables for SQLite, Dolt and PostgreSQL, and a SQLite bundle with full-text search. |
|
||||
| [context/](../context/README.md) | The JSON-LD context that makes annotation layers W3C Web Annotations. |
|
||||
| [docs/](README.md) | Guides, including this page. |
|
||||
@@ -131,12 +131,12 @@ The [specification's reading paths](../spec/README.md) say which chapters each r
|
||||
|
||||
## How it compares
|
||||
|
||||
paperspec adds to existing standards and replaces none of them. [The comparison page](comparison.md) has the full account; five points follow.
|
||||
PaperSpec adds to existing standards and replaces none of them. [The comparison page](comparison.md) has the full account; five points follow.
|
||||
|
||||
- JATS is the NISO standard by which [publishers and archives exchange journal content](https://www.niso.org/publications/z3996-2024-jats).
|
||||
Its [version 1.4 element list](https://jats.nlm.nih.gov/archiving/tag-library/1.4/) shows no sentence element.
|
||||
A JATS file is an input here (witness kind `jats`).
|
||||
- TEI has a [sentence-like element](https://tei-c.org/release/doc/tei-p5-doc/en/html/ref-s.html) and [markup that keeps both readings of a correction](https://tei-c.org/release/doc/tei-p5-doc/en/html/ref-corr.html), and recommends `xml:id` pointers ["for durability in the presence of editing"](https://tei-c.org/release/doc/tei-p5-doc/en/html/SA.html). paperspec mints and retires IDs by rule and keeps corrections as a separate, evidence-gated record.
|
||||
- TEI has a [sentence-like element](https://tei-c.org/release/doc/tei-p5-doc/en/html/ref-s.html) and [markup that keeps both readings of a correction](https://tei-c.org/release/doc/tei-p5-doc/en/html/ref-corr.html), and recommends `xml:id` pointers ["for durability in the presence of editing"](https://tei-c.org/release/doc/tei-p5-doc/en/html/SA.html). PaperSpec mints and retires IDs by rule and keeps corrections as a separate, evidence-gated record.
|
||||
TEI is built for encoding scholarly text in general, including correction markup within a text.
|
||||
- GROBID [converts PDFs to TEI](https://grobid.readthedocs.io/en/latest/Introduction/) and [reports F1 scores](https://grobid.readthedocs.io/en/latest/Introduction/) for its automatic reading.
|
||||
Its output can be held as one reading, under witness kind `xml`.
|
||||
@@ -145,7 +145,7 @@ paperspec adds to existing standards and replaces none of them. [The comparison
|
||||
The W3C model calls the `TextPositionSelector` ["very brittle"](https://www.w3.org/TR/annotation-model/) against changes to the resource, and the anchors here pin a hash instead.
|
||||
For annotation in general, use the W3C model.
|
||||
- Docling's [document schema](https://raw.githubusercontent.com/docling-project/docling-core/main/docs/DoclingDocument.json) refers to items by position (`#/texts/12`) and lists no per-item hash field.
|
||||
Docling is a conversion toolkit that, [by its own abstract](https://arxiv.org/abs/2501.17887), uses AI models for layout analysis and table structure recognition. paperspec defines no converter.
|
||||
Docling is a conversion toolkit that, [by its own abstract](https://arxiv.org/abs/2501.17887), uses AI models for layout analysis and table structure recognition. PaperSpec defines no converter.
|
||||
|
||||
The formats are at version 0.1.0, the repository names no outside adopter, and the reference tools belong to the same repository.
|
||||
The formats do not replace publisher interchange formats.
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
# Changelog
|
||||
|
||||
The changelog is one file, `CHANGELOG.md` at the root of the repository, so there is a single copy to keep in sync.
|
||||
It is published with the format documentation at <https://paperspec.scient.ing/CHANGELOG.html>, and the source is at <https://git.scient.ing/papers/paperspec/src/branch/main/CHANGELOG.md>.
|
||||
|
||||
Its top-level headings are the versions of the formats, and a release of the Python package that changes only the code is a subsection under the current format version, as `### 0.1.1` sits under `## 0.1.0`.
|
||||
The package version comes from the git tag; the format version is the one `CHANGELOG.md` and `pixi.toml` state.
|
||||
When a release is tagged, the publish workflow takes the release notes from the section whose heading contains the version.
|
||||
@@ -0,0 +1,36 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,14 @@
|
||||
# License
|
||||
|
||||
PaperSpec is not under Scienting's usual license.
|
||||
Because the formats are meant to be implemented by anyone, in any product, without asking, each path of the repository keeps the license that `LICENSE.md` gives it.
|
||||
|
||||
| Paths | License | SPDX |
|
||||
| --- | --- | --- |
|
||||
| `spec/`, `docs/`, `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md` and the other prose | Creative Commons Attribution 4.0 International | `CC-BY-4.0` |
|
||||
| `schemas/`, `sql/`, `context/`, `registry/`, `vectors/`, `fixtures/` | Creative Commons Zero 1.0 Universal | `CC0-1.0` |
|
||||
| `src/` (the `paperspec` package and its commands), `tests/`, `tools/` | Apache License 2.0 | `Apache-2.0` |
|
||||
|
||||
Python source files open with an `SPDX-License-Identifier: Apache-2.0` header, which ruff checks.
|
||||
All text in the fixtures is synthetic, and the keys in `fixtures/keys/` are public test keys that must never sign anything else.
|
||||
The full text is in `LICENSE.md` at the root of the repository, <https://git.scient.ing/papers/paperspec/src/branch/main/LICENSE.md>.
|
||||
@@ -0,0 +1,14 @@
|
||||
# LLM assistance
|
||||
|
||||
Large language models (Anthropic's Claude, through Claude Code) write much of this code, its tests and its documentation, and we do not hide it.
|
||||
The repository is built so that this is safe to rely on.
|
||||
|
||||
- **A person reviews every change.** A model proposes a commit; it does not decide one.
|
||||
- **Checks gate the code.** `pixi run check` runs the formatter, the linter with the full rule set, the type checker, the Markdown lint, the pytest suite and the repository's own checker, `paperspec check`.
|
||||
CI runs the same, with branch coverage that fails under 90%, and the stress test.
|
||||
- **The oracle checks itself.** Every expected value in the vectors and fixtures is computed by the code and rebuilt byte for byte, so a change that alters a computed value shows up as a changed file in the diff.
|
||||
- **Assisted commits are marked.** Each carries a `Co-Authored-By` trailer naming the model, and a `Claude-Session` trailer linking the session.
|
||||
- **Claude's working material stays out of the repository.** Plans, notes and review reports live in an untracked `work/` folder.
|
||||
|
||||
The specification is the authority.
|
||||
Where a model's code and a chapter disagree, the chapter wins and the code is the bug.
|
||||
@@ -0,0 +1,51 @@
|
||||
# Check and rebuild the repository
|
||||
|
||||
Four commands work on a checkout of the PaperSpec repository, not on an installed package: `check`, `build`, `stress` and `site`.
|
||||
The checkout is the one an editable install points at, or else the one around the current folder.
|
||||
|
||||
## Check everything
|
||||
|
||||
```sh
|
||||
paperspec check
|
||||
```
|
||||
|
||||
The checker validates every schema, record and package, confirms that every broken package is refused for the stated reason, recomputes every test vector, rebuilds everything and compares it byte for byte, loads every package into SQLite and back, and checks the prose, the links and the website.
|
||||
Each section prints how many checks it ran, and a passing run ends with `All checks pass.`
|
||||
The exit status is 0 when every check passed and 1 otherwise.
|
||||
|
||||
`paperspec check --quick` skips the byte-for-byte rebuild, the slowest part.
|
||||
The command does not run the Python code checks or the Markdown lint; `pixi run check` runs those first ([Install](../start/install.md#the-pixi-tasks)).
|
||||
|
||||
## Rebuild the vectors and fixtures
|
||||
|
||||
No expected value in the repository is typed by hand.
|
||||
The vectors and fixtures are computed from the hand-written sources in `fixtures/src/` and the cases the builder defines in `src/paperspec/cli/build.py`.
|
||||
After you change a rule in the code, a fixture source or a case, rebuild and commit the regenerated files with the change:
|
||||
|
||||
```sh
|
||||
paperspec build
|
||||
```
|
||||
|
||||
`paperspec build --out DIR` builds elsewhere, so you can compare with `diff -r DIR/vectors vectors` before overwriting anything.
|
||||
The build is deterministic, and `paperspec check` proves it by rebuilding into a temporary folder and comparing every file.
|
||||
|
||||
## Stress the oracle
|
||||
|
||||
```sh
|
||||
paperspec stress --rounds 5
|
||||
```
|
||||
|
||||
The vectors pin values; `stress` checks the invariants the chapters state, such as canonical JSON round trips and the zip reader never writing outside its folder, on random inputs from a seeded generator.
|
||||
A failure prints its seed, so `paperspec stress --seed SEED` reproduces it.
|
||||
The defaults are the seed 20261014 and 200 cases per property.
|
||||
Before a release, run it with the default seed and with one or two others.
|
||||
|
||||
## Build the website
|
||||
|
||||
```sh
|
||||
paperspec site --out /tmp/paperspec-site
|
||||
```
|
||||
|
||||
The site mirrors the repository: each file is served at its own path, each Markdown file gets a rendered page beside it, and the schemas are at the addresses in their `$id`.
|
||||
It needs only the standard library.
|
||||
The pages you are reading are a separate site, built with Zensical by `pixi run -e docs docs-build`.
|
||||
@@ -0,0 +1,12 @@
|
||||
# Guides
|
||||
|
||||
Each guide takes one task from start to finish, with commands that were run against the repository's synthetic fixtures.
|
||||
|
||||
| Guide | For |
|
||||
| --- | --- |
|
||||
| [Validate a package](validate-a-package.md) | Check a package folder or a zipped package against every rule, and try a proposed correction without writing it. |
|
||||
| [Load packages into SQLite](load-into-sqlite.md) | Put packages in a database you can query, or build a bundle with full-text search. |
|
||||
| [Use the library](use-the-library.md) | Compute hashes and identifiers, read a package and run the gate from Python. |
|
||||
| [Check and rebuild the repository](check-and-build.md) | Run the repository's checks, regenerate the vectors and fixtures, stress the oracle and build the website. |
|
||||
|
||||
The formats themselves are explained in the guides at <https://paperspec.scient.ing/docs/>.
|
||||
@@ -0,0 +1,46 @@
|
||||
# Load packages into SQLite
|
||||
|
||||
`paperspec load` validates packages and loads them into a SQLite database with the tables of `sql/doc.sql` and `sql/store.sql`.
|
||||
A node, a reference, a correction and a receipt each get rows you can join and query.
|
||||
|
||||
## Load a package
|
||||
|
||||
```sh
|
||||
paperspec load --sqlite lab.db fixtures/packages/hale2026harmonic-damb
|
||||
```
|
||||
|
||||
```text
|
||||
hale2026harmonic-damb: 75 nodes
|
||||
```
|
||||
|
||||
- Every package is validated first, and nothing is loaded if any fails.
|
||||
Each failure is printed as `package: where: rule: message`, as `paperspec validate` prints it.
|
||||
- A new file gets the tables, and an existing one takes more packages, so you can add papers to the same database later.
|
||||
- Files with no table of their own (assets, datasets, derived files) are copied by SHA-256 into a folder beside the database, `lab.db.assets/`, which must travel with it.
|
||||
- The full and checks-only forms of one document share its key, so load them into separate databases.
|
||||
|
||||
## Query it
|
||||
|
||||
```sh
|
||||
python -m sqlite3 lab.db "SELECT kind, COUNT(*) FROM nodes GROUP BY kind ORDER BY 2 DESC, kind LIMIT 3"
|
||||
```
|
||||
|
||||
```text
|
||||
('cell', 23)
|
||||
('sentence', 18)
|
||||
('row', 6)
|
||||
```
|
||||
|
||||
The guide at <https://paperspec.scient.ing/docs/examples.html> has queries to start from: the sentences still below fidelity F2, the citation graph at sentence level, and who signed what.
|
||||
|
||||
## Build a bundle with full-text search
|
||||
|
||||
```sh
|
||||
paperspec load --sqlite search.db --bundle --built-from REV paper/ other/
|
||||
```
|
||||
|
||||
A bundle is a `scienting-bundle/1` file: it also gets the tables of `sql/bundle-sqlite.sql`, the full-text search index and `bundle_meta`.
|
||||
It is built once, into a file that does not exist yet.
|
||||
`--bundle` needs `--built-from`, which names the store revision the packages come from, and the command prints the number of search rows it added.
|
||||
`--store` names the store, and defaults to the packages' common store.
|
||||
`--built-from` and `--store` are refused without `--bundle`.
|
||||
@@ -0,0 +1,66 @@
|
||||
# Use the library
|
||||
|
||||
The modules of `paperspec` compute every value the formats define, so a program that writes or reads packages can import them instead of reimplementing the specification.
|
||||
Every module imports with the standard library alone.
|
||||
Schema validation needs `paperspec[schema]`, and Ed25519 and HKDF need `paperspec[crypto]`; `paperspec[tools]` installs both ([Install](../start/install.md)).
|
||||
|
||||
## Canonical JSON and hashes
|
||||
|
||||
`jcs.dumps` writes the canonical JSON the formats hash and store: sorted keys, no spaces, and numbers written as an ECMAScript engine would.
|
||||
`text.sha256_hex` hashes a string, and `text.norm` applies the normalization the five hashes start from.
|
||||
|
||||
```python
|
||||
from paperspec import jcs, text
|
||||
|
||||
print(jcs.dumps({"b": 1.0, "a": [2, "é"]}))
|
||||
print(text.norm("a b\n c"))
|
||||
print(text.sha256_hex("The two parameter sets agree to within 2% for every bond."))
|
||||
```
|
||||
|
||||
```text
|
||||
{"a":[2,"é"],"b":1}
|
||||
a b c
|
||||
175bfc8867816a9761fd5bb9ffc956df6d9e7f203870961a5485fc1912cb663a
|
||||
```
|
||||
|
||||
## Validate a package
|
||||
|
||||
`package.validate` checks a package folder against every rule and returns a report whose `errors` list is empty when the package is valid.
|
||||
The schema store reads the schemas from wherever the package carries them, in an installed wheel or at the root of a checkout.
|
||||
|
||||
```python
|
||||
from paperspec import package, resources
|
||||
from paperspec.schema import Store
|
||||
|
||||
store = Store(resources.path("schemas"))
|
||||
report = package.validate("fixtures/packages/hale2026harmonic-damb", store)
|
||||
print(bool(report), report.errors)
|
||||
```
|
||||
|
||||
```text
|
||||
True []
|
||||
```
|
||||
|
||||
Each entry of `errors` is a dictionary with `rule`, `where` and `message`, the three fields `paperspec validate` prints.
|
||||
|
||||
## Read a package and run the gate
|
||||
|
||||
`package.read_state` reads a package folder into a state that holds its nodes, and `corrections.gate` runs a proposed correction against it without changing it.
|
||||
It returns the state the correction would produce and the record it would append, or raises `tree.Refusal`, which names the rule broken.
|
||||
|
||||
```python
|
||||
from paperspec import corrections, package, resources
|
||||
from paperspec.schema import Store
|
||||
|
||||
state = package.read_state("fixtures/packages/tiny2026tiny-j4qm")
|
||||
store = Store(resources.path("schemas"))
|
||||
new_state, record = corrections.gate(state, proposal, store)
|
||||
```
|
||||
|
||||
Here `proposal` is a parsed correction such as the one in [Validate a package](validate-a-package.md).
|
||||
|
||||
## Check your own code against the vectors
|
||||
|
||||
The vectors travel with the package as the data subpackage `paperspec.vectors`, and `resources.path("vectors")` finds the folder in an installed wheel and in an editable install alike.
|
||||
Four of them, `resolve.jsonl`, `grading.jsonl`, `targets.jsonl` and `traces.jsonl`, name a fixture package, and the fixtures stay in the repository.
|
||||
The [reference](../reference/api.md) lists the modules.
|
||||
@@ -0,0 +1,56 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,22 @@
|
||||
# PaperSpec
|
||||
|
||||
PaperSpec is the reference implementation of the scienting formats, the files in which a team stores its scientific papers once, corrects them once and addresses them down to the sentence.
|
||||
This site documents the Python package `paperspec` and its command.
|
||||
The formats themselves, with the specification, schemas, test vectors and fixtures, are published at <https://paperspec.scient.ing>.
|
||||
|
||||
The package is an oracle: a plain program whose answers count as the expected ones.
|
||||
Every hash, identifier, canonical JSON string, package check and database form in the repository is computed by this code, and no expected value in a test vector is typed by hand.
|
||||
It favors clarity over speed, and it is not a production reader or writer.
|
||||
|
||||
## Who it is for
|
||||
|
||||
- **A developer writing a reader, writer, converter or store** installs the package to validate their output against every rule, and to compute the values their own code must match.
|
||||
- **A researcher or editor with a package** uses the `paperspec` command to validate it, to try a proposed correction without writing it, and to load it into SQLite and query it.
|
||||
- **A maintainer of the formats** uses the command to rebuild the vectors and fixtures, and to check the whole repository.
|
||||
|
||||
## Where to go next
|
||||
|
||||
- [Get started](start/index.md): install the package and run a first command.
|
||||
- [Guides](guides/index.md): validate a package, load it into SQLite, use the library from Python, and check and rebuild the repository.
|
||||
- [Reference](reference/index.md): every command and option, and the library's modules.
|
||||
- [About](about/index.md): status, design commitments and known limits.
|
||||
@@ -0,0 +1,101 @@
|
||||
# Python API
|
||||
|
||||
The package `paperspec` is a set of small modules, one for each part of the specification, and each opens with a docstring that says what it is for.
|
||||
This page is written by hand from those docstrings and lists the modules and the functions most programs call; `help(paperspec.MODULE)` has the rest.
|
||||
The base package needs only the standard library.
|
||||
`schema` needs `paperspec[schema]`, and the Ed25519 and HKDF functions of `crypto` need `paperspec[crypto]`; both import their packages on first use.
|
||||
|
||||
Two aliases are shared by the type annotations: `jsontypes.Record`, one parsed JSON object, and `jsontypes.StrPath`, a path given as text or as a path object.
|
||||
A function that takes a path returns text unless its docstring says otherwise.
|
||||
A rule that is broken raises `tree.Refusal`, whose `rule` attribute names the rule as the specification's conformance chapter lists it.
|
||||
|
||||
`paperspec.resources.path(name)` returns the folder `schemas`, `sql`, `vectors`, `registry` or `context`, in an installed wheel and in a checkout alike, and `fixtures` in a checkout or an editable install of one.
|
||||
`paperspec.resources.registry(name)` reads a registry file by its path under `registry/`, such as `rules.json` or `stamps/scienting-stamps-1.json`.
|
||||
|
||||
## Text, hashes and canonical JSON
|
||||
|
||||
| Module | For | Main functions |
|
||||
| --- | --- | --- |
|
||||
| `text` | Normalization, IDs and small helpers shared by the rest. | `norm`, `sha256_hex`, `collapse_ws`, `digits`, `letter_first`, `mint_node_id`, `record_id`, `cp_to_utf16` |
|
||||
| `jcs` | Canonical JSON, RFC 8785. | `dumps`, `dumpb`, `loads`, `loads_line`, `parse_int` |
|
||||
| `hashing` | The plain, strict and lossy projections of a node, and its five content values. | `compute`, `plain`, `strict`, `strict_runs`, `lossy`, `lossy_from_strict`, `own_content`, `meta_hash`, `Hasher`, `Index` |
|
||||
| `notation` | Simple math notation and its canonical linear form. | `fold_math`, `complex_key`, `fold_plain_text` |
|
||||
| `keys` | Work and document keys. | `work_key`, `unique_work_key`, `document_key`, `split_key` |
|
||||
|
||||
## The document
|
||||
|
||||
| Module | For | Main functions |
|
||||
| --- | --- | --- |
|
||||
| `model` | The node tree of `scienting-doc/1`. | `Doc`, `anchor_class`, the tables of allowed children and attributes |
|
||||
| `tree` | Establishing a document from a nested tree, and the structural checks. | `establish`, `establish_with_side`, `flatten`, `mint_ids`, `validate_structure`, `validate_references`, `Refusal` |
|
||||
| `anchors` | Addresses, anchors and their resolution. | `parse_address`, `format_address`, `make_anchor`, `resolve`, `resolve_address`, `follow` |
|
||||
| `align` | Alignment of two readings of one paper. | `align`, `classify`, `similarity` |
|
||||
| `fingerprint` | Page fingerprints and download-stamp rules. | `fingerprint`, `is_stamp`, `published_rules` |
|
||||
| `targets` | The target set of targeted F3. | `target_set` |
|
||||
|
||||
## Packages, corrections and the database
|
||||
|
||||
| Module | For | Main functions |
|
||||
| --- | --- | --- |
|
||||
| `package` | Writing, reading and validating a package folder or a zipped package. | `validate`, `validate_zip`, `check_forms`, `read_state`, `write`, `write_zip`, `read_zip`, `read_zip_files`, `check_zip_entries`, `read_json`, `read_jsonl`, `parse_json`, `parse_jsonl` |
|
||||
| `corrections` | The correction gate and the state it works on. | `gate`, `apply`, `State`, `OPS`, `KEEPS_LEVEL` |
|
||||
| `revision` | Applying corrections to a package and writing the package they make. | `revise`, `revise_zip`, `revise_files`, `summarize`, `level_after`, `Refused`, `Invalid` |
|
||||
| `datasets` | A package's datasets, checked against its text. | `problems`, `content_hash`, `folders` |
|
||||
| `schema` | JSON Schema validation with the keyword subset the schemas are restricted to. | `Store`, `validate`, `lint` |
|
||||
| `db` | The database form. | `create`, `create_bundle`, `load`, `unload`, `read_state`, `delete`, `load_layer`, `upgrade`, `index` |
|
||||
|
||||
## Signatures, receipts and the log
|
||||
|
||||
| Module | For | Main functions |
|
||||
| --- | --- | --- |
|
||||
| `crypto` | Keyed hashing, Merkle roots and proofs, Ed25519, HKDF and `did:key`. | `merkle_root`, `inclusion_path`, `verify_inclusion`, `consistency_proof`, `verify_consistency`, `ed25519_sign`, `ed25519_verify`, `did_key` |
|
||||
| `receipts` | Receipts, revocations, levels and spot-check sampling. | `seal`, `verify_signature`, `statuses`, `effective_levels`, `sample`, `upper_bound` |
|
||||
| `log` | The team's transparency log and its signed checkpoints. | `sign_checkpoint`, `verify_checkpoint`, `write_log`, `read_log` |
|
||||
| `vrf` | ECVRF-EDWARDS25519-SHA512-TAI, RFC 9381. | `prove`, `verify`, `proof_to_hash` |
|
||||
| `mldsa` | ML-DSA-65, FIPS 204, in plain Python. | `keygen`, `sign`, `verify` |
|
||||
|
||||
## Layers, rights and grading
|
||||
|
||||
| Module | For | Main functions |
|
||||
| --- | --- | --- |
|
||||
| `rights` | Rights records, policies and stage checks. | `effective`, `combine`, `check`, `backend_allowed` |
|
||||
| `layers` | What every annotation shares: its record ID, its anchors and the lists its fields take. | `annotation_id`, `anchors_of`, `BODY_KINDS`, `CATEGORIES`, `VERDICTS`, `STATUSES` |
|
||||
| `claims` | References to PaperClaim claims and their pins. | `parse_ref`, `parse_pin`, `format_ref`, `format_pin` |
|
||||
| `traces` | Traced citations. | `resolve`, `problems`, `disputed` |
|
||||
| `structures` | Chemical structures tied to words. | `scan`, `problems` |
|
||||
| `sequences` | Biological sequences tied to words. | `residues`, `problems` |
|
||||
| `data` | Data tied to words. | `problems` |
|
||||
| `grade` | Grading a submission against an exercise key. | `grade`, `key_anchors` |
|
||||
|
||||
The `problems` functions of the four annotation modules return the rules an annotation breaks, as a list of `{"rule", "message"}` records in the order checked.
|
||||
|
||||
## Correcting a package
|
||||
|
||||
`revision.revise(root, proposals, store)` validates the package folder at `root`, runs each proposed correction through the gate in order, and writes the corrected package in place, or to `out` when it is given; `revision.revise_zip` does the same for a zipped package.
|
||||
Nothing is written unless every proposal passes and the package written validates.
|
||||
The writer recomputes every node's values and `document.json`, and records the corrections, the retired IDs and the resolved references.
|
||||
A leaf a correction changed is F1 when the correction's evidence includes a crop of the page and F0 otherwise, and is no longer corroborated; an `emend`, `relink` or `resolve` keeps its level ([spec/08 §8.1](https://paperspec.scient.ing/spec/08-fidelity.html#81-levels-of-fidelity)).
|
||||
A merged node's boxes go to the node it merged into, suspects at removed nodes and those named in `answered` leave `suspects.jsonl`, and the lines of `derived/` files and the datasets that read corrected text are left out and reported, since only the tools that made them can rebuild them ([spec/12 §12.7](https://paperspec.scient.ing/spec/12-package.html#127-derived-files)).
|
||||
With no proposals, the package written is the package read, byte for byte.
|
||||
|
||||
```python
|
||||
from paperspec import resources, revision
|
||||
from paperspec.schema import Store
|
||||
|
||||
result = revision.revise("paper/", [proposal], Store(resources.path("schemas")))
|
||||
result["rev"], result["package"], result["dropped"]
|
||||
```
|
||||
|
||||
A proposal the gate refuses raises `revision.Refused`, with the proposal's `index` and the `rule` it breaks, and a package that does not validate raises `revision.Invalid` with its errors.
|
||||
`revision.revise_files` works on a package held in memory, as `{path: bytes}`, and `revision.summarize` recomputes what `document.json` derives from the nodes, for a producer that writes packages itself.
|
||||
|
||||
## Math forms
|
||||
|
||||
`package.validate` reports `doc.math.form` for a source with `form` that is not the form's own spelling ([spec/03 §3.7](https://paperspec.scient.ing/spec/03-nodes.html#37-math-forms)).
|
||||
Without help it knows only what `scienting-math/1` never holds, a `\tag`, `\label`, `\nonumber`, `\notag`, style command, `\dfrac` or `\tfrac`; with PaperMath installed it spells every source again and requires it back unchanged.
|
||||
Pass `forms={}` to check only the first, or a mapping from a form to a function that spells a source in it.
|
||||
|
||||
## The command
|
||||
|
||||
`paperspec.cli` holds the subcommands of the `paperspec` command, one module each, with a `run(args)` function that returns the exit status; see [Command line](cli.md).
|
||||
`cli.checkout()` finds the repository root that `check`, `build`, `stress` and `site` work on.
|
||||
@@ -0,0 +1,103 @@
|
||||
# Command line
|
||||
|
||||
One command, `paperspec`, with seven subcommands.
|
||||
`python -m paperspec` runs the same program.
|
||||
`paperspec --version` prints the package version and the Unicode version it pins, and `paperspec COMMAND --help` prints a command's options, advice and examples.
|
||||
|
||||
| Command | Works | Does |
|
||||
| --- | --- | --- |
|
||||
| [`validate`](#validate) | anywhere the package is installed with its `tools` extra | Validate packages, or run proposed corrections through the gate. |
|
||||
| [`correct`](#correct) | anywhere the package is installed with its `tools` extra | Apply proposed corrections to a package and write the corrected package. |
|
||||
| [`load`](#load) | anywhere the package is installed with its `tools` extra | Validate packages and load them into a SQLite database. |
|
||||
| [`check`](#check) | in a checkout | Check the whole repository. |
|
||||
| [`build`](#build) | in a checkout | Rebuild `fixtures/` and `vectors/` from their sources. |
|
||||
| [`stress`](#stress) | in a checkout | Stress the oracle with random inputs. |
|
||||
| [`site`](#site) | in a checkout | Build the website into `_site/`. |
|
||||
|
||||
A misspelled command gets a suggestion, and an option a command does not know is refused.
|
||||
"In a checkout" means the repository an editable install points at, or else the one around the current folder.
|
||||
|
||||
## validate
|
||||
|
||||
```text
|
||||
paperspec validate [-h] [--correction PROPOSALS] [--max-size BYTES] PACKAGE [PACKAGE ...]
|
||||
```
|
||||
|
||||
| Option | Meaning |
|
||||
| --- | --- |
|
||||
| `PACKAGE` | A package folder or a zipped package (`.sct.zip`), unpacked under the specification's path rules first. |
|
||||
| `--correction PROPOSALS` | A JSON file holding one proposed correction, or a JSON Lines file of several, run through the gate against the one package given. Each record that would be appended to `corrections.jsonl` is printed, until one is refused. Nothing is written. |
|
||||
| `--max-size BYTES` | Refuse a zipped package that expands past this many bytes (default 1073741824). |
|
||||
|
||||
Each failure is printed to standard error as `package: where: rule: message`.
|
||||
Exit status: 0 when everything is valid, 1 when something is refused, 2 for a usage error.
|
||||
|
||||
## correct
|
||||
|
||||
```text
|
||||
paperspec correct [-h] --correction PROPOSALS [--out PATH] [--answered SUSPECT] [--asset FILE] [--max-size BYTES] PACKAGE
|
||||
```
|
||||
|
||||
| Option | Meaning |
|
||||
| --- | --- |
|
||||
| `PACKAGE` | A package folder or a zipped package. It is validated first. |
|
||||
| `--correction PROPOSALS` | A JSON file holding one proposed correction, or a JSON Lines file of several, applied in order. Nothing is written unless every one passes the gate. |
|
||||
| `--out PATH` | Write the corrected package here, a folder, or a zip for a zipped package, which must not exist. By default `PACKAGE` is replaced. |
|
||||
| `--answered SUSPECT` | The ID of a suspect the corrections answer, which leaves `suspects.jsonl`. Repeat for several. |
|
||||
| `--asset FILE` | A file to add under `assets/` as `<sha256>.<extension>`, such as a crop a correction's evidence names. Repeat for several. |
|
||||
| `--max-size BYTES` | As for `validate`. |
|
||||
|
||||
The corrected package is validated before it replaces anything.
|
||||
Each record appended to `corrections.jsonl` is printed, one per line; standard error names the derived lines and datasets left out because they read corrected text, and ends with the document's new revision and package hash.
|
||||
A refusal is printed as `validate` prints it, and nothing is written.
|
||||
Exit status: 0 when the corrections were applied, 1 when the package or a proposal is refused, 2 for a usage error.
|
||||
|
||||
## load
|
||||
|
||||
```text
|
||||
paperspec load [-h] --sqlite DATABASE [--bundle] [--built-from REV] [--store STORE] [--max-size BYTES] PACKAGE [PACKAGE ...]
|
||||
```
|
||||
|
||||
| Option | Meaning |
|
||||
| --- | --- |
|
||||
| `PACKAGE` | A package folder or a zipped package. Every package is validated first, and nothing is loaded if any fails. |
|
||||
| `--sqlite DATABASE` | The database file, created with the tables of `sql/` if it does not exist. Files with no table of their own are copied into `DATABASE.assets/`. |
|
||||
| `--bundle` | Build a new `scienting-bundle/1` file with the full-text search index. Needs `--built-from`. |
|
||||
| `--built-from REV` | With `--bundle`: the store revision the packages come from. |
|
||||
| `--store STORE` | With `--bundle`: the store's name (default: the packages' common store). |
|
||||
| `--max-size BYTES` | As for `validate`. |
|
||||
|
||||
## check
|
||||
|
||||
```text
|
||||
paperspec check [-h] [--quick]
|
||||
```
|
||||
|
||||
`--quick` skips the byte-for-byte rebuild.
|
||||
Exit status: 0 when every check passed, 1 otherwise.
|
||||
|
||||
## build
|
||||
|
||||
```text
|
||||
paperspec build [-h] [--out DIR]
|
||||
```
|
||||
|
||||
Without `--out` it rewrites `fixtures/` and `vectors/` in the checkout; with it, it builds into `DIR` instead.
|
||||
|
||||
## stress
|
||||
|
||||
```text
|
||||
paperspec stress [-h] [--seed SEED] [--rounds ROUNDS]
|
||||
```
|
||||
|
||||
`--seed` sets the random seed (default 20261014) and `--rounds` the cases per property (default 200).
|
||||
Exit status: 0 when every property held, 1 otherwise.
|
||||
|
||||
## site
|
||||
|
||||
```text
|
||||
paperspec site [-h] [--out DIR] [--base-url URL]
|
||||
```
|
||||
|
||||
`--out` sets the output folder, which must not be the repository or contain it (default `_site/` in the checkout).
|
||||
`--base-url` sets the site's address for canonical links (default `https://paperspec.scient.ing`).
|
||||
@@ -0,0 +1,6 @@
|
||||
# Reference
|
||||
|
||||
- [Command line](cli.md): the `paperspec` command, its six subcommands and every option.
|
||||
- [Python API](api.md): the modules of the package and what each is for.
|
||||
|
||||
The formats the code implements are specified at <https://paperspec.scient.ing/spec/>, and the JSON Schemas, SQL and test vectors are at the same address.
|
||||
@@ -0,0 +1,9 @@
|
||||
# Get started
|
||||
|
||||
Two pages take you from nothing to a result.
|
||||
|
||||
1. [Install](install.md) the package from Scienting's package registry, or work from a checkout.
|
||||
2. [Quick start](quick-start.md) validates the example paper and loads it into a database.
|
||||
|
||||
The package needs Python 3.14.
|
||||
It is the only version with the Unicode 16.0 character data the specification pins, and the package refuses to import on any other.
|
||||
@@ -0,0 +1,74 @@
|
||||
# Install
|
||||
|
||||
The package needs Python 3.14.
|
||||
Its base install has no dependencies: every module imports with the standard library alone.
|
||||
Three extras add what some modules need:
|
||||
|
||||
| Extra | Adds | Needed by |
|
||||
| --- | --- | --- |
|
||||
| `schema` | `jsonschema`, `referencing` | schema validation, so `package.validate` and `corrections.gate` |
|
||||
| `crypto` | `cryptography` | Ed25519 signatures and HKDF in `crypto`, which the signature and receipt checks use |
|
||||
| `tools` | both of the above | the `paperspec` command, and any program that validates packages |
|
||||
|
||||
## From Scienting's package registry
|
||||
|
||||
The registry does not mirror PyPI, so an installer needs two indexes: the registry for `paperspec`, and PyPI for `jsonschema`, `referencing` and `cryptography`.
|
||||
Tie `paperspec` to the registry wherever the installer allows it, so that a package of the same name on PyPI is never chosen instead.
|
||||
`[CHECK: no version tag has been pushed yet, so the registry holds no release until the first tag is published]`
|
||||
|
||||
With pixi, in `pixi.toml`:
|
||||
|
||||
```toml
|
||||
[pypi-dependencies]
|
||||
paperspec = { version = ">=0.1.1", extras = ["tools"], index = "https://git.scient.ing/api/packages/papers/pypi/simple" }
|
||||
```
|
||||
|
||||
With uv, in `pyproject.toml`:
|
||||
|
||||
```toml
|
||||
[[tool.uv.index]]
|
||||
name = "scienting"
|
||||
url = "https://git.scient.ing/api/packages/papers/pypi/simple"
|
||||
explicit = true
|
||||
|
||||
[tool.uv.sources]
|
||||
paperspec = { index = "scienting" }
|
||||
```
|
||||
|
||||
With pip, which cannot tie a package to an index and takes the highest version from either:
|
||||
|
||||
```sh
|
||||
pip install --index-url https://git.scient.ing/api/packages/papers/pypi/simple/ --extra-index-url https://pypi.org/simple/ "paperspec[tools]"
|
||||
```
|
||||
|
||||
If the organization or the package is private, the installer also needs a token with the `read:package` scope, for example in a `~/.netrc` entry for `git.scient.ing`.
|
||||
|
||||
## From a checkout
|
||||
|
||||
Clone the repository and let pixi set up a pinned environment, with the package installed editable:
|
||||
|
||||
```sh
|
||||
git clone https://git.scient.ing/papers/paperspec
|
||||
pixi install
|
||||
pixi run check
|
||||
```
|
||||
|
||||
`pixi run check` runs the formatter, the linter, the type checker, the Markdown lint, the tests and the repository's own checker, and ends with `All checks pass.`
|
||||
Without pixi, install the checkout with `pip install -e ".[tools]" --group dev` on Python 3.14.
|
||||
|
||||
## The pixi tasks
|
||||
|
||||
| Task | Does |
|
||||
| --- | --- |
|
||||
| `check` | Every check CI runs, in order: `fmt-check`, `lint`, `typecheck`, `lint-md`, `test`, `verify`. |
|
||||
| `verify` | `paperspec check`, the repository's own checker. |
|
||||
| `quick` | `paperspec check --quick`, which skips the byte-for-byte rebuild. |
|
||||
| `fmt`, `fmt-check` | Format the code with ruff, or check the formatting. |
|
||||
| `lint`, `lint-fix` | Lint with ruff, or lint and apply the safe fixes. |
|
||||
| `typecheck` | Type-check `src/` with ty. |
|
||||
| `test`, `cov` | Run the pytest suite, or run it with branch coverage that fails under 90%. |
|
||||
| `lint-md` | Lint every Markdown file with markdownlint. |
|
||||
| `build`, `load`, `validate`, `stress`, `site` | The commands of the same names. |
|
||||
| `hooks` | Install the git pre-commit hooks. |
|
||||
| `docs-build`, `docs-serve` | Build these pages strictly into `build/docs`, or preview them. |
|
||||
| `dist` | Build the sdist and wheel into `dist/`. |
|
||||
@@ -0,0 +1,59 @@
|
||||
# Quick start
|
||||
|
||||
This page validates the repository's example paper, shows what a refusal looks like, and loads the paper into a database.
|
||||
Run every command from the root of a checkout (see [Install](install.md)); the example is a synthetic chemistry paper in `fixtures/packages/hale2026harmonic-damb`.
|
||||
|
||||
## Validate a package
|
||||
|
||||
```sh
|
||||
paperspec validate fixtures/packages/hale2026harmonic-damb
|
||||
```
|
||||
|
||||
```text
|
||||
fixtures/packages/hale2026harmonic-damb: valid
|
||||
```
|
||||
|
||||
The exit status is 0.
|
||||
A broken package prints one line per failure, as `package: where: rule: message`, and exits with status 1.
|
||||
The folder `fixtures/invalid/` holds packages that each break one named rule:
|
||||
|
||||
```sh
|
||||
paperspec validate fixtures/invalid/text-edited/package
|
||||
```
|
||||
|
||||
```text
|
||||
fixtures/invalid/text-edited/package: s0fn2fj: doc.hash.text-hash: text_hash does not recompute
|
||||
fixtures/invalid/text-edited/package: s0fn2fj: doc.hash.match-hash: match_hash does not recompute
|
||||
…
|
||||
```
|
||||
|
||||
Each rule ID, such as `doc.hash.text-hash`, is listed in <https://paperspec.scient.ing/registry/rules.json> with the chapter of the specification that states it.
|
||||
|
||||
## Load it into SQLite
|
||||
|
||||
```sh
|
||||
paperspec load --sqlite lab.db fixtures/packages/hale2026harmonic-damb
|
||||
```
|
||||
|
||||
```text
|
||||
hale2026harmonic-damb: 75 nodes
|
||||
```
|
||||
|
||||
The command validates the package first, creates `lab.db` with the tables of `sql/`, and loads the package.
|
||||
Query the result with any SQLite client; Python's own works:
|
||||
|
||||
```sh
|
||||
python -m sqlite3 lab.db "SELECT kind, COUNT(*) FROM nodes GROUP BY kind ORDER BY 2 DESC, kind LIMIT 3"
|
||||
```
|
||||
|
||||
```text
|
||||
('cell', 23)
|
||||
('sentence', 18)
|
||||
('row', 6)
|
||||
```
|
||||
|
||||
## Where next
|
||||
|
||||
- [Validate a package](../guides/validate-a-package.md), including how to try a correction without writing it.
|
||||
- [Load packages into SQLite](../guides/load-into-sqlite.md).
|
||||
- [Use the library](../guides/use-the-library.md) from Python.
|
||||
+2
-2
@@ -10,7 +10,7 @@ Experts find the cost of each choice and, where a neighboring standard chose dif
|
||||
|
||||
The formats are at version 0.1.0.
|
||||
Of the 29 in `registry/formats.json`, 19 are `candidate` and 13 are `provisional`, and the provisional ones are named where they appear.
|
||||
The repository is paperspec, at <https://git.scient.ing/infra/paperspec>.
|
||||
The repository is PaperSpec, at <https://git.scient.ing/papers/paperspec>.
|
||||
The `scienting-` prefix in format names such as `scienting-anchor/1` is the formats' namespace, separate from the repository's name.
|
||||
|
||||
## Identity
|
||||
@@ -41,7 +41,7 @@ A merge records its successor, a deletion records that there is none, and legacy
|
||||
A citation key such as `vaswani2017attention` is what readers say, and it collides: a preprint and its published version, or two papers by one first author in one year with the same first title word, would share it.
|
||||
Four characters of a hash of the work's identity, its DOI when it has one, settle the collision and let any tool holding the DOI recompute the key.
|
||||
The key is minted once and never recomputed, so a corrected title cannot change a name someone has cited; when two works still share four characters, the later one gets six ([spec/02 §2.4](../spec/02-model.md#24-work-and-document-keys)).
|
||||
The rule is the one the studio's reading-list tool already uses, so a paper keeps its key from the reading list to the store.
|
||||
The rule is the one Scienting's reading-list tool already uses, so a paper keeps its key from the reading list to the store.
|
||||
|
||||
### Identifiers are tag URIs
|
||||
|
||||
|
||||
+2
-2
@@ -7,7 +7,7 @@ Its problems are modeled on the failures that the specification's rules address.
|
||||
Three readers can use the guide, and each gets something different.
|
||||
A newcomer knows what a paper and a citation are, not hashes or JSON, so every term is defined where it first appears.
|
||||
An implementer who will write a reader, writer, converter or checker gets the chapter and test vector for each step.
|
||||
An expert gets the status: [paperspec](https://git.scient.ing/infra/paperspec) is at version 0.1.0, and each format is `candidate` or `provisional` in [`registry/formats.json`](../registry/formats.json) (19 candidate, 13 provisional).
|
||||
An expert gets the status: [PaperSpec](https://git.scient.ing/papers/paperspec) is at version 0.1.0, and each format is `candidate` or `provisional` in [`registry/formats.json`](../registry/formats.json) (19 candidate, 13 provisional).
|
||||
The `scienting-` prefix on format names, as in `scienting-doc/1`, is the formats' namespace.
|
||||
It has nothing to do with the repository's name.
|
||||
|
||||
@@ -132,7 +132,7 @@ The table shows how each anchor resolves at revision 12 ([vectors/resolve.jsonl]
|
||||
A reader shows each note by its result.
|
||||
A checker of exact words accepts only `current`, `moved` and `reattached`.
|
||||
|
||||
The [W3C Web Annotation Data Model](https://www.w3.org/TR/annotation-model/) is the general W3C Recommendation for annotating web resources. paperspec's annotation layers build on it, with a custom `AnchorSelector` followed by a standard `TextQuoteSelector` as a fallback.
|
||||
The [W3C Web Annotation Data Model](https://www.w3.org/TR/annotation-model/) is the general W3C Recommendation for annotating web resources. PaperSpec's annotation layers build on it, with a custom `AnchorSelector` followed by a standard `TextQuoteSelector` as a fallback.
|
||||
It has no permanent IDs for sentences inside the source, no hashes of the target text, and no results such as `moved` or drift.
|
||||
See [comparison.md](comparison.md).
|
||||
|
||||
|
||||
+14
-9
@@ -1,7 +1,7 @@
|
||||
# Fixtures
|
||||
|
||||
A reader, writer, converter or checker of stored papers needs files to test against, and a newcomer needs examples of what a stored paper looks like.
|
||||
This folder holds that example data of paperspec (<https://git.scient.ing/infra/paperspec>), version 0.1.0.
|
||||
This folder holds that example data of PaperSpec (<https://git.scient.ing/papers/paperspec>), version 0.1.0.
|
||||
All text is synthetic, written for these files and dedicated CC0; license fields inside the fixtures describe fictional works.
|
||||
|
||||
Three readers use these files.
|
||||
@@ -25,12 +25,12 @@ A conforming reader accepts each one and recomputes every hash it contains.
|
||||
|
||||
| Package | What it is for |
|
||||
| --- | --- |
|
||||
| `packages/hale2026harmonic/` | The main example, followed step by step in [the walkthrough](../docs/walkthrough.md): a chemistry paper that was read once with mistakes and then fixed by twelve corrections. It has a table with two levels of column headers and grouped rows, an equation inside a sentence, a footnote, a figure with text inside its panels and a real image, references, legacy aliases, boxes on fingerprinted pages, receipts in every state (counting, partly invalidated, spot-checked, revoked and suspended), the roster of public keys that checks their signatures, a dataset taken from the table, derived MathML, and the derived reading of three formulas in the math form `scienting-math/1`, one of which the form's tree cannot read ([spec/09 section 9.4](../spec/09-figures-tables-equations.md#94-the-math-form)). |
|
||||
| `packages/hale2026harmonic.checks-only/` | The same document prepared for sharing within the team: text withheld, every hash an HMAC (a hash computed under a secret key) under the team key. The team key is derived from the team secret in `keys/` ([spec/05](../spec/05-hashes.md), [spec/12 section 12.5](../spec/12-package.md#125-text-policies)). It shows how a team can share its checks on a paywalled paper without sharing the paper. |
|
||||
| `packages/okafor2025open/` | An open-access paper established from a JATS file (an XML format for journal articles) and a PDF that agree, so every leaf is at fidelity F2, corroborated by an independent witness. |
|
||||
| `packages/smithlab2027charges/` | A short draft written in Typst (a typesetting language). One of its sentences holds a cross-reference whose target is the address `hale2026harmonic#a4jrz2t`, a sentence of the main example. |
|
||||
| `packages/tiny2026example/` | A small document, the starting point of the correction vectors (`vectors/corrections.jsonl`) and of every broken package below. |
|
||||
| `packages/tiny2026example.sct.zip` | The same document as a zipped package, written the way a producer makes a byte-identical archive: entries under one folder named by the key, sorted by path, stored, dated 1980-01-01, with no extra fields ([spec/12 section 12.2](../spec/12-package.md#122-paths)). A reader unpacks it to exactly the folder beside it. |
|
||||
| `packages/hale2026harmonic-damb/` | The main example, followed step by step in [the walkthrough](../docs/walkthrough.md): a chemistry paper that was read once with mistakes and then fixed by twelve corrections. It has a table with two levels of column headers and grouped rows, an equation inside a sentence, a footnote, a figure with text inside its panels and a real image, references, legacy aliases, boxes on fingerprinted pages, receipts in every state (counting, partly invalidated, spot-checked, revoked and suspended), the roster of public keys that checks their signatures, a dataset taken from the table, derived MathML, and the derived reading of three formulas in the math form `scienting-math/1`, one of which the form's tree cannot read ([spec/09 section 9.4](../spec/09-figures-tables-equations.md#94-the-math-form)). |
|
||||
| `packages/hale2026harmonic-damb.checks-only/` | The same document prepared for sharing within the team: text withheld, every hash an HMAC (a hash computed under a secret key) under the team key. The team key is derived from the team secret in `keys/` ([spec/05](../spec/05-hashes.md), [spec/12 section 12.5](../spec/12-package.md#125-text-policies)). It shows how a team can share its checks on a paywalled paper without sharing the paper. |
|
||||
| `packages/okafor2025solvent-acth/` | An open-access paper established from a JATS file (an XML format for journal articles) and a PDF that agree, so every leaf is at fidelity F2, corroborated by an independent witness. |
|
||||
| `packages/writer2027fixed-ynr7.v3/` | A short draft written in Typst (a typesetting language). One of its sentences holds a cross-reference whose target is the address `hale2026harmonic-damb#a4jrz2t`, a sentence of the main example. |
|
||||
| `packages/tiny2026tiny-j4qm/` | A small document, the starting point of the correction vectors (`vectors/corrections.jsonl`) and of every broken package below. |
|
||||
| `packages/tiny2026tiny-j4qm.sct.zip` | The same document as a zipped package, written the way a producer makes a byte-identical archive: entries under one folder named by the key, sorted by path, stored, dated 1980-01-01, with no extra fields ([spec/12 section 12.2](../spec/12-package.md#122-paths)). A reader unpacks it to exactly the folder beside it. |
|
||||
|
||||
## Records
|
||||
|
||||
@@ -47,8 +47,11 @@ Each record is a single file, or a folder where a format needs several files.
|
||||
| `backend-docling.json`, `backend-examplevendor.json` | The code and weight licenses of a conversion tool and the conditions attached to them. |
|
||||
| `profile-acme.json`, `profile-smithlab.json` | What those conditions ask about a team: its purpose, its funding and whom it competes with. |
|
||||
| `roster.json` | The keys that may sign, the role of each key's holder in the team, and what each key may sign. Ana is the owner, so she may revoke anyone's receipt. |
|
||||
| `layer/` | A layer of annotations on the main example (`layer.json`, `annotations.jsonl`) and the receipt that confirms them (`receipt.json`). Its claim link and its symbol name the claim `amber/k-bond` of paperclaim's example store as paperclaim references it, `claim:272XTX7C`, pinned at `claim:272XTX7C@02f47b`; the symbol names `K_r` by its key, `K_{r}`. |
|
||||
| `layer/` | A layer of annotations on the main example (`layer.json`, `annotations.jsonl`) and the receipt that confirms them (`receipt.json`). Its claim link and its symbol name the claim `amber/k-bond` of PaperClaim's example store as PaperClaim references it, `claim:272XTX7C`, pinned at `claim:272XTX7C@02f47b`; the symbol names `K_r` by its key, `K_{r}`. |
|
||||
| `traces/` | A layer of traced citations on the Typst draft, which cites the main example (`layer.json`, `annotations.jsonl`, `receipt.json`): a trace a model proposed from the draft's citation of "a two-step fit" to the abstract of the main example and a person confirmed, with its receipt; a second candidate, the introduction's sentence, that a person rejected; a person's trace of the same sentence to Table 1; and a person's reply that disputes the first ([spec/18 §18.5](../spec/18-layers.md#185-traced-citations)). `vectors/traces.jsonl` resolves them after corrections. |
|
||||
| `chemistry/` | A layer of chemical structures on the main example (`layer.json`, `annotations.jsonl`, `receipt.json`): ethane, named in the methods and confirmed; water, named by a model and still `proposed`; the CT–CT pattern of Table 1, a SMARTS with the bond constants of both parameter sets as terms; and water again as a SMILES that writes its hydrogens, with the OW–HW bond constants. The two writings of water share an InChIKey ([spec/18 §18.6](../spec/18-layers.md#186-chemical-structures)). `vectors/structures.jsonl` pins the rules. |
|
||||
| `biology/` | A layer of sequences on the Typst draft (`layer.json`, `annotations.jsonl`, `receipt.json`): the villin headpiece subdomain HP35, named by the words that name it, shown by the sequence the sentence prints, with its three helices as regions, and its N68H variant as a variant a model proposed ([spec/18 §18.7](../spec/18-layers.md#187-sequences)). The residues are numbered 42 to 76, as the headpiece is. `vectors/sequences.jsonl` pins the rules. |
|
||||
| `data/` | A layer of data on the main example (`layer.json`, `annotations.jsonl`, `receipt.json`): the caption of Table 1, confirmed, tied to `ds-hale-bond-params` as force-field parameters for ethane, water and the CT–CT pattern, with the force constant and the equilibrium length as its quantities; the caption of Figure 1a, confirmed, tied to `ds-hale-ctct-scan` as an energy profile of ethane; and the sentence that introduces Table 1, tied to the first dataset by a model and still `proposed` ([spec/18 §18.8](../spec/18-layers.md#188-data)). The subjects are the identities of the chemistry layer, and the units are the datasets' own. `vectors/data.jsonl` pins the rules. |
|
||||
| `submissions/`, `grades/` | A student's answers to exercises in the layer, and the grader's result for each. |
|
||||
| `suspect.json` | A doubtful reading raised for review: the converter's reading of an exponent in the main example, before the first correction answered it. |
|
||||
| `qa-report.json` | Reviewer error bounds for a delivery that covers two of the main example's receipts, signed by the team's owner key. |
|
||||
@@ -61,7 +64,7 @@ Each record is a single file, or a folder where a format needs several files.
|
||||
|
||||
## Broken packages
|
||||
|
||||
Each folder in `invalid/` holds a `package/` folder, or a `package.sct.zip` archive, that breaks exactly one rule, built from `packages/tiny2026example/` by one edit, and an `expect.json` that names the rule.
|
||||
Each folder in `invalid/` holds a `package/` folder, or a `package.sct.zip` archive, that breaks exactly one rule, built from `packages/tiny2026tiny-j4qm/` by one edit, and an `expect.json` that names the rule.
|
||||
A conforming implementation refuses every one of them and should report that rule.
|
||||
`registry/rules.json` lists every rule ID with its meaning, and a validator reports each failure as `path:line: rule: message` ([spec/22 section 22.2](../spec/22-conformance.md#222-validating-a-package)).
|
||||
|
||||
@@ -82,6 +85,7 @@ A conforming implementation refuses every one of them and should report that rul
|
||||
| `location-unknown-page/` | A location on a page no witness has. | `doc.location.page` |
|
||||
| `manifest-hash/` | A file changed after the manifest was written. | `package.manifest.hash` |
|
||||
| `manifest-key/` | The manifest names another key than document.json. | `package.manifest.key` |
|
||||
| `math-form-label/` | A `scienting-math/1` source that still holds its `\tag`, which the form lifts out. | `doc.math.form` |
|
||||
| `missing-required-file/` | A required file is missing. | `package.file.required` |
|
||||
| `not-canonical/` | A line that is valid JSON but not canonical JSON (the fixed form of RFC 8785, which gives equal data identical bytes). | `package.file.canonical` |
|
||||
| `receipt-root/` | A receipt whose Merkle root (one hash that summarizes a list of hashes) does not recompute. | `doc.receipt.root` |
|
||||
@@ -92,6 +96,7 @@ A conforming implementation refuses every one of them and should report that rul
|
||||
| `root-mismatch/` | document.json's root is not the root node's node_hash. | `doc.hash.root` |
|
||||
| `signer-mismatch/` | A receipt whose signature was made with another key than the signer it names. | `doc.receipt.signature` |
|
||||
| `style-sup-sub/` | A run cannot be both a subscript and a superscript. | `doc.run.style` |
|
||||
| `suspect-witness/` | A suspect whose second reading names a witness the package does not have. | `doc.suspect.witness` |
|
||||
| `text-edited/` | Text changed without its hashes. | `doc.hash.text-hash` |
|
||||
| `unknown-kind/` | Kinds outside the list are refused. | `package.schema` |
|
||||
| `unlisted-file/` | A file the manifest does not list. | `package.manifest.unlisted` |
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
{"note":"A scienting-math/1 source that still holds its \\tag, which the form lifts out.","rule":"doc.math.form"}
|
||||
@@ -0,0 +1 @@
|
||||
{"doc":"scienting-doc/1","files":[{"path":"document.json","sha256":"2586b1713112b6c2dc297066c497e096128e7594179862098439c2300cf179d9","size":764},{"path":"nodes.jsonl","sha256":"0146621bd4b98c3ef9f658b3b8a9cfe940a6b996bf10d5452fa13c0886eb4c7b","size":11405},{"path":"provenance.json","sha256":"4bc7649bf6d3113f6c72b4016713654f57c8f03069632eabd1e6025c05cb9dac","size":226},{"path":"receipts.jsonl","sha256":"f745067d43480bbd467c5d8f11ff13eec198fac821664894ad8bd90b8b7cf0b3","size":2182},{"path":"references.jsonl","sha256":"59908a8aff6a2d5800747a1f45c6c2943ea1e31e7e1f10b6348967d30f16b87e","size":60},{"path":"roster.json","sha256":"3c71b0c007924cbacd3b4af02485214ab904db8ff8fca133ab32e67c5c76d481","size":6941},{"path":"witnesses.json","sha256":"83ac4411c2efe65e0f7fc4c9336abbef6977cd32b0f90de029a7f8516afc3e97","size":750}],"format":"scienting-package/1","key":"tiny2026tiny-j4qm"}
|
||||
@@ -0,0 +1 @@
|
||||
{"counts":{"leaves":10,"nodes":22},"fidelity":{"counts":{"F0":0,"F1":0,"F2":2,"F3":8},"lowest":"F2"},"format":"scienting-doc/1","hashing":{"algorithm":"sha-256","scheme":"plain"},"history":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","key":"tiny2026tiny-j4qm","kind":"article","language":"en","license":{"spdx":"CC0-1.0"},"meta":{"author":[{"family":"Tiny","given":"T."}],"issued":{"date-parts":[[2026]]},"title":"A tiny example"},"meta_hash":"1062e6079e2871c390f4737f5354448b65fe524d8c09d1c82afaa8b71ba6b3e7","policy":"full","relations":[],"rev":0,"root":"842b9e18bcc50da04b4bb45285ec006a34ad369730cc9b14286cc73a9f74d197","version":{"type":"version-of-record"},"work":{"key":"tiny2026tiny-j4qm","same_as":["doi:10.5555/example.tiny.2026"]}}
|
||||
@@ -0,0 +1,22 @@
|
||||
{"align_key":"65f9b52a7bd652256da439faf19fc25f04b7f2ff7201d6af3a623bbca9fa39e2","id":"s0fn2fj","kind":"document","match_hash":"96546166e7b438ec513007778509c5cbe982076768183ef59de55a21a22dfb92","node_hash":"842b9e18bcc50da04b4bb45285ec006a34ad369730cc9b14286cc73a9f74d197","ord":0,"own_hash":"34444fe0e6bdbf3927a579fe3286859d204ea0882a381b7769ffd4905551d24f","parent":null,"text_hash":"37409459e7e2b3a8184e60c6f7b7b21cff6c4efa07d04fdf0dcb4635c3e981d8"}
|
||||
{"align_key":"c375c776c496f0e334acc55b000f3cecd226661b2e337d20d3efa082a6754459","attrs":{"level":1},"id":"b9wp3tt","kind":"section","label":"1","match_hash":"59c4b8702f7716ec47e32f1bb5b331c6611d9623f2744deb8f8b203f7f6a095b","node_hash":"d9673b45baffdd2a338e49bfa6184f026ae67224aafc136ce97766554671e0d5","ord":0,"own_hash":"65da097b48f8237e8d171bfbd0053ff0e3795c0532d5522d23a92b53430956f4","parent":"s0fn2fj","text_hash":"141698d1f118f50b107f017875c14fc24b529da752ed66f6c17a6332f032cd09"}
|
||||
{"align_key":"c099142bc3186ded72786ba27e9ea6d2da240fb9fd3fe79b479ecf8e734b2850","id":"vet7k0e","kind":"heading","match_hash":"219c4a6c86a716e99d5dc9611b61e584deb11b57e972d87d4b773387ebc3cadd","node_hash":"a3c82ab1e44bf4cffa1a59507f8bddc39a1ad191321ee803d0d60d96609a44c7","ord":0,"own_hash":"e813ff86a8920cef741e548eb5df545774b520d2fadbdda6e2b872a6729b9d26","parent":"b9wp3tt","text_hash":"219c4a6c86a716e99d5dc9611b61e584deb11b57e972d87d4b773387ebc3cadd"}
|
||||
{"align_key":"c099142bc3186ded72786ba27e9ea6d2da240fb9fd3fe79b479ecf8e734b2850","content":[{"kind":"text","text":"Results"}],"fidelity":"F2","id":"em5pd9v","kind":"sentence","match_hash":"219c4a6c86a716e99d5dc9611b61e584deb11b57e972d87d4b773387ebc3cadd","node_hash":"293fc03ff4e39d7532467e4417ffcdb15f470f0bd3658dc1c021645ad53c9bef","ord":0,"own_hash":"c55f401232b19ff1133d77eac6c72868975064f177fc2d31ab8a181303c30599","parent":"vet7k0e","text_hash":"219c4a6c86a716e99d5dc9611b61e584deb11b57e972d87d4b773387ebc3cadd"}
|
||||
{"align_key":"610c235321e38145abff21e31eaab303d85a6ce0d1b9340a599dc821a04922f6","id":"ytp1e5n","kind":"paragraph","match_hash":"bcb4902ec69f2a7a724384f561ee9aa0e214c824c5882c1ad92777bee680aad4","node_hash":"7667a3a4bc2e8fec1dc7af53e19c414952f9ce926b1e37e8d9adca66dd8f8d1d","ord":1,"own_hash":"494e069be36a18ecaabf5a63be7c31617ade7a5460218ca83a2de3d8d8f964e0","parent":"b9wp3tt","text_hash":"f589ee914c46c4aea7ce2de49d925c433c914121f576b81a3eab692f17f179a3"}
|
||||
{"align_key":"8f21603c39df123eb8680362184274aac9bdf1dbd485b3bba230960179071c95","content":[{"kind":"text","text":"The value is 42.0 at 300 K."}],"fidelity":"F2","id":"jvnys4s","kind":"sentence","match_hash":"3bcf9fa8412dca28be91d6423460233ddedd7add6c324d8a0f2b26038567d3d3","node_hash":"f5761f338b2878dff39a6ee724a75b13626dd625a0df96cf1cc6f9e8258cb7cc","ord":0,"own_hash":"7f0b9190d076cf01b51a8be863a51e9a8eeaab5d3ec8656202ff4d41578d4d82","parent":"ytp1e5n","text_hash":"3bcf9fa8412dca28be91d6423460233ddedd7add6c324d8a0f2b26038567d3d3"}
|
||||
{"align_key":"8e7fe271cd1bab88d86c8900fe3ffae0ce95c55af6659df1fca278d359296e2d","content":[{"kind":"text","text":"See "},{"kind":"xref","target":"tb49qpc","text":"Table 1"},{"kind":"text","text":" and the note."},{"kind":"cite","refs":["r3e21zr"],"text":"1"}],"fidelity":"F2","id":"mzwwhxj","kind":"sentence","match_hash":"9894a48790a8561966e68672fa13da20541d25a5178653720648f62cbc9ad36b","node_hash":"8f3e5338ba3c97efca4cef5c60d849757aed6334ee27ab807fa71d969089e46e","ord":1,"own_hash":"02ed6d50b8ac607b59e3f7b5116ee6143ed7e69af25b19c4037aa799bc330a88","parent":"ytp1e5n","text_hash":"5b1de19c9eb1399e54bde7e96f051cac8b337be1f307fac320292b8db7e39da7"}
|
||||
{"align_key":"d1dfb8303cf760f1c9b5869aabebd28e80d6730e8fc0663366951b3f86459c1c","id":"exq1ter","kind":"paragraph","match_hash":"1320b130813dce9cd6e0630dddfce86d62983de5eeb7e3ce3dc39002aa4d74bc","node_hash":"5d72bc43a31cfd65c71630cb61bd00ec17cce925f7a5d86294feea2de6574de2","ord":2,"own_hash":"494e069be36a18ecaabf5a63be7c31617ade7a5460218ca83a2de3d8d8f964e0","parent":"b9wp3tt","text_hash":"f567a0cebf7b8cec19220dfa2a7a41dc254e7676f2ee17ff96d3107d6d438db0"}
|
||||
{"align_key":"b02a85962a2cecd80fc82093410195e78374b6147bd169fda37f737cb12601c0","content":[{"kind":"text","text":"A second paragraph, "},{"form":"scienting-math/1","kind":"math","notation":"tex","source":"x=1\\tag{2}"},{"kind":"text","text":"."}],"fidelity":"F2","id":"j663d4h","kind":"sentence","match_hash":"c57b6ddabc53ff4d46acd560a10853de9b25d9ae9f95efd75344a3611178d1a9","node_hash":"d24303fe6b04bcf7b942ce79f5db1743763fa4c529793a0f11669d62a16f6a6d","ord":0,"own_hash":"432e8e839c6c4294b560300905e1d40af2f58103ce4055d8b49bd68f828bc937","parent":"exq1ter","text_hash":"6db4ee9addc6f343d677e0b612a9ccaf45f747ddbb893c64b398c00f9b986a67"}
|
||||
{"align_key":"437c101749b0481e615fc7eed8dcacb536b65400c7e0695ad4cbb2bf2dae488c","content":[{"kind":"text","text":"It ends here."}],"fidelity":"F2","id":"rsw24qc","kind":"sentence","match_hash":"2888dbfa0c08fd65c58c923b920860c76e13913d9fa93b03eccbbf7bdf53b882","node_hash":"caeb3ae57d0821b8ac961c9507debbcda2b118b16cdc010b83a143a782058d57","ord":1,"own_hash":"705f77e8520c8c5ce3a7a495a20d8a9c55baa9801e49a55c341f5de79eeede75","parent":"exq1ter","text_hash":"2888dbfa0c08fd65c58c923b920860c76e13913d9fa93b03eccbbf7bdf53b882"}
|
||||
{"align_key":"cb0107aa0d562e8bd1188c33dc1ef5a1d07808e51edeabaa87465556d11b6ec8","attrs":{"columns":[{"header_path":["af5b51r"],"id":"pj5sk05"},{"header_path":["ajqxkgh"],"id":"nymcs5q"}]},"id":"tb49qpc","kind":"table","label":"Table 1","match_hash":"1951e0b61441d7b817b4967b36eee007f8e7525ac75fd359437eddb871e59f72","node_hash":"154c910857f33c152fdc78e42582510327055e62da9a25ab10c3891eeaf69627","ord":3,"own_hash":"fb4cc66080def0b42a06f7aa566a24957c7345c77b8d873ca5c790704a890f47","parent":"b9wp3tt","text_hash":"1951e0b61441d7b817b4967b36eee007f8e7525ac75fd359437eddb871e59f72"}
|
||||
{"align_key":"769a4e6d0003189c7e96c5d9b7e810a0d11c3a12832527ec94b0f86d277f51ca","id":"t2ps2mp","kind":"table-head","match_hash":"887fcea6a80333c6c02ae7e79735f0edad8d811f0b61431495f796f4bf6a7c19","node_hash":"6d8056adfb50dc0b65a2a65b47eccc5f47d5482a8dfbefa0d8a06f6641a4be3a","ord":0,"own_hash":"c5749bee3a4b981fb79cf6db125ebb416dce5a83613a00feecd9d4cf75df9bb4","parent":"tb49qpc","text_hash":"887fcea6a80333c6c02ae7e79735f0edad8d811f0b61431495f796f4bf6a7c19"}
|
||||
{"align_key":"769a4e6d0003189c7e96c5d9b7e810a0d11c3a12832527ec94b0f86d277f51ca","id":"rr9rtf5","kind":"row","match_hash":"887fcea6a80333c6c02ae7e79735f0edad8d811f0b61431495f796f4bf6a7c19","node_hash":"8bd1fa377ec390fdc36e17baa8c3a39d2df7ef2a53cd0c0dc745ae40e98f99f8","ord":0,"own_hash":"6c7c11bf1b6260162c4141f1468aa6869f5c33359900497e2cdb1a051488bd62","parent":"t2ps2mp","text_hash":"887fcea6a80333c6c02ae7e79735f0edad8d811f0b61431495f796f4bf6a7c19"}
|
||||
{"align_key":"2d711642b726b04401627ca9fbac32f5c8530fb1903cc4db02258717921a4881","attrs":{"colspan":1,"column":"pj5sk05","role":"column-header","rowspan":1},"content":[{"kind":"text","text":"x"}],"fidelity":"F1","id":"af5b51r","kind":"cell","match_hash":"2d711642b726b04401627ca9fbac32f5c8530fb1903cc4db02258717921a4881","node_hash":"59d1c20766a77bacde2aae80a134c7156fbcc708c140a3bb2d2a67f78bd9c6f5","ord":0,"own_hash":"c68933b07bc7c5b806892ae36b3e4c3205a0a2066fd6f8255578f7d1ca86dc10","parent":"rr9rtf5","text_hash":"2d711642b726b04401627ca9fbac32f5c8530fb1903cc4db02258717921a4881"}
|
||||
{"align_key":"a1fce4363854ff888cff4b8e7875d600c2682390412a8cf79b37d0b11148b0fa","attrs":{"colspan":1,"column":"nymcs5q","role":"column-header","rowspan":1},"content":[{"kind":"text","text":"y"}],"fidelity":"F1","id":"ajqxkgh","kind":"cell","match_hash":"a1fce4363854ff888cff4b8e7875d600c2682390412a8cf79b37d0b11148b0fa","node_hash":"838e3fba38f0797d40522b7063cb5c2962e32a019c09c19f09849ced73079a87","ord":1,"own_hash":"28df42bf1dcd44b053275ed014bd1599914f17adabc0c7fdb3e4247dc648ac49","parent":"rr9rtf5","text_hash":"a1fce4363854ff888cff4b8e7875d600c2682390412a8cf79b37d0b11148b0fa"}
|
||||
{"align_key":"b902cc4550838229a710bfec4c38cbc7eb11082367a409df9135e7f007a96bda","id":"dmsstkg","kind":"table-body","match_hash":"24cb52bc2dd0b9ddd4650c011d76b585e76c4d4ecae8cf220c7600efb808d738","node_hash":"baf17577660aa6f0ba9c8703d30816d77cfce7dbf0ea3257ed830fa9ab94ce9d","ord":1,"own_hash":"b229a7f92314227bf225ad27010a546e7c2373f4b30b7f6ec372e568cbacb6aa","parent":"tb49qpc","text_hash":"24cb52bc2dd0b9ddd4650c011d76b585e76c4d4ecae8cf220c7600efb808d738"}
|
||||
{"align_key":"b902cc4550838229a710bfec4c38cbc7eb11082367a409df9135e7f007a96bda","attrs":{"header_path":["rdrqkv7"]},"id":"r3e7hfs","kind":"row","match_hash":"24cb52bc2dd0b9ddd4650c011d76b585e76c4d4ecae8cf220c7600efb808d738","node_hash":"97a1f5b27bbfe8c9d2cec7212b519b4993506fc8080be3eff02f3aa31515a19d","ord":0,"own_hash":"6c7c11bf1b6260162c4141f1468aa6869f5c33359900497e2cdb1a051488bd62","parent":"dmsstkg","text_hash":"24cb52bc2dd0b9ddd4650c011d76b585e76c4d4ecae8cf220c7600efb808d738"}
|
||||
{"align_key":"6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b","attrs":{"colspan":1,"column":"pj5sk05","role":"row-header","rowspan":1},"content":[{"kind":"text","text":"1"}],"fidelity":"F1","id":"rdrqkv7","kind":"cell","match_hash":"6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b","node_hash":"87da3bd568286f3d0578d8a813496d15faafb62f4db44b07aa1c29e52cda34df","ord":0,"own_hash":"fb474321001657b59bccd3cae0987c544a4ef9a27214626d77695f4db237aa93","parent":"r3e7hfs","text_hash":"6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"}
|
||||
{"align_key":"b8736b999909049671d0ea075a42b308a5fbe2df1854899123fe09eb0ee9de61","attrs":{"colspan":1,"column":"nymcs5q","role":"data","rowspan":1},"content":[{"kind":"text","text":"2.5"}],"fidelity":"F1","id":"f463wj7","kind":"cell","match_hash":"b8736b999909049671d0ea075a42b308a5fbe2df1854899123fe09eb0ee9de61","node_hash":"f1cd6d5339c84d5c36f8e1ea484a8d837f3200f05d1b106f6119dfa30d846bfd","ord":1,"own_hash":"088eff622eb3086d68c4433cf5e1783dc9f2a6724c3536c31ec0bf80b5f89db5","parent":"r3e7hfs","text_hash":"b8736b999909049671d0ea075a42b308a5fbe2df1854899123fe09eb0ee9de61"}
|
||||
{"align_key":"b35d81b0ff35d6d05ad2c187a289d3017896427dfd8bb98160bc806ac0ec32f7","id":"aw97y35","kind":"back","match_hash":"9a2d5d28ee47736a00d074e066bb944154f95a192360c8c04226c3d12a4f7d1e","node_hash":"fcb8027f7c89115f048b9c5d6770847248f4e4fbc61cbc8ea0b04079b4d58350","ord":1,"own_hash":"bbb972bdc024231b505f4d8ce5e711fbb75c8b5ffd1b5d42ee3fb8586b85f867","parent":"s0fn2fj","text_hash":"9a2d5d28ee47736a00d074e066bb944154f95a192360c8c04226c3d12a4f7d1e"}
|
||||
{"align_key":"b35d81b0ff35d6d05ad2c187a289d3017896427dfd8bb98160bc806ac0ec32f7","id":"yd513mw","kind":"references","match_hash":"9a2d5d28ee47736a00d074e066bb944154f95a192360c8c04226c3d12a4f7d1e","node_hash":"8b8a9000e984c3efeb27fc40c8fbadd7349dd64860aa276dcd2a25a57ce52e87","ord":0,"own_hash":"2a5302e2041d0e59458fea212dd51b89299901318bfceeeff227c1a07d3f5d1a","parent":"aw97y35","text_hash":"9a2d5d28ee47736a00d074e066bb944154f95a192360c8c04226c3d12a4f7d1e"}
|
||||
{"align_key":"b35d81b0ff35d6d05ad2c187a289d3017896427dfd8bb98160bc806ac0ec32f7","content":[{"kind":"text","text":"1. An Example, 2020."}],"fidelity":"F2","id":"r3e21zr","kind":"reference","label":"1","match_hash":"9a2d5d28ee47736a00d074e066bb944154f95a192360c8c04226c3d12a4f7d1e","node_hash":"71b1af6dd6a56f24cb3b338e0fe99df06b9154ecdf4b391b00b7a7e61e23a8ed","ord":0,"own_hash":"f7c9bbc8c7456e6dc435feeaaa02cbfdbe487523b020105793fb11b91d0894f5","parent":"yd513mw","text_hash":"9a2d5d28ee47736a00d074e066bb944154f95a192360c8c04226c3d12a4f7d1e"}
|
||||
@@ -0,0 +1 @@
|
||||
{"note":"Built by hand for the conformance suite; every reading is synthetic.","stages":[{"processor":"local","stage":"hand","tool":"paperspec tools/build.py"}],"tools":[{"name":"paperspec tools/build.py","version":"0.1.0"}]}
|
||||
@@ -0,0 +1 @@
|
||||
{"at":"2026-10-11T12:00:00Z","by":"ana","doc":"tiny2026tiny-j4qm","evidence":[{"kind":"crop","node":"af5b51r","sha256":"78b08276b5122feed3829e8dd19684fa8a4a41f79cb83a499d40341e09f5d658"},{"kind":"crop","node":"ajqxkgh","sha256":"398bab4177685c88eef399d814d34c81baa556d58cd508bd5ddb33ac53a5cbfa"},{"kind":"crop","node":"f463wj7","sha256":"88b1e820b569c3a0fd025a6b6c502271ed73bbce720dd8a2e416d6a5dd0e9d67"},{"kind":"crop","node":"j663d4h","sha256":"d6484c89588a560f64bbceca108f5446e47bb5cb85521fbffc9d6d37f252e5c7"},{"kind":"crop","node":"jvnys4s","sha256":"3139fb30b88062bd0c6bbb028c4c57fc748218ce1d7a612d282e292d6a02ffe9"},{"kind":"crop","node":"mzwwhxj","sha256":"83a7fcf09321f8a644c58120f80dede5d73d89f50d080ccbb143ec5b485e3088"},{"kind":"crop","node":"r3e21zr","sha256":"ff809e11101fa6ff5422e5232e83142c1a43dada0e56d63ec03fbce3474dd1aa"},{"kind":"crop","node":"rdrqkv7","sha256":"c0699aceb344812ebebb1414838641f0761184d5113dcc870d07c721fd289437"},{"kind":"crop","node":"rsw24qc","sha256":"b4c3b133c707b1a9a2cec2efe5c17731bada0d6bace5b1fb3590c5c5ab18bb92"},{"kind":"witness","sha256":"fda3f1e9bb3538cd85dcc42281e00fd045f726652664439ce5a15d8489425b21"}],"format":"scienting-receipt/1","id":"k4wt522d9zvjr","level":"F3","nodes":[["af5b51r","59d1c20766a77bacde2aae80a134c7156fbcc708c140a3bb2d2a67f78bd9c6f5"],["ajqxkgh","838e3fba38f0797d40522b7063cb5c2962e32a019c09c19f09849ced73079a87"],["f463wj7","f1cd6d5339c84d5c36f8e1ea484a8d837f3200f05d1b106f6119dfa30d846bfd"],["j663d4h","443539440dca73149ca75276492334ce9a5a6c50070137e8dc7bf414b75a27ab"],["jvnys4s","f5761f338b2878dff39a6ee724a75b13626dd625a0df96cf1cc6f9e8258cb7cc"],["mzwwhxj","8f3e5338ba3c97efca4cef5c60d849757aed6334ee27ab807fa71d969089e46e"],["r3e21zr","71b1af6dd6a56f24cb3b338e0fe99df06b9154ecdf4b391b00b7a7e61e23a8ed"],["rdrqkv7","87da3bd568286f3d0578d8a813496d15faafb62f4db44b07aa1c29e52cda34df"],["rsw24qc","caeb3ae57d0821b8ac961c9507debbcda2b118b16cdc010b83a143a782058d57"]],"rev":0,"root":"15d9c8bd5472afd7064578e5663d3b7fd21249adc6cdb40fcbe1b790e3fae801","scope":"all","signature":{"key":"ana","scheme":"ed25519","value":"/xOfCboOpgu29ztKi22IU9crgC5LYetrHOMpQtqj4QV5dVP73n/ze94hyPknYO5qNPgBmYRrbJZBIIHdwqxoAA=="}}
|
||||
@@ -0,0 +1 @@
|
||||
{"label":"1","node":"r3e21zr","resolution":{"type":"none"}}
|
||||
@@ -0,0 +1 @@
|
||||
{"format":"scienting-roster/1","keys":[{"did":"did:key:z6Mkj7iUX8QG7zkAtNaV78CUXcenhD87qWwQbc7NU5aVXyW9","id":"ana","person":{"name":"Ana Example"},"public":"RUiz5j+y0QwgOtsQpqXrlq+gy3c/JFnkxwvlWUNX4Ao=","purposes":["sign"],"registered_at":"2026-09-01T00:00:00Z","revoked_at":null,"role":"owner","scheme":"ed25519"},{"did":"did:key:z6MkhemKN7rMQcgt6wT2eWPyx3vFRS1RUoRziLMnLq2vZ9yi","id":"ben","person":{"name":"Ben Example"},"public":"L4WMLs7xLjBLRsxS/EYpD194puMBpADybcfFEWxBkWk=","purposes":["sign"],"registered_at":"2026-09-01T00:00:00Z","revoked_at":null,"role":"editor","scheme":"ed25519"},{"did":"did:key:z6MkrBf2w3MUroaNBiHTQJzH4e1w31jpcosd5vNxjikijndU","id":"ben-spot","person":{"name":"Ben Example"},"public":"rkzxigjCXg869PGSFAVr4EDXXRmwk+S/+wJ93lrG4dc=","purposes":["spot-check"],"registered_at":"2026-09-01T00:00:00Z","revoked_at":null,"role":"editor","scheme":"ed25519"},{"did":"did:key:z6Mkgrc9HCeEUL5tz1bVfuuDeSm6mP6hyWUX5ivhgReSbEQM","id":"cara","person":{"name":"Cara Example"},"public":"I7J1GqG5CHOc0LHYZPNNto1Me2lJUzBVn2A7GrUGbZ4=","purposes":["sign"],"registered_at":"2026-09-01T00:00:00Z","revoked_at":null,"role":"reader","scheme":"ed25519"},{"did":"did:key:z4xcFfnTC6XJy4gzg9whfyMzcnxV7yM2XafMFynKXhAEvMgjfQCxSnjZaa53arz2iNo8v35ZN5SdAUcbFkbuvftcMczRT2CPhYsXkNYZhDzXWQVS5KZZkhnMDmwChWfgRHu4Bs6KHyEmvzwesTioW5yS3YtfR7mUPJAwWSRq9f23HRxzenGpVVBcVjpd8YDZ4Y1ZamcUfesnB6pGLrPtLDvGM7Te1cJWoRG4m3TetEF3i9V3W4CH43nouCwUPbjy7dpTNEWiCqaTPiPhV8UEWBD8b9e1729PwoUFyAFreuq6wvhphLKGHhFCFujrUtqDZPs6FFF1Q7Lpt9eFcjbxrZSAYsh9VTfxaUeQ4HmFqzrg28EEjJzxxADZyjTXDsfwskRbibHSms9bbN2xK6GQcUxE2mrA2ULfYwsk5RQsVULUTj3pMMXpxRqP4zerzui2ZRZ3SqeNUwqnhmF861pEtcemZPY6ivcX41QK3ekCtpc1HndtY9xua1Lrhs4jd6qEbxHWzBPHok6qTpyxnn7ubZssBqSMz3uNrou1ayZGDn1ayAXtzCJPjAcxdNX1dpm5vyDB8GYtNKsQHuiX5xUd2EMAVfq4cFrZ6ncY1zrG5exH6mhJYbZfW7BgXxq7GsnzAAGkzgHCRADe5EEm1Hj1YdmVBTiaGsPGYkF4Mcrw3T2j3AcPJCzPLRNjKBKXyHAcf3VPUmreaHd1GoA5zqvtANSPmppY2AhCAj8u6n92fiyBgrvJTh4hyvtMFcwaa9vKnY9rBS4n5XGpdwKQe11Tk5sah8VZc2PyH2WPBU3DmhZSwUkKHRQQQQMXjrLjuMtygzxWBgrJAcWRPzxmzHZEj5x9GgFZb4dPDwqVXsgR25KrpuyQKcxfbxzQoRprnhu1ec8SfX5zeUo282Si9dBZ3JVdxzYHzP6xSiuBeHHFMvMwb1MKUq2dMi9vWdg2eCDo5wTvSaTVcdYGtZsT7HMswWtxx9GLw1RafYRcNqMhBhCbRdJszUKjQKwNNZbaryRs4kTYicuE24PWbqfxdJnrzrLbXnVBDMNHjX8ESXSKTMnAoE1AiLgjdj3zbBrY39Pxc72EikA7GvP2qxKZBkJ6G2RRWCw9d3nZKmTmQqP5PP9HgdtSTnZhNTJqBkwL3iqfoWxtbkLjLLSQc3dbFpmhe4kAh7VUUDcLzjb4nGzCbr5U1YoqAoLnSC9BPijnfMHxBP6i8cR762ryxPwe7HdGk62DVYoqxbwz8ygrDPjdPi3t11PpHp51GxuhMkoR3GFxAdMEv8j4tVpJ6qjefULEFTtRPzZ5kTE57RTxC4wg62qcYwupWx4dvvB2BR9ZGnNwCojpBYByeeYETrgm4HJjjS3SH64sbpyqz7336YMAcWyQFc9BeqjQHHUHS8CJ82N88apbPPE8N9X76DQ8PgwACtR4D5ofE9o14kpdVZFV2YMtmnKCybNLn3atspK6T1ZPYB3vQ1c4DbzZFgCpm6izEzxsY17in79ieo3cY965Cr5mkxca29VxcTaEtovdu9sKAL4VgCZzWkps5nnimX5JBEdVKYxTtMb6CcTkdWGFtXBTBuAMTpRNLXG5nG4bq9XXLkFS4oXpVS7KayqAMtrrqttpgwdAPNuzd6E4JskxdenwMq6qzMTDKoMqGDVEKkwCxCcbUtNpHGMLWMMk9MDrsPvcU8u2C89UmJmsfS5gQqswkz6TfXvthM3wPcuKaX7TUJJRzYstWsXRKUaPqqT3ppftCbXPFgia3mXkA5bk9Y3GWcTADGTnzKkTzbnL6hsgQW1FyvsFwUiWUJd5weeHkfaHt8iV3PKy99S6d831iLCfFWM6bYZgEBvyx5seHSpiaXRfSv4A2yDsf4Tb4EVsyDUJPUmZLnbFkJmw46A6PoQHdwfBbXWV47DFM6w5mKXCPmKzuAG1Vmw7D36n4oHd91r1VzTynVnhD1EA5UVh4qhiw2CnWgo2uAPxEpLYnvrCLiVprnzdPzvZZqMUxXRFWHwfshJDARRLvP933693aWxa5PeDNgMjZYgKJBV5e66Z1Mk5rYegEuSq7uyz8Mw3iuidtJeqBugbNCYeNdmeBPgKux8HcuFNqQaVwhP9vW8vyaU7DvuKEeXs1uyAgtk9RCua2Mx8rQqUwQigWNjXaJoSYqMT9SVEGUSYAGQiLnMFENqG1r87uhxV58hTwR8QED9cQkStFXeuZAMY6FWTZCsD5juC48KdqoUQYr77iBy7fW2quQNdPvwEUdhh1mzSTX2PPubCbm9rcdBxBQ2CBZizn1EsbPMic1X39t17scRE5F4Yank18EF4aUmJwwNHx5m1WKDQMZ1kJQRyhtRvAHTPqBdJCw5SHaEqBVpEQHUZwBKsQoTRj4Gk1opv6XfczoK3MLuprTMSx2maw5Gv6LhF2SWUvEXMMqoeqVzyP9g11dumkKQLMiAQa2VGaa7EF7Foj2ZDUhPM6PPiffHMhDMwWhRBywg3SC6aP9zz2TdMXweHv8rags9chFZ217aAP3bcCf5i1VZqPT9b8Ea7ykjjUy6PNwiSforRXN46suuRFREuhx6DuWDojythjH73wMAeKKx23rF4QfdUxzkC2mmmS4dq8Xx7Bda4e31EGab4t81Jk4dAVGjSrZC9wx89CAjovhoejgDTKNsN3ri4GjW9UD","id":"dana","person":{"name":"Dana Example"},"public":"lQ6M2DulKY4RkQLGTPGZD+CHlOOib4kBkwlccVNWRDPco1k5kHtelT/yUP4+CoAQnHnLu96vpeWztaee/9RmjR3bstGj+P5tOSrwFlPuyNUPOWPNjwCQLrVEyeUGBaA4+HRvFwK7C4OHB8EJWYtC0OuH+tRPlCdLpxlVcZZcM7dsZYe2BDNenbWfp4TeX2Oa+dThlceDY0m9MewwqUrd5xdo9tc8PS9R9o0ZUWf0vDw7Fc5AcsWwbf76lDLvIbyd0aCaHJ7eaK6DFsBuZFKVdlZlH0inJciAMF8dPoRuE+A0VlZTEOsOivNWprM5iLHzXse3zSoHLldWr0t4hWxHH3MBQ57Ucee8RTU6hFRfqfFRl6zJQyRZOFZZoYD9QwXkR3NmUzV/FcsOMHpbgTcY7O0TAajPnfpSTp+XdyPVBR7TlTsturUCpryP0ZX1S3VJk2IaneB123thtcOtWsbqdT3Bb846H7yudI95WVTixIS/KIwoCbekSf8Y9+iW/xRVSWLRVc1gpigDxXfieSA7bI+qiUBjiKR7QU1KFYZA58VcOQhzeMLY6an34rsW4WHAwzzSv8Q6vrwpn8Ct9fTsIeiZsWZLueNkIUfjR0G1bHHoT2RHKton0AMRjOUGSKUUB4DNZ5xzXvC0jvUMWlgHB9z2wBCsIkIDVWqSA2DD0xeIY2wSUVPwPc1MnBAf/Fx3poweUlcPWglR2VaO9ematC4hfLxxkGldGQt3C6ZLPsm96S7o6j88rwOqkDNIR1pNJOepgciJH/w4Xwtg9gJ52CpdlCeSllRQD74l95ysmZ2D/gLweNoUt61P0RYQQelio8VnPUNB1e2uK7zW9joG1k59CjJGQNvuZr6JkQ9+Hxo5xKEOy9KcpT6t48wTzbz3YMFDxTNl0/DzL8qdTU2UrSW6/TFgPLokbAQN00yhw0lg8cR/e1m+ujFyBeesL3luwE6HNcIyK5Y/+To04vR3OD7Uz8cnABxWyOeSBm2R2bu2fxeN0Hlv+qhoOYtbZ1DKx/aES4z51jATynEIdMIMSNhmVDoDiGODh9ocenzg/DUarjIzWltPFRyQj+tnFGTXp7C87Line truncated
|
||||
@@ -0,0 +1 @@
|
||||
{"witnesses":[{"id":"nmfryke","kind":"pdf","media_type":"application/pdf","origin":{"source":"author"},"pages":1,"rights":{"asserted_by":{"by":"ana","evidence":[{"kind":"statement","note":"The team's own draft."}]},"at":"2026-09-15T12:00:00Z","basis":"own-work","format":"scienting-rights/1","license":{"spdx":"CC-BY-4.0"},"uses":{"accessible-copy":true,"ai":{"external/local":true,"external/outside":true,"external/outside-no-retention":true,"external/tenancy":true,"internal/local":true,"internal/outside":true,"internal/outside-no-retention":true,"internal/tenancy":true},"quote-public":true,"read":true,"redistribute":true,"tdm":true},"valid_until":null},"sha256":"fda3f1e9bb3538cd85dcc42281e00fd045f726652664439ce5a15d8489425b21","size":1000}]}
|
||||
@@ -0,0 +1 @@
|
||||
{"note":"A suspect whose second reading names a witness the package does not have.","rule":"doc.suspect.witness"}
|
||||
@@ -0,0 +1 @@
|
||||
{"doc":"scienting-doc/1","files":[{"path":"document.json","sha256":"e10c4aaab285d02d859ed2cf590fa9add9b77b0fab7a2b71b8c82f61b310a031","size":764},{"path":"nodes.jsonl","sha256":"6ce54e0d837dceb4a2a39c1b2618cc66e16684b93f71b93ab4e6e709a90b0e52","size":11295},{"path":"provenance.json","sha256":"4bc7649bf6d3113f6c72b4016713654f57c8f03069632eabd1e6025c05cb9dac","size":226},{"path":"receipts.jsonl","sha256":"f745067d43480bbd467c5d8f11ff13eec198fac821664894ad8bd90b8b7cf0b3","size":2182},{"path":"references.jsonl","sha256":"59908a8aff6a2d5800747a1f45c6c2943ea1e31e7e1f10b6348967d30f16b87e","size":60},{"path":"roster.json","sha256":"3c71b0c007924cbacd3b4af02485214ab904db8ff8fca133ab32e67c5c76d481","size":6941},{"path":"suspects.jsonl","sha256":"62c33a53ec529721a3d9514d6dd6401b3cd45f8446ab4b06f2f78051610e7cfa","size":129},{"path":"witnesses.json","sha256":"83ac4411c2efe65e0f7fc4c9336abbef6977cd32b0f90de029a7f8516afc3e97","size":750}],"format":"scienting-package/1","key":"tiny2026tiny-j4qm"}
|
||||
@@ -0,0 +1 @@
|
||||
{"counts":{"leaves":10,"nodes":22},"fidelity":{"counts":{"F0":0,"F1":0,"F2":1,"F3":9},"lowest":"F2"},"format":"scienting-doc/1","hashing":{"algorithm":"sha-256","scheme":"plain"},"history":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","key":"tiny2026tiny-j4qm","kind":"article","language":"en","license":{"spdx":"CC0-1.0"},"meta":{"author":[{"family":"Tiny","given":"T."}],"issued":{"date-parts":[[2026]]},"title":"A tiny example"},"meta_hash":"1062e6079e2871c390f4737f5354448b65fe524d8c09d1c82afaa8b71ba6b3e7","policy":"full","relations":[],"rev":0,"root":"a05328e6d13edba652599aceb58c018dbccf54abd1f878c9f61623017960e1fe","version":{"type":"version-of-record"},"work":{"key":"tiny2026tiny-j4qm","same_as":["doi:10.5555/example.tiny.2026"]}}
|
||||
@@ -0,0 +1,22 @@
|
||||
{"align_key":"b3108c22ec836d883e5116f7ed8546fa75390eb4aa960d78f2936115f69b6826","id":"s0fn2fj","kind":"document","match_hash":"b6a4e12f700a6214bf02c9a437559e82fccdbecea7b575fa438a7d2e8c33071a","node_hash":"a05328e6d13edba652599aceb58c018dbccf54abd1f878c9f61623017960e1fe","ord":0,"own_hash":"34444fe0e6bdbf3927a579fe3286859d204ea0882a381b7769ffd4905551d24f","parent":null,"text_hash":"bd2abc746d51cf52d57a18632383245d585e29e265426967894eed99bc937561"}
|
||||
{"align_key":"caf6aee3882b3890996037e35d0ffdfe30b5e66653d45321d7ea0fa9135f1ee9","attrs":{"level":1},"id":"b9wp3tt","kind":"section","label":"1","match_hash":"5a96c01f314c4d8a22fd5e105bebef45df4301886cccbc2538ecefddfcb1d405","node_hash":"ea9a1409bbf0f0f7bd8d508bfdbbf7d14a22ab1e3da011eafbfcd4e14ae7e4fd","ord":0,"own_hash":"65da097b48f8237e8d171bfbd0053ff0e3795c0532d5522d23a92b53430956f4","parent":"s0fn2fj","text_hash":"7a97628fe9643c0fca3614a077e2e631c3fee81d3733ba1564292df65a294573"}
|
||||
{"align_key":"c099142bc3186ded72786ba27e9ea6d2da240fb9fd3fe79b479ecf8e734b2850","id":"vet7k0e","kind":"heading","match_hash":"219c4a6c86a716e99d5dc9611b61e584deb11b57e972d87d4b773387ebc3cadd","node_hash":"a3c82ab1e44bf4cffa1a59507f8bddc39a1ad191321ee803d0d60d96609a44c7","ord":0,"own_hash":"e813ff86a8920cef741e548eb5df545774b520d2fadbdda6e2b872a6729b9d26","parent":"b9wp3tt","text_hash":"219c4a6c86a716e99d5dc9611b61e584deb11b57e972d87d4b773387ebc3cadd"}
|
||||
{"align_key":"c099142bc3186ded72786ba27e9ea6d2da240fb9fd3fe79b479ecf8e734b2850","content":[{"kind":"text","text":"Results"}],"fidelity":"F2","id":"em5pd9v","kind":"sentence","match_hash":"219c4a6c86a716e99d5dc9611b61e584deb11b57e972d87d4b773387ebc3cadd","node_hash":"293fc03ff4e39d7532467e4417ffcdb15f470f0bd3658dc1c021645ad53c9bef","ord":0,"own_hash":"c55f401232b19ff1133d77eac6c72868975064f177fc2d31ab8a181303c30599","parent":"vet7k0e","text_hash":"219c4a6c86a716e99d5dc9611b61e584deb11b57e972d87d4b773387ebc3cadd"}
|
||||
{"align_key":"610c235321e38145abff21e31eaab303d85a6ce0d1b9340a599dc821a04922f6","id":"ytp1e5n","kind":"paragraph","match_hash":"bcb4902ec69f2a7a724384f561ee9aa0e214c824c5882c1ad92777bee680aad4","node_hash":"7667a3a4bc2e8fec1dc7af53e19c414952f9ce926b1e37e8d9adca66dd8f8d1d","ord":1,"own_hash":"494e069be36a18ecaabf5a63be7c31617ade7a5460218ca83a2de3d8d8f964e0","parent":"b9wp3tt","text_hash":"f589ee914c46c4aea7ce2de49d925c433c914121f576b81a3eab692f17f179a3"}
|
||||
{"align_key":"8f21603c39df123eb8680362184274aac9bdf1dbd485b3bba230960179071c95","content":[{"kind":"text","text":"The value is 42.0 at 300 K."}],"fidelity":"F2","id":"jvnys4s","kind":"sentence","match_hash":"3bcf9fa8412dca28be91d6423460233ddedd7add6c324d8a0f2b26038567d3d3","node_hash":"f5761f338b2878dff39a6ee724a75b13626dd625a0df96cf1cc6f9e8258cb7cc","ord":0,"own_hash":"7f0b9190d076cf01b51a8be863a51e9a8eeaab5d3ec8656202ff4d41578d4d82","parent":"ytp1e5n","text_hash":"3bcf9fa8412dca28be91d6423460233ddedd7add6c324d8a0f2b26038567d3d3"}
|
||||
{"align_key":"8e7fe271cd1bab88d86c8900fe3ffae0ce95c55af6659df1fca278d359296e2d","content":[{"kind":"text","text":"See "},{"kind":"xref","target":"tb49qpc","text":"Table 1"},{"kind":"text","text":" and the note."},{"kind":"cite","refs":["r3e21zr"],"text":"1"}],"fidelity":"F2","id":"mzwwhxj","kind":"sentence","match_hash":"9894a48790a8561966e68672fa13da20541d25a5178653720648f62cbc9ad36b","node_hash":"8f3e5338ba3c97efca4cef5c60d849757aed6334ee27ab807fa71d969089e46e","ord":1,"own_hash":"02ed6d50b8ac607b59e3f7b5116ee6143ed7e69af25b19c4037aa799bc330a88","parent":"ytp1e5n","text_hash":"5b1de19c9eb1399e54bde7e96f051cac8b337be1f307fac320292b8db7e39da7"}
|
||||
{"align_key":"282eea00b316a6950fb7179f6289a8b98359019e11cb23a3ff426cdecad90165","id":"exq1ter","kind":"paragraph","match_hash":"da88f35d24faf0099610c720953c4919647a5dfb9003889a15c464cd9c540fb1","node_hash":"062dd26bfb226ca9811d0dfb013df211cb201dfe7b4b25f9aba000f3212298d5","ord":2,"own_hash":"494e069be36a18ecaabf5a63be7c31617ade7a5460218ca83a2de3d8d8f964e0","parent":"b9wp3tt","text_hash":"da88f35d24faf0099610c720953c4919647a5dfb9003889a15c464cd9c540fb1"}
|
||||
{"align_key":"b8074a8bc013aa007023c4cce7334f1e1f22384d57a526ca22fd2f5589d5ab17","content":[{"kind":"text","text":"A second paragraph."}],"fidelity":"F2","id":"j663d4h","kind":"sentence","match_hash":"2e8313b033de5e17878ae778d6293bbd6e197a072f36acf7fe0840a690a7f31e","node_hash":"443539440dca73149ca75276492334ce9a5a6c50070137e8dc7bf414b75a27ab","ord":0,"own_hash":"acee4b6b1399bfde1dc67dea8d8c86b0db961d2af516ae4aaee26f294261456f","parent":"exq1ter","text_hash":"2e8313b033de5e17878ae778d6293bbd6e197a072f36acf7fe0840a690a7f31e"}
|
||||
{"align_key":"437c101749b0481e615fc7eed8dcacb536b65400c7e0695ad4cbb2bf2dae488c","content":[{"kind":"text","text":"It ends here."}],"fidelity":"F2","id":"rsw24qc","kind":"sentence","match_hash":"2888dbfa0c08fd65c58c923b920860c76e13913d9fa93b03eccbbf7bdf53b882","node_hash":"caeb3ae57d0821b8ac961c9507debbcda2b118b16cdc010b83a143a782058d57","ord":1,"own_hash":"705f77e8520c8c5ce3a7a495a20d8a9c55baa9801e49a55c341f5de79eeede75","parent":"exq1ter","text_hash":"2888dbfa0c08fd65c58c923b920860c76e13913d9fa93b03eccbbf7bdf53b882"}
|
||||
{"align_key":"cb0107aa0d562e8bd1188c33dc1ef5a1d07808e51edeabaa87465556d11b6ec8","attrs":{"columns":[{"header_path":["af5b51r"],"id":"pj5sk05"},{"header_path":["ajqxkgh"],"id":"nymcs5q"}]},"id":"tb49qpc","kind":"table","label":"Table 1","match_hash":"1951e0b61441d7b817b4967b36eee007f8e7525ac75fd359437eddb871e59f72","node_hash":"154c910857f33c152fdc78e42582510327055e62da9a25ab10c3891eeaf69627","ord":3,"own_hash":"fb4cc66080def0b42a06f7aa566a24957c7345c77b8d873ca5c790704a890f47","parent":"b9wp3tt","text_hash":"1951e0b61441d7b817b4967b36eee007f8e7525ac75fd359437eddb871e59f72"}
|
||||
{"align_key":"769a4e6d0003189c7e96c5d9b7e810a0d11c3a12832527ec94b0f86d277f51ca","id":"t2ps2mp","kind":"table-head","match_hash":"887fcea6a80333c6c02ae7e79735f0edad8d811f0b61431495f796f4bf6a7c19","node_hash":"6d8056adfb50dc0b65a2a65b47eccc5f47d5482a8dfbefa0d8a06f6641a4be3a","ord":0,"own_hash":"c5749bee3a4b981fb79cf6db125ebb416dce5a83613a00feecd9d4cf75df9bb4","parent":"tb49qpc","text_hash":"887fcea6a80333c6c02ae7e79735f0edad8d811f0b61431495f796f4bf6a7c19"}
|
||||
{"align_key":"769a4e6d0003189c7e96c5d9b7e810a0d11c3a12832527ec94b0f86d277f51ca","id":"rr9rtf5","kind":"row","match_hash":"887fcea6a80333c6c02ae7e79735f0edad8d811f0b61431495f796f4bf6a7c19","node_hash":"8bd1fa377ec390fdc36e17baa8c3a39d2df7ef2a53cd0c0dc745ae40e98f99f8","ord":0,"own_hash":"6c7c11bf1b6260162c4141f1468aa6869f5c33359900497e2cdb1a051488bd62","parent":"t2ps2mp","text_hash":"887fcea6a80333c6c02ae7e79735f0edad8d811f0b61431495f796f4bf6a7c19"}
|
||||
{"align_key":"2d711642b726b04401627ca9fbac32f5c8530fb1903cc4db02258717921a4881","attrs":{"colspan":1,"column":"pj5sk05","role":"column-header","rowspan":1},"content":[{"kind":"text","text":"x"}],"fidelity":"F1","id":"af5b51r","kind":"cell","match_hash":"2d711642b726b04401627ca9fbac32f5c8530fb1903cc4db02258717921a4881","node_hash":"59d1c20766a77bacde2aae80a134c7156fbcc708c140a3bb2d2a67f78bd9c6f5","ord":0,"own_hash":"c68933b07bc7c5b806892ae36b3e4c3205a0a2066fd6f8255578f7d1ca86dc10","parent":"rr9rtf5","text_hash":"2d711642b726b04401627ca9fbac32f5c8530fb1903cc4db02258717921a4881"}
|
||||
{"align_key":"a1fce4363854ff888cff4b8e7875d600c2682390412a8cf79b37d0b11148b0fa","attrs":{"colspan":1,"column":"nymcs5q","role":"column-header","rowspan":1},"content":[{"kind":"text","text":"y"}],"fidelity":"F1","id":"ajqxkgh","kind":"cell","match_hash":"a1fce4363854ff888cff4b8e7875d600c2682390412a8cf79b37d0b11148b0fa","node_hash":"838e3fba38f0797d40522b7063cb5c2962e32a019c09c19f09849ced73079a87","ord":1,"own_hash":"28df42bf1dcd44b053275ed014bd1599914f17adabc0c7fdb3e4247dc648ac49","parent":"rr9rtf5","text_hash":"a1fce4363854ff888cff4b8e7875d600c2682390412a8cf79b37d0b11148b0fa"}
|
||||
{"align_key":"b902cc4550838229a710bfec4c38cbc7eb11082367a409df9135e7f007a96bda","id":"dmsstkg","kind":"table-body","match_hash":"24cb52bc2dd0b9ddd4650c011d76b585e76c4d4ecae8cf220c7600efb808d738","node_hash":"baf17577660aa6f0ba9c8703d30816d77cfce7dbf0ea3257ed830fa9ab94ce9d","ord":1,"own_hash":"b229a7f92314227bf225ad27010a546e7c2373f4b30b7f6ec372e568cbacb6aa","parent":"tb49qpc","text_hash":"24cb52bc2dd0b9ddd4650c011d76b585e76c4d4ecae8cf220c7600efb808d738"}
|
||||
{"align_key":"b902cc4550838229a710bfec4c38cbc7eb11082367a409df9135e7f007a96bda","attrs":{"header_path":["rdrqkv7"]},"id":"r3e7hfs","kind":"row","match_hash":"24cb52bc2dd0b9ddd4650c011d76b585e76c4d4ecae8cf220c7600efb808d738","node_hash":"97a1f5b27bbfe8c9d2cec7212b519b4993506fc8080be3eff02f3aa31515a19d","ord":0,"own_hash":"6c7c11bf1b6260162c4141f1468aa6869f5c33359900497e2cdb1a051488bd62","parent":"dmsstkg","text_hash":"24cb52bc2dd0b9ddd4650c011d76b585e76c4d4ecae8cf220c7600efb808d738"}
|
||||
{"align_key":"6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b","attrs":{"colspan":1,"column":"pj5sk05","role":"row-header","rowspan":1},"content":[{"kind":"text","text":"1"}],"fidelity":"F1","id":"rdrqkv7","kind":"cell","match_hash":"6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b","node_hash":"87da3bd568286f3d0578d8a813496d15faafb62f4db44b07aa1c29e52cda34df","ord":0,"own_hash":"fb474321001657b59bccd3cae0987c544a4ef9a27214626d77695f4db237aa93","parent":"r3e7hfs","text_hash":"6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"}
|
||||
{"align_key":"b8736b999909049671d0ea075a42b308a5fbe2df1854899123fe09eb0ee9de61","attrs":{"colspan":1,"column":"nymcs5q","role":"data","rowspan":1},"content":[{"kind":"text","text":"2.5"}],"fidelity":"F1","id":"f463wj7","kind":"cell","match_hash":"b8736b999909049671d0ea075a42b308a5fbe2df1854899123fe09eb0ee9de61","node_hash":"f1cd6d5339c84d5c36f8e1ea484a8d837f3200f05d1b106f6119dfa30d846bfd","ord":1,"own_hash":"088eff622eb3086d68c4433cf5e1783dc9f2a6724c3536c31ec0bf80b5f89db5","parent":"r3e7hfs","text_hash":"b8736b999909049671d0ea075a42b308a5fbe2df1854899123fe09eb0ee9de61"}
|
||||
{"align_key":"b35d81b0ff35d6d05ad2c187a289d3017896427dfd8bb98160bc806ac0ec32f7","id":"aw97y35","kind":"back","match_hash":"9a2d5d28ee47736a00d074e066bb944154f95a192360c8c04226c3d12a4f7d1e","node_hash":"fcb8027f7c89115f048b9c5d6770847248f4e4fbc61cbc8ea0b04079b4d58350","ord":1,"own_hash":"bbb972bdc024231b505f4d8ce5e711fbb75c8b5ffd1b5d42ee3fb8586b85f867","parent":"s0fn2fj","text_hash":"9a2d5d28ee47736a00d074e066bb944154f95a192360c8c04226c3d12a4f7d1e"}
|
||||
{"align_key":"b35d81b0ff35d6d05ad2c187a289d3017896427dfd8bb98160bc806ac0ec32f7","id":"yd513mw","kind":"references","match_hash":"9a2d5d28ee47736a00d074e066bb944154f95a192360c8c04226c3d12a4f7d1e","node_hash":"8b8a9000e984c3efeb27fc40c8fbadd7349dd64860aa276dcd2a25a57ce52e87","ord":0,"own_hash":"2a5302e2041d0e59458fea212dd51b89299901318bfceeeff227c1a07d3f5d1a","parent":"aw97y35","text_hash":"9a2d5d28ee47736a00d074e066bb944154f95a192360c8c04226c3d12a4f7d1e"}
|
||||
{"align_key":"b35d81b0ff35d6d05ad2c187a289d3017896427dfd8bb98160bc806ac0ec32f7","content":[{"kind":"text","text":"1. An Example, 2020."}],"fidelity":"F2","id":"r3e21zr","kind":"reference","label":"1","match_hash":"9a2d5d28ee47736a00d074e066bb944154f95a192360c8c04226c3d12a4f7d1e","node_hash":"71b1af6dd6a56f24cb3b338e0fe99df06b9154ecdf4b391b00b7a7e61e23a8ed","ord":0,"own_hash":"f7c9bbc8c7456e6dc435feeaaa02cbfdbe487523b020105793fb11b91d0894f5","parent":"yd513mw","text_hash":"9a2d5d28ee47736a00d074e066bb944154f95a192360c8c04226c3d12a4f7d1e"}
|
||||
@@ -0,0 +1 @@
|
||||
{"note":"Built by hand for the conformance suite; every reading is synthetic.","stages":[{"processor":"local","stage":"hand","tool":"paperspec tools/build.py"}],"tools":[{"name":"paperspec tools/build.py","version":"0.1.0"}]}
|
||||
@@ -0,0 +1 @@
|
||||
{"at":"2026-10-11T12:00:00Z","by":"ana","doc":"tiny2026tiny-j4qm","evidence":[{"kind":"crop","node":"af5b51r","sha256":"78b08276b5122feed3829e8dd19684fa8a4a41f79cb83a499d40341e09f5d658"},{"kind":"crop","node":"ajqxkgh","sha256":"398bab4177685c88eef399d814d34c81baa556d58cd508bd5ddb33ac53a5cbfa"},{"kind":"crop","node":"f463wj7","sha256":"88b1e820b569c3a0fd025a6b6c502271ed73bbce720dd8a2e416d6a5dd0e9d67"},{"kind":"crop","node":"j663d4h","sha256":"d6484c89588a560f64bbceca108f5446e47bb5cb85521fbffc9d6d37f252e5c7"},{"kind":"crop","node":"jvnys4s","sha256":"3139fb30b88062bd0c6bbb028c4c57fc748218ce1d7a612d282e292d6a02ffe9"},{"kind":"crop","node":"mzwwhxj","sha256":"83a7fcf09321f8a644c58120f80dede5d73d89f50d080ccbb143ec5b485e3088"},{"kind":"crop","node":"r3e21zr","sha256":"ff809e11101fa6ff5422e5232e83142c1a43dada0e56d63ec03fbce3474dd1aa"},{"kind":"crop","node":"rdrqkv7","sha256":"c0699aceb344812ebebb1414838641f0761184d5113dcc870d07c721fd289437"},{"kind":"crop","node":"rsw24qc","sha256":"b4c3b133c707b1a9a2cec2efe5c17731bada0d6bace5b1fb3590c5c5ab18bb92"},{"kind":"witness","sha256":"fda3f1e9bb3538cd85dcc42281e00fd045f726652664439ce5a15d8489425b21"}],"format":"scienting-receipt/1","id":"k4wt522d9zvjr","level":"F3","nodes":[["af5b51r","59d1c20766a77bacde2aae80a134c7156fbcc708c140a3bb2d2a67f78bd9c6f5"],["ajqxkgh","838e3fba38f0797d40522b7063cb5c2962e32a019c09c19f09849ced73079a87"],["f463wj7","f1cd6d5339c84d5c36f8e1ea484a8d837f3200f05d1b106f6119dfa30d846bfd"],["j663d4h","443539440dca73149ca75276492334ce9a5a6c50070137e8dc7bf414b75a27ab"],["jvnys4s","f5761f338b2878dff39a6ee724a75b13626dd625a0df96cf1cc6f9e8258cb7cc"],["mzwwhxj","8f3e5338ba3c97efca4cef5c60d849757aed6334ee27ab807fa71d969089e46e"],["r3e21zr","71b1af6dd6a56f24cb3b338e0fe99df06b9154ecdf4b391b00b7a7e61e23a8ed"],["rdrqkv7","87da3bd568286f3d0578d8a813496d15faafb62f4db44b07aa1c29e52cda34df"],["rsw24qc","caeb3ae57d0821b8ac961c9507debbcda2b118b16cdc010b83a143a782058d57"]],"rev":0,"root":"15d9c8bd5472afd7064578e5663d3b7fd21249adc6cdb40fcbe1b790e3fae801","scope":"all","signature":{"key":"ana","scheme":"ed25519","value":"/xOfCboOpgu29ztKi22IU9crgC5LYetrHOMpQtqj4QV5dVP73n/ze94hyPknYO5qNPgBmYRrbJZBIIHdwqxoAA=="}}
|
||||
@@ -0,0 +1 @@
|
||||
{"label":"1","node":"r3e21zr","resolution":{"type":"none"}}
|
||||
@@ -0,0 +1 @@
|
||||
{"format":"scienting-roster/1","keys":[{"did":"did:key:z6Mkj7iUX8QG7zkAtNaV78CUXcenhD87qWwQbc7NU5aVXyW9","id":"ana","person":{"name":"Ana Example"},"public":"RUiz5j+y0QwgOtsQpqXrlq+gy3c/JFnkxwvlWUNX4Ao=","purposes":["sign"],"registered_at":"2026-09-01T00:00:00Z","revoked_at":null,"role":"owner","scheme":"ed25519"},{"did":"did:key:z6MkhemKN7rMQcgt6wT2eWPyx3vFRS1RUoRziLMnLq2vZ9yi","id":"ben","person":{"name":"Ben Example"},"public":"L4WMLs7xLjBLRsxS/EYpD194puMBpADybcfFEWxBkWk=","purposes":["sign"],"registered_at":"2026-09-01T00:00:00Z","revoked_at":null,"role":"editor","scheme":"ed25519"},{"did":"did:key:z6MkrBf2w3MUroaNBiHTQJzH4e1w31jpcosd5vNxjikijndU","id":"ben-spot","person":{"name":"Ben Example"},"public":"rkzxigjCXg869PGSFAVr4EDXXRmwk+S/+wJ93lrG4dc=","purposes":["spot-check"],"registered_at":"2026-09-01T00:00:00Z","revoked_at":null,"role":"editor","scheme":"ed25519"},{"did":"did:key:z6Mkgrc9HCeEUL5tz1bVfuuDeSm6mP6hyWUX5ivhgReSbEQM","id":"cara","person":{"name":"Cara Example"},"public":"I7J1GqG5CHOc0LHYZPNNto1Me2lJUzBVn2A7GrUGbZ4=","purposes":["sign"],"registered_at":"2026-09-01T00:00:00Z","revoked_at":null,"role":"reader","scheme":"ed25519"},{"did":"did:key:z4xcFfnTC6XJy4gzg9whfyMzcnxV7yM2XafMFynKXhAEvMgjfQCxSnjZaa53arz2iNo8v35ZN5SdAUcbFkbuvftcMczRT2CPhYsXkNYZhDzXWQVS5KZZkhnMDmwChWfgRHu4Bs6KHyEmvzwesTioW5yS3YtfR7mUPJAwWSRq9f23HRxzenGpVVBcVjpd8YDZ4Y1ZamcUfesnB6pGLrPtLDvGM7Te1cJWoRG4m3TetEF3i9V3W4CH43nouCwUPbjy7dpTNEWiCqaTPiPhV8UEWBD8b9e1729PwoUFyAFreuq6wvhphLKGHhFCFujrUtqDZPs6FFF1Q7Lpt9eFcjbxrZSAYsh9VTfxaUeQ4HmFqzrg28EEjJzxxADZyjTXDsfwskRbibHSms9bbN2xK6GQcUxE2mrA2ULfYwsk5RQsVULUTj3pMMXpxRqP4zerzui2ZRZ3SqeNUwqnhmF861pEtcemZPY6ivcX41QK3ekCtpc1HndtY9xua1Lrhs4jd6qEbxHWzBPHok6qTpyxnn7ubZssBqSMz3uNrou1ayZGDn1ayAXtzCJPjAcxdNX1dpm5vyDB8GYtNKsQHuiX5xUd2EMAVfq4cFrZ6ncY1zrG5exH6mhJYbZfW7BgXxq7GsnzAAGkzgHCRADe5EEm1Hj1YdmVBTiaGsPGYkF4Mcrw3T2j3AcPJCzPLRNjKBKXyHAcf3VPUmreaHd1GoA5zqvtANSPmppY2AhCAj8u6n92fiyBgrvJTh4hyvtMFcwaa9vKnY9rBS4n5XGpdwKQe11Tk5sah8VZc2PyH2WPBU3DmhZSwUkKHRQQQQMXjrLjuMtygzxWBgrJAcWRPzxmzHZEj5x9GgFZb4dPDwqVXsgR25KrpuyQKcxfbxzQoRprnhu1ec8SfX5zeUo282Si9dBZ3JVdxzYHzP6xSiuBeHHFMvMwb1MKUq2dMi9vWdg2eCDo5wTvSaTVcdYGtZsT7HMswWtxx9GLw1RafYRcNqMhBhCbRdJszUKjQKwNNZbaryRs4kTYicuE24PWbqfxdJnrzrLbXnVBDMNHjX8ESXSKTMnAoE1AiLgjdj3zbBrY39Pxc72EikA7GvP2qxKZBkJ6G2RRWCw9d3nZKmTmQqP5PP9HgdtSTnZhNTJqBkwL3iqfoWxtbkLjLLSQc3dbFpmhe4kAh7VUUDcLzjb4nGzCbr5U1YoqAoLnSC9BPijnfMHxBP6i8cR762ryxPwe7HdGk62DVYoqxbwz8ygrDPjdPi3t11PpHp51GxuhMkoR3GFxAdMEv8j4tVpJ6qjefULEFTtRPzZ5kTE57RTxC4wg62qcYwupWx4dvvB2BR9ZGnNwCojpBYByeeYETrgm4HJjjS3SH64sbpyqz7336YMAcWyQFc9BeqjQHHUHS8CJ82N88apbPPE8N9X76DQ8PgwACtR4D5ofE9o14kpdVZFV2YMtmnKCybNLn3atspK6T1ZPYB3vQ1c4DbzZFgCpm6izEzxsY17in79ieo3cY965Cr5mkxca29VxcTaEtovdu9sKAL4VgCZzWkps5nnimX5JBEdVKYxTtMb6CcTkdWGFtXBTBuAMTpRNLXG5nG4bq9XXLkFS4oXpVS7KayqAMtrrqttpgwdAPNuzd6E4JskxdenwMq6qzMTDKoMqGDVEKkwCxCcbUtNpHGMLWMMk9MDrsPvcU8u2C89UmJmsfS5gQqswkz6TfXvthM3wPcuKaX7TUJJRzYstWsXRKUaPqqT3ppftCbXPFgia3mXkA5bk9Y3GWcTADGTnzKkTzbnL6hsgQW1FyvsFwUiWUJd5weeHkfaHt8iV3PKy99S6d831iLCfFWM6bYZgEBvyx5seHSpiaXRfSv4A2yDsf4Tb4EVsyDUJPUmZLnbFkJmw46A6PoQHdwfBbXWV47DFM6w5mKXCPmKzuAG1Vmw7D36n4oHd91r1VzTynVnhD1EA5UVh4qhiw2CnWgo2uAPxEpLYnvrCLiVprnzdPzvZZqMUxXRFWHwfshJDARRLvP933693aWxa5PeDNgMjZYgKJBV5e66Z1Mk5rYegEuSq7uyz8Mw3iuidtJeqBugbNCYeNdmeBPgKux8HcuFNqQaVwhP9vW8vyaU7DvuKEeXs1uyAgtk9RCua2Mx8rQqUwQigWNjXaJoSYqMT9SVEGUSYAGQiLnMFENqG1r87uhxV58hTwR8QED9cQkStFXeuZAMY6FWTZCsD5juC48KdqoUQYr77iBy7fW2quQNdPvwEUdhh1mzSTX2PPubCbm9rcdBxBQ2CBZizn1EsbPMic1X39t17scRE5F4Yank18EF4aUmJwwNHx5m1WKDQMZ1kJQRyhtRvAHTPqBdJCw5SHaEqBVpEQHUZwBKsQoTRj4Gk1opv6XfczoK3MLuprTMSx2maw5Gv6LhF2SWUvEXMMqoeqVzyP9g11dumkKQLMiAQa2VGaa7EF7Foj2ZDUhPM6PPiffHMhDMwWhRBywg3SC6aP9zz2TdMXweHv8rags9chFZ217aAP3bcCf5i1VZqPT9b8Ea7ykjjUy6PNwiSforRXN46suuRFREuhx6DuWDojythjH73wMAeKKx23rF4QfdUxzkC2mmmS4dq8Xx7Bda4e31EGab4t81Jk4dAVGjSrZC9wx89CAjovhoejgDTKNsN3ri4GjW9UD","id":"dana","person":{"name":"Dana Example"},"public":"lQ6M2DulKY4RkQLGTPGZD+CHlOOib4kBkwlccVNWRDPco1k5kHtelT/yUP4+CoAQnHnLu96vpeWztaee/9RmjR3bstGj+P5tOSrwFlPuyNUPOWPNjwCQLrVEyeUGBaA4+HRvFwK7C4OHB8EJWYtC0OuH+tRPlCdLpxlVcZZcM7dsZYe2BDNenbWfp4TeX2Oa+dThlceDY0m9MewwqUrd5xdo9tc8PS9R9o0ZUWf0vDw7Fc5AcsWwbf76lDLvIbyd0aCaHJ7eaK6DFsBuZFKVdlZlH0inJciAMF8dPoRuE+A0VlZTEOsOivNWprM5iLHzXse3zSoHLldWr0t4hWxHH3MBQ57Ucee8RTU6hFRfqfFRl6zJQyRZOFZZoYD9QwXkR3NmUzV/FcsOMHpbgTcY7O0TAajPnfpSTp+XdyPVBR7TlTsturUCpryP0ZX1S3VJk2IaneB123thtcOtWsbqdT3Bb846H7yudI95WVTixIS/KIwoCbekSf8Y9+iW/xRVSWLRVc1gpigDxXfieSA7bI+qiUBjiKR7QU1KFYZA58VcOQhzeMLY6an34rsW4WHAwzzSv8Q6vrwpn8Ct9fTsIeiZsWZLueNkIUfjR0G1bHHoT2RHKton0AMRjOUGSKUUB4DNZ5xzXvC0jvUMWlgHB9z2wBCsIkIDVWqSA2DD0xeIY2wSUVPwPc1MnBAf/Fx3poweUlcPWglR2VaO9ematC4hfLxxkGldGQt3C6ZLPsm96S7o6j88rwOqkDNIR1pNJOepgciJH/w4Xwtg9gJ52CpdlCeSllRQD74l95ysmZ2D/gLweNoUt61P0RYQQelio8VnPUNB1e2uK7zW9joG1k59CjJGQNvuZr6JkQ9+Hxo5xKEOy9KcpT6t48wTzbz3YMFDxTNl0/DzL8qdTU2UrSW6/TFgPLokbAQN00yhw0lg8cR/e1m+ujFyBeesL3luwE6HNcIyK5Y/+To04vR3OD7Uz8cnABxWyOeSBm2R2bu2fxeN0Hlv+qhoOYtbZ1DKx/aES4z51jATynEIdMIMSNhmVDoDiGODh9ocenzg/DUarjIzWltPFRyQj+tnFGTXp7C87Line truncated
|
||||
@@ -0,0 +1 @@
|
||||
{"a":"42.0","b":"42.5","format":"scienting-suspect/1","id":"aaaaaaaaaaaaa","kind":"number","node":"jvnys4s","witness":"zzzzzzz"}
|
||||
@@ -0,0 +1 @@
|
||||
{"witnesses":[{"id":"nmfryke","kind":"pdf","media_type":"application/pdf","origin":{"source":"author"},"pages":1,"rights":{"asserted_by":{"by":"ana","evidence":[{"kind":"statement","note":"The team's own draft."}]},"at":"2026-09-15T12:00:00Z","basis":"own-work","format":"scienting-rights/1","license":{"spdx":"CC-BY-4.0"},"uses":{"accessible-copy":true,"ai":{"external/local":true,"external/outside":true,"external/outside-no-retention":true,"external/tenancy":true,"internal/local":true,"internal/outside":true,"internal/outside-no-retention":true,"internal/tenancy":true},"quote-public":true,"read":true,"redistribute":true,"tdm":true},"valid_until":null},"sha256":"fda3f1e9bb3538cd85dcc42281e00fd045f726652664439ce5a15d8489425b21","size":1000}]}
|
||||
@@ -1 +1 @@
|
||||
{"doc":"scienting-doc/1","files":[{"path":"document.json","sha256":"882e41e87ffbaa617e55b13fe5f9c1bdfd2e6c53159a57ab17c0b6a8b12e8b7e","size":802},{"path":"nodes.jsonl","sha256":"3845502f83168047e51719c45fd8732b3e6b37741fb8944771cb9d18bc791518","size":8295},{"path":"provenance.json","sha256":"4bc7649bf6d3113f6c72b4016713654f57c8f03069632eabd1e6025c05cb9dac","size":226},{"path":"references.jsonl","sha256":"a854aa7fa3f337bd2641fe1986882b3d43acf2e83a65671cd4cfae6465103933","size":344},{"path":"witnesses.json","sha256":"badd17f82e6cc4aa8d116d2056d10b868fbf6978fa47947d89404c458b6a532c","size":766}],"format":"scienting-package/1","key":"writer2027fixed-ynr7.v3"}
|
||||
{"doc":"scienting-doc/1","files":[{"path":"document.json","sha256":"900a33206b1f44f62e3600a8484cfefe2dedcfb93be7c71050a69b89e3389609","size":802},{"path":"nodes.jsonl","sha256":"12109f6b7f2e76391ab2e417f0245142d7319c64ed3e11d079c0eeb2bdd490e9","size":9000},{"path":"provenance.json","sha256":"4bc7649bf6d3113f6c72b4016713654f57c8f03069632eabd1e6025c05cb9dac","size":226},{"path":"references.jsonl","sha256":"a854aa7fa3f337bd2641fe1986882b3d43acf2e83a65671cd4cfae6465103933","size":344},{"path":"witnesses.json","sha256":"badd17f82e6cc4aa8d116d2056d10b868fbf6978fa47947d89404c458b6a532c","size":766}],"format":"scienting-package/1","key":"writer2027fixed-ynr7.v3"}
|
||||
@@ -1 +1 @@
|
||||
{"counts":{"leaves":7,"nodes":15},"fidelity":{"counts":{"F0":0,"F1":0,"F2":7,"F3":0},"lowest":"F2"},"format":"scienting-doc/1","hashing":{"algorithm":"sha-256","scheme":"plain"},"history":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","key":"writer2027fixed-ynr7.v3","kind":"draft","language":"en","license":{"spdx":"CC-BY-4.0"},"meta":{"author":[{"family":"Writer","given":"A."}],"issued":{"date-parts":[[2027]]},"title":"Fixed charges in biomolecular force fields","type":"report"},"meta_hash":"6a844957c7f8e582c6f30d836e702f6fa816a1bea5d5c0e157b2cfbbacba0ec3","policy":"full","relations":[],"rev":0,"root":"5e9137c41b5832b63c299ce20732fe7afc91bc8de1c67496ff09f0272880c011","store":"smithlab","version":{"seq":3,"type":"draft"},"work":{"key":"writer2027fixed-ynr7","same_as":[]}}
|
||||
{"counts":{"leaves":8,"nodes":16},"fidelity":{"counts":{"F0":0,"F1":0,"F2":8,"F3":0},"lowest":"F2"},"format":"scienting-doc/1","hashing":{"algorithm":"sha-256","scheme":"plain"},"history":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","key":"writer2027fixed-ynr7.v3","kind":"draft","language":"en","license":{"spdx":"CC-BY-4.0"},"meta":{"author":[{"family":"Writer","given":"A."}],"issued":{"date-parts":[[2027]]},"title":"Fixed charges in biomolecular force fields","type":"report"},"meta_hash":"6a844957c7f8e582c6f30d836e702f6fa816a1bea5d5c0e157b2cfbbacba0ec3","policy":"full","relations":[],"rev":0,"root":"4db38d21c978dcb5be1aa3a46af4d0682181ac5ca5621508534b0c856cf0d586","store":"smithlab","version":{"seq":3,"type":"draft"},"work":{"key":"writer2027fixed-ynr7","same_as":[]}}
|
||||
@@ -1,15 +1,16 @@
|
||||
{"align_key":"1a2bb9eac1e4dc9f227cf4559731b2057dc2a9a2b9d6b54889a56d91cd87a782","id":"eaaw8zs","kind":"document","match_hash":"20454adf8e339b779917cfcb20d652557204568101ce947616928ef833350e2b","node_hash":"5e9137c41b5832b63c299ce20732fe7afc91bc8de1c67496ff09f0272880c011","ord":0,"own_hash":"34444fe0e6bdbf3927a579fe3286859d204ea0882a381b7769ffd4905551d24f","parent":null,"text_hash":"beece988a027b059e0ff0a0097337b6fe347e680acdfe8e72e43452554fac195"}
|
||||
{"align_key":"37108c46d3691a0fcb4a378eda3fe2cd7ab3843f22cfcc34d486d069123ea9a7","id":"nedkmhw","kind":"front","match_hash":"3d4535506043f6f04de395aeb16ea50f7f26f2ab341023fe1883f97c2749d406","node_hash":"e06b854f1015214643f375533f258b90470f06a08ac60a13b66b12dc7736bb39","ord":0,"own_hash":"0167516d70e0a89263e33c0f9be5ca4443113347814530257a60d43910af71b6","parent":"eaaw8zs","text_hash":"3d4535506043f6f04de395aeb16ea50f7f26f2ab341023fe1883f97c2749d406"}
|
||||
{"align_key":"dbdc4c68fc8b3f2691befec850e48fac1c30723c809353a9ee99f2b52c45fada","id":"x632xpk","kind":"document","match_hash":"a55c5c85adebb4afc46d8acf9a58639b972824c71af26a9a450b52398fde1589","node_hash":"4db38d21c978dcb5be1aa3a46af4d0682181ac5ca5621508534b0c856cf0d586","ord":0,"own_hash":"34444fe0e6bdbf3927a579fe3286859d204ea0882a381b7769ffd4905551d24f","parent":null,"text_hash":"a579520f61ab893092f6c72df2e4cfa1635d1bdf4997799cde36c2f62aa797cb"}
|
||||
{"align_key":"37108c46d3691a0fcb4a378eda3fe2cd7ab3843f22cfcc34d486d069123ea9a7","id":"nedkmhw","kind":"front","match_hash":"3d4535506043f6f04de395aeb16ea50f7f26f2ab341023fe1883f97c2749d406","node_hash":"e06b854f1015214643f375533f258b90470f06a08ac60a13b66b12dc7736bb39","ord":0,"own_hash":"0167516d70e0a89263e33c0f9be5ca4443113347814530257a60d43910af71b6","parent":"x632xpk","text_hash":"3d4535506043f6f04de395aeb16ea50f7f26f2ab341023fe1883f97c2749d406"}
|
||||
{"align_key":"1c346b0b6df77616e3db9eebcff5d56ccc123715374eb60a0df1a6cbe1e059ec","id":"w7dabwn","kind":"title","match_hash":"d3c3de666d0290878de3949bc0e0ffcaef965c66d2b61e81a5e615e26a2997df","node_hash":"25cb59151aa6bb80d785263e14ffb762938f1a0991ff3a069a1fc6dc6fd42fc8","ord":0,"own_hash":"c22e4fc822618a3a2c774cc9ea6fc5fc5b34463724257cfa4fd33022d4e35165","parent":"nedkmhw","text_hash":"d3c3de666d0290878de3949bc0e0ffcaef965c66d2b61e81a5e615e26a2997df"}
|
||||
{"align_key":"1c346b0b6df77616e3db9eebcff5d56ccc123715374eb60a0df1a6cbe1e059ec","content":[{"kind":"text","text":"Fixed charges in biomolecular force fields"}],"fidelity":"F2","id":"csgs20p","kind":"sentence","match_hash":"d3c3de666d0290878de3949bc0e0ffcaef965c66d2b61e81a5e615e26a2997df","node_hash":"a859025788a7d67363ba278fd6d67e4349ccb9bccb4c215f60271b3b70b0d549","ord":0,"own_hash":"102b7f337262638415717e077a41d3a4ae579b32a37c837c4ab404a075bf347f","parent":"w7dabwn","prov":{"backend":"typst reader (illustrative)","witnesses":["tszzg52"]},"text_hash":"d3c3de666d0290878de3949bc0e0ffcaef965c66d2b61e81a5e615e26a2997df"}
|
||||
{"align_key":"6bb0f8a42947682adacb47add8ac5d59c3d49f02ee275e8d390acab500b441e1","content":[{"kind":"text","text":"A. Writer"}],"fidelity":"F2","id":"t5xv7jz","kind":"authors","match_hash":"cb38b0c8294dc57d6923a5aab72e1093289f2efbb69293d1f6f5702536a54720","node_hash":"282f0d59e22716e1c28ed5de02bf0729c309bec17bb2ab59c7cb2937c2dad1c0","ord":1,"own_hash":"f1fc7a0ac9b744d5f99583296e8a980e52f80a2a398f240803d457d68a124973","parent":"nedkmhw","prov":{"backend":"typst reader (illustrative)","witnesses":["tszzg52"]},"text_hash":"cb38b0c8294dc57d6923a5aab72e1093289f2efbb69293d1f6f5702536a54720"}
|
||||
{"align_key":"2ae14f38f7c9c72752502a2766e9ac856f477479fe1456b47d2ef880f17e8eb4","attrs":{"level":1},"id":"tqcsy8w","kind":"section","label":"1","match_hash":"34e0c5261e9055e0fa15b1e1c95e2c6cf8f55f6a9fa0177f6dd36f09410864ea","node_hash":"818f509bcf5783450604a80a5bd200232a3ce88e446c8eca5feeb7e6d15f9c6a","ord":1,"own_hash":"78563e96f51db1954d3fabe08f3748956b564c87ba4c8f7954bf747545a37fcd","parent":"eaaw8zs","text_hash":"86a59f6424a18898cc62dc1413ad12a0cc2c8dfbd84d218c43316bc8659fddf2"}
|
||||
{"align_key":"d3db5338aae140c5cc04ac37690aa4f98041e14a042bc6473d54ecda8d95f93e","id":"wxsngqp","kind":"heading","match_hash":"b605350bc00209520b7cd8f546322663356ba630708f71bbf30aead6b3dd608e","node_hash":"c7288f33d2cb2ac9b9c146dabd403d2e64e793418bd31ac14802349543ac84c8","ord":0,"own_hash":"e813ff86a8920cef741e548eb5df545774b520d2fadbdda6e2b872a6729b9d26","parent":"tqcsy8w","text_hash":"b605350bc00209520b7cd8f546322663356ba630708f71bbf30aead6b3dd608e"}
|
||||
{"align_key":"2c0677fd2f58c8bde302d6c44ef1e588b5b460dfc338accc08ec98ff1ffcd375","attrs":{"level":1},"id":"gmzn0mf","kind":"section","label":"1","match_hash":"18b16ea1daa5fa8371000fcde7cccb22940b2e2c94c7dd691f5b822e7c9b4fad","node_hash":"b9dd1c100f1e4b5af2ba32aab3c471a802825a826440b900000a6ce594a54774","ord":1,"own_hash":"78563e96f51db1954d3fabe08f3748956b564c87ba4c8f7954bf747545a37fcd","parent":"x632xpk","text_hash":"91bd6528549b451f8be7cca2e31c075e382992fadec65ef4b4f1c2196f1760c5"}
|
||||
{"align_key":"d3db5338aae140c5cc04ac37690aa4f98041e14a042bc6473d54ecda8d95f93e","id":"wxsngqp","kind":"heading","match_hash":"b605350bc00209520b7cd8f546322663356ba630708f71bbf30aead6b3dd608e","node_hash":"c7288f33d2cb2ac9b9c146dabd403d2e64e793418bd31ac14802349543ac84c8","ord":0,"own_hash":"e813ff86a8920cef741e548eb5df545774b520d2fadbdda6e2b872a6729b9d26","parent":"gmzn0mf","text_hash":"b605350bc00209520b7cd8f546322663356ba630708f71bbf30aead6b3dd608e"}
|
||||
{"align_key":"d3db5338aae140c5cc04ac37690aa4f98041e14a042bc6473d54ecda8d95f93e","content":[{"kind":"text","text":"Introduction"}],"fidelity":"F2","id":"zvt571v","kind":"sentence","match_hash":"b605350bc00209520b7cd8f546322663356ba630708f71bbf30aead6b3dd608e","node_hash":"8a2293448ea48f2d3e279e609965f34443fae62b24b6fa13524f14a324749285","ord":0,"own_hash":"7c40e5ddd02d461a4ee50cde05532932e1d737ab3bc74b722cecf16cc6ffe59b","parent":"wxsngqp","prov":{"backend":"typst reader (illustrative)","witnesses":["tszzg52"]},"text_hash":"b605350bc00209520b7cd8f546322663356ba630708f71bbf30aead6b3dd608e"}
|
||||
{"align_key":"e9f8aaa4f05b10a153d268295a96c6adb2c39164a98b93eb1927e00838afe1fc","id":"x9ryw92","kind":"paragraph","match_hash":"e506663279fb3bebf3612dc69a36f5e090228abc0197f5228d4f0bd4abd47812","node_hash":"b17dff0cff3ce730e52efca92b9fe585ffc956cc9f76e52a8b37721cbbec442f","ord":1,"own_hash":"494e069be36a18ecaabf5a63be7c31617ade7a5460218ca83a2de3d8d8f964e0","parent":"tqcsy8w","text_hash":"844954fa39d218228b947367bc95f21c449b4d70d1521a7f016e308643e6cf48"}
|
||||
{"align_key":"7dc562c54f1b1cc46e472838c4b2d7c97b3e1b4d39172628d6607b0f2d313c3e","content":[{"kind":"text","text":"The bond term is harmonic in the bond length."}],"fidelity":"F2","id":"kda5wym","kind":"sentence","match_hash":"8f22f3f58beb618723a14dd8fee8caaeb5cef6b26f43d88a5ddb4ff42f86d63e","node_hash":"dd438a68616e63fd1cd5050d308779af58dfed2b4d43cc5a4bbab3fc8d4f2bcb","ord":0,"own_hash":"46dfbddc0e456a2b7f4105b8d3636220ff9145acccf3bdf81a206f0b84f95b63","parent":"x9ryw92","prov":{"backend":"typst reader (illustrative)","witnesses":["tszzg52"]},"text_hash":"8f22f3f58beb618723a14dd8fee8caaeb5cef6b26f43d88a5ddb4ff42f86d63e"}
|
||||
{"align_key":"81422dae1385acfea463f7b7c75962de0bf92671d970a6ae9643763a8f87cd7f","content":[{"kind":"text","text":"Its constants come from a two-step fit "},{"kind":"xref","target":"hale2026harmonic-damb#a4jrz2t","text":"(Hale and Osei, Table 1)"},{"kind":"text","text":"."},{"kind":"cite","refs":["ebcq5cy"],"text":"1"}],"fidelity":"F2","id":"qgh1k31","kind":"sentence","match_hash":"fe82fa8560942e052e31d9b18cc8d3a9ba54ce01d91b66538ded6ff682a4e885","node_hash":"93a39490870e694299e88e6f475d42c38078d1442959e555bdbdf58488dcf187","ord":1,"own_hash":"e004436e7b28ff3dc41e0056f231ba707d9be985694e68acb911345a547842ed","parent":"x9ryw92","prov":{"backend":"typst reader (illustrative)","witnesses":["tszzg52"]},"text_hash":"0d5b27a20da22922ba0c5b65e06581a09d60b899e6daddc63b0e9c1dd3819055"}
|
||||
{"align_key":"fae2fe63ef00f3826f525b2fd7f5c29824c06c1461b0a648927598f1efc84bc0","content":[{"kind":"text","text":"In that fit the energy is "},{"kind":"math","notation":"typst","source":"E = K_r (r - r_\"eq\")^2"},{"kind":"text","text":", up to a constant factor."}],"fidelity":"F2","id":"wbntyy4","kind":"sentence","match_hash":"9b297e00b7348c2df4c6b12f67b2f879217a0d71e1be382fc8a4f6bd7439ddd0","node_hash":"18b4b664473aeccb797c3c52b0d3fc3c37a33593d3aca32640acdb40161fa3e2","ord":2,"own_hash":"7ae59942b690f78ed24570ba25764a8b13239067437c6546622ebe701d55aee1","parent":"x9ryw92","prov":{"backend":"typst reader (illustrative)","witnesses":["tszzg52"]},"text_hash":"3873ff52fe20b52be605c10c11e78b24bcabb05c8f725aeb4820c23428631509"}
|
||||
{"align_key":"a7226a2c68503d064f16cae87f6e01d25e5c75664bc8dee2d68ee2dc8c9f0c65","id":"hbb210j","kind":"back","match_hash":"5333f67a9eca4bf08b7c5bd643168084dddf40c175d8620dad293ff976a0ca31","node_hash":"a42481d70d840a9e15c3a5c31b9bfe503a78633c6b6431d3dc84dcd21b2f3019","ord":2,"own_hash":"bbb972bdc024231b505f4d8ce5e711fbb75c8b5ffd1b5d42ee3fb8586b85f867","parent":"eaaw8zs","text_hash":"b652c2e642345a7363119a8e2b95154e29eee21a3dacefc147a9cc6cd1731316"}
|
||||
{"align_key":"a70d3e5d1405673a9dd12a4e4fcaf31ca716be14d97ba7e9c8dc31007f05f672","id":"y4z5j53","kind":"paragraph","match_hash":"3bf084f108d315e4e1295d55e4fc139499da566a6d8090722668f587742f7bfc","node_hash":"86cd27353ae55ba760c0f033028c42ebf9f2d31b25598f70b94dd6ff79abfbec","ord":1,"own_hash":"494e069be36a18ecaabf5a63be7c31617ade7a5460218ca83a2de3d8d8f964e0","parent":"gmzn0mf","text_hash":"57f258843880d625007bbce10ace271b01d3fef066818beb84487e1d16f815eb"}
|
||||
{"align_key":"7dc562c54f1b1cc46e472838c4b2d7c97b3e1b4d39172628d6607b0f2d313c3e","content":[{"kind":"text","text":"The bond term is harmonic in the bond length."}],"fidelity":"F2","id":"kda5wym","kind":"sentence","match_hash":"8f22f3f58beb618723a14dd8fee8caaeb5cef6b26f43d88a5ddb4ff42f86d63e","node_hash":"dd438a68616e63fd1cd5050d308779af58dfed2b4d43cc5a4bbab3fc8d4f2bcb","ord":0,"own_hash":"46dfbddc0e456a2b7f4105b8d3636220ff9145acccf3bdf81a206f0b84f95b63","parent":"y4z5j53","prov":{"backend":"typst reader (illustrative)","witnesses":["tszzg52"]},"text_hash":"8f22f3f58beb618723a14dd8fee8caaeb5cef6b26f43d88a5ddb4ff42f86d63e"}
|
||||
{"align_key":"81422dae1385acfea463f7b7c75962de0bf92671d970a6ae9643763a8f87cd7f","content":[{"kind":"text","text":"Its constants come from a two-step fit "},{"kind":"xref","target":"hale2026harmonic-damb#a4jrz2t","text":"(Hale and Osei, Table 1)"},{"kind":"text","text":"."},{"kind":"cite","refs":["ebcq5cy"],"text":"1"}],"fidelity":"F2","id":"qgh1k31","kind":"sentence","match_hash":"fe82fa8560942e052e31d9b18cc8d3a9ba54ce01d91b66538ded6ff682a4e885","node_hash":"93a39490870e694299e88e6f475d42c38078d1442959e555bdbdf58488dcf187","ord":1,"own_hash":"e004436e7b28ff3dc41e0056f231ba707d9be985694e68acb911345a547842ed","parent":"y4z5j53","prov":{"backend":"typst reader (illustrative)","witnesses":["tszzg52"]},"text_hash":"0d5b27a20da22922ba0c5b65e06581a09d60b899e6daddc63b0e9c1dd3819055"}
|
||||
{"align_key":"fae2fe63ef00f3826f525b2fd7f5c29824c06c1461b0a648927598f1efc84bc0","content":[{"kind":"text","text":"In that fit the energy is "},{"kind":"math","notation":"typst","source":"E = K_r (r - r_\"eq\")^2"},{"kind":"text","text":", up to a constant factor."}],"fidelity":"F2","id":"wbntyy4","kind":"sentence","match_hash":"9b297e00b7348c2df4c6b12f67b2f879217a0d71e1be382fc8a4f6bd7439ddd0","node_hash":"18b4b664473aeccb797c3c52b0d3fc3c37a33593d3aca32640acdb40161fa3e2","ord":2,"own_hash":"7ae59942b690f78ed24570ba25764a8b13239067437c6546622ebe701d55aee1","parent":"y4z5j53","prov":{"backend":"typst reader (illustrative)","witnesses":["tszzg52"]},"text_hash":"3873ff52fe20b52be605c10c11e78b24bcabb05c8f725aeb4820c23428631509"}
|
||||
{"align_key":"50034267db628bc04f130e0f1289f8db0e54500d9d8d98e9c6556d5fc5733ca9","content":[{"kind":"text","text":"We test the charges on the villin headpiece subdomain HP35, LSDEDFKAVFGMTRSAFANLPLWKQQNLKKEKGLF, and on its N68H variant."}],"fidelity":"F2","id":"rh0yjt9","kind":"sentence","match_hash":"0d2c4ad8fc643245b3c0d6680110754f04ebca185a6c5ad9d0c2ddc1c473ea6b","node_hash":"aae718e0ec1f295e43fe41852e01196f97a12da3b64b4999e99fdbbb15d7329c","ord":3,"own_hash":"ab86459ace3bcd986530476ff939befdc2fd0ffdca0d6979284b3d942169d8b2","parent":"y4z5j53","prov":{"backend":"typst reader (illustrative)","witnesses":["tszzg52"]},"text_hash":"0d2c4ad8fc643245b3c0d6680110754f04ebca185a6c5ad9d0c2ddc1c473ea6b"}
|
||||
{"align_key":"a7226a2c68503d064f16cae87f6e01d25e5c75664bc8dee2d68ee2dc8c9f0c65","id":"hbb210j","kind":"back","match_hash":"5333f67a9eca4bf08b7c5bd643168084dddf40c175d8620dad293ff976a0ca31","node_hash":"a42481d70d840a9e15c3a5c31b9bfe503a78633c6b6431d3dc84dcd21b2f3019","ord":2,"own_hash":"bbb972bdc024231b505f4d8ce5e711fbb75c8b5ffd1b5d42ee3fb8586b85f867","parent":"x632xpk","text_hash":"b652c2e642345a7363119a8e2b95154e29eee21a3dacefc147a9cc6cd1731316"}
|
||||
{"align_key":"a7226a2c68503d064f16cae87f6e01d25e5c75664bc8dee2d68ee2dc8c9f0c65","id":"t728ktw","kind":"references","match_hash":"5333f67a9eca4bf08b7c5bd643168084dddf40c175d8620dad293ff976a0ca31","node_hash":"f25fb824a77ea0b61566aa32083103f6045473eeea053361f16d15127143e7e4","ord":0,"own_hash":"2a5302e2041d0e59458fea212dd51b89299901318bfceeeff227c1a07d3f5d1a","parent":"hbb210j","text_hash":"b652c2e642345a7363119a8e2b95154e29eee21a3dacefc147a9cc6cd1731316"}
|
||||
{"align_key":"a7226a2c68503d064f16cae87f6e01d25e5c75664bc8dee2d68ee2dc8c9f0c65","content":[{"kind":"text","text":"1. R. Hale and M. Osei, J. Example Chem. 2026, 14, 101–109."}],"fidelity":"F2","id":"ebcq5cy","kind":"reference","label":"1","match_hash":"5333f67a9eca4bf08b7c5bd643168084dddf40c175d8620dad293ff976a0ca31","node_hash":"88c4043a1c30e4bec8f9fdbdd98922289d3f4224168da680d1582b96743ac053","ord":0,"own_hash":"6dc3f27fb4a4d7176f24c9de291095202c357030c173f1f9f2d9295929ae5f84","parent":"t728ktw","prov":{"backend":"typst reader (illustrative)","witnesses":["tszzg52"]},"text_hash":"b652c2e642345a7363119a8e2b95154e29eee21a3dacefc147a9cc6cd1731316"}
|
||||
@@ -0,0 +1,3 @@
|
||||
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"body":{"alphabet":"protein","identity":"protein:5807fcbf6d5567ca","kind":"sequence","label":"HP35","organism":"Gallus gallus","role":"names","start":42,"type":"TextualBody","value":"LSDEDFKAVFGMTRSAFANLPLWKQQNLKKEKGLF"},"created":"2026-10-14T09:00:00Z","creator":{"id":"tag:scient.ing,2026:key:ana","name":"Ana Example","type":"Person"},"id":"tag:scient.ing,2026:annotation:smithlab/s05a5q9qa4bhj","layer":"tag:scient.ing,2026:layer:smithlab/bq5k8r3w","motivation":"identifying","receipt":"b09z8grf3mrs4","status":"confirmed","target":{"selector":[{"anchor":{"doc":"writer2027fixed-ynr7.v3","format":"scienting-anchor/1","kind":"sentence","node":"rh0yjt9","node_hash":"aae718e0ec1f295e43fe41852e01196f97a12da3b64b4999e99fdbbb15d7329c","own_hash":"ab86459ace3bcd986530476ff939befdc2fd0ffdca0d6979284b3d942169d8b2","quote":{"exact":"villin headpiece subdomain HP35","prefix":"We test the charges on the ","suffix":", LSDEDFKAVFGMTRSAFANLPLWKQQNLKK"},"rev":0,"span":[27,58],"store":"smithlab"},"type":"AnchorSelector"},{"exact":"villin headpiece subdomain HP35","prefix":"We test the charges on the ","suffix":", LSDEDFKAVFGMTRSAFANLPLWKQQNLKK","type":"TextQuoteSelector"}],"source":"tag:scient.ing,2026:doc:smithlab/writer2027fixed-ynr7.v3","type":"SpecificResource"},"type":"Annotation"}
|
||||
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"body":{"alphabet":"protein","identity":"protein:5807fcbf6d5567ca","kind":"sequence","label":"HP35","regions":[{"end":51,"label":"helix 1","start":44},{"end":59,"label":"helix 2","start":55},{"end":74,"label":"helix 3","start":63}],"role":"depicts","start":42,"type":"TextualBody","value":"LSDEDFKAVFGMTRSAFANLPLWKQQNLKKEKGLF"},"created":"2026-10-14T09:05:00Z","creator":{"id":"tag:scient.ing,2026:key:ana","name":"Ana Example","type":"Person"},"id":"tag:scient.ing,2026:annotation:smithlab/s04e0n9y6wger","layer":"tag:scient.ing,2026:layer:smithlab/bq5k8r3w","motivation":"identifying","receipt":"b09z8grf3mrs4","status":"confirmed","target":{"selector":[{"anchor":{"doc":"writer2027fixed-ynr7.v3","format":"scienting-anchor/1","kind":"sentence","node":"rh0yjt9","node_hash":"aae718e0ec1f295e43fe41852e01196f97a12da3b64b4999e99fdbbb15d7329c","own_hash":"ab86459ace3bcd986530476ff939befdc2fd0ffdca0d6979284b3d942169d8b2","quote":{"exact":"LSDEDFKAVFGMTRSAFANLPLWKQQNLKKEKGLF","prefix":"illin headpiece subdomain HP35, ","suffix":", and on its N68H variant."},"rev":0,"span":[60,95],"store":"smithlab"},"type":"AnchorSelector"},{"exact":"LSDEDFKAVFGMTRSAFANLPLWKQQNLKKEKGLF","prefix":"illin headpiece subdomain HP35, ","suffix":", and on its N68H variant.","type":"TextQuoteSelector"}],"source":"tag:scient.ing,2026:doc:smithlab/writer2027fixed-ynr7.v3","type":"SpecificResource"},"type":"Annotation"}
|
||||
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"body":{"alphabet":"protein","identity":"protein:5807fcbf6d5567ca","kind":"sequence","label":"HP35 N68H","role":"reports","start":42,"type":"TextualBody","value":"LSDEDFKAVFGMTRSAFANLPLWKQQNLKKEKGLF","variants":[{"alt":"H","position":68,"ref":"N"}]},"created":"2026-10-14T09:10:00Z","creator":{"id":"tag:scient.ing,2026:software:example-model","name":"A model (illustrative)","type":"Software"},"id":"tag:scient.ing,2026:annotation:smithlab/n8pvfne6pkb9z","layer":"tag:scient.ing,2026:layer:smithlab/bq5k8r3w","motivation":"identifying","status":"proposed","target":{"selector":[{"anchor":{"doc":"writer2027fixed-ynr7.v3","format":"scienting-anchor/1","kind":"sentence","node":"rh0yjt9","node_hash":"aae718e0ec1f295e43fe41852e01196f97a12da3b64b4999e99fdbbb15d7329c","own_hash":"ab86459ace3bcd986530476ff939befdc2fd0ffdca0d6979284b3d942169d8b2","quote":{"exact":"N68H","prefix":"FANLPLWKQQNLKKEKGLF, and on its ","suffix":" variant."},"rev":0,"span":[108,112],"store":"smithlab"},"type":"AnchorSelector"},{"exact":"N68H","prefix":"FANLPLWKQQNLKKEKGLF, and on its ","suffix":" variant.","type":"TextQuoteSelector"}],"source":"tag:scient.ing,2026:doc:smithlab/writer2027fixed-ynr7.v3","type":"SpecificResource"},"type":"Annotation"}
|
||||
@@ -0,0 +1 @@
|
||||
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"audience":"expert","created":"2026-10-14T09:00:00Z","creator":{"id":"tag:scient.ing,2026:key:ana","name":"Ana Example","type":"Person"},"docs":["smithlab/writer2027fixed-ynr7.v3"],"format":"scienting-layer/1","id":"tag:scient.ing,2026:layer:smithlab/bq5k8r3w","label":"Sequences in the draft","license":{"spdx":"CC-BY-4.0"},"project":"smithlab-charges","purpose":"The peptide the draft tests its charges on, its helices and its variant.","total":3,"type":"AnnotationCollection","visibility":"team"}
|
||||
@@ -0,0 +1 @@
|
||||
{"at":"2026-10-14T09:30:00Z","by":"ana","doc":"writer2027fixed-ynr7.v3","evidence":[],"format":"scienting-receipt/1","id":"b09z8grf3mrs4","level":"F3","nodes":[],"records":[["annotation","s04e0n9y6wger","bff8ef0d11e39c9aaffd0434a5f648d60ab05e876f5ff4c5ad31dff861196e8f"],["annotation","s05a5q9qa4bhj","81373fb287b77a6f523085bdc9647cc2d3c72f0d1fcbfa541ed074019f821db5"]],"rev":0,"root":"df2012c1d4da1f09d001e7595e7ff466aba7c915fc5e203624d274bafb83183e","scope":"targeted:sequences","signature":{"key":"ana","scheme":"ed25519","value":"TA4GpuntRYraJ/q3WdfPNWQfy5SlAxSrsTv+Wb1lH0TeH/QNSFWLU3FatOhhSYpgkbgkYTHBuCduODIr3dGPCQ=="}}
|
||||
@@ -0,0 +1,4 @@
|
||||
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"body":{"accessions":[{"db":"pubchem","id":"6324"}],"format":"chemical/x-daylight-smiles","identity":"OTMSDBZUPAUEDD-UHFFFAOYSA-N","kind":"structure","label":"ethane","role":"names","type":"TextualBody","value":"CC"},"created":"2026-10-14T09:00:00Z","creator":{"id":"tag:scient.ing,2026:key:ana","name":"Ana Example","type":"Person"},"id":"tag:scient.ing,2026:annotation:smithlab/n0539sf2trjdn","layer":"tag:scient.ing,2026:layer:smithlab/cm7h4p2x","motivation":"identifying","receipt":"q9z9fee99g3cg","status":"confirmed","target":{"selector":[{"anchor":{"doc":"hale2026harmonic-damb","format":"scienting-anchor/1","kind":"sentence","node":"qwgfg51","node_hash":"4a3be03766323b3c88d5b43591b0f573823b89fe582f2c3a6f0b43474685a30d","own_hash":"04bd6d16a9310fa00dbf5d0930f4dbaca52b6bb58e76bb3cdd348bec73a27737","quote":{"exact":"ethane","prefix":"ws the scan for the C–C bond of ","suffix":".a"},"rev":12,"span":[44,50],"store":"smithlab"},"type":"AnchorSelector"},{"exact":"ethane","prefix":"ws the scan for the C–C bond of ","suffix":".a","type":"TextQuoteSelector"}],"source":"tag:scient.ing,2026:doc:smithlab/hale2026harmonic-damb","type":"SpecificResource"},"type":"Annotation"}
|
||||
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"body":{"format":"chemical/x-daylight-smiles","identity":"XLYOFNOQVPJJNP-UHFFFAOYSA-N","kind":"structure","label":"water","role":"names","type":"TextualBody","value":"O"},"created":"2026-10-14T09:05:00Z","creator":{"id":"tag:scient.ing,2026:software:example-model","name":"A model (illustrative)","type":"Software"},"id":"tag:scient.ing,2026:annotation:smithlab/fdkfpz98yw4ae","layer":"tag:scient.ing,2026:layer:smithlab/cm7h4p2x","motivation":"identifying","status":"proposed","target":{"selector":[{"anchor":{"doc":"hale2026harmonic-damb","format":"scienting-anchor/1","kind":"sentence","node":"hca6dc5","node_hash":"8cfed5a34aab28517e89e8a164f0f96c14361de83ebc800439116e83ef479f34","own_hash":"c270571517825ceed31ca912b80ac76203effe47f1c84f8ee8962800d0afc92f","quote":{"exact":"Water","suffix":", H$_2$O, served as the first te"},"rev":12,"span":[0,5],"store":"smithlab"},"type":"AnchorSelector"},{"exact":"Water","prefix":"","suffix":", H$_2$O, served as the first te","type":"TextQuoteSelector"}],"source":"tag:scient.ing,2026:doc:smithlab/hale2026harmonic-damb","type":"SpecificResource"},"type":"Annotation"}
|
||||
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"body":{"format":"chemical/x-daylight-smarts","identity":"smarts:2e2a923f840c","kind":"structure","label":"CT–CT","role":"parametrizes","terms":[{"atoms":[0,1],"kind":"bond","source":"Table 1, Set A","types":["CT","CT"],"units":{"k_r":"kcal mol-1 A-2","r_eq":"A"},"values":{"k_r":"310.0","r_eq":"1.526"}},{"atoms":[0,1],"kind":"bond","source":"Table 1, Set B","types":["CT","CT"],"units":{"k_r":"kcal mol-1 A-2","r_eq":"A"},"values":{"k_r":"305.2","r_eq":"1.5260"}}],"type":"TextualBody","value":"[CX4][CX4]","written":"CT–CT"},"created":"2026-10-14T09:10:00Z","creator":{"id":"tag:scient.ing,2026:key:ana","name":"Ana Example","type":"Person"},"id":"tag:scient.ing,2026:annotation:smithlab/p9kaa8djhezd2","layer":"tag:scient.ing,2026:layer:smithlab/cm7h4p2x","motivation":"identifying","receipt":"q9z9fee99g3cg","status":"confirmed","target":{"selector":[{"anchor":{"context":{"column_path":["Bond"],"row_path":["Bond parameters","CT–CT"],"table_label":"Table 1"},"doc":"hale2026harmonic-damb","format":"scienting-anchor/1","kind":"cell","node":"vd76637","node_hash":"33810e4da42f8e65a224b5369c06fe8db254890294b7b6760808fe6e039da21a","own_hash":"2ef085ec0ae741d540d9ace389393d02c30523a66f55648470404733c73ecde3","quote":{"exact":"CT–CT"},"rev":12,"store":"smithlab"},"type":"AnchorSelector"},{"exact":"CT–CT","prefix":"","suffix":"","type":"TextQuoteSelector"}],"source":"tag:scient.ing,2026:doc:smithlab/hale2026harmonic-damb","type":"SpecificResource"},"type":"Annotation"}
|
||||
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"body":{"accessions":[{"db":"pubchem","id":"962"}],"format":"chemical/x-daylight-smiles","identity":"XLYOFNOQVPJJNP-UHFFFAOYSA-N","kind":"structure","label":"water","role":"parametrizes","terms":[{"atoms":[0,1],"kind":"bond","source":"Table 1, Set A","types":["OW","HW"],"units":{"k_r":"kcal mol-1 A-2","r_eq":"A"},"values":{"k_r":"553.0","r_eq":"0.9572"}},{"atoms":[0,1],"kind":"bond","source":"Table 1, Set B","types":["OW","HW"],"units":{"k_r":"kcal mol-1 A-2","r_eq":"A"},"values":{"k_r":"548.1","r_eq":"0.9570"}}],"type":"TextualBody","value":"O([H])[H]","written":"OW–HW"},"created":"2026-10-14T09:15:00Z","creator":{"id":"tag:scient.ing,2026:key:ana","name":"Ana Example","type":"Person"},"id":"tag:scient.ing,2026:annotation:smithlab/n0xj47295v5p3","layer":"tag:scient.ing,2026:layer:smithlab/cm7h4p2x","motivation":"identifying","receipt":"q9z9fee99g3cg","status":"confirmed","target":{"selector":[{"anchor":{"context":{"column_path":["Bond"],"row_path":["Bond parameters","OW–HW"],"table_label":"Table 1"},"doc":"hale2026harmonic-damb","format":"scienting-anchor/1","kind":"cell","node":"yvkd7xr","node_hash":"aab8791a24bc4067c7e37fc5f0244d2128205e0a169e65c2c0fad977aabce313","own_hash":"943ff2019857c2f6dc6d5c08bb0f4423bb31a8d2fac8951e3fa79c1e2ef9a736","quote":{"exact":"OW–HW"},"rev":12,"store":"smithlab"},"type":"AnchorSelector"},{"exact":"OW–HW","prefix":"","suffix":"","type":"TextQuoteSelector"}],"source":"tag:scient.ing,2026:doc:smithlab/hale2026harmonic-damb","type":"SpecificResource"},"type":"Annotation"}
|
||||
@@ -0,0 +1 @@
|
||||
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"audience":"expert","created":"2026-10-14T09:00:00Z","creator":{"id":"tag:scient.ing,2026:key:ana","name":"Ana Example","type":"Person"},"docs":["smithlab/hale2026harmonic-damb"],"format":"scienting-layer/1","id":"tag:scient.ing,2026:layer:smithlab/cm7h4p2x","label":"Structures in Hale and Osei","license":{"spdx":"CC-BY-4.0"},"project":"smithlab-charges","purpose":"The molecules the paper names and the force-field constants it gives for them.","total":4,"type":"AnnotationCollection","visibility":"team"}
|
||||
@@ -0,0 +1 @@
|
||||
{"at":"2026-10-14T09:30:00Z","by":"ana","doc":"hale2026harmonic-damb","evidence":[],"format":"scienting-receipt/1","id":"q9z9fee99g3cg","level":"F3","nodes":[],"records":[["annotation","n0539sf2trjdn","9a7b0badfa3bd023d24b6de3509523cbc6566bc82e8a17953ea4297987e0c560"],["annotation","n0xj47295v5p3","17ce7549a4c24f8e20b3b539b942436ecbde0e09f40c336ff5830f692226cbfc"],["annotation","p9kaa8djhezd2","239247de4906cabbf0da105ce026567646d15e2ca5988ad05d829f9378934a95"]],"rev":12,"root":"cf1d025838f64c48e2ae4260753735b9cb2a6e276fc7139d2ba5780a3067fa03","scope":"targeted:structures","signature":{"key":"ana","scheme":"ed25519","value":"PajQPzelH/egWsv4O8yja4acSnrwmWAHCwRRGxOEKHSkYamxaqORnLiKqSb5RFZf1V+x7Jzrk3ZGzHqEK4euCg=="}}
|
||||
@@ -0,0 +1,3 @@
|
||||
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"body":{"data_type":"force-field-parameters","dataset":"ds-hale-bond-params","kind":"data","label":"bond parameters","method":"scanned in steps of 0.01 Å, energies fitted by least squares","quantities":[{"field":"k_r","name":"harmonic bond force constant","unit":"kcal / mol / angstrom ** 2"},{"field":"r_eq","name":"equilibrium bond length","unit":"angstrom"}],"role":"reports","subjects":[{"identity":"OTMSDBZUPAUEDD-UHFFFAOYSA-N","kind":"structure","label":"ethane"},{"identity":"XLYOFNOQVPJJNP-UHFFFAOYSA-N","kind":"structure","label":"water"},{"identity":"smarts:2e2a923f840c","kind":"structure","label":"CT–CT"}],"type":"TextualBody","value":"Harmonic bond constants for CT–CT, CT–HC and OW–HW, in two parameter sets"},"created":"2026-10-14T09:00:00Z","creator":{"id":"tag:scient.ing,2026:key:ana","name":"Ana Example","type":"Person"},"id":"tag:scient.ing,2026:annotation:smithlab/c4648hbwpavgp","layer":"tag:scient.ing,2026:layer:smithlab/dt9n2k5y","motivation":"classifying","receipt":"v84xfyx5n1wg4","status":"confirmed","target":{"selector":[{"anchor":{"doc":"hale2026harmonic-damb","format":"scienting-anchor/1","kind":"sentence","node":"wxxhb3s","node_hash":"52063ded5cf76abdd32ba5c1d0d5d7348843eb0516ad29f5b1f249964e015b50","own_hash":"506d3bd0afffb1dff34f1563338d538c85be50434905c86784a94b747f979bc3","quote":{"exact":"Fitted harmonic bond parameters."},"rev":12,"store":"smithlab"},"type":"AnchorSelector"},{"exact":"Fitted harmonic bond parameters.","prefix":"","suffix":"","type":"TextQuoteSelector"}],"source":"tag:scient.ing,2026:doc:smithlab/hale2026harmonic-damb","type":"SpecificResource"},"type":"Annotation"}
|
||||
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"body":{"data_type":"energy-profile","dataset":"ds-hale-ctct-scan","kind":"data","label":"CT–CT scan","method":"scanned in steps of 0.01 Å around the minimum","quantities":[{"field":"r","name":"C–C bond length","unit":"angstrom"},{"field":"e","name":"energy","unit":"kcal / mol"}],"role":"reports","subjects":[{"identity":"OTMSDBZUPAUEDD-UHFFFAOYSA-N","kind":"structure","label":"ethane"}],"type":"TextualBody","value":"Energy along the C–C stretch of ethane"},"created":"2026-10-14T09:05:00Z","creator":{"id":"tag:scient.ing,2026:key:ana","name":"Ana Example","type":"Person"},"id":"tag:scient.ing,2026:annotation:smithlab/d3b924s8ve538","layer":"tag:scient.ing,2026:layer:smithlab/dt9n2k5y","motivation":"classifying","receipt":"v84xfyx5n1wg4","status":"confirmed","target":{"selector":[{"anchor":{"doc":"hale2026harmonic-damb","format":"scienting-anchor/1","kind":"sentence","node":"caehhp6","node_hash":"9f9c9a412cd08d0634daa3f23c63f5125c1270c13834c45c045c1a9a7452af86","own_hash":"75a68ec1ba13ad2d3fb7ef61634103b8740eb98494ca8fb607a3429f464ed278","quote":{"exact":"(a) The scan."},"rev":12,"store":"smithlab"},"type":"AnchorSelector"},{"exact":"(a) The scan.","prefix":"","suffix":"","type":"TextQuoteSelector"}],"source":"tag:scient.ing,2026:doc:smithlab/hale2026harmonic-damb","type":"SpecificResource"},"type":"Annotation"}
|
||||
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"body":{"data_type":"force-field-parameters","dataset":"ds-hale-bond-params","kind":"data","role":"uses","type":"TextualBody","value":"The fitted bond constants of Table 1, which this sentence introduces"},"created":"2026-10-14T09:10:00Z","creator":{"id":"tag:scient.ing,2026:software:example-model","name":"A model (illustrative)","type":"Software"},"id":"tag:scient.ing,2026:annotation:smithlab/j4c41y21r5a8f","layer":"tag:scient.ing,2026:layer:smithlab/dt9n2k5y","motivation":"classifying","status":"proposed","target":{"selector":[{"anchor":{"doc":"hale2026harmonic-damb","format":"scienting-anchor/1","kind":"sentence","node":"a4jrz2t","node_hash":"f64c6a5040f9c773d5ac4e559b58465aeae30bba79a82fc38b14ac7b61826ba8","own_hash":"dde95db22e0600c8e6da72dd6701436315a786655cb74fc313a4bf574c9356ee","quote":{"exact":"Table 1 lists the fitted constants for both parameter sets."},"rev":12,"store":"smithlab"},"type":"AnchorSelector"},{"exact":"Table 1 lists the fitted constants for both parameter sets.","prefix":"","suffix":"","type":"TextQuoteSelector"}],"source":"tag:scient.ing,2026:doc:smithlab/hale2026harmonic-damb","type":"SpecificResource"},"type":"Annotation"}
|
||||
@@ -0,0 +1 @@
|
||||
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"audience":"expert","created":"2026-10-14T09:00:00Z","creator":{"id":"tag:scient.ing,2026:key:ana","name":"Ana Example","type":"Person"},"docs":["smithlab/hale2026harmonic-damb"],"format":"scienting-layer/1","id":"tag:scient.ing,2026:layer:smithlab/dt9n2k5y","label":"Data in Hale and Osei","license":{"spdx":"CC-BY-4.0"},"project":"smithlab-charges","purpose":"What kind of data the paper's table and figure present, and what they are about.","total":3,"type":"AnnotationCollection","visibility":"team"}
|
||||
@@ -0,0 +1 @@
|
||||
{"at":"2026-10-14T09:30:00Z","by":"ana","doc":"hale2026harmonic-damb","evidence":[],"format":"scienting-receipt/1","id":"v84xfyx5n1wg4","level":"F3","nodes":[],"records":[["annotation","c4648hbwpavgp","c455aa6956e11ec8fcad44e525ef1029f9c7670218a912fb634fe55aea5d0c74"],["annotation","d3b924s8ve538","81aae04ef8ad507462eca1626ae43c40670d074e053edf2759743b5583e642bf"]],"rev":12,"root":"159ca32cd0673a86388ceaa593216665e942a4aaf31094e9996d34efd9f60812","scope":"targeted:data","signature":{"key":"ana","scheme":"ed25519","value":"FQxsuXHOeBz/Dfjcf5YitIvnRKyrgI64eRgHtJYC2dxZC97wlp563dzbLu85l5vogwIkh4rJfFBaMu3RbsGCCA=="}}
|
||||
@@ -1,5 +1,6 @@
|
||||
{"id":"csgs20p","ord":0,"section":null,"text_hash":"d3c3de666d0290878de3949bc0e0ffcaef965c66d2b61e81a5e615e26a2997df"}
|
||||
{"id":"zvt571v","ord":0,"section":"tqcsy8w","text_hash":"b605350bc00209520b7cd8f546322663356ba630708f71bbf30aead6b3dd608e"}
|
||||
{"id":"kda5wym","ord":0,"section":"tqcsy8w","text_hash":"8f22f3f58beb618723a14dd8fee8caaeb5cef6b26f43d88a5ddb4ff42f86d63e"}
|
||||
{"id":"qgh1k31","ord":1,"section":"tqcsy8w","text_hash":"0d5b27a20da22922ba0c5b65e06581a09d60b899e6daddc63b0e9c1dd3819055"}
|
||||
{"id":"wbntyy4","ord":2,"pinned":"energy-sentence","section":"tqcsy8w","text_hash":"3873ff52fe20b52be605c10c11e78b24bcabb05c8f725aeb4820c23428631509"}
|
||||
{"id":"zvt571v","ord":0,"section":"gmzn0mf","text_hash":"b605350bc00209520b7cd8f546322663356ba630708f71bbf30aead6b3dd608e"}
|
||||
{"id":"kda5wym","ord":0,"section":"gmzn0mf","text_hash":"8f22f3f58beb618723a14dd8fee8caaeb5cef6b26f43d88a5ddb4ff42f86d63e"}
|
||||
{"id":"qgh1k31","ord":1,"section":"gmzn0mf","text_hash":"0d5b27a20da22922ba0c5b65e06581a09d60b899e6daddc63b0e9c1dd3819055"}
|
||||
{"id":"wbntyy4","ord":2,"section":"gmzn0mf","text_hash":"3873ff52fe20b52be605c10c11e78b24bcabb05c8f725aeb4820c23428631509"}
|
||||
{"id":"rh0yjt9","ord":3,"pinned":"energy-sentence","section":"gmzn0mf","text_hash":"0d2c4ad8fc643245b3c0d6680110754f04ebca185a6c5ad9d0c2ddc1c473ea6b"}
|
||||
@@ -1 +1 @@
|
||||
{"claims":{"paperclaim":"amber"},"datasets":["ds-hale-bond-params","ds-hale-ctct-scan"],"documents":[{"doc":"smithlab/hale2026harmonic-damb","reason":"The bond constants we start from.","status":{"Ben Example":"read","Cara Example":"reading"},"tags":["parameters"]},{"doc":"okafor2025solvent-acth","reason":"Solvent shifts for the validation set.","tags":["spectra"]}],"drafts":["smithlab/writer2027fixed-ynr7.v3"],"format":"scienting-project/1","key":"smithlab-charges","layers":["tag:scient.ing,2026:layer:smithlab/kp4m2x7q","tag:scient.ing,2026:layer:smithlab/tr6c3q8m"],"members":[{"keys":["ana"],"person":"Ana Example","role":"owner"},{"keys":["ben","ben-spot"],"person":"Ben Example","role":"editor"},{"keys":["cara"],"person":"Cara Example","role":"reader"}],"name":"Charges and bonds","paths":[{"id":"onboarding","steps":[{"note":"Read the introduction.","ref":"smithlab/hale2026harmonic-damb","type":"document"},{"note":"Then the table.","ref":"smithlab/hale2026harmonic-damb#hj4s7pb","type":"node"},{"note":"The bond force constant, amber/k-bond.","ref":"claim:272XTX7C","type":"claim"}],"title":"First week"}],"settings":{"digit_rule":"anchored-sections","drift_threshold":"0.25","log":{"origin":"scient.ing/log/smithlab","threshold":1,"witnesses":["wit"]},"rights_unknown":"refuse","spot_check":{"minimum":10,"rate":"0.05"},"stages":"scienting-stages-default"},"store":"smithlab","views":["ctct-scan"]}
|
||||
{"claims":{"paperclaim":"amber"},"datasets":["ds-hale-bond-params","ds-hale-ctct-scan"],"documents":[{"doc":"smithlab/hale2026harmonic-damb","reason":"The bond constants we start from.","status":{"Ben Example":"read","Cara Example":"reading"},"tags":["parameters"]},{"doc":"okafor2025solvent-acth","reason":"Solvent shifts for the validation set.","tags":["spectra"]}],"drafts":["smithlab/writer2027fixed-ynr7.v3"],"format":"scienting-project/1","key":"smithlab-charges","layers":["tag:scient.ing,2026:layer:smithlab/kp4m2x7q","tag:scient.ing,2026:layer:smithlab/tr6c3q8m","tag:scient.ing,2026:layer:smithlab/cm7h4p2x","tag:scient.ing,2026:layer:smithlab/bq5k8r3w","tag:scient.ing,2026:layer:smithlab/dt9n2k5y"],"members":[{"keys":["ana"],"person":"Ana Example","role":"owner"},{"keys":["ben","ben-spot"],"person":"Ben Example","role":"editor"},{"keys":["cara"],"person":"Cara Example","role":"reader"}],"name":"Charges and bonds","paths":[{"id":"onboarding","steps":[{"note":"Read the introduction.","ref":"smithlab/hale2026harmonic-damb","type":"document"},{"note":"Then the table.","ref":"smithlab/hale2026harmonic-damb#hj4s7pb","type":"node"},{"note":"The bond force constant, amber/k-bond.","ref":"claim:272XTX7C","type":"claim"}],"title":"First week"}],"settings":{"digit_rule":"anchored-sections","drift_threshold":"0.25","log":{"origin":"scient.ing/log/smithlab","threshold":1,"witnesses":["wit"]},"rights_unknown":"refuse","spot_check":{"minimum":10,"rate":"0.05"},"stages":"scienting-stages-default"},"store":"smithlab","views":["ctct-scan"]}
|
||||
@@ -20,7 +20,8 @@
|
||||
{"p": [
|
||||
{"name": "@d1", "s": ["The bond term is harmonic in the bond length."], "fidelity": "F2"},
|
||||
{"name": "@d2", "s": ["Its constants come from a two-step fit ", {"xref": "ext:hale2026harmonic:@s5", "text": "(Hale and Osei, Table 1)"}, ".", {"cite": ["@dr1"], "text": "1"}], "fidelity": "F2"},
|
||||
{"name": "@d3", "s": ["In that fit the energy is ", {"t": "E = K_r (r - r_\"eq\")^2"}, ", up to a constant factor."], "fidelity": "F2"}
|
||||
{"name": "@d3", "s": ["In that fit the energy is ", {"t": "E = K_r (r - r_\"eq\")^2"}, ", up to a constant factor."], "fidelity": "F2"},
|
||||
{"name": "@d4", "s": ["We test the charges on the villin headpiece subdomain HP35, LSDEDFKAVFGMTRSAFANLPLWKQQNLKKEKGLF, and on its N68H variant."], "fidelity": "F2"}
|
||||
]}
|
||||
]},
|
||||
{"kind": "back", "children": [
|
||||
|
||||
@@ -2,51 +2,90 @@
|
||||
name = "paperspec"
|
||||
version = "0.1.0"
|
||||
description = "The scienting data formats: specification, JSON Schemas, SQL, test vectors and fixtures"
|
||||
authors = ["Scientific Computing Studio <maintainer@scient.ing>"]
|
||||
authors = ["Scienting <maintainer@scient.ing>"]
|
||||
license = "CC-BY-4.0 AND CC0-1.0 AND Apache-2.0"
|
||||
license-file = "LICENSE.md"
|
||||
readme = "README.md"
|
||||
homepage = "https://paperspec.scient.ing"
|
||||
repository = "https://git.scient.ing/infra/paperspec"
|
||||
repository = "https://git.scient.ing/papers/paperspec"
|
||||
documentation = "https://paperspec.scient.ing/docs/"
|
||||
channels = ["conda-forge"]
|
||||
platforms = ["linux-64", "linux-aarch64", "osx-64", "osx-arm64"]
|
||||
requires-pixi = ">=0.40"
|
||||
requires-pixi = ">=0.50"
|
||||
|
||||
[dependencies]
|
||||
python = ">=3.14,<3.15"
|
||||
# the package's tools extra, as in pyproject.toml
|
||||
jsonschema = ">=4.26.0"
|
||||
cryptography = ">=46"
|
||||
# the Markdown lint (`pixi run lint-md`)
|
||||
markdownlint-cli2 = ">=0.23.3"
|
||||
nodejs = ">=22"
|
||||
cryptography = ">=46"
|
||||
|
||||
# The reference implementation in src/paperspec, installed editable so that `import paperspec` and the
|
||||
# `paperspec` command work in every pixi environment; without pixi, `pip install -e ".[tools]"` does the same.
|
||||
[pypi-dependencies]
|
||||
paperspec = { path = ".", editable = true }
|
||||
|
||||
# What building and publishing the package needs: pixi run -e dev dist; see deploy/README.md.
|
||||
[feature.test.dependencies]
|
||||
pytest = ">=8.4"
|
||||
pytest-cov = ">=6"
|
||||
hypothesis = ">=6.130"
|
||||
|
||||
[feature.lint.dependencies]
|
||||
ruff = ">=0.17.1,<0.18"
|
||||
pre-commit = ">=4"
|
||||
|
||||
[feature.lint.pypi-dependencies]
|
||||
ty = ">=0.0.89,<0.0.90"
|
||||
|
||||
# What building and publishing the package needs: pixi run -e release dist; see deploy/README.md.
|
||||
# setuptools and setuptools-scm replace the standard's hatchling (the package keeps setuptools-scm).
|
||||
# twine 6.1 is the first that reads the license metadata (Metadata-Version 2.4) setuptools writes.
|
||||
[feature.dev.dependencies]
|
||||
[feature.release.dependencies]
|
||||
setuptools = ">=80"
|
||||
setuptools-scm = ">=8"
|
||||
python-build = ">=1.2"
|
||||
twine = ">=6.1"
|
||||
|
||||
[feature.dev.tasks]
|
||||
dist = { cmd = "python -m build --sdist --wheel --no-isolation --outdir dist", description = "Build the paperspec sdist and wheel into dist/" }
|
||||
[feature.release.tasks]
|
||||
dist = { cmd = "python -m build --sdist --wheel --no-isolation --outdir dist", description = "Build the sdist and wheel into dist/" }
|
||||
|
||||
# The package documentation (docs/package/), built with Zensical as in paperclaim.
|
||||
[feature.docs.dependencies]
|
||||
zensical = ">=0.0.69,<0.0.70"
|
||||
|
||||
[feature.docs.tasks]
|
||||
docs-build = { cmd = "zensical build --strict", description = "Build the documentation strictly into build/docs" }
|
||||
docs-serve = { cmd = "zensical serve", description = "Preview the documentation locally" }
|
||||
|
||||
[environments]
|
||||
default = { solve-group = "default" }
|
||||
dev = { features = ["dev"], solve-group = "default" }
|
||||
# `default` has everything for development; `release` builds and publishes the package; `docs` builds the docs.
|
||||
default = { features = ["test", "lint"], solve-group = "default" }
|
||||
release = { features = ["release"], solve-group = "default" }
|
||||
docs = { features = ["docs"], solve-group = "default" }
|
||||
|
||||
[tasks]
|
||||
check = { cmd = "paperspec check", depends-on = [
|
||||
fmt = { cmd = "ruff format", description = "Format code" }
|
||||
fmt-check = { cmd = "ruff format --check", description = "Check formatting" }
|
||||
lint = { cmd = "ruff check", description = "Lint" }
|
||||
lint-fix = { cmd = "ruff check --fix", description = "Lint and apply fixes" }
|
||||
typecheck = { cmd = "ty check", description = "Type-check src with ty" }
|
||||
test = { cmd = "pytest", description = "Fast suite: unit, property, integration, doctests" }
|
||||
cov = { cmd = "pytest -m 'not live' --maxfail=0 --cov --cov-report=term-missing --cov-report=xml", description = "All offline tests with branch coverage (fails under 90%)" }
|
||||
lint-md = { cmd = "markdownlint-cli2", description = "Lint every Markdown file with markdownlint" }
|
||||
verify = { cmd = "paperspec check", description = "Check schemas, records, packages, vectors, a byte-for-byte rebuild, the SQL round trip, prose and links" }
|
||||
check = { depends-on = [
|
||||
"fmt-check",
|
||||
"lint",
|
||||
], description = "Check schemas, records, packages, vectors, a byte-for-byte rebuild, the SQL round trip, prose and links" }
|
||||
"typecheck",
|
||||
"lint-md",
|
||||
"test",
|
||||
"verify",
|
||||
], description = "Every code check CI runs, then the repository's own check" }
|
||||
hooks = { cmd = "pre-commit install", description = "Install git pre-commit hooks" }
|
||||
quick = { cmd = "paperspec check --quick", description = "Check everything except the byte-for-byte rebuild" }
|
||||
build = { cmd = "paperspec build", description = "Rebuild fixtures/ and vectors/ from fixtures/src/ and the oracle" }
|
||||
lint = { cmd = "markdownlint-cli2", description = "Lint every Markdown file with markdownlint" }
|
||||
load = { cmd = "paperspec load", description = "Load packages into SQLite: pixi run load --sqlite lab.db PACKAGE..." }
|
||||
validate = { cmd = "paperspec validate", description = "Validate packages, or run proposed corrections through the gate" }
|
||||
stress = { cmd = "paperspec stress", description = "Stress the oracle with random inputs: pixi run stress --seed N" }
|
||||
|
||||
+34
-19
@@ -7,12 +7,9 @@ name = "paperspec"
|
||||
dynamic = ["version"]
|
||||
description = "The scienting formats: the reference implementation of every rule, with the JSON Schemas, SQL and test vectors as package data"
|
||||
readme = "README.md"
|
||||
# The code (src/) is Apache-2.0 and the schemas, SQL and vectors it carries are CC0-1.0, as LICENSE.md says.
|
||||
license = "Apache-2.0 AND CC0-1.0"
|
||||
license-files = ["LICENSE.md"]
|
||||
authors = [{ name = "Scientific Computing Studio", email = "maintainer@scient.ing" }]
|
||||
# Python 3.14 is the only version with the Unicode 16.0 character data the specification pins (spec/01 §1.4);
|
||||
# 3.13 has 15.1 and 3.15 has 17.0, and the package refuses to import on either.
|
||||
authors = [{ name = "Scienting", email = "maintainer@scient.ing" }]
|
||||
requires-python = ">=3.14,<3.15"
|
||||
classifiers = [
|
||||
"Development Status :: 3 - Alpha",
|
||||
@@ -21,8 +18,6 @@ classifiers = [
|
||||
"Programming Language :: Python :: 3.14",
|
||||
"Topic :: Scientific/Engineering",
|
||||
]
|
||||
# The base package is standard library only. `schema.py` needs jsonschema and
|
||||
# `crypto.py` needs cryptography; the repository's own tools need both.
|
||||
dependencies = []
|
||||
|
||||
[project.optional-dependencies]
|
||||
@@ -30,37 +25,57 @@ schema = ["jsonschema>=4.26", "referencing>=0.35"]
|
||||
crypto = ["cryptography>=46"]
|
||||
tools = ["paperspec[crypto,schema]"]
|
||||
|
||||
# One command with subcommands: paperspec validate, load, check, build, stress and site; `paperspec --help`
|
||||
# says which work anywhere and which need a checkout.
|
||||
[project.scripts]
|
||||
paperspec = "paperspec.cli.main:main"
|
||||
|
||||
[project.urls]
|
||||
Homepage = "https://paperspec.scient.ing"
|
||||
Repository = "https://git.scient.ing/infra/paperspec"
|
||||
Documentation = "https://paperspec.scient.ing/docs/"
|
||||
Homepage = "https://docs.scient.ing/paperspec/"
|
||||
Documentation = "https://docs.scient.ing/paperspec/"
|
||||
Specification = "https://paperspec.scient.ing"
|
||||
Repository = "https://git.scient.ing/papers/paperspec"
|
||||
Changelog = "https://git.scient.ing/papers/paperspec/src/branch/main/CHANGELOG.md"
|
||||
|
||||
[dependency-groups]
|
||||
test = ["pytest>=8.4", "pytest-cov>=6", "hypothesis>=6.130"]
|
||||
lint = ["ruff>=0.17.1,<0.18", "ty>=0.0.89,<0.0.90"]
|
||||
dev = [
|
||||
{ include-group = "test" },
|
||||
{ include-group = "lint" },
|
||||
"pre-commit>=4",
|
||||
"build>=1.2",
|
||||
"twine>=6.1",
|
||||
]
|
||||
|
||||
# The code is `src/paperspec`. The schemas, SQL and vectors stay at the repository root, where the
|
||||
# specification links to them and the website serves the schemas at their `$id` URLs, and travel with the
|
||||
# package as data subpackages, so a consumer reads them with importlib.resources. That mapping is why the
|
||||
# packages are listed rather than found.
|
||||
[tool.setuptools]
|
||||
packages = ["paperspec", "paperspec.cli", "paperspec.schemas", "paperspec.sql", "paperspec.vectors"]
|
||||
packages = [
|
||||
"paperspec",
|
||||
"paperspec.cli",
|
||||
"paperspec.schemas",
|
||||
"paperspec.sql",
|
||||
"paperspec.vectors",
|
||||
"paperspec.registry",
|
||||
"paperspec.registry.stamps",
|
||||
"paperspec.registry.stages",
|
||||
"paperspec.context",
|
||||
]
|
||||
|
||||
[tool.setuptools.package-dir]
|
||||
"" = "src"
|
||||
"paperspec.schemas" = "schemas"
|
||||
"paperspec.sql" = "sql"
|
||||
"paperspec.vectors" = "vectors"
|
||||
"paperspec.registry" = "registry"
|
||||
"paperspec.context" = "context"
|
||||
|
||||
[tool.setuptools.package-data]
|
||||
"paperspec.schemas" = ["*.json"]
|
||||
"paperspec.sql" = ["*.sql"]
|
||||
"paperspec.vectors" = ["*.jsonl"]
|
||||
"paperspec.registry" = ["*.json"]
|
||||
"paperspec.registry.stamps" = ["*.json"]
|
||||
"paperspec.registry.stages" = ["*.json"]
|
||||
"paperspec.context" = ["*.jsonld"]
|
||||
|
||||
# The package version comes from git tags (v0.1.1 builds as 0.1.1, later commits as 0.1.2.devN); CONTRIBUTING.md
|
||||
# says how it relates to the format version that CHANGELOG.md and pixi.toml carry. A source tree without git
|
||||
# history, such as a downloaded archive, builds as 0+unknown instead of failing.
|
||||
[tool.setuptools_scm]
|
||||
fallback_version = "0+unknown"
|
||||
version_file = "src/paperspec/_version.py"
|
||||
|
||||
+91
-1
@@ -113,6 +113,41 @@
|
||||
"description": "document.json's rev is not the number of corrections.",
|
||||
"chapter": "spec/22-conformance.md"
|
||||
},
|
||||
{
|
||||
"id": "doc.dataset.anchor",
|
||||
"description": "A line of a dataset's anchors.jsonl does not match its schema, names no value of its resource's CSV, or has an anchor that does not resolve as current.",
|
||||
"chapter": "spec/15-datasets.md"
|
||||
},
|
||||
{
|
||||
"id": "doc.dataset.file",
|
||||
"description": "A dataset has no datapackage.json, or one of its files cannot be read: JSON that does not parse, anchors.jsonl not in canonical form, a CSV that does not read, or a resource whose path names no file of the dataset.",
|
||||
"chapter": "spec/15-datasets.md"
|
||||
},
|
||||
{
|
||||
"id": "doc.dataset.id",
|
||||
"description": "A dataset's folder is not named by its ID.",
|
||||
"chapter": "spec/15-datasets.md"
|
||||
},
|
||||
{
|
||||
"id": "doc.dataset.key",
|
||||
"description": "The primary key of a dataset's CSV resource is not unique.",
|
||||
"chapter": "spec/15-datasets.md"
|
||||
},
|
||||
{
|
||||
"id": "doc.dataset.schema",
|
||||
"description": "A dataset's datapackage.json does not match dataset.schema.json.",
|
||||
"chapter": "spec/15-datasets.md"
|
||||
},
|
||||
{
|
||||
"id": "doc.dataset.unanchored",
|
||||
"description": "A numeric value of a reported resource has no line in anchors.jsonl tying it to what prints it.",
|
||||
"chapter": "spec/15-datasets.md"
|
||||
},
|
||||
{
|
||||
"id": "doc.dataset.value",
|
||||
"description": "A value of a dataset's CSV is not, character for character after normalization, the text its anchor resolves to.",
|
||||
"chapter": "spec/15-datasets.md"
|
||||
},
|
||||
{
|
||||
"id": "doc.derived.math",
|
||||
"description": "A line of derived/math.jsonl names a formula that is not TeX, says it is complete when its tree has an opaque node or the reverse, or lists symbols that are not the sym keys of its tree.",
|
||||
@@ -220,7 +255,7 @@
|
||||
},
|
||||
{
|
||||
"id": "doc.math.form",
|
||||
"description": "A source with a form is not that form's canonical spelling. Only a validator that implements the form can check it; the reference validator does not.",
|
||||
"description": "A source with a form is not that form's canonical spelling. The reference validator reports a scienting-math/1 source that holds a label or style command, which the form never does, and checks every source with papermath when it is installed.",
|
||||
"chapter": "spec/03-nodes.md"
|
||||
},
|
||||
{
|
||||
@@ -448,6 +483,61 @@
|
||||
"description": "The exercise kind is unknown.",
|
||||
"chapter": "spec/22-conformance.md"
|
||||
},
|
||||
{
|
||||
"id": "layer.data.dataset",
|
||||
"description": "A data body's dataset is not a dataset ID, is not the dataset whose descriptor was given, or has a quantity whose field the dataset lacks or whose unit differs from the field's.",
|
||||
"chapter": "spec/18-layers.md"
|
||||
},
|
||||
{
|
||||
"id": "layer.data.quantity",
|
||||
"description": "A data body has two quantities for one field.",
|
||||
"chapter": "spec/18-layers.md"
|
||||
},
|
||||
{
|
||||
"id": "layer.data.subject",
|
||||
"description": "A data body's subject is not a structure or a sequence, has an identity not of the form its kind gives, or repeats another subject.",
|
||||
"chapter": "spec/18-layers.md"
|
||||
},
|
||||
{
|
||||
"id": "layer.data.type",
|
||||
"description": "A data body's kind of data or role is not one the body allows.",
|
||||
"chapter": "spec/18-layers.md"
|
||||
},
|
||||
{
|
||||
"id": "layer.sequence.identity",
|
||||
"description": "A sequence body's identity is not its alphabet, a colon and the first sixteen hex digits of the SHA-256 of its residues with the gaps taken out.",
|
||||
"chapter": "spec/18-layers.md"
|
||||
},
|
||||
{
|
||||
"id": "layer.sequence.region",
|
||||
"description": "A sequence body's region starts after it ends, or reaches outside the residues the value numbers from its start.",
|
||||
"chapter": "spec/18-layers.md"
|
||||
},
|
||||
{
|
||||
"id": "layer.sequence.value",
|
||||
"description": "A sequence body's alphabet is unknown, its value holds a letter its alphabet does not allow, or it holds only gaps.",
|
||||
"chapter": "spec/18-layers.md"
|
||||
},
|
||||
{
|
||||
"id": "layer.sequence.variant",
|
||||
"description": "A sequence body's variant is outside the residues, names a reference residue the value does not have there, changes a residue to itself, or has an alternative its alphabet does not allow.",
|
||||
"chapter": "spec/18-layers.md"
|
||||
},
|
||||
{
|
||||
"id": "layer.structure.identity",
|
||||
"description": "A structure body's identity is not the InChIKey of a SMILES or smiles: or smarts: and the first twelve hex digits of the SHA-256 of its value, or is of the other format than the value.",
|
||||
"chapter": "spec/18-layers.md"
|
||||
},
|
||||
{
|
||||
"id": "layer.structure.term",
|
||||
"description": "A structure body's term cites an atom its value does not write, an atom twice, atoms not joined as its kind needs, a number of atoms or types its kind does not take, or units for values it does not give.",
|
||||
"chapter": "spec/18-layers.md"
|
||||
},
|
||||
{
|
||||
"id": "layer.structure.value",
|
||||
"description": "A structure body's value is not a SMILES or SMARTS as its format says: an unclosed bracket, branch or ring, a stray character, a bond with no atom, or a query in a SMILES.",
|
||||
"chapter": "spec/18-layers.md"
|
||||
},
|
||||
{
|
||||
"id": "layer.trace.source",
|
||||
"description": "A trace's passage is not in the document its source names, its source is the citing document, its selector has no AnchorSelector, or its TextQuoteSelector does not repeat the anchor's plain quote.",
|
||||
|
||||
+8
-4
@@ -1,6 +1,6 @@
|
||||
# Schemas
|
||||
|
||||
This folder holds the JSON (JavaScript Object Notation) Schemas (draft 2020-12) for every file and record that the paperspec formats (paperspec is the specification this repository holds) define: 43 schema files.
|
||||
This folder holds the JSON (JavaScript Object Notation) Schemas (draft 2020-12) for every file and record that the PaperSpec formats (PaperSpec is the specification this repository holds) define: 43 schema files.
|
||||
A JSON Schema is a file, itself written in JSON, that states what a valid JSON file looks like.
|
||||
Newcomers can read it as a form: it lists the fields a record must have and what kind of value each field takes.
|
||||
Implementers will find the loading recipe and the traps under "Validating" and "Writing schemas".
|
||||
@@ -38,7 +38,7 @@ The rest belong to `candidate` formats or to no format of their own.
|
||||
|
||||
The bundle has no JSON Schema: its registry entry points to `sql/bundle-sqlite.sql`.
|
||||
Of the 43 schemas, 12 have no format of their own because each describes a line or part of a larger file: `common`, `node`, `runs`, `witnesses`, `provenance`, `location`, `reference`, `id-entry`, `mathml`, `math`, `annotation` and `value-anchor`.
|
||||
A line of `derived/math.jsonl` carries `form`, the math form `scienting-math/1` it reads the formula in; that names a spelling of TeX, which papermath implements ([spec/09 §9.4](../spec/09-figures-tables-equations.md#94-the-math-form)), not a file format, so the registry does not list it.
|
||||
A line of `derived/math.jsonl` carries `form`, the math form `scienting-math/1` it reads the formula in; that names a spelling of TeX, which PaperMath implements ([spec/09 §9.4](../spec/09-figures-tables-equations.md#94-the-math-form)), not a file format, so the registry does not list it.
|
||||
Of the schemas that do have one, 27 require a `format` property; `spot-check.schema.json` describes the input a VRF proof is made over rather than a file.
|
||||
The others (`page`, `draft-ids`, `view` and `log-entry`) describe a line of a file, a Vega-Lite specification (a JSON description of a chart) or an item of a tree, and the record itself does not need to carry the identifier.
|
||||
|
||||
@@ -51,8 +51,12 @@ import json, pathlib
|
||||
from jsonschema import Draft202012Validator
|
||||
from referencing import Registry, Resource
|
||||
|
||||
schemas = {p.name: json.loads(p.read_text()) for p in pathlib.Path("schemas").glob("*.json")}
|
||||
registry = Registry().with_resources((s["$id"], Resource.from_contents(s)) for s in schemas.values())
|
||||
schemas = {
|
||||
p.name: json.loads(p.read_text()) for p in pathlib.Path("schemas").glob("*.json")
|
||||
}
|
||||
registry = Registry().with_resources(
|
||||
(s["$id"], Resource.from_contents(s)) for s in schemas.values()
|
||||
)
|
||||
validator = Draft202012Validator(schemas["anchor.schema.json"], registry=registry)
|
||||
validator.validate(json.load(open("fixtures/records/anchor-span.json")))
|
||||
```
|
||||
|
||||
@@ -59,6 +59,266 @@
|
||||
"additionalProperties": false
|
||||
}
|
||||
]
|
||||
},
|
||||
"accession": {
|
||||
"description": "An entry of an outside database or vocabulary that a structure, a sequence or some data is, or is of: `db` names it in lower case (pubchem, chebi, cas, uniprot, genbank, refseq, ensembl, pdb, zenodo, geo, edam, chmo) and `id` is the entry's identifier there (spec/18 §18.6).",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"db": {
|
||||
"type": "string",
|
||||
"pattern": "^[a-z][a-z0-9-]*$",
|
||||
"maxLength": 32
|
||||
},
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
|
||||
"maxLength": 128
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"db",
|
||||
"id"
|
||||
],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"structureTerm": {
|
||||
"description": "A bond, angle, torsion or improper that a paper gives values for, citing the structure's atoms by number (spec/18 §18.6).",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"kind": {
|
||||
"enum": [
|
||||
"bond",
|
||||
"angle",
|
||||
"torsion",
|
||||
"improper"
|
||||
]
|
||||
},
|
||||
"atoms": {
|
||||
"description": "Atom numbers, from 0 in the order the value writes its atoms. An improper lists its central atom first.",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "integer",
|
||||
"minimum": 0
|
||||
},
|
||||
"minItems": 2,
|
||||
"maxItems": 4,
|
||||
"uniqueItems": true
|
||||
},
|
||||
"types": {
|
||||
"description": "The force field's atom types, one for each atom.",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"maxLength": 16
|
||||
},
|
||||
"minItems": 2,
|
||||
"maxItems": 4
|
||||
},
|
||||
"values": {
|
||||
"description": "The parameters the paper gives, by the name it uses (k_r, r_eq, theta_0).",
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"$ref": "common.schema.json#/$defs/decimal"
|
||||
},
|
||||
"minProperties": 1
|
||||
},
|
||||
"units": {
|
||||
"description": "The unit of each value, by the same names.",
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
}
|
||||
},
|
||||
"source": {
|
||||
"description": "Where in the paper the values are given.",
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"kind",
|
||||
"atoms"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"allOf": [
|
||||
{
|
||||
"if": {
|
||||
"properties": {
|
||||
"kind": {
|
||||
"const": "bond"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"kind"
|
||||
]
|
||||
},
|
||||
"then": {
|
||||
"properties": {
|
||||
"atoms": {
|
||||
"minItems": 2,
|
||||
"maxItems": 2
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"if": {
|
||||
"properties": {
|
||||
"kind": {
|
||||
"const": "angle"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"kind"
|
||||
]
|
||||
},
|
||||
"then": {
|
||||
"properties": {
|
||||
"atoms": {
|
||||
"minItems": 3,
|
||||
"maxItems": 3
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"if": {
|
||||
"properties": {
|
||||
"kind": {
|
||||
"const": "torsion"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"kind"
|
||||
]
|
||||
},
|
||||
"then": {
|
||||
"properties": {
|
||||
"atoms": {
|
||||
"minItems": 4,
|
||||
"maxItems": 4
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"if": {
|
||||
"properties": {
|
||||
"kind": {
|
||||
"const": "improper"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"kind"
|
||||
]
|
||||
},
|
||||
"then": {
|
||||
"properties": {
|
||||
"atoms": {
|
||||
"minItems": 4,
|
||||
"maxItems": 4
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"region": {
|
||||
"description": "A stretch of a sequence, by residue number, both ends included (spec/18 §18.7).",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"start": {
|
||||
"type": "integer",
|
||||
"minimum": 1
|
||||
},
|
||||
"end": {
|
||||
"type": "integer",
|
||||
"minimum": 1
|
||||
},
|
||||
"label": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"start",
|
||||
"end"
|
||||
],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"variant": {
|
||||
"description": "A substitution, stop or deletion at one residue: `ref` is the residue the value has there, `alt` what the variant has (`*` a stop, `-` a deletion) (spec/18 §18.7).",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"position": {
|
||||
"type": "integer",
|
||||
"minimum": 1
|
||||
},
|
||||
"ref": {
|
||||
"type": "string",
|
||||
"pattern": "^[A-Z*]$"
|
||||
},
|
||||
"alt": {
|
||||
"type": "string",
|
||||
"pattern": "^[A-Z*-]$"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"position",
|
||||
"ref",
|
||||
"alt"
|
||||
],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"quantity": {
|
||||
"description": "What a field of a dataset measures: `field` is the dataset's field, `name` says what it is in words, and `unit` is the field's unit as the dataset spells it (spec/18 §18.8).",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"field": {
|
||||
"type": "string",
|
||||
"pattern": "^[A-Za-z_][A-Za-z0-9_.-]*$"
|
||||
},
|
||||
"name": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
},
|
||||
"unit": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"field",
|
||||
"name"
|
||||
],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"subject": {
|
||||
"description": "A molecule or a sequence that data is about, found by the identity a `structure` or a `sequence` body carries (spec/18 §18.8).",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"kind": {
|
||||
"enum": [
|
||||
"structure",
|
||||
"sequence"
|
||||
]
|
||||
},
|
||||
"identity": {
|
||||
"type": "string",
|
||||
"pattern": "^([A-Z]{14}-[A-Z]{10}-[A-Z]|(smiles|smarts):[0-9a-f]{12}|(protein|dna|rna):[0-9a-f]{16})$"
|
||||
},
|
||||
"label": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"kind",
|
||||
"identity"
|
||||
],
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
@@ -540,6 +800,301 @@
|
||||
],
|
||||
"additionalProperties": false
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"type": {
|
||||
"const": "TextualBody"
|
||||
},
|
||||
"kind": {
|
||||
"const": "structure"
|
||||
},
|
||||
"value": {
|
||||
"description": "The structure as a SMILES or a SMARTS, whichever `format` says (spec/18 §18.6).",
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"maxLength": 20000
|
||||
},
|
||||
"format": {
|
||||
"enum": [
|
||||
"chemical/x-daylight-smiles",
|
||||
"chemical/x-daylight-smarts"
|
||||
]
|
||||
},
|
||||
"role": {
|
||||
"enum": [
|
||||
"names",
|
||||
"depicts",
|
||||
"parametrizes",
|
||||
"uses"
|
||||
]
|
||||
},
|
||||
"identity": {
|
||||
"description": "The InChIKey of a SMILES that has one; otherwise `smiles:` or `smarts:` and the first twelve hex digits of the SHA-256 of the value.",
|
||||
"type": "string",
|
||||
"pattern": "^([A-Z]{14}-[A-Z]{10}-[A-Z]|(smiles|smarts):[0-9a-f]{12})$"
|
||||
},
|
||||
"written": {
|
||||
"description": "The structure as the paper writes it, when that is not SMILES or SMARTS: R-OH, CT-CT.",
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
},
|
||||
"label": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
},
|
||||
"accessions": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/accession"
|
||||
},
|
||||
"minItems": 1,
|
||||
"uniqueItems": true
|
||||
},
|
||||
"terms": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/structureTerm"
|
||||
},
|
||||
"minItems": 1
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"type",
|
||||
"kind",
|
||||
"value",
|
||||
"format",
|
||||
"role",
|
||||
"identity"
|
||||
],
|
||||
"additionalProperties": false
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"type": {
|
||||
"const": "TextualBody"
|
||||
},
|
||||
"kind": {
|
||||
"const": "sequence"
|
||||
},
|
||||
"value": {
|
||||
"description": "The residues in capital letters, a gap as `-` (spec/18 §18.7).",
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"maxLength": 100000
|
||||
},
|
||||
"alphabet": {
|
||||
"enum": [
|
||||
"protein",
|
||||
"dna",
|
||||
"rna"
|
||||
]
|
||||
},
|
||||
"role": {
|
||||
"enum": [
|
||||
"names",
|
||||
"depicts",
|
||||
"uses",
|
||||
"reports"
|
||||
]
|
||||
},
|
||||
"identity": {
|
||||
"description": "The alphabet, a colon and the first sixteen hex digits of the SHA-256 of the residues with the gaps taken out.",
|
||||
"type": "string",
|
||||
"pattern": "^(protein|dna|rna):[0-9a-f]{16}$"
|
||||
},
|
||||
"start": {
|
||||
"description": "The number of the first residue of the value in the molecule's own numbering; 1 when omitted.",
|
||||
"type": "integer",
|
||||
"minimum": 1
|
||||
},
|
||||
"label": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
},
|
||||
"organism": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
},
|
||||
"accessions": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/accession"
|
||||
},
|
||||
"minItems": 1,
|
||||
"uniqueItems": true
|
||||
},
|
||||
"regions": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/region"
|
||||
},
|
||||
"minItems": 1
|
||||
},
|
||||
"variants": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/variant"
|
||||
},
|
||||
"minItems": 1
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"type",
|
||||
"kind",
|
||||
"value",
|
||||
"alphabet",
|
||||
"role",
|
||||
"identity"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"allOf": [
|
||||
{
|
||||
"if": {
|
||||
"properties": {
|
||||
"alphabet": {
|
||||
"const": "protein"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"alphabet"
|
||||
]
|
||||
},
|
||||
"then": {
|
||||
"properties": {
|
||||
"value": {
|
||||
"pattern": "^[ACDEFGHIKLMNPQRSTVWYBXZJUO*-]+$"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"if": {
|
||||
"properties": {
|
||||
"alphabet": {
|
||||
"const": "dna"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"alphabet"
|
||||
]
|
||||
},
|
||||
"then": {
|
||||
"properties": {
|
||||
"value": {
|
||||
"pattern": "^[ACGTRYKMSWBDHVN-]+$"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"if": {
|
||||
"properties": {
|
||||
"alphabet": {
|
||||
"const": "rna"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"alphabet"
|
||||
]
|
||||
},
|
||||
"then": {
|
||||
"properties": {
|
||||
"value": {
|
||||
"pattern": "^[ACGURYKMSWBDHVN-]+$"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"type": {
|
||||
"const": "TextualBody"
|
||||
},
|
||||
"kind": {
|
||||
"const": "data"
|
||||
},
|
||||
"value": {
|
||||
"description": "The data in a few words: what it is and what it is about (spec/18 §18.8).",
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"maxLength": 2000
|
||||
},
|
||||
"data_type": {
|
||||
"description": "What kind of data it is (spec/18 §18.8).",
|
||||
"enum": [
|
||||
"abundance",
|
||||
"benchmark",
|
||||
"binding-affinity",
|
||||
"dose-response",
|
||||
"energy-profile",
|
||||
"force-field-parameters",
|
||||
"geometry",
|
||||
"kinetics",
|
||||
"other",
|
||||
"physical-property",
|
||||
"sequence-property",
|
||||
"simulation-observable",
|
||||
"spectrum",
|
||||
"thermodynamics",
|
||||
"variant-effect"
|
||||
]
|
||||
},
|
||||
"role": {
|
||||
"enum": [
|
||||
"reports",
|
||||
"uses"
|
||||
]
|
||||
},
|
||||
"dataset": {
|
||||
"description": "The dataset (spec/15) that holds the values.",
|
||||
"$ref": "common.schema.json#/$defs/datasetId"
|
||||
},
|
||||
"label": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
},
|
||||
"method": {
|
||||
"description": "How the data was obtained, in the paper's words.",
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
},
|
||||
"quantities": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/quantity"
|
||||
},
|
||||
"minItems": 1
|
||||
},
|
||||
"subjects": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/subject"
|
||||
},
|
||||
"minItems": 1
|
||||
},
|
||||
"accessions": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/accession"
|
||||
},
|
||||
"minItems": 1,
|
||||
"uniqueItems": true
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"type",
|
||||
"kind",
|
||||
"value",
|
||||
"data_type",
|
||||
"role"
|
||||
],
|
||||
"additionalProperties": false
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
|
||||
@@ -41,7 +41,7 @@ An implementation states, for each format, which versions it reads and writes.
|
||||
Every format has an identifier of the form `scienting-<name>/<major>`, such as `scienting-doc/1`.
|
||||
The identifier tells a reader which rules apply to a file.
|
||||
The prefix `scienting-` is the namespace of the formats.
|
||||
The namespace is not the name of this repository, paperspec, and formats are named after what they hold.
|
||||
The namespace is not the name of this repository, PaperSpec, and formats are named after what they hold.
|
||||
|
||||
A file or record that can travel on its own carries its identifier in a `format` property.
|
||||
The anchor in `fixtures/records/anchor-leaf.json` begins `{"doc":"hale2026harmonic-damb","format":"scienting-anchor/1", ...`.
|
||||
|
||||
@@ -150,4 +150,5 @@ A consumer MAY rely on these properties of a source that carries `form`:
|
||||
A producer writes `form` only on a source it has spelled in that form.
|
||||
A correction that changes such a source writes the new source in the form too, since the gate does not implement the form and cannot check it.
|
||||
A validator that implements the form reports a source with `form` that is not its own canonical spelling as `doc.math.form`.
|
||||
One that does not can still report a `scienting-math/1` source that holds `\tag`, `\label`, `\nonumber`, `\notag`, a style command such as `\displaystyle`, `\dfrac` or `\tfrac`, which the form never holds ([9.4](09-figures-tables-equations.md#94-the-math-form)); the reference validator does that, and checks every source with PaperMath when it is installed.
|
||||
`form` enters no content value, so adding it to a source already in the form changes no hash, ID or anchor, while respelling a source in the form changes them as any edit of the source does ([5.2](05-hashes.md#52-own-content)).
|
||||
+2
-1
@@ -11,7 +11,8 @@
|
||||
|
||||
Levels apply to leaves.
|
||||
The pipeline records F0, F1 or F2 in a leaf's `fidelity`; F3 comes only from receipts.
|
||||
A correction that changes a leaf drops it back: the gate's crop evidence makes it F1 at most, until it is corroborated or proofread again.
|
||||
A correction that changes a leaf drops it back, until it is corroborated or proofread again: to F1 when the correction's evidence includes a crop of the page, which answers it against the page image, and to F0 otherwise.
|
||||
The leaves it changes are those its record lists in `touched` and `created` ([11.3](11-corrections.md#113-applied-fields)), and a dropped leaf no longer names a witness in `corroborated_by`.
|
||||
An `emend`, `relink` or `resolve` ([11.1](11-corrections.md#111-operations)) never does, because a level measures the reading against its witnesses and the page.
|
||||
An emend corrects the authors, not the reading, and leaves the leaf as printed ([3.6](03-nodes.md#36-the-plain-projection)) as it was; a relink or a resolve changes no text, and the references a citation names are not text a witness corroborates.
|
||||
|
||||
|
||||
@@ -41,7 +41,7 @@ MathML is derived by a pinned tool and recorded, with the tool's name and versio
|
||||
|
||||
`scienting-math/1` is the standard form of a formula in a paper: one canonical TeX spelling, a tree read from it, a key for each symbol, and the issues a reader should look at.
|
||||
A converter writes a package's equations and math runs in it, a reader renders and searches it, and a claim store reads a paper's equations and its own claims through it, so the two can be matched.
|
||||
papermath is its reference implementation, and what papermath computes is what the form says; this section states what the specification relies on.
|
||||
PaperMath is its reference implementation, and what PaperMath computes is what the form says; this section states what the specification relies on.
|
||||
The identifier names a spelling of formulas, not a file format, so [registry/formats.json](../registry/formats.json) does not list it; its readings travel in a package's `derived/math.jsonl`.
|
||||
The form reads TeX only.
|
||||
|
||||
@@ -94,7 +94,7 @@ A later minor version of the form may add a kind, and a consumer that meets a ki
|
||||
**A symbol** is a base, which is a letter, a Greek letter, or a font or accent command on a group (`\mathbf{F}`, `\hat{H}`), with any subscript, any superscript that names rather than raises (`R^{*}`, `A^{\dagger}`, `E^{\text{LJ}}`), and primes.
|
||||
A text group alone is a symbol too, unless it holds several words, is a condition in `cases`, or is the set under a big operator.
|
||||
A symbol's key is its canonical TeX with `\mathrm` spelled `\text`, `\ast` spelled `*`, `\prime` spelled `'`, and no space inside text: `K_r` and `K_{r}` have the key `K_{r}`, and `r_{\mathrm{eq}}` has the key `r_{\text{eq}}`.
|
||||
The key is the one a paperclaim claim store gives a symbol, so a symbol in a paper and the same symbol in a claim have one key, and a `symbol` annotation names its symbol by it ([18.4](18-layers.md#184-bodies)).
|
||||
The key is the one a PaperClaim claim store gives a symbol, so a symbol in a paper and the same symbol in a claim have one key, and a `symbol` annotation names its symbol by it ([18.4](18-layers.md#184-bodies)).
|
||||
|
||||
**Issues** never stop the reading; each is `{code, message, at}`, with `at` the canonical TeX it is about.
|
||||
|
||||
@@ -113,4 +113,4 @@ A later minor version may add a code.
|
||||
`run` is the index of the math run among the node's runs, or null for an equation or equation line, as in `derived/mathml.jsonl`; `symbols` lists the keys in the order the formula first writes them; `label` is the label the tool lifted from a `\tag`, omitted when the source has none, as a canonical source never does.
|
||||
The schema is `math.schema.json`.
|
||||
A validator checks what it can without implementing the form: that each line names a formula of the package (`doc.derived.node`), and that the formula is TeX, `complete` is true exactly when the tree has no `opaque` node, and `symbols` holds each `sym` key of the tree once (`doc.derived.math`).
|
||||
`fixtures/packages/hale2026harmonic-damb/derived/math.jsonl` holds papermath's reading of the example's equation, of a math run that is one symbol, and of the run `_2` of "H₂O", which the tree cannot read alone.
|
||||
`fixtures/packages/hale2026harmonic-damb/derived/math.jsonl` holds PaperMath's reading of the example's equation, of a math run that is one symbol, and of the run `_2` of "H₂O", which the tree cannot read alone.
|
||||
@@ -24,4 +24,10 @@ A digitized value never passes as reported, and its uncertainty is at least the
|
||||
|
||||
A dataset's content hash is SHA-256 of the canonical JSON of `{"format": "scienting-dataset/1", "files": [[path, sha256, size], …]}` over its files, sorted by path.
|
||||
A dataset can be a source of kind `dataset`, so a claim can rest on a value read from a figure, with that fact visible in its evidence.
|
||||
A validator checks each dataset of a package against the package.
|
||||
It reports a descriptor that does not match `dataset.schema.json` (`doc.dataset.schema`), a folder not named by the dataset's ID (`doc.dataset.id`), a file that cannot be read (`doc.dataset.file`), and a CSV resource whose primary key is not unique (`doc.dataset.key`).
|
||||
Each line of `anchors.jsonl` matches its schema and names a value of its resource, and its anchor resolves as current ([6.5](06-anchors.md#65-resolution)) (`doc.dataset.anchor`), to text that is the value as the CSV holds it once both are normalized ([1.4](01-conventions.md#14-text-normalization-for-hashing)) (`doc.dataset.value`).
|
||||
Every numeric value of a `reported` resource is anchored (`doc.dataset.unanchored`); a resource's other fields, such as the labels that name its rows, need not be.
|
||||
A correction that changes or removes an anchored cell makes these fail, so a producer that applies one rebuilds the dataset or leaves it out, as it does a derived file ([12.7](12-package.md#127-derived-files)).
|
||||
|
||||
`fixtures/packages/hale2026harmonic-damb/datasets/ds-hale-bond-params` reports Table 1, and the suite checks that every value resolves to the cell that prints it.
|
||||
+117
-2
@@ -53,13 +53,16 @@ Replies are annotations that target annotations, so discussions are threads anch
|
||||
| `prerequisite` | `SpecificResource` | `source` | What to read or know first. |
|
||||
| `crosslink` | `SpecificResource` | `source`, `selector` | That the span corresponds to a span in another document. |
|
||||
| `trace` | `SpecificResource` | `source`, `selector`, `reference`, `note`, `verdict`, `proposer` | That the target's sentence cites `reference` on the strength of a passage of the cited document ([18.5](#185-traced-citations)). |
|
||||
| `structure` | `TextualBody` | `format`, `role`, `identity`, `written`, `label`, `accessions`, `terms` | That the span names, draws, gives parameters for or uses a chemical structure ([18.6](#186-chemical-structures)). |
|
||||
| `sequence` | `TextualBody` | `alphabet`, `role`, `identity`, `start`, `label`, `organism`, `accessions`, `regions`, `variants` | That the span names, shows, uses or reports a variant of a protein, DNA or RNA sequence ([18.7](#187-sequences)). |
|
||||
| `data` | `TextualBody` | `data_type`, `role`, `dataset`, `quantities`, `subjects`, `method`, `label`, `accessions` | That the span presents data of a kind, what its fields measure and which molecules and sequences it is about ([18.8](#188-data)). |
|
||||
| `translation` | `TextualBody` | `language` | The span in another language. |
|
||||
| `description` | `TextualBody` | `role` | A description of a figure, panel or table for readers who cannot see it: `alt`, a short text equivalent, or `long`, a full description. |
|
||||
| `generated` | `TextualBody` | `generator` | Text a model wrote about the span; never mistaken for source. `generator` is `{model, run}` as a correction's model author is ([11.2](11-corrections.md#112-every-correction-records)). |
|
||||
|
||||
A textual body has a `value`, and optionally a `format` (`text/plain` or `text/markdown`) and a `language`.
|
||||
|
||||
The `source` of a `claim-link` or `symbol` body is a claim in a paperclaim claim store, written as paperclaim writes a reference: `claim:` and the claim's tag, eight Crockford base32 capitals (the digits and the letters without I, L, O and U), as in `claim:272XTX7C`, or `claim:<host>/<tag>` for a claim in another store, `<host>` being a domain name.
|
||||
The `source` of a `claim-link` or `symbol` body is a claim in a PaperClaim claim store, written as PaperClaim writes a reference: `claim:` and the claim's tag, eight Crockford base32 capitals (the digits and the letters without I, L, O and U), as in `claim:272XTX7C`, or `claim:<host>/<tag>` for a claim in another store, `<host>` being a domain name.
|
||||
A tag never changes, while a claim's slug, such as `amber/k-bond`, may be renamed, so a slug is never a reference.
|
||||
The optional `pin` fixes the claim as the annotator read it: the same reference, `@`, and the first six lowercase hex digits of the claim's statement hash, as in `claim:272XTX7C@02f47b`.
|
||||
`common.schema.json` defines both, as `claimRef` and `claimPin`.
|
||||
@@ -87,7 +90,7 @@ The store's `annotations` table keeps the category beside the body's kind ([13.4
|
||||
Nothing a model writes is ever stored as source text.
|
||||
A model may propose a `description`, and like any annotation it stays `proposed` until a person confirms it; an accessible export uses confirmed descriptions only, and a figure with none has no description.
|
||||
Other text a model writes about a span, such as a summary, is a `generated` annotation, which names its `generator`.
|
||||
`fixtures/records/layer/` holds a layer with one annotation of each common kind, each comment, caveat and question with its category, a claim link and a symbol that reference a paperclaim claim and pin it, and the receipt that confirms some of them.
|
||||
`fixtures/records/layer/` holds a layer with one annotation of each common kind, each comment, caveat and question with its category, a claim link and a symbol that reference a PaperClaim claim and pin it, and the receipt that confirms some of them.
|
||||
|
||||
## 18.5 Traced citations
|
||||
|
||||
@@ -132,3 +135,115 @@ A chain of "as previously reported" is then followed one trace at a time: the re
|
||||
A trace breaks `layer.trace.source` when its selector has no `AnchorSelector`, an anchor is in another document than `source` names, `source` is the citing document, or the `TextQuoteSelector` does not repeat the anchor's plain quote.
|
||||
It breaks `layer.trace.target` when the target is not a leaf with runs of the citing document selected by an `AnchorSelector`, or the sentence does not cite `reference` ([22.4](22-conformance.md#224-rules)).
|
||||
`vectors/traces.jsonl` resolves traces against the fixture packages after corrections, with every outcome and every refusal, and `fixtures/records/traces/` holds a layer of four annotations on `writer2027fixed-ynr7.v3` that cites `hale2026harmonic-damb`: a trace a model proposed to the paper's abstract and a person confirmed with a receipt, a candidate a person rejected, a person's trace to Table 1, and a reply that disputes the first.
|
||||
|
||||
## 18.6 Chemical structures
|
||||
|
||||
A paper writes about a molecule in words, and nothing in a converted document finds it there.
|
||||
A `structure` annotation ties one to the words: its target is the span, as for any annotation, and its body holds the structure.
|
||||
The words stay the paper's, the structure is one reader's reading of them, attributed and withdrawable, and a model's tie stays `proposed` until a person confirms it.
|
||||
What a paper reports about a structure, such as the force-field constants of a bond, is about reading this paper ([18.1](#181-one-rule-decides-what-is-a-claim-and-what-is-a-layer)), so it is an annotation here; a claim store holds a parameter once it is checked.
|
||||
|
||||
| Property | Required | Holds |
|
||||
| --- | --- | --- |
|
||||
| `value` | Yes | The structure as a SMILES or a SMARTS, whichever `format` says. |
|
||||
| `format` | Yes | `chemical/x-daylight-smiles` for a SMILES, `chemical/x-daylight-smarts` for a SMARTS. |
|
||||
| `role` | Yes | What the span does with the structure: `names` it, `depicts` it (a figure, scheme or table draws it), `parametrizes` it (the span gives parameters for it) or `uses` it (a reagent, solvent or probe). |
|
||||
| `identity` | Yes | What finds the same structure however it was written: the structure's InChIKey when it is a SMILES and the producer has one, else `smiles:` or `smarts:` and the first twelve hex digits of the SHA-256 of the value as written. |
|
||||
| `written` | No | The structure as the paper writes it when that is not SMILES or SMARTS: `R-OH`, `CT-CT`. |
|
||||
| `label` | No | A short name, such as `NMA`. |
|
||||
| `accessions` | No | Entries of outside databases that the structure is: a list of `{db, id}`, with `db` in lower case (`pubchem`, `chebi`, `cas`). |
|
||||
| `terms` | No | The bonds, angles, torsions and impropers the paper gives values for. |
|
||||
|
||||
A structure that is not one molecule, such as a group, a fragment with open positions or a pattern of atom types, is a SMARTS.
|
||||
An open position is an atom that matches any atom, `[*:1]`, with its label as the atom map number, so `R-C(=O)-R'` is `[*:1]-C(=O)-[*:2]` and `R-OH` is `[*:1]-[OX2H]`, and the paper's own notation goes in `written`.
|
||||
SMILES text that a toolkit would refuse, because a valence rule fails, is kept as a SMARTS rather than dropped, since a paper's drawing often is not a molecule a toolkit can sanitize.
|
||||
|
||||
**Atom numbers.**
|
||||
Atoms are numbered from 0 in the order the value writes them, a bracket atom as one, so `CC(=O)NC` has atoms 0 to 4.
|
||||
A hydrogen that is not written as an atom has no number: a term on a hydrogen needs `[H]` in the value.
|
||||
The rule is of the text and not of any toolkit, which is what lets the numbers be checked without one.
|
||||
|
||||
A term has a `kind` (`bond`, `angle`, `torsion` or `improper`), `atoms` (2, 3, 4 and 4 atom numbers; an improper lists its central atom first), and optionally `types` (the force field's atom types, one for each atom), `values` (the parameters by the name the paper uses, each a decimal string as [1.2](01-conventions.md#12-numbers) writes numbers that carry meaning), `units` (a unit for each value) and `source` (where in the paper).
|
||||
The atoms of a bond, angle or torsion are a chain, each bonded to the next, and the atoms of an improper are each bonded to the first.
|
||||
|
||||
A structure body breaks `layer.structure.value` when its value is not a SMILES or SMARTS as its format says: an unclosed bracket, branch or ring, a stray character, a bond with no atom, or a query (`,`, `;`, `&`, `!` or `$` inside a bracket, or `a` or `A`) in a SMILES.
|
||||
It breaks `layer.structure.identity` when its identity is not of the form its value gives, or, for a `smiles:` or `smarts:` identity, is not the hash of the value.
|
||||
It breaks `layer.structure.term` when a term cites an atom the value does not write or cites an atom twice, when its atoms are not joined as its kind needs, when `types` has another length than `atoms`, or when `units` names a value that is not given ([22.4](22-conformance.md#224-rules)).
|
||||
The reference implementation, `paperspec.structures.problems`, reads atoms and bonds from the text with the standard library alone.
|
||||
It does not check valence, aromaticity or the InChIKey, which need a chemistry toolkit; a producer with one SHOULD also check that the value sanitizes as a molecule when `format` says a SMILES, and that the InChIKey is the molecule's.
|
||||
`vectors/structures.jsonl` reads the atoms and bonds of SMILES and SMARTS texts, mints identities, and breaks every rule, and `fixtures/records/chemistry/` holds a layer of four structures on `hale2026harmonic-damb`: ethane, named and confirmed; water, named by a model and still `proposed`; the CT–CT pattern of Table 1, a SMARTS with the bond constants of both parameter sets as terms; and water again, as a SMILES that writes its hydrogens, with the OW–HW constants.
|
||||
The two writings of water share one InChIKey, which is what finds them as one.
|
||||
|
||||
## 18.7 Sequences
|
||||
|
||||
A `sequence` annotation ties a protein, DNA or RNA sequence to the words that name it, show it or report a variant of it, as [18.6](#186-chemical-structures) does for a structure.
|
||||
|
||||
| Property | Required | Holds |
|
||||
| --- | --- | --- |
|
||||
| `value` | Yes | The residues in capital letters, a gap as `-`. |
|
||||
| `alphabet` | Yes | `protein`, `dna` or `rna`, which says what the letters mean. |
|
||||
| `role` | Yes | `names` the sequence, `depicts` it (the span shows it, as text, a figure or an alignment), `uses` it (a construct, primer or probe) or `reports` something about it (a variant, a region). |
|
||||
| `identity` | Yes | The alphabet, a colon and the first sixteen hex digits of the SHA-256 of the residues with the gaps taken out, so a sequence is found whatever gaps it was shown with and whatever its numbering. |
|
||||
| `start` | No | The number of the first residue of the value in the molecule's own numbering; 1 when omitted. |
|
||||
| `label` | No | A short name, such as `HP35`. |
|
||||
| `organism` | No | The organism the sequence is from, as the paper names it. |
|
||||
| `accessions` | No | Entries of outside databases that the sequence is, as in [18.6](#186-chemical-structures) (`uniprot`, `genbank`, `refseq`, `ensembl`, `pdb`). |
|
||||
| `regions` | No | Stretches of the sequence the span is about: a list of `{start, end, label?}`, both ends included. |
|
||||
| `variants` | No | Changes the span reports: a list of `{position, ref, alt}`. |
|
||||
|
||||
The alphabets allow the twenty amino acids, selenocysteine (`U`), pyrrolysine (`O`), the ambiguity codes `B`, `Z`, `J` and `X` and a stop (`*`) for `protein`; `A`, `C`, `G`, `T` and the IUPAC ambiguity codes for `dna`; the same with `U` for `T` for `rna`; and `-` for a gap in all three.
|
||||
A residue's number is `start` plus the number of residues before it, gaps not counted, so a fragment of a protein is numbered as the whole protein is, and `regions` and `variants` use those numbers.
|
||||
A variant says that the residue at `position` is `ref` in the value and `alt` in the variant; `alt` is a residue, `*` for a stop or `-` for a deletion.
|
||||
|
||||
A sequence body breaks `layer.sequence.value` when its letters are not those of its alphabet or are all gaps, `layer.sequence.identity` when its identity is not the hash of its residues, `layer.sequence.region` when a region starts after it ends or reaches outside the residues, and `layer.sequence.variant` when a variant is outside the residues, names a `ref` the value does not have at that position, changes a residue to itself, or has an `alt` its alphabet does not allow ([22.4](22-conformance.md#224-rules)).
|
||||
The reference implementation is `paperspec.sequences.problems`.
|
||||
It needs no toolkit, since an alphabet is a set of letters; a producer that knows the molecule SHOULD also check the sequence against the `accessions` it names.
|
||||
`vectors/sequences.jsonl` mints identities and breaks every rule, and `fixtures/records/biology/` holds a layer of three annotations on the draft `writer2027fixed-ynr7.v3`, whose last sentence tests its charges on the villin headpiece subdomain HP35: the words that name it, the printed sequence with its three helices as regions, and a model's proposal of the N68H variant, in the numbering 42 to 76 that the headpiece uses.
|
||||
|
||||
## 18.8 Data
|
||||
|
||||
A paper reports data in a table, a figure or a passage, and a dataset ([15](15-datasets.md)) holds its values.
|
||||
A `data` annotation says what kind of data its span presents, what the dataset's fields measure and which molecules and sequences it is about, so that data can be found by kind and by subject.
|
||||
Its target is the span, as for any annotation.
|
||||
The words and the dataset stay as they are, the kind is one reader's reading, attributed and withdrawable, and a model's tie stays `proposed` until a person confirms it.
|
||||
Whether the values hold is a claim ([18.1](#181-one-rule-decides-what-is-a-claim-and-what-is-a-layer)); this body says only what they are.
|
||||
|
||||
| Property | Required | Holds |
|
||||
| --- | --- | --- |
|
||||
| `value` | Yes | The data in a few words: what it is and what it is about. |
|
||||
| `data_type` | Yes | What kind of data it is, one of the kinds below. |
|
||||
| `role` | Yes | What the span does with the data: `reports` it (the span is the table, figure panel or passage that gives it) or `uses` it (the span relies on data given elsewhere). |
|
||||
| `dataset` | No | The ID of the dataset that holds the values, `ds-` and a key ([15](15-datasets.md)). |
|
||||
| `quantities` | No | What the dataset's fields measure: a list of `{field, name, unit?}`, with the `field` of the dataset, a `name` in words (`harmonic bond force constant`) and the `unit` as the dataset spells it. |
|
||||
| `subjects` | No | The molecules and sequences the data is about: a list of `{kind, identity, label?}`, with `kind` `structure` or `sequence` and the `identity` of a `structure` ([18.6](#186-chemical-structures)) or `sequence` ([18.7](#187-sequences)) body. |
|
||||
| `method` | No | How the data was obtained, in the paper's words: `isothermal titration calorimetry`, `DFT, B3LYP/6-31G*`. |
|
||||
| `label` | No | A short name. |
|
||||
| `accessions` | No | Entries of outside databases or vocabularies that the data is, or is of: a list of `{db, id}`, with `db` in lower case (`zenodo`, `geo`, `edam`, `chmo`). |
|
||||
|
||||
| `data_type` | Covers |
|
||||
| --- | --- |
|
||||
| `abundance` | Counts, expression levels or concentrations measured in samples. |
|
||||
| `benchmark` | How well a method or model does against a reference or against other methods: errors, scores, run times. |
|
||||
| `binding-affinity` | How tightly molecules bind: dissociation constants, inhibition constants, IC50, binding free energies. |
|
||||
| `dose-response` | A response as a function of dose or concentration. |
|
||||
| `energy-profile` | Energy along a coordinate: scans, potentials of mean force, reaction paths. |
|
||||
| `force-field-parameters` | Constants a force field or model uses for bonded and non-bonded terms. |
|
||||
| `geometry` | Lengths, angles, torsions, distances or deviations of structures. |
|
||||
| `kinetics` | Rates, rate constants, half-lives and barriers. |
|
||||
| `physical-property` | A property of a substance: density, melting point, pKa, logP, solubility. |
|
||||
| `sequence-property` | Values for the positions of a sequence: conservation, disorder, fitness scores. |
|
||||
| `simulation-observable` | A quantity computed from a simulation: distributions, time series, order parameters. |
|
||||
| `spectrum` | A spectrum or its peaks: NMR, infrared, Raman, ultraviolet-visible, mass. |
|
||||
| `thermodynamics` | Enthalpy, entropy, free energy, heat capacity, or a melting temperature of a process. |
|
||||
| `variant-effect` | What a change to a sequence or a structure does to a property. |
|
||||
| `other` | Data none of these describes; the `value` says what it is. |
|
||||
|
||||
The list is fixed by this chapter, and a new kind is a minor change ([0.4](00-introduction.md#04-status)).
|
||||
Where a kind has an outside term, `accessions` carries it, so a producer is not limited to this list when it says what the data is.
|
||||
A dataset's `origin` ([15](15-datasets.md)) says where its values came from, so the body does not repeat whether they were reported, digitized, computed or measured.
|
||||
|
||||
A data body breaks `layer.data.type` when its `data_type` or its `role` is not one the body allows, `layer.data.quantity` when two quantities are for one field, `layer.data.subject` when a subject's identity is not of the form its kind gives or a subject repeats another, and `layer.data.dataset` when `dataset` is not a dataset ID or, for a checker given the dataset's descriptor, is not that dataset, or a quantity names a field the dataset lacks or gives it a unit other than the dataset's ([22.4](22-conformance.md#224-rules)).
|
||||
The reference implementation is `paperspec.data.problems`, which takes the descriptor as an optional second argument.
|
||||
It compares units as strings and needs no unit library; a producer SHOULD also check that each unit parses and that its dimension fits the quantity it is given for, and that each subject's identity belongs to a `structure` or `sequence` annotation of the same layer or another.
|
||||
`vectors/data.jsonl` breaks every rule, and `fixtures/records/data/` holds a layer of three annotations on `hale2026harmonic-damb`: the caption of Table 1, tied to its dataset as force-field parameters for ethane, water and the CT–CT pattern with its force constant and equilibrium length; the caption of Figure 1a, tied to the dataset read from the scan as an energy profile of ethane; and the sentence that introduces Table 1, tied by a model and still `proposed`.
|
||||
The subjects' identities are those of the annotations in `fixtures/records/chemistry/`.
|
||||
@@ -6,7 +6,7 @@
|
||||
| --- | --- | --- |
|
||||
| `vectors/*.jsonl` | Inputs and expected outputs, one case per line. | Computes every expected output from its input. |
|
||||
| `fixtures/packages/` | Valid packages: a converted chemistry paper with corrections, receipts, a multi-level-header table and a dataset; its checks-only export; an open-access paper with two witnesses; a Typst draft; a tiny document, as a folder and as the zip of [12.2](12-package.md#122-paths). | Accepts each, and recomputes every value it contains. |
|
||||
| `fixtures/records/` | A valid record of every other format that is a JSON file of its own, and a second layer, of traced citations ([18.5](18-layers.md#185-traced-citations)), whose traces resolve as `vectors/traces.jsonl` says; the stage requirements and stamp rules are in `registry/`, and a bundle is built by `paperspec load --bundle`. | Accepts each. |
|
||||
| `fixtures/records/` | A valid record of every other format that is a JSON file of its own, and four more layers: traced citations ([18.5](18-layers.md#185-traced-citations)), whose traces resolve as `vectors/traces.jsonl` says, chemical structures ([18.6](18-layers.md#186-chemical-structures)), sequences ([18.7](18-layers.md#187-sequences)) and data ([18.8](18-layers.md#188-data)), whose rules `vectors/structures.jsonl`, `vectors/sequences.jsonl` and `vectors/data.jsonl` pin; the stage requirements and stamp rules are in `registry/`, and a bundle is built by `paperspec load --bundle`. | Accepts each. |
|
||||
| `fixtures/invalid/` | Invalid packages, each with `expect.json` naming the rule it breaks. | Refuses each, and SHOULD name that rule. |
|
||||
| `fixtures/keys/` | The test keys that signed the fixtures and the team secret of the checks-only export. | Never uses them for anything else. |
|
||||
|
||||
@@ -41,6 +41,7 @@ Rule IDs are stable: a rule's meaning never changes, and a retired rule's ID is
|
||||
| `package.` | The manifest, paths, files and schemas. |
|
||||
| `doc.tree.`, `doc.node.`, `doc.run.`, `doc.table.`, `doc.math.` | The tree, node content and runs. |
|
||||
| `doc.derived.` | Derived files ([12.7](12-package.md#127-derived-files)). |
|
||||
| `doc.dataset.` | Datasets ([15](15-datasets.md)). |
|
||||
| `doc.hash.` | The five values, the root and the metadata hash. |
|
||||
| `doc.id.`, `doc.order.` | The ID table and file order. |
|
||||
| `doc.policy.` | Text policies and keyed hashing. |
|
||||
@@ -49,10 +50,10 @@ Rule IDs are stable: a rule's meaning never changes, and a retired rule's ID is
|
||||
| `doc.receipt.`, `doc.qa.`, `doc.fidelity.` | Receipts, spot-checks and levels. |
|
||||
| `doc.witness.`, `doc.page.`, `doc.location.`, `doc.reference.` | Witnesses and geometry. |
|
||||
| `grade.` | Grading. |
|
||||
| `layer.` | Annotations that refer to documents: `layer.trace.source` and `layer.trace.target` ([18.5](18-layers.md#185-traced-citations)). |
|
||||
| `layer.` | Annotations: `layer.trace.source` and `layer.trace.target`, which refer to documents ([18.5](18-layers.md#185-traced-citations)); `layer.structure.value`, `layer.structure.identity` and `layer.structure.term` ([18.6](18-layers.md#186-chemical-structures)); `layer.sequence.value`, `layer.sequence.identity`, `layer.sequence.region` and `layer.sequence.variant` ([18.7](18-layers.md#187-sequences)); and `layer.data.type`, `layer.data.quantity`, `layer.data.subject` and `layer.data.dataset` ([18.8](18-layers.md#188-data)). |
|
||||
|
||||
A package is validated by [22.2](#222-validating-a-package), but a layer is not part of one.
|
||||
The `layer.` rules are reported for an annotation, in the form `annotation: rule: message`, by a validator that has the annotation and the states of the documents it names; the reference implementation does so for traces in `paperspec.traces.problems`.
|
||||
The `layer.` rules are reported for an annotation, in the form `annotation: rule: message`, by a validator that has the annotation and, for a trace, the states of the documents it names; the reference implementation does so in `paperspec.traces.problems`, `paperspec.structures.problems`, `paperspec.sequences.problems` and `paperspec.data.problems`.
|
||||
|
||||
## 22.5 Stability
|
||||
|
||||
|
||||
+3
-3
@@ -1,8 +1,8 @@
|
||||
# The paperspec specification
|
||||
# The PaperSpec specification
|
||||
|
||||
This specification states exactly what each paperspec file holds and how every value in it is computed.
|
||||
This specification states exactly what each PaperSpec file holds and how every value in it is computed.
|
||||
The schemas, SQL, JSON-LD context, registries, vectors and fixtures are normative too, and each chapter says which of them it relies on.
|
||||
A chapter and a vector that disagree signal a bug, so please report it in the repository, <https://git.scient.ing/infra/paperspec>.
|
||||
A chapter and a vector that disagree signal a bug, so please report it in the repository, <https://git.scient.ing/papers/paperspec>.
|
||||
|
||||
Two readers will get the most from it: implementers who build a reader, writer, converter or checker, and experts who want the precise rules.
|
||||
Newcomers should start with the [guides](../docs/README.md), which explain what the formats are for.
|
||||
|
||||
+1
-1
@@ -68,7 +68,7 @@ CREATE TABLE layers (
|
||||
CREATE TABLE annotations (
|
||||
id VARCHAR(256) NOT NULL,
|
||||
layer VARCHAR(256) NOT NULL,
|
||||
body_kind VARCHAR(24) NOT NULL CHECK (body_kind IN ('gloss', 'claim-link', 'symbol', 'comment', 'caveat', 'question', 'exercise', 'citation-context', 'prerequisite', 'crosslink', 'trace', 'translation', 'description', 'generated')),
|
||||
body_kind VARCHAR(24) NOT NULL CHECK (body_kind IN ('gloss', 'claim-link', 'symbol', 'comment', 'caveat', 'question', 'exercise', 'citation-context', 'prerequisite', 'crosslink', 'trace', 'structure', 'sequence', 'data', 'translation', 'description', 'generated')),
|
||||
category VARCHAR(12) CHECK (category IN ('comment', 'context', 'critique', 'question', 'correction', 'feedback', 'resource')),
|
||||
status VARCHAR(10) NOT NULL CHECK (status IN ('proposed', 'confirmed', 'rejected', 'withdrawn')),
|
||||
receipt VARCHAR(32),
|
||||
|
||||
+23
-12
@@ -1,16 +1,24 @@
|
||||
"""The reference implementation of the scienting formats: the computations behind every expected value
|
||||
in the paperspec repository; see https://paperspec.scient.ing/tools/.
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
# Copyright 2026 Scienting
|
||||
#
|
||||
# Source Code: https://git.scient.ing/papers/paperspec
|
||||
# See the LICENSE.md file for full license terms.
|
||||
|
||||
"""The reference implementation of the scienting formats.
|
||||
|
||||
It holds the computations behind every expected value in the paperspec repository; see
|
||||
https://paperspec.scient.ing/tools/.
|
||||
|
||||
Every module imports with the standard library alone. Schema validation (`schema`, and with it
|
||||
`package.validate` and `corrections.gate`) needs `paperspec[schema]`, and HKDF and Ed25519 in `crypto`, which
|
||||
the signature and receipt checks use, need `paperspec[crypto]`; both import their packages on first use, and
|
||||
`paperspec[tools]` installs both.
|
||||
`package.validate` and `corrections.gate`) needs `paperspec[schema]`, and HKDF and Ed25519 in
|
||||
`crypto`, which the signature and receipt checks use, need `paperspec[crypto]`; both import their
|
||||
packages on first use, and `paperspec[tools]` installs both.
|
||||
The schemas, SQL and vectors travel with the package: `paperspec.resources.path("sql")`.
|
||||
The commands are in `paperspec.cli`.
|
||||
|
||||
The specification pins the Unicode character data that normalization and the character classes come from
|
||||
(spec/01 §1.4), so the package refuses to import on a Python with any other version: a different version
|
||||
would compute different values for text with the characters it adds or changes.
|
||||
The specification pins the Unicode character data that normalization and the character classes
|
||||
come from (spec/01 §1.4), so the package refuses to import on a Python with any other version: a
|
||||
different version would compute different values for text with the characters it adds or changes.
|
||||
"""
|
||||
|
||||
import unicodedata
|
||||
@@ -18,10 +26,13 @@ import unicodedata
|
||||
UNICODE_VERSION = "16.0.0"
|
||||
|
||||
if unicodedata.unidata_version != UNICODE_VERSION:
|
||||
raise ImportError("paperspec needs the Unicode %s character data the specification pins, which Python 3.14 "
|
||||
"ships; this Python has Unicode %s." % (UNICODE_VERSION, unicodedata.unidata_version))
|
||||
raise ImportError(
|
||||
f"paperspec needs the Unicode {UNICODE_VERSION} character data the specification "
|
||||
f"pins, which Python 3.14 ships; this Python has Unicode {unicodedata.unidata_version}."
|
||||
)
|
||||
|
||||
try:
|
||||
from ._version import __version__
|
||||
except ImportError: # a checkout that was never built or installed, as `python -m` from src/ runs it
|
||||
from paperspec._version import __version__
|
||||
except ImportError:
|
||||
# A checkout that was never built or installed, as `python -m` from src/ runs it.
|
||||
__version__ = "0+unknown"
|
||||
@@ -1,3 +1,9 @@
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
# Copyright 2026 Scienting
|
||||
#
|
||||
# Source Code: https://git.scient.ing/papers/paperspec
|
||||
# See the LICENSE.md file for full license terms.
|
||||
|
||||
"""`python -m paperspec COMMAND`: the same as the `paperspec` command."""
|
||||
|
||||
import sys
|
||||
|
||||
+117
-51
@@ -1,24 +1,36 @@
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
# Copyright 2026 Scienting
|
||||
#
|
||||
# Source Code: https://git.scient.ing/papers/paperspec
|
||||
# See the LICENSE.md file for full license terms.
|
||||
|
||||
"""Whole-document sentence alignment, in the manner of a patience diff.
|
||||
|
||||
Non-normative; see spec/05-hashes.md, "Alignment".
|
||||
Each reading is a list of items: {"id", "strict", "lossy", "complex", "container", "context"}.
|
||||
Each reading is a list of items:
|
||||
{"id", "strict", "lossy", "complex", "container", "context"}.
|
||||
"""
|
||||
|
||||
import unicodedata
|
||||
from collections.abc import Sequence
|
||||
from itertools import pairwise
|
||||
|
||||
from .hashing import prose_length
|
||||
from paperspec.hashing import prose_length
|
||||
from paperspec.jsontypes import Record
|
||||
|
||||
MIN_PROSE = 20
|
||||
MIN_SIMILAR = 0.8
|
||||
|
||||
type Pair = tuple[int, int]
|
||||
|
||||
def _numeric_skeleton(strict):
|
||||
|
||||
def _numeric_skeleton(strict: str) -> str:
|
||||
keep = []
|
||||
i, n = 0, len(strict)
|
||||
while i < n:
|
||||
ch = strict[i]
|
||||
if ch in "_^" and i + 1 < n and strict[i + 1] == "{":
|
||||
keep.append(strict[i:i + 2])
|
||||
keep.append(strict[i : i + 2])
|
||||
i += 2
|
||||
continue
|
||||
if unicodedata.category(ch) == "Nd" or ch in "\u2212.,+}":
|
||||
@@ -27,8 +39,12 @@ def _numeric_skeleton(strict):
|
||||
return "".join(keep)
|
||||
|
||||
|
||||
def classify(a, b):
|
||||
"""`None` when two paired sentences agree; else the suspect kind."""
|
||||
def classify(a: Record, b: Record) -> str | None:
|
||||
"""The suspect kind of two paired sentences, or `None` when they agree.
|
||||
|
||||
The kind is `number` when the numeric skeletons of the strict projections differ,
|
||||
else `equation` when the complex math keys differ, else `word`.
|
||||
"""
|
||||
if a["strict"] == b["strict"] and a["complex"] == b["complex"]:
|
||||
return None
|
||||
if _numeric_skeleton(a["strict"]) != _numeric_skeleton(b["strict"]):
|
||||
@@ -38,8 +54,11 @@ def classify(a, b):
|
||||
return "word"
|
||||
|
||||
|
||||
def _lis(pairs):
|
||||
"""Longest subsequence increasing in B among pairs sorted by A; lexicographically smallest A on ties."""
|
||||
def _lis(pairs: Sequence[Pair]) -> list[Pair]:
|
||||
"""Longest subsequence increasing in b among pairs sorted by a.
|
||||
|
||||
Ties go to the lexicographically smallest a.
|
||||
"""
|
||||
n = len(pairs)
|
||||
if not n:
|
||||
return []
|
||||
@@ -59,32 +78,46 @@ def _lis(pairs):
|
||||
return out
|
||||
|
||||
|
||||
def _lcs(A, B, a0, a1, b0, b1):
|
||||
"""LCS over align keys of A[a0:a1] and B[b0:b1], as index pairs, with the spec's tie rule."""
|
||||
def _lcs(
|
||||
reading_a: Sequence[Record],
|
||||
reading_b: Sequence[Record],
|
||||
a0: int,
|
||||
a1: int,
|
||||
b0: int,
|
||||
b1: int,
|
||||
) -> list[Pair]:
|
||||
"""LCS over the align keys of two stretches, as index pairs, with the spec's tie rule.
|
||||
|
||||
The stretches are `reading_a[a0:a1]` and `reading_b[b0:b1]`; the pairs index the
|
||||
whole readings.
|
||||
"""
|
||||
n, m = a1 - a0, b1 - b0
|
||||
L = [[0] * (m + 1) for _ in range(n + 1)]
|
||||
lengths = [[0] * (m + 1) for _ in range(n + 1)]
|
||||
for i in range(n - 1, -1, -1):
|
||||
for j in range(m - 1, -1, -1):
|
||||
if A[a0 + i]["lossy"] == B[b0 + j]["lossy"]:
|
||||
L[i][j] = L[i + 1][j + 1] + 1
|
||||
if reading_a[a0 + i]["lossy"] == reading_b[b0 + j]["lossy"]:
|
||||
lengths[i][j] = lengths[i + 1][j + 1] + 1
|
||||
else:
|
||||
L[i][j] = max(L[i + 1][j], L[i][j + 1])
|
||||
lengths[i][j] = max(lengths[i + 1][j], lengths[i][j + 1])
|
||||
out = []
|
||||
i = j = 0
|
||||
while i < n and j < m:
|
||||
if A[a0 + i]["lossy"] == B[b0 + j]["lossy"]:
|
||||
if reading_a[a0 + i]["lossy"] == reading_b[b0 + j]["lossy"]:
|
||||
out.append((a0 + i, b0 + j))
|
||||
i += 1
|
||||
j += 1
|
||||
elif L[i + 1][j] >= L[i][j + 1]:
|
||||
elif lengths[i + 1][j] >= lengths[i][j + 1]:
|
||||
i += 1
|
||||
else:
|
||||
j += 1
|
||||
return out
|
||||
|
||||
|
||||
def lcs_length(a, b):
|
||||
"""Length of the longest common subsequence of two strings' code points (bit-parallel, Hyyrö 2004)."""
|
||||
def lcs_length(a: str, b: str) -> int:
|
||||
"""Length of the longest common subsequence of two strings' code points.
|
||||
|
||||
Bit-parallel (Hyyrö 2004).
|
||||
"""
|
||||
if len(a) < len(b):
|
||||
a, b = b, a
|
||||
masks = {}
|
||||
@@ -98,82 +131,115 @@ def lcs_length(a, b):
|
||||
return len(a) - v.bit_count()
|
||||
|
||||
|
||||
def similarity(a, b):
|
||||
"""2L / (|a| + |b|) over code points, L the longest common subsequence; 1 for two empty strings."""
|
||||
def similarity(a: str, b: str) -> float:
|
||||
"""2L / (|a| + |b|) over code points, L the longest common subsequence.
|
||||
|
||||
Two empty strings have similarity 1.
|
||||
"""
|
||||
if not a and not b:
|
||||
return 1.0
|
||||
return 2 * lcs_length(a, b) / (len(a) + len(b))
|
||||
|
||||
|
||||
def _similar(a, b):
|
||||
"""Whether two lossy projections are at least MIN_SIMILAR alike; exact, with two cheap upper bounds first."""
|
||||
def _similar(a: str, b: str) -> bool:
|
||||
"""Whether two lossy projections are at least MIN_SIMILAR alike.
|
||||
|
||||
Exact, with two cheap upper bounds first.
|
||||
"""
|
||||
total = len(a) + len(b)
|
||||
if 2 * min(len(a), len(b)) < MIN_SIMILAR * total:
|
||||
return False
|
||||
common = sum(min(n, b.count(ch)) for ch, n in {ch: a.count(ch) for ch in set(a)}.items())
|
||||
common = sum(
|
||||
min(n, b.count(ch)) for ch, n in {ch: a.count(ch) for ch in set(a)}.items()
|
||||
)
|
||||
if 2 * common < MIN_SIMILAR * total:
|
||||
return False
|
||||
return 2 * lcs_length(a, b) >= MIN_SIMILAR * total
|
||||
|
||||
|
||||
def _substitutions(A, B, pairs):
|
||||
"""Step 3: in each stretch between pairs, an unpaired sentence beside a nearly equal one is paired with it."""
|
||||
def _substitutions(
|
||||
reading_a: Sequence[Record], reading_b: Sequence[Record], pairs: Sequence[Pair]
|
||||
) -> list[Pair]:
|
||||
"""Step 3: in each stretch between pairs, pair an unpaired sentence with a similar one."""
|
||||
out = []
|
||||
bounds = [(-1, -1)] + pairs + [(len(A), len(B))]
|
||||
for (a0, b0), (a1, b1) in zip(bounds, bounds[1:]):
|
||||
bounds = [(-1, -1), *pairs, (len(reading_a), len(reading_b))]
|
||||
for (a0, b0), (a1, b1) in pairwise(bounds):
|
||||
nxt = b0 + 1
|
||||
for i in range(a0 + 1, a1):
|
||||
if prose_length(A[i]["lossy"]) < MIN_PROSE:
|
||||
if prose_length(reading_a[i]["lossy"]) < MIN_PROSE:
|
||||
continue
|
||||
for j in range(nxt, b1):
|
||||
if prose_length(B[j]["lossy"]) >= MIN_PROSE and _similar(A[i]["lossy"], B[j]["lossy"]):
|
||||
if prose_length(reading_b[j]["lossy"]) >= MIN_PROSE and _similar(
|
||||
reading_a[i]["lossy"], reading_b[j]["lossy"]
|
||||
):
|
||||
out.append((i, j))
|
||||
nxt = j + 1
|
||||
break
|
||||
return out
|
||||
|
||||
|
||||
def align(A, B):
|
||||
"""Align reading B to reading A. Returns {"pairs": [...], "suspects": [...]}."""
|
||||
def align(reading_a: Sequence[Record], reading_b: Sequence[Record]) -> Record:
|
||||
"""Align reading B to reading A.
|
||||
|
||||
Returns:
|
||||
`{"pairs": [...], "suspects": [...]}`: the paired sentence IDs, each with
|
||||
whether the two agree, and the suspects (differing, restructured, joined,
|
||||
dropped or added sentences).
|
||||
"""
|
||||
count_a, count_b = {}, {}
|
||||
for x in A:
|
||||
for x in reading_a:
|
||||
count_a[x["lossy"]] = count_a.get(x["lossy"], 0) + 1
|
||||
for x in B:
|
||||
for x in reading_b:
|
||||
count_b[x["lossy"]] = count_b.get(x["lossy"], 0) + 1
|
||||
pos_b = {x["lossy"]: j for j, x in enumerate(B)}
|
||||
pos_b = {x["lossy"]: j for j, x in enumerate(reading_b)}
|
||||
cands = [
|
||||
(i, pos_b[x["lossy"]]) for i, x in enumerate(A)
|
||||
if count_a[x["lossy"]] == 1 and count_b.get(x["lossy"]) == 1 and prose_length(x["lossy"]) >= MIN_PROSE
|
||||
(i, pos_b[x["lossy"]])
|
||||
for i, x in enumerate(reading_a)
|
||||
if count_a[x["lossy"]] == 1
|
||||
and count_b.get(x["lossy"]) == 1
|
||||
and prose_length(x["lossy"]) >= MIN_PROSE
|
||||
]
|
||||
anchors = _lis(cands)
|
||||
pairs = []
|
||||
prev_a, prev_b = 0, 0
|
||||
for ai, bi in anchors + [(len(A), len(B))]:
|
||||
pairs += _lcs(A, B, prev_a, ai, prev_b, bi)
|
||||
if ai < len(A):
|
||||
for ai, bi in [*anchors, (len(reading_a), len(reading_b))]:
|
||||
pairs += _lcs(reading_a, reading_b, prev_a, ai, prev_b, bi)
|
||||
if ai < len(reading_a):
|
||||
pairs.append((ai, bi))
|
||||
prev_a, prev_b = ai + 1, bi + 1
|
||||
pairs = sorted(pairs + _substitutions(A, B, pairs))
|
||||
pairs = sorted([*pairs, *_substitutions(reading_a, reading_b, pairs)])
|
||||
out_pairs, suspects = [], []
|
||||
for ai, bi in pairs:
|
||||
kind = classify(A[ai], B[bi])
|
||||
out_pairs.append({"a": A[ai]["id"], "b": B[bi]["id"], "agree": kind is None})
|
||||
kind = classify(reading_a[ai], reading_b[bi])
|
||||
out_pairs.append(
|
||||
{"a": reading_a[ai]["id"], "b": reading_b[bi]["id"], "agree": kind is None}
|
||||
)
|
||||
if kind:
|
||||
suspects.append({"kind": kind, "a": A[ai]["id"], "b": B[bi]["id"]})
|
||||
if A[ai]["context"] != B[bi]["context"]:
|
||||
suspects.append({"kind": "structure", "a": A[ai]["id"], "b": B[bi]["id"]})
|
||||
for (a1, b1), (a2, b2) in zip(pairs, pairs[1:]):
|
||||
suspects.append(
|
||||
{"kind": kind, "a": reading_a[ai]["id"], "b": reading_b[bi]["id"]}
|
||||
)
|
||||
if reading_a[ai]["context"] != reading_b[bi]["context"]:
|
||||
suspects.append(
|
||||
{
|
||||
"kind": "structure",
|
||||
"a": reading_a[ai]["id"],
|
||||
"b": reading_b[bi]["id"],
|
||||
}
|
||||
)
|
||||
for (a1, b1), (a2, b2) in pairwise(pairs):
|
||||
if a2 == a1 + 1 and b2 == b1 + 1:
|
||||
same_a = A[a1]["container"] == A[a2]["container"]
|
||||
same_b = B[b1]["container"] == B[b2]["container"]
|
||||
same_a = reading_a[a1]["container"] == reading_a[a2]["container"]
|
||||
same_b = reading_b[b1]["container"] == reading_b[b2]["container"]
|
||||
if same_a != same_b:
|
||||
suspects.append({"kind": "join", "a": A[a2]["id"], "b": B[b2]["id"]})
|
||||
suspects.append(
|
||||
{"kind": "join", "a": reading_a[a2]["id"], "b": reading_b[b2]["id"]}
|
||||
)
|
||||
paired_a = {a for a, _ in pairs}
|
||||
paired_b = {b for _, b in pairs}
|
||||
for i, x in enumerate(A):
|
||||
for i, x in enumerate(reading_a):
|
||||
if i not in paired_a:
|
||||
suspects.append({"kind": "dropped", "a": x["id"], "b": None})
|
||||
for j, x in enumerate(B):
|
||||
for j, x in enumerate(reading_b):
|
||||
if j not in paired_b:
|
||||
suspects.append({"kind": "added", "a": None, "b": x["id"]})
|
||||
return {"pairs": out_pairs, "suspects": suspects}
|
||||
+259
-54
@@ -1,14 +1,25 @@
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
# Copyright 2026 Scienting
|
||||
#
|
||||
# Source Code: https://git.scient.ing/papers/paperspec
|
||||
# See the LICENSE.md file for full license terms.
|
||||
|
||||
"""Addresses, anchors and their resolution.
|
||||
|
||||
Non-normative; see spec/06-anchors.md.
|
||||
"""
|
||||
|
||||
import math
|
||||
import re
|
||||
from collections.abc import Collection, Iterable, Mapping, Sequence
|
||||
from fractions import Fraction
|
||||
from typing import Any
|
||||
|
||||
from . import hashing, jcs
|
||||
from .model import CONTAINERS_WITH_CONTENT, LEAVES, RUN_KINDS, Doc, anchor_class
|
||||
from .text import norm
|
||||
from paperspec import hashing, jcs
|
||||
from paperspec.corrections import State
|
||||
from paperspec.jsontypes import Record
|
||||
from paperspec.model import LEAVES, Doc, anchor_class
|
||||
from paperspec.text import norm
|
||||
|
||||
ADDRESS_RE = re.compile(
|
||||
r"^(?:(?P<store>[a-z0-9][a-z0-9._-]*)/)?"
|
||||
@@ -21,12 +32,25 @@ QUOTE_CAP = 200
|
||||
CONTEXT_CAP = 32
|
||||
|
||||
|
||||
def parse_address(s):
|
||||
def parse_address(s: str) -> Record | None:
|
||||
"""Parse an address `[store/]key#node[@pin][[start:end]]`.
|
||||
|
||||
Returns:
|
||||
A dict with `store`, `key`, `node`, `pin` and `span` (`[start, end]` in code
|
||||
points, or `None`), or `None` when `s` is not an address or the span runs
|
||||
backwards.
|
||||
"""
|
||||
m = ADDRESS_RE.match(s)
|
||||
if not m:
|
||||
return None
|
||||
d = m.groupdict()
|
||||
out = {"store": d["store"], "key": d["key"], "node": d["node"], "pin": d["pin"], "span": None}
|
||||
out = {
|
||||
"store": d["store"],
|
||||
"key": d["key"],
|
||||
"node": d["node"],
|
||||
"pin": d["pin"],
|
||||
"span": None,
|
||||
}
|
||||
if d["start"] is not None:
|
||||
a, b = int(d["start"]), int(d["end"])
|
||||
if a > b:
|
||||
@@ -35,16 +59,24 @@ def parse_address(s):
|
||||
return out
|
||||
|
||||
|
||||
def format_address(store, key, node, pin=None, span=None):
|
||||
def format_address(
|
||||
store: str | None,
|
||||
key: str,
|
||||
node: str,
|
||||
pin: str | None = None,
|
||||
span: Sequence[int] | None = None,
|
||||
) -> str:
|
||||
"""Format an address; the pin is cut to its first six hex digits."""
|
||||
s = (store + "/" if store else "") + key + "#" + node
|
||||
if pin:
|
||||
s += "@" + pin[:6]
|
||||
if span is not None:
|
||||
s += "[%d:%d]" % tuple(span)
|
||||
start, end = span
|
||||
s += f"[{start}:{end}]"
|
||||
return s
|
||||
|
||||
|
||||
def cell_context(doc, cell_id):
|
||||
def cell_context(doc: Doc, cell_id: str) -> Record:
|
||||
"""Table label and the text of the row and column header paths of a cell."""
|
||||
cell = doc.nodes[cell_id]
|
||||
row = doc.nodes[cell["parent"]]
|
||||
@@ -53,7 +85,7 @@ def cell_context(doc, cell_id):
|
||||
cols = {c["id"]: c for c in table.get("attrs", {}).get("columns", [])}
|
||||
col = cols.get(cell.get("attrs", {}).get("column"), {"header_path": []})
|
||||
|
||||
def txt(nid):
|
||||
def txt(nid: str) -> str:
|
||||
return norm(hashing.plain(doc, nid))
|
||||
|
||||
return {
|
||||
@@ -63,19 +95,47 @@ def cell_context(doc, cell_id):
|
||||
}
|
||||
|
||||
|
||||
def make_anchor(doc, values, node, rev, span=None, store=None):
|
||||
def make_anchor(
|
||||
doc: Doc,
|
||||
values: Mapping[str, Record],
|
||||
node: str,
|
||||
rev: int,
|
||||
span: Sequence[int] | None = None,
|
||||
store: str | None = None,
|
||||
) -> Record:
|
||||
"""Make a `scienting-anchor/1` record for a node (spec/06).
|
||||
|
||||
Args:
|
||||
doc: The document.
|
||||
values: The content values of every node, as `hashing.compute` gives them.
|
||||
node: The node to anchor.
|
||||
rev: The revision the anchor is made at.
|
||||
span: `[start, end]` in code points of the node's plain projection, for a
|
||||
leaf; the whole leaf when `None`.
|
||||
store: The store the document lives in, if any.
|
||||
"""
|
||||
n = doc.nodes[node]
|
||||
a = {"format": "scienting-anchor/1"}
|
||||
if store:
|
||||
a["store"] = store
|
||||
a.update({"doc": doc.key, "node": node, "kind": n["kind"], "own_hash": values[node]["own_hash"],
|
||||
"node_hash": values[node]["node_hash"]})
|
||||
a.update(
|
||||
{
|
||||
"doc": doc.key,
|
||||
"node": node,
|
||||
"kind": n["kind"],
|
||||
"own_hash": values[node]["own_hash"],
|
||||
"node_hash": values[node]["node_hash"],
|
||||
}
|
||||
)
|
||||
if n["kind"] in LEAVES:
|
||||
text = hashing.plain(doc, node)
|
||||
if span is not None:
|
||||
a["span"] = list(span)
|
||||
exact = text[span[0]:span[1]]
|
||||
pre, suf = text[max(0, span[0] - CONTEXT_CAP):span[0]], text[span[1]:span[1] + CONTEXT_CAP]
|
||||
exact = text[span[0] : span[1]]
|
||||
pre, suf = (
|
||||
text[max(0, span[0] - CONTEXT_CAP) : span[0]],
|
||||
text[span[1] : span[1] + CONTEXT_CAP],
|
||||
)
|
||||
else:
|
||||
exact, pre, suf = text, "", ""
|
||||
q = {}
|
||||
@@ -97,23 +157,32 @@ def make_anchor(doc, values, node, rev, span=None, store=None):
|
||||
return a
|
||||
|
||||
|
||||
def _quote_hits(text, q):
|
||||
"""Start positions where the quote matches `text`."""
|
||||
def _quote_hits(text: str, q: Record) -> tuple[list[int], int]:
|
||||
"""Start positions where the quote matches `text`, and the quote's length."""
|
||||
if "exact" in q:
|
||||
ex = q["exact"]
|
||||
hits = [i for i in range(len(text) - len(ex) + 1) if text.startswith(ex, i)]
|
||||
length = len(ex)
|
||||
else:
|
||||
length = q["length"]
|
||||
hits = [i for i in range(len(text) - length + 1)
|
||||
if hashing.PLAIN(norm(text[i:i + length])) == q["exact_hash"]]
|
||||
hits = [
|
||||
i
|
||||
for i in range(len(text) - length + 1)
|
||||
if hashing.PLAIN(norm(text[i : i + length])) == q["exact_hash"]
|
||||
]
|
||||
if len(hits) > 1 and ("prefix" in q or "suffix" in q):
|
||||
pre, suf = q.get("prefix", ""), q.get("suffix", "")
|
||||
hits = [i for i in hits if text[:i].endswith(pre) and text[i + length:].startswith(suf)]
|
||||
hits = [
|
||||
i
|
||||
for i in hits
|
||||
if text[:i].endswith(pre) and text[i + length :].startswith(suf)
|
||||
]
|
||||
return hits, length
|
||||
|
||||
|
||||
def _drift(state, doc, anchor, nid, threshold):
|
||||
def _drift(
|
||||
state: State, doc: Doc, anchor: Record, nid: str, threshold: Fraction
|
||||
) -> Record:
|
||||
leaves = set(doc.leaves(nid))
|
||||
touched = set()
|
||||
count = 0
|
||||
@@ -131,17 +200,19 @@ def _drift(state, doc, anchor, nid, threshold):
|
||||
return {"count": count, "share": _decimal(share), "level": level}
|
||||
|
||||
|
||||
def _decimal(fr):
|
||||
def _decimal(fr: Fraction) -> str:
|
||||
"""A share as a decimal string with four places, rounded half up."""
|
||||
v = (fr * 10000 + Fraction(1, 2)).__floor__()
|
||||
return "%d.%04d" % (v // 10000, v % 10000)
|
||||
v = math.floor(fr * 10000 + Fraction(1, 2))
|
||||
return f"{v // 10000}.{v % 10000:04d}"
|
||||
|
||||
|
||||
def _follow(state, nid):
|
||||
"""Follow aliases and retirements. Returns (live id or None, chain, via)."""
|
||||
live = {n["id"] for n in state.nodes}
|
||||
table = {e["id"]: e for e in state.ids}
|
||||
chain, via = [], None
|
||||
def _walk(
|
||||
live: Collection[str], ids: Iterable[Record], nid: str
|
||||
) -> tuple[str | None, list[str], str | None]:
|
||||
"""Walk the ID table from `nid` until a live ID, a deletion, a repeat or an unknown ID."""
|
||||
table = {e["id"]: e for e in ids}
|
||||
chain: list[str] = []
|
||||
via = None
|
||||
seen = set()
|
||||
while nid not in live:
|
||||
if nid in seen or nid not in table:
|
||||
@@ -151,44 +222,161 @@ def _follow(state, nid):
|
||||
if e["kind"] == "retired" or via is None:
|
||||
via = e["kind"]
|
||||
chain.append(nid)
|
||||
nid = e.get("successor")
|
||||
if nid is None:
|
||||
successor = e.get("successor")
|
||||
if successor is None:
|
||||
return None, chain, via
|
||||
nid = successor
|
||||
return nid, chain, via
|
||||
|
||||
|
||||
def _relabel_reverted_own(state, doc, nid, anchor):
|
||||
"""The own_hash the node had before the relabel corrections since the anchor, or None when anything else
|
||||
changed the node or what is below it since (spec/06 §6.5: its *only* changes were relabel corrections)."""
|
||||
since = [c for c in state.corrections if c["index"] > anchor["rev"] and (
|
||||
c.get("target") == nid or nid in (c.get("path") or []) or nid in (c.get("to_path") or []))]
|
||||
def follow(state: State, nid: str) -> tuple[str | None, list[str], str | None]:
|
||||
"""Follow aliases and retirements from a node ID (spec/06 §6.5, "Follow the ID").
|
||||
|
||||
Args:
|
||||
state: The document state, with its nodes and ID table.
|
||||
nid: A node ID or a legacy alias.
|
||||
|
||||
Returns:
|
||||
A tuple `(live, chain, via)`: the live node ID reached, or `None` when a
|
||||
deletion ends the chain or an ID is unknown or repeats; the IDs followed, in
|
||||
order; and the kind of the chain (`retired` when it passed a retirement,
|
||||
else `alias` when it followed an alias, else `None`).
|
||||
"""
|
||||
return _walk({n["id"] for n in state.nodes}, state.ids, nid)
|
||||
|
||||
|
||||
def resolve_address(
|
||||
nodes: Iterable[Record],
|
||||
ids: Iterable[Record],
|
||||
address: str,
|
||||
values: Mapping[str, Record] | None = None,
|
||||
) -> Record:
|
||||
"""Resolve a pinned address against nodes and an ID table alone (spec/06 §6.1, §6.5).
|
||||
|
||||
This needs no `State` and no corrections: it follows aliases and retirements
|
||||
through `ids`, then compares the address's pin, the first six hex digits of a
|
||||
`node_hash`, with the live node's. It never returns `moved`, `reattached` or
|
||||
`changed-below`, which need a quote, an anchor or the corrections.
|
||||
|
||||
An empty span such as `[3:3]` is a valid address: the grammar of spec/06 §6.1
|
||||
requires only that `start` is not greater than `end`, and `addresses.jsonl`
|
||||
has `[0:0]`. The node part is any `lowalnum` run, a node ID or an alias, so
|
||||
a caller that wants only seven-character node IDs checks that itself.
|
||||
|
||||
Args:
|
||||
nodes: The node records, as `nodes.jsonl` gives them (`id` and `node_hash`).
|
||||
ids: The ID table records, as `ids.jsonl` gives them.
|
||||
address: An address `[store/]key#node[@pin][[start:end]]`.
|
||||
values: The content values of every node, as `hashing.compute` gives them,
|
||||
used in place of the stored `node_hash` when given.
|
||||
|
||||
Returns:
|
||||
A record with `result`, `node`, `node_hash`, `via` and `span` as for
|
||||
`resolve`. `result` is `current` when the live node is reached without a
|
||||
retirement and the address has no pin or the pin is the start of the
|
||||
node's `node_hash`; otherwise `stale`, with a `reason`: `not an address`,
|
||||
`unknown node`, `retired without a successor`, `retired` (the node is the
|
||||
successor reached), or `the pin differs from the node hash`.
|
||||
"""
|
||||
parts = parse_address(address)
|
||||
if parts is None:
|
||||
return {"result": "stale", "node": None, "reason": "not an address"}
|
||||
index = {n["id"]: n for n in nodes}
|
||||
nid, chain, via = _walk(index, ids, parts["node"])
|
||||
out: Record = {"result": "stale", "node": nid}
|
||||
hash_: str | None = None
|
||||
if nid is not None:
|
||||
hash_ = (values[nid] if values is not None else index[nid]).get("node_hash")
|
||||
out["node_hash"] = hash_
|
||||
if chain:
|
||||
out["via"] = chain
|
||||
if nid is None:
|
||||
out["reason"] = "retired without a successor" if chain else "unknown node"
|
||||
elif via == "retired":
|
||||
out["reason"] = "retired"
|
||||
elif parts["pin"] is not None and not (hash_ or "").startswith(parts["pin"]):
|
||||
out["reason"] = "the pin differs from the node hash"
|
||||
else:
|
||||
out["result"] = "current"
|
||||
if parts["span"] is not None:
|
||||
out["span"] = parts["span"]
|
||||
return out
|
||||
|
||||
|
||||
def _relabel_reverted_own(
|
||||
state: State, doc: Doc, nid: str, anchor: Record
|
||||
) -> str | None:
|
||||
"""The own_hash the node had before the relabel corrections since the anchor.
|
||||
|
||||
It is `None` when anything else changed the node or what is below it since
|
||||
(spec/06 §6.5: its *only* changes were relabel corrections).
|
||||
"""
|
||||
since = [
|
||||
c
|
||||
for c in state.corrections
|
||||
if c["index"] > anchor["rev"]
|
||||
and (
|
||||
c.get("target") == nid
|
||||
or nid in (c.get("path") or [])
|
||||
or nid in (c.get("to_path") or [])
|
||||
)
|
||||
]
|
||||
rel = [c for c in since if c.get("target") == nid]
|
||||
if not rel or any(c["op"] != "relabel" or c.get("target") != nid for c in since):
|
||||
return None
|
||||
n = dict(doc.nodes[nid], label=rel[0]["from"])
|
||||
tmp = Doc(doc.key, [n if x["id"] == nid else x for x in [doc.nodes[i] for i in doc.order]])
|
||||
return hashing.PLAIN(jcs.dumpb(hashing.own_content(tmp, nid, lambda h: hashing.PLAIN(
|
||||
norm(hashing.plain(tmp, h))))))
|
||||
tmp = Doc(
|
||||
doc.key, [n if x["id"] == nid else x for x in [doc.nodes[i] for i in doc.order]]
|
||||
)
|
||||
return hashing.PLAIN(
|
||||
jcs.dumpb(
|
||||
hashing.own_content(
|
||||
tmp, nid, lambda h: hashing.PLAIN(norm(hashing.plain(tmp, h)))
|
||||
)
|
||||
)
|
||||
)
|
||||
|
||||
|
||||
def resolve(state, anchor, threshold=Fraction(1, 4)):
|
||||
def resolve(
|
||||
state: State, anchor: Record, threshold: Fraction = Fraction(1, 4)
|
||||
) -> Record:
|
||||
"""Resolve an anchor against the current state of its document (spec/06 §6.5).
|
||||
|
||||
Args:
|
||||
state: The document state, with its corrections and ID table.
|
||||
anchor: A `scienting-anchor/1` record.
|
||||
threshold: The share of a container's leaves touched by later corrections
|
||||
above which `changed-below` drift counts as high.
|
||||
|
||||
Returns:
|
||||
A record with `result` (`current`, `moved`, `reattached`, `changed-below` or
|
||||
`stale`), `node` (the live node, or `None`), its `node_hash`, the `via` chain
|
||||
of aliases and retirements followed, and, as the result calls for, `span`,
|
||||
`reason` and `drift`.
|
||||
"""
|
||||
doc = state.doc()
|
||||
values = hashing.compute(doc)
|
||||
kind = anchor.get("kind")
|
||||
original = anchor["node"]
|
||||
nid, chain, via = _follow(state, original)
|
||||
nid, chain, via = follow(state, original)
|
||||
live_kind = doc.nodes[nid]["kind"] if nid else None
|
||||
table = {e["id"]: e for e in state.ids}
|
||||
# The kind falls back to the retired entry the chain reached (spec/06 §6.5); an alias carries no kind.
|
||||
retired_kind = next((table[x].get("node_kind") for x in reversed(chain)
|
||||
if table.get(x, {}).get("kind") == "retired"), None)
|
||||
# The kind falls back to the retired entry the chain reached (spec/06 §6.5); an
|
||||
# alias carries no kind.
|
||||
retired_kind = next(
|
||||
(
|
||||
table[x].get("node_kind")
|
||||
for x in reversed(chain)
|
||||
if table.get(x, {}).get("kind") == "retired"
|
||||
),
|
||||
None,
|
||||
)
|
||||
kind = kind or live_kind or retired_kind
|
||||
cls = anchor_class(kind) if kind else "leaf"
|
||||
is_span = "span" in anchor
|
||||
result = {"node": nid}
|
||||
retired = via == "retired"
|
||||
|
||||
def out(res, **kw):
|
||||
def out(res: str, **kw: Any) -> Record:
|
||||
r = {"result": res, "node": kw.pop("node", nid)}
|
||||
if r["node"]:
|
||||
r["node_hash"] = values[r["node"]]["node_hash"]
|
||||
@@ -198,7 +386,7 @@ def resolve(state, anchor, threshold=Fraction(1, 4)):
|
||||
return r
|
||||
|
||||
# The cell rule: a retired cell is found again by its table label and header paths.
|
||||
def cell_rule():
|
||||
def cell_rule() -> Record | None:
|
||||
ctx = anchor.get("context")
|
||||
q = anchor.get("quote")
|
||||
if kind != "cell" or not ctx or not q:
|
||||
@@ -221,8 +409,11 @@ def resolve(state, anchor, threshold=Fraction(1, 4)):
|
||||
return None
|
||||
|
||||
if nid is None:
|
||||
return cell_rule() or out("stale", node=None, reason="retired without a successor" if chain
|
||||
else "unknown node")
|
||||
return cell_rule() or out(
|
||||
"stale",
|
||||
node=None,
|
||||
reason="retired without a successor" if chain else "unknown node",
|
||||
)
|
||||
|
||||
if cls == "leaf":
|
||||
text = hashing.plain(doc, nid)
|
||||
@@ -233,16 +424,26 @@ def resolve(state, anchor, threshold=Fraction(1, 4)):
|
||||
if q:
|
||||
hits, ln = _quote_hits(text, q)
|
||||
if (is_span and len(hits) == 1) or (not is_span and hits):
|
||||
return out("moved", **({"span": [hits[0], hits[0] + ln]} if is_span else {}))
|
||||
return cell_rule() or out("stale", reason="the successor does not contain the quote")
|
||||
return out(
|
||||
"moved",
|
||||
**({"span": [hits[0], hits[0] + ln]} if is_span else {}),
|
||||
)
|
||||
return cell_rule() or out(
|
||||
"stale", reason="the successor does not contain the quote"
|
||||
)
|
||||
if q:
|
||||
hits, ln = _quote_hits(text, q)
|
||||
if len(hits) == 1:
|
||||
return out("reattached", **({"span": [hits[0], hits[0] + ln]} if is_span else {}))
|
||||
return out(
|
||||
"reattached",
|
||||
**({"span": [hits[0], hits[0] + ln]} if is_span else {}),
|
||||
)
|
||||
own = _relabel_reverted_own(state, doc, nid, anchor)
|
||||
if own is not None and own == anchor["own_hash"]:
|
||||
return out("reattached", reason="relabel")
|
||||
return out("stale", reason="the node changed and the quote does not occur exactly once")
|
||||
return out(
|
||||
"stale", reason="the node changed and the quote does not occur exactly once"
|
||||
)
|
||||
|
||||
if cls == "container-with-content":
|
||||
if values[nid]["own_hash"] == anchor["own_hash"]:
|
||||
@@ -250,7 +451,9 @@ def resolve(state, anchor, threshold=Fraction(1, 4)):
|
||||
return out("moved")
|
||||
if values[nid]["node_hash"] == anchor["node_hash"]:
|
||||
return out("current")
|
||||
return out("changed-below", drift=_drift(state, doc, anchor, nid, threshold))
|
||||
return out(
|
||||
"changed-below", drift=_drift(state, doc, anchor, nid, threshold)
|
||||
)
|
||||
if not retired:
|
||||
own = _relabel_reverted_own(state, doc, nid, anchor)
|
||||
if own is not None and own == anchor["own_hash"]:
|
||||
@@ -265,7 +468,9 @@ def resolve(state, anchor, threshold=Fraction(1, 4)):
|
||||
held = sum(1 for i, m in orig if i in now or m in now_match)
|
||||
if 2 * held >= len(orig):
|
||||
return out("moved")
|
||||
return out("stale", reason="the successor holds fewer than half of the original leaves")
|
||||
return out(
|
||||
"stale", reason="the successor holds fewer than half of the original leaves"
|
||||
)
|
||||
if values[nid]["node_hash"] == anchor["node_hash"]:
|
||||
return out("current")
|
||||
return out("changed-below", drift=_drift(state, doc, anchor, nid, threshold))
|
||||
@@ -0,0 +1,102 @@
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
# Copyright 2026 Scienting
|
||||
#
|
||||
# Source Code: https://git.scient.ing/papers/paperspec
|
||||
# See the LICENSE.md file for full license terms.
|
||||
|
||||
"""Claim references and pins.
|
||||
|
||||
A claim reference is `claim:TAG` or `claim:HOST/TAG`, the tag being eight Crockford
|
||||
base32 capitals; a pin is a reference, `@` and the first six lowercase hex digits of
|
||||
the claim's statement hash. The patterns are those of `claimRef` and `claimPin` in
|
||||
`schemas/common.schema.json`. Non-normative; see spec/18 §18.4, spec/02 §2.4 and
|
||||
spec/20.
|
||||
"""
|
||||
|
||||
import re
|
||||
|
||||
from paperspec.jsontypes import Record
|
||||
|
||||
_HOST = r"(?P<host>[a-z0-9.-]+\.[a-z]{2,})"
|
||||
_TAG = r"(?P<tag>[0-9A-HJKMNP-TV-Z]{8})"
|
||||
# `\Z`, not `$`: the schema's `$` (ECMAScript) does not match before a final newline.
|
||||
CLAIM_REF_RE = re.compile(rf"^claim:(?:{_HOST}/)?{_TAG}\Z")
|
||||
CLAIM_PIN_RE = re.compile(
|
||||
rf"^(?P<ref>claim:(?:{_HOST}/)?{_TAG})@(?P<pin>[0-9a-f]{{6}})\Z"
|
||||
)
|
||||
PIN_LENGTH = 6
|
||||
|
||||
|
||||
def parse_ref(s: str) -> Record | None:
|
||||
"""Parse a claim reference `claim:[host/]TAG` (spec/18 §18.4).
|
||||
|
||||
Args:
|
||||
s: The text to parse.
|
||||
|
||||
Returns:
|
||||
A dict with `host` (`None` for the local store) and `tag`, or `None` when
|
||||
`s` is not a claim reference.
|
||||
"""
|
||||
m = CLAIM_REF_RE.match(s)
|
||||
if not m:
|
||||
return None
|
||||
return {"host": m["host"], "tag": m["tag"]}
|
||||
|
||||
|
||||
def parse_pin(s: str) -> Record | None:
|
||||
"""Parse a claim pin `claim:[host/]TAG@pin` (spec/18 §18.4).
|
||||
|
||||
Args:
|
||||
s: The text to parse.
|
||||
|
||||
Returns:
|
||||
A dict with `ref` (the reference without the pin), `host`, `tag` and `pin`
|
||||
(six lowercase hex digits), or `None` when `s` is not a claim pin.
|
||||
"""
|
||||
m = CLAIM_PIN_RE.match(s)
|
||||
if not m:
|
||||
return None
|
||||
return {"ref": m["ref"], "host": m["host"], "tag": m["tag"], "pin": m["pin"]}
|
||||
|
||||
|
||||
def format_ref(tag: str, host: str | None = None) -> str:
|
||||
"""Format a claim reference.
|
||||
|
||||
Args:
|
||||
tag: The eight-character claim tag.
|
||||
host: The domain of another claim store, or `None` for the local one.
|
||||
|
||||
Returns:
|
||||
`claim:TAG`, or `claim:HOST/TAG` when a host is given.
|
||||
|
||||
Raises:
|
||||
ValueError: If the result is not a claim reference.
|
||||
"""
|
||||
s = f"claim:{host}/{tag}" if host else f"claim:{tag}"
|
||||
if not CLAIM_REF_RE.match(s):
|
||||
msg = f"not a claim reference: {s!r}"
|
||||
raise ValueError(msg)
|
||||
return s
|
||||
|
||||
|
||||
def format_pin(ref: str, statement_hash: str) -> str:
|
||||
"""Pin a claim reference to its statement hash.
|
||||
|
||||
Args:
|
||||
ref: A claim reference.
|
||||
statement_hash: The claim's statement hash, 64 lowercase hex digits.
|
||||
|
||||
Returns:
|
||||
The reference, `@` and the first six digits of the hash.
|
||||
|
||||
Raises:
|
||||
ValueError: If `ref` is not a claim reference or the hash is not 64
|
||||
lowercase hex digits.
|
||||
"""
|
||||
if not CLAIM_REF_RE.match(ref):
|
||||
msg = f"not a claim reference: {ref!r}"
|
||||
raise ValueError(msg)
|
||||
if not re.fullmatch(r"[0-9a-f]{64}", statement_hash):
|
||||
msg = "a statement hash is 64 lowercase hex digits"
|
||||
raise ValueError(msg)
|
||||
return f"{ref}@{statement_hash[:PIN_LENGTH]}"
|
||||
@@ -1,55 +1,82 @@
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
# Copyright 2026 Scienting
|
||||
#
|
||||
# Source Code: https://git.scient.ing/papers/paperspec
|
||||
# See the LICENSE.md file for full license terms.
|
||||
|
||||
"""The `paperspec` command's subcommands, one module each; the parser and the help are in `main.py`.
|
||||
|
||||
`paperspec validate` and `paperspec load` work anywhere the package is installed with `paperspec[tools]`.
|
||||
`paperspec check`, `build`, `stress` and `site` work on a checkout of the paperspec repository: the one an
|
||||
editable install points at, or else the one around the current folder.
|
||||
Each module has `run(args)`, which takes the parsed arguments and returns the exit status.
|
||||
`paperspec validate`, `paperspec correct` and `paperspec load` work anywhere the package is
|
||||
installed with `paperspec[tools]`. `paperspec check`, `build`, `stress` and `site` work on a
|
||||
checkout of the paperspec repository: the one an editable install points at, or else the one
|
||||
around the current folder. Each module has `run(args)`, which takes the parsed arguments and
|
||||
returns the exit status.
|
||||
"""
|
||||
|
||||
import importlib.util
|
||||
import os
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
REPOSITORY = "https://git.scient.ing/infra/paperspec.git"
|
||||
REPOSITORY = "https://git.scient.ing/papers/paperspec.git"
|
||||
INSTALL = "https://paperspec.scient.ing/deploy/#install-from-the-registry"
|
||||
|
||||
|
||||
class UsageError(Exception):
|
||||
"""Arguments that parse but do not fit together; `paperspec` prints the command's usage and exits 2."""
|
||||
"""Arguments that parse but do not fit together.
|
||||
|
||||
`paperspec` prints the command's usage and exits 2.
|
||||
"""
|
||||
|
||||
|
||||
def require(*modules):
|
||||
"""Exit with what to install when a package a command needs is missing."""
|
||||
def require(*modules: str) -> None:
|
||||
"""Exit with what to install when a package a command needs is missing.
|
||||
|
||||
Args:
|
||||
*modules: Importable names of the packages the command needs.
|
||||
"""
|
||||
missing = [m for m in modules if importlib.util.find_spec(m) is None]
|
||||
if missing:
|
||||
sys.exit("This command needs %s %s, which the package's tools extra installs.\n"
|
||||
"Install paperspec[tools] from the package registry: %s\n"
|
||||
"In a checkout of the repository, pip install -e \".[tools]\" or pixi run COMMAND installs them."
|
||||
% ("the package" if len(missing) == 1 else "the packages", " and ".join(missing), INSTALL))
|
||||
what = "the package" if len(missing) == 1 else "the packages"
|
||||
sys.exit(
|
||||
f"This command needs {what} {' and '.join(missing)}, "
|
||||
"which the package's tools extra installs.\n"
|
||||
f"Install paperspec[tools] from the package registry: {INSTALL}\n"
|
||||
'In a checkout of the repository, pip install -e ".[tools]" '
|
||||
"or pixi run COMMAND installs them."
|
||||
)
|
||||
|
||||
|
||||
def _is_checkout(d):
|
||||
return all(os.path.exists(os.path.join(d, m)) for m in ("pyproject.toml", "spec", "registry", "fixtures/src"))
|
||||
def _is_checkout(d: Path) -> bool:
|
||||
return all(
|
||||
(d / m).exists() for m in ("pyproject.toml", "spec", "registry", "fixtures/src")
|
||||
)
|
||||
|
||||
|
||||
def checkout():
|
||||
"""The root of the paperspec checkout a repository command works on, or exit with what to do.
|
||||
def checkout() -> str:
|
||||
"""Find the root of the paperspec checkout a repository command works on.
|
||||
|
||||
An editable install (and `python -m paperspec` from `src/`) runs the checkout this file is in, so the code
|
||||
and the files it checks always match; an installed wheel uses the nearest checkout above the current folder.
|
||||
An editable install (and `python -m paperspec` from `src/`) runs the checkout this file is
|
||||
in, so the code and the files it checks always match; an installed wheel uses the nearest
|
||||
checkout above the current folder.
|
||||
|
||||
Returns:
|
||||
The root folder of the checkout.
|
||||
"""
|
||||
own = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
|
||||
own = Path(__file__).absolute().parents[3]
|
||||
if _is_checkout(own):
|
||||
return own
|
||||
d = os.getcwd()
|
||||
return str(own)
|
||||
d = Path.cwd()
|
||||
while True:
|
||||
if _is_checkout(d):
|
||||
return d
|
||||
parent = os.path.dirname(d)
|
||||
return str(d)
|
||||
parent = d.parent
|
||||
if parent == d:
|
||||
sys.exit("This command works on a checkout of the paperspec repository, and %s is not inside one.\n"
|
||||
sys.exit(
|
||||
"This command works on a checkout of the paperspec repository, "
|
||||
f"and {Path.cwd()} is not inside one.\n"
|
||||
"Clone it and run the command there:\n"
|
||||
" git clone %s\n"
|
||||
f" git clone {REPOSITORY}\n"
|
||||
" cd paperspec && pixi run check\n"
|
||||
"paperspec validate and paperspec load work anywhere." % (os.getcwd(), REPOSITORY))
|
||||
"paperspec validate and paperspec load work anywhere."
|
||||
)
|
||||
d = parent
|
||||
+5922
-1224
File diff suppressed because it is too large.
Load diff
Loaded 100 of 189 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user