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

Library reference

Operational


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.

  • pain001 0.0.90 or newer (below 1.0), pygls 2.1 or newer (below 3) and jsonschema 4.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

pain001

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

pain001-lsp

Language Server for the payment-data records that drive generation

You author or review those records in an editor: this package

pain001-mcp

Model Context Protocol server exposing the library as agent tools

You work with payment data from an AI assistant

pain001-loader-mt101

SWIFT MT101 requests for transfer to pain.001 flat records

Your transfers still arrive as MT101

pain001-loader-xlsx

Excel .xlsx reader for flat-record payment data

Finance teams keep payments in a spreadsheet

pain001-mockbank

Synthetic SFTP bank-response test service

Generate pain.002 replies in integration tests

pain001-plugin-template

Cookiecutter plugin scaffold

Develop an external loader or validator

pain001-fast

Experimental native validation extension

Optional IBAN, BIC and character-set helpers

pain001.com

Website and browser demo

Browse documentation and try the library

pain001-sdk-go

Go client for the REST API, tested with the conformance kit

Call the REST API from Go services

pain001-sdk-java

Java client for the REST API, tested with the conformance kit

Call the REST API from JVM applications

pain001-sdk-rust

Rust client for the REST API, tested with the conformance kit

Call the REST API from Rust programs

pain001-sdk-dotnet

.NET client for the REST API, tested with the conformance kit

Call the REST API from .NET applications

pain001-sdk-cpp

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)

.csv documents checked by the core’s CSV diagnostic engine, with per-cell ranges

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 id

Released

Formatting

Whole-document pretty-print, 2-space indent, idempotent

Released

Example corpus

pain001.corpus.list and pain001.corpus.get commands

Released

Faces

pain001.faces.list and pain001.faces.project commands (pain001 0.0.78)

Released

Targeted fixes per diagnostic, code lenses

See ROADMAP.md

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

pain001 library from a script

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_IBAN and the *_agent_BIC fields 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 description of 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>), with payment_id as 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.list lists the validated example files the core ships (filter by kind, country, version); pain001.corpus.get returns one file’s XML with its provenance.

  • Faces commands (pain001 0.0.78): pain001.faces.list names each face and the binding keys it accepts; pain001.faces.project takes {"xml", "face", "version"?, "bindings"?} with the open buffer’s text as xml and 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

messageType

initializationOptions

Message type to validate against at startup (default pain.001.001.09).

pain001.messageType (or messageType)

workspace/didChangeConfiguration

Switch the message type without a restart.

pain001.serverCommand

VS Code setting

Command that starts the server (default pain001-lsp).

pain001.messageType

VS Code setting

Message type, one of the thirteen the core supports.

pain001.filePattern

VS Code setting

Glob of the JSON files sent to the server (default **/*.json); **/*.pain.json, for example, keeps completion, hover and formatting out of other JSON files.

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

01_lsp_helpers.py

Diagnostics, completion and hover on sample records

02_quick_fix.py

The missing-fields quick fix and the snippet it inserts

03_configure_message_type.py

Overriding the message type through initializationOptions

04_corpus_commands.py

The example-corpus commands

05_faces_commands.py

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 validate and the core’s REST API.

  • You are authoring pain.001 XML. 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:

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.