Конвертер JSON у CSV

Перетворення JSON у CSV: площинна структура і втрата типів

JSON — ієрархічний формат із підтримкою вкладених об’єктів, масивів, чисел, булевих значень і null. CSV — це плоска таблиця без типів даних, без вкладеності та без аркушів. Конвертація з JSON у CSV означає вирівнювання всієї структури: кожне вкладене поле перетворюється на окремий стовпець із крапковою нотацією (dot‑path notation). Наприклад, об’єкт {"address": {"city": "Київ", "zip": 01001}} у CSV стає двома стовпцями: address.city та address.zip.

Цей інструмент повністю втрачає інформацію про типи JSON. Числа, булеві значення та null стають рядками в CSV. Число 100 перетворюється на рядок "100", булеве true — на рядок "true", а null — на порожній рядок. Важливо: провідні нулі в числах, як-от 00123, губляться під час конвертації, оскільки JSON числа не зберігають їх. Якщо вам потрібно зберегти провідні нулі, слід спочатку перетворити такі значення на рядки в самому JSON.

Оскільки CSV використовує роздільники, значення, що містять коми, символи нового рядка або лапки, автоматично обгортаються в подвійні лапки з екрануванням. Наприклад, рядок "Hello, world" у комі-роздільному CSV буде записаний як "Hello, world". Рядок, що містить лапки, наприклад, John "Johnny" Doe, стане "John ""Johnny"" Doe". Ці правила реалізовані автоматично — користувачеві не потрібно вручну цитувати дані.

Як форматувати JSON для успішної конвертації

Інструмент приймає лише «таблицеподібний» JSON (table‑shaped). Це означає, що коренева структура має бути масивом об’єктів (кожен об’єкт — рядок, ключі — стовпці) або масивом масивів (кожен внутрішній масив — рядок, елементи — стовпці без назв). Якщо JSON не відповідає цьому шаблону або є некоректним, виводиться помилка: «This JSON is invalid or not table‑shaped.»

Приклад 1: масив об’єктів

[
  {"name": "Анна", "age": 30, "address": {"city": "Львів"}},
  {"name": "Петро", "age": 25, "address": {"city": "Одеса"}}
]

Результат у CSV:

name,age,address.city
Анна,30,Львів
Петро,25,Одеса

Якщо два об'єкти мають різні набори ключів, об'єднання всіх ключів стає заголовком; відсутні значення стають порожніми клітинками.

Приклад 2: масив масивів

[
  ["Анна", 30, "Львів"],
  ["Петро", 25, "Одеса"]
]

Результат:

Анна,30,Львів
Петро,25,Одеса

У другому випадку стовпці не мають назв — вони просто позиційні. Інструмент не додає заголовки автоматично, тому перший рядок CSV стане даними, а не заголовком. Якщо потрібні заголовки, слід використовувати масив об’єктів.

Для вкладених структур застосовується крапкова нотація. Якщо об'єкт містить вкладений масив, весь масив залишається в одній клітинці як його JSON текст.

Вибір роздільника та його значення

Інструмент дозволяє вибрати один із трьох роздільників: кома (,), крапка з комою (;) або табуляція (\t). Вибір впливає на те, як CSV інтерпретуватиметься іншими програмами. Наприклад, у багатьох європейських локалях Excel за замовчуванням використовує крапку з комою, оскільки кома є десятковим роздільником. Якщо ви обрали кому, а Excel налаштований на крапку з комою, дані можуть об’єднатися в один стовпець. Табуляція часто використовується для TSV-файлів, які краще сумісні з базами даних.

Автоматичне цитування залежить від обраного роздільника. Якщо вибрано крапку з комою, то значення, що містять крапку з комою, лапки або переходи рядка, цитуватимуться. Наприклад, рядок A;B стане "A;B". Це стандартна поведінка згідно з RFC 4180 (для коми) та аналогічно для інших роздільників.

Обмеження та помилки, які варто знати

Інструмент працює повністю на стороні клієнта — жодні дані не передаються на сервер. Це забезпечує конфіденційність під час роботи з чутливими API-відповідями. Однак існують жорсткі обмеження:

• Розмір файлу: якщо JSON більший за 8 МБ, показано помилку «This file is too large. Use a file under ‹max›.»
• Кількість рядків: якщо таблиця має більше 10 000 рядків, викликає помилку «This table has more than ‹max› rows.»
• Кількість стовпців: аналогічно — якщо таблиця має більше 200 стовпців, викликає помилку «This table has more than ‹max› columns.»
• Інші помилки:
  • "Choose one file first." — не вибрано жодного файлу.
  • "Choose a CSV, JSON or XLSX file." — обрано несумісний тип.
  • "Choose a different output format." — обрано не CSV.
  • "Could not convert this file." — загальна помилка конвертації.
  • "Conversion cancelled." — операцію скасовано.
  • "This conversion is taking too long. Try a smaller file." — перевищено час очікування.

Усі обробки відбуваються локально, тому помилки, пов’язані з мережею, відсутні. Розмір файлу та кількість рядків/стовпців — єдині обмеження, окрім формату даних.

Типові помилки при перетворенні JSON → CSV

1. Втрата вкладеної структури. Користувачі, які звикли до JSON, часто очікують, що вкладений об’єкт залишиться окремим стовпцем із підструктурою. У CSV цього не відбувається — усе сплющується в плоскі назви стовпців. Якщо в JSON є масив об’єктів, він перетворюється на кілька рядків, але якщо масив вкладено всередині одного запису — він стає рядком.

2. Некоректне використання масиву масивів. Якщо JSON є масивом масивів, але перший внутрішній масив містить заголовки, інструмент не сприймає їх як заголовки — вони стають першим рядком даних. Потрібно заздалегідь перетворити таку структуру на масив об’єктів або вручну додати заголовки в CSV після конвертації.

3. Проблеми з символами нового рядка всередині значень. CSV підтримує багаторядкові клітинки, якщо вони цитовані. Інструмент це робить автоматично, але деякі програми (наприклад, старий Excel) можуть неправильно інтерпретувати такі файли. Рекомендується перевіряти результат у текстовому редакторі перед імпортом.

4. Кодування символів. Інструмент читає файл як UTF-8 (стандарт для сучасних JSON/CSV). Якщо ваш CSV-інструмент очікує інше кодування (наприклад, Windows-1252 для старих версій Excel), можливо, вам доведеться перекодувати файл після завантаження. Інструмент не пропонує опцій кодування.

5. Зворотна сумісність при повторній конвертації. Якщо ви конвертуєте CSV назад у JSON, ви не отримаєте оригінальну вкладену структуру — лише плоский JSON зі стовпцями як ключами, включно з крапковою нотацією. Типи також не відновляться. Для збереження типів у JSON потрібно використовувати спеціалізовані інструменти, які додають метадані.

Часті питання (FAQ)

1. Чому зникають провідні нулі, наприклад, 00123 стає 123?
JSON числа не можуть мати провідних нулів. Якщо ваше вихідне значення "0123" (рядок), воно залишається 0123. Якщо це 0123 як числовий літерал, JSON парсери обробляють його як число 123, і інструмент виводить 123. Зберігайте такі значення як рядки в JSON, якщо вам потрібен нуль.

2. Чи можна конвертувати вкладений об’єкт?
Так, але він буде сплющений через крапкову нотацію: {"a": {"b": 1}} стане стовпцем a.b. Якщо вкладений об’єкт містить масив, цей масив не розгорнеться — він перетвориться на рядок, як-от ``. Для розгортання масиву в окремі рядки потрібно попередньо «розширити» JSON.

3. Чи завантажуються мої дані на сервер?
Ні. Усі обчислення відбуваються у вашому браузері. Жоден файл не передається на сервер. Це забезпечує повну конфіденційність, що особливо важливо для даних API-відповідей з обліковими записами чи персональними даними.

4. Чому з’являється помилка «This JSON is invalid or not table‑shaped.»?
Це означає, що ваш JSON не є масивом об’єктів або масивом масивів. Наприклад, кореневий об’єкт {"name": "Іван"} не підходить. Також помилка виникає, якщо структура містить змішані типи в одному масиві (наприклад, один елемент — об’єкт, інший — рядок). Приведіть JSON до масиву однотипних структур.

5. Як вибрати правильний роздільник?
Якщо ви плануєте відкривати CSV в Excel локалі, де десятковим роздільником є кома, обирайте крапку з комою. Для англомовних локалей — кома. Для роботи з базами даних або скриптами часто зручна табуляція, яка рідше зустрічається в даних. Якщо не впевнені, почніть з коми, а потім перевірте відображення в програмі.

6. Чи підтримується конвертація масиву масивів?
Так. Якщо ваш JSON — це ``, то перший рядок CSV буде «1,2», другий — «3,4». Заголовки не додаються. Це корисно для простих таблиць без назв стовпців. Якщо потрібні заголовки, перетворіть таку структуру на масив об’єктів з ключами.