JSON Schema to sposób opisania, jaka powinna być struktura dokumentu JSON, za pomocą innego dokumentu JSON. Zamiast ręcznie walidować dane warunkami w kodzie, można deklaratywnie opisać oczekiwane typy, wymagane pola i ograniczenia wartości, a następnie automatycznie sprawdzać dane.
Podstawowe słowa kluczowe draft-07
type— oczekiwany typ wartości (object, string, number, array itd.).required— lista pól obiektu, które muszą być obecne.properties— opis schematu dla każdego pola obiektu osobno.enum— ograniczenie wartości do konkretnego zestawu opcji.pattern— walidacja ciągu znaków wyrażeniem regularnym, np. dla formatu numeru PESEL.
Przykład: pattern dla numeru PESEL
Polski PESEL to zawsze dokładnie 11 cyfr, w których pierwsze sześć koduje datę urodzenia. Schemat dla pola w formularzu rejestracyjnym API może opisać to tak: "pesel": {"type": "string", "pattern": "^\\d{11}$"}. Nie sprawdza to cyfry kontrolnej ani tego, czy zakodowana data urodzenia w ogóle istnieje — do tego potrzebna jest osobna logika — ale od razu odrzuca oczywiste błędy: PESEL wklejony ze spacjami po trzy cyfry (jak w numerze telefonu) albo o niewłaściwej długości.
Czym różni się to od walidacji składni
Zwykła walidacja JSON sprawdza tylko, czy tekst jest poprawny składniowo — właściwe nawiasy, cudzysłowy, przecinki. JSON Schema sprawdza znacznie więcej: czy obiekt ma wymagane pole email, czy wartość age jest liczbą, a nie ciągiem znaków, czy status mieści się w dozwolonym zestawie wartości.
Do czego to potrzebne
- Sprawdzenie, czy odpowiedź zewnętrznego API odpowiada udokumentowanemu kontraktowi.
- Walidacja plików konfiguracyjnych przed wdrożeniem, aby wcześniej wychwycić błąd.
- Udokumentowanie oczekiwanej struktury danych w formacie, który od razu można automatycznie sprawdzić.
additionalProperties: czy można dodawać dodatkowe pola
Domyślnie JSON Schema pozwala w obiekcie na dowolne pola ponad te opisane w properties — required i properties ustalają jedynie minimum, a nie wyczerpującą listę. Jeśli trzeba zabronić nieznanych pól, należy jawnie dodać "additionalProperties": false — bez tej flagi schemat pozostaje „otwarty".