Co JSON dopuszcza, a czego nie
JSON jest celowo ubogi. Standard ECMA-404 opisuje sześć rodzajów wartości: obiekt, tablicę, tekst, liczbę, wartość logiczną i null. Nazwy pól wymagają cudzysłowów prostych, więc pojedyncze cudzysłowy zamiast podwójnych psują dokument, choć w JavaScripcie zapis apostrofami uchodzi płazem. Po ostatnim elemencie tablicy lub obiektu nie może stać przecinek. Komentarzy nie ma w ogóle, mimo że wiele edytorów je toleruje.
Te ograniczenia są źródłem większości błędów w plikach pisanych ręcznie. Formaty konfiguracyjne oparte na JSON dopuszczają czasem rozszerzenia (JSON5 z komentarzami i kluczami bez cudzysłowów, JSONC w edytorach Microsoftu), ale zwykły JSON.parse odrzuci taki plik bez litości. JSON formatter na tej stronie zgłosi wtedy błąd i zaproponuje usunięcie odstępstw, żeby dokument dało się sparsować.
Jak czytać komunikat o błędzie
Przeglądarka zgłasza błąd parsowania w postaci pozycji znaku, na przykład „Unexpected token } in JSON at position 118”. Sama pozycja jest mało czytelna w pliku mającym kilkaset wierszy, dlatego przeliczamy ją na numer wiersza i kolumny, a następnie pokazujemy trzy sąsiednie wiersze z zaznaczonym znakiem.
Parser ma przy tym pułapkę, o której łatwo zapomnieć w trakcie szukania literówki. Zgłasza błąd tam, gdzie zauważył problem, a nie tam, gdzie go popełniono. Brakujący przecinek między dwoma polami zostanie zgłoszony na początku drugiego pola, a niedomknięty cudzysłów dopiero na końcu pliku. Jeśli wskazane miejsce wygląda niewinnie, sprawdź kilka linii wyżej.
Formatowanie i minifikacja JSON, sortowanie kluczy
Formatowanie rozkłada dokument na linie, dodaje wcięcia i nadaje mu czytelną postać, przez co zagnieżdżenie widać na pierwszy rzut oka. Minifikacja idzie w drugą stronę i zostawia ciąg JSON pozbawiony białych znaków spoza tekstów, zamknięty w jednej linii. Dla typowego dokumentu API oszczędność sięga 20-30% objętości, choć przy włączonej kompresji gzip realna różnica w transmisji jest znacznie mniejsza.
Sortowanie kluczy to sztuczka przydatna przy porównywaniu. Standard nie narzuca kolejności pól w obiekcie, więc dwa dokumenty o identycznej treści mogą różnić się układem. Po alfabetycznym uporządkowaniu obu i sformatowaniu tym samym wcięciem zwykły diff pokaże wyłącznie realne różnice.
Znaki specjalne, escape i polskie litery
Wewnątrz tekstu JSON wymaga escapowania kilku znaków. Cudzysłów prosty zapisuje się jako \", ukośnik wsteczny podwaja się, a znak nowej linii ma postać \n. Dosłowny podział linii w środku wartości tekstowej jest błędem składni, mimo że edytory chętnie go wstawiają przy zawijaniu długiego napisu.
Polskie znaki nie wymagają escapowania, bo JSON zapisuje się w UTF-8. Spotyka się jednak dokumenty, w których każda litera spoza ASCII ma postać \u0105, i tak zachowują się starsze biblioteki serwerowe. Po sformatowaniu takie sekwencje wracają do zwykłych liter, bo narzędzie najpierw parsuje dokument, a potem zapisuje go od nowa.
Kiedy da się zamienić JSON na CSV
CSV to tabela o wierszach i kolumnach jednakowej struktury. JSON jest drzewem, więc konwersja ma sens tylko wtedy, gdy dokument jest tablicą obiektów o podobnym zestawie pól - na przykład listą zamówień albo wynikiem zapytania do bazy. Kolumny zbieramy z sumy wszystkich kluczy, a brakujące wartości zostawiamy puste.
Zagnieżdżone struktury są problemem, którego CSV nie rozwiązuje. Wypisujemy je w komórce jako tekst JSON. Taki zapis zachowuje informację, ale nie ułatwia analizy. W polskiej wersji arkuszy kalkulacyjnych domyślnym separatorem jest średnik, dlatego to on jest tutaj ustawiony jako domyślny, a znacznik BOM na początku pliku sprawia, że Excel poprawnie rozpozna polskie znaki.
Gdzie w codziennej pracy pojawia się JSON
Plik konfiguracyjny w repozytorium, odpowiedzi API z serwera testowego, eksport z bazy i log aplikacji trafiają dziś do tego samego formatu, więc programiści oglądają JSON kilkanaście razy dziennie, najczęściej w postaci zminifikowanej, czyli jako jedną długą linię bez spacji. W takiej postaci gołym okiem nie widać ani struktury dokumentu, ani miejsca błędu, więc formatowanie JSON jest pierwszą czynnością, zanim w ogóle zacznie się czytać dane.
Osobny przypadek to logi w formacie JSONL, w których każda linia jest samodzielnym dokumentem. Całego takiego pliku JSON.parse nie przyjmie, więc do formattera wklej pojedynczą linię. Tak samo wyglądają strumieniowe eksporty z hurtowni danych.
Pliki konfiguracyjne mają jeszcze jedną cechę. Powstają ręcznie, a ręczne pisanie kończy się literówką znacznie częściej niż generowanie dokumentu z kodu, dlatego walidacji używa się głównie do plików konfiguracyjnych z repozytorium, takich jak package.json czy composer.json.
Co dzieje się z danymi wklejonymi do formattera
Dokumenty JSON, które ktoś wkleja do narzędzia diagnostycznego, to zwykle odpowiedzi API z produkcyjnego serwera, a w nich siedzą dane klientów, tokeny sesji i klucze do zewnętrznych usług. Wysyłanie ich do losowego serwisu w sieci jest wyciekiem, nawet jeśli serwis obiecuje, że nic nie zapisuje.
Formatter działa w całości w przeglądarce, od parsowania po kolorowanie i konwersję do CSV. Możesz otworzyć zakładkę „Sieć” w narzędziach deweloperskich, wkleić dokument i przekonać się, że nie wychodzi żadne zapytanie. Pobrany plik też powstaje w pamięci przeglądarki.