Walidacja JSON Schema: kompletny przewodnik po wersjach i regulach

Czym jest JSON Schema?

JSON Schema to słownik do adnotowania i walidowania dokumentów JSON. Definiuje strukturę, typy i ograniczenia, które musi spełniać dokument JSON. Pomyśl o tym jak o kontrakcie — schemat opisuje, jak wyglądają prawidłowe dane, a walidatory sprawdzają, czy dokument jest zgodny z tym kontraktem.

JSON Schema jest napisana w samym JSON, co czyni ją maszynoczytelną i niezależną od języka. Jest obsługiwana przez walidatory we wszystkich głównych językach programowania (JavaScript/Ajv, Python/jsonschema, Java/everit, Go/gojsonschema) i jest używana do walidacji API, plików konfiguracyjnych i generowania formularzy.

Podstawy JSON Schema

Podstawowe słowa kluczowe definiują kształt prawidłowych dokumentów JSON.

• type — określa dozwolony typ JSON: string, number, integer, boolean, object, array lub null. Najbardziej fundamentalne ograniczenie.
• properties i required — dla obiektów 'properties' definiuje schemat każdego pola, a 'required' wymienia, które pola muszą być obecne. Pola nieujęte w 'required' są domyślnie opcjonalne.
• enum i const — 'enum' ogranicza wartość do stałego zestawu wyborów, natomiast 'const' ogranicza ją do jednej dokładnej wartości. Przydatne dla pól statusu, kategorii i opcji konfiguracyjnych.
• pattern i format — 'pattern' waliduje ciągi względem wyrażenia regularnego. 'format' zapewnia walidację semantyczną jak 'email', 'uri', 'date-time' i 'ipv4' bez regex.

Te podstawowe słowa kluczowe pokrywają większość potrzeb walidacyjnych. Prosty schemat może definiować typ obiektu z wymaganą właściwością 'name' (string) i opcjonalną 'age' (integer, minimum 0).

Zaawansowane funkcje schematów

Dla złożonych wymagań walidacyjnych JSON Schema oferuje kompozycję, referencje i logikę warunkową.

• $ref referencje — ponownie używaj definicji schematu, odwołując się do nich przez $ref. Wskazuj na definicje w tym samym dokumencie ($ref: #/$defs/Address) lub plikach zewnętrznych. Eliminuje duplikację w dużych schematach.
• allOf / anyOf / oneOf — słowa kluczowe kompozycji łączące wiele schematów. 'allOf' wymaga dopasowania wszystkich pod-schematów, 'anyOf' wymaga co najmniej jednego, a 'oneOf' wymaga dokładnie jednego. Przydatne dla typów polimorficznych.
• if / then / else — schematy warunkowe stosujące różne reguły walidacji na podstawie wartości danych. Na przykład jeśli kraj to 'US', to kod pocztowy musi pasować do wzorca 5-cyfrowego, w przeciwnym razie dopuść dowolny format.
• additionalProperties — kontroluje, czy obiekt może zawierać właściwości nieujęte w 'properties'. Ustaw na false dla ścisłej walidacji lub na schemat, aby ograniczyć dodatkowe właściwości.

Wersje robocze schematów

JSON Schema ewoluowała przez kilka wersji roboczych, z których każda dodawała nowe funkcje i udoskonalała istniejące zachowanie.

• Draft-04 — pierwsza szeroko przyjęta wersja. Wprowadzono $ref, required jako tablicę i podstawowe słowa kluczowe walidacji. Nadal używana w wielu starszych systemach i OpenAPI 3.0.
• Draft-06 — dodano słowo kluczowe const, propertyNames, contains dla tablic i schematy boolowskie (true/false jako prawidłowe schematy). Niewielkie, ale przydatne dodatki.
• Draft-07 — dodano logikę warunkową if/then/else, adnotacje readOnly/writeOnly i słowa kluczowe kodowania treści. Najpopularniejsza wersja robocza dzisiaj.
• 2019-09 (Draft 2019-09) — główna restrukturyzacja. Wprowadzono $defs (zastępując definitions), $anchor, unevaluatedProperties i system słowników. Lepsze do projektowania schematów na dużą skalę.
• 2020-12 (Draft 2020-12) — najnowsza stabilna wersja robocza. Udoskonalono dynamiczne referencje, dodano prefixItems do walidacji krotek (zastępując items jako tablicę) i ulepszono formaty wyjściowe. Zalecane dla nowych projektów.

Typowe przypadki użycia

JSON Schema jest używana wszędzie tam, gdzie dane JSON muszą być walidowane lub dokumentowane.

• Walidacja API — waliduj treści żądań i parametry zapytań względem schematów w middleware Express/Fastify. Specyfikacje OpenAPI/Swagger osadzają JSON Schema dla definicji kontraktu API.
• Walidacja konfiguracji — waliduj pliki konfiguracyjne aplikacji (JSON, YAML skonwertowany do JSON) podczas uruchamiania. Wyłapuj literówki i brakujące pola zanim spowodują błędy w czasie wykonania.
• Generowanie formularzy — narzędzia takie jak react-jsonschema-form i vue-jsonschema-form automatycznie generują formularze HTML z definicji JSON Schema, w tym reguły walidacji i widżety UI.
• Generowanie kodu — generuj interfejsy TypeScript, struktury Go lub dataclasses Pythona z definicji JSON Schema. Utrzymuje typy zsynchronizowane z kontraktami API.

Typowe błędy walidacji

Podczas walidowania JSON względem schematu, oto najczęstsze błędy, z którymi się spotkasz.

• Niezgodność typów — typ wartości nie zgadza się z ograniczeniem 'type' schematu. Częste przykłady: string gdzie oczekiwana jest liczba, null dla pola niemogącego być null lub obiekt gdzie wymagana jest tablica.
• Brakujące wymagane pola — obiektowi JSON brakuje właściwości wymienionej w tablicy 'required'. Walidatory raportują, które konkretne pole jest brakujące.
• Błąd wzorca — wartość tekstowa nie pasuje do wyrażenia regularnego 'pattern'. Często wykrywa nieprawidłowe formaty adresów e-mail, numerów telefonów lub własnych identyfikatorów, które nie są zgodne z oczekiwanym wzorcem.
• Błąd rozwiązania $ref — schemat odwołuje się do innego schematu przez $ref, który nie może zostać znaleziony. Dzieje się tak, gdy brakuje wpisu $defs, ścieżka jest błędna lub zewnętrzne pliki schematu są niedostępne.

Często zadawane pytania

Którego szkicu JSON Schema powinienem używać w nowych projektach?

Używaj Draft 2020-12 w nowych projektach, chyba że masz ograniczenia. Ma najwięcej funkcji (prefixItems dla krotek, unevaluatedProperties, dynamiczne referencje) i najwyższą jakość specyfikacji. Jeśli potrzebujesz zgodności z OpenAPI 3.0, użyj Draft-04. Jeśli potrzebujesz najszerszego wsparcia bibliotek, Draft-07 jest najbezpieczniejszym wyborem — obsługuje go niemal każdy walidator.

Jak mogę ponownie używać schematów w wielu plikach?

Używaj $ref do odwoływania się do schematów przez URI. Dla definicji lokalnych umieść wielokrotnie używane schematy pod $defs w tym samym pliku i odwołaj się do nich przez $ref: '#/$defs/SchemaName'. Dla odwołań między plikami używaj względnych URI ($ref: './address.json') lub bezwzględnych URI. Większość walidatorów obsługuje zarówno lokalne, jak i zdalne rozwiązywanie $ref.

Czy JSON Schema może walidować zagnieżdżone obiekty?

Tak. Definiuj zagnieżdżone schematy we właściwościach 'properties' obiektu nadrzędnego. Każda zagnieżdżona właściwość może mieć własny typ, wymagane pola i reguły walidacji. W przypadku głęboko zagnieżdżonych struktur używaj $ref, aby schemat pozostał czytelny. Głębokość zagnieżdżenia nie jest ograniczona — walidator rekurencyjnie sprawdza każdy poziom.