steelmorgan/skd-dsl

SKD DSL

When to Use

| Trigger | Action | |---------|----------| | Create a report (SKD) from scratch | xml-gen skd compile with JSON DSL | | External data set (without a query) | dataSets[].objectName (DataSetObject) | | Combine data sets | dataSets[].items (DataSetUnion) | | Calculated fields | calculatedFields (shorthand or object) | | Output templates | templates + groupTemplates — see references/templates-dsl.md | | Cell drilldown | parameters[].drilldown in the template | | Links between data sets | dataSetLinks | | Understand someone else's SKD | xml-gen skd info --mode overview → then trace/query/variant | | Check correctness | xml-gen validate --type skd | | Targeted editing | skd add-parameter / skd add-field → xml-generation §3 |

CLI Commands

# Компиляция: JSON DSL → Template.xml
xml-gen skd compile [--format designer|edt] <input.json> <output.xml>

# Анализ: Template.xml → компактная сводка (11 режимов)
xml-gen skd info <Template.xml> [--mode <mode>] [--name <name>] [--batch <N>]

# Валидация структуры
xml-gen validate --type skd <Template.xml> [--detailed] [--max-errors 20]

output.xml is the path to the Template.xml layout: .../Templates/<Name>/Ext/Template.xml.

DSL Root Structure

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

Defaults: dataSources → auto ИсточникДанных1/Local; settingsVariants → auto "Main" with detailed records.

Data Sets

The type is determined by the key: query → DataSetQuery, objectName → DataSetObject, items → DataSetUnion.

DataSetQuery: { "name": "...", "query": "ВЫБРАТЬ ...", "fields": [...] }. The query is an inline string or a file "query": "@queries/sales.sql" (path relative to the JSON file, then CWD). DataSetObject: external data set without a query. Data is passed through ПроцессорКомпоновкиДанных.Инициализировать(Макет, Новый Структура("<objectName>", ТЗ), …). Fields are described explicitly in fields[]. name is the data set name, objectName is the key in the data transfer structure. DataSetUnion: { "name": "...", "items": [...], "fields": [...] } — combining data sets with common fields.

Fields - object form only

WARNING: in the current CLI implementation, shorthand strings ("Name [Title]: type @role #restriction") for the fields, calculatedFields, totalFields, and parameters collections are NOT supported — the Jackson deserializer for SkdDsl$Field, SkdDsl$CalculatedField, SkdDsl$Parameter, and SkdDsl$TotalField does not have a String constructor and rejects strings with the error Cannot construct instance ... no String-argument constructor. Use only object form in all examples below, regardless of what is shown in the shorthand fragments of the documentation. The shorthand forms are kept in the file as a reference description of the target semantics.

Object form of a field:

{ "field": "Сумма", "title": "Сумма продажи", "type": "decimal(15,2)",
  "appearance": { "ГоризонтальноеПоложение": "Right", "МинимальнаяШирина": "80" } }

dataPath is taken from field if not specified explicitly.

If roles/restrictions are needed, use object equivalents of shorthand flags:

{ "field": "Организация", "type": "CatalogRef.Организации", "role": "@dimension" }
{ "field": "Служебное", "type": "string", "restrict": ["noFilter", "noOrder"] }

Title: multilingual "title": { "ru": "...", "en": "..." }. Supported everywhere that accepts title/presentation.

Types: string, string(N), decimal, decimal(D,F), boolean, date, dateTime. decimal without parentheses = decimal(10,2). decimal(N) = decimal(N,0). Suffix ,nonneg → AllowedSign=Nonnegative. Aliases number/the Russian word for number ≡ decimal.

Reference types: CatalogRef.X, DocumentRef.X, EnumRef.X, ChartOfAccountsRef.X, StandardPeriod. Emitted with inline namespace d5p1:. Building EPF with reference types requires a database with a matching configuration.

Composite type is an array in object form: "type": ["CatalogRef.А", "CatalogRef.Б"]. Qualifiers apply to each element.

Roles: @dimension, @account, @balance, @period.

Restrictions: shorthand flags #noField, #noFilter, #noGroup, #noOrder; object form: "restrict": ["noField", "noFilter"].

Additional: presentationExpression — expression for presentation (the value remains for drilldown). appearance — default column formatting (platform parameter keys).

Calculated Fields (calculatedFields)

Shorthand: "Name [Title]: type = Expression #flags" — everything except the name is optional.

"calculatedFields": [
  "Маржа = Цена - Закупка",
  "Наценка [Наценка, %]: decimal(10,2) = Маржа / Закупка * 100",
  "Служебное: string = \"\" #noField #noFilter #noGroup #noOrder"
]

Object form — when appearance or composite settings are needed: { "name", "title", "expression", "type", "useRestriction" }.

Totals (totalFields)

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

Bound to groupings — object form:

{ "dataPath": "Кол", "expression": "Сумма(Кол)", "group": ["Группа1", "Группа1 Иерархия", "ОбщийИтог"] }

Parameters

Shorthand: "Name [Title]: type = value @flags".

| Flag | Effect | |------|--------| | @autoDates | For StandardPeriod — adds derived НачалоПериода/КонецПериода. Use &НачалоПериода/&КонецПериода in the query. The parameter gets use=Always, denyIncompleteValues=true. | | @valueList | valueListAllowed=true — allows a list of values. | | @hidden | availableAsField=false + excluded from "dataParameters": "auto". | | @always | use=Always. |

Object form: title, hidden, valueListAllowed, availableAsField, denyIncompleteValues, use: "Always", availableValues[].

"dataParameters": "auto" in a settings variant outputs all non-hidden parameters with userSettingID. Parameters without a default value are disabled (the user will enable them manually).

Filters

Shorthand: "Field operator value @flags". Value _ = empty (placeholder).

Operators: =, <>, >, >=, <, <=, in, notIn, contains, filled, notFilled, InHierarchy.

Flags: @off (use=false), @user (userSettingID=auto), @quickAccess, @normal, @inaccessible.

Groups:

{ "group": "Or", "items": [
  { "group": "And", "items": [
    { "field": "Статус", "op": "=", "value": "Активен" },
    { "field": "Сумма",  "op": ">", "value": 1000 }
  ]},
  { "field": "Количество", "op": "filled" }
]}

Filter value types: Перечисление.* / Справочник.* / ПланСчетов.* / Документ.* → DesignTimeValue (auto-detected).

Data Set Links (dataSetLinks)

"dataSetLinks": [{ "source": "...", "target": "...",
  "items": [{ "sourceExpression": "Организация", "targetExpression": "Организация" }]
}]

Variant Structure (structure)

String shorthand: "structure": "Организация > Номенклатура > details" (> separates levels, details = detail records).

Object form:

"structure": [{ "name": "...", "groupFields": ["Организация"],
  "selection": ["Организация", "Сумма", "Auto"], "children": [{ "groupFields": [] }] }]

type defaults to "group". Supported: name, selection, order, filter, outputParameters, recursive children, type: "table", type: "chart".

Settings Variants (settingsVariants)

"settingsVariants": [{
  "name": "Основной", "title": "Продажи по организациям",
  "settings": {
    "selection": ["Номенклатура", "Количество", "Auto"],
    "filter": ["Организация = _ @off @user"],
    "order": ["Количество desc", "Auto"],
    "outputParameters": { "Заголовок": "Мой отчёт" },
    "dataParameters": ["Период = LastMonth @user"],
    "structure": "Организация > details"
  }
}]

selection: "Auto" = all available fields; { "folder": "...", "items": [...] } → SelectedItemFolder.

Conditional Appearance (conditionalAppearance)

{ "selection": ["Поле1"], "filter": ["Поле1 notFilled"],
  "appearance": { "Текст": "Не указано", "ЦветТекста": "style:XXX" },
  "presentation": "...", "viewMode": "Normal", "userSettingID": "auto" }

Values of appearance: style:XXX/web:XXX/win:XXX → Color; true/false → Boolean; Формат/Текст/Заголовок → LocalStringType; everything else → String.

In settingsVariants.settings, add it under the key "conditionalAppearance": [...].

Output Templates and Groupings

The full specification (cell syntax, styles, drilldown, groupTemplates) — references/templates-dsl.md.

Analysis — xml-gen skd info

11 modes. Detailed output examples — references/info-modes.md.

| Mode | Without --name | With --name | |-------|--------------|-------------| | overview (default) | Schema map + hints for next steps | — | | query | — | Data set query text (with batch table of contents) | | fields | Field map by data set | Field details: dataset, type, role, format | | links | All data set links | — | | calculated | Calculated field map | Expression + title + restrictions | | resources | Resource map (* = has group formulas) | Aggregation formulas by groupings | | params | Parameter table (type, value, visibility) | — | | variant | List of variants | Grouping structure + filters + output | | templates | Template binding map | Template content: rows, cells, expressions | | trace | — | Full chain: data set → calculation → resource | | full | overview + query + fields + resources + params + variant | — |

Workflow: overview → trace --name <field> → query --name <dataset> → variant --name <N>. Parameters: --mode, --name, --batch (0 = all batches), --limit/--offset (default 150), --out-file.

Example — with external query, resources, @autoDates

All collections are in object form (the CLI rejects shorthand strings, see the warning above).

{
  "dataSets": [{
    "query": "@queries/sales.sql",
    "fields": [
      {"field": "Организация",  "type": "CatalogRef.Организации", "role": "@dimension"},
      {"field": "Номенклатура", "type": "CatalogRef.Номенклатура", "role": "@dimension"},
      {"field": "Количество",   "type": "decimal(15,3)"},
      {"field": "Сумма",        "type": "decimal(15,2)"}
    ]
  }],
  "totalFields": [
    {"dataPath": "Количество", "expression": "Сумма(Количество)"},
    {"dataPath": "Сумма",      "expression": "Сумма(Сумма)"}
  ],
  "parameters": [
    {"name": "Период", "type": "StandardPeriod", "value": "LastMonth", "autoDates": true}
  ],
  "settingsVariants": [{
    "name": "Основной",
    "settings": {
      "selection": ["Организация", "Номенклатура", "Количество", "Сумма"],
      "filter": ["Организация = _ @off @user"],
      "dataParameters": "auto",
      "structure": "Организация > details"
    }
  }]
}

Anti-patterns

"filter": ["Amount greater than 0"] — incorrect: the parser accepts operators only from the fixed set (=, <>, >, >=, <, <=, in, notIn, contains, filled, notFilled, InHierarchy). greater is not recognized.

---

depends_on: [] metadata: category: 1c-development version: "2.0"