Walidator i upiększacz JSON

Walidator i upiększacz JSON to bezpłatne narzędzie, które sprawdza poprawność składni JSON i formatuje prawidłowe dane, aby ich struktura była łatwiejsza do odczytania.

Na czym polega walidacja i upiększanie JSON?

Walidacja JSON potwierdza, że dane wejściowe są zgodne z gramatyką tego formatu. Upiększanie przedstawia natomiast prawidłowe obiekty i tablice z jednolitymi odstępami oraz wcięciami. Przydaje się to podczas debugowania odpowiedzi API, sprawdzania konfiguracji przed wdrożeniem i analizowania skompresowanych danych otrzymanych od innego dostawcy.

Składnia JSON jest bardziej rygorystyczna niż składnia literału obiektu JavaScript. Nazwy właściwości muszą znajdować się w podwójnych cudzysłowach, ciągów znaków nie można zapisywać w pojedynczych cudzysłowach, a po ostatnim elemencie obiektu lub tablicy nie może występować przecinek. Specyfikacja JSON nie dopuszcza też komentarzy ani wartości undefined, NaN i Infinity.

Narzędzie korzysta na serwerze z funkcji PHP json_decode. Wprowadzone dane są przesyłane na serwer przez HTTPS i nie są przechowywane. Opuszczają jednak Twoje urządzenie, dlatego usuń hasła, tokeny dostępu i dane osobowe, jeśli obowiązujące w Twojej organizacji zasady nie pozwalają wysyłać ich na zewnętrzny serwer.

Jak sprawdzić i sformatować JSON?

Wklej zawartość w polu JSON i uruchom narzędzie. Aby uzyskać przydatny wynik, podaj jedną kompletną wartość JSON, a nie fragment obiektu skopiowany z wiersza dziennika.

1. Skopiuj nieprzetworzoną odpowiedź, blok konfiguracji lub inną wartość JSON bez otaczających ją etykiet konsoli.
2. Wklej ją w polu JSON, zachowując cudzysłowy i znaki ucieczki.
3. Uruchom walidację i sprawdź sformatowany wynik albo zgłoszony błąd.
4. Jeśli walidacja się nie powiedzie, popraw pierwszy widoczny błąd składni i uruchom ją ponownie. Brak jednego cudzysłowu może sprawić, że parser nieprawidłowo zinterpretuje wiele kolejnych znaków.

Między tokenami JSON dozwolone są cztery nieistotne znaki odstępu: spacja (U+0020), tabulator (U+0009), znak nowego wiersza (U+000A) i powrót karetki (U+000D). Można je dodawać lub usuwać bez zmiany danych. Odstępy wewnątrz ciągu ujętego w cudzysłowy są częścią danych i muszą pozostać niezmienione. Zachowywane są również znaki interpunkcyjne wewnątrz ciągów, choć cudzysłowy, ukośniki odwrotne i znaki sterujące wymagają odpowiednich sekwencji ucieczki.

Jak odczytać wynik walidacji?

Powodzenie oznacza, że PHP zdołał zdekodować dane wejściowe jako JSON. Błąd wskazuje, że parser nie mógł ich zinterpretować jako jednej kompletnej i prawidłowej wartości JSON. Upiększenie poprawnych danych uwidacznia poziomy zagnieżdżenia oraz granice obiektów i tablic.

Do częstych przyczyn błędów należą:

• przecinek przed końcowym znakiem } lub ];
• nazwa właściwości bez cudzysłowów, na przykład {name: "Ada"};
• ciągi zapisane w pojedynczych cudzysłowach;
• brak przecinka między właściwościami lub elementami tablicy;
• podwójny cudzysłów lub ukośnik odwrotny bez znaku ucieczki wewnątrz ciągu;
• niekompletny obiekt, tablica lub ciąg;
• nieprawidłowe dane UTF-8 albo nieprzetworzony znak sterujący wewnątrz ciągu;
• zbędne zera na początku części całkowitej, jak w 01 lub -01, albo wartości niedozwolone w JSON, takie jak NaN.

Puste pole nie jest prawidłowym JSON-em. Z kolei samodzielna wartość, taka jak 42, true, null lub "hello", jest poprawnym JSON-em, mimo że nie stanowi obiektu ani tablicy. Bardzo głęboko zagnieżdżona zawartość może też przekroczyć limit zagnieżdżenia dekodera.

Walidacja składni nie potwierdza zgodności danych z kontraktem API. Dokument może być prawidłowym JSON-em, a mimo to zawierać ciąg znaków w miejscu, w którym aplikacja oczekuje liczby, pomijać wymaganą właściwość albo używać niedopuszczalnego formatu daty. Takie wymagania sprawdzaj za pomocą JSON Schema lub mechanizmów walidacji w aplikacji.

Przykłady danych JSON

Prawidłowe dane w zwartej postaci:

{"name":"Ada","active":true,"roles":["admin","editor"]}

Po upiększeniu właściwości i elementy tablicy są wyświetlane na osobnych poziomach z odpowiednimi wcięciami. Poszczególne wartości nadal są odpowiednio ciągiem znaków, wartością logiczną i tablicą. Formatowanie zmienia sposób prezentacji, a nie bazowe typy danych.

Nieprawidłowe dane z końcowym przecinkiem:

{"name":"Ada","active":true,}

Walidacja kończy się błędem, ponieważ JSON nie dopuszcza przecinka po ostatniej właściwości. Usuń go, aby obiekt stał się prawidłowy.

Znaki diakrytyczne i tekst zapisany alfabetem innym niż łaciński mogą występować bezpośrednio w ciągach JSON, jeśli dane wejściowe są prawidłowo zakodowane w UTF-8. Na przykład {"city":"Zürich","greeting":"こんにちは"} jest poprawny. Notacja ucieczki JSON, taka jak \u00fc, to inny prawidłowy sposób zapisu niektórych znaków Unicode. Znaki spoza podstawowej płaszczyzny wielojęzycznej wymagają jednak par zastępczych.

Kiedy nie warto upiększać JSON?

Upiększanie jest zbędne, gdy JSON będzie odczytywany wyłącznie przez maszynę i nie planujesz sprawdzania go przez człowieka ani przeglądania zmian w systemie kontroli wersji. Dodatkowe wcięcia i podziały wierszy zwiększają liczbę przesyłanych bajtów, dlatego odpowiedzi produkcyjne są zwykle wysyłane w zwartej postaci.

Minifikowanie JSON-u, który już ma zwartą postać, również niewiele daje. Wielokrotna minifikacja nie skróci stałych nazw właściwości ani wartości tekstowych, a ich zmiana oznaczałaby zmianę danych. Jeśli chcesz przygotować do wdrożenia kod JavaScript, a nie dane JSON, odpowiednim narzędziem będzie Minifikator JS.

Upiększanie jest najbardziej przydatne podczas sprawdzania struktur i wartości JSON w trakcie debugowania, przeglądu kodu oraz kontroli przed wdrożeniem. Uwidacznia nieprawidłowe zagnieżdżenia, ułatwia przeglądanie dużych tablic i pozwala uzyskać czytelniejsze różnice po zapisaniu konfiguracji w Git. Nie naprawia automatycznie błędnego JSON-u ani nie rozstrzyga, jakie znaczenie miał mieć niejednoznaczny fragment.

Najczęściej zadawane pytania

Czy JSON może zawierać komentarze?

Nie. Standard JSON nie definiuje składni komentarzy, dlatego // comment i /* comment */ powodują błąd walidacji. Jeśli potrzebujesz komentarzy w pliku konfiguracyjnym, wybierz format, który je obsługuje, albo usuń je przed przekazaniem zawartości do parsera ściśle przestrzegającego składni JSON.

Czy powtarzające się nazwy właściwości zostaną odrzucone?

Niekoniecznie. Specyfikacja JSON wskazuje, że nazwy elementów w obiekcie powinny być unikatowe, ale parsery nie zawsze traktują duplikaty jako błąd składni. Dekoder PHP zwykle zachowuje późniejszą wartość. Jeśli musisz zachować każde wystąpienie, wykryj duplikaty przed walidacją.

Czy można sprawdzić plik JSON Lines?

Nie jako jeden dokument JSON. Format JSON Lines, nazywany też NDJSON, zawiera osobną wartość JSON w każdym wierszu, podczas gdy zwykły parser JSON oczekuje jednej wartości najwyższego poziomu. Sprawdź każdy wiersz oddzielnie albo przekształć rekordy w jedną tablicę JSON.

Czy kolejność właściwości w obiekcie JSON ma znaczenie?

Aplikacje nie powinny polegać na kolejności właściwości obiektu JSON. Tablice są uporządkowane, ale obiekty reprezentują zbiory nazwanych elementów, a inny parser lub serializator może zapisać je w odmiennej kolejności. Jeśli kolejność ma znaczenie, umieść wartości w tablicy.

Dlaczego plik JSON nie przechodzi walidacji, choć wygląda poprawnie?

Niewidoczny znacznik kolejności bajtów, błędne kodowanie UTF-8 lub znak sterujący bez sekwencji ucieczki mogą spowodować odrzucenie pozornie prawidłowej zawartości. Kopiowanie z terminala może też dodać prefiksy, na przykład etykiety stanu lub znaczniki czasu. Sprawdź nieprzetworzone bajty albo otwórz plik w edytorze, który potrafi wyświetlać kodowanie i znaki sterujące.

Kontrola końcowa

Przed wdrożeniem poprawionego JSON-u porównaj nie tylko widoczne wartości, ale również typy danych. Sprawdź, czy sekwencje ucieczki się nie zmieniły, a następnie uruchom aplikację korzystającą z tych danych lub jej walidację schematu. Podczas diagnozowania danych od zewnętrznego dostawcy zachowaj nienaruszoną kopię pierwotnej odpowiedzi, aby formatowanie nie utrudniło ustalenia źródła błędu.