Czym jest JSON Schema?

JSON Schema opisuje, jak powinien wyglądać dokument JSON: jakie właściwości ma obiekt, które z nich są wymagane, jaki jest typ każdej wartości, dozwolone zakresy i długości, a także wzorce i formaty, takie jak adresy e-mail czy daty. API, pliki konfiguracyjne i kreatory formularzy używają schematów do sprawdzania danych, zanim im zaufają, a OpenAPI opisuje za ich pomocą treść żądań i odpowiedzi.

Jak korzystać z walidatora

  1. Wklej lub wpisz JSON Schema w pierwszym polu.
  2. Wklej lub wpisz dane JSON do sprawdzenia w drugim polu.
  3. Wynik pojawia się podczas wpisywania: albo JSON jest prawidłowy, albo wyświetlana jest lista wszystkich błędów wraz ze ścieżką do błędnej wartości, słowem kluczowym schematu, które narusza, i krótkim wyjaśnieniem.
  4. Każda nieprawidłowa wartość jest oznaczona w danych. Kliknij błąd, aby przewinąć do niego dane, albo kliknij oznaczenie, aby znaleźć powiązany z nim błąd na liście.

Pole Wersja schematu pokazuje, według której wersji JSON Schema sprawdzono dane.

Obsługiwane wersje

Słowo kluczowe $schema w schemacie określa wersję:

  • Wersja 2020-12: https://json-schema.org/draft/2020-12/schema
  • Wersja 2019-09: https://json-schema.org/draft/2019-09/schema
  • Wersja 7: http://json-schema.org/draft-07/schema#
  • Wersja 6: http://json-schema.org/draft-06/schema#

Schemat bez $schema jest sprawdzany według wersji 7. Wersja 4 i starsze nie są obsługiwane. Sam schemat jest najpierw sprawdzany względem met schematu danej wersji, więc literówka, taka jak "type": "strin", jest zgłaszana jako nieprawidłowy schemat, a nie pomijana. Adnotacje takie jak title, description i examples są dozwolone, podobnie jak nieznane danej wersji słowa kluczowe, na przykład własne adnotacje x-: są one ignorowane.

Odczytywanie błędów

  • Ścieżki są zapisywane w formacie JSONPath i zaczynają się od $, czyli całego dokumentu: $.ingredients[1].unit wskazuje właściwość unit drugiego składnika.
  • Brak wymaganej właściwości jest zgłaszany dla obiektu, który powinien ją zawierać; komunikat podaje nazwę właściwości.
  • Niedozwolona przez schemat dodatkowa właściwość jest wskazywana przez jej nazwę.
  • W przypadku enum i const komunikat zawiera dozwolone wartości.
  • W przypadku anyOf i oneOf każda niespełniona gałąź dodaje własne błędy, a następnie dodawany jest błąd dotyczący samego słowa kluczowego, więc jedna nieprawidłowa wartość może spowodować kilka błędów.

Komunikaty o błędach pochodzą z biblioteki Ajv i są w języku angielskim.

Formaty

Sprawdzane są również wartości ze słowem kluczowym format: email, uri, uri-reference, date, time, date-time, duration, uuid, ipv4, ipv6, hostname, regex, json-pointer i inne. Format, którego walidator nie rozpoznaje, jest ignorowany, zgodnie z dopuszczeniem specyfikacji JSON Schema.

Odwołania

$ref działa w przypadku definicji w tym samym schemacie, takich jak #/$defs/address lub #/definitions/address. Odwołania do innych plików lub adresów URL nie są pobierane: schemat, który ich wymaga, jest zgłaszany jako nieprawidłowy, wraz z odwołaniem, którego nie udało się rozwiązać.

Jak to działa

Narzędzie przeprowadza walidację za pomocą Ajv, powszechnie używanego walidatora JSON Schema, a formaty sprawdza za pomocą ajv-formats. Wszystko działa w przeglądarce: schemat ani dane nigdy nie są przesyłane.

Funkcje

  • Obsługa wersji JSON Schema 6, 7, 2019-09 i 2020-12, wybieranej na podstawie $schema
  • Każdy błąd wraz ze ścieżką, słowem kluczowym i komunikatem
  • Oznaczenia nieprawidłowych wartości w danych; kliknięcie przewija do danej wartości
  • Sprawdzanie formatów adresów e-mail, URI, dat, UUID, adresów IP i innych
  • Sprawdzanie schematu względem jego met schematu
  • Wiersz i kolumna błędów składni JSON
  • Działanie w przeglądarce