Skip to content

Terry Data Contracts

Contract Layers

Terry стоит документировать через несколько стабильных contract layers, а не через payload каждого конкретного source.

Logical entity model для этих contract layers вынесен в Reference ERD.

Current implementation baseline уже добавляет один важный contract layer до actual payload processing: persisted source catalog contract.

Он включает:

  • workspace
  • domain
  • data_source
  • LoaderConfig, материализуемый из persisted data_sources row

1. Source Payload

source payload это raw input, полученный из внешнего источника.

Требования:

  • payload сохраняется без потери значимых полей;
  • известен source format и transport metadata;
  • payload можно повторно проиграть для replay/debug.

2. Normalized Record

normalized record это internal representation после parsing и transformation.

Минимальные свойства:

  • stable identifier или dedup key;
  • normalized business fields;
  • source provenance;
  • processing timestamps;
  • optional quality flags.

3. Validation Result

validation result должен быть machine-readable и пригоден для policy decisions.

Минимальные свойства:

  • rule identifier;
  • severity;
  • pass/fail status;
  • explanation message;
  • pointer на affected field или record fragment.

4. Persistence Outcome

Результат записи в sink должен различать:

  • created;
  • updated;
  • unchanged;
  • rejected;
  • failed.

Это нужно и для аналитики pipeline, и для запуска notification rules.

5. Delivery Event

Notification layer должна работать не с raw payload, а с delivery-oriented contract.

Минимальные свойства:

  • template identifier;
  • rendered variables;
  • destination/channel;
  • send status;
  • attempt number;
  • provider response metadata.

6. Error Envelope

error envelope нужен для retry, triage и dead-letter processing.

Минимальные свойства:

  • stage;
  • error category;
  • retryability;
  • correlation ids;
  • original cause;
  • links на payload, record и delivery attempts.

Contract Discipline

  • source-specific поля не должны протекать в global contract без явной normalization;
  • каждое поле должно иметь owner stage;
  • notification contracts должны быть производными от normalized data и execution outcome;
  • contract changes должны обновляться здесь раньше, чем разрастутся implementation notes.

Дополнение для текущего Terry runtime:

  • persisted config contract должен быть устойчивым к JSONB evolution и backward-compatible migrations;
  • runtime lookup contract должен быть deterministic: в текущем baseline это вызов loader по data_source_id;
  • catalog metadata (workspace_id, domain_id, data_source_id, page_type, code_name) считается частью execution provenance contract.