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

Какво прави този инструмент

Този инструмент приема JSON файл и го преобразува във формат CSV. Потребителят може да качи файл чрез бутон или да го плъзне директно в определената зона. След като избере разделител – запетая, точка и запетая или табулация – и натисне бутон за конвертиране, инструментът показва предварителен преглед на таблицата и предлага файла за сваляне. Цялата обработка се извършва в браузъра на потребителя; нито един байт от файла не напуска неговата машина. Това го прави подходящ за работа с чувствителни данни, при която качването във външен сървър е недопустимо.

Защо този инструмент е различен

Преобразуването от JSON към CSV е фундаментално различно от обратното (CSV → JSON) или от конвертирането между Excel и CSV. JSON поддържа йерархични структури – обекти и масиви – и типове данни: числа, булеви стойности, null, низове. CSV от своя страна е плосък текстов формат, който не различава типове, не поддържа вложени обекти и няма понятие за отделни листове. Този инструмент трябва да изравни (flatten) йерархията в проста редово-колонна структура.

Ключовият механизъм е използването на точкова нотация за представяне на вложени полета. Например ако JSON съдържа обект person с вложен обект address, който има поле city, то в CSV колоната ще се казва address.city. Масив от обекти се превръща в редове, като всеки обект дава един ред, а неговите ключове (включително разгънатите с точка) стават колони. Ако JSON съдържа масив от масиви, всеки вътрешен масив е отделен ред, а елементите му са колоните – тук няма ключове за имена на колони.

За разлика от конвертирането на Excel в CSV, тук няма множество листове. За разлика от CSV в JSON, тук не се възстановява типова информация. Всички стойности в изходния CSV запазват типовете си, когато е възможно. Това означава, че числата запазват числовия си тип, булевите стойности запазват булевия си тип, а null става празен низ. Вложените структури изчезват – остава само плоската точкова нотация.

Как работи преобразуването: от йерархия към таблица

JSON трябва да е "табличен"

Инструментът работи само с JSON, който е "таблично оформен". Това означава, че коренната структура трябва да бъде масив от обекти (еднородни по ключове) или масив от масиви. Ако файлът е невалиден JSON или не е табличен, се показва грешка: "This JSON is invalid or not table‑shaped." Пример за невалидна структура: единичен обект без масив отгоре, или обект, чиито стойности са разнотипни.

Алгоритъм на изравняване

1. Инструментът открива дали коренният елемент е масив.
2. Ако масивът съдържа обекти: за всеки обект се генерира един ред. Ключовете на обектите определят колоните. Ако даден ключ сочи към вложен обект (например address), той се разгъва: address.street, address.city и т.н. Ако един обект има поле, което в друг обект липсва, празните клетки се попълват с празни низове.
3. Ако масивът съдържа масиви: всеки вътрешен масив се превръща в ред. Броят на колоните е равен на максималната дължина на масивите. Липсващите стойности се попълват с празно.
4. След изравняване, стойностите се записват в CSV. При необходимост се прилагат правила за цитиране (кавички): ако стойността съдържа разделител, нов ред или кавичка, тя се огражда в двойни кавички, а вътрешните кавички се удвояват.

Какво се губи

• Типове: числа като 1234 запазват числовия си тип. Булевите true/false запазват булевия си тип. null става празна клетка.
• Вложеност: структурата се разгъва плоска. Няма как да се запази дълбочината на обектите освен чрез точкова нотация.
• Водещи нули: при числа със символна представка (например "00123" като низ) се запазват, но ако JSON съдържа число 123, то в CSV ще стане "123". Често срещана грешка: когато данните имат код 0001, но в JSON е записан като число 1. Тогава в CSV ще се появи "1", а не "0001". Потребителят трябва да осигури, че такива стойности са низове в изходния JSON.

Важни правила и гранични случаи

Инструментът има няколко ограничения, които са важни за практически сценарии:

• Размер на файла: при прекалено голям файл се показва грешка "This file is too large. Use a file under 8 MB.".
• Брой редове: ако таблицата има повече от 10 000 реда, се появява "This table has more than ‹max› rows.".
• Брой колони: ако броят колони надвиши 200, се показва "This table has more than ‹max› columns.".
• Несъответствие на разширението: ако се опитате да качите файл, който не е CSV, JSON или XLSX, получавате "Choose a CSV, JSON or XLSX file.".
• Липсващ файл: при опит за конвертиране без избран файл: "Choose one file first.".
• Грешен изходен формат: при избор на различен от CSV изход: "Choose a different output format.".
• Неочаквана грешка: "Could not convert this file.".
• Анулиране: ако потребителят спре операцията, се показва "Conversion cancelled.".
• Твърде бавно: "This conversion is taking too long. Try a smaller file." – това може да се случи при много големи JSON файлове, тъй като обработката е еднопоточна в браузъра.

Цитиране в CSV

CSV форматът изисква специално третиране на разделители, нови редове и двойни кавички. Инструментът го прави автоматично. Например ако клетка съдържа запетая ",", тя ще бъде оградена в кавички. Ако съдържа кавичка, тя се удвоява (""). Ако съдържа нов ред, той се запазва в рамките на кавичките. Това е по стандарта RFC 4180.

Водещи нули

Един от най-честите проблеми при конвертиране на JSON към CSV е загубата на водещи нули. Например в JSON "id": "00123" (низ) ще се запази като "00123". Но ако в JSON стои "id": 00123 (невалиден – JSON не поддържа водещи нули за числа, така че обикновено е "id": 123), то в CSV ще стане "123". Потребителят трябва да провери, че стойностите, които трябва да запазят водещи нули, са кодирани като низове в JSON.

Входове и изходи

Входове:

• Един единствен JSON файл (с разширение.json).
• Потребителят задава разделител: запетая (,), точка и запетая (;) или табулация (\t).

Изходи:

• CSV файл, готов за сваляне.
• Предварителен преглед на таблицата, показващ първите 8 реда и 8 колони.
• Брой редове и брой колони.
• Размер на изходния файл в байтове или килобайти.

Изборът на разделител е важен за съвместимостта с локални настройки. Например в България Excel понякога очаква точка и запетая, а не запетая, когато десетичният разделител е запетая. С този инструмент можете да експортирате с ; и Excel ще отвори CSV правилно.

За кого е този инструмент

• Разработчици, които имат JSON отговор от API (например REST услуга) и искат да го заредят в Excel или Google Sheets за анализ.
• Анализатори на данни, които работят с чувствителна информация и не могат да използват онлайн конвертори с качване.
• Хора, които се нуждаят от CSV с различен разделител поради регионални настройки на софтуера.
• Всеки, който бързо иска да изравни йерархичен JSON в таблица, без да пише скрипт.
• При тестване на data pipelines – възможност за бързо конвертиране и проверка на структурата.

Често задавани въпроси

1. Защо някои колони в CSV са празни, когато в JSON имаше данни?

Ако JSON масивът не е еднороден – в някои обекти липсват ключове – инструментът събира всички ключове от всички обекти. За липсващите стойности се поставя празна клетка. Това е нормално поведение, тъй като CSV изисква всички редове да имат еднакъв брой колони.

2. Какво става с null стойности в JSON?

null се превръща в празна клетка. Ако искате да го обозначите изрично, трябва да замените null с низ "null" в JSON преди конвертиране.

3. Мога ли да конвертирам JSON с вложени масиви от обекти?

Да. Ако JSON съдържа масив от обекти, а някои от полетата са масиви, инструментът ще ги третира като низове (поради липса на схема). Вложен масив от обекти не може да се разгъне в същия CSV, защото би довел до различен брой колони. В такъв случай трябва предварително да "изправите" структурата (например с де‑нормализация) или да използвате инструмент, който поддържа вложени JSON масиви (например като създава отделни редове с повторение на родителските ключове). Този инструмент не го прави – той изравнява само обектно‑вложените полета.

4. Ще се изтрият ли данните ми след конвертиране?

Да, данните се обработват изцяло в браузъра. След затваряне на раздела или опресняване на страницата нищо не се запазва. Нито вие, нито ние имаме достъп до файла на сървър.

5. Как да избегна загуба на водещи нули?

Уверете се, че в JSON тези стойности са низове, а не числа. Например вместо "zip": 01234 (невалиден JSON) използвайте "zip": "01234". Ако вече имате числа с водещи нули, конвертирайте ги в низове с функция като String(value) преди експорт.

6. Има ли ограничение за броя на редовете, което може да доведе до грешка?

Да. Инструментът има горна граница от 10 000 реда. Ако вашият JSON съдържа повече редове от допустимото, трябва да го разделите на по-малки части. Механизмът е клиентски, затова големи файлове могат да причинят забавяне или грешка "This conversion is taking too long. Try a smaller file.".