Перейти к основному содержимому

Введение в схему JSON в Java

· 4 мин. чтения

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 : это должен быть JSON Object .

Кроме того, схема 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 .