Джейсон Скима — Проверка данных нотации объектов JavaScript

{
  "type":"object",
  "properties":{
    "firstName":{"type":"string"},
    "age":{"type":"number"}
  },
  "required":["firstName", "lastName"]
}

{"type": "string"|"object"|"array"|"number"|"boolean"|"null"|"integer"|"any"}

{
  "properties": { "firstName": { "type":"string"}, etc.... },
  "additionalProperties":false
}

Эти ключевые слова на самом деле довольно универсальны. Здесь мы запрещаем любые другие свойства, кроме явно указанных. Если вместо этого мы хотим позволить объекту иметь другие свойства, мы можем установить для него значение true или не устанавливать его вообще. Или, значение  additionalProperties  ключевого слова может быть альтернативно суб-схема , которая определяет вид всех дополнительных свойств в объекте.

Мы видели, как указать  обязательные  свойства в примере выше. Два других параметра ограничивают размер объекта:  minProperties  и  maxProperties, А для большей гибкости в именовании вы можете использовать шаблоны регулярных выражений для имен свойств — это может быть полезно, если у вас есть какой-либо формат, состоящий из букв и цифр или UUID, например. Ключевое слово для этого —  patternProperties :

{
  "patternProperties": { "j_
 
  +[0-9]+": { "type":"object"} },
  "minProperties":1,
  "maxProperties":100
}

 

Выше можно указать от 1 до 100 свойств, имена которых соответствуют шаблону j_ letters_digits  . Вот и все об объектах. Это важно.

Проверка массивов в основном сводится к проверке их элементов, поэтому вы предоставляете подсхему для элементов с   ключевым словом items . Либо вы даете одну схему или массив схем. Одна схема будет применяться ко всем элементам массива, в то время как массив должен соответствовать элементу для элемента (так называемая  типизация кортежей ). Это основа. Вот дополнительные функции: у нас есть  minItems  и maxItems  для управления размером массива; у нас есть  дополнительные элементы,  которые применяются только когда элементы это массив, и он контролирует, что делать с дополнительными элементами, когда они есть. Подобно  additionalProperties  ключевых слов, вы можете поместить ложные запретить дополнительные элементы или предоставить схему для проверки их. Наконец, вы можете потребовать, чтобы все элементы массива отличались по ключевому  слову uniqueItems . Пример:

{
  "items": { "type": "string" },
  "uniqueItems":true, 
  "minItems":10,
  "additionalItems":false
}

Здесь мы указываем ровно 10 уникальных строк в массиве. Вот и все для областей. Числа и строки довольно просты. Для числа вы можете определить диапазон и делимость. Это ключевые слова: минимальное  (для> =),  максимальное  (для <=),  exclusiveMinimum  (если true,  минимальное значение  >), exclusiveMaximum  (если true,  максимальное значение  <). Строки могут быть проверены с помощью регулярного выражения с  ключевым словом pattern и путем ограничения их длины с помощью  minLength  и  maxLength . Надеюсь, вам не нужны примеры, чтобы увидеть проверку строк и чисел в действии. Синтаксис регулярного выражения: ECMA 262 (http://www.ecma-international.org/publications/standards/Ecma-262.htm ).

Обратите внимание, что пока нет логических операторов. В предыдущей итерации спецификации схемы JSON (черновик 3) некоторые из этих ключевых слов допускали области в качестве значений с интерпретацией «или». Например,  типом  может быть  [«string», «number»],  указывающее, что значением может быть либо строка, либо число. От них отказались в пользу всеобъемлющего набора логических операторов для объединения схемы в более сложное проверочное поведение. Давайте рассмотрим их: «и» — это  allOf , или «- это  anyOf»  , «xor» — это  oneOf,  «not» —  нет . Это буквально следует понимать как стандартную логику:не  должен быть подсхемой, которая не должна совпадать для успешной проверки,  allOf должен быть массивом схем, и все они должны совпадать для принятия JSON. Аналогично, anyOf  — это массив, которому должен соответствовать хотя бы один, а  oneOf  означает, что ровно одна из схем в массиве должна соответствовать целевому JSON. Например, для обеспечения того, чтобы человек был женат, мы могли бы заявить, что у него должно быть имущество мужа или жены, но не оба:

{ "oneOf":[
  {"required":["husband"]},
  {"required":["wife"]}
 ]
}

Если у вас есть предопределенный список значений, вы можете использовать  enum . Например, гендерное свойство должно быть либо «мужской», либо «женский»:

{ 
  "properties":{
  "gender":{"enum":["male", "female"]}
  }
}

При этом вы знаете почти все, что нужно знать о JSON Schema. Почти. Выше я упомянул «несколько дополнительных ключевых слов для структурирования больших сложных схем». Я утрировал. На самом деле есть только одно такое ключевое слово:  $ ref  ( идентификатор связанного ключевого слова на   самом деле не нужен). $ ref  позволяет вам ссылаться на схемы, определенные в другом месте, вместо того, чтобы повторять те же конструкции. Например, если где-то в Интернете существует стандартный формат адреса с определенной для него схемой и если эту схему можно получить по адресу http://standardschemas.org/address (составленный URL-адрес), вы можете сделать следующее:

{ 
  "properties":{
  "address":{"$ref":"http://standardschemas.org/address"}
  }
}

Интересная часть  $ ref  заключается в том, что URI может относиться к текущей схеме,  и  вы можете использовать указатель JSON во фрагменте URI (часть после знака pound #), чтобы ссылаться на часть схемы в документе! JSON Pointer — это небольшой RFC (http://tools.ietf.org/html/rfc6901), в котором определены пути-подобные выражения Unix для навигации по свойствам и массивам в сложной структуре JSON. Например, выражение  / дети / 0 / Жандр  относится к Жандр первого элемента в  детях  собственности массива. Обратите внимание, что используется только косая черта, без скобок и точек, и этого вполне достаточно. Если вы хотите избежать косой черты внутри имени свойства, напишите  ~ 1,  а чтобы избежать тильды, напишите  ~ 0, Например, чтобы получить в свое распоряжение надежную проверку почтового индекса, вы можете сделать следующее: 

{ 
  "properties":{
  "zip":{"$ref":"http://standardschemas.org/address#/postalCode"}
  }
}

Это означает, что вы можете определить схемы для вашего RESTful API в стандартном месте и опубликовать их и / или сослаться на них в своих ответах API. Любой валидатор JSON должен быть в состоянии извлечь правильную подсхему, и хорошая реализация кеширует их, чтобы вам не приходилось беспокоиться о сетевых скачках. Ссылочный URI может относиться к текущей схеме, поэтому, если у вас есть другие схемы в том же базовом местоположении, они могут ссылаться друг на друга независимо от того, где они развернуты. В качестве особого случая вы можете разрешать фрагменты, относящиеся к текущей схеме. Например:

{ 
  "myschemas": {
    "properName": { "type":"string", "pattern":"
 
  [a-z]+"}
  }
  "properties":{
    "firstName":{ "$ref":"#/myschemas/properName"},
    "lastName":{ "$ref":"#/myschemas/properName"}
  }
}

 

Поскольку спецификация JSON Schema допускает свойства, которые не являются ключевыми словами, мы можем просто выбрать имя, например,  myschemas  , в качестве заполнителя для подсхем , которые мы хотим использовать повторно. Таким образом, мы определили, что собственное имя должно начинаться с заглавной буквы, за которой следуют одна или несколько строчных букв, и затем мы можем использовать ее в любом месте, где захотим. Это такой общий шаблон, тогда в спецификации определено ключевое слово для размещения таких подсхем. Это  ключевое слово определений, которое должно появляться на верхнем уровне, само по себе не играет роли в валидации  , но является просто заполнителем для встроенных схем. Таким образом, приведенный выше пример должен быть правильно переписан как:

{ 
  "definitions": {
    "properName": { "type":"string", "pattern":"[A-Z][a-z]+"}
  }
  "properties":{
    "firstName":{ "$ref":"#/definitions/properName"},
    "lastName":{ "$ref":"#/definitions/properName"}
  }
}

Подводя итог, можно использовать   ключевое слово $ ref и   заполнитель определений — все, что вам нужно для структурирования больших схем, разделения их на более мелкие, возможно, в разных документах, обращения к стандартизированным схемам через Интернет и т. Д. 

Ресурсы

Json schema = Json.read(new URL("http://mycompany.com/schemas/model");
Json data = Json.object("firstName", "John", "lastName", "Smith")
            .set("children", Json.array().add(/* etc... */));
Json errors = schema.validate(data);
for (Json e: errors.asJsonList())
    System.out.println("JSON validation error:" + e);

object {
string name;
string description?;
string homepage /^http:/;
integer {1500,3000} invented;
}*;