cc-1c-skills/docs/xdto-guide.md

Работа с пакетами XDTO

Пакет XDTO описывает XML-формат: какие есть типы, из каких свойств состоят, что обязательно. По нему платформа умеет читать и писать XML — через ФабрикаXDTO. Встречается везде, где 1С обменивается данными наружу: ЭДО, ЕГАИС, ВЕТИС, ФСС, клиент-банк, веб-сервисы, EnterpriseData.

Навыки

Навык	Задача
/xdto-info	Что в пакете и как заполнять тип — в терминах 1С
/xdto-compile	Собрать пакет по XML-схеме
/xdto-decompile	Выгрузить пакет в XML-схему
/xdto-edit	Точечно поправить существующий пакет
/xdto-validate	Проверить перед загрузкой в базу

Формат описания — обычная XML-схема, своего DSL нет. Схема в реальных задачах обычно уже есть: её присылает контрагент или публикует регулятор.

Сценарии

Написать код, который заполняет объект XDTO

Самая частая задача. Нужны namespace, имя типа и состав свойств — какой тип значения присваивать, что обязательно, где создавать вложенный объект.

# известны namespace и тип (например, из строки ФабрикаXDTO.Тип(...) в чужом коде)
/xdto-info src -Namespace "urn:1C.ru:ClientBankExchange" -Name ПлатежныйДокумент -Depth 2

# только обязательное — скелет для заполнения
/xdto-info src -Namespace "urn:1C.ru:ClientBankExchange" -Name ПлатежныйДокумент -RequiredOnly

Вывод даёт типы уже в нотации 1С (Строка(6), Число(18,2)), помечает обязательные свойства и коллекции, перечисляет допустимые значения и подсказывает вызовы фабрики. Читать Package.bin при этом не нужно.

Если имя пакета неизвестно, а тип известен — -Name по корню исходников найдёт его по всем пакетам конфигурации.

Разобрать входящий XML

Нужно понять, какому типу соответствует корень документа. Это точки входа — глобальные объявления пакета:

/xdto-info src -Namespace "urn:partner:orders"

Дальше по имени типа — состав свойств, как в предыдущем сценарии.

Добавить пакет по схеме контрагента

/xdto-compile -XsdPath partner.xsd -OutputDir src -Name ЗаказыКонтрагента
/xdto-validate src/XDTOPackages/ЗаказыКонтрагента

Читай предупреждения компилятора. XML Schema выразительнее модели XDTO, и часть конструкций переносится приближённо: вложенные xs:choice уплощаются, xs:all становится последовательностью, кратность на частице отбрасывается. Навык печатает, что именно упростилось; если упрощение недопустимо — меняй схему, а не игнорируй.

Схема ссылается на чужой namespace через <xs:import> — сначала собери пакет-зависимость. Иначе платформа при загрузке молча подменит тип на xs:anyType, и обнаружится это только в рантайме.

Поправить существующий пакет

Точечно — /xdto-edit, схему целиком читать не нужно:

/xdto-edit src/XDTOPackages/ОбменСБанком -Operation add-property -Target "ПлатежныйДокумент" `
           -Value '<xs:element name="Комментарий" type="xs:string" minOccurs="0"/>'

Многострочный фрагмент передавай файлом: -Value "@frag.xsd".

Перед правкой существующего типа полезно посмотреть, кого она затронет:

/xdto-info src -Mode used-by -Name СуммаТип

Если переработка широкая или сначала надо разобраться в схеме — выгрузи её целиком:

/xdto-decompile src/XDTOPackages/ОбменСБанком -OutFile bank.xsd
# правка bank.xsd
/xdto-compile -XsdPath bank.xsd -OutputDir src -Name ОбменСБанком -Force

Пара замыкается без потерь, включая имя, синоним и комментарий объекта метаданных.

Новая версия пакета

Типовой приём в обменах: рядом со старым пакетом появляется новый с другим пространством имён (EnterpriseData_1_19 → _1_20). Старые потребители продолжают смотреть на прежний namespace.

/xdto-decompile src/XDTOPackages/Обмен_1_0 -OutFile v2.xsd
# правка targetNamespace и содержимого в v2.xsd
/xdto-compile -XsdPath v2.xsd -OutputDir src -Name Обмен_2_0

Если же нужно сменить namespace у существующего пакета — /xdto-edit -Operation set-namespace. Он перепишет все внутренние ссылки и перечислит пакеты, которые импортируют старый namespace, но менять их не станет.

Отдать схему контрагенту

/xdto-decompile src/XDTOPackages/ОбменСБанком -OutFile bank.xsd

Схема валидна и ничего не теряет. Штатный «Экспорт XML-схемы» в Конфигураторе для этого хуже: он теряет nillable у свойств-атрибутов.

Разобраться, почему обмен ведёт себя странно

Симптом «свойство возвращает что-то бесструктурное» почти всегда означает, что тип не разрешился и стал xs:anyType:

/xdto-validate src/XDTOPackages/ПодозрительныйПакет -Detailed

Платформа такие вещи не диагностирует: при импорте XML-схемы неразрешённый чужой тип заменяется молча, пакет выглядит загруженным. Валидатор называет и симптом, и причину — объявленный, но неиспользуемый <import>.

Структура файлов

XDTOPackages/
├── ОбменСБанком.xml            объект метаданных: Name, Synonym, Comment, Namespace
└── ОбменСБанком/
    └── Ext/
        └── Package.bin         модель пакета (текстовый XML, несмотря на расширение)

Плюс регистрация в корневом Configuration.xml — без неё платформа пакет не увидит.

Рабочий цикл

1. /xdto-info — понять, что есть
2. /xdto-compile или /xdto-edit — изменить
3. /xdto-validate — проверить до загрузки
4. /db-load-xml + /db-update — применить

Спецификации

• Формат исходников — 1c-xdto-spec.md
• XML Schema как формат описания, таблица соответствий и аннотации xdto: — xdto-dsl-spec.md