Kluczowe punkty
- 01Zasilany przez Ajv, najpopularniejszą bibliotekę walidatora schematu JSON w JavaScript — to, co przejdzie tutaj, przejdzie w Node.js, Fastify i większości łańcuchów narzędzi JS.
- 02Raportuje każdy błąd walidacji naraz (tryb allErrors), a nie tylko pierwszą awarię.
- 03Każdy błąd zawiera ścieżkę JSON Pointer do pola, które nie przeszło walidacji, aby umożliwić szybką nawigację.
- 04Zarówno schemat jak i dane działają całkowicie w Twojej przeglądarce — nic nie jest przesyłane.
Dlaczego walidować JSON względem schematu?
JSON Schema to standardowy sposób opisania struktury dokumentu JSON — wymagane pola, dozwolone typy, ograniczenia wartości, struktury zagnieżdżonych obiektów. Walidacja względem schematu przed dotarciem ładunku do produkcji wyłapuje niezgodności typów, brakujące wymagane pola i naruszenia ograniczeń wcześnie, gdy są tanie do naprawienia.
Najczęstsze przypadki użycia to testowanie treści żądań i odpowiedzi API, walidacja plików konfiguracyjnych, sprawdzanie przykładowych obiektów OpenAPI i weryfikacja eksportów danych względem znanej struktury. Walidator Handytool używa Ajv — de facto biblioteki JavaScript JSON Schema, używanej wewnątrz samego Node.js — więc wyniki tutaj odpowiadają temu, co zobaczy Twój backend.
Jak walidować JSON względem schematu
- 01
Wklej swój schemat JSON
Wklej schemat w lewym panelu. Może to być schemat Draft 7, 2019-09 lub 2020-12 z type, properties, required, items, anyOf, allOf — dowolnym standardowym słowem kluczowym obsługiwanym przez Ajv.
- 02
Wklej swoje dane JSON
Wklej dokument danych, który chcesz walidować, w prawym panelu. To jest instancja — treść żądania API, obiekt konfiguracyjny, rekord eksportu lub pojedynczy przykład z Twojej specyfikacji OpenAPI.
- 03
Kliknij Waliduj
Ajv uruchamia walidację z allErrors: true, co oznacza, że zbiera każdą awarię zamiast zatrzymywać się na pierwszej.
- 04
Przejrzyj listę błędów
Każdy błąd pokazuje ścieżkę JSON Pointer do wartości, która nie przeszła (np. /user/email), słowo kluczowe, które nie przeszło (type, required, minimum) i czytelny dla człowieka komunikat. Napraw każdy i ponownie waliduj.
Co deweloperzy walidują za pomocą schematu JSON
- 01Treści żądań REST API — potwierdź, że ładunek odpowiada oczekiwanej strukturze punktu końcowego przed wysłaniem.
- 02Przykładowe obiekty specyfikacji OpenAPI — waliduj każdy przykład względem wbudowanego komponentu schematu.
- 03Pliki konfiguracyjne — upewnij się, że wymagane klucze są obecne i wartości mają prawidłowy typ.
- 04Rekordy potoku danych — wykryj dryf strukturalny między producentami i konsumentami danych.
- 05Ładunki przesyłania formularza — przetestuj, czy walidacja frontendu odzwierciedla ograniczenia schematu backendu.
- 06Treści webhooków stron trzecich — potwierdź, że udokumentowany schemat odpowiada rzeczywistemu ładunkowi.
Prywatna walidacja bez wymaganego serwera
Ajv działa całkowicie w Twojej przeglądarce. Ani schemat, ani dane nie są wysyłane na żaden serwer — możesz bezpiecznie walidować schematy opisujące wewnętrzne struktury danych i obiekty danych zawierające wrażliwe wartości pól.
Walidator obsługuje schematy JSON drafts 6, 7, 2019-09 i 2020-12. Najczęstszym draftem w użyciu jest Draft 7, który obejmuje wszystkie codzienne słowa kluczowe: type, properties, required, items, minimum, maximum, pattern, enum, anyOf, allOf, oneOf, not i $ref.
Walidator schematu JSON — najczęściej zadawane pytania
Które drafty schematu JSON są obsługiwane?
Ajv obsługuje drafty 6, 7, 2019-09 i 2020-12. Draft 7 jest najczęstszy w istniejących bazach kodu i obejmuje wszystkie standardowe słowa kluczowe.
Dlaczego mój schemat $ref nie jest rozwiązywany?
Zewnętrzne adresy URL $ref nie są pobierane w tym narzędziu działającym tylko w przeglądarce. Wbuduj wszystkie schematy, do których się odwołujesz, używając $defs i lokalnych wskaźników JSON, takich jak #/$defs/MyType.
Czy mój schemat lub dane są przesyłane na jakiś serwer?
Nie. Ajv działa całkowicie w Twojej przeglądarce — zarówno schemat jak i dane pozostają na Twoim urządzeniu.
Czy mogę użyć tego do walidacji specyfikacji OpenAPI 3?
Możesz walidować poszczególne komponenty schematu i obiekty przykładowe. Walidacja całego dokumentu OpenAPI wymaga dedykowanego walidatora OpenAPI, który rozumie meta-schemat specyfikacji.
Dlaczego widzę wiele błędów zamiast tylko pierwszego?
Walidator jest skonfigurowany z allErrors: true, co powoduje, że Ajv zbiera każdą awarię zamiast zatrzymywać się na pierwszej. Jest to celowe — możesz naprawić wszystkie problemy w jednym przejściu zamiast wykonywać powtórzone próby walidacji.