JSON Formatter

Wklej zwarty, zminimalizowany lub nieuporządkowany JSON i uzyskaj idealnie wcięty wynik w mgnieniu oka. Formatter analizuje Twój JSON za pomocą wbudowanej w przeglądarkę funkcji JSON.parse (zgodnie z ECMA-404), zachowuje znaki Unicode i zwraca dane z wybranym wcięciem:

• 2 spacje (domyślnie dla npm i prettier)
• 4 spacje
• tabulator

Zagnieżdżone obiekty i tablice są poprawnie wcięte na każdym poziomie głębokości. Klucze, ciągi znaków, liczby, wartości logiczne i null otrzymują wyraźne kolory podświetlania składni, dzięki czemu możesz szybko przejrzeć strukturę.

Etykieta 'beautifier' (upiększacz) jest zamienna z 'formatter' lub 'pretty printer' — wszystkie opisują tę samą operację: tworzenie czytelnego dla człowieka JSON-a z kompaktowego wejścia.

Walidacja odbywa się podczas pisania. Jeśli Twój JSON nie przejdzie parsowania, formatter pokaże dokładnie linię, kolumnę oraz to, czego oczekiwał parser.

Walidacja jest ścisła zgodnie z RFC 8259 (standard internetowy IETF) oraz ECMA-404 — brak komentarzy, brak przecinków na końcu, brak pojedynczych cudzysłowów, brak kluczy bez cudzysłowów, brak NaN, brak Infinity, brak undefined. Wartością najwyższego poziomu może być dowolna wartość JSON (obiekt, tablica, ciąg znaków, liczba, true, false, null).

W przypadku danych wejściowych zakodowanych w UTF-8 formatter akceptuje pełny zestaw znaków Unicode; środowiska obsługujące wyłącznie ASCII powinny używać zapisów \uXXXX.

Najczęstsze błędy i rozwiązania:

• przecinek na końcu po ostatnim elemencie tablicy/obiektu (usuń go)
• pojedyncze cudzysłowy wokół kluczy lub ciągów znaków (zastąp podwójnymi)
• brakujący zamykający nawias klamrowy lub kwadratowy (kolumna błędu wskazuje miejsce w pobliżu obcięcia)
• niezabezpieczone znaki sterujące w ciągach znaków (zabezpiecz za pomocą \n, \t, \\)

Minifikacja usuwa wszystkie nieistotne białe znaki — spacje między tokenami, wcięcia oraz nowe linie — pozostawiając najbardziej zwartą możliwą reprezentację. Typowe oszczędności wynoszą 20–60% w zależności od tego, jak mocno wcięty był Twój źródłowy JSON.

Używaj zminifikowanego JSON-a do:

• odpowiedzi API REST/GraphQL
• wiadomości WebSocket
• ładunków JWT
• bloków konfiguracyjnych SaaS
• osadzonych atrybutów danych w HTML

Zachowaj sformatowany (upiększony) JSON dla:

• plików konfiguracyjnych kontrolowanych pod kątem wersji
• obiektów testowych i migawek w testach
• dokumentów edytowanych przez ludzi

Zminifikowany JSON to nadal w 100% standardowy JSON — każdy zgodny parser go zaakceptuje. Tutejszy minifikator dokładnie zachowuje dane: brak zmiany kolejności kluczy, brak wymuszania typu wartości, brak utraty precyzji liczb w zakresie double IEEE 754.

Czysta walidacja składni JSON sprawdza jedynie, czy dokument daje się sparsować. JSON Schema weryfikuje kształt dokumentu — to, czy 'email' jest ciągiem znaków, 'age' jest liczbą całkowitą 0–150, a 'role' jest jednym z ['admin', 'user', 'guest']. Sam schemat jest dokumentem JSON opisującym ograniczenia; instancje są weryfikowane względem niego.

Najpopularniejsze słowa kluczowe: type, required, properties, items, enum, pattern (wyrażenie regularne), minimum/maximum, minLength/maxLength, format (email, date-time, uri).

Przykładowe implementacje:

• Ajv (JavaScript, najszybsza)
• jsonschema (Python)
• networknt/json-schema-validator (Java)
• justinrainbow/json-schema (PHP)

Walidacja schematu wychwytuje ogromną klasę błędów na granicy API: brakujące wymagane pola, niewłaściwe typy, wartości spoza zakresu, wadliwe daty. Specyfikacje OpenAPI 3.x używają JSON Schema do walidacji żądań i odpowiedzi.

JSONPath ma się tak do JSON-a, jak XPath do XML — to język zapytań służący do nawigacji i wyodrębniania danych ze zagnieżdżonego JSON-a.

Składnia:

• $ (korzeń)
• . (dziecko)
• .. (schodzenie rekurencyjne)
• [n] (indeks tablicy)
• [start:end] (wycinek)
• [?(expression)] (filtr)
• * (symbol wieloznaczny)

Przykłady dla typowego JSON-a sklepu:

• $.store.book[0].title pobiera tytuł pierwszej książki
• $..author zwraca każdego autora w całym dokumencie
• $.store.book[?(@.price < 10)] filtruje książki tańsze niż 10
• $.store..price[*] spłaszcza wszystkie ceny

Narzędzia: jq (nieco inna składnia, ale te same możliwości, dominujące w skryptach powłoki), skrypty testowe Postman, JMESPath (opcja --query w AWS CLI) oraz biblioteki JSONPath w każdym głównym języku.

JSON Lines (jsonlines.org), znany również jako NDJSON lub LDJSON, to format, w którym każda linia jest osobną, kompletną wartością JSON. Cały plik jako taki nie jest poprawnym dokumentem JSON – ale każda linia z osobna już tak.

Jest szeroko stosowany do przesyłania strumieni logów (Loki, Splunk HEC, Vector), potoków ETL, danych treningowych uczenia maszynowego (pliki dostrajające OpenAI) oraz każdego przepływu danych typu append-only (tylko do dopisywania).

Zalety:

• przyjazny dla strumieniowania (analiza jednego rekordu naraz, stała pamięć)
• tylko do dopisywania (wystarczy dopisać kolejną linię)
• obsługiwany przez grep i awk w standardowych narzędziach systemu Unix

Rozszerzenia plików: .jsonl, .ndjson. Konwersja z tablicy JSON za pomocą `jq -c '.[]'`; konwersja do tablicy JSON za pomocą `jq -s` (slurp). BigQuery, Athena, Snowflake i większość nowoczesnych hurtowni danych natywnie obsługuje import NDJSON.

JSON5 (json5.org) rozszerza standard JSON o udogodnienia dla programistów:

• komentarze (// i /* */)
• przecinki końcowe (trailing commas)
• łańcuchy w pojedynczych cudzysłowach
• klucze bez cudzysłowów
• łańcuchy wielolinijkowe (z kontynuacją za pomocą ukośnika odwrotnego)
• liczby szesnastkowe
• wartości specjalne standardu IEEE 754 (NaN, Infinity)

Format ten NIE jest kompatybilny z funkcją JSON.parse – wymaga osobnego parsera JSON5 (pakiet npm json5, PyJson5).

Używaj JSON5 w plikach konfiguracyjnych edytowanych przez ludzi, gdzie komentarze są przydatne: babel.config.json5, konfiguracje niektórych narzędzi budujących, .vscode/settings.json (który korzysta z JSONC, podobnego wariantu JSON z komentarzami).

Trzymaj się czystego JSON-a w przypadku: interfejsów API HTTP, wymiany danych, formatów przechowywania oraz wszelkich danych generowanych maszynowo. Mieszanie tych dwóch podejść dezorientuje narzędzia – wybierz jeden format dla pliku i się go trzymaj.

Najczęstsze błędy parsowania JSON i sposoby ich naprawy:

• (1) Przecinek na końcu ostatniego elementu – `{"a":1,}` lub `[1,2,3,]` – usuń zbędny przecinek.
• (2) Pojedyncze cudzysłowy w kluczach lub wartościach tekstowych – `{'name':'Alice'}` – muszą to być podwójne cudzysłowy.
• (3) Klucze bez cudzysłowów – `{name:"Alice"}` – uźyj cudzysłowów.
• (4) Komentarze z użyciem // lub /* */ – czysty JSON ich nie dopuszcza; usuń je lub przejdź na JSON5/JSONC.
• (5) Wartości języka JavaScript niedostępne w JSON – undefined, NaN, Infinity, funkcje – zastąp je wartością null lub je usuń.
• (6) Ucięte dane wejściowe – parser zazwyczaj wskazuje linię, w której zabrakło oczekiwanej treści.
• (7) BOM (znacznik kolejności bajtów) na początku pliku UTF-8 – większość parserów go odrzuca; usuń go za pomocą `sed -i '1s/^\xEF\xBB\xBF//'`.
• (8) Mieszanie tabulatorów i spacji nie przerywa parsowania, ale psuje mechanizm diff – wybierz jeden styl wcięć.

Trzy kategorie podatności związanych z JSON, które powinien rozumieć każdy programista.

• (1) Skażenie prototypu (prototype pollution): scalanie niezaufanego JSON-a z istniejącym obiektem może skazić Object.prototype, jeśli dane wejściowe zawierają klucze __proto__, constructor lub prototype – wpływając na każdy obiekt w czasie wykonania. Używaj Object.create(null), structuredClone lub bibliotek takich jak defaultsDeep z pakietu lodash, które jawnie blokują te klucze.
• (2) Nigdy nie używaj eval() do parsowania JSON-a – eval wykonuje dowolny kod JavaScript, podczas gdy JSON.parse działa w bezpiecznej piaskownicy. Mity o tym, że 'eval jest szybszy', zostały obalone wiele lat temu.
• (3) Pułapki ponownej serializacji: JSON.stringify pomija po cichu funkcje, wartości undefined oraz Symbol w obiektach (w tablicach zamienia je na null). Domyślnie wyrzuca też błąd przy odwołaniach cyklicznych oraz obiektach BigInt.

Przed przetworzeniem waliduj niezaufany JSON za pomocą schematu JSON Schema, ustaw maksymalny rozmiar treści (body) w swoim API i korzystaj ze sprawdzania nagłówka Content-Type, aby wcześnie odrzucać dane niebędące formatem JSON. Ściągawka OWASP REST Security Cheat Sheet omawia ten temat kompleksowo.

JSON ↔ YAML to konwersja w pełni bezstratna – oba formaty obsługują zagnieżdżone obiekty i tablice. Uważaj na automatyczną zamianę typów w YAML-u (yes/no/on/off zamieniają się na wartości logiczne, liczby bez cudzysłowów pozostają liczbami, a dosłowne słowo 'null' staje się wartością null) – otaczaj dwuznaczne wartości cudzysłowem. Narzędzia: js-yaml (npm), PyYAML, yq.

JSON → CSV wymaga spłaszczenia zagnieżdżonej struktury – sprawdza się najlepiej w przypadku tablic płaskich obiektów. Wybierz strategię dla zagnieżdżonych wartości: stringify (zapis jako JSON w komórce) lub kolumny z notacją kropkową (`address.city`, `address.zip`). Narzędzia: in2csv z pakietu csvkit, pandas pd.json_normalize, json2csv (npm).

JSON → XML jest prosty w przypadku struktur drzewiastych, ale zatraca rozróżnienie pomiędzy tablicą a obiektem – elementy potomne w XML mogą być jednym i drugim. Uważaj na niepoprawne nazwy elementów XML (nie mogą zaczynać się od cyfr ani zawierać spacji). Narzędzia: xml-js, xmltodict (Python).

Przy wszystkich konwersjach zdecyduj zawczasu, czy zachowujesz informacje o typach, czy spłaczasz wszystko do tekstu.

JSON.parse ładuje cały dokument do pamięci RAM – co jest w porządku przy typowych odpowiedziach API, ale stanowi problem dla plików większych niż kilkaset megabajtów. Parsery strumieniowe przetwarzają jeden token (lub rekord) naraz, zużywając stałą ilość pamięci niezależnie od rozmiaru pliku.

• JavaScript: stream-json lub oboe.js do parsowania w stylu SAX.
• Python: ijson do parsowania przyrostowego lub wcześniejsza konwersja do formatu JSON Lines i odczyt linia po linii.
• Java: Jackson Streaming API (JsonParser).
• Powłoka (Shell): jq przetwarza strumieniowy JSON za pomocą flagi --stream.

W przypadku plików generowanych jako tablice rekordów JSON, rozważ zmianę producenta danych na emitowanie formatu JSON Lines – skorzysta na tym każdy kolejny konsument. Jeśli musisz obsłużyć ogromną tablicę JSON w pamięci, zamiast budować równoległą strukturę danych, postaw na iterowanie i odrzucanie rekordów. Monitoruj wielkość stosu, ustawiaj flagę --max-old-space-size w Node oraz profiluj kod przed optymalizacją.

Szybka referencja do codziennych zadań z JSON.

• Wcięcia: Prettier i npm domyślnie używają 2 spacji; wybierz 4 spacje dla kodów korporacyjnych, w których przyjęto taki standard w różnych językach; tabulatory są poprawne, lecz rzadkie w formacie JSON.
• Sortowanie kluczy (dla czytelniejszych porównań diff): JSON.stringify(obj, Object.keys(obj).sort(), 2) dla prostych obiektów; jq --sort-keys dla głębokiej rekursji; w Pythonie json.dumps(obj, sort_keys=True).
• Porównywanie dwóch plików JSON (diff): użyj jq --sort-keys dla obu plików, a następnie uruchom zwykłe polecenie diff; albo skorzystaj z json-diff (npm), DeepDiff (Python) lub wbudowanego w VS Code narzędzia porównującego pliki z uwzględnieniem JSON.
• Znaki ucieczki w łańcuchach: \\" (cudzysłów), \\\\ (ukośnik odwrotny), \\/ (ukośnik, opcjonalnie), \\b (backspace), \\f (wysuw strony), \\n (nowa linia), \\r (powrót karetki), \\t (tabulator), \\uXXXX (punkt kodowy Unicode).
• Liczby: JSON dopuszcza liczby dziesiętne i wykładnicze (1.5e3), ale nie pozwala na wiodące zera (0123 jest niepoprawne) ani na kropkę dziesiętną na końcu (1. jest niepoprawne).
• Łańcuchy tekstowe muszą być ujęte w podwójne cudzysłowy – pojedyncze są dozwolone tylko w formacie JSON5.