Содержание
  1. Кто заключает контракт
  2. Схема и семантика
  3. Качество и свежесть
  4. Учебный договор orders
  5. Три контрольных нарушения
  6. Версия и согласование изменений
  7. Связь с автоматической проверкой
  8. Частые вопросы
Справочник

Что такое data contract: договор о качестве данных

15 ноября 2026 · 8 минут чтения

Что такое data contract: договор о качестве данных — это письменное соглашение между производителем данных и их потребителями. В стандарте Open Data Contract Standard сказано: контракт определяет договор между производителем данных и потребителями. Документ фиксирует схему, семантику, качество, свежесть, владельца и порядок смены версий.

Кто заключает контракт

Стороны контракта — производитель данных и потребитель. В стандарте Open Data Contract Standard (ODCS) на сайте bitol-io.github.io прямо сказано: контракт определяет договор между производителем данных и потребителями. Производитель отвечает за публикацию и соблюдение обещанных условий, потребитель — за использование данных в рамках описанной семантики.

В учебном договоре orders_daily v1 роли распределены так: владелец — команда заказов, потребитель — аналитика. Владелец отвечает за поставку и за реакцию на нарушение. Потребитель получает описание полей и знает, что означает каждое число.

Роль владельца закреплена в самом документе. У каждого нарушения есть владелец реакции — это условие входит в учебный договор. Без имени владельца контракт превращается в описание таблицы, за которое никто не отвечает.

Документация Soda описывает библиотеку для проверки условий контрактов данных: она проверяет стандарты качества как можно раньше и чаще в конвейере, чтобы предотвратить негативные последствия для потребителей. Проверка идёт на стороне производителя, а результат видит потребитель.

Практический шаг: до написания текста договора назовите две стороны поимённо. Запишите, кто публикует данные, кто их читает и кто получает уведомление при сбое. Эти три имени — минимальный каркас соглашения.

Схема и семантика

Схема описывает структуру: имена полей, типы, обязательность, ограничения. Семантика объясняет смысл значений. В документации datacontract CLI сказано, что в контракте есть раздел schema для структуры и семантики данных, а также разделы service levels и quality с ожидаемой свежестью и числом строк.

В учебном договоре orders_daily v1 схема выглядит так:

Поле Тип Ограничение Смысл
order_id integer not null, unique идентификатор заказа
amount_rub decimal not null, >= 0 сумма заказа в рублях
status строка paid или refund состояние заказа
updated_at timestamp в UTC время обновления записи

Семантика в договоре сформулирована отдельной строкой: amount_rub означает сумму заказа в рублях, строки refund не входят в показатель paid_amount. Это предложение снимает главный источник расхождений между командами: одинаковое имя поля может означать разные величины.

Схема проверяет типы и ограничения. Смысл поля схема не проверяет: она не подтверждает, что amount_rub означает выручку. Семантику фиксируют словами в договоре и сверяют с потребителем при согласовании.

Практический шаг: рядом с каждым полем напишите одно предложение о смысле. Если предложение не помещается в строку, поле требует разделения или уточнения.

Качество и свежесть

Качество и свежесть — отдельные обещания. Документация Soda перечисляет стандарты, которым должны соответствовать новые данные: схема и тип колонки, свежесть, стандарты пропусков и валидности. Договор начинается с подготовки контракта, в котором эти стандарты зафиксированы.

Свежесть измеряется временем. В учебном договоре orders_daily v1 поставка описана так: ежедневно до 09:00 UTC. Это проверяемое обещание: у него есть событие (поставка файла) и граница времени.

Стандарт ODCS описывает свойства уровня сервиса через список пар ключ-значение. В документации указано, что у свойства есть имя, описание для людей и единица измерения по стандарту ISO: например, d или days для дней, y или yr для лет. Единица нужна там, где свойство её требует.

Обещание Что проверяем Как выглядит нарушение
Схема типы и ограничения полей поле стало NULL или появился дубликат ключа
Свежесть время поставки файл пришёл позже согласованной границы
Полнота число строк строк меньше ожидаемого
Валидность допустимые значения status вне списка paid или refund

Практический шаг: для каждого обещания напишите, какое событие считается нарушением и кто его разбирает. Обещание без описанной реакции остаётся пожеланием.

Учебный договор orders

Ниже — полный учебный текст договора orders_daily v1. Это человекочитаемый документ для согласования между командами. Он помогает договориться о полях, семантике и сроках.

ТЕКСТ22 строки
Договор orders_daily, версия 1
Владелец: команда заказов
Потребитель: аналитика

Поля:
order_id    — integer, not null, unique
amount_rub  — decimal, not null, >= 0
status      — paid или refund
updated_at  — timestamp в UTC

Семантика:
amount_rub — сумма заказа в рублях.
Строки refund не входят в показатель paid_amount.

Поставка: ежедневно до 09:00 UTC.
Смена валюты требует новой версии и уведомления потребителя.

Пример данных:
(1, 100, paid,   08:00Z)
(2, 40,  refund, 08:10Z)

Эталон: paid_amount = 100.

Две строки примера дают эталон: показатель paid_amount равен 100, потому что строка refund в него не входит. Этот эталон — точка отсчёта для контрольных проб.

datacontract CLI — открытый инструмент командной строки для работы с контрактами данных. Сам контракт остаётся соглашением, которое такой инструмент может проверять. Учебный текст выше остаётся человекочитаемым документом и не является исполняемым файлом Soda, ODCS или CLI.

Практический шаг: заведите договор отдельным файлом в репозитории команды и добавьте его в ревью изменений. Так правка полей проходит через согласование.

Три контрольных нарушения

Проверка договора строится на пробах. Каждая проба начинается от исходных двух корректных строк и меняет ровно одно условие. Результаты проб не складываются в одну мутировавшую таблицу.

Проба Что меняем Результат Реакция
A добавляем дубликат order_id = 1 unique FAIL карантин
B в первой строке amount_rub = NULL not null FAIL не считать нулём
C строки те же, файл доставлен в 10:30 UTC schema PASS, freshness FAIL разбор задержки

Проба A проверяет уникальность ключа. Дубликат идентификатора может размножить строки соединения и завысить суммы при агрегации, поэтому запись уходит в карантин.

Проба B проверяет обязательность поля. Пропуск в amount_rub нельзя заменять нулём: ноль искажает сумму заказов и выглядит как корректное значение.

Проба C проверяет свежесть. Схема проходит, потому что строки не изменились, а свежесть падает: файл пришёл позже согласованной границы.

Документация Soda описывает поведение при провале проверки: данные не соответствуют стандартам качества контракта и требуют разбирательства или карантина. Учебные пробы показывают, как это выглядит на двух строках.

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

Версия и согласование изменений

Версия — часть договора. В документации ODCS поле version описано как текущая версия контракта, а поле apiVersion — как версия стандарта, по которому контракт построен. Это два разных поля: одно относится к документу, другое к стандарту.

Изменения проходят согласование. В учебном договоре orders_daily v1 зафиксировано правило: смена валюты требует новой версии и уведомления потребителя. Смена валюты меняет смысл amount_rub, поэтому старое описание перестаёт быть верным.

Порядок согласования изменения:

  1. Опишите, что меняется: поле, тип, семантика или срок поставки.
  2. Определите, затрагивает ли изменение смысл данных для потребителя.
  3. При затрагивании смысла выпустите новую версию договора.
  4. Уведомите потребителя до вступления изменения в силу.
  5. Обновите контрольные пробы под новую версию.

Практический шаг: храните историю версий рядом с текстом договора. Потребитель должен видеть, какая версия действует сейчас и что изменилось.

Связь с автоматической проверкой

Контракт и валидатор связаны, но не совпадают. Документация Soda описывает библиотеку, которая выполняет проверки из контракта при каждом приёме или выпуске новых данных. Документация datacontract CLI описывает поддержку стандарта ODCS для проверки контрактов, подключения к источникам данных и запуска проверок схемы и качества.

Автоматическая проверка берёт из договора проверяемые условия: типы, ограничения, сроки. Адресата уведомления можно настроить по владельцу. Смысл показателя и достаточность реакции согласуют люди; произвольный текст договора сам не становится исполняемой проверкой.

Что даёт договор Что берёт автоматика
типы и ограничения полей проверки схемы
срок поставки проверка свежести
список допустимых значений проверка валидности
имя владельца адресат уведомления
смысл показателя согласование людьми; автоматизируется только формализованное правило

Практический шаг: начните с текста договора, затем перенесите проверяемые условия в инструмент. Синтаксис инструмента сверяйте по его собственной схеме: версии ODCS, Soda и CLI описываются отдельно и не смешиваются.

Частые вопросы

Что такое data contract простыми словами?
Это письменное соглашение между командой, которая публикует данные, и теми, кто их читает. В нём описаны поля, их смысл, сроки поставки и порядок действий при нарушении. Стандарт ODCS определяет контракт как договор между производителем данных и потребителями.

Чем контракт отличается от схемы таблицы?
Схема описывает типы и ограничения полей. Контракт добавляет семантику, свежесть, владельца и реакцию на нарушение. Схема не подтверждает, что поле означает выручку, и не проверяет, что файл пришёл вовремя.

Как выглядит data contract example?
Учебный договор orders_daily v1 описывает четыре поля: order_id, amount_rub, status, updated_at. Поставка идёт ежедневно до 09:00 UTC, строки refund не входят в показатель paid_amount. Две строки примера дают эталон paid_amount = 100.

Что происходит при нарушении контракта?
Проверка возвращает FAIL по конкретному условию. Документация Soda описывает два варианта реакции: разбирательство или карантин. В учебном договоре у каждого нарушения есть владелец реакции.

Нужна ли автоматическая проверка, если есть договор?
Договор фиксирует обещания, автоматика проверяет их при каждой поставке. Документация datacontract CLI описывает запуск проверок схемы и качества по контракту. Текст договора остаётся источником семантики и порядка реакции.

Читайте также

3 материала