← Все статьи

Маппинг данных между системами: как оформить спецификацию соответствий

· 8 мин чтения

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

Почти любая интеграция сводится к переводу данных с языка одной системы на язык другой. В CRM клиент — это contact с полями firstName и lastName, в учётной системе — Контрагент с полем Наименование, а в XML для налоговой — элемент СвФЛ с атрибутами. Правила такого перевода — маппинг — чаще всего живут в голове разработчика или в коде трансформации. Пока всё работает, это незаметно. Когда появляется расхождение данных, выясняется, что никто не может сказать, откуда в поле взялось значение. Разберём, как оформить маппинг так, чтобы он был понятен и разработчику, и тестировщику, и через год вам самим.

Что такое маппинг и зачем он отдельным документом

Маппинг данных (спецификация соответствий, mapping specification) — описание того, как каждое поле целевой структуры получается из полей источника: напрямую, через преобразование, справочник, константу или вычисление.

Зачем выделять его в отдельный артефакт, если есть контракты API обеих сторон:

  • Контракты описывают структуры, но не связь между ними. По двум схемам OpenAPI нельзя понять, что status: "A" в одной системе означает ACTIVE в другой.
  • Маппинг — основа для тестирования. Тестировщик проверяет преобразование по таблице, а не по коду.
  • Маппинг — основа для разбора инцидентов. Когда в целевой системе неверное значение, первый вопрос — по какому правилу оно получено.
  • Маппинг обсуждают с бизнесом. Владелец данных подтверждает, что «дата заключения договора» — это действительно дата подписания, а не дата регистрации в системе.

Структура таблицы маппинга

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

КолонкаЧто писать
№номер правила, на него ссылаются в задачах и дефектах
Целевое полепуть в целевой структуре: customer.contacts[].phone или XPath /Документ/СвФЛ/@ИНН
Тип и ограничения целитип, длина, формат, обязательность
Источникпуть в исходной структуре; несколько полей, если значение составное
Тип источникатип и формат исходного поля
Правилокак получается значение: «напрямую», «по справочнику», формула, условие
Если пусточто делать, если в источнике нет значения: пропустить поле, значение по умолчанию, ошибка
Примерзначение на входе → значение на выходе
Комментарийвопросы, ссылки на требования, кто подтвердил

Пример

Передача клиента из CRM (JSON) в учётную систему (XML):

№Целевое полеИсточникПравилоЕсли пустоПример
1/Контрагент/@Ид, строка(36), обяз.idнапрямуюошибка, сообщение не отправлять"c7a1…" → c7a1…
2/Контрагент/Наименование, строка(250), обяз.lastName, firstName, middleNameсклеить через пробел, пустые части пропустить, обрезать до 250ошибкаИванов, Иван, — → «Иванов Иван»
3/Контрагент/ВидЛица, перечисление, обяз.typeпо справочнику: person → ФЛ, company → ЮЛ, entrepreneur → ИПошибка"person" → ФЛ
4/Контрагент/ИНН, строка 10 или 12 цифрtaxIdубрать пробелы; проверить длину: 12 для ФЛ и ИП, 10 для ЮЛэлемент не передавать" 7701 234567 " → 7701234567
5/Контрагент/Телефон, 0..1phones[]первый телефон с isPrimary = true, иначе первый в списке; привести к формату +7XXXXXXXXXXэлемент не передавать["8 (900) 111-22-33"] → +79001112233
6/Контрагент/ДатаСоздания, xs:datecreatedAt (date-time, UTC)перевести в часовой пояс Москвы, взять датутекущая дата2026-10-05T22:30:00Z → 2026-10-06
7/Контрагент/Источник—константа CRM—CRM

Обратите внимание на правило 6: без него разработчик возьмёт дату из UTC, и клиенты, созданные поздно вечером, окажутся созданы «вчера» в учётной системе. Именно такие мелочи маппинг и должен фиксировать.

Виды правил

  • Прямое соответствие — значение переносится как есть. Даже здесь стоит проверить типы и длины: строка 500 символов в поле на 250 — уже правило (обрезать, отклонить?).
  • Преобразование формата — даты, телефоны, суммы (копейки в рубли), регистр, кодировки.
  • Справочное соответствие — перевод кодов одной системы в коды другой. Таблицу соответствия выносят отдельно, если значений больше пяти — в отдельный лист или справочник.
  • Константа — значение, которого нет в источнике, но которое требует цель.
  • Вычисление — сумма, количество, склейка, извлечение части строки.
  • Условие — «если тип = ЮЛ, то КПП из поля kpp, иначе не передавать».
  • Обогащение — значение, которого нет в сообщении, а берётся из другой системы или справочника по ключу. Это важно отметить отдельно: появляется зависимость от ещё одного источника.
  • Агрегация и разбиение — несколько записей источника в одну цель или наоборот.

Справочники и перекодировки

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

  • Полнота. Все ли значения источника имеют соответствие? Что делать с неизвестным значением: ошибка, значение по умолчанию, пропуск?
  • Однозначность. Если двум значениям источника соответствует одно значение цели, обратное преобразование станет невозможным — это нормально для односторонней интеграции, но опасно для двусторонней синхронизации.
  • Где живёт таблица. В коде, в конфигурации или в справочнике, который может менять пользователь? Кто её владелец?
  • Что при изменении справочника. В источнике появился новый статус — интеграция упадёт, пропустит запись или передаст значение по умолчанию? Узнает ли кто-нибудь об этом?
Статус в CRMСтатус в учётной системеКомментарий
lead— (не передавать)потенциальные клиенты в учёт не попадают
activeДействующий
suspendedДействующийв учётной системе нет приостановки; подтверждено владельцем данных
closedЗакрыт
любое другоеошибкасообщение в очередь разбора, уведомление дежурному

Пустые значения

Отдельная колонка «Если пусто» в таблице не случайна. Для каждого поля нужно различать:

  • поле отсутствует в источнике;
  • поле присутствует со значением null;
  • поле содержит пустую строку или строку из пробелов;
  • поле содержит значение-заглушку: "-", "0", "N/A", дата 1900-01-01.

И для каждого случая решить, что передаём в цель. Особенно важно при обновлении: «поле не пришло» обычно означает «не трогать», а «пришёл null» — «очистить». Если цель — XML, решение ещё и техническое: отсутствующий элемент, пустой элемент или xsi:nil.

Массивы и вложенные структуры

Правила для коллекций описывают на уровне коллекции, а затем — для полей её элементов:

  • сколько элементов допустимо в цели и что делать, если в источнике больше (взять первые N, отклонить);
  • как выбирать элемент, если в цели одно значение, а в источнике список (первый, основной, последний по дате);
  • порядок элементов в цели;
  • как сопоставлять элементы при обновлении: по идентификатору, по позиции или заменой списка целиком.

Для путей внутри массивов удобна запись с []: items[].price → Товары/Товар/Цена, с примечанием «для каждого элемента».

Ошибки и неполные данные

Маппинг должен описывать не только успешное преобразование, но и что происходит, когда оно невозможно:

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

Форма документа

Маппинг чаще всего ведут в таблице (Excel, Google Sheets, страница вики), и это нормально, если соблюдать несколько правил:

  • Версия и дата в заголовке, история изменений — отдельным листом или разделом.
  • Ссылки на контракты обеих сторон с версиями: маппинг составлен для OpenAPI v2.3 источника и XSD v1.7 цели.
  • Справочники перекодировок — отдельными листами, со ссылками из основной таблицы.
  • Открытые вопросы выделены цветом или отдельной колонкой, с ответственным.
  • Набор тестовых примеров — пары «входной документ → ожидаемый результат», включая граничные случаи.

Всё чаще маппинг хранят рядом с кодом в текстовом формате — Markdown-таблица или YAML — и версионируют в git вместе с контрактами. Тогда изменение маппинга проходит ревью так же, как изменение кода, и всегда видно, какая версия правил действовала на дату инцидента.

Как проверять маппинг

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

Типичные ошибки

  • Маппинг «по названиям полей» — поля с одинаковыми именами в разных системах означают разное (date — дата создания или дата документа?).
  • Нет правила для неизвестных значений — в источнике появился новый статус, интеграция молча передаёт пустоту.
  • Часовые пояса — дата смещается на сутки.
  • Обрезка без предупреждения — наименование организации теряет окончание, и документы не проходят сверку.
  • Маппинг не обновляется — код давно делает иначе, а документ остался в первой версии.
  • Нет примеров — формулировка «привести к формату телефона» понимается тремя разработчиками тремя способами.

Итог

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

Структуры обеих сторон удобно держать рядом: JSON Schema, XSD или OpenAPI, а примеры документов проверять в инструментах JSON и XML. Для быстрой проверки преобразований пригодятся гайды «JSON в XML» и «XML в JSON». Таблицу маппинга можно вести в Markdown прямо в проекте. О том, почему JSON и XML плохо стыкуются на уровне схем, — в статье «JSON Schema и XSD».