oxml-lsp 0.0.11

Status: a language server for diagnostics

oxml-lsp --stdio speaks the Language Server Protocol, for the one thing this crate does well: diagnostics. An editor starts it, opens a document, and gets positioned squiggles as it types.

What it does not advertise: completion, hover, formatting, go-to-definition, schema validation. Announcing a capability and returning nothing is worse than staying quiet — an editor that believes the announcement stops offering its own fallback.

The command-line linter is unchanged and still the right tool for CI or a Makefile.

Getting started

What it does today — diagnostics over LSP, a linter, and a library
Install — Cargo, from source
Quick Start — lint a file in one line

The oxml ecosystem

The oxml ecosystem — seven crates, one version

Reference

Library API — analyse() and Diagnostic
Diagnostics — what is reported, and at what severity
Exit status — and why it matters in a pipeline
Design — positions, severities, and what is deliberately absent
Roadmap — what comes after the transport
Ecosystem comparison — and when to use lemminx instead
Benchmarks — latency per document, which is what an editor feels

Practical

Examples — the linter and the library
When not to use oxml-lsp
FAQ
Development
Security
Documentation
Acknowledgements
License

What it does today

A library. analyse(&str) -> Vec<Diagnostic>, each with a severity, a line and column, a message and a stable code.
A command-line linter. Reads a file or standard input, prints diagnostics, exits non-zero if any is an error.
A language server. oxml-lsp --stdio implements initialize, the textDocument open/change/close lifecycle, and pushes publishDiagnostics after every edit.

What it does not do: completion, hover, formatting, go-to-definition, or schema validation.

Install

cargo install oxml-lsp --version 0.0.11 --locked

As a library:

[dependencies]
oxml-lsp = "0.0.11"

Quick Start

$ oxml-lsp config.xml
3:13: error: at byte 39: </hostname> closes <port> [not-well-formed]

$ oxml-lsp valid.xml
no diagnostics

Reads standard input when given no file, so it composes:

curl -s https://example.com/feed.xml | oxml-lsp
find . -name '*.xml' -print0 | xargs -0 -n1 oxml-lsp

The oxml ecosystem

Crate	What it is
`oxml`	The library: parser, tree, XPath 1.0
`xmlschema`	XSD validation
`oxml-cli`	The command line
`oxml-wasm`	WebAssembly bindings
`oxml-mcp`	Model Context Protocol server
`oxml-lsp`	This crate — diagnostics
`oxml-json`	JSON support for the language server

All seven ship one version number, in steps of 0.0.1.

Library API

use oxml_lsp::{Severity, analyse};

let diagnostics = analyse("<a><b></a>");
assert_eq!(diagnostics.len(), 1);

let d = &diagnostics[0];
assert_eq!(d.severity, Severity::Error);
assert_eq!(d.code, "not-well-formed");
// Positions are zero-based, as LSP requires.
assert_eq!(d.start.line, 0);

Item
`analyse(source) -> Vec<Diagnostic>`	Every diagnostic for a document
`Diagnostic`	`start`, `end`, `severity`, `message`, `code`
`Position`	`line`, `character` — zero-based, as LSP requires
`Severity`	`Error`, `Warning`, `Information`, `Hint` — numbered as LSP numbers them

Both are shaped for the transport: positions are zero-based and Severity's discriminants are LSP's numbers, so the layer is a cast rather than a conversion.

The command-line front end adds one to both before printing, because a person counting lines starts at one.

Diagnostics

One per document, at most, today. A parse failure stops the parse, and continuing past one produces cascades of diagnostics that are all consequences of the first — an editor showing eleven squiggles for one missing > is worse than one.

Positions in the library are zero-based, as LSP requires. The command line prints them one-based, because that is how a person counts.

Either way the character offset is counted in characters, not bytes, so a multi-byte character earlier on the line does not shift it.

Code	Meaning
`not-well-formed`	The document violates a well-formedness rule

The code is stable and is what you match on. The message is human-facing and may be reworded.

Exit status

Code	Meaning
0	No errors
1	At least one error
2	Could not read the file or standard input

The distinction between 1 and 2 matters in a script: "this document has a problem" and "you gave me a path that does not exist" need different responses, and a tool that returns 1 for both makes set -e a liability.

Design

The analysis is a library, not a binary. analyse() takes a &str and returns owned diagnostics. No I/O, no protocol, no global state — so it is testable without an editor, and the CLI and the LSP transport are both thin layers over the same function.

No error recovery. The parser stops at the first well-formedness violation. Recovery means guessing what a malformed document meant, and two implementations guessing differently is how an editor and a build tool come to disagree about a file.

Positions come from the parser's byte offsets. oxml returns an offset rather than a formatted message precisely so that a consumer can turn it into whatever it needs — a line and column here, a caret elsewhere, an LSP Range later.

Roadmap

In the order it makes sense to build:

Done in 0.0.8: the LSP transport — initialize, shutdown, exit, textDocument/didOpen, didChange, didClose and publishDiagnostics, framed with Content-Length over stdio.

Next, in the order it makes sense to build:

Incremental sync, so a large document is not reparsed on every keystroke. Sync is currently full-document.
Schema-aware diagnostics via xmlschema, which is where validity errors rather than well-formedness errors come from.
Completion from a schema.

Steps 2 and 3 are why the analysis is a library: they add diagnostic sources, not a new front end.

Ecosystem comparison

	Language	Diagnostics	Schema validation	LSP transport
`oxml-lsp`	Rust, no `unsafe`	✅ well-formedness, duplicate attributes, empty elements	✗ — use `oxml-cli validate` or `xmlschema`	✅ diagnostics only
`lemminx`	Java	✅	✅ XSD and DTD	✅
`vscode-xml`	Java (`lemminx` underneath)	✅	✅	✅

The honest summary: lemminx remains the more complete server. It validates against XSD and DTD, offers completion and hover, and has years of editor integration behind it. This crate serves diagnostics and says so in its capabilities rather than advertising more.

What it offers instead is a Rust dependency with no JVM, no unsafe, and a linting pass fast enough to run on every keystroke — see Benchmarks.

Benchmarks

cargo bench --bench analyse

An editor calls analyse() on every keystroke, so the figure that matters is not throughput on a large file but latency on a small one. A language server that takes 20 ms to lint a 4 KB buffer feels slow in a way that a batch parser doing the same work does not.

Document	Time
small, 10 entries	0.017 ms
editor buffer, 200 entries (18 KB)	0.31 ms
large, 5,000 entries (480 KB)	9.2 ms
mid-edit, unclosed tag	0.24 ms
not well-formed	0.002 ms

From one run on an Apple Silicon laptop that was not idle. These describe the machine as much as the code; compare runs, not numbers. See oxml's BENCHMARKS.md for the method and the conditions a figure has to carry.

The benchmark earned its place: it is what found analyse() being quadratic in the number of attributes, which cost 1,088 ms on a document that now takes 9.5.

Examples

examples/ asserts its output, so the invocations in this README fail CI when they stop being true.

Example	What it shows
`lint.sh`	Files, standard input, exit codes
`library.rs`	`analyse()` and every field of a `Diagnostic`
`lint_a_document.rs`	What an editor integration calls: lint, then read the diagnostics

When not to use oxml-lsp

You want completion, hover or formatting. It serves diagnostics and nothing else. Use lemminx (Java) or vscode-xml.
You need schema validation. Use oxml-cli validate or xmlschema directly.
You need formatting. xmllint --format.
You need every error, not the first. There is no recovery.

FAQ

Is it a language server?

Yes, since 0.0.8. It speaks LSP over stdio: initialize, shutdown, exit, textDocument/didOpen, didChange, didClose and publishDiagnostics, with Content-Length framing.

Sync is full-document rather than incremental, which is correct but reparses on every keystroke; that is the next thing on the roadmap. The linter and the library remain, and all three are thin layers over the same analyse().

Can I use it in CI now?

Yes — that is the useful part today:

- run: find . -name '*.xml' -print0 | xargs -0 -n1 oxml-lsp

Exits non-zero on the first malformed document.

Why only one diagnostic per document?

Because the parser stops at the first violation, and a recovering parser produces cascades where every diagnostic after the first is a consequence of it. One accurate diagnostic beats eleven guesses.

How do I get diagnostics for schema violations?

Not from here yet. Use oxml-cli validate schema.xsd doc.xml.

Are the positions LSP-compatible?

The stdio transport sends zero-based UTF-16 ranges, LSP's mandatory default encoding, including for emoji and other non-BMP characters. The native Position API continues to count Unicode scalar values; the conversion is isolated at the transport boundary. Severity uses LSP's numeric values directly.

Does it fetch anything?

No. No network code, and external entities are never dereferenced.

Which editors work with it?

Editors that can launch a stdio language server can use oxml-lsp --stdio for diagnostics. Completion, hover and schema validation are not advertised.

Development

./scripts/gate.sh

That runs everything CI runs, in the order that fails fastest: format, clippy, tests, rustdoc, the #![forbid(unsafe_code)] check, the examples, the 95% coverage floor and an MSRV build. It pins the toolchain rather than trusting rust-toolchain.toml, because a RUSTUP_TOOLCHAIN in the environment silently overrides that file and a lint that exists in one release and not another then makes a green local run and a red CI one.

The individual steps, if you want them one at a time:

cargo test --all-features
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --all --check
cargo bench --bench analyse
OXML_LSP="$PWD/target/release/oxml-lsp" ./examples/lint.sh
cargo run --example library
cargo run --example lint_a_document

CI runs the same set on Linux, macOS and Windows.

Security

Scorecard scans use a digest-pinned upstream image. Results are retained as CI artifacts and repository posture findings in GitHub code scanning, not published to Scorecard's public service. The badge shows workflow status, not a security score; a successful scan can still report findings.

No network access. External entities never dereferenced, so a document cannot make the linter read /etc/passwd. Entity expansion and recursion bounded. Analysis uses the strict core profile, including an 8 MiB document limit. LSP headers are capped at 8 KiB and message bodies at 16 MiB before body allocation. #![forbid(unsafe_code)].

See https://github.com/sebastienrousseau/oxml/blob/main/doc/SECURITY-MODEL.md.

Documentation

Acknowledgements

oxml-lsp exists because of work that came before it:

lemminx — the XML language server this one is measured against, and the reference for what an editor integration should offer.
Microsoft — for the Language Server Protocol specification.
lxml and libxml2 — decades of hard-won correctness, and the yardstick for behaviour.

License

Licensed under either of Apache-2.0 (LICENSE-APACHE) or MIT (LICENSE-MIT), at your option.