Zrozumienie JSON Schema: Waliduj dane jak profesjonalista

Czy kiedykolwiek miałeś buga, gdzie API zwróciło "42" (string) zamiast 42 (liczba) i wszystko poniżej się posypało? Albo ktoś wysłał żądanie bez wymaganego pola i aplikacja się zawiesiła zamiast zwrócić pomocny komunikat o błędzie? JSON Schema istnieje właśnie po to, żeby zapobiegać takim problemom.

Pomyśl o tym jak o planie dla twoich danych JSON — opisuje, jaki kształt dane powinny mieć, i wyłapuje wszystko, co się nie zgadza.

Jak wygląda JSON Schema

JSON Schema jest pisany w JSON-ie (meta, prawda?). Oto prosty schemat dla obiektu użytkownika:

To mówi: „Oczekuję obiektu z wymaganym name (niepusty string) i email (poprawny format email), plus opcjonalne age (liczba całkowita od 0 do 150)." Jeśli ktoś wyśle {"name": "", "email": "not-an-email"}, walidator wyłapie oba problemy.

Budowanie schematów krok po kroku

Zacznij od typu. Każdy schemat zaczyna się od "type": object, array, string, number, integer, boolean lub null.

Dodaj ograniczenia. Dla stringów: minLength, maxLength, pattern (regex). Dla liczb: minimum, maximum, multipleOf. Dla tablic: minItems, maxItems, uniqueItems. Oficjalny przewodnik JSON Schema ma pełną listę.

Oznacz wymagane pola. Użyj tablicy "required" na poziomie obiektu. Wymieniaj tylko pola, które naprawdę muszą być obecne — nie rób wszystkiego wymaganym, chyba że naprawdę tego chcesz.

Definiuj zagnieżdżone obiekty. Po prostu umieść definicje schematu wewnątrz "properties". Oto użytkownik z adresem:

Ten pattern na kodzie pocztowym? Zapewnia, że akceptowane są tylko 5-cyfrowe kody pocztowe US. Taka walidacja z życia wzięta zapobiega wpadaniu śmieciowych danych do twojej bazy danych.

Dlaczego naprawdę powinieneś tego używać

Walidacja API: Waliduj przychodzące ciała żądań na brzegu API. Złe dane są odrzucane z jasnymi komunikatami o błędach, zanim dotkną twojej logiki biznesowej. Większość frameworków to wspiera — Ajv dla JavaScript jest błyskawiczny.

Walidacja konfiguracji: Waliduj pliki konfiguracyjne przy starcie aplikacji. Zawiódź szybko z jasnym komunikatem „w twojej konfiguracji brakuje pola database.host" zamiast kryptycznego wyjątku null pointer 5 minut później.

Dokumentacja: JSON Schema służy jako żywa dokumentacja. Narzędzia jak Swagger UI generują dokumentację API bezpośrednio ze schematów.

Generowanie kodu: Generuj interfejsy TypeScript, struktury Go lub dataclassy Python ze swojego schematu. Napisz raz, używaj wszędzie.

Testowanie: Waliduj odpowiedzi API w swoim zestawie testów, żeby automatycznie wyłapywać regresje.

Zacznij w 30 sekund

Najszybszy sposób na start? Wygeneruj schemat z istniejących danych JSON. Wklej przykładową odpowiedź JSON w nasz JSON Schema Generator — przeanalizuje dane i wygeneruje schemat, który możesz doprecyzować. Następnie przetestuj go naszym JSON Schema Validator na prawdziwych danych.

Możesz też walidować programistycznie. Oto szybki przykład w Node.js z Ajv:

Dla Pythona sprawdź bibliotekę jsonschema. Dla Javy jest everit-json-schema. Praktycznie każdy język ma solidne wsparcie — sprawdź pełną listę implementacji.

Zaawansowane funkcje schematu, które powinieneś znać

Kiedy opanujesz podstawy, JSON Schema oferuje potężne funkcje, które umożliwiają złożoną walidację.

oneOf, anyOf, allOf — Łączenie schematów:

Czasami pole może być jednym z kilku typów. Na przykład API może akceptować zarówno ID w formie stringa, jak i numeryczne ID:

Ten schemat akceptuje zarówno {"id": "PRD-1234"}, jak i {"id": 42}, ale odrzuca {"id": -1} lub {"id": "invalid"}.

$ref — Wielokrotnie używane definicje schematów:

W miarę jak twoje schematy rosną, będziesz chciał unikać powtarzania tych samych definicji. Słowo kluczowe $ref pozwala odwoływać się do współdzielonych definicji:

Teraz zarówno billing_address, jak i shipping_address używają dokładnie tych samych reguł walidacji. Zmień definicję address raz, a oba pola się zaktualizują. To jest niezbędne do utrzymania dużych schematów w porządku.

additionalProperties — Zablokuj swoje obiekty:

Domyślnie JSON Schema pozwala na dodatkowe właściwości, które nie są wymienione w properties. To często NIE jest to, czego chcesz — nieoczekiwane pola mogą wskazywać na buga klienta lub niezgodność wersji. Ustaw "additionalProperties": false, żeby odrzucać nieznane pola:

Z tym schematem {"name": "Alice", "email": "[email protected]", "admin": true} zostanie odrzucony, ponieważ admin nie jest zdefiniowaną właściwością.

Częste błędy JSON Schema

Nawet doświadczeni programiści popełniają te błędy przy pisaniu schematów:

1. Zapominanie, że required jest na poziomie obiektu, a nie właściwości. To jest błędne:

Poprawny sposób to:

2. Używanie "type": "number", kiedy masz na myśli "type": "integer". Typ number akceptuje liczby dziesiętne jak 3.14, podczas gdy integer akceptuje tylko liczby całkowite. Jeśli twoje pole to licznik lub ID, użyj integer.

3. Nieokreślanie format dla typowych wzorców. JSON Schema ma wbudowane walidatory formatu dla email, uri, date-time, ipv4, ipv6, uuid i innych. Używaj ich zamiast pisania skomplikowanych wzorców regex.

4. Robienie wszystkiego wymaganym. Oznaczaj pola jako wymagane tylko wtedy, gdy naprawdę muszą być obecne. Zbyt restrykcyjny schemat utrudnia ewolucję API — dodanie nowego opcjonalnego pola to zmiana nienaruszająca kompatybilność, ale tracisz tę elastyczność, jeśli wszystko jest wymagane.

Przykład z życia: Schemat produktu E-Commerce

Spójrzmy na praktyczny schemat, którego mógłbyś użyć dla API produktów:

Ten schemat wymusza, żeby każdy produkt miał nazwę (1-200 znaków), dodatnią cenę i kategorię z ustalonej listy. Tagi są opcjonalne, ale muszą być unikalnymi stringami z maksymalną liczbą 10. Słowo kluczowe enum jest niezwykle przydatne dla pól, które powinny akceptować tylko określone wartości.

Wersje JSON Schema: Którego draftu użyć

JSON Schema przeszedł przez kilka wersji roboczych — każda opublikowana jako IETF Internet-Draft — i to może być mylące dla początkujących. Oto szybki przegląd:

Dla nowych projektów używaj 2020-12 (najnowszego). Jeśli pracujesz z istniejącą bazą kodu, sprawdź, który draft wspiera twój walidator. Większość nowoczesnych walidatorów jak Ajv wspiera Draft 7 i nowsze.

Integracja JSON Schema z twoim procesem pracy

Oto praktyczne podejście do dodawania walidacji JSON Schema do API Express.js:

Ten wzorzec daje ci automatyczną walidację żądań z jasnymi komunikatami o błędach. Opcja allErrors: true zapewnia, że wszystkie błędy walidacji są raportowane naraz, nie tylko pierwszy.

Wypróbuj sam

Gotowy, żeby dodać walidację schematu do swojego projektu? Zacznij od tych narzędzi:

• JSON Schema Generator — Wklej dowolne dane JSON i automatycznie wygeneruj schemat. Idealny do tworzenia schematów z przykładowych odpowiedzi API.
• JSON Schema Validator — Przetestuj swój schemat na prawdziwych danych, żeby upewnić się, że wyłapuje to, co powinien, i przepuszcza to, co powinien.
• JSON Validator — Szybko sprawdź, czy twój JSON jest poprawny składniowo, zanim zaczniesz się martwić o walidację schematu.

JSON Schema może wydawać się dodatkową pracą na początku, ale zwraca się wielokrotnie, wyłapując błędy na granicy twojego systemu zamiast głęboko w logice biznesowej.