An E-Invoice Conformance Engine That Reads PDFs

E-invoicing is going mandatory across the EU. Every public buyer in Europe already has to accept invoices in the EN 16931 semantic model, and Germany has begun phasing in mandatory B2B e-invoicing built on the same standard. The format turns out to be the easy part. The hard part is proving a given invoice actually conforms — that every business rule holds, every code comes from the right list, and every conditional field is present exactly when the standard says it must be. That is what this engine does.

🧾 What EN 16931 Actually Is

EN 16931 defines a semantic data model for the core invoice — roughly 160 business terms (an invoice number, a seller VAT identifier, a line net amount) — plus a long list of business rules that constrain them. The rules come in families:

• BR-xx — structural rules, e.g. “an Invoice shall have an Invoice number.”
• BR-CO-xx — calculation rules, e.g. “the sum of line net amounts shall equal the invoice line net total.”
• BR-CL-xx — code-list rules, e.g. “the currency shall be coded with ISO 4217.”
• BR-S / BR-Z / BR-E / BR-AE … — the VAT-category rules that make totals and exemption reasons hang together.

The same model is carried in two XML syntaxes: UBL (OASIS) and UN/CEFACT CII (the Cross Industry Invoice). A conformance engine has to speak both, because a supplier can send you either.

🔬 Clean-Room Rules, Differential-Tested

The official validation artefacts ship as Schematron — XSLT-driven assertions that are authoritative but heavy to run and awkward to embed in a pipeline. Rather than shipping the Schematron, the engine implements each business rule as a small, direct check over a parsed invoice.

To be sure those checks match the reference exactly, every rule is differential-tested: a corpus of valid and deliberately-broken invoices is run through both the official Schematron and this engine, and the pass/fail verdicts have to agree rule-for-rule. A rule is not considered done until its verdicts line up with the Schematron on every fixture — that is the whole point, and it is what keeps the clean-room implementation honest.

🇩🇪 XRechnung: The German Layer on Top

EN 16931 is the floor; countries tighten it with a CIUS (Core Invoice Usage Specification). Germany’s is XRechnung, which adds its own BR-DE-xx rules on top of the European base — a buyer reference (Leitweg-ID) becomes mandatory, seller contact details are required, and several fields EN 16931 leaves optional are promoted to required. The engine layers those national rules over the EN 16931 core, so you can validate against plain EN 16931 or the stricter XRechnung profile with the same tool.

📄 Reading the Invoice Out of a PDF

Here is the part people do not expect. Factur-X (France) and ZUGFeRD (Germany) are hybrid invoices: an ordinary, human-readable PDF/A-3 that carries the full structured invoice XML embedded as an attachment inside the PDF. The visible page is for a person; the embedded factur-x.xml / zugferd-invoice.xml is for a machine.

So the engine takes a PDF, pulls the embedded XML out of the PDF/A-3 attachment table, and validates that. In practice this means you can drop in the exact file a supplier emailed you and get a machine verdict — no separate XML export, no copy-paste, no “can you also send the XML?” round-trip.

✅ SARIF and a CI Gate

Findings come out as SARIF — the Static Analysis Results Interchange Format. SARIF is what GitHub reads to draw inline annotations, so a failing rule shows up right on the offending line instead of buried in a log. Packaged as a GitHub Action, the engine becomes a conformance gate: open a pull request that changes an invoice template, and if the output stops conforming, the check turns red before the invoice ever reaches a customer or a tax authority. The same binary runs locally and self-hosted — there is no service to call and nothing leaves your machine.

⚠️ Honest Limits

• Conformance, not truth. It can tell you the totals are internally consistent and the codes are valid; it cannot know that your VAT rate is the commercially correct one for the transaction.
• Scope is EN 16931 + XRechnung. Other national profiles — Peppol BIS, France’s CIUS, Italy’s FatturaPA — are their own rule layers and are out of scope for now.
• PDF extraction targets Factur-X / ZUGFeRD. A scanned PDF with no embedded XML has nothing structured to validate — there is simply no invoice data in it to check.

🧰 Why Build It This Way

Conformance tooling today is usually one of two things: a large Java Schematron runner, or a paid SaaS you upload your invoices to. Neither fits a CI pipeline that wants to stay fast, offline, and auditable. A small engine with clean-room rules — differential-proven against the reference, able to read the PDFs suppliers actually send, and speaking SARIF so the results land where developers already look — drops into a build with no drama. That is the whole design goal: make “is this invoice conformant?” a green check, not a project.

— DankDev

---

Tags: E-Invoicing · EN 16931 · XRechnung · Factur-X · SARIF · GitHub Actions

← Back to all posts