pain001-lsp¶
Contents¶
Getting started
Install: pip, pipx or uv, Docker, the VS Code extension
Requirements: toolchain floor, platforms
Quick Start: point your editor at
pain001-lsp, or call the helpers directly
The pain001-lsp ecosystem
The pain001-lsp ecosystem: the core library and the other thirteen members of the pain001 suite
Library reference
Capabilities at a glance: the current surface by theme
Ecosystem comparison: short matrix; full table at
docs/COMPARISON.mdBenchmarks: headline numbers; full table at
docs/BENCHMARKS.mdFeatures: module-level capability list
Configuration: core options
Examples: runnable example index
Operational
When not to use pain001-lsp: limitations
Development: make targets, fuzzing, CI
Security: guarantees and compliance
Documentation: all reference docs
Stability guarantees: SemVer axis, output stability, minimum toolchain discipline
Install¶
As a Python library¶
python -m pip install pain001-lsp
Latest release: v0.0.90: released with pain001 0.0.90. Diagnostics, completion and the editor commands are unchanged; the container image moves to Python 3.15.
The package installs a pain001-lsp console command and pulls in the core
pain001 library, pygls and jsonschema. To keep the
command on your PATH without touching a project environment:
pipx install pain001-lsp
uv tool install pain001-lsp
Check the install:
python -c "import pain001_lsp; print(pain001_lsp.__version__)"
As a container¶
docker pull ghcr.io/sebastienrousseau/pain001-lsp:latest
The image (linux/amd64 and linux/arm64) runs pain001-lsp over stdio as a
non-root user; an editor launches it with docker run -i --rm ghcr.io/sebastienrousseau/pain001-lsp.
As a VS Code extension¶
Every release
attaches pain001-lsp-json-<version>.vsix. In VS Code choose Extensions,
the ... menu, Install from VSIX…. The extension starts the
pain001-lsp command, so install the Python package as well. Its source is
in editors/vscode/.
Requirements¶
Python 3.11 or newer, tested in CI on 3.11, 3.12, 3.13 and 3.14 on Linux (toolchain policy). The package is pure Python and runs wherever its dependencies do: macOS, Linux and Windows.
pain0010.0.90 or newer (below 1.0),pygls2.1 or newer (below 3) andjsonschema4.17 or newer (below 5), installed automatically.An editor with a Language Server Protocol client (Neovim, VS Code, Helix, Emacs, Sublime Text LSP and others).
Quick Start¶
-- Neovim 0.11+, built-in LSP client
vim.lsp.config["pain001"] = {
cmd = { "pain001-lsp" },
filetypes = { "json" },
root_markers = { ".git" },
init_options = { messageType = "pain.001.001.09" },
}
vim.lsp.enable("pain001")
Open a JSON array of payment records. The server validates every record on
open and on each change, completes field names and message types, shows
schema descriptions on hover, offers a quick fix that inserts the record’s
missing required fields, formats the document and outlines it by record.
pain001-lsp speaks LSP on stdin and stdout, so any editor that can spawn a
command over stdio can use it: register pain001-lsp as the command for
JSON files, with the same initializationOptions.
The same logic is importable, without an editor:
import json
from pain001_lsp.server import compute_diagnostics, missing_required_fields
doc = json.dumps([{"id": "MSG-0001", "debtor_account_IBAN": "INVALID"}])
for diagnostic in compute_diagnostics(doc)[:2]:
print(diagnostic["severity"], diagnostic["message"])
print(missing_required_fields({"id": "MSG-0001"})[:3])
The pain001-lsp ecosystem¶
pain001-lsp is one of the fourteen repositories of the pain001 suite, built
around the pain001 library for ISO 20022 customer credit
transfer initiation (pain.001) files. Every member ships the same version,
the core first, and every interface calls the core’s validators and
schemas, so the editor, the command line, the REST API and an AI agent
apply the same rules.
Component |
Purpose |
Use case |
|---|---|---|
Core library, CLI and REST API: generate and validate ISO 20022 payment files from CSV, JSON and other data |
You produce payment files in code, scripts or a service |
|
Language Server for the payment-data records that drive generation |
You author or review those records in an editor: this package |
|
Model Context Protocol server exposing the library as agent tools |
You work with payment data from an AI assistant |
|
SWIFT MT101 requests for transfer to |
Your transfers still arrive as MT101 |
|
Excel |
Finance teams keep payments in a spreadsheet |
|
Synthetic SFTP bank-response test service |
Generate pain.002 replies in integration tests |
|
Cookiecutter plugin scaffold |
Develop an external loader or validator |
|
Experimental native validation extension |
Optional IBAN, BIC and character-set helpers |
|
Website and browser demo |
Browse documentation and try the library |
|
Go client for the REST API, tested with the conformance kit |
Call the REST API from Go services |
|
Java client for the REST API, tested with the conformance kit |
Call the REST API from JVM applications |
|
Rust client for the REST API, tested with the conformance kit |
Call the REST API from Rust programs |
|
.NET client for the REST API, tested with the conformance kit |
Call the REST API from .NET applications |
|
C++ client for the REST API, tested with the conformance kit |
Call the REST API from C++ programs |
Capabilities at a glance¶
Area |
Capability |
Status |
|---|---|---|
Diagnostics |
Each record checked against the message type’s input JSON Schema; IBAN and BIC fields checked with the core validators |
Released |
Diagnostics (CSV) |
|
Released |
Completion |
Every input field with its schema description, plus every supported message type by name |
Released |
Hover |
The schema description of the field under the cursor |
Released |
Code actions |
Quick fix inserting the missing required fields of the record under the cursor |
Released |
Outline |
One document symbol per record, named by |
Released |
Formatting |
Whole-document pretty-print, 2-space indent, idempotent |
Released |
Example corpus |
|
Released |
Faces |
|
Released |
Targeted fixes per diagnostic, code lenses |
See |
Planned |
Ecosystem comparison¶
The alternatives to this server are a JSON Schema alone, in any
schema-aware editor, and calling the pain001 library from a script after
saving.
Project |
Feedback while typing |
IBAN check digits |
Quick fix for missing fields |
|---|---|---|---|
pain001-lsp |
Yes |
Yes |
Yes |
A JSON Schema alone |
Yes |
No |
No |
|
No |
Yes |
No |
See docs/COMPARISON.md for the evidence and complete matrix.
Benchmarks¶
Diagnostics run on every keystroke, so the number that matters is how large
a document stays interactive. Measured with benches/bench_diagnostics.py.
Scenario |
Result |
Environment |
|---|---|---|
Diagnostics, cost per record |
0.08 ms |
recorded for 0.0.64 (2026-08-29) |
Interactive budget (under 100 ms per change) |
~1,200 records |
recorded for 0.0.64 (2026-08-29) |
Malformed document |
0.01 ms |
Apple A18 Pro, Python 3.12.15, load average above 30 (2026-10-21) |
See docs/BENCHMARKS.md for methodology and full results.
Features¶
For payment-data files: a JSON array of flat payment records, or a single
record object treated as one record. Documents whose URI ends in .csv go
to the core’s CSV engine instead.
Editors send the server other JSON files too (package.json,
tsconfig.json). A JSON document gets diagnostics only when it is an
array, or an object with at least one field of the active message type as
a key; text that does not parse yet counts when it opens an array or
quotes one of those fields as a key. Any other document is published with
no diagnostics.
Diagnostics: schema validation reports missing required fields, wrong types, and pattern or length violations.
debtor_account_IBAN,creditor_account_IBAN,charge_account_IBANand the*_agent_BICfields are also checked as IBAN or BIC (warnings). A document that does not parse gets one error: at JSON’s position for a syntax error, at the top for nesting too deep or an integer too long.Completion: every input field for the message type, with its schema description as the detail, plus every supported message type with its name (
pain.001.001.09: Customer Credit Transfer Initiation V09).Hover: the schema
descriptionof the field under the cursor.Code actions: “Add missing required fields” on the record under the cursor, inserting type-appropriate placeholders (
"",0,false,[],{}) before its closing brace.Document symbols: one symbol per top-level record, named by its
id(or<record N>), withpayment_idas the detail.Formatting: two-space JSON with a trailing newline as one whole-document edit; no edit when already formatted or when the JSON does not parse.
Corpus commands:
pain001.corpus.listlists the validated example files the core ships (filter bykind,country,version);pain001.corpus.getreturns one file’s XML with its provenance.Faces commands (pain001 0.0.78):
pain001.faces.listnames each face and the binding keys it accepts;pain001.faces.projecttakes{"xml", "face", "version"?, "bindings"?}with the open buffer’s text asxmland returns the UK Open Banking, Berlin Group or ISO 20022-named payload with a loss report of every element not carried, or{"error": ...}when the face refuses.
The logic lives in pure helpers in pain001_lsp.server:
compute_diagnostics, compute_diagnostics_csv, completion_items,
hover_text, missing_required_fields, build_insert_text, corpus_list
and corpus_get, and in pain001_lsp._faces: faces_list and
faces_project. The LSP handlers map their plain dicts to lsprotocol
types. Each diagnostic is
{"line": int, "character": int, "severity": "error" | "warning", "message": str}.
Configuration¶
Setting |
Where |
Description |
|---|---|---|
|
|
Message type to validate against at startup (default |
|
|
Switch the message type without a restart. |
|
VS Code setting |
Command that starts the server (default |
|
VS Code setting |
Message type, one of the thirteen the core supports. |
|
VS Code setting |
Glob of the JSON files sent to the server (default |
pain001-lsp takes no command-line options: it speaks LSP over stdio from
the first byte. A message type the core does not support is ignored, and
the previous one stays active.
Examples¶
One runnable script per surface in examples/, each
run in CI and by make examples:
Example |
Demonstrates |
|---|---|
Diagnostics, completion and hover on sample records |
|
The missing-fields quick fix and the snippet it inserts |
|
Overriding the message type through |
|
The example-corpus commands |
|
The faces commands: list the faces, project a document, and a refusal |
git clone https://github.com/sebastienrousseau/pain001-lsp.git && cd pain001-lsp
poetry install --all-extras
poetry run python examples/01_lsp_helpers.py
When not to use pain001-lsp¶
You have no LSP-capable editor. Scripts and CI are better served by
pain001 validateand the core’s REST API.You are authoring
pain.001XML. Completion, hover and the quick fix target the JSON records that drive generation, not XML; use an XSD-aware XML language server.Your documents run to thousands of records. Diagnostics re-validate the whole document on every change (see Benchmarks), so very large files lag on each keystroke.
You want agent tools, not editor diagnostics. Use
pain001-mcp.
Development¶
git clone https://github.com/sebastienrousseau/pain001-lsp.git && cd pain001-lsp
poetry install --all-extras
make check # lint, mypy, bandit, complexity, versions, tests, docstrings, examples, spelling
make test # pytest, 100% line and branch coverage enforced
make complexity # per-function ceilings against complexity-baseline.json
make mutate # mutation testing of the handlers, 85% floor
make demo # re-render .github/demo.gif with VHS
CI installs from hash-pinned requirements/*.txt (compiled from
requirements/*.in with uv pip compile --generate-hashes, through
scripts/ci-install.sh) and runs the test matrix on Python 3.11 to 3.14,
ruff, black, mypy in strict mode, bandit, interrogate (100% docstrings), the
complexity ceilings, the version-source check, pip-audit over poetry.lock
and every requirements file, codespell and markdownlint, mutation testing,
Atheris fuzzing, CodeQL and OpenSSF Scorecard.
DEVELOPMENT.md
maps each CI job to the command that reproduces it locally. See CONTRIBUTING.md and
RELEASING.md.
Security¶
The server reads only the document text the editor sends over stdio. It
opens no network socket, executes nothing from the document, takes no file
path from the client, and parses JSON with the standard library; a document
that does not parse yields one diagnostic, never an exception. The document
handlers are fuzzed with Atheris on every change and weekly (see
fuzz/). Actions are pinned by SHA, the container base image by
digest, every pip install is hash-pinned, workflow tokens are
least-privilege, and releases carry SLSA provenance, PEP 740 attestations,
cosign signatures and SPDX and CycloneDX SBOMs.
The project holds the
OpenSSF Best Practices passing badge.
Report vulnerabilities according to SECURITY.md.
Documentation¶
User manual · API reference · Developer docs · Family map · Architecture · Releasing · Contributing · Changelog · Roadmap · Security policy · Support · What is pain.001?
Stability guarantees¶
The project is pre-1.0 and versions advance in 0.0.1 steps, in lockstep
with the rest of the pain001 suite. The breaking axis is what an editor
receives: the capabilities the server advertises, and the diagnostics,
completion items, code actions, symbols and edits it returns, including the
plain-dict shapes of the public helpers. A change to what the server
reports for the same document is breaking even when no Python signature
moves, and is called out in the changelog. The Python floor
moves only as described in the toolchain policy.
License¶
This project is dual-licensed under either:
Apache License, Version 2.0 (
LICENSE-APACHEor https://www.apache.org/licenses/LICENSE-2.0)MIT License (
LICENSE-MITor https://opensource.org/licenses/MIT)
at your option. Any contribution submitted for inclusion is licensed the same way, without additional terms. Dependencies keep their own licences. Built on pygls and lsprotocol.