If you write software that receives invoices, someone is going to send you a file and expect you to know whether it is valid. This is a note about doing that in .NET, which until about six months ago meant running Java.

What “valid” actually involves

EN 16931 is the European standard for the semantic content of an invoice. It says nothing about file format directly; it defines around 200 business terms (BT-1 is the invoice number, BT-112 the total with VAT) and the rules between them.

A real invoice then arrives in one of two syntaxes — OASIS UBL 2.1 or UN/CEFACT CII D16B — and usually claims to follow a national profile on top of the standard. Germany has XRechnung. Peppol has BIS Billing 3.0. France and Italy have their own. So validating one invoice means, in order:

1. XML Schema. Is this structurally a UBL Invoice at all?
2. The EN 16931 business rules. BR-CO-15: does the total with VAT equal the total without VAT plus the VAT amount?
3. The national profile’s extra rules. BR-DE-15: XRechnung requires a buyer reference, which EN 16931 leaves optional.

Steps 2 and 3 are published as Schematron — a rule language where each rule is an XPath expression and a message. The publishers ship them precompiled to XSLT, which sounds like good news until you look at the header:

<schema queryBinding="xslt2" xmlns="http://purl.oclc.org/dsdl/schematron">

The reason everyone shipped a JVM

System.Xml.Xsl.XslCompiledTransform implements XSLT 1.0. Only XSLT 1.0. There has never been an XSLT 2.0 implementation in the .NET base class library and Microsoft has been clear that there will not be one.

The EN 16931 artefacts use XSLT 2.0 constructs throughout, and the German ones reach further still — Saxon’s Q{namespace}name notation shows up in the location paths they emit. There is no rewriting your way around this. You need a real XSLT 2.0/3.0 processor.

So every option involved somebody else’s runtime:

That last row is the one that mattered for the people I ended up talking to. An on-premise German accounting product cannot post its customers’ invoices to a third party for checking, and adding a JVM to a .NET deployment because of one XSLT file is the kind of thing that gets an architecture rejected.

I found a repository that captured the situation exactly: someone had created einvoice-validator in May 2026, a .NET wrapper that shells out to the KoSIT validator in Docker. The README says it wraps the reference validator “instead of implementing Peppol business rules in application code”. Two commits, zero stars, abandoned after two days. Somebody needed this, found nothing, built a Java wrapper by hand, and walked away.

What changed

SaxonCS-HE 13.0.0, released 29 May 2026 under MPL-2.0. It is a native .NET build of Saxon — not IKVM, not a Java transpile — and it is the first licence-free XSLT 3.0 processor for .NET. Before Saxon 13, SaxonCS was Enterprise-only.

That is the whole unlock. The gap was never mysterious; the thing that closed it simply did not exist until recently.

var processor = new Processor();
var executable = processor.NewXsltCompiler().Compile(new Uri(stylesheetPath));
var transformer = executable.Load30();

Compiling the 895 KB EN16931-UBL-validation.xslt takes about two seconds warm, six cold. Validating an invoice afterwards takes 27 milliseconds. That ratio is the single most important architectural fact: compile once, keep the XsltExecutable for the life of the process, and never do it per request.

Four things that will cost you an afternoon

These are the ones I lost time to. None of them are in any tutorial.

The context item is absent. Load the KoSIT stylesheets and the first transformation fails with XPDY0002. The Schematron artefacts declare global variables that select from the document root, and Xslt30Transformer does not infer a global context item from the node you pass to ApplyTemplates. You have to set it yourself:

var transformer = executable.Load30();
transformer.GlobalContextItem = input;   // not optional
transformer.ApplyTemplates(input, destination);

XmlSchemaSet will not compile the UBL schemas the obvious way. XmlResolver is null by default on modern .NET, so xsd:import resolves to nothing and compilation fails. Set a resolver and it fails differently: the UBL modules reference each other’s prefixes without always importing them, and following imports as well as adding files loads some namespaces twice.

What works is to add every module explicitly with resolution turned off:

var set = new XmlSchemaSet { XmlResolver = null };
var settings = new XmlReaderSettings { DtdProcessing = DtdProcessing.Parse, XmlResolver = null };

foreach (var name in schemaFiles)
{
    using var reader = XmlReader.Create(name, settings);
    set.Add(XmlSchema.Read(reader, null));
}

set.Compile();

DtdProcessing.Parse is needed because the xmldsig core schema declares an internal DTD of entities. Invoices themselves are still read with DTDs prohibited outright — that is a different trust boundary.

Do not tidy the XML. I spent an evening on a rule that fired locally and not in the official test suite. The cause was XDocument.ToString(), which pretty-prints by default. Indenting a fragment inserts whitespace text nodes, which changes the string value of elements, which silently flips any rule that measures content length. SaveOptions.DisableFormatting fixes it. For the same reason, do not strip comments or processing instructions: a validator has to judge the document as it arrived.

A Schematron location is the rule’s context, not the value. When I started reporting the offending value alongside each finding, I resolved the location XPath and took its string value. For BR-CL-04 — an invalid currency code — that gives you "XYZ", which is exactly what you want. For BR-CO-15, which compares three totals, the location is /Invoice and the string value is every scrap of text in the entire document. Adding [not(*)] to the XPath, so only leaf nodes report a value, was the difference between a useful field and an unusable one.

Proving it, rather than asserting it

Anyone can run a Schematron file and print the output. The interesting question is whether your verdicts match the verdicts that matter.

Two things settle it.

CEN publishes a test suite: 309 files, each targeting one rule, each declaring which rules must fire and which must not. Replaying every expectation proves agreement per rule rather than in aggregate. It also turned up something I would not have guessed — CEN ships test files for BR-CO-25 while its own Schematron never implements that rule. My test suite pins that exact set, so the day CEN adds it, the build says so.

Then, because Germany is the market, I run KoSIT’s own validationtool over the same invoices in CI and diff the rule ids against mine. Same scenario configuration release on both sides — read from my manifest, so it cannot drift onto a different version and produce disagreements that mean nothing.

comparing 143 files against itplr-kosit/validator@v1.6.3
100/100 comparable files agree rule for rule with the reference validator (43 not comparable)

The 43 are recorded with the reason each cannot be compared, usually that the XRechnung configuration matched no scenario for that file. A report with no matched scenario is the reference declining to judge, which is not the same as judging clean, and counting those as agreement would have inflated the number for nothing.

Java runs the reference. It is not needed to use the library — CI keeping a JDK around to check my work does not change that.

Where the artefacts live

One design decision worth explaining, because it looks like an inconvenience.

The rule artefacts are not in the package. The CEN rules are EUPL-1.2, the KoSIT configurations are Apache-2.0, and they are not mine to redistribute. So the package embeds a manifest naming every artefact, its upstream release tag, its licence and its SHA-256, and downloads them on request:

klarfakt rules restore

That runs once — at deployment, or in a Docker build stage so the running container never reaches the network. Nothing else in the library makes a network call. A pack is checked against the manifest the first time it is used, so an artefact altered on disk stops validation rather than quietly changing a verdict.

Where this leaves things

Validating an EN 16931 invoice in .NET is now an ordinary problem. No JVM, no Node process, no uploading a customer’s invoice to somebody else’s API. The library I built is Klarfakt — free below €1,000,000 of annual revenue and free inside OSI-licensed open source, €690 a year above that — but the more useful thing in this post is probably the four gotchas, which apply to anyone running Schematron on .NET regardless of what they build with it.

If you are running EN 16931 validation in production some other way, I would genuinely like to hear what it cost you. That is the part nobody writes down.

%PDF-1.7
1 0 obj << /Type /Catalog /Pages 2 0 R /Names << /EmbeddedFiles 4 0 R >> >> endobj
2 0 obj << /Type /Pages /Kids [3 0 R] /Count 1 >> endobj
3 0 obj << /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] >> endobj
4 0 obj << /Kids [4 0 R] >> endobj
...

Look at object 4. Its /Kids array contains a reference to object 4.

I found this in my own code, which makes it a better story than if I had found it in somebody else’s.

Why I was walking a PDF at all

I maintain a library that reads European e-invoices. Since January 2025 every German company has to be able to receive one, and one of the formats they receive is Factur-X: an ordinary-looking PDF with the invoice also embedded inside it as XML. Human reads the PDF, machine reads the XML, one file.

To get at the XML you look in the document catalogue for /Names, then /EmbeddedFiles. What you find there is a PDF name tree — a structure that is either a leaf holding a /Names array of key-value pairs, or a branch holding a /Kids array of more nodes.

A tree. So I wrote the obvious thing:

private static void CollectNameTree(PdfDictionary node, Dictionary<string, byte[]> attachments)
{
    var names = node.Elements.GetArray("/Names");
    if (names is not null)
    {
        // ... pull out the attachments
    }

    var kids = node.Elements.GetArray("/Kids");
    if (kids is null) return;

    for (var index = 0; index < kids.Elements.Count; index++)
    {
        var kid = kids.Elements.GetDictionary(index);
        if (kid is not null) CollectNameTree(kid, attachments);
    }
}

I was pleased with this. It handles both shapes, it is short, and it reads like the specification.

It is also a straight line to a dead process, because nothing in a PDF file prevents object 4 from listing itself as its own child. The format is a graph of numbered objects that reference each other. Nobody validates that the subgraph you happen to be treating as a tree is actually a tree. The producer of the file decides what is in it, and in my case the producer is whoever emailed my user an invoice.

Stack overflow.
   at Klarfakt.Reading.PdfAttachments.CollectNameTree(...)
   at Klarfakt.Reading.PdfAttachments.CollectNameTree(...)
   at Klarfakt.Reading.PdfAttachments.CollectNameTree(...)
   ...

The part that actually stung

I had a handler. I had written it deliberately, with a comment explaining itself:

// A malformed PDF can fail anywhere inside the reader, and PDFsharp does not confine itself
// to PdfReaderException — a truncated file raises ArgumentOutOfRangeException. Callers get
// one exception type for "this file is not usable" rather than whatever surfaced.
catch (Exception exception) when (exception is not (UnsupportedDocumentException or OutOfMemoryException))

It does nothing here. Since .NET 2.0, a StackOverflowException cannot be caught. The runtime does not raise it as an exception you may handle; it terminates the process. Not the request, not the thread — the process. In a container handling a queue of inbound invoices, one crafted attachment takes down the worker and everything else it was in the middle of.

Every defensive habit I have was pointing at the wrong thing. I was thinking about what happens if the parser fails. The parser was fine. It handed me a perfectly well-formed object graph and I walked off the end of the stack myself.

The fix is not clever:

var pending = new Stack<PdfDictionary>();
var seen = new HashSet<object>(ReferenceEqualityComparer.Instance);
var visited = 0;

pending.Push(root);

while (pending.Count > 0)
{
    if (++visited > limits.MaxPdfNameTreeNodes) throw new UnsupportedDocumentException(...);

    var node = pending.Pop();
    if (!seen.Add(node)) continue;

    // ... same body as before, pushing kids instead of recursing
}

Iterative, so there is no stack to overflow. A visited set, so a cycle terminates. And a node cap, because a visited set alone still happily walks a million-node chain that isn’t a cycle at all, just long. Both guards earn their place; I tested each with its own hand-built file.

Then I found the second one

Feeling thorough, I went looking for the same class of problem elsewhere, and found it about ten metres away.

The library has a configurable cap on attachment size. Sensible. Here is how it was applied:

var bytes = content?.Stream?.UnfilteredValue;

if (bytes.LongLength > limits.MaxAttachmentBytes)
{
    throw new UnsupportedDocumentException($"The attachment is {bytes.LongLength:N0} bytes...");
}

UnfilteredValue is PDFsharp’s “give me the decompressed bytes” property. So the check reads: allocate the entire attachment, then decide whether we were willing to allocate it.

Embedded files in a PDF are usually Flate-compressed. Deflate tops out around 1000:1 on repetitive input. I generated a 261 KB PDF whose attachment expands to 256 MB, and the library dutifully allocated all 256 MB before refusing it:

The attachment 'factur-x.xml' is 268,435,456 bytes, over the 33,554,432 byte limit.

It knows the exact size. That is how you can tell it paid for it.

Scaling up, a 2.6 MB file produced a 2.5 GB attachment and died differently — IOException: Stream was too long, because .NET refuses to grow a MemoryStream past about 2 GB. Which is a kind of accidental safety net, if your definition of safe includes a two-gigabyte allocation on a machine that may only have four.

The fix was to stop using the convenient property and inflate it myself, a block at a time, checking as I go:

while ((read = inflater.Read(chunk, 0, chunk.Length)) > 0)
{
    if (buffer.Length + read > limits.MaxAttachmentBytes) throw TooLarge(...);
    buffer.Write(chunk, 0, read);
}

Both bomb files now stop at 33.5 MB. They also finish faster than before — 1.2 seconds instead of 5.5 — because nothing large is ever materialised. That is usually a sign the earlier version was doing something silly.

One caveat I left in deliberately: this path only handles plain Flate with no decode parameters, which is what every hybrid invoice in my test corpus uses. Anything more exotic — a predictor, a chain of filters — still goes through PDFsharp with the check afterwards. Guessing wrong about an unusual filter would mean failing to read a legitimate invoice in order to save memory, and that is the wrong trade for a compliance tool.

What I took from it

A limit you check afterwards is not a limit. It is a report. If the expensive thing has already happened by the time you test the condition, you have written an assertion, not a guard.

Know which exceptions your runtime will not let you catch. StackOverflowException is the obvious one and it is genuinely different from everything else in .NET: no catch, no finally, no AppDomain.UnhandledException. If untrusted input can reach recursive code, the recursion is the bug, not the missing handler.

“It’s a tree” is an assumption about the producer, not the format. PDF, XML with entity references, JSON with $ref, protobuf with recursive messages — in every case the shape you are relying on is a convention the sender can decline to follow. My name-tree walker was correct for every file produced by software that wasn’t trying to hurt me.

Test the guard, not the happy path. Both of these were found by sitting down and writing files specifically designed to break my own code: a self-referencing node, a two-node cycle, a node that is its own grandchild, a 6,000-node chain, and two compression bombs. All of them are in the test suite now. None of them would have appeared in any corpus of real invoices, which is exactly why 521 files of real corpus told me nothing about either bug.

The library is Klarfakt, if you want to see the fixes in context. But the two mistakes are not specific to PDFs or to e-invoicing, which is why I wrote this instead of a release note.