Generator schematu JSON

Generator JSON Schema — schemat draft-07 z przykładowego JSON-a

Generator schematu JSON zamienia przykładowy obiekt JSON w gotowy schemat JSON Schema w wersji draft-07. Wklejasz reprezentatywny fragment danych, a narzędzie wnioskuje typy pól, buduje sekcję properties i listę required oraz opisuje elementy tablic przez items — dostajesz punkt wyjścia do walidacji API, konfiguracji i formularzy.

Czym jest JSON Schema

JSON Schema to język opisu struktury danych JSON, sam zapisany w JSON. Zamiast opisywać w komentarzu, że pole id jest liczbą całkowitą, a tags tablicą łańcuchów, zapisujesz to formalnie i pozwalasz walidatorowi sprawdzić zgodność automatycznie. Schemat pełni potrójną rolę: jest kontraktem, dokumentacją czytelną dla człowieka i regułą, którą wykona maszyna. Kluczowe słowa — type, properties, required, items, $schema — mają stałe znaczenie niezależnie od języka.

Jak działa wnioskowanie schematu z przykładu

Narzędzie parsuje wklejony JSON i schodzi rekurencyjnie po jego strukturze. Dla obiektu tworzy sekcję properties z opisem każdego pola, a pola o niepustej wartości dopisuje do listy required. Dla tablicy ustala typ przez items na podstawie pierwszego elementu. Wartości proste mapuje na typy JSON Schema: liczba całkowita to integer, liczba z kropką dziesiętną to number, wartość logiczna to boolean, null daje null, a łańcuch znaków to string. Rozróżnienie integer od number bierze się z zapisu, więc dla pól bywających ułamkiem podaj w przykładzie wartość z kropką.

type, properties, required, items — z czego składa się wynik

Zagnieżdżone obiekty i tablice

Struktury zagnieżdżone są obsługiwane w pełni rekurencyjnie: obiekt w obiekcie dostaje własną sekcję properties, a tablica obiektów opisuje w items schemat pojedynczego rekordu razem z listą required. Pusty obiekt {} to type: object z pustym properties, a pusta tablica [] to type: array bez klucza items — bo z pustej tablicy nie da się odgadnąć typu elementów, więc narzędzie zostawia to miejsce do uzupełnienia.

Jak wygenerować schemat krok po kroku

1. Wklej reprezentatywny przykład danych — im pełniejszy obiekt, tym trafniejszy schemat.
2. Kliknij Generuj schemat. Wynik pojawi się po prawej, sformatowany z wcięciami.
3. Sprawdź listę required i usuń z niej pola faktycznie opcjonalne.
4. Dopisz to, czego z jednego przykładu nie widać: format, pattern, enum, ograniczenia liczbowe.
5. Skopiuj gotowy schemat i wczytaj go do walidatora.

Wersje drafta i pole $schema

Pole $schema deklaruje, według której wersji specyfikacji czytać schemat. Generator wpisuje adres draft-07 — wersji szeroko wspieranej przez walidatory w PHP, JavaScripcie i Pythonie. Nowsze wydania (2019-09, 2020-12) zmieniły m.in. opis elementów tablicy: items w formie tablicowej zastąpiono słowem prefixItems. Jeśli Twój walidator wymaga nowszej wersji, podmień adres i dostosuj zmienione fragmenty.

Walidacja danych względem schematu

Sam schemat niczego nie sprawdza — potrzebujesz walidatora, który porówna z nim dane: justinrainbow/json-schema w PHP, Ajv w JavaScripcie, moduł jsonschema w Pythonie. Zwróci listę niezgodności: brakujące pole z required, zły typ, wartość spoza enum. Aby najpierw sprawdzić, czy sam JSON jest poprawny składniowo, użyj narzędzia walidator JSON, a do przejrzenia struktury w formie drzewa — przeglądarki JSON online.

Do czego służy JSON Schema w praktyce

Najczęstsze zastosowanie to walidacja wejścia API: serwer odrzuca dane niezgodne ze schematem i zwraca czytelny błąd. Schemat bywa też źródłem dokumentacji API, opisuje reguły formularzy spójnie po stronie klienta i serwera, a w plikach konfiguracyjnych podpowiada dozwolone klucze i typy. Zanim schemat trafi do repozytorium, uporządkuj jego zapis formatterem JSON.

Najczęściej zadawane pytania