1. Обзор
Схема JSON
— это декларативный язык для проверки формата и структуры объекта JSON
. Это позволяет нам указать количество специальных примитивов, чтобы точно описать, как будет выглядеть действительный объект JSON .
Спецификация схемы JSON
разделена на три части:
- Ядро схемы JSON. В спецификации ядра схемы JSON определяется терминология схемы.
- Проверка схемы JSON. Спецификация проверки схемы JSON — это документ, определяющий допустимые способы определения ограничений проверки. В этом документе также определяется набор ключевых слов, которые можно использовать для указания проверки для JSON API. В следующих примерах мы будем использовать некоторые из этих ключевых слов.
- Гиперсхема JSON : это еще одно расширение спецификации схемы JSON, в котором определяются ключевые слова, связанные с гиперссылкой и гипермедиа.
2. Определение схемы JSON
Теперь, когда мы определили, для чего используется схема JSON
, давайте создадим объект JSON
и соответствующую схему JSON
, описывающую его.
Ниже приведен простой объект JSON
, представляющий каталог продуктов:
{
"id": 1,
"name": "Lampshade",
"price": 0
}
Мы могли бы определить его схему JSON
следующим образом:
{
"$schema": "http://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. - Ключевые слова
заголовка
иописания
носят только описательный характер, поскольку они не добавляют ограничений к проверяемым данным. Цель схемы указывается с помощью этих двух ключевых слов: описывает продукт. - Ключевое слово
type
определяет первое ограничение для наших данныхJSON
: это должен быть JSONObject
.
Кроме того, схема JSON МОЖЕТ содержать свойства, которые не являются ключевыми словами схемы. В нашем случае id
, name
, price
будут членами (или свойствами) объекта JSON
.
Для каждого свойства мы можем определить тип
. Мы определили id
и name
как строку
и цену
как число
. В схеме JSON
число может иметь минимум. По умолчанию этот минимум является инклюзивным, поэтому нам нужно указать ExclusiveMinimum
.
Наконец, схема
сообщает, что
требуются идентификатор
, имя
и цена
. ``
3. Проверка с помощью схемы JSON
Создав нашу схему JSON
, мы можем проверить наш объект JSON
.
Есть много библиотек для выполнения этой задачи. Для нашего примера мы выбрали библиотеку Java json-schema .
Прежде всего, нам нужно добавить следующую зависимость в наш pom.xml
:
<dependency>
<groupId>org.everit.json</groupId>
<artifactId>org.everit.json.schema</artifactId>
<version>1.3.0</version>
</dependency>
Наконец, мы можем написать пару простых тестов для проверки нашего объекта 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.
Если вы посмотрите на консоль, она напечатает следующий вывод:
#/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 .