CDRN

Waliduj składnię JSON

  • Panel
  • Dokumentacja
  • API
sprawdza składnię ciągu JSON i wskazuje wiersz oraz kolumnę każdego błędu

Do czego służy walidator JSON?

Walidator JSON ma skromniejszą, ale bardziej precyzyjną rolę niż formater: nic nie przepisuje. Bierze ciąg i odpowiada na binarne pytanie: czy ten tekst to JSON zgodny z RFC 8259? Jeśli tak, narzędzie oddaje kontrolę. Jeśli nie, dokładnie wskazuje linię, kolumnę i wycinek JSON wokół problemu, aby pomóc programiście natychmiast naprawić.

W praktyce jest to narzędzie, którego się używa, gdy parser gdzieś zwraca kryptyczny komunikat błędu typu SyntaxError: Unexpected token } in JSON at position 217. Zamiast liczyć znaki ręcznie w edytorze, wkleja się pełen ciąg, odczytuje pozycję i widzi wadliwy wycinek.

Walidacja, formatowanie: dwie odrębne operacje

Często myli się te dwie rzeczy. Nasz formater JSON bierze prawidłowy JSON i przepisuje go z czytelnym wcięciem. Walidator natomiast ogranicza się do werdyktu składniowego. Nie wykonuje walidacji semantycznej: nie wie, czy wartość pola email przypomina email ani czy struktura odpowiada schematowi JSON Schema. Do tego używamy dedykowanych narzędzi (ajv w Node, justinrainbow/json-schema w PHP).

Klasyczna kolejność w debugowaniu to: walidacja najpierw (narzędzie wskazuje błąd składni), formatowanie następnie (teraz prawidłowy payload staje się czytelny), porównanie wreszcie z innym referencyjnym payloadem przez nasz komparator JSON.

Najczęstsze błędy JSON

  • Przecinek końcowy (trailing comma): {"a": 1, "b": 2,}. Tolerowany przez JavaScript, ECMAScript i JSON5, odrzucany przez czysty JSON. To błąd nr 1 przy kopiowaniu z edytora kodu.
  • Apostrofy zamiast podwójnych cudzysłowów: {'a': 1} jest nieprawidłowy. JSON akceptuje tylko podwójne cudzysłowy wokół kluczy jak i wartości ciągów.
  • Niecytowane klucze: {a: 1}, prawidłowa składnia JavaScript, ale nieprawidłowy JSON.
  • Nieescapowane znaki kontrolne w ciągu: surowy znak nowej linii, tabulator. JSON wymaga \n, \t, \r.
  • Komentarze: // commentaire lub /* */. Akceptowane w JSONC (config VS Code) lub JSON5, odrzucane w czystym JSON.
  • Nieprawidłowe kodowanie: BOM UTF-8 na początku pliku, źle skonwertowana treść w latin-1. Walidator często zwraca generyczny komunikat dla tych przypadków.
  • Nie zakończona struktura: { lub [ bez zamknięcia, częste gdy obcina się payload przy kopiowaniu.

Jak walidator lokalizuje błąd

Narzędzie używa json_decode() PHP z flagą JSON_THROW_ON_ERROR. PHP zwraca komunikat zawierający pozycję w bajtach (position 217), którą konwertujemy na parę linia/kolumna, licząc znaki nowej linii przed offsetem. Wycinek około 80 znaków jest następnie wycinany wokół pozycji, aby dać kontekst. Zazwyczaj wystarcza to do zlokalizowania błędu: źle umieszczonego cudzysłowu, nadmiarowego przecinka, brakującego nawiasu.

Uwaga: pozycja zgłaszana przez PHP nie zawsze jest dokładnie wadliwym znakiem. Często znajduje się po błędzie, w momencie gdy parser się poddał. Jeśli wycinek pokazuje "name": "Alice", }, rzeczywistym błędem jest przecinek, a nie nawias klamrowy.

Typowe przypadki użycia

  • Uszkodzona konfiguracja: composer.json, package.json, tsconfig.json, które uniemożliwiają uruchomienie budowania. Wklejamy, widzimy linię, poprawiamy.
  • Obcięta odpowiedź API: proxy obcięło payload. Struktura nie jest zakończona, walidator to sygnalizuje.
  • Payload webhooka: usługa zewnętrzna wysyła źle sformowany JSON. Walidator pozwala stwierdzić problem po stronie nadawcy bez zagłębiania się w kod aplikacyjny.
  • JSON zbudowany przez konkatenację: praktyka do unikania, ale częsta, zwłaszcza w bash lub SQL. Walidator ujawnia nieescapowane podwójne cudzysłowy.

Ograniczenia narzędzia

Walidator nie wykonuje walidacji względem schematu. Nie mówi, że brakuje pola email, że wartość nie jest liczbą całkowitą lub że oczekiwana tablica nie ma odpowiedniej długości. Do tych weryfikacji strukturalnych używamy JSON Schema. Walidator nie naprawia również JSON: nie próbuje dodać brakującego nawiasu klamrowego ani usunąć nadmiarowego przecinka. To wybór: automatyczna korekta zbyt często maskuje rzeczywiste błędy.

Najczęściej zadawane pytania

Jaka jest różnica w stosunku do lintera?

Linter idzie dalej: sprawdza również reguły stylu (alfabetyczne, konwencje nazewnictwa), wykrywa zduplikowane wartości, sugeruje ulepszenia. Walidator pozostaje przy zgodności składniowej.

Mój JSON jest prawidłowy, ale moja aplikacja go odrzuca?

Sprawdź kodowanie (UTF-8 bez BOM), limit rozmiaru po stronie serwera, oczekiwane typy. JSON poprawny składniowo może mimo to nie odpowiadać schematowi aplikacyjnemu.

Czy walidator przechowuje mój JSON?

Nie. Przetwarzanie jest synchroniczne po stronie serwera, bez utrwalania. Dla bardzo wrażliwych danych preferuj lokalną walidację za pomocą jq lub skryptu PHP.

Przykładowe zapytanie

curl -X POST https://cdrn.fr/api/v1/tools/json-validator/execute \
  -H "Content-Type: application/json" \
  -d '{"input":"..."}'

Schemat wejściowy

Pole Typ Wymagane Domyślnie
input text ✓ –

Punkty końcowe

  • GET https://cdrn.fr/api/v1/tools - lista wszystkich dostępnych narzędzi
  • GET https://cdrn.fr/api/v1/tools/json-validator - zwraca schemat dla tego narzędzia
  • POST https://cdrn.fr/api/v1/tools/json-validator/execute - uruchamia to narzędzie z payloadem JSON