Walidacja (Validate) JSON - poprawność, przykłady, błędy

Validate JSON, czyli walidacja JSON, to proces sprawdzania, czy dane zapisane w formacie JSON mają poprawną składnię i spełniają określone wymagania strukturalne. W praktyce oznacza to nie tylko wykrywanie brakujących przecinków, źle zamkniętych nawiasów czy błędnych cudzysłowów, ale także kontrolę tego, czy w dokumencie występują właściwe pola, typy danych, formaty wartości i relacje między elementami. Walidacja JSON jest szczególnie ważna w API, aplikacjach webowych, konfiguracjach systemów, integracjach między usługami oraz wszędzie tam, gdzie jedna aplikacja przekazuje dane drugiej.

Czym jest JSON i dlaczego trzeba go sprawdzać?

JSON, czyli JavaScript Object Notation, to lekki format wymiany danych. Jest czytelny dla człowieka, prosty do wygenerowania przez program i łatwy do odczytania przez różne języki programowania. Z tego powodu JSON jest powszechnie używany w komunikacji między aplikacjami, w konfiguracjach, plikach eksportu, systemach CMS, aplikacjach mobilnych, panelach administracyjnych i interfejsach API.

Na pierwszy rzut oka JSON wygląda bardzo prosto. Przykładowy dokument może mieć tylko kilka pól:

{
  "name": "Jan",
  "age": 32,
  "active": true
}

Problem polega na tym, że nawet niewielki błąd może sprawić, że cały dokument przestanie działać. Brak przecinka, użycie pojedynczych cudzysłowów, komentarz w niedozwolonym miejscu albo dodatkowy przecinek po ostatnim elemencie mogą wystarczyć, aby parser JSON odrzucił dane. Dlatego przed użyciem pliku lub odpowiedzi z API warto wykonać validate JSON, czyli sprawdzić poprawność danych.

Validate JSON - co właściwie oznacza walidacja JSON?

Określenie "Validate JSON" można rozumieć na dwóch poziomach. Pierwszy poziom to walidacja składniowa. Sprawdza ona, czy dokument jest poprawnym JSON-em zgodnym z regułami formatu. Drugi poziom to walidacja logiczna lub strukturalna, czyli sprawdzenie, czy dane pasują do oczekiwanego schematu.

Przykład: taki JSON może być poprawny składniowo:

{
  "email": "tekst-bez-malpy",
  "age": "trzydzieści",
  "active": "tak"
}

Technicznie dokument jest poprawny, bo ma odpowiednie nawiasy, cudzysłowy i dwukropki. Ale z punktu widzenia aplikacji może być błędny, ponieważ pole "email" nie zawiera prawidłowego adresu e-mail, "age" powinno być liczbą, a "active" powinno być wartością logiczną true albo false, a nie tekstem "tak".

Dlatego w praktyce walidacja JSON może oznaczać:

• sprawdzenie poprawności składni JSON,
• sprawdzenie wymaganych pól,
• kontrolę typów danych,
• sprawdzenie minimalnych i maksymalnych wartości,
• weryfikację formatu, np. adresu e-mail, daty lub identyfikatora,
• porównanie danych z przygotowanym schematem JSON Schema.

Poprawna składnia JSON - najważniejsze zasady

JSON ma dość restrykcyjną składnię. To jedna z jego zalet, ponieważ dzięki temu dane są przewidywalne, ale jednocześnie częsty powód błędów u osób, które ręcznie edytują pliki konfiguracyjne lub odpowiedzi testowe API.

W JSON można używać obiektów, tablic, tekstów, liczb, wartości logicznych i wartości null. Nie można natomiast stosować komentarzy, funkcji, niezacytowanych kluczy ani typowych dla niektórych języków programowania skrótów składniowych.

Najczęstsze błędy w plikach JSON

Najczęstsze błędy w JSON wynikają z ręcznej edycji danych albo kopiowania fragmentów z JavaScript, dokumentacji API, panelu administracyjnego lub pliku konfiguracyjnego. Część z nich jest łatwa do zauważenia, ale niektóre potrafią być bardzo irytujące, zwłaszcza gdy dokument ma kilkaset lub kilka tysięcy linii.

Brak przecinka między elementami

To jeden z najbardziej typowych błędów. W JSON kolejne pary klucz-wartość muszą być oddzielone przecinkami.

Błędnie:

{
  "name": "Anna"
  "email": "
 Adres poczty elektronicznej jest chroniony przed robotami spamującymi. W przeglądarce musi być włączona obsługa JavaScript, żeby go zobaczyć.
 "
}

Poprawnie:

{
  "name": "Anna",
  "email": "
 Adres poczty elektronicznej jest chroniony przed robotami spamującymi. W przeglądarce musi być włączona obsługa JavaScript, żeby go zobaczyć.
 "
}

Dodatkowy przecinek po ostatnim elemencie

W JavaScript taki zapis czasem bywa tolerowany, ale w czystym JSON jest błędny.

Błędnie:

{
  "name": "Anna",
  "email": "
 Adres poczty elektronicznej jest chroniony przed robotami spamującymi. W przeglądarce musi być włączona obsługa JavaScript, żeby go zobaczyć.
 ",
}

Poprawnie:

{
  "name": "Anna",
  "email": "
 Adres poczty elektronicznej jest chroniony przed robotami spamującymi. W przeglądarce musi być włączona obsługa JavaScript, żeby go zobaczyć.
 "
}

Pojedyncze cudzysłowy zamiast podwójnych

JSON wymaga podwójnych cudzysłowów. Pojedyncze apostrofy są błędem.

Błędnie:

{
  'name': 'Anna'
}

Poprawnie:

{
  "name": "Anna"
}

Komentarze w JSON

Czysty JSON nie obsługuje komentarzy. To częsty problem w plikach konfiguracyjnych, w których użytkownik chce dopisać krótką notatkę.

Błędnie:

{
  // główny adres e-mail użytkownika
  "email": "
 Adres poczty elektronicznej jest chroniony przed robotami spamującymi. W przeglądarce musi być włączona obsługa JavaScript, żeby go zobaczyć.
 "
}

Poprawnie:

{
  "email": "
 Adres poczty elektronicznej jest chroniony przed robotami spamującymi. W przeglądarce musi być włączona obsługa JavaScript, żeby go zobaczyć.
 "
}

Jeżeli komentarze są naprawdę potrzebne, można rozważyć inny format konfiguracyjny, np. YAML, albo zastosować pole opisowe, choć nie zawsze jest to dobry pomysł w danych produkcyjnych.

JSON validator - jak działa walidator JSON?

JSON validator to narzędzie, które analizuje wklejony tekst lub przesłany plik i sprawdza, czy jest on poprawnym JSON-em. Najprostszy walidator wykrywa błędy składniowe i wskazuje miejsce, w którym parser przestał rozumieć dokument. Bardziej rozbudowane narzędzia potrafią też formatować dane, kolorować składnię, pokazywać strukturę drzewa, zwijać elementy, sortować klucze albo sprawdzać zgodność z JSON Schema.

Typowy proces działania walidatora wygląda tak:

1. Użytkownik wkleja dokument JSON do pola edycji.
2. Walidator próbuje przetworzyć tekst zgodnie z regułami JSON.
3. Jeżeli dokument jest poprawny, narzędzie zwraca informację o sukcesie.
4. Jeżeli dokument zawiera błąd, walidator pokazuje komunikat i numer linii lub kolumny.
5. W bardziej zaawansowanych przypadkach dane są porównywane z przygotowanym schematem.

JSON Schema - walidacja struktury danych

Sama poprawność składniowa JSON nie wystarcza, gdy aplikacja oczekuje konkretnych danych. Do opisu wymaganej struktury służy JSON Schema. Pozwala on określić, jakie pola powinien mieć dokument, które z nich są wymagane, jaki typ danych jest dopuszczalny i jakie ograniczenia muszą spełniać wartości.

Przykładowy JSON z danymi użytkownika może wyglądać tak:

{
  "name": "Anna",
  "email": "
 Adres poczty elektronicznej jest chroniony przed robotami spamującymi. W przeglądarce musi być włączona obsługa JavaScript, żeby go zobaczyć.
 ",
  "age": 28,
  "active": true
}

Dla takich danych można przygotować schemat:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 18
    },
    "active": {
      "type": "boolean"
    }
  },
  "required": ["name", "email", "age"]
}

Taki schemat mówi, że dokument powinien być obiektem, pole "name" ma być tekstem, "email" powinien mieć format adresu e-mail, "age" powinno być liczbą całkowitą nie mniejszą niż 18, a "active" powinno być wartością logiczną. Dodatkowo pola "name", "email" i "age" są wymagane.

Dzięki temu walidacja nie ogranicza się do pytania: "czy to jest poprawny JSON?", ale odpowiada na ważniejsze pytanie: "czy to jest poprawny JSON dla mojego systemu?".

Validate JSON w API i aplikacjach internetowych

Walidacja JSON jest szczególnie ważna w API. Aplikacje internetowe bardzo często wysyłają i odbierają dane w tym formacie. Formularz kontaktowy, koszyk w sklepie, logowanie, rejestracja użytkownika, płatność, panel administracyjny, integracja z kurierem albo systemem fakturowania - w każdym z tych miejsc może pojawić się JSON.

Przykładowe żądanie do API może zawierać dane zamówienia:

{
  "orderId": 12345,
  "customerEmail": "
 Adres poczty elektronicznej jest chroniony przed robotami spamującymi. W przeglądarce musi być włączona obsługa JavaScript, żeby go zobaczyć.
 ",
  "items": [
    {
      "productId": 10,
      "quantity": 2
    },
    {
      "productId": 14,
      "quantity": 1
    }
  ],
  "paymentMethod": "card"
}

Aplikacja powinna sprawdzić, czy "orderId" jest liczbą, "customerEmail" jest poprawnym adresem, "items" jest tablicą, każdy produkt ma identyfikator i ilość, a "paymentMethod" zawiera jedną z dopuszczalnych wartości. Bez walidacji system może przyjąć dane niekompletne, błędne albo potencjalnie niebezpieczne.

Narzędzia do walidacji JSON

Do walidacji JSON można używać narzędzi online, edytorów kodu, bibliotek programistycznych, terminala albo funkcji wbudowanych w języki programowania. Wybór zależy od tego, czy sprawdzamy jednorazowy fragment danych, plik konfiguracyjny, odpowiedź API czy dane produkcyjne w aplikacji.

Przydatne linki do walidacji JSON

Do szybkiego sprawdzania składni JSON można wykorzystać walidatory online, a do bardziej zaawansowanej kontroli struktury danych - narzędzia obsługujące JSON Schema. Warto jednak pamiętać, aby do publicznych narzędzi nie wklejać danych poufnych, tokenów API, haseł, danych klientów ani konfiguracji produkcyjnych.

• JSONLint - prosty walidator JSON online, przydatny do szybkiego sprawdzenia składni i formatowania danych.
• JSON Formatter - narzędzie do formatowania, walidacji, podglądu i konwersji JSON.
• JSON Schema - oficjalna strona standardu JSON Schema, czyli sposobu opisywania i walidowania struktury danych JSON.
• JSON Schema Validator - interaktywny walidator do sprawdzania danych JSON względem schematu JSON Schema.
• Ajv JSON Schema Validator - popularne narzędzie programistyczne do walidacji JSON Schema w aplikacjach JavaScript i Node.js.

Walidacja, formatowanie i minifikacja JSON - czym się różnią?

Wiele narzędzi do pracy z JSON oferuje kilka podobnych funkcji, które bywają mylone. Walidacja, formatowanie i minifikacja dotyczą tego samego dokumentu, ale służą do czegoś innego.

Walidacja JSON

Walidacja odpowiada na pytanie, czy dokument jest poprawny. Może sprawdzać samą składnię albo także zgodność z określonym schematem.

Formatowanie JSON

Formatowanie, często nazywane także "beautify JSON" albo "pretty print", poprawia czytelność dokumentu. Dodaje wcięcia, nowe linie i układa strukturę tak, aby człowiek łatwiej mógł ją przejrzeć.

JSON przed formatowaniem:

{"name":"Anna","age":28,"active":true}

JSON po formatowaniu:

{
  "name": "Anna",
  "age": 28,
  "active": true
}

Minifikacja JSON

Minifikacja działa odwrotnie niż formatowanie. Usuwa zbędne spacje, wcięcia i znaki nowych linii. Dzięki temu dokument zajmuje mniej miejsca i może być szybciej przesyłany.

{"name":"Anna","age":28,"active":true}

Minifikacja nie powinna zmieniać znaczenia danych. Zmienia tylko sposób zapisu.

Walidacja JSON a bezpieczeństwo danych

Walidacja JSON ma znaczenie nie tylko dla wygody programisty, ale także dla bezpieczeństwa aplikacji. Każde dane przychodzące z zewnątrz powinny być traktowane jako potencjalnie niepewne. Dotyczy to formularzy, webhooków, publicznych endpointów API, integracji z zewnętrznymi systemami i danych importowanych z plików.

Brak walidacji może prowadzić do problemów takich jak:

• przyjęcie niepełnych danych,
• błędy aplikacji po stronie backendu,
• niepoprawne zapisy w bazie danych,
• awarie integracji między systemami,
• podatność na nieoczekiwane lub złośliwe dane wejściowe,
• problemy z obsługą bardzo dużych lub zagnieżdżonych struktur.

Szczególną ostrożność trzeba zachować przy walidatorach online. Jeżeli JSON zawiera dane osobowe, tokeny API, klucze prywatne, dane płatności, informacje klientów albo konfigurację produkcyjną, nie powinno się wklejać go do przypadkowych narzędzi dostępnych w internecie. W takich sytuacjach lepiej użyć lokalnego edytora, narzędzia CLI albo walidacji w środowisku developerskim.

Dobre praktyki przy pracy z JSON

Dobrze zaprojektowany proces walidacji JSON ogranicza liczbę błędów i ułatwia utrzymanie aplikacji. Nie chodzi tylko o jednorazowe sprawdzenie danych w narzędziu online, ale o stałą kontrolę jakości danych na różnych etapach pracy.

Waliduj dane po stronie serwera

Walidacja w przeglądarce jest wygodna dla użytkownika, ale nie wystarcza. Frontend można ominąć, zmodyfikować albo wysłać żądanie bezpośrednio do API. Dlatego ostateczna walidacja powinna odbywać się po stronie serwera.

Stosuj JSON Schema tam, gdzie dane mają stałą strukturę

Jeżeli różne systemy wymieniają dane w określonym formacie, warto opisać ten format schematem. Ułatwia to testowanie, dokumentację i komunikację między zespołami.

Nie wklejaj danych poufnych do przypadkowych walidatorów

Walidatory online są wygodne, ale nie zawsze wiadomo, co dzieje się z wklejonymi danymi. Do publicznych narzędzi najlepiej wklejać tylko przykładowe, anonimowe lub testowe fragmenty JSON.

Czytaj komunikaty błędów, ale sprawdzaj też kontekst

Numer linii i kolumny wskazany przez walidator jest bardzo pomocny, ale czasem źródło problemu znajduje się wcześniej. Warto sprawdzić poprzednią linię, ostatni przecinek, zamknięcie nawiasów i cudzysłowy.

Testuj przypadki brzegowe

Poprawny JSON z idealnymi danymi to za mało. Warto sprawdzić także puste wartości, brakujące pola, zbyt długie teksty, błędne typy, puste tablice, dodatkowe pola i nietypowe znaki.

Praktyczny przykład walidacji JSON

Załóżmy, że aplikacja przyjmuje dane użytkownika podczas rejestracji. Oczekiwany JSON wygląda tak:

{
  "username": "adam123",
  "email": "
 Adres poczty elektronicznej jest chroniony przed robotami spamującymi. W przeglądarce musi być włączona obsługa JavaScript, żeby go zobaczyć.
 ",
  "password": "TajneHaslo123",
  "newsletter": false
}

Na poziomie składni trzeba sprawdzić, czy dokument jest poprawnym JSON-em. Na poziomie struktury trzeba sprawdzić, czy:

• pole "username" istnieje i jest tekstem,
• pole "email" istnieje i ma format adresu e-mail,
• pole "password" istnieje i spełnia wymagania długości,
• pole "newsletter" jest wartością logiczną,
• nie brakuje wymaganych pól,
• nie pojawiają się wartości w nieoczekiwanym typie.

Błędny dokument może wyglądać tak:

{
  "username": "adam123",
  "email": "adam.example.com",
  "password": 123456,
  "newsletter": "nie"
}

Taki JSON może przejść prostą walidację składniową, ale powinien zostać odrzucony przez walidację strukturalną. "email" nie jest prawidłowym adresem, "password" jest liczbą zamiast tekstu, a "newsletter" jest tekstem zamiast wartości true albo false.

Kiedy warto walidować JSON?

Walidację JSON warto wykonywać zawsze wtedy, gdy dane mają wpływ na działanie aplikacji lub są przekazywane między systemami. Szczególnie ważne jest to w przypadku API, importów, eksportów, konfiguracji i automatyzacji.

Validate JSON - podsumowanie

Validate JSON to podstawowa, ale bardzo ważna czynność przy pracy z danymi. Najprostsza walidacja pozwala sprawdzić, czy dokument ma poprawną składnię. Bardziej zaawansowana walidacja, oparta na JSON Schema lub regułach aplikacji, pozwala ocenić, czy dane mają właściwą strukturę, typy i wartości.

W codziennej pracy warto pamiętać, że poprawny składniowo JSON nie zawsze oznacza poprawne dane. Dokument może być technicznie prawidłowy, a mimo to bezużyteczny dla aplikacji, jeśli brakuje w nim wymaganych pól albo wartości mają nieprawidłowy typ. Dlatego najlepsze podejście polega na połączeniu walidacji składniowej, walidacji strukturalnej i zdrowego rozsądku przy obsłudze danych wejściowych.

W przypadku prostych testów wystarczy walidator online lub edytor kodu. W projektach produkcyjnych walidacja powinna być jednak częścią aplikacji, testów i procesu integracji. To niewielki element techniczny, który może zapobiec wielu trudnym do wykrycia błędom.

FAQ - Validate JSON