Перейти к содержанию

DataContract и Revisions

DataContract описывает, что обещает прислать конкретный поставщик. Это соглашение со стороны поставщика — типы файлов, ожидаемые колонки, роль каждого файла — и оно намеренно не говорит, как вы трансформируете данные. Это разделение держит формат поставщика независимым от вашей цели.

Sources

У контракта одна или несколько Sources, по одной на роль файла. Каждая source типизирована (CSV, XLSX, TXT, JSON, XML, DATEV) и несёт конфигурацию парсинга плюс Frictionless Table Schema с ожидаемыми колонками и типами. Схема позволяет ловить структурные ошибки на этапе парсинга, до запуска трансформации.

FIBU-поставка, например, обычно имеет две sources: buchungsdatei (проводки) и saldendatei (сальдо).

Необязательные sources

По умолчанию каждая source обязательна: сессию нельзя подтвердить, пока у каждой обязательной роли нет доставленного, распарсенного файла. Source можно вместо этого пометить как необязательную (required = false). Поставщик может её прислать или нет — сессия, у которой отсутствуют только необязательные файлы, всё равно проходит пайплайн до checked и может быть подтверждена. Source vat_options, которую поставщик присылает только при изменении настроек НДС, — естественный кандидат.

Флаг принадлежит ревизии, поэтому сохраняется, когда вы создаёте новую ревизию из активной. Что происходит дальше по пайплайну, если необязательная source не доставлена, описано в жизненном цикле Session.

Подсказки формата

Если значение нарушает constraints.pattern, ошибку исправляет поставщик — поэтому сообщение должно называть ожидаемый формат словами, а не показывать само регулярное выражение. Этот текст берётся из 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 (например, 20251114)"
}

Без подсказки сообщение показывает сырое выражение, которое поставщик прочитать не может. pattern без x-format-hint — неполная схема.

Поставщики читают на разных языках, поэтому подсказку можно задать многоязычным объектом — он разрешается под язык читателя:

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

Обычная строка остаётся допустимой и показывается всем. Если языка читателя в объекте нет, покажут другой вариант, а не выражение.

В интерфейсе подсказка задаётся в Schema → редактирование поля → Extensions → Format hint, по вкладке на язык. Поле с pattern, но без подсказки, помечается в списке значком no hint.

Модель ревизий

Форматы меняются со временем, поэтому контракт версионируется через Revisions:

draft → active → frozen
  • Draft-ревизия редактируема.
  • Её активация создаёт неизменяемую active-ревизию и запускает проверку совместимости со всеми трансформерами, указывающими на контракт.
  • Когда активируется более новая ревизия, предыдущая становится frozen — сохранённой, чтобы исторические сессии по-прежнему разрешались против того формата, на котором они выполнялись.

В каждый момент у контракта ровно одна активная ревизия. Эволюция формата выражается как новая ревизия внутри того же контракта, никогда — мутацией активной, поэтому старые поставки не ломаются.

Связанное