Jak walidować JSON: Kompletny przewodnik z przykładami

JSON (JavaScript Object Notation) jest podstawą nowoczesnych API webowych, plików konfiguracyjnych i wymiany danych. Ale nieprawidłowy JSON może powodować awarie aplikacji, niepowodzenia integracji API i godziny frustracji przy debugowaniu. Ten przewodnik przeprowadzi cię przez wszystko, co musisz wiedzieć o walidacji JSON, od podstawowego sprawdzania składni po zaawansowaną walidację Schema z rzeczywistymi przykładami.

Dlaczego walidacja JSON jest ważna

Nieprawidłowy JSON jest jednym z najczęstszych źródeł błędów w aplikacjach webowych. Źle umieszczony przecinek, niezacytowany klucz lub przecinek końcowy mogą spowodować, że JSON.parse() zgłosi SyntaxError, załamując cały potok danych. Walidacja wychwytuje te błędy wcześnie, zanim rozprzestrzenią się w systemie i spowodują awarie downstream.

Poza poprawnością składniową, walidacja zapewnia również zgodność danych JSON z oczekiwaną strukturą. API może zwrócić poprawny JSON, ale z brakującymi wymaganymi polami, nieprawidłowymi typami danych lub wartościami poza akceptowalnym zakresem. Walidacja Schema rozwiązuje te problemy strukturalne.

Reguły składni JSON

Zanim zagłębisz się w narzędzia walidacyjne, kluczowe jest zrozumienie reguł, które czynią JSON poprawnym. JSON ma ścisłą składnię zdefiniowaną przez RFC 8259, a nawet pojedyncze naruszenie znaku unieważnia cały dokument.

Stringi muszą używać podwójnych cudzysłowów

Wszystkie wartości stringów i klucze obiektów muszą być ujęte w podwójne cudzysłowy. Pojedyncze cudzysłowy nie są prawidłowymi separatorami stringów JSON — to częsty błąd popełniany przez programistów przechodzących z JavaScript.

// Invalid - single quotes
{'name': 'Alice', 'age': 30}

// Valid - double quotes
{"name": "Alice", "age": 30}

Klucze obiektów muszą być w cudzysłowach

W przeciwieństwie do literałów obiektów JavaScript, JSON wymaga, aby wszystkie klucze obiektów były ujęte w podwójne cudzysłowy. Niezacytowane klucze są błędem składniowym.

// Invalid - unquoted keys
{name: "Alice", age: 30}

// Valid - quoted keys
{"name": "Alice", "age": 30}

Przecinek końcowy niedozwolony

JSON nie zezwala na przecinek po ostatnim elemencie obiektu lub tablicy. To kolejny częsty błąd, szczególnie przy ręcznej edycji JSON.

// Invalid - trailing comma
{
  "name": "Alice",
  "age": 30,
}

// Valid - no trailing comma
{
  "name": "Alice",
  "age": 30
}

Komentarze nieobsługiwane

JSON nie obsługuje komentarzy. // komentarze jednoliniowe i /* */ komentarze wieloliniowe są nieprawidłowe w JSON. Jeśli potrzebujesz dokumentacji, użyj osobnego pliku lub formatu takiego jak JSONC.

Częste błędy walidacji JSON

Zrozumienie najczęstszych błędów pomaga szybko je wykryć i naprawić. Oto błędy, które najczęściej napotkasz:

• Nieoczekiwany token: Zwykle spowodowany pojedynczymi cudzysłowami, niezacytowanymi kluczami lub przecinkami końcowymi. Komunikat o błędzie zawiera lokalizację, gdzie parsowanie się nie powiodło.
• Nieoczekiwany koniec danych JSON: String JSON jest niekompletny lub pusty. Zazwyczaj dzieje się tak, gdy żądanie sieciowe zwraca pustą odpowiedź.
• Nieoczekiwany znak niebędący białym znakiem: Dodatkowa treść po głównej wartości JSON, na przykład drugi obiekt nieopakowany w tablicę.
• Nieprawidłowa liczba: Liczby z zerami wiodącymi (z wyjątkiem samego 0), notacja szesnastkowa lub wartości NaN / Infinity nie są prawidłowym JSON.

Walidacja JSON w JavaScript

Najprostszym sposobem walidacji JSON w JavaScript jest opakowanie JSON.parse() w blok try-catch. Jeśli JSON jest nieprawidłowy, metoda zgłasza SyntaxError.

function validateJSON(jsonString) {
  try {
    JSON.parse(jsonString);
    return { valid: true };
  } catch (error) {
    return {
      valid: false,
      error: error.message
    };
  }
}

const result = validateJSON('{"name": "Alice"}');
console.log(result);
// { valid: true }

const badResult = validateJSON("{'name': 'Alice'}");
console.log(badResult);
// { valid: false, error: "Unexpected token '..." }

Walidacja JSON w Python

Python udostępnia moduł json z funkcją json.loads() do parsowania stringów JSON. Podobnie jak w JavaScript, nieprawidłowy JSON zgłasza json.JSONDecodeError ze szczegółowymi informacjami o lokalizacji.

import json

def validate_json(json_string):
    try:
        json.loads(json_string)
        return {"valid": True}
    except json.JSONDecodeError as e:
        return {
            "valid": False,
            "error": str(e),
            "line": e.lineno,
            "column": e.colno
        }

result = validate_json('{"name": "Alice"}')
print(result)
# {'valid': True}

Walidacja JSON Schema

Walidacja składniowa mówi tylko, czy JSON jest poprawnie sformatowany. JSON Schema pozwala zdefiniować oczekiwaną strukturę i walidować dane względem niej. Schema określa wymagane pola, typy danych, zakresy wartości, wzorce stringów i struktury zagnieżdżonych obiektów.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "email"],
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0 }
  }
}

Popularne walidatory JSON Schema obejmują Ajv dla JavaScript, jsonschema dla Pythona i json-schema-validator dla Javy. Biblioteki te walidują dane JSON względem Twojego Schema i generują szczegółowe komunikaty o błędach dla każdego naruszenia.

Narzędzia do walidacji JSON online

Gdy potrzebujesz szybko sprawdzić dokument JSON bez pisania kodu, walidatory online są najszybszą opcją. Zapewniają natychmiastową informację zwrotną z podświetlaniem błędów i numerami linii.

Najlepsze praktyki walidacji JSON

• Waliduj wcześnie: Sprawdzaj JSON na granicach systemu (takich jak endpointy API i funkcje importu plików), zanim dane wejdą do logiki biznesowej.
• Używaj walidacji Schema: Poza składnią, używaj JSON Schema do walidacji struktury danych, aby wychwycić brakujące pola, nieprawidłowe typy i wartości poza zakresem.
• Dostarczaj jasne komunikaty o błędach: Gdy walidacja się nie powiedzie, podaj ścieżkę pola, oczekiwany typ i rzeczywistą wartość, aby pomóc użytkownikom szybko naprawić problemy.
• Waliduj zarówno po stronie klienta, jak i serwera: Walidacja po stronie klienta zapewnia natychmiastową informację zwrotną, podczas gdy walidacja po stronie serwera zapewnia bezpieczeństwo i integralność danych.
• Automatyzuj walidację w CI/CD: Używaj narzędzi takich jak ajv-cli lub jsonschema do walidacji fixture'ów JSON i plików konfiguracyjnych w potoku budowania.
• Rejestruj błędy walidacji: Rejestruj niepowodzenia walidacji z kontekstem, aby identyfikować wzorce i naprawiać przyczyny źródłowe u producentów danych.