Konwerter JSON na Excel

Dlaczego konwersja JSON do Excela nie jest trywialna

JSON i Excel (XLSX) to dwa zasadniczo różne modele danych. JSON jest typowany i hierarchiczny – jeden plik może zawierać zagnieżdżone obiekty, tablice, liczby, wartości logiczne i null. XLSX to płaski arkusz z wierszami i kolumnami, który nie potrafi bezpośrednio oddać struktury drzewiastej. Dlatego samo przekopiowanie danych nie wystarczy – konieczne jest zaaplikowanie reguły spłaszczania (flattening), która zamienia hierarchię na płaską tabelę.

Główną różnicą między tą stroną a konwersją z CSV lub Excela jest właśnie ta reguła. CSV i Excel są już z definicji płaskie – każdy wiersz ma tę samą liczbę kolumn, a nagłówki opisują konkretne pola. JSON nie ma takiego wymogu. Jeden rekord może mieć address.city, a inny address.street – co więcej, w ogóle nie musi mieć pola address. Narzędzie musi więc najpierw przeanalizować wszystkie obiekty w pliku, zebrać wszystkie możliwe ścieżki kluczy, a dopiero potem ułożyć je jako kolumny.

Jak działa spłaszczanie JSON na tabelę

Wejściowy plik musi być „table‑shaped”, czyli nadawać się do przekształcenia na wiersze i kolumny. Narzędzie obsługuje dwa przypadki:

• Tablica obiektów – każdy obiekt staje się jednym wierszem. Klucze obiektu (w tym klucze zagnieżdżone) stają się nagłówkami kolumn. Zagnieżdżenie jest rozwijane za pomocą notacji z kropką, np. address.city, user.name.first.

• Tablica tablic – każda wewnętrzna tablica staje się wierszem, a jej elementy kolumnami. To przypadek rzadszy, ale występuje, gdy JSON pochodzi z systemów, które zwracają dane jako macierz.

Dla przykładu, weźmy ten JSON:

[
  {
    "id": 1,
    "name": "Jan Kowalski",
    "address": {
      "city": "Warszawa",
      "zip": "00-001"
    },
    "active": true
  },
  {
    "id": 2,
    "name": "Anna Nowak",
    "address": {
      "city": "Kraków",
      "zip": "30-001"
    },
    "active": false
  }
]

Po konwersji otrzymamy arkusz z kolumnami: id, name, address.city, address.zip, active. Wartości logiczne (true, false) zostaną zachowane jako typ logiczny w XLSX, a nie jako tekst.

Jeśli jeden z obiektów ma dodatkowe zagnieżdżenie, np. address.coordinates.lat, to narzędzie doda kolumnę address.coordinates.lat dla wszystkich wierszy, a w rekordach bez tej wartości pojawi się puste pole.

Typy danych w JSON a komórki Excela

XLSX (Open XML Spreadsheet) to format oparty na spakowanym (ZIP) XML, który natywnie obsługuje kilka typów danych: liczby całkowite, zmiennoprzecinkowe, wartości logiczne, tekst i puste komórki. Różni się to zasadniczo od CSV, gdzie wszystko – nawet true i 42 – zapisywane jest jako ciąg znaków i dopiero program arkusza kalkulacyjnego może je zinterpretować.

Mapowanie typów w narzędziu wygląda następująco:

To ma znaczenie praktyczne. Jeśli w JSON masz kolumnę salary z wartościami liczbowymi, to w XLSX będą to liczby – możesz od razu robić na nich sumy i średnie. W CSV dostałbyś tekst i musiałbyś ręcznie zmienić format kolumny.

Ograniczenia i reguły brzegowe

Narzędzie działa w przeglądarce – całe przetwarzanie odbywa się po stronie klienta. Żaden plik nie jest wysyłany na serwer, co ma znaczenie dla prywatności danych. Ale to nałożyło też ograniczenia. W pliku wynikowym powstaje tylko jeden arkusz (Sheet1). Nie ma obsługi formuł, stylów ani formatowania warunkowego. Z JSON nie da się przenieść informacji o wyglądzie – JSON to dane, nie układ.

Lista komunikatów błędów, które może zwrócić narzędzie:

• „Choose a CSV, JSON or XLSX file.” – plik ma nieobsługiwane rozszerzenie.
• „This file is too large. Use a file under ‹max›.” – przekroczono maksymalny rozmiar pliku (maksymalny rozmiar pliku to 8 MB).
• „Ten kod JSON jest nieprawidłowy lub nie ma struktury tabeli.” – plik nie zawiera poprawnej tablicy obiektów ani tablicy tablic (np. to pojedynczy obiekt, obiekt z zagnieżdżeniem niebędącym tablicą lub uszkodzony JSON).
• „This file has no table rows.” – tablica jest pusta.
• „This conversion is taking too long. Try a smaller file.” – przetwarzanie trwa zbyt długo, prawdopodobnie z powodu zbyt dużego pliku.
• „Conversion cancelled.” – użytkownik przerwał działanie.
• „Nie udało się przekonwertować tego pliku.” – nie udało się przekonwertować pliku.

Nie ma rozróżnienia na to, czy przekroczono limit wierszy czy kolumn – oba są zwracane jako osobne komunikaty.

Kiedy JSON nie nadaje się do konwersji

Nie każdy plik JSON da się sensownie przerobić na arkusz. Najczęstsze problemy:

• Głęboko zagnieżdżone obiekty – jeśli JSON ma strukturę wielopoziomową (obiekt w obiekcie w obiekcie), to długość nagłówka kolumny (np. data.attributes.metadata.created.date) może być nieczytelna. Narzędzie rozwinie wszystkie poziomy, ale arkusz stanie się trudny w użyciu.
• Tablice wewnątrz obiektów – jeśli jeden wiersz ma pole z tablicą (np. tags: ["a", "b", "c"]), to narzędzie nie utworzy osobnych wierszy dla każdego taga. Tablica zostanie zrzutowana do tekstu (np. ["a","b","c"]). Arkusz nie obsługuje komórek z listami.
• Różna struktura obiektów – jeśli pierwszy obiekt ma klucze name i age, a drugi name i phone, to kolumna age będzie pusta dla drugiego rekordu, a kolumna phone dla pierwszego. To działa, ale robi się nieczytelne przy dużym zróżnicowaniu.

Dlatego narzędzie ma warunek „table‑shaped” – dane muszą mieć względnie jednolitą strukturę. Idealne źródło to odpowiedź z API REST zwracająca listę obiektów o tych samych kluczach.

Format XLSX – co w nim siedzi

XLSX to nie jest binarny format Excela (.xls). To archiwum ZIP zawierające kilka plików XML:

• xl/workbook.xml – opis arkuszy, ich nazwy i kolejność.
• xl/worksheets/sheet1.xml – właściwe dane: wiersze, kolumny, wartości i ich typy.
• xl/styles.xml – style (dla tego narzędzia puste, bo nie ma formatowania).
• xl/sharedStrings.xml – jeśli ten sam tekst pojawia się wiele razy, jest przechowywany w słowniku, a w komórkach tylko referencje.
• [Content_Types].xml i _rels/ – metadane.

Wartości liczbowe są przechowywane w tagu <v> z typem n (number), logiczne z typem b (boolean), a tekstowe z typem s (string z shared strings). Null nie ma osobnego typu – w XLSX komórka po prostu nie istnieje w XML, dopóki nie ma wartości.

To odróżnia XLSX od CSV, gdzie każda komórka to ciąg znaków oddzielony przecinkiem. XLSX pozwala zachować oryginalny typ danych z JSON – o ile ten typ nie jest obiektem lub tablicą.

FAQ

Dlaczego po konwersji widzę kolumnę z nazwą address.city, a nie osobne kolumny dla miasta i kodu?

To efekt spłaszczania. JSON pozwala na dowolne zagnieżdżenie, ale arkusz wymaga płaskiej struktury. Narzędzie łączy ścieżkę dostępu z kropkami, aby zachować informację o hierarchii. Gdyby utworzyło po prostu kolumnę city, straciłoby kontekst – nie wiadomo, czy to miasto z adresu, czy z pola city na najwyższym poziomie.

Czy mogę przekonwertować plik JSON zawierający daty?

Daty nie mają w JSON osobnego typu – są najczęściej zapisane jako tekst („2024-03-15”) lub liczba (timestamp). W XLSX trafią jako daty, liczby lub tekst.

Co się stanie z wartością null w JSON?

Null jest traktowany jako brak wartości. W arkuszu pojawi się pusta komórka. To ważne – narzędzie nie wstawia tekstu „null”. Jeśli chcesz odróżnić celowy null od brakującego pola, musisz zrobić to przed konwersją, np. zamienić null na specjalny znacznik.

Moj plik ma 50 kolumn – czy to działa?

Tak, o ile nie przekroczono maksymalnej liczby kolumn (200). Pamiętaj jednak, że każdy zagnieżdżony obiekt dodaje kolejne kolumny. Jeśli masz obiekt z 10 polami, z których każde zawiera obiekt z 5 polami, to teoretycznie możesz dostać 50 kolumn. W praktyce im więcej kolumn, tym gorzej arkusz się czyta.

Czy narzędzie zachowuje kolejność kluczy z JSON?

Kolejność kluczy w obiekcie JSON z definicji nie jest gwarantowana – standard mówi, że obiekty są nieuporządkowane. W praktyce jednak większość środowisk (Node.js, Python, nowoczesne przeglądarki) zachowuje kolejność dodawania kluczy. Narzędzie prawdopodobnie użyje tej kolejności, ale nie jest to wymuszone przez żaden standard. Jeśli zależy ci na konkretnym układzie kolumn, lepiej uporządkować klucze w pliku źródłowym.

Dlaczego nie mogę przekonwertować pliku z tablicą obiektów, gdzie jeden obiekt ma klucze a, b, a drugi a, c?

Możesz – to jest poprawna tablica obiektów. Różne zestawy kluczy są obsługiwane. Kolumny będą sumą wszystkich kluczy ze wszystkich obiektów. Jeśli jeden obiekt nie ma klucza c, to w jego wierszu będzie puste pole. To standardowe zachowanie dla narzędzi do spłaszczania JSON.