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

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 .