Въведение в JSON Schema в Java

1. Общ преглед

JSON Schema е декларативен език за валидиране на формата и структурата на JSON обект . Позволява ни да посочим броя на специалните примитиви, за да опишем как точноще изглеждавалиден JSON обект .

Спецификацията на JSON Schema е разделена на три части:

  • Ядро на JSON Schema: Спецификацията на JSON Schema Core е мястото, където е дефинирана терминологията за схема.
  • JSON Schema Validation: JSON Schema Validation Specification е документът, който дефинира валидните начини за дефиниране на ограничения за валидиране. Този документ също така определя набор от ключови думи, които могат да се използват за задаване на валидирания за JSON API. В следващите примери ще използваме някои от тези ключови думи.
  • JSON Hyper-Schema: Това е друго разширение на спецификацията на JSON Schema, където са дефинирани ключовите думи, свързани с хипервръзката и хипермедията.

2. Дефиниране на JSON схема

След като дефинирахме за какво се използва JSON схема , нека създадем JSON обект и съответната JSON схема, която го описва.

По-долу е прост JSON обект, представляващ продуктов каталог:

{ "id": 1, "name": "Lampshade", "price": 0 }

Можем да дефинираме неговата JSON схема, както следва:

{ "$schema": "//json-schema.org/draft-04/schema#", "title": "Product", "description": "A product from the catalog", "type": "object", "properties": { "id": { "description": "The unique identifier for a product", "type": "integer" }, "name": { "description": "Name of the product", "type": "string" }, "price": { "type": "number", "minimum": 0, "exclusiveMinimum": true } }, "required": ["id", "name", "price"] }

Както виждаме, JSON схемата е JSON документ и този документ ТРЯБВА да бъде обект. Членовете на обекта (или свойствата), дефинирани от JSON Schema, се наричат ключови думи .

Нека да обясним ключовите думи, които сме използвали в нашата извадка:

  • В схемата $ ключови думи се посочва, че тази схема е написана в съответствие със спецификацията проект v4.
  • В заглавие и описание Ключовите думи са описателни само по това, че не се добавя ограничения по отношение на данните, които се потвърждават. Намерението на схемата е посочено с тези две ключови думи: описва продукт.
  • На вид ключова дума определя първото ограничение на нашия JSON данни: тя трябва да бъде по- JSON обект .

Също така, JSON схема МОЖЕ да съдържа свойства, които не са ключови думи на схемата. В нашия случай идентификатор , име , цена ще бъдат членове (или свойства) на JSON обекта .

За всяко свойство можем да определим типа . Определихме id и име като низ, а цената като номер . В JSON Schema числото може да има минимум. По подразбиране този минимум е включен, така че трябва да посочим exclusiveMinimum .

И накрая, схемата казва, че са необходими идентификатор , име и цена .

3. Проверка със JSON схема

С нашата JSON схема, въведена на място, ние можем да потвърдим нашия JSON обект .

Има много библиотеки за изпълнение на тази задача. За нашия пример избрахме библиотеката Java json-schema.

На първо място, трябва да добавим следната зависимост към нашия pom.xml :

 org.everit.json org.everit.json.schema 1.3.0  

И накрая, можем да напишем няколко прости тестови случая, за да потвърдим нашия JSON обект:

@Test public void givenInvalidInput_whenValidating_thenInvalid() throws ValidationException { JSONObject jsonSchema = new JSONObject( new JSONTokener(JSONSchemaTest.class.getResourceAsStream("/schema.json"))); JSONObject jsonSubject = new JSONObject( new JSONTokener(JSONSchemaTest.class.getResourceAsStream("/product_invalid.json"))); Schema schema = SchemaLoader.load(jsonSchema); schema.validate(jsonSubject); }

В този случай хвърленият ValidationException ще сочи към # / цена. Ако погледнете конзолата, тя ще отпечата следния изход:

#/price: 0.0 is not higher than 0 

Вторият тест изглежда по следния начин:

@Test public void givenValidInput_whenValidating_thenValid() throws ValidationException { JSONObject jsonSchema = new JSONObject( new JSONTokener(JSONSchemaTest.class.getResourceAsStream("/schema.json"))); JSONObject jsonSubject = new JSONObject( new JSONTokener(JSONSchemaTest.class.getResourceAsStream("/product_valid.json"))); Schema schema = SchemaLoader.load(jsonSchema); schema.validate(jsonSubject); }

Тъй като използваме валиден JSON обект , няма да се появи грешка при проверка.

4. Заключение

В тази статия дефинирахме какво представлява JSON схема и кои са някои подходящи ключови думи, които ни помагат да дефинираме нашата схема.

Свързвайки JSON схема със съответното представяне на обект JSON, можем да изпълним някаква задача за проверка.

Един прост пример за тази статия може да бъде намерен в проекта GitHub.