Назад

JSON data transfer object

Стандарт JSON

Данный документ описывает формат JSON для сериализации данных объектов 1С. JDTO может быть использован для организации обмена данными между базами данных 1С и внешними системами. Данный формат является основным для механизма логической репликации 1С:Предприятие 8. Исходный код сериализатора JDTO на языке 1С.

  1. Простые типы данных
  2. Ссылочные типы данных
  3. Значения перечислений
  4. Табличные части объектов
  5. Составной тип данных
  6. Удаление ссылочного объекта
  7. Наборы записей регистров

Простые типы данных

Тип данных Значение JSON
Неопределено null
Булево true или false
Число 1234 или 12.34 или -1234 или -12.34
Дата “2025-01-01T00:00:00”
Строка “Это строковое значение”
ХранилищеЗначения Двоичные данные в формате BASE64
УникальныйИдентификатор “841e82c6-b88b-42ed-83c5-be5a5cb20636”
ВидДвиженияНакопления “Приход” или “Расход”

Пример JSON Schema для простых типов данных:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "Пример для простых типов данных",
  "type": "object",
  "properties": {
    "Неопределено": { "type": "null" },
    "Булево": { "type": "boolean" },
    "Число": { "type": "number" },
    "Строка": { "type": "string" },
    "Дата": {
      "type": "string",
      "format": "date-time"
    },
    "ХранилищеЗначения": {
      "type": "string",
      "contentEncoding": "base64"
    },
    "УникальныйИдентификатор": {
      "type": "string",
      "format": "uuid"
    }
  }
}

Наверх

Ссылочные типы данных

Ссылки сериализуются как объект, имеющий два свойства “type” и “value”. Свойство “type” определяет тип ссылки, а свойство “value” хранит её значение.

Тип ссылки указывает на таблицу базы данных, а значение является значением первичного ключа этой таблицы.

Например, ссылка на элемент справочника “Номенклатура” в базе данных в формате JDTO выглядит следующим образом:

{
  "type": "Справочник.Номенклатура",
  "value": "841e82c6-b88b-42ed-83c5-be5a5cb20636"
}

Пример JSON Schema для ссылки:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "ObjectRef",
  "description": "Ссылка на объект в базе данных",
  "type": "object",
  "properties": {
    "type": { "type": "string" },
    "value": { "type": "string", "format": "uuid" }
  },
  "required": [ "type", "value" ],
  "additionalProperties": false
}

Наверх

Значения перечислений

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

{
  "type": "Перечисление.СтавкиНДС",
  "value": "НДС10"
}

Пример JSON Schema для ссылок на значения перечислений:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "EnumRef",
  "description": "Ссылка на значение перечисления",
  "type": "object",
  "properties": {
    "type": { "type": "string", "pattern": "^Перечисление" },
    "value": { "type": "string", "not": { "format": "uuid" }
    }
  },
  "required": [ "type", "value" ],
  "additionalProperties": false
}

Наверх

Табличные части объектов

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

Свойства записей табличных частей сериализуются по тем же правилам и в том же формате, что и свойства ссылочных объектов.

Табличные части не могут быть вложены друг в друга. То есть иерархия для всех JSON объектов ограничена двумя уровнями.

Пример JSON Schema для свойства объекта, значением которого является табличная часть:

{
  "Товары": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "СвойствоТабличнойЧасти": { "type": "string" }
      }
    }
  }
}

Наверх

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

Свойства объектов могут иметь составной тип данных. Это означает, что в разные моменты времени значение свойства может иметь разный тип, а, именно, например, значением свойства может быть число, строка или даже ссылка. Аналогичным составному типу данных является, например, тип данных sql_variant Microsoft SQL Server.

В информатике такие типы данных называются “tagged union” или “discriminated union”.

Значение составного типа в формат JSON сериализуется по тем же правилам, как описано выше, в зависимости от того какое конкретное значение имеет свойство объекта в данный момент времени.

Для описания составных типов данных при помощи JSON Schema предусмотрено ключевое слово oneOf. Постольку поскольку это ключевое слово должно содержать массив схем данных, которые используются для валидации текущего фактического значения свойства объекта, необходимо описать все возможные варианты значений составного типа.

Пример JSON Schema для составного типа значения:

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

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

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "Пример описания составного типа данных",
  "type": "object",
  "properties": {
    "СоставнойТип": {
      "oneOf": [
        { "type": "null" },
        { "type": "boolean" },
        { "type": "number" },
        { "type": "string", "format": "date-time" },
        { "type": "string", "not": { "format": "date-time" } },
        { "type": "#/$defs/EnumRef" },
        { "type": "#/$defs/ObjectRef" }
      ]
    }
  }
}

Наверх

Удаление ссылочного объекта

При удалении ссылочного объекта из базы данных передаётся только значение ссылки на этот объект. Типом сообщения обмена в таком случае является “ObjectDeletion” (удаление объекта). Ниже следующий пример демонстрирует JSON для такого сообщения.

{
  "type": "Справочник.Справочник1",
  "value": "ebed3f4f-8b4f-11f0-9d57-3c64cfca4840"
}

Пример JSON Schema для объекта удаления:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "ObjectDeletion",
  "description": "Сообщение удаления ссылочного объекта",
  "type": "object",
  "properties": {
    "type": { "type": "string" },
    "value": { "type": "string", "format": "uuid" }
  },
  "required": [ "type", "value" ],
  "additionalProperties": false
}

Наверх

Наборы записей регистров

Набор записей регистра — это объект, который представляет собой операцию удаления или вставки одной или нескольких записей в таблицу базы данных. Такой объект имеет одно или оба свойства “delete” и/или “insert” одновременно.

Значением свойства “delete” является объект, свойства которого соответствуют отбору или, иначе говоря, предложению WHERE команды DELETE. Значением свойства “delete” может быть пустой объект, что соответствует операции удаления всех записей целевой таблицы. Значения свойств объединяются в предложении WHERE команды DELETE при помощи логического оператора AND.

{ "delete": {} }

Значением свойства “insert” является массив объектов. Эти объекты представляют собой записи таблицы, которые необходимо в неё вставить. Свойства таких объектов строго соответствуют полям целевой таблицы.

На заметку! Вид операции DML, “INSERT”, “UPDATE” или “DELETE”, для набора записей определяется дополнительным свойством “command”, которое передаётся в составе метаданных сообщения обмена.

Важно! Зачастую операции “DELETE” и “INSERT” выполняются в одной транзакции последовательно друг за другом. При этом они также регистрируются отдельными последовательными сообщениями. Это очень важно учитывать при передаче таких сообщений в транспортный канал и последующей их обработке на стороне приёмника. Требуется обеспечение и реализация гарантии упорядоченной доставки FIFO.

Пример команды INSERT:

{ "insert": [
    {
      "Измерение1": {
        "type": "Справочник.Справочник1",
        "value":"9158802c-8b4f-11f0-9d57-3c64cfca4840"
      },
      "Ресурс1": "111"
    }
  ]
}

Псевдокод SQL для команды INSERT:

INSERT РегистрСведений.РегистрСведений1 (Измерение1, Ресурс1)
VALUES ($.insert[0].Измерение1, $.insert[0].Ресурс1)

Пример команды DELETE:

{ "delete": {
    "Измерение1": {
      "type":"Справочник.Справочник1",
      "value":"9158802c-8b4f-11f0-9d57-3c64cfca4840"
    }
  }
}

Псевдокод SQL для команды DELETE:

DELETE РегистрСведений.РегистрСведений1
 WHERE Измерение1 = $.delete.Измерение1

Пример команды UPDATE:

{ "delete": {
    "Измерение1": {
      "type":"Справочник.Справочник1",
      "value":"d2db05ad-8b4f-11f0-9d57-3c64cfca4840"
    }
  },
  "insert": [
    {
      "Измерение1": {
        "type": "Справочник.Справочник1",
        "value": "d2db05ad-8b4f-11f0-9d57-3c64cfca4840"
      },
      "Ресурс1": "333"
    }
  ]
}

Псевдокод SQL для команды UPDATE:

BEGIN TRANSACTION

DELETE РегистрСведений.РегистрСведений1
 WHERE Измерение1 = $.delete.Измерение1

INSERT РегистрСведений.РегистрСведений1 (Измерение1, Ресурс1)
VALUES ($.insert[0].Измерение1, $.insert[0].Ресурс1)

COMMIT TRANSACTION

Наверх