Zum Inhalt

DataContract & Revisionen

Ein DataContract dokumentiert, was ein bestimmter Lieferant zu liefern zusagt. Es ist die lieferanten-seitige Vereinbarung — Dateitypen, erwartete Spalten, die Rolle jeder Datei — und sagt bewusst nichts darüber aus, wie Sie die Daten transformieren. Diese Trennung hält das Format des Lieferanten unabhängig von Ihrem Ziel.

Sources

Ein Vertrag hat eine oder mehrere Sources, eine pro Datei-Rolle. Jede Source ist typisiert (CSV, XLSX, TXT, JSON, XML, DATEV) und trägt die Parsing-Konfiguration plus ein Frictionless-Table-Schema, das erwartete Spalten und Typen beschreibt. Das Schema ermöglicht, strukturelle Fehler beim Parsen zu erkennen, bevor irgendeine Transformation läuft.

Eine FIBU-Lieferung hat z. B. typischerweise zwei Sources: eine buchungsdatei und eine saldendatei.

Optionale Sources

Standardmäßig ist jede Source erforderlich: Eine Session kann erst bestätigt werden, wenn jede erforderliche Rolle eine gelieferte, geparste Datei hat. Eine Source kann stattdessen als optional markiert werden (required = false). Der Lieferant kann sie liefern oder nicht — eine Session, deren einzige fehlende Dateien optional sind, durchläuft die Pipeline trotzdem bis checked und kann bestätigt werden. Eine vat_options-Source, die der Lieferant nur bei Änderungen der USt-Einstellungen sendet, passt natürlich dazu.

Das Flag gehört zur Revision und bleibt daher erhalten, wenn Sie aus der aktiven eine neue Revision erstellen. Was nachgelagert passiert, wenn eine optionale Source nicht geliefert wird, beschreibt der Session-Lebenszyklus.

Formathinweise

Verstößt ein Wert gegen constraints.pattern, muss der Datenlieferant den Fehler beheben können — die Meldung muss das erwartete Format also in Worten nennen und niemals den regulären Ausdruck selbst. Dieser Text stammt aus x-format-hint des Feldes:

{
  "name": "BELEGDATUM",
  "type": "string",
  "constraints": { "pattern": "^20\\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\\d|3[01])$" },
  "x-format-hint": "JJJJMMTT (z. B. 20251114)"
}

Fehlt der Hinweis, zeigt die Meldung ersatzweise das rohe Muster, das für Datenlieferanten unlesbar ist. Ein pattern ohne x-format-hint gilt als unvollständiges Schema.

Da nicht alle Datenlieferanten dieselbe Sprache lesen, kann der Hinweis auch als mehrsprachiges Objekt hinterlegt und je Leser aufgelöst werden:

"x-format-hint": {
  "en": "14 digits, zero-padded (e.g. 00000000123456)",
  "de": "14 Ziffern, mit führenden Nullen (z. B. 00000000123456)"
}

Eine einfache Zeichenkette bleibt gültig und wird allen Lesern gezeigt. Fehlt die Sprache des Lesers, wird eine andere Variante statt des Musters angezeigt.

In der Oberfläche steht der Hinweis unter Schema → Feld bearbeiten → Extensions → Format hint, mit je einem Reiter pro Sprache. Ein Feld mit pattern, aber ohne Hinweis, wird in der Feldliste mit no hint markiert.

Das Revisionsmodell

Formate ändern sich mit der Zeit, daher ist ein Vertrag über Revisionen versioniert:

draft → active → frozen
  • Eine Draft-Revision ist bearbeitbar.
  • Ihre Aktivierung erzeugt eine unveränderliche aktive Revision und führt eine Kompatibilitätsprüfung gegen alle Transformer aus, die auf den Vertrag zeigen.
  • Wird eine neuere Revision aktiviert, wird die vorherige frozen — erhalten, damit historische Sessions weiterhin gegen das exakte Format auflösen, mit dem sie liefen.

Es gibt zu jedem Zeitpunkt genau eine aktive Revision pro Vertrag. Format- Evolution wird als neue Revision innerhalb desselben Vertrags ausgedrückt, nie durch Mutation einer aktiven — so brechen alte Lieferungen nie.

Verwandt