Обзор

AJAX-приложения зависят от JSON-сервисов, результаты работы которых должны соответствовать ожиданиям. Если сервисы предоставляют ответы в непредусмотренном формате или с неправильным содержимым, поведение приложения может стать непредсказуемым. В случае сложных приложений можно смягчить риск непредсказуемого поведения, реализуя специализированные процедуры для проверки получаемых от сервисов данных. В качестве альтернативы для проверки входных данных можно использовать JSON Schema.

JSON Schema – это проект стандарта, специфицирующего JSON-формат для определения структуры JSON-данных. На момент написания данной статьи самой последней версией была draft-03 (см. раздел Ресурсы).

В данной статье сравнивается несколько процедур основанной на JSON Schema проверки. Узнайте, как использовать самые современные библиотеки, изучите соглашения и передовые методики создания библиотек для проверки взаимодействий. В статью также включена новая программа, которая поможет вам создавать свои собственные JSON Schema.

Загрузите примеры, используемые в данной статье.

В начало

Выбор библиотеки для приложения

Выбор библиотеки для приложения может оказаться сложным делом. Каждое приложение имеет свой собственный набор ограничений, влияющих на этот выбор. В таблице 1 приведены функциональные возможности четырех основанных на JSON Schema JavaScript-библиотек.

Приложение, основанное на Dojo, может использовать библиотеку dojox.json.schema, поскольку она включена в инструментальный пакет. Приложение, которое должно поддерживать несколько версий (проектов) стандарта, может использовать JSV.

Библиотека dojox.json.schema является ответвлением json-schema, поэтому используется аналогично. Библиотеку schema.js использует только подмножество draft-02. В статье основное внимание уделяется примерам использования dojox.json.schema и JSV.

В начало

Использование dojox.json.schema

В листинге 1 приведен фрагмент HTML-кода, проверяющего простой объект. Он предназначен для внедрения в HTML-элемент head.

<script src="http://ajax.googleapis.com/ajax/libs/dojo/1.7.0/dojo/dojo.js"
    type="text/javascript"></script>

<script type="text/javascript">

    require(["dojox/json/schema"], function() {
        // Объект для проверки
        var successObj = { 
            "foo" : "bar"
        };
        var failureObj = {
            "foo" : 1234
        };
        
        // Schema
        var schema = { 
            "type": "object",
            "properties" : {
                "foo" : {
                    "type" : "string"
                }
            }
        };
        
        // Запуск проверки, которая должна пройти успешно
        // Измените эту строку, чтобы использовать failureObj для вывода ошибки
        var result = dojox.json.schema.validate(successObj, schema);
        
        // Проверка результатов
        if (result.valid) {
            // Успешное завершение, выполнить какие-то действия
            alert("Object is valid");
        } else {
            // Неудачное завершение – извлечь массив ошибок
            var errorArr = result.errors;
            alert("property : " + errorArr[0].property + "\nmessage :  " 
                + errorArr[0].message);
        }
    });
    
</script>

В начало

Использование JSV

В листинге 2 приведен фрагмент HTML-кода, проверяющий простой объект. Он предназначен для внедрения в HTML-элемент head.

<!-- Внимание! Для реального использования вы должны сами загрузить копии
библиотек. github – это не CDN. -->
<script src="https://raw.github.com/garycourt/JSV/master/lib/uri/uri.js"
    type="text/javascript"></script>
<script src="https://raw.github.com/garycourt/JSV/master/lib/jsv.js"
    type="text/javascript"></script>
<script src="https://raw.github.com/garycourt/JSV/master/lib/json-schema-draft-03.js"
    type="text/javascript"></script>

<script type="text/javascript">

        // Объект для проверки
        var successObj = { 
            "foo" : "bar"
        };
        var failureObj = {
            "foo" : 1234
        };
        
        // Schema
        var schema = { 
            "type": "object",
            "properties" : {
                "foo" : {
                    "type" : "string"
                }
            }
        };
        
        // Запуск проверки, которая должна пройти успешно
        var env = JSV.createEnvironment("json-schema-draft-03"); 
        // Измените эту строку, чтобы использовать failureObj для вывода ошибки
        var result = env.validate(successObj, schema);
        
        // Проверка результата
        if (result.errors.length === 0) {
            // Успешное завершение, выполнить какие-то действия
            alert("Object is valid");
        } else {
            // Неудачное завершение – извлечь массив ошибок
            var errorArr = result.errors;
            alert("uri : " + errorArr[0].uri + "\nmessage :  " 
                + errorArr[0].message);
        }

</script>

JSV предоставляет расширенную информацию об ошибках в массиве errors. Каждая ошибка может содержать следующие атрибуты:

• message: понятное человеку сообщение об ошибке.
• uri: URI дефектного объекта.
• schemaUri: URI схемы, вызывающей неудачное завершение проверки.
• Attribute: ограничение Schema, вызывающее неудачное завершение проверки.
• Details: массив в свободной форме, содержащий дополнительную информацию, например ожидаемые значения.

В начало

Комбинирование основанной на JSON Schema проверки с XMLHttpRequest

При разработке сложных AJAX-приложений рассмотрите возможность использования вышеописанных методик для проверки AJAX-взаимодействий. Проверка объекта – это простая процедура, если схема представлена в виде JavaScript-объекта. Существуют разнообразные решения для получения объектов схемы.

При написании библиотеки для получения схем и проверки взаимодействий следует учитывать:

• Накладные расходы на загрузку страниц. Предварительная загрузка схем выглядит привлекательно, но может замедлить загрузку страницы.
• Накладные расходы на AJAX-вызовы. Отложенная загрузка схем повлияет на первый вызов, использующий каждую схему. Проверка каждого взаимодействия может привести к снижению производительности. Подумайте о проверке только наиболее сложных сервисов.

В начало

Написание JSON Schema

Определение JSON Schema имеет множество нюансов, поэтому написание и тестирование схем может оказаться не простым делом. В статье содержится ссылку на программу JSON Schema Lint, которая поможет в создании и тестировании JSON Schema.

Советы и рекомендации

• Проект JSON Schema Internet Draft (см. раздел Ресурсы) содержит полное описание спецификации JSON Schema и является бесценным ресурсом. Обязательно ознакомьтесь с последней версией проекта.
• Подумайте об использовании JSON Schema для работы с сервисами документирования. Используйте атрибут description для описания свойств.
• При написании схем соотносите потребности приложения и строгость проверки. В случае тщательной проверки можно полностью определить каждый атрибут, но это может привести к недолговечности сервиса, развивающегося с приложением. JSON Schema позволяет частичную проверку, что может оказаться полезным в данном случае.
• Используйте расширенные возможности JSON Schema для ограничения свойств. Для этого можно использовать additionalProperties, enum, minItems, maxItems и т.д.
• Если нужно разрешить свойству иметь несколько типов, можно использовать массив для их определения. В качестве альтернативы используйте тип any.

В начало

Заключение

В статье рассматривались способы основанной на JSON Schema проверки JavaScript-объектов с использованием двух библиотек. Также были даны советы по созданию библиотек проверки взаимодействий и рассмотрены передовые методики создания схем. В статье содержится ссылка на программу, которая поможет вам при создании и тестировании собственных схем.

В начало

Загрузка

Информация о методах загрузки

Ресурсы

• Оригинал статьи Use JSON Schema validation in your rich Internet application (EN).
  
  
• JSON Schema: дополнительная информация о новых схемах и инструментальных средствах, а также их обсуждение.
  
  
• JSON Media Type для описания структуры и значения JSON-документов: прочтите новый вариант проекта JSON Schema Internet Draft (рабочий документ организации Internet Engineering Task Force (IETF)).
  
  
• Документация по dojox.json.schema: информация о том, как dojox.json.schema реализует JSON Schema для предоставления основанной на JSON Schema проверки данных.
  
  
• Библиотека JSV Гари Курта (Gary Court): дополнительная информация об этой JavaScript-реализации расширяемой и полностью совместимой программы JSON Schema Validator.
  
  
• Библиотека schema.js Андреаса Калша (Andreas Kalsch): дополнительная информация об этом современном средстве проверки и адаптации данных, основанном на JSON Schema.
  
  
• Библиотека json-schema Криса Зипа (Kris Zyp): информация о спецификациях JSON Schema, рекомендованных схемах и реализации CommonJS.
  
  
• developerWorks в Твиттере. Следите за твитами developerWorks.
  
  

Об авторе

Оценить эту статью

Комментарии

В начало

Содержание

• Обзор
• Choosing a library
• Использование dojox.json.schema
• Использование JSV
• Комбинирование основанной на JSON Schema проверки с XMLHttpRequest
• Написание JSON Schema
• Заключение
• Загрузка
• Ресурсы
• Об авторе
• Комментарии