Co JSON Schema naprawdę rozwiązuje
Podsumowanie: Schemat rządzi strukturą i typami, a nie znaczeniem biznesowym. Zatrzymuje brakujące pola, złe typy i wyliczenia poza zakresem, podczas gdy reguły takie jak kwota większa od zera zostają w kodzie.
Najważniejsze: pozwól JSON Schema wymuszać strukturę, typy, zakresy i formaty, podczas gdy reguły między polami, niezmienny biznesowe i stan zewnętrzny zostają w kodzie; przyjmuj je dla publicznych API i współdzielonych ładunków, a nie dla wewnętrznej usługi z pięcioma polami.
Odpowiada na „czy te dane mają poprawny kształt”, a nie „czy te dane mają sens”.
Co robi dobrze
Kompletność strukturalna. Które pola muszą istnieć, czy dodatkowe są dozwolone (required, additionalProperties).
Typy. port jako liczba lub łańcuch, tags jako tablica lub skalar. To samo usuwa dużo kodu defensywnego w systemach wielojęzycznych.
Zakresy. enum, minimum/maximum, długość łańcuchów i tablic.
Formaty. format dla dat, e-maili, URI i UUID, z walidatorami, które je wymuszają.
Zagnieżdżenie. Każdy poziom obiektów i tablic dostaje własne ograniczenia, a błędy niosą precyzyjną ścieżkę.
Dokumentacja. Schemat jest kontraktem. Zmień pole, a diff pokaże zasięg oddziaływania. Generuje też typy i formularze, więc jedna definicja zasila kilka konsumentów.
Czego nie potrafi
Zależności między polami. „Koniec musi być po początku” da się wyrazić przez if/then/else, ale wynik jest dłuższy i trudniejszy do odczytania niż trzy linie kodu.
Niezmienny biznesowe. „Stan magazynowy nie może stać się ujemny” zależy od stanu zewnętrznego. Schemat widzi jeden dokument.
Semantyka. price: -100 doskonale spełnia {"type": "number"}. Czy to legalna cena, jest poza wiedzą Schematu.
Wykonalny podział
| Warstwa | Właściciel |
|---|---|
| Składnia: czy to poprawny JSON | Parser |
| Struktura: pola, typy, zakresy, formaty | JSON Schema |
| Semantyka: między polami, reguły biznesowe, stan zewnętrzny | Kod aplikacji |
| Bezpieczeństwo: rozmiar, głębokość, tempo | Brama / middleware |
Zwiń to w jedno miejsce, a Schemat urośnie do setek linii z pięcioma poziomami if/then. Wtedy ludzie zaczynają go obchodzić.
Kiedy się opłaca
- Publiczne API z nieznanymi konsumentami
- Wiele usług czytających ten sam ładunek
- Systemy napędzane konfiguracją, gdzie literówki muszą zawodzić szybko
- Generowanie typów lub formularzy z kontraktu
Dla małej wewnętrznej usługi z pięcioma polami i jednym frontendem ręcznie pisane kontrole są szybsze w utrzymaniu. Wprowadzanie tam Schematu to praca ujemna.
FAQ
Jak zdecydować, czy przyjąć JSON Schema?
Rozważ publicznych konsumentów, wiele usług czytających ten sam ładunek i potrzebę generowania typów lub formularzy. Dla małej wewnętrznej usługi z pięcioma polami i jednym frontendem ręcznie pisane kontrole są szybsze w utrzymaniu.
Dlaczego reguły między polami powinny zostawać w kodzie?
„Koniec musi być po początku” da się wcisnąć w if/then/else, ale wynik jest dłuższy i trudniejszy do odczytania niż kilka linii kodu. Schemat nie widzi też stanu zewnętrznego.
Czy Schema powinien walidować rozmiar ładunku i głębokość zagnieżdżenia?
Nie. Schemat opisuje strukturę, a nie rozmiar czy głębokość; te limity należą do warstwy bramy lub middleware.