ESJ: EN 16931 als JSON

Wer Software baut, in der Rechnungen entstehen oder ankommen, kommt an der EN 16931 nicht vorbei. Die Norm legt fest, was eine elektronische Rechnung enthält: 164 Geschäftsterme in 32 Gruppen, von BT-1, der Rechnungsnummer, bis zu den Positionen in BG-25. Sie legt aber nicht fest, wie diese Terme in einer Datei stehen. Dafür gibt es zwei XML-Syntaxen, UBL und CII, und darauf aufsetzend die in Deutschland üblichen Profile XRechnung und ZUGFeRD beziehungsweise Factur-X. Vier Namen, eine Rechnung.

In der Praxis bedeutet das: Jede Anwendung baut sich ihr eigenes internes Rechnungsmodell, konvertiert aus jeder Syntax hinein und zum Versenden wieder heraus. Und mit der Ausgabe EN 16931:2026 kommen neue Felder, neue Gruppen und neue Regeln, die auf jedem dieser Wege nachgezogen werden müssen. Das ist der Moment, in dem Entwickler über Kündigung nachdenken – jedenfalls in unserem Video.

Ein Modell statt vier Wege

ESJ steht für EN 16931 Semantic JSON. Die Idee ist einfach: Die Rechnung wird als flaches JSON abgelegt, in dem der Schlüssel der Pfad des Geschäftsterms in der Norm ist und der Wert genau das, was die Norm dort vorsieht – ohne Syntax dazwischen.

{
  "format": "EN16931-Semantic-JSON",
  "version": "0.1",
  "semanticModel": "EN16931-1:2017+A1:2019/AC:2020",
  "values": {
    "/BT-1": "RE-2026-0042",
    "/BT-2": "2026-09-22",
    "/BG-4/BT-27": "Example GmbH",
    "/BG-25/0/BT-131": "1200",
    "/BG-22/BT-112": "1535.1"
  }
}

Eine Rechnung, die als UBL ankommt, und dieselbe Rechnung als CII ergeben dasselbe ESJ-Dokument – mit demselben kryptografischen Digest. Die Anwendung speichert, indiziert, vergleicht und prüft die Rechnung im Modell der Norm; UBL, CII, XRechnung und ZUGFeRD bleiben das, was sie sind: Transportformate, die beim Lesen und Schreiben an der Grenze der Anwendung bedient werden.

EN 16931 definiert die Rechnung. ESJ macht sie für Software direkt benutzbar.

Das Video

Zwei Minuten, im Retro-Look, weil das Thema sonst so trocken ist wie ein Schematron-Report. Max muss „nur“ E-Rechnungen unterstützen, Lena zeigt ihm, wie es geht. Alles, was auf dem Bildschirm zu sehen ist, ist echte Ausgabe der Version 0.9.1 – einschließlich der Datenbank.

Video auf Deutsch   Video in English

Die Links führen zu YouTube; wir betten hier bewusst keinen Player ein, damit diese Seite ohne Fremdskripte auskommt.

Was in der Version 0.9.1 steckt

• Lesen und konvertieren: UBL 2.1, CII D16B, XRechnung und hybride PDFs (ZUGFeRD/Factur-X) werden zu ESJ; ESJ wird zurück zu UBL oder CII geschrieben.
• Prüfen: die offiziellen XSD- und Schematron-Artefakte von CEN und KoSIT werden als Daten ausgeführt, die Geschäftsregeln der EN 16931 zusätzlich nativ über das Modell; dazu Containerprüfung für PDFs und ein Prüfbericht als PDF oder HTML.
• Rendern: HTML, PDF/A-3 mit eingebetteter Factur-X und dem ESJ-Dokument, wahlweise als Geschäftsbrief mit eigenem Briefpapier und GiroCode.
• Speichern: als JSONB in PostgreSQL, mit Views und Indizes auf die Geschäftsterme – jedes SQL-Beispiel der Dokumentation läuft im Test gegen ein echtes PostgreSQL.
• Erzeugen: eine Java-API in den Begriffen der Domäne – Verkäufer, Käufer, Positionen, Umsatzsteuer –, die Summen ableitet und verweigert, was die Norm nicht zulässt. Wer damit arbeitet, muss kein XML und keine BT-Nummern kennen.
• Für alle anderen Laufzeiten: das Kommandozeilenwerkzeug esj, ohne JDK installierbar (Homebrew, Binaries für macOS und Linux, Container-Image), dazu Bindings für TypeScript und C#.
• Ausgabe 2026: das neue Termregister der EN 16931-1:2026 ist als eigene Registry enthalten, mit einem Upgrade-Befehl von 2017 nach 2026; die offiziellen Prüfartefakte dafür gibt es noch nicht, und das sagt das Werkzeug auch so.

Warum Open Source

Wir haben ESJ gebaut, weil wir es in eigener Software brauchen. Als Format taugt so etwas aber nur, wenn es offen ist – ein Rechnungsmodell, das nur ein Hersteller versteht, wäre genau das Problem, das wir loswerden wollten. Deshalb liegt ESJ unter Apache-2.0 auf GitHub: Spezifikation, Termregister, JSON-Schema, Referenzimplementierung in Java und die Konformitätsdaten, mit denen jede weitere Implementierung sich selbst prüfen kann.

Zwei Dinge sagen wir dazu deutlich. ESJ ist kein Deliverable von CEN oder KoSIT; die Norm und die offiziellen Prüfartefakte bleiben maßgeblich, und genau deshalb führt esj validate sie unverändert aus, statt sie nachzubauen. Und die Software steht bei 0.9 – ein Release Candidate, in dem das Format 0.1 unverändert zur 1.0 werden soll, wenn die Prüfung durch andere keine Fehler findet.

• github.com/bsnsoft/esj – Quelltext, Spezifikation, Dokumentation
• brew install bsnsoft/tap/esj – oder die Archive der Releases für macOS und Linux
• Maven Central: de.bsnsoft.esj (esj-bom, esj-core, esj-invoice, esj-render, esj-pdf, …)

Fehler, Fragen und Gegenbeispiele nehmen wir als Issues auf GitHub entgegen. Wer eine Rechnung hat, die ESJ anders liest als der offizielle Validator, hat unsere volle Aufmerksamkeit.