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

Шаблоны контрактов

Готовые шаблоны для быстрого создания контрактов данных. Каждый шаблон содержит подробные комментарии и best practices.

Обзор

Каждый контракт данных состоит из 6 файлов, каждый из которых имеет свой шаблон:

Файл Шаблон Кто редактирует Когда меняется версия
contract.yaml contract-template.yaml Data Owner Minor (новые теги)
schema.avsc schema-template.avsc Application Developer Major/Minor (схема!)
quality_rules.yml quality_rules-template.yml QA Engineer Patch (новые правила)
sla.yml sla-template.yml Data Owner + SRE Patch (изменение SLA)
physical_layout.yml physical_layout-template.yml Data Engineer Не меняет версию
runbook.md runbook-template.md SRE Не меняет версию

Как создать контракт из шаблонов

Шаг 1. Создайте структуру

# Скопируйте шаблоны
mkdir -p contracts/domains/{namespace}/{entity}
cp contracts/templates/contract-template.yaml contracts/domains/{namespace}/{entity}/contract.yaml
cp contracts/templates/schema-template.avsc contracts/domains/{namespace}/{entity}/schema.avsc
cp contracts/templates/quality_rules-template.yml contracts/domains/{namespace}/{entity}/quality_rules.yml
cp contracts/templates/sla-template.yml contracts/domains/{namespace}/{entity}/sla.yml
cp contracts/templates/physical_layout-template.yml contracts/domains/{namespace}/{entity}/physical_layout.yml
cp contracts/templates/runbook-template.md contracts/domains/{namespace}/{entity}/runbook.md

Шаг 2. Заполните метаданные

Начните с contract.yaml — замените все {placeholder} на реальные значения.

Шаг 3. Определите схему

Заполните schema.avsc — определите поля, типы, обязательность.

Шаг 4. Задайте правила качества

Заполните quality_rules.yml — критичные проверки (error), предупреждения (warning), мониторинг (info).

Шаг 5. Настройте SLA

Заполните sla.yml — доступность, свежесть, retention, эскалация.

Шаг 6. Валидация

# Проверить контракт локально
pip install kruma-validator
python contracts/ci/validate_contract.py contracts/domains/{namespace}/{entity}/

contract.yaml

Основной файл контракта — бизнес-метаданные, владение, lineage, changelog.

Ключевые секции:

  • metadata — имя, namespace, описание, владелец, потребители, теги
  • schema — ссылка на Avro-схему
  • quality_rules — ссылка на правила качества
  • sla — ссылка на SLA
  • lineage — upstream-источники и downstream-потребители
  • changelog — история изменений контракта
Развернуть шаблон contract-template.yaml 
# Версии
spec_version: "1.0.0"
contract_version: "1.0.0"

metadata:
  name: "{entity}"
  namespace: "{namespace}"
  display_name: "{Название сущности}"
  description: |
    Краткое описание того, что представляют эти данные.

  owner:
    team: "{team-name}"
    email: "{team-name}@company.ru"
    mattermost: "{team-name}-alerts"

  systems:
    producer: "{Название системы-источника}"
    consumers:
      - name: "{Система-потребитель}"
        team: "{consumer-team}"
        criticality: "high"

  tags:
    - "{domain}"

schema:
  file: "./schema.avsc"
  format: "avro"

quality_rules:
  file: "./quality_rules.yml"
  enabled: true

sla:
  file: "./sla.yml"

physical_layout:
  file: "./physical_layout.yml"

runbook:
  file: "./runbook.md"

lineage:
  upstream:
    - system: "{Источник}"
      database: "{connection-string}"
      tables:
        - "{source_table}"
  downstream:
    - system: "{Назначение}"
      database: "{connection-string}"
      tables:
        - "{destination_table}"

changelog:
  - version: "1.0.0"
    date: "{YYYY-MM-DD}"
    author: "{email}"
    changes:
      - type: "initial"
        description: "Первоначальное создание контракта"
    breaking: false

schema.avsc

Apache Avro схема, определяющая структуру данных.

Ключевые элементы:

  • name — имя записи (PascalCase)
  • namespace — домен.сущность
  • fields — поля с типами, nullable-обёртки, logical types для дат
Развернуть шаблон schema-template.avsc 
{
  "type": "record",
  "name": "{EntityName}",
  "namespace": "{namespace}.{entity}",
  "doc": "{Описание entity}",
  "fields": [
    {
      "name": "{field_id}",
      "type": "string",
      "doc": "Уникальный идентификатор"
    },
    {
      "name": "{field_amount}",
      "type": "double",
      "doc": "Сумма/количество"
    },
    {
      "name": "{field_status}",
      "type": {
        "type": "enum",
        "name": "{EntityName}Status",
        "symbols": ["active", "inactive", "pending"]
      },
      "doc": "Статус записи"
    },
    {
      "name": "{nullable_field}",
      "type": ["null", "string"],
      "default": null,
      "doc": "Опциональное поле"
    },
    {
      "name": "created_at",
      "type": {"type": "long", "logicalType": "timestamp-millis"},
      "doc": "Дата и время создания (UTC)"
    }
  ]
}

quality_rules.yml

Правила валидации данных. Каждая запись проверяется при прохождении через Quality Validator.

Типы правил:

Тип Описание DMBOK-измерение
not_null Поле не должно быть пустым Полнота
unique Уникальность в рамках батча Уникальность
range Числовой диапазон Корректность
regex Соответствие паттерну Корректность
enum Допустимые значения Корректность
freshness Свежесть временной метки Своевременность
format Предопределённый формат (email, uuid) Корректность
custom Python-выражение Точность, Согласованность
Развернуть шаблон quality_rules-template.yml 
version: "1.0"

rules:
  # NOT NULL — обязательные поля
  - name: "id_not_null"
    field: "id"
    type: "not_null"
    severity: "error"
    message: "ID is required"

  # RANGE — числовой диапазон
  - name: "amount_positive"
    field: "amount"
    type: "range"
    min: 0
    severity: "error"
    message: "Amount must be non-negative"

  # ENUM — допустимые значения
  - name: "status_valid"
    field: "status"
    type: "enum"
    values: ["active", "inactive", "deleted"]
    severity: "error"
    message: "Invalid status"

  # FRESHNESS — свежесть данных
  - name: "data_freshness"
    field: "created_at"
    type: "freshness"
    max_age_minutes: 60
    severity: "error"
    message: "Data older than 1 hour"

  # UNIQUE — уникальность в батче
  - name: "id_unique_in_batch"
    field: "id"
    type: "unique"
    severity: "error"
    message: "Duplicate ID"

  # CUSTOM — бизнес-логика
  - name: "discount_not_exceed_amount"
    field: "discount"
    type: "custom"
    expression: "discount <= amount"
    severity: "error"
    message: "Discount exceeds amount"

sla.yml

Соглашения об уровне обслуживания: доступность, свежесть, retention, эскалация.

Ключевые секции:

  • availability — процент доступности и расписание
  • freshness — максимальный возраст данных, пороги алертов
  • response_time — SLA реагирования на инциденты по приоритетам
  • retention — политики хранения по слоям (Kafka → DWH → Archive)
  • escalation — матрица эскалации
Развернуть шаблон sla-template.yml 
version: "1.0.0"

availability:
  target: "99.9%"
  schedule:
    weekdays: "00:00-23:59"
    weekends: "00:00-23:59"

freshness:
  max_age: "PT1H"          # ISO 8601: 1 час
  alert_threshold: "PT2H"
  critical_threshold: "PT4H"

response_time:
  critical: "PT15M"
  high: "PT1H"
  medium: "PT4H"
  low: "P1D"
  recovery_time:
    target: "PT2H"
    maximum: "PT4H"

retention:
  raw:
    duration: "P7D"
  prod:
    duration: "P30D"
  dlq:
    duration: "P90D"
  dwh:
    hot: { duration: "P1Y", storage_class: "ssd" }
    warm: { duration: "P3Y", storage_class: "hdd" }
    cold: { duration: "P7Y", storage_class: "archive" }

escalation:
  level_1:
    team: "{your-team}"
    mattermost: "{alerts-channel}"
  level_2:
    team: "data-platform"
    mattermost: "data-platform-oncall"
  level_3:
    team: "engineering-leadership"

physical_layout.yml

Конфигурация физического хранения для Apache Iceberg + Parquet. Этот файл не влияет на версию контракта.

Ключевые секции:

  • iceberg — конфигурация таблицы Iceberg (каталог, format version)
  • partitioning — стратегия партиционирования (hidden partitioning)
  • sort_order — порядок сортировки для ускорения запросов
  • parquet — компрессия, bloom-фильтры, dictionary encoding
  • compaction — настройки объединения мелких файлов
  • query_patterns — типичные запросы для оптимизации
Развернуть шаблон physical_layout-template.yml 
version: "1.0"

iceberg:
  format_version: 2
  catalog:
    type: "gravitino"
    uri: "http://gravitino-server:8090"
    warehouse: "s3://data-lake/warehouse"

partitioning:
  strategy: "iceberg_hidden"
  spec:
    - source_column: "<timestamp_field>"
      transform: "day"

sort_order:
  fields:
    - column: "<filtered_column>"
      direction: "asc"
    - column: "<timestamp_column>"
      direction: "desc"

parquet:
  compression:
    codec: "zstd"
    level: 3
  bloom_filters:
    - column: "<id_column>"
      fpp: 0.01

runbook.md

Операционный runbook для реагирования на инциденты. Содержит все необходимые процедуры для дежурных инженеров.

Ключевые секции:

  • Обзор и SLA
  • Контакты и матрица эскалации
  • Топики Kafka и endpoints
  • Типичные инциденты с пошаговыми инструкциями
  • Ошибки валидации и правила
  • Процедуры отката
  • Обработка DLQ
  • Процедуры обслуживания

Best Practice

Runbook должен позволять новому инженеру диагностировать проблему и начать исправление в течение 15 минут без обращения к коллегам.

Примеры реальных контрактов

Посмотрите, как шаблоны используются на практике:

  • sales/orders

    Полный пример с PII, 8 правилами качества, SLA 99.9%

  • warehouse/inventory

    Real-time данные, свежесть 5 минут, consistency checks

  • aviation/flights

    Демо-контракт с геоданными и ADS-B

Дополнительные материалы