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 есть в конфигурации src?»

«Что внутри пакета ОбменСБанком — какие типы и с чего начинать чтение?»

Обычный первый шаг, когда формат чужой или давно не открывался. Список пакетов показывает имя, пространство имён и число типов; обзор пакета — типы и точки входа.

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

«Сформируй платёжное поручение по пакету ОбменСБанком и запиши в out.xml»

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

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

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

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

«Разбери in/egais-ttn.xml по пакету ЕГАИС3 — с какого типа начинать?»

«Какие точки входа у пакета ЕГАИС3?»

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

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

«Контрагент прислал schemas/orders.xsd — добавь пакет в конфигурацию, исходники в src»

«Собери пакет по schemas/fss-person.xsd, имя FSS_Person_01»

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

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

Если схема ссылается на чужое пространство имён через <xs:import>, сначала нужен пакет-зависимость: платформа отвергнет конфигурацию, где импортируемого пакета нет. Об этом скажут ещё на сборке — чинить дешевле там, чем на /db-update. Исключение — пространства имён самой платформы (http://www.w3.org/2001/XMLSchema, http://v8.1c.ru/8.1/data/core и подобные): их пакетами объявлять не нужно.

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

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

«Убери свойство СтарыйКод у типа Документ в пакете Обмен»

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

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

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

«Кто ссылается на тип Адрес из пакета КонтактнаяИнформация?»

Ответ — список типов и пакетов, включая те, что ссылаются через границу пакета.

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

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

«Сделай из пакета Обмен версию 2: новый пакет ОбменV2 с namespace urn:…:v2, старый не трогай»

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

1. /xdto-decompile исходного пакета в файл схемы;
2. в схеме поменять targetNamespace — и связанное с ним объявление xmlns, которым внутренние ссылки пользуются как префиксом;
3. /xdto-compile этой схемы с -Name нового пакета (имя и синоним задаются флагами, править их внутри схемы не нужно).

Внутренние ссылки при этом переводятся на новый namespace целиком, импорты чужих пакетов сохраняются, исходный пакет не меняется.

Менять targetNamespace заменой всех вхождений строки — плохая идея: если пакет импортирует пространство имён, у которого старый URI является префиксом (urn:example:exchange и urn:example:exchange:legacy), заменится и оно.

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

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

«Выгрузи схему пакета Обмен в schemas/exchange.xsd, отправлю партнёру»

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

Проверить перед загрузкой в базу

«Проверь пакет Обмен перед загрузкой в базу»

«Я правил Package.bin руками — проверь, что платформа его примет»

Проверка ловит то, на чём /db-update отказывается принимать конфигурацию: импорт пакета, которого в конфигурации нет; ссылку на несуществующий тип или необъявленный префикс; нарушенный порядок элементов верхнего уровня; расхождение объекта метаданных с моделью; отсутствие пакета в Configuration.xml. Дешевле поймать здесь, чем в отказе загрузки. После правки через /xdto-edit проверка запускается сама.

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

«Пакет ФСС загрузился, но обращение к Смена.Сотрудник возвращает что-то бесструктурное — разберись»

Такой симптом почти всегда означает, что тип не разрешился и стал «произвольным». Платформа об этом молчит: при импорте 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