cc-1c-skills/docs/skd-dsl-spec.md

JSON DSL для схемы компоновки данных (СКД)

Компактный JSON-формат для описания DataCompositionSchema (Template.xml). Компилируется навыком /skd-compile в XML, валидируется /skd-validate.

---

1. Корневая структура

{
  "dataSources": [...],
  "dataSets": [...],
  "dataSetLinks": [...],
  "calculatedFields": [...],
  "totalFields": [...],
  "parameters": [...],
  "templates": [...],
  "groupTemplates": [...],
  "settingsVariants": [...]
}

Умолчания:

• dataSources опущен → авто-создаётся { "name": "ИсточникДанных1", "type": "Local" }
• source в наборе опущен → первый dataSource
• name набора опущен → "НаборДанных1", "НаборДанных2"...
• settingsVariants опущен → один вариант "Основной" с детальной группировкой и selection: ["Auto"]

---

2. Источники данных (dataSources)

"dataSources": [
  { "name": "ИсточникДанных1", "type": "Local" }
]

Поле	Обязат.	Умолчание	XML-маппинг
name	да	—	<name>
type	нет	"Local"	<dataSourceType>

Значения type: "Local", "External".

---

3. Наборы данных (dataSets)

Тип определяется по ключу-дискриминатору:

Ключ	Тип	xsi:type
query	Запрос	DataSetQuery
objectName	Объект	DataSetObject
items	Объединение	DataSetUnion

DataSetQuery (самый частый)

{ "name": "Продажи", "query": "ВЫБРАТЬ ...", "fields": [...], "autoFillFields": false }

DataSetObject

{ "name": "ТаблицаПроверки", "objectName": "ТаблицаПроверки", "fields": [...] }

DataSetUnion

{
  "name": "Объединение",
  "items": [
    { "name": "Набор1", "query": "...", "fields": [...] },
    { "name": "Набор2", "query": "...", "fields": [...] }
  ],
  "fields": [...]
}

Поле	Обязат.	Описание
name	нет	Авто: "НаборДанных1"...
source	нет	Имя dataSource (авто: первый)
query	да*	Текст запроса (DataSetQuery)
objectName	да*	Имя объекта (DataSetObject)
items	да*	Вложенные наборы (DataSetUnion)
fields	нет	Массив полей
autoFillFields	нет	false — отключить автозаполнение (по умолчанию не выводится = true)

---

4. Поля — shorthand и объектная форма

Shorthand-строка

"<dataPath>[: <type>] [@role...] [#restrict...]"

Примеры:

"fields": [
  "Наименование",
  "Количество: decimal(15,2)",
  "Организация: CatalogRef.Организации @dimension",
  "Служебное: string #noFilter #noOrder",
  "Счёт: CatalogRef.Хозрасчетный @account",
  "Сумма: decimal(15,2) @balance"
]

Объектная форма

{
  "dataPath": "Сумма",
  "field": "Сумма",
  "title": "Сумма продаж",
  "type": "decimal(15,2)",
  "role": { "dimension": true },
  "restrict": ["noFilter", "noGroup"],
  "attrRestrict": ["noFilter"],
  "appearance": { "Формат": "ЧДЦ=2" },
  "presentationExpression": "Формат(Сумма, \"ЧДЦ=2\")"
}

Парсинг shorthand

1. Разделить по пробелам; найти @-роли и #-ограничения
2. Остаток до первого : — dataPath (и field по умолчанию)
3. После : до @/# — тип

Типы

DSL	XML v8:Type	Квалификатор
string	xs:string	Length=0, AllowedLength=Variable
string(N)	xs:string	Length=N, AllowedLength=Variable
decimal(D,F)	xs:decimal	Digits=D, FractionDigits=F, AllowedSign=Any
decimal(D,F,nonneg)	xs:decimal	Digits=D, FractionDigits=F, AllowedSign=Nonnegative
boolean	xs:boolean	—
date	xs:dateTime	DateFractions=Date
dateTime	xs:dateTime	DateFractions=DateTime
CatalogRef.XXX	cfg:CatalogRef.XXX	—
DocumentRef.XXX	cfg:DocumentRef.XXX	—
EnumRef.XXX	cfg:EnumRef.XXX	—
ChartOfAccountsRef.XXX	cfg:ChartOfAccountsRef.XXX	—
StandardPeriod	v8:StandardPeriod	—

Роли

DSL shorthand	Объектная форма	XML
@dimension	"role": "dimension" или {"dimension": true}	<dcscom:dimension>true</dcscom:dimension>
@account	"role": "account" или {"account": true}	<dcscom:account>true</dcscom:account>
@balance	"role": "balance" или {"balance": true}	<dcscom:balance>true</dcscom:balance>
@period	"role": "period" или {"period": true}	<dcscom:period>true</dcscom:period>

Объектная форма с доп. полями:

"role": {
  "account": true,
  "accountTypeExpression": "Счёт.ВидСчёта",
  "balanceGroup": "/Остатки"
}

Ограничения

DSL shorthand	Объектная форма	XML useRestriction
#noField	"noField"	<field>true</field>
#noFilter / #noCondition	"noFilter"	<condition>true</condition>
#noGroup	"noGroup"	<group>true</group>
#noOrder	"noOrder"	<order>true</order>

Оформление (appearance)

"appearance": {
  "Формат": "ЧДЦ=2",
  "ГоризонтальноеПоложение": "Center"
}

Маппинг на XML:

<appearance>
  <dcscor:item xsi:type="dcsset:SettingsParameterValue">
    <dcscor:parameter>Формат</dcscor:parameter>
    <dcscor:value xsi:type="xs:string">ЧДЦ=2</dcscor:value>
  </dcscor:item>
</appearance>

Значения ГоризонтальноеПоложение → xsi:type="v8ui:HorizontalAlign".

---

5. Итоговые поля (totalFields)

Shorthand

"<dataPath>: <Функция>"
"<dataPath>: <Функция>(<выражение>)"

Примеры:

"totalFields": [
  "Количество: Сумма",
  "Цена: Максимум",
  "Стоимость: Сумма(Кол * Цена)"
]

Парсинг: "A: Func" → dataPath=A, expression=Func(A). "A: Func(expr)" → dataPath=A, expression=Func(expr).

Функции (русские): Сумма, Количество, Максимум, Минимум, Среднее.

Объектная форма

{ "dataPath": "X", "expression": "Максимум(X)", "group": "Группа1" }

---

6. Параметры (parameters)

Shorthand

"<name>: <type> [= <default>]"

Примеры:

"parameters": [
  "Период: StandardPeriod = LastMonth",
  "Организация: CatalogRef.Организации",
  "ДатаОтчета: date"
]

Парсинг: "A: T = V" → name=A, type=T, value=V. Значение LastMonth и другие варианты периодов → v8:StandardPeriod с v8:variant.

Объектная форма

{
  "name": "ДатаНач",
  "title": "Дата начала",
  "type": "date",
  "value": "0001-01-01T00:00:00",
  "expression": "&Период.ДатаНачала",
  "availableAsField": false,
  "useRestriction": true,
  "use": "Always"
}

Поле	Описание
name	Имя параметра
title	Заголовок (умолч. = name)
type	Тип (см. таблицу типов)
value	Значение по умолчанию
expression	Выражение для вычисления
availableAsField	false — скрыть из полей
useRestriction	true — скрыть от пользователя
use	"Always", "Auto"

Значения параметров по типу

Тип	value	XML
StandardPeriod	"LastMonth", "ThisYear" и др.	<v8:variant xsi:type="v8:StandardPeriodVariant">LastMonth</v8:variant>
date	"0001-01-01T00:00:00"	xsi:type="xs:dateTime"
string	"текст"	xsi:type="xs:string"
boolean	true/false	xsi:type="xs:boolean"

Стандартные варианты периодов: Custom, Today, ThisWeek, ThisMonth, ThisQuarter, ThisYear, LastMonth, LastQuarter, LastYear.

---

7. Вычисляемые поля (calculatedFields)

Shorthand

"<dataPath> = <expression>"

"calculatedFields": [
  "УИД = Строка(Ссылка.УникальныйИдентификатор())",
  "Итого = Количество * Цена"
]

Объектная форма

{
  "dataPath": "Итого",
  "expression": "Количество * Цена",
  "title": "Итого",
  "type": "decimal(15,2)",
  "restrict": ["noGroup"],
  "appearance": { "Формат": "ЧДЦ=2" }
}

---

8. Связи наборов (dataSetLinks)

Только объектная форма:

"dataSetLinks": [
  {
    "source": "Периоды",
    "dest": "Данные",
    "sourceExpr": "Месяц",
    "destExpr": "Месяц",
    "parameter": "НачалоМесяца"
  }
]

Поле	XML
source	<sourceDataSet>
dest	<destinationDataSet>
sourceExpr	<sourceExpression>
destExpr	<destinationExpression>
parameter	<parameter> (опц.)

---

9. Варианты настроек (settingsVariants)

"settingsVariants": [{
  "name": "Основной",
  "presentation": "Основной вариант",
  "settings": {
    "selection": [...],
    "filter": [...],
    "order": [...],
    "outputParameters": {...},
    "dataParameters": [...],
    "structure": [...]
  }
}]

selection

"selection": [
  "Наименование",
  { "field": "Количество", "title": "Кол-во" },
  "Auto"
]

• Строка → SelectedItemField
• "Auto" → SelectedItemAuto
• Объект с field/title → SelectedItemField с lwsTitle

filter

"filter": [
  { "field": "Организация", "op": "=", "use": false, "userSettingID": "auto" },
  { "field": "Дата", "op": ">=", "value": "0001-01-01T00:00:00", "valueType": "xs:dateTime" },
  { "group": "Or", "items": [
    { "field": "Статус", "op": "=", "value": true, "valueType": "xs:boolean" },
    { "field": "Пометка", "op": "filled" }
  ]}
]

Поле	Описание
field	Имя поля
op	Оператор (см. таблицу)
value	Правая часть (опц.)
valueType	xsi:type для значения (опц.)
use	Включён (true по умолчанию)
presentation	Текст подсказки
viewMode	"Normal", "QuickAccess", "Inaccessible"
userSettingID	"auto" → генерировать GUID

Операторы:

DSL	XML comparisonType
=	Equal
<>	NotEqual
>	Greater
>=	GreaterOrEqual
<	Less
<=	LessOrEqual
in	InList
notIn	NotInList
inHierarchy	InHierarchy
contains	Contains
notContains	NotContains
beginsWith	BeginsWith
filled	Filled
notFilled	NotFilled

Группа условий: { "group": "And"|"Or"|"Not", "items": [...] } → FilterItemGroup с groupType.

order

"order": ["Количество desc", "Наименование", "Auto"]

• "Field" → OrderItemField, orderType=Asc
• "Field desc" → OrderItemField, orderType=Desc
• "Field asc" → OrderItemField, orderType=Asc
• "Auto" → OrderItemAuto

outputParameters

"outputParameters": {
  "Заголовок": "Мой отчёт",
  "ВыводитьЗаголовок": "Output",
  "МакетОформления": "ОформлениеОтчетовЧерноБелый"
}

Ключ → dcscor:parameter, значение → dcscor:value.

Типы значений определяются автоматически:

• "Заголовок" → v8:LocalStringType
• "ВыводитьЗаголовок", "ВыводитьПараметрыДанных", "ВыводитьОтбор" → dcsset:DataCompositionTextOutputType
• "РасположениеПолейГруппировки" → dcsset:DataCompositionGroupFieldsPlacement
• "РасположениеРеквизитов" → dcsset:DataCompositionAttributesPlacement
• "ГоризонтальноеРасположениеОбщихИтогов", "ВертикальноеРасположениеОбщихИтогов" → dcscor:DataCompositionTotalPlacement
• Прочие → xs:string

dataParameters

"dataParameters": [
  { "parameter": "Период", "value": { "variant": "LastMonth" }, "userSettingID": "auto" },
  { "parameter": "Организация", "use": false, "viewMode": "Normal", "userSettingID": "auto" }
]

structure

"structure": [
  {
    "type": "group",
    "groupBy": ["Организация"],
    "selection": ["Auto"],
    "order": ["Auto"],
    "children": [
      { "type": "group", "selection": ["Auto"], "order": ["Auto"] }
    ]
  }
]

Группировка (group)

Поле	Описание
type	"group"
name	Имя группировки (опц.)
groupBy	Массив полей. Пусто/опущено = детальные записи
groupType	"Items" (умолч.), "Hierarchy", "HierarchyOnly"
selection	Выборка (как в settings)
filter	Отборы (как в settings)
order	Сортировка (как в settings)
outputParameters	Параметры вывода (как в settings)
children	Вложенные элементы структуры

Пустой groupBy (или []) = детальные записи (без groupItems в XML).

Таблица (table)

{
  "type": "table",
  "name": "Таблица",
  "rows": [
    { "groupBy": ["Номенклатура"], "selection": ["Auto"], "order": ["Auto"] }
  ],
  "columns": [
    { "groupBy": ["Период"], "selection": ["Auto"], "order": ["Auto"] }
  ]
}

Диаграмма (chart)

{
  "type": "chart",
  "points": { "groupBy": ["Организация"], "order": ["Auto"] },
  "series": { "groupBy": ["Месяц"], "order": ["Auto"] },
  "selection": ["Сумма"]
}

---

10. Макеты и привязки (templates, groupTemplates)

Редко используются. Поддерживаются в объектной форме, близкой к XML.

templates

"templates": [
  {
    "name": "Макет1",
    "template": "<raw XML dcsat:AreaTemplate>",
    "parameters": [
      { "name": "ТипЦены", "expression": "Представление(ТипЦен)" }
    ]
  }
]

groupTemplates

"groupTemplates": [
  { "groupField": "ТипЦен", "templateType": "Header", "template": "Макет1" }
]

---

11. Полный пример — минимальный

{
  "dataSets": [
    {
      "name": "НаборДанных1",
      "query": "ВЫБРАТЬ\n\tНоменклатура.Наименование КАК Наименование,\n\tКОЛИЧЕСТВО(1) КАК Количество\nИЗ\n\tСправочник.Номенклатура КАК Номенклатура\nСГРУППИРОВАТЬ ПО\n\tНоменклатура.Наименование",
      "fields": [
        { "dataPath": "Наименование", "title": "Наименование" },
        "Количество"
      ]
    }
  ],
  "totalFields": ["Количество: Сумма"],
  "settingsVariants": [{
    "name": "Основной",
    "presentation": "Основной",
    "settings": {
      "selection": ["Наименование", "Количество"],
      "structure": [
        { "type": "group", "order": ["Auto"], "selection": ["Auto"] }
      ]
    }
  }]
}

12. Полный пример — средний

{
  "dataSets": [
    {
      "name": "Продажи",
      "query": "ВЫБРАТЬ\n\tПродажи.Организация,\n\tПродажи.Номенклатура,\n\tПродажи.Количество,\n\tПродажи.Сумма\nИЗ\n\tРегистрНакопления.Продажи КАК Продажи\n{ГДЕ\n\tПродажи.Период >= &ДатаНачала\n\tИ Продажи.Период < &ДатаОкончания}",
      "fields": [
        "Организация: CatalogRef.Организации @dimension",
        "Номенклатура: CatalogRef.Номенклатура @dimension",
        "Количество: decimal(15,3)",
        "Сумма: decimal(15,2)"
      ]
    }
  ],
  "totalFields": [
    "Количество: Сумма",
    "Сумма: Сумма"
  ],
  "parameters": [
    "Период: StandardPeriod = LastMonth",
    { "name": "ДатаНачала", "type": "date", "expression": "&Период.ДатаНачала", "availableAsField": false },
    { "name": "ДатаОкончания", "type": "date", "expression": "&Период.ДатаОкончания", "availableAsField": false }
  ],
  "settingsVariants": [{
    "name": "Основной",
    "presentation": "Продажи по организациям",
    "settings": {
      "selection": ["Номенклатура", "Количество", "Сумма", "Auto"],
      "filter": [
        { "field": "Организация", "op": "=", "use": false, "userSettingID": "auto" }
      ],
      "order": ["Сумма desc", "Auto"],
      "outputParameters": {
        "Заголовок": "Анализ продаж",
        "ВыводитьЗаголовок": "Output"
      },
      "dataParameters": [
        { "parameter": "Период", "value": { "variant": "LastMonth" }, "userSettingID": "auto" }
      ],
      "structure": [
        {
          "type": "group",
          "groupBy": ["Организация"],
          "selection": ["Auto"],
          "order": ["Auto"],
          "children": [
            { "type": "group", "selection": ["Auto"], "order": ["Auto"] }
          ]
        }
      ]
    }
  }]
}