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

Спецификация XDTO DSL — XML Schema как формат описания пакета

Навыки /xdto-compile (XSD → пакет) и /xdto-decompile (пакет → XSD) используют в качестве формата описания обычную XML-схему. Отдельного DSL нет: XSD и модель XDTO выражают одно и то же, различаясь синтаксисом и умолчаниями, а схема в реальных задачах обычно уже есть — прислана контрагентом.

Формат самих исходников (Package.bin, объект метаданных, схема префиксов) — 1c-xdto-spec.md.

Пример

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:tns="urn:1C.ru:ObmenSBankom"
           targetNamespace="urn:1C.ru:ObmenSBankom"
           elementFormDefault="qualified">
    <xs:simpleType name="СуммаТип">
        <xs:restriction base="xs:decimal">
            <xs:totalDigits value="18"/>
            <xs:fractionDigits value="2"/>
        </xs:restriction>
    </xs:simpleType>

    <xs:complexType name="Платёж">
        <xs:sequence>
            <xs:element name="Дата" type="xs:date"/>
            <xs:element name="Сумма" type="tns:СуммаТип"/>
            <xs:element name="Назначение" type="xs:string" minOccurs="0"/>
        </xs:sequence>
        <xs:attribute name="Номер" type="xs:string"/>
    </xs:complexType>
</xs:schema>

---

1. Таблица соответствий

XML Schema	Модель XDTO
xs:schema/@targetNamespace	package/@targetNamespace
elementFormDefault="qualified"	elementFormQualified="true"
attributeFormDefault="qualified"	attributeFormQualified="true"
xs:import/@namespace	import/@namespace
xs:complexType	objectType
xs:simpleType	valueType
xs:element (глобальный)	property в package
xs:attribute (глобальный)	property form="Attribute" в package
xs:element (локальный)	property
xs:attribute (локальный)	property form="Attribute"
@minOccurs	@lowerBound
@maxOccurs="unbounded"	@upperBound="-1"
@nillable, @default	те же имена
@fixed="V"	@fixed="true" + @default="V" — в модели признак и значение разнесены
xs:element/@ref	property/@ref
анонимный xs:simpleType в объявлении	typeDef xsi:type="ValueType"
анонимный xs:complexType в объявлении	typeDef xsi:type="ObjectType"
xs:complexContent/xs:extension/@base	objectType/@base
@abstract="true", @mixed="true"	те же имена
xs:choice	ordered="false"
xs:sequence	порядок по умолчанию
xs:any + xs:anyAttribute	open="true"
xs:simpleContent/xs:extension/@base	свойство __content с form="Text"
xs:restriction/@base + дочерние фасеты	@base + фасеты атрибутами
xs:pattern, xs:enumeration	<pattern>, <enumeration> — значение в тексте узла
xs:list/@itemType	variety="List" + @itemType
xs:union/@memberTypes	variety="Union" + @memberTypes

Ловушки, на которых модель ошибается чаще всего:

• Кратность инвертирована по смыслу: lowerBound="0" = необязательный, upperBound="-1" = неограниченный.
• Фасеты в XDTO — атрибуты, а не дочерние элементы: maxLength="30", не <xs:maxLength value="30"/>.
• Каждая ссылка на тип требует локального объявления префикса dNpM — в том числе на собственный targetNamespace.

Всё это делает компилятор; писать вручную ничего из перечисленного не нужно.

---

2. Аннотации xdto:

Две вещи XDTO выражает, а XML Schema — нет:

• nillable у атрибута (спецификация XSD допускает его только у элементов);
• qualified у отдельного свойства.

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

Такие случаи описываются атрибутами из пространства имён самой модели XDTO — http://v8.1c.ru/8.1/xdto. Правило одно:

Чего XSD сказать не может — пиши атрибутом xdto: с тем же именем, что в Package.bin.

<xs:attribute name="Представление" type="xs:string"
              xmlns:xdto="http://v8.1c.ru/8.1/xdto" xdto:nillable="true"/>

Такая схема остаётся валидной: XML Schema разрешает атрибуты из чужих пространств имён на объявлениях (anyAttribute namespace="##other" в схеме схем). Валидаторы их игнорируют.

Аннотации строго опциональны — подавляющее большинство схем обходится без единой.

Аннотация	Где	Назначение
xdto:nillable	xs:attribute	nillable у свойства-атрибута
xdto:lowerBound, xdto:upperBound	xs:attribute	кратность свойства-атрибута
xdto:qualified	объявление	переопределение *FormQualified
xdto:form	xs:element	записать form явно (например form="Element")
xdto:name	объявление	имя свойства, если XML-имя не является идентификатором 1С; тогда XML-имя уходит в localName
xdto:variety	xs:restriction, xs:list, xs:union	записать variety явно
xdto:memberTypesForm="prefixed"	xs:union	писать memberTypes префиксами, а не нотацией Кларка
xdto:open, xdto:abstract, xdto:mixed, xdto:ordered, xdto:sequenced	xs:complexType	значения, не выводимые из модели содержимого
xdto:order	xs:complexType	исходный порядок свойств, если он не «атрибуты первыми»; имена через |
xdto:textName, xdto:textlowerBound, xdto:textupperBound, xdto:textnillable	xs:extension в xs:simpleContent	параметры свойства form="Text", если оно названо не __content
xdto:elementFormQualified, xdto:attributeFormQualified	xs:schema	записать флаги явно
xdto:fixed	объявление	признак фиксированного значения отдельно от самого значения: в XSD fixed="V" совмещает их, в модели это fixed="true" + default="V". Нужен только для fixed="false" при заданном default
xdto:type	xs:enumeration	xsi:type литерала перечисления
xdto:prefix	объявление	осмысленный префикс пространства имён вместо генерируемого dNpM (например dcsset)
xdto:declareNs	xs:union	объявить префикс пространства имён на узле (при нотации Кларка платформа иногда его пишет, иногда нет)

Что выводится само

Аннотация нужна только там, где вывод невозможен:

Свойство XDTO	Выводится из
open="true"	наличие xs:any / xs:anyAttribute
ordered="false"	xs:choice вместо xs:sequence
abstract, mixed	одноимённые атрибуты xs:complexType
variety="List" / "Union"	xs:list / xs:union
порядок свойств	атрибуты первыми, затем остальные

sequenced из XSD не выводится (в корпусе он не коррелирует однозначно ни с одной конструкцией) и всегда приходит аннотацией.

---

3. Свойства объекта метаданных

Name, Synonym и Comment живут в xs:annotation/xs:appinfo — штатном месте XML Schema для инструментальных метаданных. Namespace не дублируется: его единственный источник — targetNamespace.

<xs:annotation>
    <xs:appinfo>
        <xdto:package xmlns:xdto="http://v8.1c.ru/8.1/xdto">
            <xdto:name>ОбменСБанком</xdto:name>
            <xdto:synonym lang="ru">Обмен с банком</xdto:synonym>
            <xdto:comment>Формат 1С:Предприятие — Клиент банка</xdto:comment>
        </xdto:package>
    </xs:appinfo>
</xs:annotation>

Блок опционален. Параметры -Name, -Synonym, -Comment навыка /xdto-compile имеют приоритет над ним. Без того и другого имя берётся из имени файла XSD.

Благодаря этому блоку пара /xdto-decompile → /xdto-compile замыкается без потерь, включая свойства объекта метаданных.

---

4. Прощающий ввод

Компилятор принимает и не вполне канонические схемы:

• Имя типа без префикса (type="Платёж") трактуется как тип целевого пространства имён.
• form="qualified" на глобальном объявлении — так экспортирует XML-схему сам Конфигуратор, хотя спецификация XSD допускает form только у локальных объявлений. Такие файлы читаются; сам навык пишет корректно.
• Порядок объявлений верхнего уровня произвольный — компилятор расставляет их в требуемом моделью порядке import → property → valueType → objectType.
• xs:group и xs:attributeGroup раскрываются по ссылке: содержимое группы подставляется в тип.

5. Конструкции без точного соответствия

XML Schema выразительнее модели XDTO. Перечисленное ниже переносится приближённо, и компилятор об этом предупреждает — молча терять свойства нельзя.

Конструкция	Что происходит
вложенная xs:sequence	уплощается в плоский список свойств
вложенная xs:choice	уплощается, и ветки становятся необязательными: иначе «одно из двух» превратилось бы в «оба обязательны» и тип нельзя было бы заполнить. Запрет «ровно один из» не сохраняется
xs:all	трактуется как последовательность
minOccurs/maxOccurs на самой частице	не выражается, отбрасывается
substitutionGroup	объявление сохраняется как обычное
xs:key, xs:keyref, xs:unique	отбрасываются
xs:redefine	игнорируется
xs:include	игнорируется: зависимости разрешаются только по namespace — включаемую схему нужно собрать отдельным пакетом и заменить на xs:import

ordered="false" (выбор одного из вариантов) выводится только из корневой xs:choice типа: модель хранит признак на типе целиком, а не на вложенной частице.