DEV Community: chenhao5721865

Validating Factur-X / ZUGFeRD e-invoices in practice: XSD + Schematron

chenhao5721865 — Sat, 10 Oct 2026 14:48:02 +0000

If you build software for European businesses, the clock is ticking: France makes B2B e-invoicing mandatory from September 2026 (reception first, then issuance), and Germany follows in January 2027. Both mandates are built on the same foundation — the European standard EN 16931 — and both use hybrid formats (Factur-X in France, ZUGFeRD in Germany) that embed a structured XML file inside a human-readable PDF.

I recently built an e-invoicing API around this, and learned the hard way that "the file is valid XML" is nowhere near enough. This post is what I wish someone had told me before I started.

What a Factur-X invoice actually is

A Factur-X file is a regular PDF with an XML attachment (usually factur-x.xml) embedded via the PDF/A-3 association mechanism. The PDF is for humans; the XML is for machines. The XML follows the UN/CEFACT CII syntax (Cross Industry Invoice) — the other allowed EN 16931 syntax is UBL, used by XRechnung.

So validating one involves three distinct steps:

Extract the embedded XML from the PDF
Check the XML against the XSD (structure, data types)
Check it against the Schematron business rules (the BR-* rules from EN 16931)

Skip step 3 and you'll accept invoices that any compliant receiver will reject.

Step 1: Extracting the XML with PDFBox 3

try (PDDocument doc = Loader.loadPDF(pdfBytes)) {
    PDDocumentNameDictionary names = doc.getDocumentCatalog().getNames();
    PDEmbeddedFilesNameTreeNode efTree = names.getEmbeddedFiles();
    Map<String, PDComplexFileSpecification> files = efTree.getNames();
    // Factur-X attaches "factur-x.xml"; ZUGFeRD uses "zugferd-invoice.xml"
    for (var entry : files.entrySet()) {
        PDEmbeddedFile ef = entry.getValue().getEmbeddedFile();
        byte[] xml = ef.toByteArray();
        // ...
    }
}

Two gotchas here:

Not every PDF has attachments. A plain PDF invoice (what most French suppliers still send today) will come back with an empty map — that's a 422, not a validation failure.
Don't trust the file extension or Content-Type header. Check magic bytes (%PDF- for PDF, < for raw XML) — clients upload mislabeled files constantly.

Step 2: XSD validation

The EN 16931 CII schema is based on the UN/CEFACT D16B schemas. You load the XSD once and reuse the Schema (it's thread-safe; Validator instances are not, so create one per call):

SchemaFactory factory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
Schema schema = factory.newSchema(new File("Factur-X_BASICWL.xsd"));

Validator v = schema.newValidator();
v.setErrorHandler(handler); // collect, don't throw on first error
v.validate(new StreamSource(new ByteArrayInputStream(xml)));

Collect all errors instead of failing fast — users fixing invoices want the full list in one pass.

Step 3: Schematron business rules

This is the layer everyone forgets. The XSD checks structure; Schematron checks meaning. EN 16931 ships ~200 business rules like:

BR-CO-26: the seller must have a VAT identifier or a legal registration identifier
BR-07: the buyer name must be present
BR-S-05: an invoice line in VAT category "S" (standard rate) must have a VAT rate > 0

That last one is my favorite trap: vatRate: 0 with the default category S is structurally perfect XML — and completely non-compliant. Zero-rated lines must use category Z. No XSD will ever tell you that.

In Java, the practical choice is ph-schematron in "pure" mode (Schematron interpreted directly, no XSLT compilation step):

SchematronResourcePure schematron = SchematronResourcePure.fromFile("EN16931-CII-validation.sch");
if (!schematron.isValidSchematron()) throw new IllegalStateException("bad rules file");

// validate
SchematronOutputType result = schematron
    .applySchematronValidation(new StreamSource(new ByteArrayInputStream(xml)));

One caveat I hit: the applySchematronValidation* family throws or swallows exceptions depending on which overload you pick — test with malformed input, not just valid samples, or your validator will 500 on exactly the files users most need help with.

The pure implementation is thread-safe for concurrent validation (I load-tested 8 threads × 25 iterations with no failures), which matters if you're putting this behind an API.

The tooling gap

When I looked for a place to test all this, the options were surprisingly bad: the official validators are enterprise-priced or require uploading invoices to someone's portal with a signup form. So I built the thing I wanted:

Factur-X Validator — free, unlimited, no signup. Drop a Factur-X/ZUGFeRD PDF or raw XML, get the full XSD + Schematron error list with rule IDs (BR-07, etc.) and locations.

And for anyone who needs to generate compliant invoices from a SaaS rather than validate them, there's a companion API — POST /api/generate takes plain JSON (seller, buyer, line items with net prices) and returns an auto-validated EN 16931 XML. All totals (net, VAT, gross) are computed server-side so the output can't be internally inconsistent, and every generated document is round-tripped through the same validator before it's returned. 5 invoices/month free, docs at factur-x-api.com/docs.

If you're preparing for the mandate

Receiving invoices (mandatory Sept 2026 in France): you need to read Factur-X — at minimum, extract the embedded XML reliably.
Issuing invoices: get your totals chain right (net → VAT per rate → gross), pick the right VAT category codes, and validate against Schematron before sending anything. A rejected invoice in the new system isn't a bounced email — it's an unpaid invoice.

Curious what others are doing: building EN 16931 support in-house, or going through a PDP (Plateforme de Dématérialisation Partenaire)? And if you try the validator on a real invoice and hit a false positive/negative, I'd genuinely love to hear about it

I built a free Redis plugin for IntelliJ Community, here's what tripped me up

chenhao5721865 — Fri, 09 Oct 2026 02:13:28 +0000

The official Redis tooling in IntelliJ is Ultimate-only, and I use Community. The third-party plugins on the Marketplace either cost money or fall over in exactly the situations I care about: SSH tunnels, non-UTF-8 data, Remote Development.

So I wrote my own. It's called Redis Navigator, it's on the JetBrains Marketplace now, and it's completely free. No paid tier, nothing locked.

Rather than another feature list, I want to write down the bugs that cost me the most time. Maybe it saves someone an evening.

1. localhost killed the SSH tunnel, and the error blamed Redis

Jedis kept throwing:

Unexpected end of stream

I spent way too long checking Redis config, firewalls, TLS. All fine. The actual problem: JSch passes the target host string to the SSH server to resolve. My Redis host was set to localhost, the Windows OpenSSH server resolved that to IPv6 ::1, and my Redis (Memurai) only listens on IPv4. So the tunnel came up and died immediately, and Jedis reported a dead connection in the least helpful way possible.

The fix is to resolve the host to a literal IP before forwarding:

String literal;
try {
    literal = InetAddress.getByName(host).getHostAddress();
} catch (UnknownHostException e) {
    literal = host; // jump host with its own internal DNS, pass through as-is
}

If you're debugging tunnel issues: build the channel by hand with ssh -N -L, push a PING through with a raw socket, and only then test your actual client. Splitting the SSH layer from the Redis layer makes the whole thing obvious.

2. Editing a String removed its TTL

One of those Redis semantics things: bare SET clears the TTL. I knew this. I still shipped the bug and only caught it in testing.

jedis.set(key, value, SetParams.setParams().keepttl());

3. Pattern search has to drain the SCAN cursor

SCAN is cursor-based and one page is just a partial result. If your pattern search stops after one page, you're silently missing keys. It needs to loop until the cursor wraps back to 0, with some cap in case a pattern goes wild (mine bails at 50k keys). Scroll pagination is only appropriate for plain * browsing.

Two Jedis 6 things that got me: Pipeline.sync() returns void, so batch results need syncAndReturnAll(). And sscan/hscan want the cursor as byte[] while ScanResult.getCursor() hands you back a String.

4. A mojibake bug that was actually a feature request

Testing with Chinese data, everything showed up as garbage. The plugin was fine. The data was fine, technically. I had loaded my test data through a GBK console, so the GBK bytes went straight into Redis and my UTF-8 decoding did exactly what it should: display nonsense.

Then it clicked: some companies really do have GBK-era data sitting in production Redis. So per-connection charset (UTF-8 / GBK / auto-detect) went from nice-to-have to core feature. GBK data displays correctly and editing in GBK mode round-trips without corrupting anything.

Practical takeaway: load Chinese test data through a socket or script, never through a console. The other takeaway is to look at your bugs and ask whether they're someone else's daily reality.

5. Split Mode testing, blocked by someone else's bug

Remote Development support matters to me, so I tested with runIdeSplitMode from the IntelliJ Platform Gradle Plugin. The client just hung on "Connecting to remote host..." forever.

Turned out the plugin had a bug with spaces in the project path: when the backend restarts itself, it goes through a native restarter that drops the Gradle-provided sandbox config, and the new process never starts. My project lives in C:\Project Exploration\.... Direct hit.

Workaround was dumb but effective: copy the source to a path without spaces. I filed an issue upstream and JetBrains fixed it within a week, relaunching the backend via exit code instead of the restarter. Once that ships in a release I can delete the workaround.

The good news is everything in the plugin works in the JetBrains Client: tool window, JSON preview, editing, SSH tunnels, all verified in Split Mode.

If this sounds useful, the plugin is here:

Redis Navigator on JetBrains Marketplace

Bugs and feature requests go to GitHub issues. It's early days, I read everything and I respond fast.