JSON Schema

Рассмотрим следующий JSON-документ.

{
  "artists" : [
    { 
      "artistname" : "Deep Purple",
      "formed" : "1968"
    },
    { 
      "artistname" : "Joe Satriani",
      "born" : "1956-07-15" 
    },
    { 
      "artistname" : "Maroon 5",
      "formed" : "1994" 
    }
  ]
}

В данном примере применяется разный формат даты у объектов. Кроме того, один объект использует born (указывает, когда родился исполнитель), в то время как другие используют formed (когда образовалась группа/исполнитель).

В JSON нет правил, согласно которым некоторые объекты должны использовать определённый тип данных или даже содержать одинаковые поля. Им даже не нужно содержать одинаковое количество полей. Например, мы можем добавить поле favoritecolor к одному объекту, не добавляя его к другим.

Кроме того, нет правила, согласно которому данные должны быть в заданном формате. Например, поле born может быть представлено любым из следующих способов.

"born" : "1956"
"born" : 1956
"born" : "Июль 15, 1956"
"born" : "1956-07-15"
"born" : "07/15/1956"
"born" : "15/07/1956"
"born" : "Я люблю апельсины!"
"born" : [
  {
    "albumname" : "Flying in a Blue Dream",
    "year" : "1989",
    "genre" : "Инструментальный рок"
  }, 
  {
    "albumname" : "The Extremist",
    "year" : "1992",
    "genre" : "Инструментальный рок"
  },
  {
    "albumname" : "Shockwave Supernova",
    "year" : "2015",
    "genre" : "Инструментальный рок"
  }
]
"born" : "Упс!!!"

Да, верно — «Упс!!!». Вы можете вставить туда что угодно.

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

Поэтому при работе с JSON часто требуется задать ограничения для типов данных, которые могут попадать в файл. Например, чтобы все даты вводились в определённом формате, скажем, ГГГГ-ММ-ДД. Или убедиться, что пользователи вводят только число в поле возраста.

Создание схемы

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

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

{ "type": "string" }

Вот пример базовой схемы JSON Schema (взят с json-schema.org).

{
  "title": "Example Schema",
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "age": {
      "description": "Age in years",
      "type": "integer",
      "minimum": 0
    }
  },
  "required": ["firstName", "lastName"]
}

Можете использовать эту схему для проверки правильности ввода пользователем имени и возраста.

Как видите, JSON Schema на деле является тем же JSON. Так что не всегда легко определить что перед вами: JSON Schema или обычный JSON-документ.

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

Чтобы объявить JSON Schema, используйте ключевое слово $schema.

{ "$schema": "http://json-schema.org/schema#" }

В данном примере объявляется JSON Schema, написанная для текущей версии спецификации.

Вы также можете указать явно, какую версию спецификации используете. В следующем примере объявляется JSON Schema, написанная для JSON Schema, черновая версия 4.

{ "$schema": "http://json-schema.org/draft-04/schema#" }

Для создания JSON Schema ознакомьтесь с JSONSchema.net. Это онлайн-инструмент, который автоматически генерирует JSON Schema из любого введённого вами JSON.

Автор: Йен Диксон
Последнее изменение: 27.02.2024