Jak formatować i walidować JSON: przewodnik dla programistów

JSON jest wszędzie: odpowiedzi API, pliki konfiguracyjne, logi, kolejki wiadomości, payloady żądań, kolumny w bazach danych. Jak na tak prosty format, zaskakująco często wpadamy z nim w kłopoty - brakujący przecinek psuje deploy, dodatkowy znak białego znaku czyni dwa pliki “różnymi”, gdy powinny być identyczne, głęboko zagnieżdżona struktura jest niemożliwa do debugowania, bo nikt jej nie wciął.

Co JSON naprawdę dopuszcza

Specyfikacja JSON jest celowo drobna. Dokument JSON to jedno z:

• Obiekt: { "key": value, ... }
• Tablica: [ value, ... ]
• String: "text" (zawsze podwójne cudzysłowy, nigdy pojedyncze)
• Liczba: 42, 3.14, -2.5e10
• Wartość logiczna: true lub false
• null

To wszystko. Bez komentarzy. Bez końcowych przecinków. Bez niecytowanych kluczy. Bez stringów w pojedynczych cudzysłowach. Bez undefined. Bez NaN czy Infinity. Bez funkcji.

Jeśli kiedykolwiek zastanawiałeś się, dlaczego parser odrzucił twój “oczywiście poprawny” plik, zwykle chodzi o jedno z tych:

{
 "name": "Alice",
 "age": 30, // ← komentarz: NIE jest poprawny JSON
 "email": 'alice@...', // ← pojedyncze cudzysłowy: NIE są poprawnym JSON
 role: "admin", // ← niecytowany klucz: NIE jest poprawnym JSON
 "active": true, // ← końcowy przecinek: NIE jest poprawnym JSON
}

Formaty, które pozwalają na te luźniejsze zasady, to JSON5 (komentarze, końcowe przecinki, niecytowane klucze) i JSONC (JSON with Comments, używany w plikach konfiguracyjnych VS Code). To nadzbiory JSON-a, ale wymagają wyspecjalizowanych parserów.

Reguły formatowania, które czynią JSON czytelnym

Zminifikowany JSON:

{"users":[{"id":1,"name":"Alice","roles":["admin","editor"]},{"id":2,"name":"Bob","roles":["viewer"]}]}

Sformatowany JSON:

{
 "users": [
 {
 "id": 1,
 "name": "Alice",
 "roles": ["admin", "editor"]
 },
 {
 "id": 2,
 "name": "Bob",
 "roles": ["viewer"]
 }
 ]
}

Te same dane, zupełnie inna czytelność.

Reguły, które mają znaczenie:

• Wcięcie: 2 spacje - zdecydowanie najpowszechniejsza konwencja. Bądź konsekwentny w projekcie.
• Jeden klucz na linię wewnątrz obiektów, jedna pozycja na linię wewnątrz tablic (dla nietrywialnej zawartości)
• Spacja po dwukropku, bez spacji przed: "key": value
• Tablice prymitywów w jednej linii, gdy krótkie: "roles": ["admin", "editor"] jest OK
• Tablice obiektów w wielu liniach zawsze - inaczej szybko stają się nieczytelne

Nasz JSON Formatter stosuje to wszystko automatycznie po kliknięciu Formatuj.

Walidacja: na co uważać

1. Brakujący lub nadmiarowy przecinek

Zdecydowanie najczęstszy. Nieprawidłowy JSON prawie zawsze ma problem z przecinkami.

{
 "a": 1,
 "b": 2 ← brakujący przecinek
 "c": 3
}

Uwaga: parser obwinia linię po brakującym przecinku, co może być mylące.

2. Niezamknięty string

Błędny znak nowej linii wewnątrz stringa albo brakujący zamykający cudzysłów:

{ "name": "Alice
} 

JSON nie dopuszcza dosłownych znaków nowej linii wewnątrz stringów. Escape’uj je jako \n.

3. Niedopasowane nawiasy

Jeden nadmiarowy } lub ] gdziekolwiek w pliku. Większość parserów zgłasza pierwszy niedopasowany nawias, co może być daleko od rzeczywistego błędu.

4. Nieprawidłowa liczba

Liczby JSON przestrzegają ścisłych reguł: bez wiodącego +, bez wiodących zer (poza 0.x), bez 1. bez cyfry po kropce, bez .5 bez wiodącego zera.

{ "a": +5, "b": 07, "c": 1., "d": .5 } ← wszystkie nieprawidłowe

5. Escape’owane znaki w stringach

Backslashe i cudzysłowy wewnątrz stringów muszą być escape’owane:

{ "path": "C:\Users\Alice" } ← nieprawidłowe (backslash nie jest escape'owany)
{ "path": "C:\\Users\\Alice" } ← prawidłowe

6. Zduplikowane klucze

Technicznie specyfikacja JSON mówi, że zduplikowane klucze są “dopuszczalne, ale niezalecane”. W praktyce większość parserów po cichu bierze ostatnią wartość. To prawie zawsze bug.

{ "name": "Alice", "name": "Bob" }

Jak formatować i walidować w praktyce

Najszybszy workflow:

1. Wklej podejrzany JSON do formatera
2. Kliknij Formatuj
3. Jeśli zaakceptuje, przeczytaj sformatowane wyjście, żeby zrozumieć strukturę
4. Jeśli odrzuci, przeczytaj uważnie komunikat błędu - numer linii jest zwykle blisko (ale nie dokładnie na) prawdziwego problemu

Nasz JSON Formatter używa wbudowanego JSON.parse przeglądarki - tego samego parsera, którego używa każde API Node.js i usługa webowa. Komunikat błędu, który widzisz, jest identyczny z tym, który wyemitowałoby prawdziwe API.

Sformatuj vs zminifikuj

Formatery mają zwykle dwa przyciski:

• Formatuj (albo Upiększ, Pretty-print): dodaje spacje i wcięcia dla czytania przez ludzi
• Minifikuj (albo Kompakt): usuwa cały niepotrzebny whitespace

Zminifikowany JSON używasz, gdy zależy ci na rozmiarze w bajtach - wysyłanie przez sieć, przechowywanie w bazie, osadzanie w URL. Sformatowany - dla plików konfiguracyjnych, logów, wszystkiego co czytają ludzie.

Sformatowany: 1 240 bajtów
Zminifikowany: 680 bajtów (-45%)

Narzędzia wykraczające poza formater

Gdy twój JSON jest już sformatowany i poprawny, czasem musisz z nim zrobić więcej:

• JSON schema - sposób definiowania, jakie pola musi mieć poprawny dokument, z typami i ograniczeniami. Jeśli masz kształt JSON, który chcesz wymuszać w wielu dokumentach, napisz schemę i waliduj względem niej.
• JMESPath / jq - języki zapytań do wyciągania lub transformowania JSON-a. jq to de facto narzędzie wiersza poleceń.
• JSON diff - narzędzia pokazujące, co się zmieniło między dwoma dokumentami JSON, bardziej użytecznie niż diff tekstowy.

Nie są potrzebne do codziennego formatowania, ale jeśli regularnie pracujesz z JSON-em, warto je znać.

Szybka ściąga

Potrzeba	Co zrobić
Uczynić JSON czytelnym	Sformatuj z wcięciem 2 spacje
Skurczyć do transportu	Zminifikuj
Znaleźć błąd składniowy	Wklej do formatera, zanotuj lokalizację błędu
Sprawdzić, czy dwa dokumenty są “takie same”	Zminifikuj oba i porównaj bajt po bajcie, albo użyj JSON diff
Dodać walidację struktury	Użyj JSON Schema
Przechować w URL lub cookie	Zminifikuj i zakoduj URI

Nawyk warty wyrobienia: nigdy nie wklejaj surowego JSON-a w mail, wiadomość na czacie lub issue trackerze bez wcześniejszego sformatowania. Zminifikowany JSON w issue na GitHubie jest na granicy czytelności i marnuje czas czytelnika. Trzydzieści sekund w formaterze zamienia ścianę tekstu w czytelną strukturę.

Nasz JSON Formatter działa w twojej przeglądarce - bez uploadów, bez round-tripów na serwer, nic nie jest logowane. Wklej JSON, kliknij Formatuj lub Minifikuj, kliknij Kopiuj, gotowe. Do naprawiania zepsutego JSON-a komunikaty błędów dokładnie odpowiadają natywnemu parserowi przeglądarki - więc to, co widzisz, pasuje do tego, co zobaczy twój kod wywołując JSON.parse().