Вложенный JSON в CSV: сначала выберите, что означает строка

Объект с массивом товаров нельзя однозначно превратить в плоскую таблицу. Одна строка может означать заказ целиком, отдельный товар или пару «заказ — товар». Neraviko не делает этот выбор за пользователя: вложенные объекты и массивы в JSON → CSV версии 1 отклоняются.

Начните с единицы строки

Синтетический вход:

[{"order_id":"A01","items":[{"name":"book","qty":2},{"name":"pen","qty":1}]}]

Прямой вызов json.to_csv возвращает NESTED_JSON_VALUE. Это проверено на локальной реализации версии 1. Переключение разделителя или отключение заголовка не решает проблему: внутри ячейки по-прежнему лежит массив.

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

Вариант: одна строка на позицию

Явно подготовьте плоский массив:

[{"order_id":"A01","item":"book","qty":2},{"order_id":"A01","item":"pen","qty":1}]

Откройте JSON → CSV, оставьте заголовок включённым, выберите запятую, LF и отключите последний перевод строки для точного сравнения. Проверенный результат:

order_id,item,qty
A01,book,2
A01,pen,1

Ответ — needs_review с CSV_TYPED_VALUES_SERIALIZED, потому что количество стало текстом. Количество строк увеличилось с одного заказа до двух позиций. Такое изменение должно быть записано в контракте, иначе получатель может ошибочно посчитать два заказа.

Устойчивый ключ родителя повторяется в каждой строке. Если в одном заказе допустимы две одинаковые позиции, добавьте идентификатор позиции или индекс согласно контракту. Пара order_id,item не обязательно уникальна.

Вариант: несколько связанных таблиц

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

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

Вариант: вложенность как строка

Иногда получатель явно требует JSON-текст в одной CSV-ячейке. Тогда предварительно сериализуйте вложенное значение в JSON-строку и передавайте конвертеру именно строку, а не массив. У принимающей системы должен быть отдельный шаг JSON-разбора этой колонки.

Двойные кавычки такой строки будут экранированы по правилам CSV. Принцип удвоения кавычек описан в RFC 4180, раздел 2, октябрь 2005; проверено 05.10.2026. Это упаковка вложенности в текст, не её автоматическое разворачивание.

Не соединяйте массив значений через запятую без соглашения. Тогда строка "red,blue" не позволит понять, были ли это два элемента или один элемент с запятой. Аналогично имена колонок вроде address.city требуют договорённости: точка может быть частью исходного ключа.

Не перемножайте независимые массивы случайно

Если у объекта одновременно есть товары и теги, их нельзя без решения разворачивать в одну таблицу. Две товарные позиции и три тега при соединении каждой позиции с каждым тегом дают шесть строк. Это корректное декартово сочетание только тогда, когда именно его запросил получатель. Иначе количество товара и повторённые показатели родителя могут увеличиться при суммировании.

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

Для контрольного набора нужны родитель без детей, родитель с одним ребёнком и родитель с несколькими детьми. Такой набор показывает, исчезают ли пустые родители и правильно ли сохраняются связи. Пример с одной непустой вложенностью этих ошибок не обнаружит, даже если полученный CSV выглядит ровным.

Перед конвертацией

• Сформулируйте единицу строки и ключ записи.
• Выберите плоские строки, связанные таблицы или JSON-текст в ячейке.
• Задайте правила пустых массивов, отсутствующих полей и null.
• Для всех объектов создайте один набор плоских колонок.
• Сверьте число родителей и детей до и после подготовки.
• Проверьте пробный импорт у получателя.

Подготовка плоской модели выполняется отдельно: версия 1 не содержит опции flatten. Ограничения экспорта — 5 000 строк, 256 колонок, лимит запроса 262 144 байта. Операция конвертации серверная; по её контракту сырые входы и выходы не сохраняются и не логируются по умолчанию. Для согласования модели достаточно искусственного заказа, подобного примеру выше.