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

«Сформируй платёжное поручение в формате клиент-банка и выгрузи в файл»

«Напиши обработку выгрузки заказов по нашему обмену с маркетплейсом»

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

Выводится это уже в терминах 1С — Строка(6), Число(18,2), [обязательный], — поэтому переводить xs:decimal и lowerBound="0" в голове не приходится. Если тип большой, помогает срез только обязательных свойств: получается готовый скелет заполнения.

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

«Разбери входящий файл ЕГАИС и создай по нему документы»

«Какому типу соответствует корень этого XML?»

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

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

«Контрагент прислал схему обмена заказами, добавь её в конфигурацию»

«Нужен пакет XDTO по вот этой XSD от ФСС»

Пакет собирается по схеме и сразу регистрируется в конфигурации.

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

Если схема ссылается на чужое пространство имён через <xs:import>, сначала нужен пакет-зависимость. Иначе платформа откажется принимать конфигурацию либо молча подменит тип на «произвольный», и всплывёт это уже в рантайме.

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

«Добавь в платёжное поручение необязательный комментарий, не длиннее 200 символов»

«Убери из обмена устаревшее поле СтарыйКод»

«Добавь в перечисление видов документов значение Инкассо»

Точечная правка не требует читать схему целиком — для больших пакетов вроде EnterpriseData это единственный практичный путь. После правки автоматически запускается проверка.

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

Если переработка широкая — «перепиши обмен под новую версию формата» — схема выгружается целиком, правится и собирается обратно. Пара выгрузка-сборка замыкается без потерь, включая имя, синоним и комментарий объекта метаданных.

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

«Сделай версию 2.0 нашего обмена, старая должна продолжать работать»

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

Если же надо сменить namespace у существующего пакета, агент перепишет все внутренние ссылки и перечислит пакеты, которые импортируют старый — но менять их не станет, потому что при версионировании это было бы ошибкой.

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

«Выгрузи схему нашего обмена, отправлю партнёру»

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

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

«Обращение к Смена.Сотрудник возвращает что-то бесструктурное, разберись»

«Пакет вроде загрузился, а обмен не работает»

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

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

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

Точный синтаксис параметров каждого навыка — в его SKILL.md по ссылкам выше.

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

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