XRechnung XML-Struktur: UBL, CII, Namespaces und XSD erklärt

Eine XRechnung ist eine XML-Datei in einer von zwei Syntaxen: UBL 2.1 mit dem Wurzelelement Invoice oder CreditNote oder UN/CEFACT CII D16B mit rsm:CrossIndustryInvoice. Ein eigenes XSD-Schema für XRechnung gibt es nicht. Gültig ist eine Datei erst, wenn sie das XSD der gewählten Syntax, die EN-16931-Schematron-Regeln und die XRechnung-Regeln der KoSIT besteht.

Stand: September 2026 · Grundlage: XRechnung 3.0.2

Dieser Beitrag richtet sich an Entwicklerinnen und Entwickler, die XRechnungen erzeugen, einlesen oder prüfen. Er zeigt beide Grundgerüste, die Namespaces, eine Zuordnung der wichtigsten Business Terms zu XPath-Ausdrücken und die Fehler, die in der Praxis am häufigsten zur Ablehnung führen. Wer zuerst wissen möchte, was XRechnung fachlich ist und wer sie verwenden muss, liest den Leitfaden „Was ist XRechnung?“. Weitere Beiträge für Entwickler sammelt die Kategorie Entwickler-Tools.

Welche Syntaxen erlaubt XRechnung?

XRechnung ist die deutsche Anwendungsspezifikation (CIUS) der Norm EN 16931. Die Norm beschreibt ein semantisches Rechnungsmodell aus Business Terms wie BT-1 (Rechnungsnummer) und Business Groups wie BG-25 (Rechnungsposition). Welches XML-Element welchen Business Term trägt, legt das Syntax-Binding fest. Davon gibt es zwei: UBL 2.1 und CII in der Version D16B. Beide sind gleichwertige Ausprägungen des Standards XRechnung.

Für die Wahl zwischen beiden gibt es keine rechtliche Vorgabe. Wer über Peppol versendet, landet meist bei UBL. Wer bereits ZUGFeRD erzeugt, hat mit CII die vorhandene Struktur. Details zu den Unterschieden stehen im Vergleich UBL vs. CII, die Abgrenzung der Formate im Vergleich XRechnung vs. ZUGFeRD.

Aktuell ist XRechnung 3.0.2; das jüngste Bundle „3.0.2 Summer 2026 Bugfix“ stammt vom 31.08.2026. Version 3.0 gilt seit dem 01.02.2024 und bleibt mindestens bis zum 31.07.2027 in Kraft. Eine Vorversion von XRechnung 4.0 hat die KoSIT im September 2026 veröffentlicht, die finale Fassung wird für das Frühjahr 2027 erwartet. Die Termine pflegt die KoSIT auf der Seite Versionen und Bundles (öffnet in neuem Tab).

Welche Namespaces braucht eine XRechnung?

Ein Namespace ist eine URI, die ein XML-Vokabular eindeutig benennt. Das Präfix davor ist nur ein lokaler Kurzname. Ein namespace-fähiger Parser vergleicht immer die Kombination aus URI und lokalem Elementnamen. <Invoice xmlns="…Invoice-2"> und <ubl:Invoice xmlns:ubl="…Invoice-2"> sind deshalb für jeden Validator dasselbe Element. Umgekehrt hilft das richtige Präfix nichts, wenn die URI auch nur ein Zeichen abweicht.

Ein Tippfehler in einer dieser URIs ist tückisch: Die Datei bleibt wohlgeformt, aber kein Schema passt mehr. Der KoSIT-Validator findet dann kein Prüfszenario und lehnt die Datei ab. Die Erklärung dazu steht unter SCHEMA-002.

Wie ist eine UBL-XRechnung aufgebaut?

UBL ist flach organisiert. Auf die Kopfdaten folgen Referenzen, die Parteien, Liefer- und Zahlungsangaben, die Steueraufschlüsselung, die Summen und am Schluss die Positionen. Die Reihenfolge ist im XSD als Sequenz festgelegt. Ein korrekt benanntes Element an der falschen Stelle ist ein Schemafehler; steht zum Beispiel cbc:IssueDate hinter cbc:InvoiceTypeCode, scheitert die Datei schon am XSD.

<?xml version="1.0" encoding="UTF-8"?>
<ubl:Invoice xmlns:ubl="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
    xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
    xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0</cbc:CustomizationID> <!-- BT-24 -->
  <cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID> <!-- BT-23 -->
  <cbc:ID>RE-2026-0815</cbc:ID>                                   <!-- BT-1 -->
  <cbc:IssueDate>2026-09-28</cbc:IssueDate>                       <!-- BT-2 -->
  <cbc:DueDate>2026-10-12</cbc:DueDate>                           <!-- BT-9 -->
  <cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>                  <!-- BT-3 -->
  <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>        <!-- BT-5 -->
  <cbc:BuyerReference>991-12345-73</cbc:BuyerReference>           <!-- BT-10 -->
  <cac:AccountingSupplierParty>…</cac:AccountingSupplierParty>    <!-- BG-4 Verkäufer -->
  <cac:AccountingCustomerParty>…</cac:AccountingCustomerParty>    <!-- BG-7 Käufer -->
  <cac:PaymentMeans>…</cac:PaymentMeans>                          <!-- BG-16 -->
  <cac:TaxTotal>…</cac:TaxTotal>                                  <!-- BT-110, BG-23 -->
  <cac:LegalMonetaryTotal>                                        <!-- BG-22 -->
    <cbc:LineExtensionAmount currencyID="EUR">1500.00</cbc:LineExtensionAmount> <!-- BT-106 -->
    <cbc:TaxExclusiveAmount currencyID="EUR">1500.00</cbc:TaxExclusiveAmount>   <!-- BT-109 -->
    <cbc:TaxInclusiveAmount currencyID="EUR">1785.00</cbc:TaxInclusiveAmount>   <!-- BT-112 -->
    <cbc:PayableAmount currencyID="EUR">1785.00</cbc:PayableAmount>             <!-- BT-115 -->
  </cac:LegalMonetaryTotal>
  <cac:InvoiceLine>                                               <!-- BG-25 -->
    <cbc:ID>1</cbc:ID>                                            <!-- BT-126 -->
    <cbc:InvoicedQuantity unitCode="HUR">15</cbc:InvoicedQuantity> <!-- BT-129, BT-130 -->
    <cbc:LineExtensionAmount currencyID="EUR">1500.00</cbc:LineExtensionAmount> <!-- BT-131 -->
    <cac:Item>
      <cbc:Name>Beratungsleistung September 2026</cbc:Name>       <!-- BT-153 -->
      <cac:ClassifiedTaxCategory>…</cac:ClassifiedTaxCategory>    <!-- BG-30 -->
    </cac:Item>
    <cac:Price>
      <cbc:PriceAmount currencyID="EUR">100.00</cbc:PriceAmount>  <!-- BT-146 -->
    </cac:Price>
  </cac:InvoiceLine>
</ubl:Invoice>

Zwei Details fallen auf. Jeder Betrag trägt in UBL das Attribut currencyID; fehlt es, meldet schon das XSD einen Fehler. Und die Gutschrift ist ein eigener Dokumenttyp: CreditNote mit cbc:CreditNoteTypeCode, cac:CreditNoteLine und cbc:CreditedQuantity. Eine vollständige, gültige Beispieldatei mit Parteien und Steuerblock finden Sie im XRechnung Muster.

Wie ist eine CII-XRechnung aufgebaut?

CII gliedert die Rechnung in drei Blöcke. rsm:ExchangedDocumentContext enthält die Kennungen BT-23 und BT-24. rsm:ExchangedDocument trägt Nummer, Art und Datum der Rechnung. rsm:SupplyChainTradeTransaction enthält alles Übrige: zuerst die Positionen, danach Vereinbarung (Parteien, Käuferreferenz, Referenzdokumente), Lieferung und Abrechnung. Dass die Positionen vor den Kopfangaben stehen, überrascht viele, die von UBL kommen, ist aber im Schema so festgelegt.

<?xml version="1.0" encoding="UTF-8"?>
<rsm:CrossIndustryInvoice
    xmlns:rsm="urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100"
    xmlns:ram="urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100"
    xmlns:udt="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100"
    xmlns:qdt="urn:un:unece:uncefact:data:standard:QualifiedDataType:100">
  <rsm:ExchangedDocumentContext>
    <ram:BusinessProcessSpecifiedDocumentContextParameter>
      <ram:ID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</ram:ID>   <!-- BT-23 -->
    </ram:BusinessProcessSpecifiedDocumentContextParameter>
    <ram:GuidelineSpecifiedDocumentContextParameter>
      <ram:ID>urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0</ram:ID> <!-- BT-24 -->
    </ram:GuidelineSpecifiedDocumentContextParameter>
  </rsm:ExchangedDocumentContext>
  <rsm:ExchangedDocument>
    <ram:ID>RE-2026-0815</ram:ID>                                    <!-- BT-1 -->
    <ram:TypeCode>380</ram:TypeCode>                                 <!-- BT-3 -->
    <ram:IssueDateTime>
      <udt:DateTimeString format="102">20260928</udt:DateTimeString> <!-- BT-2 -->
    </ram:IssueDateTime>
  </rsm:ExchangedDocument>
  <rsm:SupplyChainTradeTransaction>
    <ram:IncludedSupplyChainTradeLineItem>…</ram:IncludedSupplyChainTradeLineItem> <!-- BG-25 -->
    <ram:ApplicableHeaderTradeAgreement>
      <ram:BuyerReference>991-12345-73</ram:BuyerReference>          <!-- BT-10 -->
      <ram:SellerTradeParty>…</ram:SellerTradeParty>                 <!-- BG-4 -->
      <ram:BuyerTradeParty>…</ram:BuyerTradeParty>                   <!-- BG-7 -->
    </ram:ApplicableHeaderTradeAgreement>
    <ram:ApplicableHeaderTradeDelivery>…</ram:ApplicableHeaderTradeDelivery> <!-- BG-13 -->
    <ram:ApplicableHeaderTradeSettlement>
      <ram:InvoiceCurrencyCode>EUR</ram:InvoiceCurrencyCode>         <!-- BT-5 -->
      <ram:SpecifiedTradeSettlementPaymentMeans>…</ram:SpecifiedTradeSettlementPaymentMeans> <!-- BG-16 -->
      <ram:ApplicableTradeTax>…</ram:ApplicableTradeTax>             <!-- BG-23 -->
      <ram:SpecifiedTradePaymentTerms>…</ram:SpecifiedTradePaymentTerms> <!-- BT-9, BT-20 -->
      <ram:SpecifiedTradeSettlementHeaderMonetarySummation>
        <ram:LineTotalAmount>1500.00</ram:LineTotalAmount>           <!-- BT-106 -->
        <ram:TaxBasisTotalAmount>1500.00</ram:TaxBasisTotalAmount>   <!-- BT-109 -->
        <ram:TaxTotalAmount currencyID="EUR">285.00</ram:TaxTotalAmount> <!-- BT-110 -->
        <ram:GrandTotalAmount>1785.00</ram:GrandTotalAmount>         <!-- BT-112 -->
        <ram:DuePayableAmount>1785.00</ram:DuePayableAmount>         <!-- BT-115 -->
      </ram:SpecifiedTradeSettlementHeaderMonetarySummation>
    </ram:ApplicableHeaderTradeSettlement>
  </rsm:SupplyChainTradeTransaction>
</rsm:CrossIndustryInvoice>

Anders als in UBL trägt in CII in der Regel nur ram:TaxTotalAmount das Attribut currencyID. Die übrigen Beträge beziehen sich auf die Rechnungswährung aus BT-5. Wer eine ZUGFeRD-Rechnung vorliegen hat, kann das enthaltene CII mit dem Werkzeug ZUGFeRD-XML extrahieren aus dem PDF holen und mit diesem Gerüst vergleichen.

Wo steht welches Feld? BT-Nummern und XPath

Die folgende Tabelle ordnet die wichtigsten Business Terms beiden Syntaxen zu. Die Pfade sind XPath-Ausdrücke relativ zum Wurzelelement. Für CII gelten drei Abkürzungen, damit die Tabelle lesbar bleibt:

• HA steht für rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeAgreement
• HS steht für rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeSettlement
• MS steht für HS/ram:SpecifiedTradeSettlementHeaderMonetarySummation

Wie BT-10 im öffentlichen Auftragswesen befüllt wird, erklärt der Beitrag zur Leitweg-ID. Wer beide Syntaxen einlesen muss, prüft zuerst das Wurzelelement und wählt danach die Pfade. Das folgende Python-Beispiel nutzt nur die Standardbibliothek und liest BT-10 und BT-112 aus beiden Varianten:

import sys
import xml.etree.ElementTree as ET

NS = {
    "ubl": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2",
    "cac": "urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2",
    "cbc": "urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2",
    "rsm": "urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100",
    "ram": "urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100",
}

root = ET.parse(sys.argv[1]).getroot()
if root.tag == "{%s}Invoice" % NS["ubl"]:
    bt10 = root.findtext("cbc:BuyerReference", namespaces=NS)
    bt112 = root.findtext("cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount", namespaces=NS)
elif root.tag == "{%s}CrossIndustryInvoice" % NS["rsm"]:
    tx = "rsm:SupplyChainTradeTransaction/"
    bt10 = root.findtext(tx + "ram:ApplicableHeaderTradeAgreement/ram:BuyerReference", namespaces=NS)
    bt112 = root.findtext(tx + "ram:ApplicableHeaderTradeSettlement/"
                          "ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:GrandTotalAmount", namespaces=NS)
else:
    sys.exit("Keine XRechnung: " + root.tag)
print("BT-10:", bt10, "| BT-112:", bt112)

Das Skript funktioniert unabhängig davon, welches Präfix die Datei verwendet, weil es über die Namespace-URI sucht.

In welcher Reihenfolge wird eine XRechnung geprüft?

Die Prüfung läuft in vier Stufen. Scheitert eine Stufe, sind die folgenden oft nicht mehr aussagekräftig.

1. Wohlgeformtheit. Die Datei muss XML 1.0 entsprechen. Ein unmaskiertes & in „Müller & Söhne GmbH“ macht sie unlesbar; richtig ist &. Siehe SCHEMA-001.
2. XSD. Das XSD-Schema der Syntax prüft Elementnamen, Reihenfolge, Pflichtelemente und Datentypen. Ein Komma als Dezimaltrenner, ein fehlendes currencyID oder ungültiger Base64-Inhalt in einem Anhang scheitern hier. Siehe SCHEMA-003.
3. EN-16931-Schematron. Die Regeln der Norm prüfen Pflichtfelder (BR-…), Rechenregeln (BR-CO-…), Codelisten (BR-CL-…) und Nachkommastellen (BR-DEC-…). Dazu kommen syntaxspezifische Regeln wie UBL-DT-01 (Beträge mit höchstens zwei Nachkommastellen) oder CII-DT-097 (Datumsformat). Ein typischer Treffer ist BR-CO-15: Netto plus Steuer ergibt nicht das Brutto.
4. XRechnung-Schematron der KoSIT. Die nationalen Regeln BR-DE-… ergänzen die Norm, etwa BR-DE-15 für die fehlende Käuferreferenz BT-10. Einige Regeln sind Soll-Regeln und erzeugen nur eine Warnung, in Version 3.0.2 zum Beispiel BR-DE-17 (Rechnungsart) und BR-DE-21 (Spezifikationskennung).

Die Referenz für alle vier Stufen ist der quelloffene KoSIT-Validator (öffnet in neuem Tab) in Java, zusammen mit der Prüfkonfiguration für XRechnung (öffnet in neuem Tab). Die Konfiguration enthält die XSD-Dateien und die Schematron-Regeln als XSLT. Der Validator wählt anhand von Wurzelelement und BT-24 ein Prüfszenario. Passt keines, lehnt er die Datei ab, ohne die Geschäftsregeln überhaupt anzuwenden.

java -jar validator-<version>-standalone.jar \
  -s validator-configuration-xrechnung/scenarios.xml \
  -r validator-configuration-xrechnung \
  -o pruefberichte -h \
  rechnung.xml

Im Ordner pruefberichte liegt danach ein XML-Bericht mit dem Ergebnis accept oder reject; -h legt zusätzlich eine HTML-Fassung ab. Ohne lokale Java-Installation prüft unser XRechnung Validator UBL- und CII-Dateien mit den offiziellen KoSIT-Regeln und zeigt jede Meldung mit Erklärung an. Alle Codes sind unter XRechnung Fehlercodes nachschlagbar, die zehn häufigsten Fälle behandelt der Beitrag XRechnung-Fehler beheben.

Was gehört in BT-24 und BT-23?

BT-24 (cbc:CustomizationID bzw. ram:GuidelineSpecifiedDocumentContextParameter/ram:ID) erklärt, nach welcher Spezifikation die Datei gebaut ist. Für alle Versionen 3.0.x lautet die Kennung urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0. Wer die Extension XRechnung nutzt, etwa für Unterpositionen oder XML-Anhänge im Bauwesen, hängt #conformant#urn:xeinkauf.de:kosit:extension:xrechnung_3.0 an.

Ältere Kennungen mit urn:xoev-de:kosit:standard:xrechnung_2.x sind ein häufiger Grund für Ablehnungen. BR-DE-21 meldet sie nur als Warnung, aber die aktuelle Prüfkonfiguration hat für eine ausgelaufene Version kein Szenario mehr, sodass die Datei insgesamt abgewiesen wird. Die Kennung ist versionsgebunden; für XRechnung 4.0 gilt dann die Kennung aus der finalen Spezifikation.

BT-23 (cbc:ProfileID bzw. ram:BusinessProcessSpecifiedDocumentContextParameter/ram:ID) ist in der EN 16931 optional, in XRechnung 3.0.2 aber Pflicht: Die KoSIT-Regeln enthalten die Peppol-Regel PEPPOL-EN16931-R001 „Business process MUST be provided“. Üblich ist der Wert urn:fdc:peppol.eu:2017:poacc:billing:01:1.0.

Welche Codelisten und Datenformate gelten?

• Mengeneinheiten (BT-130) stammen aus UN/ECE Recommendation 20 und 21, zum Beispiel C62 (Stück als Zähleinheit), H87 (Stück), HUR (Stunde), DAY (Tag), KGM (Kilogramm) und LS (Pauschale).
• Umsatzsteuerkategorien (BT-118, BT-151) nutzen Codes wie S (Normalsatz), Z (Nullsatz), E (steuerbefreit), AE (Reverse Charge) und K (innergemeinschaftliche Lieferung). Die vollständige Liste steht im Glossar unter Umsatzsteuerkategorie.
• Rechnungsarten (BT-3) kommen aus UNTDID 1001. XRechnung erwartet nach BR-DE-17 326, 380, 381, 384, 389, 875, 876 oder 877; mehr dazu unter Rechnungsartcode.
• Währungen folgen ISO 4217 (EUR), Ländercodes ISO 3166-1 Alpha-2 (DE).
• Datumsangaben: UBL 2026-09-28, CII 20260928 mit format="102".
• Beträge schreiben den Punkt als Dezimaltrenner, ohne Tausendertrennzeichen. Rechnungsbeträge haben höchstens zwei Nachkommastellen; Einzelpreise dürfen mehr haben.
• Zeichenkodierung: UTF-8. Die Deklaration im Prolog muss zu den tatsächlichen Bytes passen, sonst wird aus „Straße“ beim Einlesen „Straße“.

Welche Fehler machen Entwickler am häufigsten?

Die folgenden Fälle haben wir mit dem KoSIT-Validator 1.5.0 und der Prüfkonfiguration für XRechnung 3.0.2 nachgestellt.

Die meisten dieser Fehler verschwinden, wenn die Datei nicht per Zeichenkettenverkettung, sondern mit einer XML-Bibliothek serialisiert wird, die Namespaces, Maskierung und Kodierung selbst verwaltet.

Welche Werkzeuge helfen beim Lesen und Prüfen?

Für einen schnellen Blick in die Struktur öffnet der XML Viewer jede XML-Datei als aufklappbaren Baum. Der XRechnung Viewer stellt UBL- und CII-Rechnungen lesbar dar und validiert sie mit den KoSIT-Regeln. Wer eine Referenz für die eigene Ausgabe braucht, erzeugt mit dem XRechnung Generator eine UBL-Datei und vergleicht sie Element für Element. Zum Testen eines Parsers eignen sich die Musterrechnung und die absichtlich fehlerhafte Testdatei. Wie Anhänge als Base64 in die XML-Struktur kommen, zeigt der Beitrag XRechnung mit Anhang. Den fachlichen Weg von den Rechnungsdaten zur fertigen Datei beschreibt die Anleitung zum Erstellen einer XRechnung.