TOON на практике в 1С: модуль «Трансформер» для конвертации JSON/XML/CSV/TOON

В типичных интеграциях на 1С быстро возникает две боли:

• Входные данные приходят «как есть» (XML, JSON, CSV) и их нужно привести к привычным структурам/массивам.

• Данные нужно отправлять наружу или в LLM компактно, чтобы не потерять контекст и не платить за «лишний синтаксис».

Для этого я собрал модуль «Трансформер» — один общий модуль, который умеет читать и писать несколько форматов, а также напрямую конвертировать строку из одного формата в другой.

1) Зачем модуль, если в 1С уже есть JSON и XML

Встроенные средства платформы действительно закрывают базовые сценарии (прочитать JSON, записать JSON, прочитать XML через ЧтениеXML). Проблема начинается там, где форматов несколько, а требования к результату одинаковые: на входе всегда строка, на выходе всегда «структура данных 1С» (Структура/Массив/Соответствие/примитивы), плюс нужна обратная операция «данные → строка».

Ещё одна практическая проблема — «прикладная форма данных». Например, результаты запросов и табличные отчёты проще жить в ТаблицаЗначений, а LLM удобнее кормить табличным видом (TOON) или хотя бы плоским CSV. В итоге приходится постоянно писать одно и то же: выгрузить таблицу, нормализовать типы, экранировать строки, подобрать разделители, построить заголовки.

«Трансформер» решает именно это:

• Даёт единый API: Прочитать() / Записать() / Конвертировать().

• Даёт мосты с ТаблицаЗначений (в TOON и CSV) без ручной обвязки.

• Добавляет TOON как формат «данные для промпта», где ключи не повторяются в каждой строке.

2) Что умеет «Трансформер» и как он хранит данные

Поддерживаемые форматы

На текущем этапе модуль работает с четырьмя форматами:

• JSON — через встроенные средства платформы.

• XML — через ЧтениеXML/Запись строкой.

• CSV — простой «табличный» формат для обмена с Excel и внешними системами.

• TOON — компактная текстовая нотация, удобная для LLM и для передачи больших табличных массивов.

С точки зрения вызывающего кода это выглядит одинаково: вы передаёте строку и формат, получаете «данные 1С».

Данные = Трансформер.Прочитать(СтрокаВхода, "XML"); 
СтрокаTOON = Трансформер.Записать(Данные, "TOON");

Единый API

В модуле есть три основных метода:

Данные = Трансформер.Прочитать(Строка, Формат, Параметры);
Строка = Трансформер.Записать(Данные, Формат, Параметры);
Результат = Трансформер.Конвертировать(Строка, ФорматИсточник, ФорматПриёмник);

Ключевая мысль: в прикладном коде вы больше не думаете, «какой парсер звать» — это решается внутри, а вы получаете одинаковый тип результата.

Автотипизация

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

• true/false/yes/no → Булево.

• null/nil/~ → Null.

• Числа → Число (в том числе с научной записью).

• Даты ISO вида → Дата.

Это не «идеальная» типизация (и не должна ей быть), но она сильно уменьшает количество ручного кода «если похоже на число — преобразуй».

XML: атрибуты, текст и безопасные имена ключей

Самая коварная часть XML в 1С — имена. В XML легальны дефисы, двоеточия, точки и многое другое, а в именах ключей Структуры 1С такие символы приводят к ошибкам «неправильное имя атрибута структуры».

В модуле решено так:

• Любое имя элемента/атрибута экранируется в безопасный ключ: - : . / пробел заменяются на _.

• Если имя начинается с цифры, добавляется префикс n.

• Атрибуты кладутся с префиксом attr_.

• Текстовое содержимое узла, если одновременно есть атрибуты или дочерние элементы, кладётся в text_.

Пример:

<Employee id="emp-001" status="active">Иван</Employee>

Станет (логика хранения):

• attr_id = "emp-001"

• attr_status = "active"

• text_ = "Иван"

Это не «каноническая» XML модель, а практичная структура, чтобы можно было без падений и без сюрпризов прогнать любой XML и дальше преобразовывать в другие форматы.

TOON: табличные массивы и компактность

TOON в модуле нужен для двух задач:

1. быстро и компактно сериализовать большие массивы однотипных объектов (табличные данные);

2. держать в одном документе и «инструкции», и «данные», не распухая как JSON.

Табличный массив выглядит так:

products{name,sku,price}:
  "Лицензия 1С",LIC-10,85000
  "Поддержка",SUP-12,120000
  "Сервер",SRV-01,450000

Внутри модуля табличный режим включается, когда массив однороден (одинаковые ключи и примитивные значения без вложенных объектов/массивов). Если массив неоднородный — сериализация переходит в «список объектов».

3) Установка и быстрый старт

Установка (минимум действий)

1. Создайте общий модуль Трансформер.

2. Включите свойства: Сервер и Вызов сервера.

3. Вставьте код модуля.

Модуль не требует БСП, внешних компонент и сторонних библиотек — всё на встроенных объектах и обычном коде.

Первый тест: XML → TOON

Берём строку XML (можно из HTTP ответа, файла или просто из макета), и конвертируем:

СтрокаTOON = Трансформер.Конвертировать(СтрокаXML, "XML", "TOON");
Сообщить(СтрокаTOON);

Если XML содержит атрибуты с дефисами/двоеточиями (xmlns:xsi, id="org-001" и т.п.), модуль не упадёт: имена будут экранированы.

JSON → красивый JSON (форматирование)

Чтобы получать читаемый JSON (для логов и отладки), достаточно параметра Форматировать:

Парам = Новый Структура("Форматировать", Истина);
СтрокаJSON = Трансформер.Записать(Данные, "JSON", Парам);

ТаблицаЗначений → TOON

Очень частый сценарий: выгрузили запрос, хотим «упаковать» его в TOON.

Таблица = Запрос.Выполнить().Выгрузить(); 
СтрокаTOON = Трансформер.ТаблицаВТООН(Таблица, "data", ",");

Получится табличный массив с заголовком (имена колонок) и строками значений.

4) Практические кейсы (взял и применил)

Кейс A: подготовка контекста для LLM

Сценарий: есть список товаров/заказов/контрагентов, модель должна ранжировать, найти аномалии, дать рекомендации. Если отдать JSON «как есть», он быстро раздувается, а в контексте остаётся мало строк.

Решение: данные — в TOON табличным массивом, а инструкция — обычным объектом.

request: 
 task: "Найди топ-10 позиций по марже и укажи риски" 
 output: 
  format: "markdown" 
 currency: "RUB" 
 items{sku,name,price,cost,stock}: 
  A1,"Товар 1",1000,600,20 
  A2,"Товар 2",850,900,5 
  A3,"Товар 3",1200,700,0 
  A4,"Товар 4",500,200,120 
  A5,"Товар 5",1500,800,10

В 1С это обычно выглядит так:

Т = Запрос.Выполнить().Выгрузить();
TOON = Трансформер.ТаблицаВТООН(Т, "items");

Преамбула = "request:" + Символы.ПС
    + "  task: \"Найди топ-10 позиций по марже и укажи риски\"" + Символы.ПС
    + "  output:" + Символы.ПС
    + "    format: \"markdown\"" + Символы.ПС
    + "  currency: \"RUB\"" + Символы.ПС;

Промпт = Преамбула + TOON;

Кейс B: XML от внешней системы → JSON для фронта

Часто внешние системы по старинке дают XML, а фронт или шлюз ожидает JSON. «Трансформер» позволяет сделать конвертацию в одну строку:

ОтветJSON = Трансформер.Конвертировать(ОтветXML, "XML", "JSON", , Новый Структура("Форматировать", Истина));

За счёт экранирования имён модуль переживает «неудобные» XML атрибуты и имена элементов.

Кейс C: CSV импорт/экспорт без боли

CSV живуч по одной причине: он прост. В модуле есть:

• CSVВТаблицу() — превращает CSV в ТаблицаЗначений.

• ТаблицаВCSV() — выгружает ТаблицаЗначений в CSV.

CSV = Трансформер.ТаблицаВCSV(Таблица, ";", Истина);
Таблица2 = Трансформер.CSVВТаблицу(CSV, ";", Истина);

Если нужно — можно менять разделитель (запятая, точка с запятой) и управлять наличием заголовков.

Кейс D: TOON → ТаблицаЗначений (обратный ход)

Это полезно, когда вы:

• храните «настройки/снимки данных» в TOON;

• получаете от модели табличный ответ (схема + строки);

• хотите быстро превратить это в ТаблицаЗначений.

Таблица = Трансформер.ТООНВТаблицу(СтрокаTOON);

Модуль распознаёт «табличный массив» и строит таблицу по заголовку.

Кейс E: диагностика проблемных входных данных

Когда интеграция падает, нужно быстро понять: что пришло на вход и где ломается типизация/парсинг. Здесь помогает подход «всё через единый интерфейс»:

1. Прочитали как есть → получили данные 1С.

2. Сразу записали в JSON с форматированием → удобно смотреть в логах.

3. Или записали в TOON → удобно смотреть табличные массивы.

Д = Трансформер.Прочитать(СтрокаВхода, ФорматИсточник);
Сообщить(Трансформер.Записать(Д, "JSON", Новый Структура("Форматировать", Истина)));

5) Ограничения, договорённости и дальнейшее развитие

Ограничения (честно)

1. Экранирование имён в XML — это компромисс. Мы сохраняем «читабельные» ключи в Структуре 1С и не падаем на : и -, но при обратной записи в XML восстановить исходное имя один в один нельзя без отдельной карты соответствия.

2. TOON хорошо работает на однородных массивах примитивов. Если в массиве начинают появляться вложенные структуры или «плавающий набор полей», модуль переключается на режим неоднородного массива — это нормальное поведение, но компактность уже будет ниже.

3. CSV не любит сложные значения. Если в ячейках много переносов строк и кавычек, потребуется аккуратное экранирование и строгое соблюдение правил импорта/экспорта.

Практические договорённости (чтобы не было сюрпризов)

Рекомендую заранее зафиксировать в проекте:

• единый разделитель для TOON/CSV (, или ;),

• правила кавычек и экранирования,

• формат дат (лучше ISO),

• список спец литералов (null/true/false).

Тогда модуль становится предсказуемым «промежуточным представлением данных» между интеграциями, таблицами и промптами.

Идеи для развития

Если будет интерес к развитию, логичные следующие шаги:

• режим «строгой схемы» для TOON (валидация числа колонок и типов по заголовку),

• опциональная карта оригинальных XML имён (для точной обратной записи),

• потоковая обработка больших массивов (чтобы не держать всё в памяти),

• дополнительные форматы (например, YAML) или профили (разные правила типизации).

Если нужно — в следующей статье разберём сам модуль по частям: как устроен парсер TOON, как определяется однородность массива, где и зачем делается экранирование XML имён, и как безопасно включить это в реальный контур интеграции.

Дополнение: параметры и тонкая настройка

Хотя базовый сценарий обычно укладывается в один вызов Конвертировать(), в реальной жизни полезно уметь «подкрутить» поведение чтения/записи.

Параметры JSON

• Форматировать (Булево): включает переносы строк и отступы при записи, удобно для логов и отладки.

• ПрочитатьВСоответствие (Булево): при чтении позволяет получать объекты в Соответствие вместо Структуры (актуально, если вы любите ключевой доступ как к map).

Пример:

ПарамЧт = Новый Структура("ПрочитатьВСоответствие", Истина);
Д = Трансформер.Прочитать(СтрокаJSON, "JSON", ПарамЧт);

ПарамЗап = Новый Структура("Форматировать", Истина);
Красиво = Трансформер.Записать(Д, "JSON", ПарамЗап);

Параметры CSV

CSV в модуле — это сознательно простой, «приземлённый» формат. Управляется двумя вещами:

• Разделитель (Строка): ; по умолчанию, но можно поставить ,.

• ЕстьЗаголовки / СЗаголовками (Булево): считать/писать первую строку как имена колонок.

Пример импорта файла, где разделитель — запятая и нет заголовков:

Парам = Новый Структура;
Парам.Вставить("Разделитель", ",");
Парам.Вставить("ЕстьЗаголовки", Ложь);

МассивСтрок = Трансформер.Прочитать(СтрокаCSV, "CSV", Парам);

Параметры XML (запись)

При записи XML можно управлять именами узлов:

• КорневойЭлемент — имя корня.

• ЭлементМассива — имя элемента для значений массива.

• Форматировать — добавлять отступы и переносы строк.

Пример:

Парам = Новый Структура;
Парам.Вставить("КорневойЭлемент", "payload");
Парам.Вставить("ЭлементМассива", "row");
Парам.Вставить("Форматировать", Истина);

XML = Трансформер.Записать(Данные, "XML", Парам);

TOON: выбор разделителя

Для TOON обычно достаточно одного параметра:

• Разделитель (Строка): по умолчанию запятая.

Если ваши строки часто содержат запятые (например, наименования с перечислениями), можно перейти на ; и жить спокойнее:

Парам = Новый Структура("Разделитель", ";");
TOON = Трансформер.Записать(Данные, "TOON", Парам);

Ещё немного практики: сложный XML и что получается на выходе

Чтобы было понятнее, как модуль «приземляет» XML в безопасную структуру 1С, приведу небольшой (но показательный) фрагмент:

<Order id="ord-10" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Customer type="vip">ООО "Рога и Копыта"</Customer>
  <Items>
    <Item sku="A-1">Товар 1</Item>
    <Item sku="B-2">Товар 2</Item>
  </Items>
</Order>

После чтения:

• attr_id сохранит исходное значение ord-10.

• attr_xmlns_xsi позволит не падать на двоеточии в имени атрибута.

• Customer.attr_type = "vip", а текст клиента окажется в Customer.text_.

• Items.Item станет массивом из двух элементов (потому что Item повторяется).

Почему это удобно: дальше можно без дополнительных преобразований сделать XML → TOON, XML → JSON, или встроить эти данные в свою бизнес логику.

Производственные мелочи, которые экономят время

1) Логи в едином формате

Если вы пишете интеграцию, крайне полезно хранить «как пришло» и «как разобралось». Самый практичный паттерн:

• Сохранили исходную строку (XML/JSON/CSV) в регистр сведений или файл.

• Прочитали в данные 1С.

• Записали эти данные в форматированный JSON для диагностики.

Д = Трансформер.Прочитать(ИсходнаяСтрока, Формат);
Диаг = Трансформер.Записать(Д, "JSON", Новый Структура("Форматировать", Истина));

Так проще искать расхождения по ключам, массивам и типам.

2) Контроль объёма данных для LLM

Даже TOON не спасёт, если вы бездумно выгрузите «всё и сразу». Практика показывает, что лучше:

• резать данные по времени/периоду,

• ограничивать количество строк (top N),

• явно выбирать поля (только то, что влияет на решение),

• выносить справочники в отдельные блоки.

TOON здесь помогает тем, что вы можете передать больше строк на том же лимите, но дисциплина «что именно отправляем» всё равно важнее.

3) Обратимость и контракты

Если вы планируете цикл «в систему → LLM → обратно в систему», заранее определите контракт ответа:

• какие поля должны быть в табличном ответе,

• как обозначается null,

• какой разделитель используется,

• как экранируются кавычки.

Тогда TOON → ТаблицаЗначений становится почти механической операцией.