W poprzednim artykule pokrótce pokazałem, czym są, jak wyglądają i gdzie mają zastosowanie struktury danych JSON, Ponieważ programiści dowolnie mogą projektować strukturę obiektów, to musiał powstać standard pozwalający na ich dokumentowanie, czy weryfikację. Sam standard struktury nie przewiduje nawet możliwości dodania komentarzy wewnątrz obiektu. Poznajmy więc JSON Schema.
Co to takiego to JSON Schema
Praca ze strukturami JSON nie należy do prostych zadań. Z jednej strony obiekty są przejrzyste w swojej budowie i składają się z prostych elementów. Najczęściej generujemy je programowo, co też teoretycznie powinno minimalizować błędy w tworzeniu poprawnej struktury obiektu. Jednak pomyłki to codzienność pracy z obiektami JSON. Dlatego warto zapoznać się z JSON Schema.
Jest to potężne narzędzie do sprawdzania poprawności struktury danych JSON. Do wykorzystania mamy proste typy danych, o których pisałem w poprzednim artykule. Korzystając z nich, możemy reprezentować wszystkie rodzaje danych strukturalnych. Z tą wielką elastycznością wiąże się jednak wielka odpowiedzialność, ponieważ ta sama koncepcja może być reprezentowana na wiele sposobów. Projekt rekordu będzie w dużej mierze zależeć od jego zamierzonego przez nas zastosowania w aplikacji. Nie ma jednego przepisu jak tworzyć struktury, poza rekomendacją by były one możliwie najprostsze.
Przekazując rekordy pomiędzy aplikacjami, musimy jednak dokładnie wiedzieć, jak każdy rekord powinien być zorganizowany. Na przykład musimy wiedzieć, jakie pola są oczekiwane i jak reprezentowane są wartości. Do opisu oczekiwanej struktury służy właśnie JSON Schema
Struktura JSON Schema
Paradoksalnie opis rekordu JSON to nic innego jak specjalny… obiekt JSON! Nie może on jednak zawierać dowolnego kodu, istnieją pewne ograniczenia relacji między elementami danych. Przypomnijmy sobie przykład obiektu JSON z poprzedniego artykułu:
{
"hostname": "nazwa.hosta.lan",
"age": 2,
"owner": null,
"active": true,
"interfaces": [
{
"name": "eth0",
"address": "172.16.16.1"
},
{
"name": "eth1",
"address": "10.0.0.1"
}
]
} Nasz obiekt składa się z różnych typów danych. Przeprowadzając walidację poprawności tych danych, korzystamy z opisu wygenerowanego jako JSON Schema. Będzie on miał następującą postać:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"hostname": {
"type": "string"
},
"age": {
"type": "integer"
},
"owner": {
"type": "null"
},
"active": {
"type": "boolean"
},
"interfaces": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "string"
}
},
"required": [
"name",
"address"
]
},
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "string"
}
},
"required": [
"name",
"address"
]
}
]
}
},
"required": [
"hostname",
"age",
"owner",
"active",
"interfaces"
]
} Wygląda skomplikowanie? Na szczęście tak nie jest.
Podstawowe elementy opisu struktury
Jeżeli dokładnie przypatrzymy się zawartości opisu JSON Schema naszego wyjściowego obiektu, to zobaczymy, że każde z pól naszego rekordu opisane jest parametrem type, które wskazuje na jego typ. Jeżeli w kluczu age oczekujemy wartości liczbowej, to wartość atrybutu type musi zostać ustawiona na integer. Jeżeli ktoś przez pomyłkę umieściłby liczbę w cudzysłowie, a co za tym idzie przekazał wartość typu string, to proces walidacji rekordu JSON względem jego opisu zawartego w opisie, zwróci błąd.
Drugim ważnym elementem opisu danych jest atrybut required, który zawiera listę kluczy, które obowiązkowo muszą znaleźć się w utworzonym obiekcie. Dzięki temu nie musimy tworzyć osobnego schematu dla każdej możliwej kombinacji atrybutów obowiązkowych i opcjonalnych – byłoby to bardzo nieżyciowe.
Ponadto w pierwszym wierszu znajdziemy atrybut $schema odnoszący się do wersji standardu, lub jego wersji roboczej, według którego walidacja zostanie przeprowadzona.
Narzędzia do tworzenia i walidacji
Do nauki, jak i do ręcznego sprawdzania poprawności struktury JSON w oparciu o JSON Schema, polecam narzędzia on-line, do których wystarczy przeglądarka internetowa. W ten sam sposób łatwo wygenerujemy też opis na podstawie rekordu wypełnionej struktury danych.
Do wygenerowania JSON Schema na podstawie przykładowego rekordu polecam Free Online JSON to JSON Schema Converter lub JSONschema.NET.
Niezwykle przydatnym narzędziem do walidacji struktur jest JSON Schema Validator. Pozwoli on na sprawdzenie poprawności naszej struktury z szablonami dla popularnych serwisów czy protokołów komunikacyjnych. Wystarczy, że wkleimy nasz rekord i wybierzemy odpowiedni szablon z listy. Możemy także wstawić własną definicję schematu, na podstawie której sprawdzimy nasz rekord.
