Skip to content

DataContract & Revisions

A DataContract documents what a particular supplier promises to deliver. It is the supplier-facing agreement — file types, expected columns, the role of each file — and it deliberately says nothing about how you transform the data. That separation keeps the supplier's format independent of your target.

Sources

A contract has one or more Sources, one per file role. Each source is typed (CSV, XLSX, TXT, JSON, XML, DATEV) and carries the parsing configuration plus a Frictionless Table Schema describing the expected columns and types. The schema lets structural mistakes be caught at parse time, before any transformation runs.

A FIBU delivery, for example, typically has two sources: a buchungsdatei (bookings) and a saldendatei (balances).

Optional sources

By default every source is required: a session cannot be confirmed until each required role has a delivered, parsed file. A source can instead be marked optional (required = false). The supplier may deliver it or not — a session whose only missing files are optional still runs the pipeline through to checked and can be confirmed. A vat_options source the supplier sends only when VAT settings change is a natural fit.

The flag belongs to the revision, so it is preserved when you create a new revision from the active one. What happens downstream when an optional source is not delivered is covered in the Session lifecycle.

Format hints

A field whose constraints.pattern rejects a value produces an error the supplier has to act on — so the message must state the expected format in words, never the regular expression itself. That wording comes from the field's x-format-hint:

{
  "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": "YYYYMMDD (e.g. 20251114)"
}

Without the hint the message falls back to printing the raw pattern, which suppliers cannot read. Treat a pattern without an x-format-hint as an incomplete schema.

Because suppliers rarely all read the same language, the hint may also be written as a multilingual object, resolved for each reader's language:

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

A plain string stays valid and is shown to every reader. If the object lacks the reader's language, another variant is shown rather than the pattern.

In the UI the hint lives in Schema → edit a field → Extensions → Format hint, with one tab per language. A field that has a pattern but no hint is marked no hint in the field list.

The revision model

Formats change over time, so a contract is versioned through Revisions:

draft → active → frozen
  • A draft revision is editable.
  • Activating it produces an immutable active revision and runs a compatibility check against any transformers pointing at the contract.
  • When a newer revision is activated, the previous one becomes frozen — preserved so historical sessions still resolve against the exact format they ran on.

There is exactly one active revision per contract at a time. Format evolution is expressed as a new revision within the same contract, never by mutating an active one — so old deliveries never break.