JSON + JSON Schema

JSON (JavaScript Object Notation) — текстовый формат обмена данными, основанный на JavaScript.

Ограничения и синтаксис JSON

Допустимые форматы данных для пары "key":"value" в JSON указаны в карточках ниже:

Ключ "key"

string

Значение "value"

string number (integer) object array boolean null

Основные правила синтаксиса:

  1. Данные записываются в виде пар {“ключ”: значение}.

  2. Данные разделяются запятыми.

  3. В фигурных скобках записываются объекты.

  4. В квадратных скобках записываются массивы.

  5. Наименования «ключей» регистрозависимы.

Пример JSON
{
    "students": [
        {
            "id": 101,
            "name": "Max",
            "score": {
                "Math": 90,
                "Science": 80,
                "Compute": 70
            }
        },
        {
            "id": 102,
            "name": "Sam",
            "score": {
                "Math": 76,
                "Science": 80,
                "Compute": 66
            }
        }
        ],
    "name_school": "EKB Lyceum",
    "name_teacher": "TO"
}

JSON Schema

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

Схема создана для описания JSON-данных, но и сама она при этом является JSON-объектом. С помощью ключевых слов (keywords) в схеме создаются правила валидации структуры объекта и типов его полей.

Простой пример JSON
{
  "id": 210700286,
  "first_name": "Lindsey",
  "last_name": "Stirling"
}
Пример простой JSON Schema
{
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "description": "User ID"
        },
        "first_name": {
          "type": "string",
          "description": "User first name"
        },
        "last_name": {
          "type": "string",
          "description": "User last name"
        }
      },
      "required": [
        "id",
        "first_name",
        "last_name"
      ]
}

"Keywords" для описания схемы

KeywordsОписаниеПример

"$schema"

Используется для задания версии драфта схемы

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

"$id"

Используется для указания уникального идентификатора документа или его подсхем.

"$id": "http://archi-blair.com/schemas/RolesDictionaryDef.json#"

"title" "description" "examples" "comment"

Комментарии к JSON схеме

"Keywords" зависимые от типа данных

Тип данных: "type": "string"

KeywordsОписаниеПример JSON ShemaПримеры JSON сообщения

minLength maxLength

Длину строки string можно ограничить с помощью ключевых слов minLength и maxLength. Для обоих ключевых слов значение должно быть неотрицательным числом.

{
  "type": "string",
  "minLength": 2,
  "maxLength": 3
}
// Положительный кейс 
{ "АB" } или { "АBС" }

// Отрицательный кейс
{ "АBCD" }

pattern

Формат строки string можно ограничивать с помощью ключевого слова pattern. Паттерн задается с помощью регулярного выражения RegEx

{
   "type": "string",
   "pattern": "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$"
}
// Положительный кейс 
{ "555-1212" }

// Отрицательный кейс
{ "(800)FLOWERS" }

Тип данных: "type": "number"

KeywordsОписаниеПример JSON ShemaПримеры JSON сообщения

minimum maximum exclusiveMinimum exclusiveMaximum

Диапазон числа number можно ограничивать с помощью ключевых слов.

Если x - это проверяемое значение, то должно выполняться следующее:

  • x ≥ minimum

  • x > exclusiveMinimum

  • x ≤ maximum

  • x < exclusiveMaximum

{
  "type": "number",
  "minimum": 0,
  "exclusiveMaximum": 100
}
// Положительный кейс 
{ 0 } или { 99 } или { 10 }

// Отрицательный кейс
{ 100 } или { -1 }

multipleOf

Кратность числа number можно ограничивать с помощью multipleOf

{
    "type": "number",
    "multipleOf" : 10
}
// Положительный кейс 
{ 10 } или { 20 }

// Отрицательный кейс
{ 23 }

Тип данных: "type": "object"

KeywordsОписаниеПример JSON ShemaПримеры JSON сообщения

properties

Тип данных объектов object можно ограничивать с помощью properties в котором прописаны ограничения для каждого объекта

{
  "type": "object",
  "properties": {
    "number": { "type": "number" },
    "street_name": { "type": "string" },
    "street_type": { "enum": ["Street", "Avenue", "Boulevard"] }
  }
}
// Положительный кейс 
{ "number": 1600, "street_name": "Pennsylvania", "street_type": "Avenue" }

// Отрицательный кейс
{ "number": "1600", "street_name": "Pennsylvania", "street_type": "Avenue" }

patternProperties

Тип данных объектов object можно ограничивать с помощью шаблонов свойств 

{
  "type": "object",
  "patternProperties": {
    "^S_": { "type": "string" },
    "^I_": { "type": "integer" }
  }
}
// Положительный кейс 
{ "S_25": "This is a string" }
{ "I_0": 42 }

// Отрицательный кейс
{ "S_0": 42 }

additionalProperties

Используется для управления обработкой дополнительных элементов, не входящих ни в properties, ни в patternProperties

{
  "type": "object",
  "properties": {
    "number": { "type": "number" },
    "street_name": { "type": "string" },
    "street_type": { "enum": ["Street", "Avenue", "Boulevard"] }
  },
  "additionalProperties": false
}
// Положительный кейс 
{ "number": 1600, "street_name": "Pennsylvania", "street_type": "Avenue" }

// Отрицательный кейс
{ "number": 1600, "street_name": "Pennsylvania", "street_type": "Avenue", "direction": "NW" }

required

Ограничение на обязательные объекты object

 {
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "email": { "type": "string" },
    "address": { "type": "string" },
    "telephone": { "type": "string" }
  },
  "required": ["name", "email"]
}
// Положительный кейс 
{ 
  "name": "William",
  "email": "bill@stratford.co.uk",
  "address": "Henley Street,England",
  "telephone": "1234"
}

// Отрицательный кейс
{
  "name": "William",
  "address": "Henley Street,England"
}

propertyNames

Формат элементов объекта object можно ограничивать с помощью ключевого слова propertyNames. Паттерн задается с помощью регулярного выражения RegEx

{
  "type": "object",
  "propertyNames": {
    "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
  }
}
// Положительный кейс 
{ "_a_proper_token_001": "value" }

// Отрицательный кейс
{ "001 invalid": "value" }

minProperties maxProperties

Количество свойств объекта можно ограничить с помощью ключевых слов

{
  "type": "object",
  "minProperties": 2,
  "maxProperties": 3
}
// Положительный кейс 
{ "a": 0, "b": 1 }

// Отрицательный кейс
{ "a": 0 }

Тип данных: "type": "array"

KeywordsОписаниеПример JSON ShemaПримеры JSON сообщения

items

Ограничение на тип элементов массива (для всего массива)

{
  "type": "array",
  "items": {
    "type": "number"
  }
}
// Положительный кейс 
[1, 2, 3, 4, 5]

// Отрицательный кейс
[1, 2, "3", 4, 5]

prefixItems

Ограничение на тип элементов массива (для каждого конкретного индекса массива)

{
  "type": "array",
  "prefixItems": [
    { "type": "number" },
    { "type": "string" },
    { "enum": ["Street", "Avenue", "Boulevard"] },
    { "enum": ["NW", "NE", "SW", "SE"] }
  ]
}
// Положительный кейс 
[1600, "Pennsylvania", "Avenue", "NW"]

// Отрицательный кейс
[1600, "Pennsylvania", "Avenue", "MOSCOW"]

contains

Ограничение на содержание элемента в массиве

{
   "type": "array",
   "contains": {
     "type": "number"
   }
}
// Положительный кейс 
["life", "universe", "everything", 42]

// Отрицательный кейс
["life", "universe", "everything", "forty-two"]

minItems maxItems

Ограничение на длину массива 

{
  "type": "array",
  "minItems": 2,
  "maxItems": 3
}
// Положительный кейс 
[1, 2]

// Отрицательный кейс
[1, 2, 3, 4]

Пример

ПолеТипОбязательностьОписание

time

string

"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\\\.[0-9]{6})?((-|\\\\+)[0-9]{2}:[0-9]{2})?)?)?$"

Да

Дата и время сообщения

eventId

string (255)

Да

Уникальный идентификатор события

contactID

string (255)

Да

Идентификатор контакта

operationType

string (enum)

Да

Тип операции CREATE, READ, UPDATE, DELETE

getFlag

string (1)

Да

Флаг

phoneNumber

string (50)

pattern: "^([0-9]{10})$"

Да

Номер телефона клиента

phoneNumberTimeZone

string (255)

Да

Таймзона клиента

scenarioId

string (255)

Да

Номер сценария

customAttributeList

Array [Object]

Да

attributeName

string (255)

Да

Идентификатор атрибута cardNum, lockSum, lockCurrency, lockDate

attributeValue

string (255)

Да

Значение атрибута

Большой развернутый пример
{    
    "$schema":"http://json-schema.org/draft-06/schema#",
    "$ref":"#/definitions/test",
    "description": "Тестовое описание",
    "type": "object",
    "properties": {
      "time": {
        "type": "string",
        "description": "Дата и время сообщения",
        "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\\\.[0-9]{6})?((-|\\\\+)[0-9]{2}:[0-9]{2})?)?)?$"
      },
      "eventId": {
        "type": "string",
        "description": "Уникальный идентификатор события",
        "minLength": 1,
        "maxLength": 255
      },
      "contactID": {
        "type": "string",
        "description": "Идентификатор контакта",
        "minLength": 1,
        "maxLength": 255
      },
      "operationType": {
        "type": "string",
        "description": "Тип операции",
	"enum": ["CREATE", "READ", "UPDATE", "DELETE"]
      },
      "getFlag": {
        "type": "string",
        "description": "Флаг",
	"maxLength": 1
      },
      "phoneNumber": {
        "type": "string",
        "description": "Номер телефона клиента",
        "pattern": "^([0-9]{10})$",
        "minLength": 1,
	"maxLength": 50
      },
      "phoneNumberTimeZone": {
        "type": "string",
        "description": "Таймзона клиента",
        "minLength": 1,
	"maxLength": 255
      },
      "scenarioId": {
        "type": "string",
        "description": "Номер сценария",
        "minLength": 1,
	"maxLength": 255
      },
      "customAttributeList": {
        "type": "array",
	"items": {
		"type": "object",
		"properties": {
			"attributeName": {
				"type": "string",
				"description": "Идентификатор атрибута",
				"minLength": 1,
				"maxLength": 255,
				"enum": ["cardNum", "lockSum", "lockCurrency", "lockDate"]
				},
			"attributeValue": {
				"type": "string",
				"description": "Значение атрибута",
				"minLength": 1,
				"maxLength": 255
				}
			},	
		"additionalProperties": false,
		"required":[
			"attributeName",
			"attributeValue"
			]
               }
      }
    },
"additionalProperties": false,
"required": [
	"time",
	"eventId",
	"contactID",
	"operationType",
	"getFlag",
	"phoneNumber",
	"phoneNumberTimeZone",
	"scenarioId",
	"customAttributeList"
    ]
}

Источники:

PreviousФорматы данныхNextAVRO

Last updated