Upgrade version of `libxmljs2` used to bring in line with Dashboard validation

[simon-20]

Brief Description
The Validator API (this repo) uses libxmljs2 to do XML parsing and schema validation, but it is using a version which is several years old and fails to catch some schema validation problems. This means the validation results reported by the Validator and the Dashboard (which has its own validation process) diverge, which is confusing.

The task here is to upgrade libxmljs2 (or switch library, if needed) to bring the validation results in line with each other.

Associated issues:

IATI/validator-web#1002
IATI/IATI-Dashboard#845

Severity
High

[arobson-ods]

The latest version of libxmljs2 wraps 2.9.9 version of libxml2 which the same version of the library that our current libxmljs2 uses. So bumping to the latest won't help. In any case libxmljs2 is no longer maintained (2024).

We can replace it with libxml2-wasm to bring the libxml2 version in sync with the one used by lxml 6.0.2.
It would require code changes.

[arobson-ods]

Recording reasoning behind selecting libxml2-wasm for future reference ...

The reported case with publisher aics: <value value-date="2026-01-01"> - </value>, a sign-only xs:decimal with surrounding whitespace - is accepted by libxml2 ≤ 2.12 but rejected from 2.13.0 onward.

libxmljs2 is no longer maintained and its last release bundles libxml2 2.9.9, so it will need to be replaced by a new library.

IATI-Stats Validator is built with Python lxml v6.0.2, which uses libxml2 2.14.6 ([PyPI](https://pypi.org/project/lxml/6.0.2/)).

Assume we want to stick with libxml2 rather than switching to a pure JS implementation.

Selected candidate library

libxml2-wasm (jameslan/libxml2-wasm)
Actively maintained, libxml2 compiled to WebAssembly rather than native bindings. Supports parsing, validation, XInclude/XSD include. Kept reasonably current.

The nearest version match is v0.6.0, which wraps libxml2 2.14.5 — one patch release behind our lxml target of 2.14.6. Going with the latest libxml2-wasm release (libxml2 2.15.1) is also an option but on balance think we should match lxml as closely as possible at least on first pass.

Verified consistent with lxml in flagging errors in the aics-org.xml test case. Impact on the existing codebase likely manageable. WASM is less fragile than native bindings, since it avoids the prebuilt-binary/toolchain-per-platform dependency. Some risk of performance degradation relative to the native-binding libxmljs2.

Other (rejected) candidates

xmllint-wasm (noppa/xmllint-wasm)
Also wraps libxml2 via WASM, but exposes the xmllint CLI interface rather than a document API - node-oriented for validation runs rather than programmatic tree manipulation. Each validation spawns a new Worker thread and WASM instantiation, adding per-call overhead. Rejected primarily because integrating this API shape into js-validator-api would be a full redesign rather than an incremental swap, and would require benchmarking to justify.

node-libxml (MatthD/node-libxml)
Native bindings, bundles libxml2 so no system dependency, but native bindings mean prebuilt binaries per Node/OS/arch combination, with the usual risk of falling back to a local compile if a prebuilt isn't available. Closer in spirit to libxmljs2 than the selected library libxml2-wasm, but the latest release is two years old and ships with libxml2 version 2.9.0 - well below the fix line, and a regression on the library we are replacing.

[simon-20]

This looks great @arobson-ods, very thorough.

I had an AI agent run the IATI XML files in this repo's test corpus through libxml2-wasm version 0.6 and version 0.7, and they produced the same results.

I think we should go for version 0.7, even though 0.6 gives a closer match to the Dashboard as of today. Version 0.7 includes security fixes that aren't present in the version of libxml that is packaged in 0.6, and since the Dashboard is under active development, it's likely the underlying version of libxml it uses will be upgraded before long anyway.

One other thing the move to libxml2-wasm will need to be careful of is that libxml2-wasm requires explicit use of dispose() to free resources, as it doesn't have a GC heap.

[arobson-ods]

Thanks @simon-20. I have a test harness checking libxml2-wasm 0.6 and 0.7 against lmxl and all three are consistent over a set of sample data. So 0.7 probably is best. Unfortunately we can't use the Javascript using keyword to manage resources in node 20 and will have to employ a try/finally as per the libxml2-wasm docs. Something to consider changing when we do the upgrade to node 24.

[simon-20]

@arobson-ods, support for Node 20 ended in April 2026, so this does need upgrading to at least Node 22, but Node 42 probably better if possible. So if you think it may make things easier, that could be done first.

It'd be best to put the Node upgrade through as a separate PR first, then address this. There are high priority issues on the MM board covering the Node upgrade.

[arobson-ods]

@simon-20 I think we should do the library upgrade and fix the aics bug first, then assess what's needed for Node. Our current libxmljs2 is stuck on Node v20, so upgrading Node first would mean upgrading the library twice - once to bring libxmljs2 current, then again to migrate to libxml2-wasm. Guess the first change is trivial (no code changes) but may as well skip it as we can.

I've confirmed libxml2-wasm runs on Node up to v24 (haven't yet worked out what else the Node upgrade needs, or what version to target). So I see the library upgrade as a first step on the Node migration path.

[arobson-ods]

@simon-20 btw, have a slightly fuller picture now on possible performance implications of changing the libraries. libxml2-wasm compiles the XSD once into a reusable validator object, whereas libxmljs2 recompiles it inside every validate() call — and since we validate one activity at a time, that's currently a full schema compilation per activity. I suspect this means the upgraded validator will actually perform better than the current one but don't have any benchmarking to back that up yet.