Как создавать XSD-файлы#
Для чего нужен XSD#
Так как общение внешнего интеграционного сервиса с API регламентируется правилами и требованиями, описываемыми с помощью XSD-схемы, то на этапе внедрения требуется обеспечить наличие всех необходимых XSD-схем, покрывающих потребности решения задач внешнего интеграционного сервиса.
Так, например, для интеграции с порталом услуг одна XSD-схема описывает предметную модель одной услуги (правила создания и заполнения всех необходимых объектов, а также полей цепочки «Заявление – Услуга – Результат услуги») в разрезе модели данных Системы.
Для одной бизнес-операции создается одна XSD-схема. В рамках одного обращения к API создается блок связанных объектов с одним корневым. Для создания нескольких несвязанных объектов необходимо сделать несколько обращений к API. Количество связей и уровней вложенности у корневого объекта не ограничено.
XSD-схема используется только для создания (редактирования) объектов в системе. Также схема содержит правила заполнения пакета, передаваемого в рамках выполнения бизнес-задачи внешней интеграционной системы.
XSD-схему необходимо разместить в системе через приложение JasperAPI и передается клиенту. Клиент может получить XSD-схему, запросив её у API отдельным методом XSD/{businessScope}.
Правила создания#
В XSD-схеме задаются:
структура объектов, которые будут создаваться и редактироваться клиентом;
методы заполнения полей объектов;
используемые справочные значения;
все алиасы и наименования схем проекта, для которых действует каждая XSD-схема.
Имя файла XSD-схемы должно отражать действие, которое необходимо выполнить внешнему интеграционному сервису для решения своей бизнес-задачи. Например, NewApplicationGPZU – новое заявление на получение услуги по выдаче ГПЗУ. Важно задать понятное и уникальное наименование файла XSD-схемы (например, Gpzu), так как клиент будет формировать запрос, где в Url указывается наименование этого файла XSD-схемы.
Синтаксис XSD-схемы четкий и структурированный. К нему много гайдов и туториалов, как и ответов на конкретно задаваемые вопросы. Кому-то проще писать текстом, кому-то – строить диаграммы (текстовое описание этой схемы тогда пишется автоматически за вас).
Для этого рекомендуется использовать десктоп редактор «Oxygen XML Editor». Приложение платное, но к нему есть триальные версии на 30 дней. Более того, для тиражирования XSD-схем на другие услуги, достаточно использовать созданный пример (См. Примеры XSD-схем).
Что важно знать и помнить при создании XSD-схемы:
Понадобятся следующие компоненты и композиторы:
element;
attribute;
complex type;
sequence;
choice;
редко – all.
Это не ограничения, а лишь основной перечень. Можно при необходимости использовать и другие, лишь бы общие правила построения XSD-схемы были соблюдены.
Хорошим тоном считается задавать аннотацию к элементу и/или его типу.
Название элементов – строго алиасы объектов и связей в Системе.
Название комплексного типа соответствует названию самого элемента с приставкой -Type.
В типе schemeType должны быть перечислены все алиасы и наименования схем проекта, для которого готовятся XSD-схемы. Иначе, интеграционный сервис не сможет использовать доступные методы API.
Важно соблюдать правила формирования XSD-схема – четкий состав и порядок использования атрибута «operation». В данном атрибуте задаются фиксированные значения типов операций с каждым из объектов Системы:
для справочников – атрибут find, т.к. значения предоставляются на просмотр, следовательно, в системе может выполняться только их поиск;
для субъектов можно выполнять операцию find-create, когда в первую очередь выполняется поиск по ключевым полям, в противном случае – создается новый объект;
если выполняется поиск субъекта или иного объекта, то элементы, по которому выполняется этот поиск (например, серия и номер паспорта), должны быть определены общим комплексным типом KeyFieldType, value которого задается true. Это значит, что именно по нему будет выполнен поиск;
для поиска, например, справочного значения по наименованию или алиасу, элементы должны быть определены общими комплексными типами EqTextType/EqDateType, которые указывают на равенство заданному значению;
наличие простого элемента Fields для каждого сложного – обязательно;
допустимые для использования интеграционным сервисом справочные значения (например, значения для справочника «Виды заявлений» для ГПЗУ должен быть только один - соответствующий) также задаются в XSD-схемах.
Таким образом, атрибут «operation» может принимать следующие значения:
set – установить указанное значение в поле объекта,
ref – установить связь с другим объектом,
create – создание объекта в системе,
find – поиск объекта в системе,
find-create – выполнить поиск объекта и создать новый, если нужного не найдено,
eq – используется при поиске и использовании значения объекта, созданного в системе ранее.
Если создается элемент, у которого в метаданных имеется ссылка на LV и из нее необходимо использовать только один LVI, то элемент называется по алиасу связи, а внутри него создается элемент сразу с алиасом ссылочного объекта (то есть LT, а не алиас LVI).
Итого, если в XSD-схемах будут неверно прописаны алиасы (названия элементов) объектов или каких-то значений, то такой объект не будет разложен (создан или найден) в систему. Если же будет неверно указана структура, которая в дальнейшем конвертируется в дефолтную структуру iaspackage, то возникнет ошибка при валидации.
Примеры XSD-схем#
Создание объекта#
Пример описания создания объекта Заявление (DocApplication) с двумя справочными полями: Статус заявления (StateApplication) и Вид заявления (ViewLetter):
<xs:element name="DocApplication" type="DocApplicationType">
<xs:annotation>
<xs:documentation>Заявление</xs:documentation>
</xs:annotation>
</xs:element>
<xs:complexType name="DocApplicationType">
<xs:sequence>
<xs:element name="Fields" type="DocApplicationFieldsType">
<xs:annotation>
<xs:documentation>Параметры заявления</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
<xs:attribute fixed="create" name="operation"/>
</xs:complexType>
<xs:complexType name="DocApplicationFieldsType">
<xs:sequence>
<xs:element name="StateApplication" type="StateApplicationType">
<xs:annotation>
<xs:documentation>Статус заявления</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="ViewLetter" type="ViewLetterType">
<xs:annotation>
<xs:documentation>Вид заявления</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
Описание поля простого типа (строка, число, дата)#
Пример описания числового поля NumEPGU, строкового поля Note и даты EpguDate:
<xs:complexType name="DocApplicationFieldsType">
<xs:sequence>
<xs:element name="NumEPGU" type="SetIntType">
<xs:annotation>
<xs:documentation>Номер</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="EpguDate" type="SetDateType">
<xs:annotation>
<xs:documentation>Дата</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="Note" type="SetTextType">
<xs:annotation>
<xs:documentation>Примечание</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="SetIntType">
<xs:attribute name="operation" type="xs:string" fixed="set" use="required"/>
<xs:attribute name="value" type="xs:integer" use="required"/>
</xs:complexType>
<xs:complexType name="SetDateType">
<xs:attribute name="operation" type="xs:string" fixed="set" use="required"/>
<xs:attribute name="value" type="xs:date" use="required"/>
</xs:complexType>
<xs:complexType name="SetTextType">
<xs:attribute fixed="set" name="operation" type="xs:string" use="required"/>
<xs:attribute name="value" type="xs:string" use="required"/>
</xs:complexType>
Описание справочного поля#
Пример описания справочного поля Форма передачи результата (ViewResult), ссылающегося на справочник DocRefFormOfTransfer:
<xs:complexType name="DocApplicationFieldsType">
<xs:sequence>
<xs:element name="ViewResult" type="ViewResultType" minOccurs="0">
<xs:annotation>
<xs:documentation>Форма передачи результата</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ViewResultType">
<xs:sequence>
<xs:element name="DocRefFormOfTransfer" type="DocRefFormOfTransferType"/>
</xs:sequence>
<xs:attribute name="operation" type="xs:string" fixed="set" use="required"/>
</xs:complexType>
<xs:complexType name="DocRefFormOfTransferType">
<xs:sequence>
<xs:element name="Fields">
<xs:complexType>
<xs:element minOccurs="1" name="Alias">
<xs:complexType>
<xs:attribute fixed="eq" name="operation" type="xs:string" use="required"/>
<xs:attribute name="value" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="DocRefFormOfTransfer_186"/>
<xs:enumeration value="DocRefFormOfTransfer_187"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute fixed="find" name="operation" type="xs:string" use="required"/>
</xs:complexType>
В поле может быть выбрано значение, найденное по полю Alias справочника. В XSD-схеме задано ограничение в виде перечислений справочных значений, доступных к использованию: “DocRefFormOfTransfer_186”, “DocRefFormOfTransfer_187”. Тот же пример с возможностью устанавливать значение справочника по любому из двух полей (Alias и Name):
<xs:complexType name="DocApplicationFieldsType">
<xs:sequence>
<xs:element name="ViewResult" type="ViewResultType" minOccurs="0">
<xs:annotation>
<xs:documentation>Форма передачи результата</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ViewResultType">
<xs:sequence>
<xs:element name="DocRefFormOfTransfer" type="DocRefFormOfTransferType"/>
</xs:sequence>
<xs:attribute name="operation" type="xs:string" fixed="set" use="required"/>
</xs:complexType>
<xs:complexType name="DocRefFormOfTransferType">
<xs:sequence>
<xs:element name="Fields">
<xs:complexType>
<xs:choice>
<xs:element minOccurs="1" name="Alias">
<xs:complexType>
<xs:attribute fixed="eq" name="operation" type="xs:string" use="required"/>
<xs:attribute name="value" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="DocRefFormOfTransfer_186"/>
<xs:enumeration value="DocRefFormOfTransfer_187"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element minOccurs="1" name="Name">
<xs:complexType>
<xs:attribute fixed="eq" name="operation" type="xs:string" use="required"/>
<xs:attribute name="value" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Бумажная"/>
<xs:enumeration value="Электронная"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
</xs:choice>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute fixed="find" name="operation" type="xs:string" use="required"/>
</xs:complexType>
Описание ссылочного поля#
Пример описания ссылочного поля Zu, которое ссылается на объект GknParcel и устанавливается по кадастровому номеру (KN):
<xs:complexType name="DocApplicationFieldsType">
<xs:sequence>
<xs:element name="Zu" type="ZuType" minOccurs="0">
<xs:annotation>
<xs:documentation>Земельный участок</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ZuType">
<xs:sequence>
<xs:element name="GknParcel" type="GknParcelType"/>
</xs:sequence>
<xs:attribute name="operation" type="xs:string" fixed="set" use="required"/>
</xs:complexType>
<xs:complexType name="GknParcelType">
<xs:sequence>
<xs:element name="Fields">
<xs:complexType>
<xs:element minOccurs="1" name="KN">
<xs:complexType>
<xs:attribute fixed="eq" name="operation" type="xs:string" use="required"/>
<xs:attribute name="value" use="required"/>
</xs:complexType>
</xs:element>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute fixed="find" name="operation" type="xs:string" use="required"/>
</xs:complexType>
Описание ММ-связи#
Пример описания ММ-связи между Заявлением и Услугой «Выдача ГПЗУ» (создаваемой в рамках этого же дата-контракта):
<xs:complexType name="DocApplicationType">
<xs:sequence>
<xs:element name="Fields" type="DocApplicationFieldsType">
<xs:annotation>
<xs:documentation>Параметры заявления</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
<xs:attribute fixed="create" name="operation"/>
</xs:complexType>
<xs:complexType name="DocApplicationFieldsType">
<xs:sequence>
<xs:element name="ServiceForApplicationRelation" type="ServiceForApplicationRelationType">
<xs:annotation>
<xs:documentation>Связь с услугой</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ServiceForApplicationRelationType">
<xs:sequence>
<xs:element name="WfServiceGPZU" type="WfServiceGPZUType">
<xs:annotation>
<xs:documentation>Услуга: Выдача ГПЗУ</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
<xs:attribute fixed="ref" name="operation" type="xs:string" use="required"/>
</xs:complexType>
<xs:complexType name="WfServiceGPZUType">
<xs:sequence>
<xs:element name="Fields">
<xs:complexType>
<xs:sequence>
<xs:element name="ProcessingStage" type="ProcessingStageType">
<xs:annotation>
<xs:documentation>Статус услуги</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="TransferMetodResult" type="WaySendType">
<xs:annotation>
<xs:documentation>Способ передачи результата</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="ViewResult" type="ViewResultType" minOccurs="0">
<xs:annotation>
<xs:documentation>Форма передачи результата</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="DocRelGpzuResult" type="DocRelGpzuResultType">
<xs:annotation>
<xs:documentation>Связь с результатом услуги</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute fixed="create" name="operation" type="xs:string" use="required"/>
</xs:complexType>
Пример описания ММ-связи между Заявлением и Услугой «Выдача ГПЗУ» (уже существующей на момент выполнения полученного пакета XML, поиск которой выполняется по полю «key»):
<xs:complexType name="DocApplicationType">
<xs:sequence>
<xs:element name="Fields" type="DocApplicationFieldsType">
<xs:annotation>
<xs:documentation>Параметры заявления</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
<xs:attribute fixed="create" name="operation"/>
</xs:complexType>
<xs:complexType name="DocApplicationFieldsType">
<xs:sequence>
<xs:element name="ServiceForApplicationRelation" type="ServiceForApplicationRelationType">
<xs:annotation>
<xs:documentation>Связь с услугой</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ServiceForApplicationRelationType">
<xs:sequence>
<xs:element name="WfServiceGPZU" type="WfServiceGPZUType">
<xs:annotation>
<xs:documentation>Услуга: Выдача ГПЗУ</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
<xs:attribute fixed="ref" name="operation" type="xs:string" use="required"/>
</xs:complexType>
<xs:complexType name="WfServiceGPZUType">
<xs:sequence>
<xs:element name="Fields">
<xs:complexType>
<xs:sequence>
<xs:element name="key" type="EqIntegerType"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute fixed="find" name="operation" type="xs:string" use="required"/>
</xs:complexType>
<xs:complexType name="EqTextType">
<xs:attribute fixed="eq" name="operation" type="xs:string" use="required"/>
<xs:attribute name="value" type="xs:string" use="required"/>
</xs:complexType>
<xs:complexType name="EqDateType">
<xs:attribute fixed="eq" name="operation" type="xs:string" use="required"/>
<xs:attribute name="value" type="xs:date" use="required"/>
</xs:complexType>
<xs:complexType name="EqIntegerType">
<xs:attribute fixed="eq" name="operation" type="xs:string" use="required"/>
<xs:attribute name="value" type="xs:date" use="required"/>
</xs:complexType>
Описание геометрии#
Пример описания создания объекта Набор данных (DmdInfoSet). На уровне с <xs:element name= «Fields»> создать <xs:element name= «Geometry» type= «GeometryType»> для описания объекта.
<xs:complexType name="InfoSetKeyType">
<xs:sequence>
<xs:element minOccurs="1" name="DmdInfoSet">
<xs:annotation>
<xs:documentation>Набор данных</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="Fields">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="1" name="Name" type="SetTextType">
<xs:annotation>
<xs:documentation>Наименование</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="Geometry" type="GeometryType">
<xs:annotation>
<xs:documentation>Геометрия</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
<xs:attribute fixed="create" name="operation" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute fixed="ref" name="operation" type="xs:string" use="required"/>
<xs:attribute fixed="true" name="clear" type="xs:boolean" use="required"/>
<xs:attribute fixed="true" name="updateField" type="xs:boolean" use="required"/>
</xs:complexType>
Описание применения GeometryType. Атрибуты являются обязательными и неизменными.
<xs:complexType name="GeometryType">
<xs:sequence>
<xs:element name="Geojson" maxOccurs="1" type="SetGeojsonType" minOccurs="1">
<xs:annotation>
<xs:documentation xml:lang="ru">Геометрия в geojson формате</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="Srid" maxOccurs="1" type="SetSridType" minOccurs="1">
<xs:annotation>
<xs:documentation xml:lang="ru">Наименование системы координат</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="SetGeojsonType">
<xs:attribute name="operation" type="xs:string" fixed="geojson" use="required"/>
<xs:attribute name="value" type="xs:string" use="required"/>
</xs:complexType>
<xs:complexType name="SetSridType">
<xs:attribute name="operation" type="xs:string" fixed="srid" use="required"/>
<xs:attribute name="value" type="xs:string" use="required"/>
</xs:complexType>
</xs:schema>
Пример описания геометрии в XML:
<DmdInfoSet operation="create">
<Fields>
<Name operation="set" value="testInfoset"/>
</Fields>
<Geometry>
<Geojson operation="geojson" value ='{"type":"Polygon","coordinates":[[[49.054568543,55.589910442],[49.0546574,55.58998857],[49.05496849,55.590417854],[49.055381262,55.591152506],[49.055735308,55.591788366],[49.055741659,55.591799143],[49.055741793,55.592038063],[49.055724393,55.592121599],[49.055559904,55.592952459],[49.055388411,55.593464641],[49.055323987,55.593704741],[49.055279824,55.593869028],[49.055222048,55.594083707],[49.055642694,55.594074471],[49.05610538,55.594076722],[49.056113311,55.594076721],[49.056098739,55.594113549],[49.056468986,55.594174379],[49.05642923,55.594271481],[49.056834367,55.594319458],[49.056808725,55.59441081],[49.057181652,55.594437685],[49.057184658,55.594424391],[49.057500323,55.594449928],[49.057610132,55.594004042],[49.057631334,55.593917991],[49.057752532,55.593425576],[49.05775981,55.593395755],[49.056855719,55.592605248],[49.056819869,55.592598608],[49.056820027,55.592597979],[49.056296397,55.5925017],[49.055788974,55.592450596],[49.055824306,55.59210182],[49.05583696,55.592041639],[49.055836818,55.591790144],[49.055673288,55.591496463],[49.055473244,55.591136322],[49.055057297,55.590399875],[49.054743031,55.589963406],[49.054722403,55.589944547],[49.054568543,55.589910442]]]}'/>
<Srid operation="srid" value ="мск 1"/>
</Geometry>
</DmdInfoSet>