steelmorgan/mxl-dsl

MXL DSL

Compact JSON format for describing 1С tabular documents (SpreadsheetDocument). Claude describes what (areas, cells, styles, parameters), while the CLI guarantees XML correctness (palettes, indices, merges, namespace).

The canon is taken from Shirokov's specification (cc-1c-skills) and extended with the --format designer|edt flag for two output formats.

When to use

| Trigger | Action | |---------|----------| | Create a print form from scratch | mxl compile + JSON DSL → references/dsl-spec.md | | Refine an existing layout | mxl decompile → edit JSON → mxl compile | | Validate MXL tool behavior against canon XML | xml-gen oracle mxl --mode dsl|cli|both | | Understand the structure of someone else's layout (areas, parameters, drill-downs) | mxl info → references/info-modes.md | | Check the correctness of the assembled Template.xml | xml-gen validate --type mxl → references/validate-classes.md | | Reverse-engineer print output from a sample (screenshot/scan) | mxl decompile or build from scratch on a grid — define page + "Nx" widths |

Intentionally outside the DSL - do it in code

The DSL covers static cell formatting — font/align/valign/border/wrap/format through the styles map. It intentionally does NOT generate runtime-conditional formatting: cell coloring/styling based on the displayed value. This is done programmatically when filling the tabular document — Область.ТекстЦвет = …, Область.ЦветФона = … on the populated area. The absence is a design choice, not a tool defect; see rule no-manual-xml-edit.md § "What is done in code, and NOT through xml-gen".

Commands

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

# Декомпиляция Template.xml → JSON DSL
xml-gen mxl decompile <Template.xml> <output.json>

# Анализ структуры (области, параметры, расшифровки, текст)
xml-gen mxl info <Template.xml> [--with-text] [--limit N] [--offset N] [--format text|json]

# Валидация
xml-gen validate --type mxl <Template.xml> [--detailed] [--max-errors N]

# Поведенческий оракул по реальному канону
xml-gen oracle mxl --source <Template.xml|src/xml> --out build/oracle --mode dsl|cli|both [--include-all]

output.xml for compile is the path to the layout in EPF/ERF: .../Templates/<Name>/Ext/Template.xml.

--format (compile only):

• designer - configuration designer format (Template.xml in Ext/)
• edt - EDT format (XML inside the .mxl folder of the EDT project)

Minimal DSL

{
  "columns": 4,
  "areas": [
    {
      "name": "Заголовок",
      "rows": [
        { "cells": [
          { "col": 1, "span": 4, "text": "Накладная" }
        ]}
      ]
    }
  ]
}

Key differences from the old inline format

| Was (old) | Became (canon) | |--------------|---------------| | {"text": "[Parameter]"} - parameter in brackets in the text | {"param": "Parameter"} - separate cell type | | {"text": "Inv. No. [Number]"} - parameter in the template in brackets | {"template": "Inv. No. [Number]"} - separate type | | span without col (sequential filling) | col 1-based + span (explicit positioning) | | Column widths were not specified | columns + columnWidths + page + "Nx" | | Solid row borders - every cell is explicit | rowStyle - automatic filling of gaps | | Only horizontal merging | rowspan (vertical) + rowStyle takes occupied cells into account | | Drill-down was not described | detail - drill-down parameter next to param | | Row height was not specified | height on the row | | N empty rows - N {} objects | { "empty": N } |

The full field specification (top level, fonts, styles, areas, rows, cells, fillType detection, rowStyle with rowspan, "Nx" proportions, 1С formats ЧДЦ=/ДФ=) - references/dsl-spec.md.

Using areas in BSL

Area names from the DSL (name) and parameter names (param) are what BSL uses to address the layout:

ТД = ЭтотОбъект.ПолучитьМакет("ПечатнаяФорма");
ТабДок = Новый ТабличныйДокумент;

ОбластьШапка = ТД.ПолучитьОбласть("Заголовок");
ОбластьШапка.Параметры.ТекстЗаголовка = "Накладная № 1";
ТабДок.Вывести(ОбластьШапка);

Для Каждого Стр Из ТЧ Цикл
    Строка = ТД.ПолучитьОбласть("Строка");
    Строка.Параметры.Товар       = Стр.Товар;        // detail = Номенклатура подставит ссылку для расшифровки
    Строка.Параметры.Количество  = Стр.Количество;
    Строка.Параметры.Сумма       = Стр.Сумма;
    ТабДок.Вывести(Строка);
КонецЦикла;

For intersections (Rows area + Columns area, for example labels/price tags), access via |:

Область = ТД.ПолучитьОбласть("ВысотаЭтикетки|ШиринаЭтикетки");

Decompile - what is important to know

• Fonts and styles receive automatic meaningful names (default, bold, header, bordered, bordered-right, bold-right, border-top, etc.) based on property combinations - they do not have to match the original.
• If all empty cells in a row have the same style, it is collapsed into rowStyle, and the empty cells are removed from the output.
• Template parameters ([Name] in text) are extracted into separate template cells.

Oracle modes

xml-gen oracle mxl validates two independent modes:

• --mode dsl decompiles canon Template.xml to JSON DSL, compiles a new sandbox Template.xml, and compares it with the canon. The canon file is never overwritten.
• --mode cli decompiles canon into a CommandPlan of public commands: epf init, epf add-template --type SpreadsheetDocument, mxl compile, validate. The result inside the temporary EPF sandbox is compared with the canon separately from DSL mode.
• --mode both runs both and reports separate dsl and cli summaries.
• With a src/xml source, the default corpus is the _Демо pilot. Use --include-all only for a broad audit of all MXL Template.xml files.

Use oracle for regression detection and coverage reports. Use normal mxl compile/decompile/info/validate for day-to-day generation and editing.

Workflow (typical)

1. (optional) If the layout is created from an image - overlay a grid, determine column proportions → set page: "A4-landscape" + "Nx" widths.
2. Write JSON (Write).
3. mxl compile → Template.xml.
4. xml-gen validate --type mxl → if there are errors, see references/validate-classes.md.
5. mxl info → inspect the structure of areas and parameters with the agent's eyes.
6. (for refining someone else's layout) mxl decompile → edit → compile.
7. (for validating tool behavior) xml-gen oracle mxl --source src/xml --out build/oracle --mode both.

Correct / Incorrect

// ❌ статический текст и параметр свалены в одну ячейку через скобки
{ "col": 2, "text": "Инв № [Номер]" }

// ✅ это шаблон с подстановкой → template
{ "col": 2, "template": "Инв № [Номер]" }

// ❌ сплошные рамки строки — каждая пустая ячейка прописана вручную
{ "cells": [
  { "col": 1, "style": "bordered", "param": "А" },
  { "col": 2, "style": "bordered" },
  { "col": 3, "style": "bordered" },
  { "col": 4, "style": "bordered", "param": "Б" }
]}

// ✅ rowStyle автозаполняет пустоты
{ "rowStyle": "bordered", "cells": [
  { "col": 1, "param": "А" },
  { "col": 4, "param": "Б" }
]}

Links

• references/dsl-spec.md - full DSL field specification
• references/info-modes.md - how to read mxl info output (area types, intersections, [tpl] parameters, detail)
• references/validate-classes.md - validator error classes
• Adjacent DSLs: ../role-dsl/, ../form-dsl/

---

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