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

1. обзор

JSON Schema - это декларативный язык для проверки формата и структурыJSON Object. Это позволяет нам указать количество специальных примитивов, чтобы точно описать, как будет выглядеть действительныйJSON Object.

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

JSON Schema Core: В спецификации ядра схемы JSON определяется терминология для схемы.
JSON Schema Validation: Спецификация проверки схемы JSON - это документ, который определяет допустимые способы определения ограничений проверки. Этот документ также определяет набор ключевых слов, которые можно использовать для определения проверок для JSON API. В следующих примерах мы будем использовать некоторые из этих ключевых слов.
JSON Hyper-Schema: это еще одно расширение спецификации схемы JSON, в котором определены ключевые слова, связанные с гиперссылкой и гипермедиа.

2. Определение схемы JSON

Теперь, когда мы определили, для чего используетсяJSON Schema, давайте создадимJSON Object и соответствующийJSON Schema, описывающий его.

Ниже приводится простойJSON Object, представляющий каталог продуктов:

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

Мы могли бы определить егоJSON Schema следующим образом:

{
    "$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 Schema - этоJSON document, и этот документ ДОЛЖЕН быть объектом. Члены (или свойства) объекта, определенныеJSON Schema, называютсяkeywords.

Давайте объясним ключевые слова, которые мы использовали в нашем примере:

Ключевое слово$schema указывает, что эта схема написана в соответствии с черновиком спецификации v4.
Ключевые словаtitle иdescription являются только описательными, поскольку они не добавляют ограничений к проверяемым данным. Назначение схемы указывается с помощью этих двух ключевых слов: описывает продукт.
Ключевое словоtypedefines the first constraint в наших данныхJSON: ithas to be aJSON Object.

Кроме того, схема JSON МОЖЕТ содержать свойства, которые не являются ключевыми словами схемы. В нашем случаеid,name,price будут членами (или свойствами)JSON Object.

Для каждого свойства мы можем определитьtype. Мы определилиid иname какstring иprice какnumber. ВJSON Schema число может иметь минимум. По умолчанию этот минимум включен, поэтому нам нужно указатьexclusiveMinimum.

Наконец,Schema сообщает, чтоid,name иprice - этоrequired.

3. Проверка с помощью схемы JSON

С нашимJSON Schema поместите на местоwe can validate нашJSON Object.

Есть многоlibraries для выполнения этой задачи. Для нашего примера мы выбрали библиотеку Javajson-schema.

Прежде всего, нам нужно добавить следующую зависимость к нашемуpom.xml:


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

Наконец, мы можем написать пару простых тестовых примеров для проверки нашегоJSON Object:

@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 Object, ошибка проверки не возникает.

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

В этой статье мы определили, что такое схема JSON и какие ключевые словаthat helps us являются релевантными для определения нашей схемы.

[#result_box .short_text] # СвязываяJSON Schema с соответствующим представлениемJSON Object, мы можем выполнить некоторую задачу проверки. #

Простой тестовый пример этой статьи можно найти вGitHub project.

TOC

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