Как преобразовать вложенный JSON в CSV без ошибок

Florian Poullin
Florian Poullin
17 мин чтения
Преобразуйте вложенный JSON в CSV
Как преобразовать вложенный JSON в CSV без ошибок
Оглавление
  1. Пример вложенного JSON-файла
  2. Преобразование вложенного JSON в CSV в Datablist
  3. Как выбрать правильный узел строк
  4. Как развернуть вложенные объекты JSON
  5. Как обрабатывать массивы внутри строк JSON
  6. Настройка параметров CSV
  7. Проверка и скачивание CSV
  8. Ожидаемая структура CSV
  9. Когда использовать этот процесс
  10. Решение проблем при преобразовании JSON в CSV
  11. Что происходит в браузере
  12. Заключение
  13. FAQ

Чтобы преобразовать вложенный JSON в CSV, воспользуйтесь онлайн-конвертером JSON в CSV, который позволяет выбрать, какой массив JSON станет строками CSV. Этот выбор важнее, чем может показаться. Реальные JSON-экспорты часто начинаются с метаданных, параметров пагинации или объектов-обёрток, а нужные записи находятся по пути вроде results, data.items или payload.records.

Обычно при преобразовании JSON в CSV нужно принять три решения:

  • Какой массив должен стать строками?
  • Какие поля вложенных объектов должны стать столбцами?
  • Какие массивы следует объединить, сохранить как JSON или развернуть в отдельные строки?

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

📌 Коротко о главном

Сначала определите, что должна представлять одна строка CSV. В нашем примере одна строка соответствует одной компании, поэтому узел строк — $.results. Затем можно развернуть метрики компании и решить, что делать с массивами вроде contacts и tags.

В этом руководстве используется вложенный JSON-экспорт с 20 000 записями о компаниях в массиве results. Тот же процесс подходит для ответов API, результатов парсинга, журналов вебхуков, экспорта из CRM и данных маркетплейсов, где полезные записи находятся не в корне JSON.

Быстрые ссылки:

Пример вложенного JSON-файла

Представим большой JSON-экспорт из API или инструмента для парсинга. Файл занимает около 8,8 МБ и содержит 20 000 записей в массиве верхнего уровня results.

Корневой объект выглядит так:

json
{
"meta": {
"generatedAt": "2026-07-04T10:00:00Z",
"source": "stress_test"
},
"results": [
{
"id": 0,
"name": "NbDXeG4Gyg",
"website": "https://example-0.com",
"contacts": [
{
"name": "Ava Martin",
"emails": [
"ava@example-0.com"
],
"phones": [
"+1 555 0100"
]
},
{
"name": "Noah Lee",
"emails": [
"noah@example-0.com"
],
"phones": []
}
],
"tags": "enterprise",
"metrics": {
"employees": 124,
"revenue": {
"amount": 476171,
"currency": "USD"
}
},
"createdAt": "2026-06-25T09:12:00Z"
},
{
"id": 1,
"name": "DwwGmkzmBi",
"website": "https://example-1.com",
"contacts": [
{
"name": "Mia Chen",
"emails": [
"mia@example-1.com"
],
"phones": [
"+1 555 0101"
]
}
],
"tags": [
"saas",
"mid-market"
],
"metrics": {
"employees": 47,
"revenue": null
},
"createdAt": "2026-06-26T14:33:00Z"
}
]
}

Именно с такими файлами у простых конвертеров возникают проблемы. Записи находятся не в корневом объекте, а внутри results. Кроме того, они содержат вложенные объекты и массивы, значения разных типов — строки и массивы, — а также значения null и даты.

🔍 Почему этот файл хорошо подходит для проверки

Плоский массив JSON позволяет проверить только самый простой сценарий. Этот файл охватывает ситуации, которые действительно важны в реальных экспортных данных: метаданные в объекте-обёртке, вложенный массив записей, поля-объекты, поля-массивы, значения разных типов и null.

Вот как выглядят первые строки:

СтрокаТип websiteКоличество контактовТип tagsВыручка
0Строка2СтрокаСумма и валюта
1Строка2МассивNull
2Массив1МассивNull

В итоговом CSV одна строка должна соответствовать одной компании. Полезные поля, такие как id, name, website, employees, amount, currency и createdAt, должны стать столбцами. Для полей вроде contacts и tags нужно определить, какую часть их структуры сохранить.

Преобразование вложенного JSON в CSV в Datablist

Откройте конвертер JSON от Datablist. JSON можно вставить в редактор или загрузить как файл .json.

Конвертер JSON в CSV от Datablist с вариантами вставки и загрузки
Конвертер JSON в CSV от Datablist с вариантами вставки и загрузки

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

После загрузки JSON Datablist анализирует его структуру и ищет массивы объектов. Корнем JSON может быть как массив, так и объект. Затем сервис проверяет вложенные пути, например $.results, $.data.items, и более глубокие массивы.

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

В нашем примере правильный узел строк:

$.results

Мы выбираем $.results, потому что хотим получить по одной строке на компанию. Каждый элемент этого массива станет отдельной строкой CSV.

Выбор массива results в качестве узла строк CSV
Выбор массива results в качестве узла строк CSV

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

⚠️ Смена узла строк меняет набор данных

$.results и $.results[].contacts — допустимые узлы строк, но они создают разные CSV-файлы. Выбирайте родительский массив, если каждая строка должна представлять компанию. Выбирайте дочерний массив, если набором данных являются вложенные элементы.

В этой статье мы сохраняем родительский узел строк:

  • $.results — одна компания или один аккаунт в строке.
  • $.results[].contacts — один контакт в строке.

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

Как выбрать правильный узел строк

Узел строк — это массив JSON, элементы которого становятся строками CSV.

Самые распространённые варианты:

Путь JSONКогда подходит
$.resultsЗаписи находятся по ключу results
$.data.itemsAPI помещает записи в объект data
$.payload.recordsВебхук или внутренняя система помещает записи в payload
$.results[].contactsКаждый вложенный контакт должен стать отдельной строкой

Перед выбором стоит ответить на один вопрос: что должна представлять одна строка?

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

Звучит просто, но этот выбор определяет структуру всего CSV.

При выборе $.results в CSV сохраняется контекст компании. Поле contacts остаётся вложенным значением в строке компании, если вы не решите обработать контакты отдельно. При выборе $.results[].contacts CSV превращается в список контактов, но поля родительской компании не добавляются автоматически — если только такая функция не появится в будущей версии конвертера.

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

Как развернуть вложенные объекты JSON

При работе с вложенными объектами CSV-конвертер должен уметь больше, чем просто преобразовывать формат файла.

В нашем примере metrics — это объект:

json
{
"metrics": {
"employees": 124,
"revenue": {
"amount": 476171,
"currency": "USD"
}
}
}

В электронной таблице не нужна одна ячейка metrics, содержащая JSON-объект. Гораздо удобнее получить столбцы, по которым можно фильтровать и сортировать данные:

  • employees
  • amount
  • currency

Datablist обнаруживает пути к вложенным объектам и позволяет выбрать, какие из них развернуть. Полезные скалярные поля лучше разворачивать: с ними удобнее работать в инструментах для CSV.

Обнаруженные поля вложенных объектов в конвертере JSON в CSV
Обнаруженные поля вложенных объектов в конвертере JSON в CSV

В нашем примере разворачиваются:

  • metrics.employees в employees
  • metrics.revenue.amount в amount
  • metrics.revenue.currency в currency
Настройки разворачивания вложенных объектов metrics и revenue
Настройки разворачивания вложенных объектов metrics и revenue

Ожидаемая структура CSV на уровне компаний выглядит так:

Столбец CSVИсходное значение
idИдентификатор строки
nameНазвание компании или аккаунта
websiteСайт, объединённый массив или JSON-строка — в зависимости от настроек
contactsВложенные данные контактов при экспорте одной компании на строку
tagsОбъединённые метки или исходный текст
employeesЗначение из metrics.employees
amountЗначение из metrics.revenue.amount
currencyЗначение из metrics.revenue.currency
createdAtИсходная или отформатированная дата

Для первого экспорта лучше использовать понятные названия столбцов. Если одинаковые названия встречаются в разных объектах, проверьте предпросмотр перед скачиванием. Например, billing.amount и revenue.amount не должны без проверки превращаться в два неоднозначных столбца amount.

💡 Оптимальный подход к разворачиванию

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

Как обрабатывать массивы внутри строк JSON

Для массивов нужно принять отдельное решение: ячейка CSV содержит текст, а массивы JSON могут иметь разный смысл.

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

Для нашего примера рекомендуются такие настройки:

ПолеРекомендуемая обработкаПочему
tagsОбъединить значенияТеги — простые метки, которые удобно хранить в одной ячейке
websiteОбъединить значения или сохранить JSONОбъедините для удобства чтения; сохраните JSON, если важны разные типы значений
contactsСохранить как JSON для строк компанийУ объектов контактов есть собственные вложенные поля
contactsИспользовать $.results[].contacts как узел строк для экспорта контактовПодходит, когда целевой результат — список контактов

Datablist предлагает несколько вариантов обработки массивов: объединение значений, сохранение массивов как JSON-строк, выбор первого элемента и индивидуальная настройка каждого случая.

Базовый подход прост:

  • Объединяйте простые массивы, например теги.
  • Сохраняйте структурированные массивы как JSON-строки, если важно не потерять их структуру.
  • Берите только первый элемент, если у него есть очевидный смысл — например, основной email.
  • Меняйте узел строк, если каждый элемент массива должен стать отдельной строкой.

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

Для экспорта контактов следует выбрать $.results[].contacts. Тогда CSV будет содержать столбцы уровня контакта:

Столбец CSVИсходное значение
nameИмя контакта
emailsОбъединённый список email или JSON-строка
phonesОбъединённый список телефонов или JSON-строка

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

Настройка параметров CSV

После выбора узла строк и настройки разворачивания объектов и обработки массивов укажите параметры итогового CSV.

Обычно можно начать с таких настроек:

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

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

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

Перед скачиванием проверьте оба варианта предпросмотра:

  • Предпросмотр таблицы помогает проверить строки и столбцы.
  • Предпросмотр исходного CSV позволяет проверить разделители, кавычки и переносы строк.

🔑 Проверяйте данные перед экспортом

Предпросмотр помогает вовремя заметить неверный узел строк, отсутствующие столбцы, неудобные массивы и проблемы с разделителем. Лучше потратить на это 30 секунд, чем потом исправлять неудачный импорт в CRM или электронную таблицу.

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

Проверка и скачивание CSV

Перед скачиванием пройдитесь по этому списку:

  • Соответствует ли количество строк выбранному узлу строк?
  • Представляют ли строки нужную сущность?
  • Разделены ли employees, amount и currency на полезные столбцы?
  • Удобно ли читать массивы и сохранены ли они как JSON там, где важна структура?
  • Отображаются ли значения null для выручки как пустые или достаточно понятные значения?
  • Подходят ли даты для электронной таблицы или инструмента импорта?
  • Используется ли ожидаемый разделитель в предпросмотре исходного CSV?
Скачивание CSV после проверки преобразованной таблицы
Скачивание CSV после проверки преобразованной таблицы

После этого скачайте CSV. Если вы загрузили файл, имя скачиваемого файла может формироваться на основе исходного — так проще отследить происхождение CSV.

После экспорта откройте файл в CSV editor от Datablist, Excel, Google Sheets или другом инструменте для работы с данными. В Datablist можно продолжить очистку, фильтрацию, дедупликацию, обогащение или перевод данных. Если вы создали несколько экспортов, можно сравнить два CSV-файла. Если файл слишком велик для другого инструмента, разделите CSV на несколько файлов меньшего размера.

Ожидаемая структура CSV

При выборе $.results каждая строка итогового файла соответствует одной компании или одному аккаунту.

Столбец CSVПуть JSON внутри строкиОжидаемое значение
id$.idИдентификатор строки
name$.nameНазвание компании или аккаунта
website$.websiteСайт в виде строки, объединённого массива или JSON-строки
contacts$.contactsОбъединённый массив контактов или массив в формате JSON, если одна строка соответствует одной компании
tags$.tagsОбъединённые метки или исходная строка
employees$.metrics.employeesКоличество сотрудников
amount$.metrics.revenue.amountСумма выручки, если указана
currency$.metrics.revenue.currencyВалюта выручки, если указана
createdAt$.createdAtИсходная или отформатированная дата

При выборе $.results[].contacts каждая строка итогового файла соответствует одному контакту.

Столбец CSVПуть JSON внутри контактаОжидаемое значение
name$.nameИмя контакта
emails$.emailsОбъединённый список email или JSON-строка
phones$.phonesОбъединённый список телефонов или JSON-строка

Оба варианта корректны, но отвечают на разные задачи.

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

Когда использовать этот процесс

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

Типичные примеры:

  • Ответы API с метаданными, пагинацией и вложенным массивом results.
  • Результаты парсинга через API, содержащие объявления, товары, контакты или события.
  • Экспорт из CRM и RevOps-систем, где компании содержат контакты, теги, метрики и пользовательские поля.
  • Экспорт с маркетплейсов или из каталогов товаров с вариантами, ценами, категориями и поставщиками.
  • Журналы вебхуков, где события вложены в payload.
  • Процессы локализации, в которых нужно перевести полученный CSV.

Схема всегда одна: найдите массив, который должен стать строками, разверните нужные поля объектов, выберите способ обработки массивов и проверьте результат перед экспортом.

Решение проблем при преобразовании JSON в CSV

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

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

Правильное количество строк не гарантирует, что каждое поле стало столбцом. Datablist определяет столбцы по первым 50 записям выбранного узла строк, а в предпросмотре таблицы отображается до 100 строк. Например, если поле optional_note присутствует только в записи 51, CSV может содержать все 51 строку, но не включать это поле.

Проверьте исходные данные на наличие полей, которые появляются только в более поздних записях, и сравните их с заголовками результата. В приведённом примере создайте копию JSON и переместите запись с optional_note в первые 50, сохранив её ID и значения. Выполните преобразование ещё раз и убедитесь, что появился нужный заголовок, а примечание из записи 51 сохранилось в скачанном CSV. Поскольку перестановка меняет порядок строк, сравнивайте результат по ID и сохраните исходный JSON. Если схема неоднородна, перед экспортом убедитесь, что первые 50 записей содержат все необходимые поля.

Если в предпросмотре отображаются не те строки, измените выбранный узел строк. Обычно это означает, что конвертер нашёл массив, но не тот, который вам нужен. Найдите путь к записям — например, $.results, $.data.items или $.payload.records.

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

Если большой файл обрабатывается медленно, учитывайте производительность браузера и устройства. Datablist выполняет разбор и преобразование в web worker, поэтому эта работа не блокирует основной поток интерфейса, однако доступная локальная память и мощность процессора всё равно задают практические ограничения.

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

Что происходит в браузере

Datablist разбирает и преобразует JSON в браузерном worker. Он анализирует возможные узлы строк, кеширует разобранный объект, преобразует выбранный узел в CSV и возвращает интерфейсу предпросмотр и итоговый результат.

Это важно по двум причинам.

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

Во-вторых, обработка выполняется локально в браузере, а данные не отправляются на серверы Datablist для конвертации. Это удобно при работе с экспортами API, результатами парсинга и внутренними файлами данных, которые не следует загружать в серверный конвертер.

При этом необходимо соблюдать принятые в вашей компании правила работы с данными. Локальная обработка в браузере полезна, но не заменяет корпоративные политики конфиденциальности и соответствия требованиям.

Заключение

При преобразовании вложенного JSON в CSV главное — правильно выбрать узел строк. Как только вы определите массив, элементы которого должны стать строками, остальные настройки станут гораздо понятнее.

В нашем примере $.results создаёт по одной строке на компанию. Разворачивание metrics.employees, metrics.revenue.amount и metrics.revenue.currency формирует удобные столбцы электронной таблицы. Настройки массивов определяют, станут ли поля tags, website и contacts читаемым текстом, сохранённым JSON или отдельным экспортом на уровне контактов.

Откройте конвертер JSON в CSV, загрузите вложенный JSON-экспорт, выберите узел строк, проверьте предпросмотр и скачайте CSV. Затем при необходимости откройте экспортированный файл в CSV editor от Datablist, чтобы очистить, отфильтровать, дедуплицировать, обогатить или перевести данные.

FAQ

Как преобразовать вложенный JSON в CSV?

Используйте конвертер, который позволяет выбрать массив JSON для создания строк. В Datablist вставьте или загрузите JSON, выберите узел строк, разверните полезные поля вложенных объектов, настройте обработку массивов, проверьте таблицу и скачайте CSV.

Можно ли преобразовать JSON в CSV, если записи находятся в results?

Да. Выберите $.results как узел строк, если каждый элемент массива results должен стать отдельной строкой CSV.

Как преобразовать data.items или payload.records в CSV?

Выберите $.data.items или $.payload.records как узел строк, если по этому пути находятся объекты, которые должны стать строками. Точный путь зависит от структуры JSON.

Как развернуть вложенные поля JSON в столбцы CSV?

Включите разворачивание для путей вложенных объектов, например metrics.revenue. Затем перед экспортом проверьте созданные столбцы в предпросмотре.

Как обрабатывать массивы внутри строк JSON?

Объединяйте простые списки, например теги; сохраняйте структурированные массивы как JSON-строки, если нужно сохранить их содержимое; либо выбирайте более глубокий узел строк, если каждый элемент массива должен стать отдельной строкой.

Можно ли преобразовать большой JSON-файл в CSV онлайн?

Да, если браузер и устройство справятся с файлом. Datablist использует web worker для разбора и преобразования, но при работе с очень большими файлами результат всё равно зависит от производительности устройства.

Безопасно ли использовать онлайн-конвертер JSON в CSV для конфиденциальных данных?

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

Что такое узел строк при преобразовании JSON в CSV?

Узел строк — это массив JSON, элементы которого становятся строками CSV. Например, $.results создаёт отдельную строку CSV для каждого объекта в массиве results.

Что произойдёт, если выбрать $.results[].contacts вместо $.results?

В CSV будет по одной строке на контакт, а не на компанию или аккаунт. Поля родительской компании не добавляются автоматически, если только инструмент не начнёт поддерживать такую возможность в будущем.

Что делать после экспорта CSV?

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

Сохраняйте идентификаторы компаний при экспорте контактов

При выборе $.results[].contacts объекты контактов становятся строками. При этом ID, название и домен родительской компании не копируются в каждый контакт автоматически. Например, если у компании с ID C-101 два контакта, будут созданы две строки контактов, но ни одна из них не получит company_id = C-101, если это значение изначально отсутствует внутри объектов контактов.

Если для импорта в CRM необходимо сохранить эту связь, перед скачиванием проверьте в предпросмотре контактов наличие идентификатора компании. Запросите экспорт из API, в котором родительский ID включён в каждый контакт, либо измените структуру JSON и добавьте его до преобразования. Сохраните исходный JSON, чтобы можно было восстановить связи, если в экспортированном CSV их не окажется. Объединение названий компаний в одной ячейке не создаёт надёжный внешний ключ.

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