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": "[e-mail]", "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"
    ]
}

Источники:

• https://infostart.ru/1c/articles/1543922/
• Подробнее про JSON Shema: https://infostart.ru/1c/articles/1546672/
• Конвертер: https://www.liquid-technologies.com/online-json-to-schema-converter