Проверка данных с помощью JSON-схемы, часть 1

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

Допустим, у вас есть база данных пользователей, где каждая запись выглядит примерно так:

Вопрос, с которым мы собираемся разобраться, заключается в том, как определить, является ли запись, подобная приведенной выше, действительной или нет.

Примеры очень полезны, но недостаточны при описании ваших требований к данным. На помощь приходит JSON-схема. Это одна из возможных схем, описывающих запись пользователя:

Посмотрите на схему выше и запись пользователя, которую она описывает (которая действительна в соответствии с этой схемой). Здесь есть много объяснений.

Код JavaScript для проверки записи пользователя по схеме может быть:

или для лучшей производительности: javascript var validate = ajv.compile(userSchema); var valid = validate(userData); if (!valid) console.log(validate.errors); javascript var validate = ajv.compile(userSchema); var valid = validate(userData); if (!valid) console.log(validate.errors);

Все примеры кода доступны в GitHub repo tutsplus-json-schema . Вы также можете попробовать это в браузере .

Ajv , валидатор, используемый в примере, является самым быстрым валидатором JSON-Schema для JavaScript. Я создал его, поэтому собираюсь использовать его в этом уроке.

Прежде чем мы продолжим, давайте быстро разберемся со всеми причинами.

Зачем проверять данные как отдельный шаг?

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

Почему JSON (а не XML)?

• такое широкое распространение, как XML
• проще в обработке и более кратким, чем XML
• доминирует в веб-разработке благодаря JavaScript

Зачем использовать схемы?

• декларативный
• легче поддерживать
• могут быть поняты некодерами
• не нужно писать код, можно использовать сторонние библиотеки с открытым исходным кодом

Почему JSON-схема?

• самое широкое применение среди всех стандартов для проверки JSON
• очень зрелый (текущая версия 4, есть предложения для версии 5)
• охватывает большую часть сценариев проверки
• использует простые для анализа документы JSON для схем
• независимая платформа
• легко растяжимый
• 30+ валидаторов для разных языков, в том числе 10+ для JavaScript, поэтому не нужно кодировать его самостоятельно

Задания

Этот учебник включает в себя несколько относительно простых задач, которые помогут вам лучше понять схему JSON и то, как ее можно использовать. Есть простые сценарии JavaScript, чтобы проверить, что вы сделали их правильно. Для их запуска вам нужно установить node.js (вам не нужно с этим работать). Просто установите nvm (менеджер версий узлов) и последнюю версию node.js:

Вам также необходимо клонировать репозиторий и запустить npm install (он установит валидатор Ajv).

Давайте погрузимся в схемы!

JSON-схема всегда является объектом. Его свойства называются «ключевые слова». Некоторые из них описывают правила для данных (например, «тип» и «свойства»), а некоторые описывают саму схему («$ schema», «id», «title», «description») — мы перейдем к их позже.

Данные действительны в соответствии со схемой, если они действительны для всех ключевых слов в этой схеме — это действительно просто.

Свойства данных

Поскольку большинство данных JSON состоит из объектов с несколькими свойствами, ключевое слово «свойства» , вероятно, является наиболее часто используемым ключевым словом. Это относится только к объектам (см. Следующий раздел о том, что означает «применять»).

В приведенном выше примере вы могли заметить, что каждое свойство внутри ключевого слова «properties» описывает соответствующее свойство в ваших данных.

Значение каждого свойства само по себе является JSON-схемой — JSON-схема является рекурсивным стандартом. Каждое свойство в данных должно быть действительным в соответствии с соответствующей схемой в ключевом слове «properties» .

Здесь важно то, что ключевое слово «properties» не требует никаких свойств; он определяет только схемы для свойств, присутствующих в данных.

Например, если наша схема:

тогда объекты со свойством «foo» или без него могут быть действительными согласно этой схеме:

и только объекты, которые имеют свойство foo, не являющееся строкой, недопустимы:

Попробуйте этот пример в браузере .

Тип данных

Вы уже выяснили, что делает ключевое слово «тип» . Это, наверное, самое важное ключевое слово. Его значение (строка или массив строк) определяет, какой тип (или типы) данных должен быть действительным.

Как видно из приведенного выше примера, пользовательские данные должны быть объектом.

Большинство ключевых слов применяются к определенным типам данных — например, ключевое слово «свойства» применяется только к объектам, а ключевое слово «шаблон» применяется только к строкам.

Что значит «подать заявку»? Допустим, у нас действительно простая схема:

Вы можете ожидать, что, чтобы быть действительным согласно такой схеме, данные должны быть строкой, соответствующей шаблону:

Но стандарт JSON-схемы указывает, что если ключевое слово не относится к типу данных, то данные действительны в соответствии с этим ключевым словом. Это означает, что любые данные, не относящиеся к типу «строка», действительны в соответствии с приведенной выше схемой — числа, массивы, объекты, логические значения и даже ноль. Если вы хотите, чтобы действительными были только строки, соответствующие шаблону, ваша схема должна быть:

Благодаря этому вы можете создавать очень гибкие схемы, которые будут проверять несколько типов данных.

Посмотрите на свойство «id» в примере пользователя. Он должен быть действительным в соответствии с этой схемой:

Эта схема требует, чтобы действительные данные были либо «строкой», либо «целым числом» . Существует также ключевое слово «pattern», которое применяется только к строкам; требуется, чтобы строка состояла только из цифр и не начиналась с 0. Существует ключевое слово «минимум», которое применяется только к числам; для этого необходимо, чтобы число было не менее 1.

Другой, более подробный способ выразить то же самое требование:

Но из-за способа определения JSON-схемы эта схема эквивалентна первой, которая короче и быстрее проверяется в большинстве валидаторов.

Типы данных, которые вы можете использовать в схемах: «объект» , «массив» , «число» , «целое число» , «строка» , «логическое значение» и «ноль» . Обратите внимание, что «число» включает в себя «целое число» — все целые числа тоже являются числами.

Проверка номеров

Есть несколько ключевых слов для проверки чисел. Все ключевые слова в этом разделе относятся только к числам (включая целые числа).

«Минимум» и «максимум» говорят сами за себя. В дополнение к ним есть ключевые слова «exclusiveMinimum» и «exclusiveMaximum» . В нашем примере пользователя возраст пользователя должен быть целым числом 13 или больше. Если схема для возраста пользователя была:

тогда эта схема потребовала бы, чтобы возраст пользователя был строго больше 13, то есть минимально допустимый возраст был бы 14.

Еще одно ключевое слово для проверки чисел — «multipOf» . Его имя также объясняет, что он делает, и вы можете проверить ссылку на ключевые слова JSON-схемы, чтобы увидеть, как это работает.

Проверка строк

Есть также несколько ключевых слов для проверки строк. Все ключевые слова в этом разделе относятся только к строкам.

«MaxLength» и «minLength» требуют, чтобы строка была не длиннее или не короче заданного числа. Стандарт JSON-схемы требует, чтобы пара юникода, например символ эмодзи, считалась одним символом. JavaScript учитывает его как два символа при доступе к свойству .length строк.

Некоторые валидаторы определяют длины строк в соответствии со стандартом, а некоторые делают это способом JavaScript, что быстрее. Ajv позволяет вам указать, как определять длину строки, и по умолчанию это соответствует стандарту.

Вы уже видели ключевое слово «pattern» в действии — оно просто требует, чтобы строка данных соответствовала регулярному выражению, определенному в соответствии с тем же стандартом, который используется в JavaScript. Смотрите пример ниже для схем и соответствующих регулярных выражений:

Ключевое слово «format» определяет семантическую проверку строк, таких как «email» , «date» или «date-time» в примере пользователя. JSON-схема также определяет форматы «uri» , «hostname» , «ipv4» и «ipv6» . Валидаторы по-разному определяют форматы, оптимизируя скорость проверки или правильность. Айв дает вам выбор:

Большинство валидаторов позволяют вам определять пользовательские форматы как регулярные выражения или проверочные функции. Мы могли бы определить собственный формат «телефон» для нашей схемы, чтобы использовать его в нескольких местах:

и тогда схема для свойства phone будет такой:

Задание 1

Создайте схему, которая потребует, чтобы данные были датой (строка) или годом (числом), а год был больше или равен 1976 году.

Поместите свой ответ в файл part1/task1/date_schema.json и запустите node part1/task1/validate чтобы проверить его.

Проверка объекта

В дополнение к «свойствам» в нашем примере пользователя вы можете увидеть несколько других ключевых слов, которые применяются к объектам.

Ключевое слово «required» перечисляет свойства, которые должны присутствовать в объекте, чтобы он был действительным. Как вы помните, ключевое слово «properties» не требует свойств, оно только проверяет их, если они присутствуют. «Required» дополняет «properties» , позволяя вам определить, какие свойства являются обязательными, а какие — необязательными.

Если бы у нас была эта схема:

тогда все объекты без свойства foo будут недействительными.

Обратите внимание, что эта схема все еще не требует, чтобы наши данные были объектом — все остальные типы данных действительны в соответствии с ней. Чтобы требовать, чтобы наши данные были объектом, мы должны добавить к нему ключевое слово «тип» .

Попробуйте приведенный выше пример в браузере .

Ключевое слово «patternProperties» позволяет вам определять схемы, в соответствии с которыми значение свойства данных должно быть допустимым, если имя свойства соответствует регулярному выражению. Его можно комбинировать с ключевым словом «properties» в той же схеме.

Свойство feeds в пользовательском примере должно быть допустимым в соответствии с этой схемой:

Чтобы быть действительными, feeds должны быть объектом со свойствами, имена которых состоят только из латинских букв и значения которых являются логическими.

Ключевое слово «AdditionalProperties» позволяет вам либо определить схему, в соответствии с которой все остальные ключевые слова (не используемые в «свойствах» и не соответствующие «patternProperties» ) должны быть действительными, либо полностью запретить другие свойства, как мы это делали в свойстве feeds схема выше.

В следующем примере «AdditionalProperties» используется для создания простой схемы для хеша целых чисел в определенном диапазоне:

Ключевые слова «maxProperties» и «minProperties» позволяют ограничить количество свойств в объекте. В нашем пользовательском примере схема для свойства address выглядит следующим образом:

Эта схема требует, чтобы адрес являлся объектом с необходимыми свойствами street , postcode , city и country , допускает два дополнительных свойства («maxProperties» равно 6) и требует, чтобы все свойства были строками.

«Зависимости» , вероятно, являются наиболее сложным и запутанным и наиболее редко используемым ключевым словом, но в то же время это очень мощное ключевое слово. Это позволяет вам определить требования, которым должны удовлетворять данные, если они имеют определенные свойства.

Существует два типа таких требований к объекту: иметь некоторые другие свойства (это называется «зависимость от свойства») или удовлетворить некоторую схему («зависимость от схемы»).

В нашем пользовательском примере одна из возможных схем, в отношении которых пользовательское соединение должно быть действительным, заключается в следующем:

Для этого требуется, connType свойство connType равно «относительному» (см. Ключевое слово «enum» ниже), а если свойство relation присутствует, это строка.

Это не требует наличия relation , но ключевое слово «зависимости» требует, чтобы ЕСЛИ свойство relation присутствовало, ТОЛЬКО свойство close тоже должно присутствовать.

В нашей схеме не определены правила проверки для свойства close , хотя из примера видно, что оно, вероятно, должно быть логическим. Один из способов исправить это упущение — изменить ключевое слово «зависимости», чтобы использовать «зависимость от схемы»:

Вы можете поиграть с обновленным примером пользователя в браузере .

Обратите внимание, что схема в свойстве «отношение» в ключевом слове «зависимости» используется для проверки родительского объекта (т. Е. Соединения), а не значения свойства relation в данных.

Задача 2

Ваша база данных содержит людей и машины. Используя только ключевые слова, которые я объяснил до сих пор, создайте схему для проверки обоих. Образец человеческого объекта:

Пример машинного объекта:

Обратите внимание, что это должна быть одна схема для проверки как людей, так и машин, а не две схемы.

Поместите свой ответ в файл part1/task2/human_machine_schema.json и запустите node part1/task2/validate чтобы проверить его.

Подсказки: используйте ключевое слово «зависимости» и посмотрите в файле part1/task2/invalid.json чтобы увидеть, какие объекты должны быть недействительными.

Какие объекты, которые, вероятно, также должны быть недействительными, отсутствуют в файле invalid.json ?

Основным выводом из этой задачи является тот факт, что целью валидации является не только валидация всех действительных объектов как допустимых. Я много раз слышал этот аргумент: «Эта схема проверяет мои действительные данные как действительные, поэтому они верны». Этот аргумент неверен, потому что вам не нужно много делать для его достижения — пустая схема сделает работу, потому что он проверяет достоверность любых данных.

Я думаю, что основная цель проверки состоит в том, чтобы проверить недействительные данные как недействительные, и в этом вся сложность.

Проверка массива

Существует несколько ключевых слов для проверки массивов (и они применяются только к массивам).

«MaxItems» и «minItems» требуют, чтобы массив содержал не больше (или не меньше), чем определенное количество элементов. В примере пользователя схема требует, чтобы количество соединений не превышало 150.

Ключевое слово «items» определяет схему (или схемы), в соответствии с которой элементы должны быть действительными. Если значением этого ключевого слова является объект (как в примере с пользователем), то этот объект является схемой, в соответствии с которой данные должны быть действительными.

Если значением ключевого слова «items» является массив, то этот массив содержит схемы, в соответствии с которыми соответствующие элементы должны быть действительными:

Схема в простом приведенном выше примере требует, чтобы данные представляли собой массив, причем первый элемент является целым числом, а второй — строкой.

Как насчет предметов после этих двух? Схема выше не определяет никаких требований для других предметов. Они могут быть определены с помощью ключевого слова « AdditionalItems».

Ключевое слово « AdditionalItems» применяется только к ситуации, в которой ключевое слово «items» является массивом, и в данных содержится больше элементов, чем в ключевом слове «items» . Во всех остальных случаях (без ключевого слова items , это объект или в данных больше нет элементов) ключевое слово AdditionalItems будет игнорироваться независимо от его значения.

Если ключевое слово « AdditionalItems» имеет значение true, оно просто игнорируется. Если оно ложно и в данных содержится больше элементов, чем в ключевом слове «items», проверка завершается неудачно:

Если ключевое слово « AdditionalItems» является объектом, то этот объект является схемой, в соответствии с которой все дополнительные элементы должны быть действительными:

Пожалуйста, поэкспериментируйте с этими примерами, чтобы увидеть, как работают «items» и «AdditionalItems» .

Последнее ключевое слово, которое применяется к массивам, это «uniqueItems» . Если его значение равно true , оно просто требует, чтобы все элементы в массиве были разными.

Проверка ключевого слова «uniqueItems» может быть вычислительно дорогой, поэтому некоторые валидаторы решили не реализовывать ее или делать это только частично.

Ajv имеет возможность игнорировать это ключевое слово:

Задача 3

Одним из способов создания объекта даты в JavaScript является передача от 2 до 7 чисел в конструктор Date:

У вас есть массив. Создайте схему, которая проверит, что это допустимый список аргументов для конструктора Date.

Поместите свой ответ в файл part1/task3/date_args_schema.json и запустите node part1/task3/validate чтобы проверить его.

Ключевое слово «Enum»

Ключевое слово enum требует, чтобы данные были равны одному из нескольких значений. Это относится ко всем типам данных.

В примере пользователя он используется для определения gender свойства внутри personal свойства как «мужской» или «женский». Он также используется для определения свойства connType в пользовательских подключениях.

Ключевое слово «enum» может использоваться с любыми типами значений, не только со строками и числами, хотя это не очень распространено.

Он также может использоваться для требования, чтобы данные были равны определенному значению, как в примере пользователя:

Предложения для следующей версии (v5) стандарта JSON-Schema включают ключевое слово «константа», чтобы сделать то же самое.

Ajv позволяет использовать «константу» и некоторые другие ключевые слова из v5:

Ключевые слова проверки соединения

Есть несколько ключевых слов, которые позволяют вам определить расширенную логику, включающую проверку по нескольким схемам. Все ключевые слова в этом разделе относятся ко всем типам данных.

В нашем примере пользователя используется ключевое слово «oneOf» для определения требований к пользовательскому соединению. Это ключевое слово допустимо, если данные успешно проверены по одной схеме внутри массива.

Если данные являются недействительными по всем схемам в ключевом слове «oneOf» или действительны по двум или более схемам, то данные являются недействительными.

Давайте посмотрим более внимательно на наш пример:

Приведенная выше схема требует, чтобы пользовательское соединение было либо «относительным» (свойство connType ), и в этом случае оно может иметь свойства relation (строка) и close (логическое), либо один из типов «друг», «коллега» или «другое» ( в этом случае он не должен иметь relation свойств и close ).

Эти схемы для подключения пользователя являются взаимоисключающими, потому что нет данных, которые могли бы удовлетворить их обоих. Поэтому, если соединение допустимо и имеет тип «относительный», нет смысла проверять его по второй схеме — оно всегда будет недействительным. Тем не менее, любой валидатор всегда будет проверять данные по обеим схемам, чтобы убедиться, что они действительны только по одной схеме.

Есть еще одно ключевое слово, которое позволяет вам избежать этого: «anyOf» . Это ключевое слово просто требует, чтобы данные были действительными согласно некоторой схеме в массиве (возможно, нескольким схемам).

В случаях, подобных описанным выше, когда схемы являются взаимоисключающими и никакие данные не могут быть действительными в соответствии с более чем одной схемой, лучше использовать ключевое слово «anyOf» — оно будет проверяться быстрее в большинстве случаев (кроме той, в которой данные действительны в соответствии с последней схемой).

Использование «oneOf» в тех случаях, когда «anyOf» выполняет одинаково хорошую работу, является очень распространенной ошибкой, которая отрицательно влияет на производительность проверки.

Наш пользовательский пример также выиграл бы от замены «oneOf» на «anyOf» .

Однако в некоторых случаях нам действительно необходимо ключевое слово «oneOf» :

Приведенная выше схема будет успешно проверять строки, которые упоминают апельсины или яблоки, но не оба (и существуют строки, которые могут упомянуть оба). Если это то, что вам нужно, тогда вам нужно использовать «oneOf» .

По сравнению с логическими операторами, anyOf — это логическое ИЛИ, а oneOf — XOR (исключающее ИЛИ). Тот факт, что JavaScript (и многие другие языки) не определяют операторы для исключающего ИЛИ, показывает, что это редко требуется.

Также есть ключевое слово «allOf» . Требуется, чтобы данные были действительны по всем схемам в массиве:

Ключевое слово «$ ref» позволяет вам требовать, чтобы данные были действительными в соответствии со схемой в другом файле (или некоторой его части). Мы будем смотреть на это во второй части этого урока.

Другая ошибка заключается в том, что в схемах «oneOf» , «anyOf» и «allOf» содержится более чем абсолютно необходимое внутри схем. Например, в нашем пользовательском примере мы можем поместить в «anyOf» все требования, которым должно удовлетворять соединение.

Мы также могли бы излишне усложнить пример с яблоками и апельсинами:

Другое «логическое» ключевое слово — «нет» . Требуется, чтобы данные НЕ действовали в соответствии со схемой, которая является значением этого ключевого слова.

Например:

Схема выше требует, чтобы данные представляли собой строку, не содержащую «apple».

В примере пользователя ключевое слово «not» используется для предотвращения использования некоторых свойств в одном из случаев в «oneOf» , хотя они определены:

Значение ключевого слова «not» в приведенном выше примере является пустой схемой. Пустая схема подтвердит правильность любого значения, а ключевое слово «not» сделает его недействительным. Таким образом, проверка схемы не удастся, если объект имеет relation свойства или close . Вы можете достичь того же самого с помощью комбинации «не» и «обязательных» ключевых слов.

Другое использование ключевого слова not — это определение схемы, которая требует, чтобы массив содержал элемент, который является допустимым в соответствии с некоторой схемой:

Приведенная выше схема требует, чтобы данные были массивом и содержали как минимум один целочисленный элемент, больший или равный 5.

Предложения V5 включают ключевое слово «содержит», чтобы удовлетворить это требование.

Задача 4

У вас есть база данных пользователей, которые соответствуют схеме из примера пользователя. Создайте схему, в соответствии с которой будут действовать только те пользователи, которые удовлетворяют всем этим критериям:

• незамужние мужчины моложе 21 года или старше 60 лет
• иметь 5 или меньше соединений
• подписаться на 3 или менее каналов

Поместите свой ответ в файл part1/task4/filter_schema.json и запустите node part1/task4/validate чтобы проверить его.

Данные теста упрощены, поэтому, пожалуйста, не используйте ключевое слово «required» в вашей схеме.

Ключевые слова, описывающие схему

Некоторые ключевые слова, используемые в примере с пользователем, напрямую не влияют на проверку, но они описывают саму схему.

Ключевое слово «$ schema» определяет URI мета-схемы для схемы. Сама схема является документом JSON, и ее можно проверить с помощью JSON-схемы. JSON-схема, которая определяет любую JSON-схему, называется мета-схемой. URI для мета-схемы для черновика 4 стандарта JSON-схемы: http://json-schema.org/draft-04/schema .

Если вы расширяете стандарт, рекомендуется использовать другое значение свойства «$ schema» .

«Id» — это URI схемы. Его можно использовать для ссылки на схему (или некоторую ее часть) из другой схемы с помощью ключевого слова «$ ref» — см. Вторую часть руководства. Большинство валидаторов, включая Ajv, допускают любую строку как «id» . Согласно стандарту, идентификатор схемы должен быть допустимым URI, который можно использовать для загрузки схемы.

Вы также можете использовать «title» и «description» для описания схемы. Они не используются во время проверки. Оба эти ключевых слова могут использоваться на любом уровне внутри схемы для описания некоторых ее частей, как это делается в примере с пользователем.

Последняя задача

Создайте пример пользовательской записи, которая при проверке с использованием примерной пользовательской схемы будет содержать 8 или более ошибок.

Поместите свой ответ в файл part1/task5/invalid_user.json и запустите node part1/task5/validate чтобы проверить его.

Что все еще не так с нашей пользовательской схемой?

Что дальше?

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

Мы также будем:

• использовать схему для определения значений по умолчанию
• отфильтровать дополнительные свойства из данных
• использовать ключевые слова, включенные в предложения для версии 5 стандарта JSON-схемы
• определить новые ключевые слова проверки
• сравнить существующие валидаторы JSON-схемы

Спасибо за прочтение!