feat(xdto-compile,xdto-decompile,xdto-validate): пакеты XDTO из XML-схемы

Три навыка для работы с пакетами XDTO. Формат описания — обычная XSD, своего DSL нет: рутину снимает конвертер (локальные объявления префиксов dNpM на каждой ссылке, инвертированная кратность lowerBound/upperBound, фасеты атрибутами вместо дочерних элементов, обязательный порядок элементов верхнего уровня). То, чего XSD выразить не может — nillable у атрибута, qualified у свойства, «атрибут записан явно» — едет атрибутами из пространства имён модели XDTO по правилу «то же имя, что в Package.bin». Свойства объекта метаданных живут в xs:appinfo, поэтому пара decompile → compile замыкается без потерь. Инвариант bin → xsd → bin проверен побайтово на 760 пакетах выгрузок Бухгалтерии и ERP 8.3.24 (харнесс debug/xdto/roundtrip-corpus.mjs). Сборка из рукописной XSD проверена загрузкой в базу 8.3.24 — именно она вскрыла обязательный порядок import→property→valueType→objectType, невидимый для корпусной сверки: все выгрузки уже канонические. xdto-validate ловит два класса тихих дефектов, которые платформа не диагностирует: подмену неразрешённого чужого типа на xs:anyType при импорте XML-схемы и nillable у свойства-атрибута, теряемый экспортом схемы в Конфигураторе. Тесты: 18 снэпшот-кейсов на синтетических схемах (типовые конфигурации в репозиторий не тащим), паритет PS↔PY на общих эталонах. Раннер получил caseFiles — копирование файлов кейса в workDir для навыков с файловым, а не JSON входом. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-26 22:51:03 +03:00 · 2026-07-25 21:21:57 +03:00
parent d544071b1e
commit d05aef54b4
140 changed files with 9601 additions and 1 deletions
@@ -49,7 +49,7 @@
 | XML-элемент | Каталог | Русское название | Спецификация |
 |-------------|---------|-----------------|--------------|
 | `ExchangePlan` | `ExchangePlans/` | Планы обмена | [1c-config-objects-spec.md § 15](1c-config-objects-spec.md#15-планы-обмена-exchangeplans) |
-| `XDTOPackage` | `XDTOPackages/` | XDTO-пакеты | [1c-configuration-spec.md § 6.14](1c-configuration-spec.md#614-xdtopackage--xdto-пакет) |
+| `XDTOPackage` | `XDTOPackages/` | XDTO-пакеты | [1c-xdto-spec.md](1c-xdto-spec.md) |
 | `WebService` | `WebServices/` | Веб-сервисы | [1c-config-objects-spec.md § 25](1c-config-objects-spec.md#25-веб-сервисы-webservices) |
 | `HTTPService` | `HTTPServices/` | HTTP-сервисы | [1c-config-objects-spec.md § 24](1c-config-objects-spec.md#24-http-сервисы-httpservices) |
 | `WSReference` | `WSReferences/` | WS-ссылки | [1c-configuration-spec.md § 6.15](1c-configuration-spec.md#615-wsreference--ws-ссылка) |
@@ -0,0 +1,329 @@
+# Спецификация формата XML пакетов XDTO 1С
+
+Формат: XML-выгрузка конфигурации 1С:Предприятие 8.3 (Конфигуратор → Конфигурация → Выгрузить конфигурацию в файлы).
+Версии формата: `2.17` (платформа 8.3.20–8.3.24), `2.20` (платформа 8.3.27+).
+
+Источники: выгрузки Бухгалтерия предприятия (8.3.24), ERP 2 (8.3.24) — 760 пакетов.
+
+> **Связанные спецификации:**
+> - Корневая структура конфигурации — [1c-configuration-spec.md](1c-configuration-spec.md)
+> - DSL навыков (XSD как формат описания) — [xdto-dsl-spec.md](xdto-dsl-spec.md)
+> - Сводный индекс — [1c-specs-index.md](1c-specs-index.md)
+
+---
+
+## 1. Структура каталогов
+
+```
+XDTOPackages/
+├── ОбменСБанком.xml              # Объект метаданных — 4 свойства, и всё
+├── ОбменСБанком/
+│   └── Ext/
+│       └── Package.bin           # Модель пакета
+└── ...
+```
+
+Регистрация в корневом `Configuration.xml`:
+
+```xml
+<ChildObjects>
+    ...
+    <XDTOPackage>ОбменСБанком</XDTOPackage>
+</ChildObjects>
+```
+
+Ни форм, ни модулей, ни макетов у пакета XDTO нет.
+
+---
+
+## 2. Объект метаданных `<Имя>.xml`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<MetaDataObject xmlns="http://v8.1c.ru/8.3/MDClasses" ... version="2.17">
+    <XDTOPackage uuid="6417d7c8-6436-4907-98eb-44cd7638f3f1">
+        <Properties>
+            <Name>ApdexExport</Name>
+            <Synonym>
+                <v8:item>
+                    <v8:lang>ru</v8:lang>
+                    <v8:content>Apdex export</v8:content>
+                </v8:item>
+            </Synonym>
+            <Comment/>
+            <Namespace>www.v8.1c.ru/ssl/performace-assessment/apdexExport</Namespace>
+        </Properties>
+    </XDTOPackage>
+</MetaDataObject>
+```
+
+| Свойство | Описание |
+|---|---|
+| `Name` | Имя объекта метаданных. Должно быть валидным идентификатором 1С |
+| `Synonym` | Многоязычное представление |
+| `Comment` | Комментарий |
+| `Namespace` | URI целевого пространства имён. Дублирует `targetNamespace` в `Package.bin` |
+
+Других свойств у пакета XDTO нет.
+
+---
+
+## 3. `Ext/Package.bin` — модель пакета
+
+Несмотря на расширение `.bin`, это **текстовый XML**: UTF-8 с BOM, перевод строки CRLF,
+отступ — символы табуляции.
+
+```xml
+<package xmlns="http://v8.1c.ru/8.1/xdto"
+         xmlns:xs="http://www.w3.org/2001/XMLSchema"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         targetNamespace="urn:1C.ru:ClientBankExchange">
+    <property xmlns:d2p1="urn:1C.ru:ClientBankExchange" name="ClientBankExchange" type="d2p1:ClientBankExchange"/>
+    <valueType name="СуммаТип" base="xs:decimal" variety="Atomic" totalDigits="18" fractionDigits="2"/>
+    <objectType name="ClientBankExchange">
+        <property xmlns:d3p1="urn:1C.ru:ClientBankExchange" name="ВерсияФормата" type="d3p1:ВерсияСхемы"/>
+        <property name="Отправитель">
+            <typeDef xsi:type="ValueType" base="xs:string" variety="Atomic" maxLength="160"/>
+        </property>
+    </objectType>
+</package>
+```
+
+### 3.1. Вложенность элементов
+
+```
+package > objectType | valueType | property | import
+objectType > property
+valueType  > enumeration | pattern | typeDef
+property   > typeDef
+typeDef    > property | enumeration | pattern
+```
+
+Всего восемь имён элементов. `typeDef` — анонимный (встроенный) тип; его разновидность
+задаёт `xsi:type` = `ValueType` либо `ObjectType`.
+
+**Порядок элементов верхнего уровня обязателен:**
+
+```
+import* → property* → valueType* → objectType*
+```
+
+Ему удовлетворяют все 760 пакетов корпуса. Нарушение порядка платформа не прощает —
+`db-update` падает с «Ошибка преобразования данных XDTO: Чтение объекта типа
+`{http://v8.1c.ru/8.1/xdto}Package`… Проверка свойства 'property'». Это существенно
+при сборке из XML-схемы, где порядок объявлений верхнего уровня произвольный.
+
+### 3.2. `<package>`
+
+| Атрибут | Значения | Описание |
+|---|---|---|
+| `targetNamespace` | URI | Целевое пространство имён |
+| `elementFormQualified` | `true` \| `false` | Умолчание при отсутствии — `true` |
+| `attributeFormQualified` | `true` \| `false` | Умолчание при отсутствии — `false` |
+
+Порядок атрибутов: `targetNamespace`, `elementFormQualified`, `attributeFormQualified`.
+
+### 3.3. `<import>`
+
+`<import namespace="URI"/>` — объявление зависимости от другого пакета. Разрешается
+по namespace среди пакетов конфигурации; `schemaLocation` в модели XDTO нет.
+
+### 3.4. `<objectType>` и `<typeDef xsi:type="ObjectType">`
+
+| Атрибут | Значения | Описание |
+|---|---|---|
+| `name` | идентификатор | Только у именованного `objectType` |
+| `base` | QName | Базовый тип (наследование) |
+| `open` | `true` \| `false` | Допускает произвольные элементы и атрибуты |
+| `abstract` | `true` \| `false` | Абстрактный тип |
+| `mixed` | `true` \| `false` | Смешанное содержимое |
+| `ordered` | `true` \| `false` | `false` — выбор одного из вариантов (аналог `xs:choice`) |
+| `sequenced` | `true` | Последовательное содержимое |
+
+Порядок атрибутов `objectType`: `name`, `base`, `open`, `abstract`, `mixed`, `ordered`, `sequenced`.
+Порядок атрибутов `typeDef`: `xsi:type`, `base`, `mixed`, `open`, `ordered`, `sequenced`, далее атрибуты простого типа.
+
+### 3.5. `<valueType>` и `<typeDef xsi:type="ValueType">`
+
+| Атрибут | Значения |
+|---|---|
+| `name` | идентификатор (только у именованного `valueType`) |
+| `base` | QName базового типа |
+| `variety` | `Atomic` \| `List` \| `Union` |
+| `itemType` | QName — тип элемента списка (`variety="List"`) |
+| `memberTypes` | список типов объединения (`variety="Union"`) |
+
+Фасеты задаются **атрибутами**, а не дочерними элементами:
+`length`, `minLength`, `maxLength`, `totalDigits`, `fractionDigits`,
+`minInclusive`, `maxInclusive`, `minExclusive`, `maxExclusive`,
+`whiteSpace` (`preserve` \| `collapse`).
+
+Базовый тип может задаваться не атрибутом `base`, а вложенным анонимным `typeDef`
+**без** `xsi:type` — соответствует анонимному `xs:simpleType` внутри `xs:restriction`:
+
+```xml
+<valueType name="INN12Type" variety="Atomic" length="12">
+    <typeDef base="xs:string" variety="Atomic"/>
+    <pattern>[0-9]{12}</pattern>
+</valueType>
+```
+
+Дочерними элементами идут только `<pattern>` и `<enumeration>` — значение в тексте узла:
+
+```xml
+<valueType name="НомерСчетаТип" base="xs:string" variety="Atomic" length="20">
+    <pattern>[0-9]{20}</pattern>
+</valueType>
+```
+
+У `<enumeration>` встречается атрибут `xsi:type` (например `xs:string`), указывающий тип литерала.
+
+### 3.6. `<property>`
+
+| Атрибут | Значения | Описание |
+|---|---|---|
+| `name` | идентификатор | Имя свойства |
+| `ref` | QName | Ссылка на глобальное свойство вместо собственного объявления |
+| `type` | QName | Тип свойства. При отсутствии и `type`, и вложенного `typeDef` — произвольный тип |
+| `lowerBound` | `0` \| `1` | Минимальная кратность. Умолчание при отсутствии — `1` |
+| `upperBound` | число \| `-1` | Максимальная кратность; `-1` — неограниченно. Умолчание — `1` |
+| `nillable` | `true` \| `false` | Допускает `xsi:nil` |
+| `fixed` | значение | Фиксированное значение |
+| `default` | значение | Значение по умолчанию |
+| `form` | `Element` \| `Attribute` \| `Text` | Форма представления в XML. Умолчание — `Element` |
+| `localName` | строка | Исходное XML-имя, если оно не является валидным идентификатором 1С |
+| `qualified` | `true` \| `false` | Переопределение `*FormQualified` для конкретного свойства |
+
+Порядок атрибутов: `name`, `ref`, `type`, `lowerBound`, `upperBound`, `nillable`,
+`fixed`, `default`, `form`, `localName`, `qualified`.
+
+**`form="Text"`** — свойство хранит собственное значение элемента (аналог `xs:simpleContent`).
+Такое свойство платформа всегда называет `__content`:
+
+```xml
+<objectType name="Error">
+    <property name="code" type="xs:NCName" lowerBound="1" form="Attribute"/>
+    <property name="__content" type="xs:string" form="Text"/>
+</objectType>
+```
+
+Наличие `form="Text"` не отменяет флагов самого типа — `mixed`, `sequenced` и прочие
+задаются как обычно:
+
+```xml
+<objectType name="Account" mixed="true" sequenced="true">
+    <property name="bic" type="d3p1:BicType" lowerBound="1" form="Attribute"/>
+    <property name="__content" type="d3p1:AccNumType" form="Text"/>
+</objectType>
+```
+
+**`localName`** — при импорте XML-схемы имя, недопустимое как идентификатор 1С,
+санируется, а оригинал сохраняется:
+
+```xml
+<property name="isFixPlaceResidence_" type="xs:boolean" localName="isFixPlaceResidence "/>
+```
+
+### 3.7. Порядок свойств внутри типа
+
+Свойства с `form="Attribute"` обычно идут перед остальными — так записаны 96.5% типов
+корпуса. Оставшиеся 3.5% содержат произвольное чередование; порядок значим и сохраняется
+платформой как есть.
+
+---
+
+## 4. Схема префиксов пространств имён
+
+Каждая ссылка на тип из пространства имён, отличного от `xs:`/`xsi:`, требует объявления
+префикса вида `dNpM`:
+
+```xml
+<property xmlns:d3p1="urn:1C.ru:ClientBankExchange" name="ВерсияФормата" type="d3p1:ВерсияСхемы"/>
+```
+
+- `N` — глубина узла: `package` = 1, его прямые потомки = 2, свойство внутри `objectType` = 3,
+  свойство внутри `typeDef` = 5, глубже — 7, 9 и т.д.
+- `M` — порядковый номер нового пространства имён, объявляемого на этом узле (с 1).
+
+Префикс объявляется **на первом узле, которому он нужен**; потомки переиспользуют его из
+области видимости, а не объявляют заново:
+
+```xml
+<objectType xmlns:d2p1="…/Permissions/1.0.0.1" name="InternetConnectionBase" base="d2p1:PermissionBase">
+    <property name="Protocol" type="d2p1:NetworkProtocols" lowerBound="0" nillable="true"/>
+</objectType>
+```
+
+Целевое пространство имён самого пакета исключением не является — ссылка на собственный
+тип тоже требует локального объявления.
+
+Частоты по корпусу: `d3p1` — 109 738, `d2p1` — 13 108, `d5p1` — 9 581, далее по убыванию до `d16p1`.
+
+### 4.1. Нотация Кларка в `memberTypes`
+
+Значения `memberTypes` записываются нотацией Кларка `{URI}Локальное`, без префикса
+(125 случаев из 135 в корпусе; остальные — обычные префиксные QName):
+
+```xml
+<valueType xmlns:d2p1="http://v8.1c.ru/8.1/data/core" name="UUID" variety="Union"
+           memberTypes="{http://v8.1c.ru/8.1/data/core}UUID {http://www.w3.org/2001/XMLSchema}base64Binary"/>
+```
+
+Обратите внимание: объявление `xmlns:d2p1` присутствует, хотя в значении не используется —
+пространство имён всё равно проходит через общий механизм выделения префиксов. Если оно уже
+объявлено предком, нового объявления не появляется.
+
+Остальные атрибуты-QName (`type`, `base`, `ref`, `itemType`) всегда префиксные.
+
+### 4.2. Осмысленные префиксы
+
+Изредка вместо сгенерированного `dNpM` встречается содержательный префикс — например
+`dcsset` для настроек компоновки данных:
+
+```xml
+<property xmlns:dcsset="http://v8.1c.ru/8.1/data-composition-system/settings"
+          name="Настройка" type="dcsset:Filter" lowerBound="0"/>
+```
+
+### 4.3. Свойство с `qualified` сериализуется с префиксом
+
+Если у свойства задан `qualified`, платформа пишет и сам тег, и имя атрибута с явным
+префиксом пространства имён модели XDTO (хотя по умолчанию оно и так объявлено как `xmlns=`):
+
+```xml
+<d3p2:property xmlns:d3p1="http://bssys.com/upg/request" xmlns:d3p2="http://v8.1c.ru/8.1/xdto"
+               name="numCheck" type="d3p1:BoolType" lowerBound="0" form="Attribute"
+               d3p2:qualified="false"/>
+```
+
+Префикс для XDTO выделяется последним, после префиксов типов. Такое встречается редко
+(16 узлов на весь корпус) и появляется при импорте XML-схемы, где `form` задан на
+объявлении в unqualified-пакете.
+
+---
+
+## 5. Умолчания записываются непоследовательно
+
+Один и тот же смысл в корпусе встречается в двух написаниях: `nillable="false"` присутствует
+явно 6 899 раз, `objectType open="false"` — 6 раз, `abstract="false"` — 2 раза, явное
+`form="Element"` — 44 раза. Пакеты, полученные импортом XML-схемы, и пакеты, созданные
+руками в Конфигураторе, отличаются стилем.
+
+Практическое следствие: приведение пакета к «каноническому» виду меняет байты реальных
+файлов. Инструменты, которым важен точный round-trip, обязаны сохранять literal-форму.
+
+---
+
+## 6. Тихая деградация в `xs:anyType`
+
+При импорте XML-схемы через Конфигуратор тип из чужого пространства имён, для которого
+в конфигурации нет соответствующего пакета, **молча** заменяется на `xs:anyType` —
+без ошибки и без предупреждения:
+
+```xml
+<!-- в схеме было type="ns2:contact" -->
+<property name="contact" type="xs:anyType"/>
+```
+
+При этом `<import namespace="…"/>` в пакете остаётся. Признак «объявлен импорт, но
+ни один тип из этого пространства имён не используется» — надёжный индикатор проблемы.
@@ -0,0 +1,173 @@
+# Спецификация XDTO DSL — XML Schema как формат описания пакета
+
+Навыки `/xdto-compile` (XSD → пакет) и `/xdto-decompile` (пакет → XSD) используют в качестве
+формата описания **обычную XML-схему**. Отдельного DSL нет: XSD и модель XDTO выражают одно и
+то же, различаясь синтаксисом и умолчаниями, а схема в реальных задачах обычно уже есть —
+прислана контрагентом.
+
+> Формат самих исходников (`Package.bin`, объект метаданных, схема префиксов) —
+> [1c-xdto-spec.md](1c-xdto-spec.md).
+
+## Пример
+
+```xml
+<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` | те же имена |
+| `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`.**
+
+```xml
+<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:type` | `xs:enumeration` | `xsi:type` литерала перечисления |
+| `xdto:prefix` | объявление | осмысленный префикс пространства имён вместо генерируемого `dNpM` (например `dcsset`) |
+
+### Что выводится само
+
+Аннотация нужна только там, где вывод невозможен:
+
+| Свойство 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`.
+
+```xml
+<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` только у локальных объявлений.
+  Такие файлы читаются; сам навык пишет корректно.
+- **`xs:include`** игнорируется (в модели XDTO соответствия нет).
+- Порядок объявлений верхнего уровня произвольный и сохраняется как есть.