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.

Если же надо сменить 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