Eigene Standards für die E-Rechnung

Wozu ein eigener Standard

Smart Templates bringt »XRechnung 3.0« (xrechnung-ubl) und »ZUGFeRD 2.5.2 (EXTENDED)« (zugferd-extended) mit. Ein eigener Standard lohnt sich, wenn ein Empfänger einzelne Angaben anders erklärt haben will, zusätzliche Prüfregeln verlangt oder eine andere Syntax braucht. Der einfachste Weg: im Designer bei einem mitgelieferten Standard »Als Datei speichern« wählen, die Datei anpassen (eigene Kennung, eigene Texte, eigene Regeln) und wieder hochladen.

Woraus ein Standard besteht

• Schemasatz: die offiziellen XSD-Dateien, Byte für Byte unverändert. Mitgeliefert sind ubl-2.1 (UBL 2.1 für XRechnung) und factur-x-1.09.2-extended (Factur-X/ZUGFeRD EXTENDED). Ein eigener Standard benutzt einen davon oder bringt einen eigenen Satz im Paket mit.
• Anmerkungsdatei: ein XSD mit eigenem targetNamespace, das die Schemata nur importiert und in xs:annotation-Blöcken beschreibt. Sie hat genau eine Wurzel xs:schema; erlaubt sind darunter nur xs:import und xs:annotation. Eigene Deklarationen (xs:element, xs:complexType …) werden abgelehnt.
• Der Kern prüft jedes Element mit dem Präfix st: gegen das Format-Schema (Aktion st_StandardLesen, Teil formatschema). Namensraum: urn:smart-templates:e-rechnung:anmerkung:1.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:st="urn:smart-templates:e-rechnung:anmerkung:1"
           xmlns:ubl="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
           xmlns:cn="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2"
           xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
           xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
           targetNamespace="urn:example:standard:my-xrechnung:1">
  <xs:import namespace="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" schemaLocation="ubl-2.1/maindoc/UBL-Invoice-2.1.xsd"/>
  <xs:import namespace="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2" schemaLocation="ubl-2.1/maindoc/UBL-CreditNote-2.1.xsd"/>
  <xs:annotation> … ein Block je Kopf, Angabe, Liste, Gruppe, Codeliste, Code-Name oder Prüfregel … </xs:annotation>
</xs:schema>

• Präfixe: Die Präfixe in Pfaden sind die des Standards und stehen alle auf xs:schema. Die XML entsteht mit genau diesen Präfixen.
• schemaLocation wird nie aufgelöst: Der Kern legt alle Dateien des Satzes selbst zusammen, ohne Netz und ohne Dateisystem.
• Ein Block ist ein xs:annotation direkt unter xs:schema mit einem xs:appinfo (darin genau ein Träger: st:standard, st:feld, st:liste, st:gruppe, st:codeliste, st:codename oder st:pruefung) und daneben den Texten als xs:documentation.
• Texte: <xs:documentation source="name" xml:lang="de">…</xs:documentation>, source ist name, erklaerung, grund, beispiel oder meldung. Nur Text, Leerraum wird zusammengefasst. Fehlt ein deutscher Pflichttext, ist das ein Fehler; fehlt der englische, ein Hinweis (es gilt der deutsche).

Der Kopf: st:standard

<xs:annotation>
  <xs:appinfo>
    <st:standard kennung="my-xrechnung" fassung="1.0" formatVersion="1" syntax="UBL" schemasatz="ubl-2.1"
                 gueltigAb="2024-02-01" einbettbar="nein" downloadName="XRechnung_{BT-1}.xml" mime="application/xml">
      <st:wurzel element="ubl:Invoice" dokument="Invoice"/>
      <st:wurzel element="cn:CreditNote" dokument="CreditNote"/>
    </st:standard>
  </xs:appinfo>
  <xs:documentation source="name" xml:lang="de">Meine XRechnung</xs:documentation>
  <xs:documentation source="name" xml:lang="en">My XRechnung</xs:documentation>
</xs:annotation>

• st:wurzel (mindestens eine): element (das Wurzelelement) und dokument (Name der Dokumentform, eindeutig). Mehrere Wurzeln brauchen eine Angabe, die die Form wählt (siehe »Codelisten und Dokumentform«).
• st:einbettung (höchstens eine): dateiname, beziehung (Data, Source, Alternative, Supplement, Unspecified), pdfa (etwa 3B), profil, version (Vorgabe 1.0), dokumentArt (Vorgabe INVOICE). Daraus entstehen Anhang und Metadaten im PDF/A-3.

Angaben: st:feld

<xs:annotation><xs:appinfo>
  <st:feld id="BT-84" abschnitt="zahlung" liste="BG-17" typ="kennung" pflicht="wenn"
           wenn="[BT-81] == '30' || [BT-81] == '58'" bereinigen="ohneLeerzeichen grossbuchstaben">
    <st:pfad>/ubl:Invoice/cac:PaymentMeans/cac:PayeeFinancialAccount/cbc:ID</st:pfad>
    <st:pfad>/cn:CreditNote/cac:PaymentMeans/cac:PayeeFinancialAccount/cbc:ID</st:pfad>
  </st:feld></xs:appinfo>
  <xs:documentation source="name" xml:lang="de">IBAN</xs:documentation>
  <xs:documentation source="erklaerung" xml:lang="de">Ihre Kontonummer, auf die der Kunde zahlen soll.</xs:documentation>
  <xs:documentation source="grund" xml:lang="de">bei Zahlung per Überweisung</xs:documentation>
</xs:annotation>

Typ gegen Schema: betrag, preis, menge und prozent nur auf Zahlen-Typen (xs:decimal und abgeleitet), datum auf xs:date oder auf Text mit Typregel-Schreibweise (CII), janein auf xs:boolean, text, kennung und code auf Text-Typen. Geschrieben wird invariant mit Punkt, ohne Tausendertrenner; Beträge und Preise mit mindestens 2 Stellen, Datum als yyyy-MM-dd bzw. nach Typregel, Wahrheitswerte true/false. Kennungen und Codes werden an den Rändern gekürzt, Texte vorne und hinten nur um Leerraum, der kein Zeilenumbruch ist.

Mehrere Pfade: je Dokumentform ein Pfad. Mehrere Pfade derselben Form sind ein bedingter Pfad: alle bis auf den letzten tragen wenn, der erste passende gilt. Weitere Attribute am st:pfad: wurzel, wenn, jeEintrag="alle" und format (siehe »Pfadsprache«).

Pfadsprache

Eine kleine Teilmenge von XPath 1.0:

Pfad      := "/" Schritt ( "/" Schritt )*              höchstens 64 Schritte, 2.000 Zeichen
Schritt   := Präfix ":" Name Prädikat?  |  "@" Name    Attribut nur als letzter Schritt, ohne Präfix
Prädikat  := "[" Zahl "]"                               Nummer, ab 1
           | "[" Rel "='" Wert "']"                     Merkmal gleich
           | "[not(" Rel ")]"                           Merkmal fehlt
           | "[not(" Rel "='" Wert "')]"                Merkmal ungleich
Rel       := ( Präfix ":" Name "/" )* ( Präfix ":" Name | "@" Name )

• Höchstens ein Prädikat je Schritt; Werte in einfachen Anführungszeichen, ohne ' darin.
• Nummer cac:TaxTotal[2]: die zweite Ausprägung. Nummern ohne Lücke: Wer [2] nennt, braucht eine Angabe in [1].
• Merkmal gleich cac:PartyTaxScheme[cac:TaxScheme/cbc:ID='VAT']: die Ausprägung, deren Kind diesen Wert hat. Das Merkmal ist zugleich ein fester Wert und wird geschrieben, sobald die Ausprägung entsteht.
• Merkmal fehlt cac:AdditionalDocumentReference[not(cbc:DocumentTypeCode)]: Unter dieser Ausprägung darf nichts in den Merkmalspfad schreiben.
• Merkmal ungleich cac:PartyIdentification[not(cbc:ID/@schemeID='SEPA')]: Ein Wert mit dem ausgeschlossenen Wert ist beim Schreiben ein Fehler.
• Zwei Ausprägungen desselben Elements unter derselben Eltern-Ausprägung müssen unterscheidbar sein: verschiedene Nummern, verschiedene Werte desselben Merkmals, »gleich« gegen »fehlt« oder »gleich« gegen »ungleich«. Alles andere ist ein Fehler.
• Ein Schritt ohne Prädikat auf einem wiederholbaren Element, das keine Liste ist, meint eine gemeinsame Ausprägung (wie [1]): Name, Telefon und E-Mail eines Ansprechpartners landen in einem Kontakt.
• Bedingter Pfad: mehrere st:pfad mit wenn, wenn das Element vom Wert abhängt. An einer Liste entscheidet die Bedingung je Eintrag.
• Angabe im Kopf, Element in einer Liste: Ein Kopfpfad durch eine Liste braucht [n] (nur in die n-te Ausprägung) oder jeEintrag="alle" (in jede). Eine solche Liste entsteht mindestens einmal, auch ohne Eintrag.
• Zusammensetzung format="[#{BT-21}#]{BT-22}": {Kennung} ist ein Wert, [ … ] fällt weg, sobald eine Angabe darin leer ist; {{, }}, [[, ]] schreiben die Zeichen. Die Zusammensetzung nennt die Angabe, die sie trägt.

Listen und Gruppen

<st:liste id="BG-25" abschnitt="positionen" min="1" quelle="regel eintraege">
  <st:pfad>/ubl:Invoice/cac:InvoiceLine</st:pfad>
  <st:pfad>/cn:CreditNote/cac:CreditNoteLine</st:pfad>
</st:liste>
<st:gruppe id="BG-6" abschnitt="verkaeufer">
  <st:pfad>/ubl:Invoice/cac:AccountingSupplierParty/cac:Party/cac:Contact</st:pfad>
</st:gruppe>

• Liste: der Pfad eines wiederholbaren Elements; je Eintrag eine Ausprägung. Prädikate am Listenelement sind erlaubt (…/cac:AllowanceCharge[cbc:ChargeIndicator='false']). Attribute: liste (die übergeordnete Liste), gruppe, min und max (nur, wo die Norm strenger ist als das Schema), quelle (regel, eintraege oder beides), wert="selbst" (das Listenelement ist selbst der Wert, mit genau einer Angabe) und haeufig. Eine Liste braucht einen Pfad für jede Dokumentform, in der ihre Angaben vorkommen.
• Positionen: Die oberste Positionsliste trägt abschnitt="positionen", ihre Positionskennung zuordnung="laufendeNummer".
• Gruppe ohne Wiederholung: eine Unterüberschrift im Fenster. filled([BG-x]) ist wahr, sobald eine Angabe der Gruppe einen Wert hat. Eine Gruppe kann in einer anderen liegen (gruppe="BG-11"); filled sieht dann auch die Untergruppen.

Festes, Attribute, Typregeln, Sperren

Vorrang an einem Attribut: Angabe vor Festem bzw. Merkmal, vor st:attribut am Pfad, vor st:attribut aus einer Typregel, vor Festem aus einer Typregel. Zwei verschiedene Quellen derselben Art an derselben Stelle sind ein Fehler.

Codelisten und Dokumentform

<st:codeliste id="EINHEIT" quelle="UN/ECE Rec 20/21">
  <st:code wert="H87" haeufig="ja" synonyme="pcs;piece"/>
  <st:code wert="C62"/>
</st:codeliste>

• Die Codes stehen vollständig in der Liste. Namen bekommen häufige Codes über einen eigenen Block st:codename (liste, wert) mit Texten; seltene erscheinen als Code. namen="cldr-49" an der Codeliste übernimmt Ländernamen aus der mitgelieferten Liste (Unicode CLDR 49).
• Erkennen: ohne Groß- und Kleinschreibung gegen Code, Namen und synonyme (durch ; getrennt). Zwei verschiedene Treffer ergeben kein Ergebnis; es wird nie geraten. Die Umsetzung der Vorlage greift zusätzlich.
• Dokumentform: Bei mehreren st:wurzel gibt es genau eine Angabe im Kopf vom Typ code, deren Codeliste an jedem Code dokument="…" trägt (XRechnung: BT-3, 380 wird Invoice, 381 CreditNote). Leer oder unbekannt ist ein Fehler.

Pflicht, »Pflicht, wenn …« und Prüfregeln

Pflicht kommt aus zwei Quellen: dem Schema (ein Pflichtelement unter einem geschriebenen Behälter braucht einen Wert) und der Anmerkung (pflicht, st:pruefung).

<st:pruefung id="BR-CO-17" art="rechnung" stufe="fehler" je="BG-23" felder="BG-23/BT-117 BG-23/BT-116 BG-23/BT-119"
             bedingung="abs([BT-117] - round([BT-116] * [BT-119] / 100, 2)) &lt; 1"/>
<!-- daneben: xs:documentation source="meldung" xml:lang="de" mit der Meldung in Alltagssprache -->

Prüfsprache

Ausdruck  := Oder
Oder      := Und ( "||" Und )*             Und   := Gleich ( "&&" Gleich )*
Gleich    := Vergl ( ("=="|"!=") Vergl )*   Vergl := Summe ( ("<"|"<="|">"|">=") Summe )*
Summe     := Prod ( ("+"|"-") Prod )*      Prod  := Unär ( ("*"|"/") Unär )*
Unär      := ("!"|"-") Unär | Primär
Primär    := "(" Ausdruck ")" | "[" Kennung ("/" Kennung)* "]" | "'" Text "'" | Zahl | true | false | Funktion "(" Argumente ")"

• [BT-81] ist der Wert einer Angabe. Eine Angabe einer Liste nur in einem Eintrag ihrer Liste (je, any, all oder ein Bezug derselben Liste), sonst [BG-25/BT-131] für alle Werte. [BG-15] steht für eine Gruppe oder Liste nur in filled, count, any und all.
• Text in einfachen Anführungszeichen ('' ist ein Anführungszeichen), Zahlen mit Punkt, true und false.
• Funktionen: filled(x), sum([L/F]) und sum([L/F], b) (nur Einträge, in denen b wahr ist), count([L]), count([L/F]) und count([L], b), any([L], b), all([L], b), round(x, n) (n von 0 bis 10, kaufmännisch), abs(x), matches(x, 'regex') (Zeitlimit 100 ms, leer ist falsch), iban(x) (Prüfziffer), aussen(x) (nur in einer Bedingung von sum, count, any, all: wertet x im Eintrag außerhalb der innersten Durchsicht aus).
• Gerechnet wird mit Dezimalzahlen. Leer zählt beim Rechnen 0; im Vergleich mit einer Zahl als 0, mit Text als leerer Text. true und false nur mit == und !=; leer ist nicht false. Eine Bedingung ist nur bei true erfüllt.
• Beim Laden geprüft: unbekannte Kennungen, Angaben einer Liste außerhalb ihrer Einträge, Text in Rechnungen, Listen in Vergleichen, Gruppen außerhalb von filled, eine Bedingung, die keinen Wahrheitswert ergibt.
• Toleranzen stehen im Ausdruck selbst, etwa abs(…) < 1 oder <= 0.02.
• Reguläre Ausdrücke sind die von .NET, die Standards schreiben XPath: Textende als (?![\s\S]) statt $, Leerraum als [ \t\r\n] statt \s, »beliebiges Zeichen der Zeile« als [^\r\n]. Geprüft wird der Wert vor dem Schreiben; ein Umbruch kann CR, CRLF oder LF sein.

Ablauf an einem Beleg: zuerst Werte unbekannter Kennungen, falscher Ebene oder ohne Stelle in der Dokumentform; dann je Ebene (Kopf, jeder Eintrag) Format, pflicht, wenn, Code, max, muster; dann min und max der Listen; zuletzt jede st:pruefung. Leer ist: fehlt, null, leerer Text oder nur Leerraum; 0 und false sind Werte.

Was beim Erzeugen geschieht

• Die XML entsteht von der Wurzel aus in der Reihenfolge des übersetzten Schemas. Ein Behälter entsteht nur mit zugeordnetem Inhalt oder weil das Schema ihn verlangt; ein Pflicht-Text ohne Wert ist dann ein Fehler. Bei einer Auswahl im Schema gilt der Zweig mit Werten (zwei gefüllte sind ein Fehler).
• Datentyp und Fassetten (Länge, Muster, Aufzählung) werden vor dem Schreiben geprüft; mehr Ausprägungen als erlaubt sind ein Fehler. Zum Schluss wird jeder nicht leere Wert gegen das Geschriebene abgeglichen: Nichts geht still verloren.
• Geschrieben wird UTF-8 ohne BOM, mit Deklaration und allen Namensräumen an der Wurzel. Danach prüft der Kern die fertige XML gegen den Schemasatz; jede Warnung außerhalb von Erweiterungsbereichen ist ein Fehler.

Hochladen: Datei oder Paket

• Datei (.xsd): eine Anmerkungsdatei auf einem mitgelieferten Schemasatz. Smart Templates verpackt sie zur Ablage.
• Paket (.zip): genau eine Anmerkungsdatei (die einzige .xsd mit dem Namensraum st:) und bei schemasatz="eigen" die Schemadateien. Nur .xsd; abgelehnt werden absolute Pfade, Laufwerke, .., leere Pfadteile und doppelte Namen. Bei mitgeliefertem Schemasatz enthält das Paket nur die Anmerkungsdatei. In eigenen Schemasätzen werden Muster mit geschachtelten Wiederholungen abgelehnt.
• Der Kern prüft vollständig, bevor er speichert. Gibt es Kennung und Fassung schon, wird nur mit »Ersetzen« überschrieben (Designer: Rückfrage; Aktion: Ersetzen = ja). Eigene Standards liegen in Dynamics in der Tabelle st_erechnungstandard; hochladen und löschen darf, wer die Sicherheitsrolle »Smart Templates Designer« hat.

Befunde beim Laden tragen einen Code und eine Fundstelle (Datei, Zeile, Spalte), etwa xml.wohlgeformt, format.schema, text.fehlt, id.doppelt, ausdruck.syntax, pfad.schritt, pfad.doppeltreffer, liste.eltern, pflicht.ohneAngabe, standard.gesperrt, paket.zip oder grenze.angaben. Hinweise wie text.englisch verhindern das Speichern nicht.

Die Übersicht

Aus dem Standard erzeugt der Kern eine Übersicht für das Zuordnungsfenster, den KI-Assistenten und das KI-Paket: Abschnitte, Angaben (Kennung, Name, Erklärung, Grund, Pflicht aus Norm und Schema, Typ, Liste, Gruppe, Codeliste), Listen (Quelle, min, Pflicht aus dem Schema), Gruppen, Codelisten (häufige Codes) und Prüfregeln. Sie ist eine Ansicht, nie gespeichert, ohne Pfade und ohne XML. Die Aktion st_StandardLesen liefert sie:

Ohne Kennung liefert die Aktion die Liste der Standards (mitgelieferte und eigene); Sprache = en liefert die englischen Texte.