Создание xsd-файла#

Для чего нужен xsd#

Так как общение внешнего интеграционного сервиса с API Jasper регламентируется правилами и требованиями, описываемыми с помощью xsd-схемы, то на этапе внедрения требуется обеспечить наличие всех необходимых xsd-схем.

Xsd-схема задаёт ограничения, структуру и правила заполнения xml-пакета, передаваемого в рамках выполнения бизнес-задачи внешнего интеграционного сервиса.

Так, например, для интеграции с порталом услуг одна xsd-схема описывает предметную модель одной услуги (правила создания и заполнения всех необходимых объектов, а также полей цепочки «Заявление – Услуга – Результат услуги») в разрезе модели данных Системы.

Для одной бизнес-операции создаётся одна xsd-схема.

Xsd используется только для создания/редактирования объектов в Системе и содержит схему проекта.

Правила создания#

Xsd-схемы создаются вручную. Синтаксис xsd-схемы чёткий и структурированный. Работать с синтаксисом xsd можно как в виде диаграмм (например, с помощью редактора «Oxygen XML Editor»), так и в виде текстового описания (например, в «Notepad++»).

Xsd-схемы типичны, поэтому на основе уже существующих схем можно создавать новые для других объектов Системы. Для тиражирования xsd для других бизнес-задач достаточно использовать созданный пример.

Важно задать понятное и уникальное наименование файла xsd, так как клиент будет формировать запрос, где в URL указывается наименование этого файла. Имя файла xsd должно отражать действие, которое необходимо выполнить внешнему интеграционному сервису для решения своей бизнес-задачи (например, NewApplicationGPZU – новое заявление на получение услуги по выдаче ГПЗУ).

В xsd-схеме задаются:

  • структура объектов, которые будут создаваться и редактироваться клиентом;

  • методы заполнения полей объектов;

  • используемые справочные значения;

  • все алиасы и наименования схем проекта, для которых действует каждая xsd.

Основные правила создания xsd-схем:

  1. Используйте компоненты:

  • element;

  • attribute;

  • complex type;

  • sequence;

  • choice;

  • all (редко).

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

  1. Задайте аннотацию к элементу и/или его типу.

  2. В качестве названия элементов обязательно укажите алиасы объектов и связей в Системе.

  3. Формируйте название комплексного типа по названию самого элемента с приставкой Type.

  4. В типе schemeType перечислите все псевдонимы и наименования схем проектов, для которых готовится xsd. Иначе интеграционный сервис не сможет использовать доступные методы API Jasper.

  5. Соблюдайте правила формирования xsd: чёткий состав и порядок использования атрибута operation.

Атрибут operation может принимать значения:

  • set – установить указанное значение в поле объекта;

  • ref – установить связь с другим объектом;

  • create – создать объект в Системе;

  • clear – очистка связи в ссылочном поле;

  • find – найти объект в Системе;

  • find-create – выполнить поиск объекта и создать новый, если нужный не найден;

  • eq – проверить на равенство значение объекта в Системе;

  • edit-existing – отредактировать значение существующего объекта в Системе.

В атрибуте operation задаются фиксированные значения типов операций с каждым из объектов Системы:

  • для справочников используется только операция find, так как справочные значения предоставляются клиенту на просмотр, то в Системе может выполняться только их поиск. Для поиска, например, справочного значения по наименованию или алиасу, элементы должны быть определены общим комплексным типом EqTextType, который указывает на равенство заданному значению;

  • для остальных объектов можно выполнять операцию find-create, когда в первую очередь выполняется поиск по ключевым полям и, при отсутствии в Системе субъекта, создаётся новый. Если выполняется поиск субъекта или иного объекта, то элементы, по которым выполняется этот поиск (например, серия и номер паспорта), должны быть определены общим комплексным типом KeyFieldType, value которого задаётся значением "true". Это значит, что именно по нему будет выполнен поиск.

  1. Проверьте наличие обязательного связующего элемента Fields для каждого сложного элемента.

  2. Задайте в xsd допустимые для использования интеграционным сервисом справочные значения, например, значение «Новое» для поля [Статус] в карточке заявления.

  3. Если создаётся элемент, у которого в метаданных имеется ссылка на LV, и из неё необходимо использовать только один LVI, то элемент называется по алиасу связи, а внутри него создаётся элемент сразу с алиасом ссылочного объекта (то есть LT, а не алиас LVI).

../../_images/metadannye.png ../../_images/metadannye2.png
  1. При создании xsd-схемы поставьте тип KeyFieldType на поля [ИНН], [ОГРН], [СНИЛС], [ОГРНИП]. Если не проставить тип KeyFieldType, то при наличии субъекта в Системе с таким же значением в указанных полях возникнет ошибка.

Важно

Необходимо учитывать, что:

  • для юридического лица в Системе не может быть 2 субъектов в статусе «Актуальный» с одинаковыми значениями ИНН, ОГРН;

  • для физического лица/ИП в Системе не может быть 2 субъектов в статусе «Актуальный» с одинаковыми значениями СНИЛС/ОГРНИП.

Если в xsd будут неверно прописаны названия элементов (алиасы объектов) или каких-то значений, то такой объект не будет создан или найден в Системе. Если же будет неверно указана структура, которая в дальнейшем конвертируется в дефолтную структуру iaspackage, то возникнет ошибка при валидации.

Структура xsd#

Структура xsd зависит от модели данных того типа объекта, к которому будет обращаться внешняя информационная система в xml-запросе, а также от той информации, которую в рамках этой модели данных собирается создавать клиент в Geometa.

При создании xsd-схемы важно понимать принципы организации метаданных для целевого типа объекта и структуру связей в карточке этого типа объекта на всех уровнях вложенности.

В общем виде xsd-схема включает в себя:

Основные теги xsd-схемы#

<xs:schema> - определяет корневой элемент.

<xs:element name="" type=""> - объявляет элемент.
    name - алиас типа объекта в модели данных Системы,
    type - определяет либо имя встроенного типа данных, либо имя элемента simpleType или complexType.

<xs:annotation> - определяет заметку.

<xs:documentation> - задаёт сведения, которые читают или используют пользователи в annotation.

<xs:complexType name=""> - объявляет сложный тип, определяющий набор атрибутов и содержимое элемента.
    name - наименование комплексного типа формируется по названию самого элемента с приставкой "Type" (например: name="DocApplicationType"), либо по наименованию функции с приставкой "Type" (например: name="EqDateType").

<xs:sequence> - требует, чтобы элементы группы появлялись в содержащем их элементе в указанной последовательности.

<xs:choice> - позволяет присутствовать в элементе-контейнере единственному элементу выбранной группы.

<xs:all> - позволяет элементам группы появляться (или не появляться) в содержащем элементе в любом порядке.

<xs:attribute name="" type="" fixed="" use=""/> - объявляет атрибут.
    name - определяет имя атрибута.
    type - необязательный. Определяет встроенный тип данных или простой тип. Атрибут type можно использовать в том случае, если контент не содержит элемент simpleType.
    fixed - необязательный. Определяет фиксированное значение атрибута.
    fixed="find" - найти объект в Системе;
    fixed="find-create" - выполнить поиск объекта и создать новый, если нужного не найдено;
    fixed="create" - создать объект в Системе;
    fixed="set" - установить указанное значение в поле объекта;
    fixed="eq" - проверить на равенство значение объекта в Системе;
    fixed="ref" - установить связь с другим объектом;
    fixed="true" - признак обязательности выполнения операции;
    use - (необязательный) определяет способ использования атрибута. Может принимать следующие значения:
    optional - атрибут не обязателен (значение по умолчанию);
    prohibited - атрибут запрещён для использования;
    required - атрибут обязателен;

<xs:simpleType> - объявляет простой тип, который определяет ограничения на значения атрибутов или элементов, включающих только содержимое, а также сведения о них.

<xs:restriction base=""> - задаёт ограничения на определение simpleType.
    base -  (например: base="xs:string" или base="xs:int")

<xs:enumeration value=""/> - задаёт ограничитель.
    value - задаёт критерий ограничения.

Элементы#

В xsd-схеме элементы представлены тегом <xs:element>.

Виды элементов по отношению к корневому элементу:

  • глобальные – это элементы, которые являются непосредственными потомками элемента schema:

    ○ корневой объект;

    ○ комплексные типы:

    ../../_images/element.png
  • локальные – элементы, вложенные в другие элементы;

Виды элементов по структуре:

  • простые элементы – содержат только текст различных типов (boolean, string, date и т.п.) и имеют фиксированные значения:

<xs:element name="имя элемента" type="тип данных"/>
<xs:element name="имя элемента" type="xs:string" fixed="фиксированное значение"/>
  • сложные элементы – содержат другие элементы и/или атрибуты.

    Все виды сложных элементов могут содержать атрибуты.

    Существует четыре вида сложных элементов:

    • пустые;

    • содержат только другие элементы;

    • содержат только текст;

    • содержат другие элементы и текст.

    Дочерние элементы должны появляться в порядке декларирования.

    Сложный элемент может иметь атрибут "type", который указывает на имя используемого комплексного типа:

    <xs:element name="имя элемента" type="ИмяКомплексногоТипа"/>
    <xs:complexType name="ИмяКомплексногоТипа">
      <xs:sequence>
          <xs:element name="имя элемента1" type="xs:string"/>
          <xs:element name="имя элемента2" type="xs:string"/>
      </xs:sequence>
    </xs:complexType>
    

    При таком способе описания элемента один и тот же комплексный тип могут использовать и другие элементы:

    <xs:element name="имя элемента1" type="ИмяКомплексногоТипа"/>
    <xs:element name="имя элемента2" type="ИмяКомплексногоТипа"/>
    <xs:element name="имя элемента3" type="ИмяКомплексногоТипа"/>
    <xs:complexType name="ИмяКомплексногоТипа">
      <xs:sequence>
          <xs:element name="имя элемента4" type="xs:string"/>
          <xs:element name="имя элемента5" type="xs:string"/>
      </xs:sequence>
    </xs:complexType>
    

Атрибуты#

В xsd атрибуты представлены тегом <xs:attribute> и предоставляют дополнительную информацию об элементе.

Атрибуты должны быть заданы для каждого сложного элемента xsd-схемы (complexType). Простые элементы не могут иметь атрибуты.

Все атрибуты декларируются, как простые типы:

<xs:attribute name="имя атрибута" type="тип данных атрибута"/>

По умолчанию атрибуты являются необязательными для использования. Чтобы декларировать обязательный атрибут, следует воспользоваться атрибутом "use" . В этом случае в xml-пакете этот атрибут должен быть указан:

<xs:attribute name="имя атрибута" type="xs:string" use="required"/>

Xsd-схемы имеют множество встроенных типов данных. Наиболее часто используются следующие типы:

  • xs:string

  • xs:integer

  • xs:boolean

  • xs:date

Если элемент или атрибут имеет определение типа данных, то это накладывает ограничение по контенту этого элемента или атрибута. Например, если элемент имеет тип "xs:date" и содержит строку "текст", то он не пройдёт валидацию.

Чтобы ограничить содержимое элемента определённым набором приемлемых значений, следует использовать ограничитель "enumeration":

<xs:complexType name="DocRefTransferMethodType">
      <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="mfc"/>
                                          <xs:enumeration value="epgu"/>
                                          <xs:enumeration value="mail"/>
                                          <xs:enumeration value="email"/>
                                          <xs:enumeration value="inHand"/>
                                          <xs:enumeration value="rpgu"/>
                                      </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:enumeration value="Почтовое отправление"/>
                                          <xs:enumeration value="Электронная почта"/>
                                          <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"/>

Индикаторы#

Для контроля использования элементов используются индикаторы.

Индикаторы очерёдности используются для определения очерёдности появления элементов в xml:

  • "all" – устанавливает, что дочерние элементы могут появляться в любом порядке и что каждый из них должен появляться всего один раз;

<xs:element name="имя сложного элемента">
  <xs:complexType>
      <xs:all>
        <xs:element name="имя элемента1" type="xs:string"/>
        <xs:element name="имя элемента2" type="xs:string"/>
      </xs:all>
  </xs:complexType>
</xs:element>
  • "choice" – устанавливает, что появляться может либо один дочерний элемент, либо другой;

<xs:element name="имя сложного элемента">
  <xs:complexType>
      <xs:choice>
        <xs:element name="имя элемента1" type="ТипЭлемента1"/>
        <xs:element name="имя элемента2" type="ТипЭлемента2"/>
      </xs:choice>
  </xs:complexType>
</xs:element>
  • "sequence" – устанавливает, что дочерние элементы должны появляться в заданном порядке.

<xs:element name="имя сложного элемента">
  <xs:complexType>
      <xs:sequence>
        <xs:element name="имя элемента1" type="xs:string"/>
        <xs:element name="имя элемента2" type="xs:string"/>
      </xs:sequence>
  </xs:complexType>
</xs:element>

Индикаторы частотности устанавливают частоту появления элементов:

  • "maxOccurs" – устанавливает максимальное количество появлений элемента;

<xs:element name="имя сложного элемента">
  <xs:complexType>
      <xs:sequence>
        <xs:element name="имя элемента1" type="xs:string"/>
        <xs:element name="имя элемента2" type="xs:string" maxOccurs="10"/>
      </xs:sequence>
  </xs:complexType>
</xs:element>
  • "minOccurs" – устанавливает минимальное количество появлений элемента.

<xs:element name="имя сложного элемента">
  <xs:complexType>
      <xs:sequence>
        <xs:element name="имя элемента1" type="xs:string"/>
        <xs:element name="имя элемента2" type="xs:string" maxOccurs="10" minOccurs="0"/>
      </xs:sequence>
  </xs:complexType>
</xs:element>

Если поле в карточке обязательное, то следует указать minOccurs="1".

Для разрешения использовать какой-то элемент неограниченное число раз, применяется выражение maxOccurs="unbounded".

Корневой объект#

Корневым объектом в примере ниже является Заявление (DocApplication). Это карточка, которая создаётся клиентом в Системе:

../../_images/kornevoi_object.png

Корневой объект на диаграмме xsd-схемы:

../../_images/diagramma.png

Корневой объект в текстовом описании xsd:

<xs:element name="DocApplication" type="DocApplicationType">
    <xs:annotation>
      <xs:documentation>Заявление</xs:documentation>
    </xs:annotation>
...
</xs:element>

где:

  • element name – алиас объекта;

  • type – алиас корневого объекта (указывается по образцу: "AliasType");

  • documentation – аннотация к элементу.

Комплексный тип#

В xsd-схеме комплексный тип представлен тегом <xs:complexType>.

Комплексный тип описывает сложный элемент и определяет набор атрибутов и содержимое такого элемента. Сложный элемент может содержать другие элементы и/или атрибуты.

Диаграмма xsd-схемы:

../../_images/complex_types.png

Текстовое описание xsd:

<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>

Комплексный тип может быть описан как внутри элемента, так и в конце xsd-схемы.

Схемы проектов#

В xsd может быть указано несколько схем проектов.

Пример с использованием нескольких схем проектов

Диаграмма xsd-схемы:

../../_images/sxemy_proekt.png

Текстовое описание xsd:

<xs:complexType name="schemeType">
    <xs:choice>
        <xs:element name="region" fixed="Министерство строительства Камчатского края"/>
        <xs:element name="pkgo" fixed="Администрация Петропавловск-камчатского городского округа"/>
        <xs:element name="vilyuchinskiygo" fixed="Администрация Вилючинского городского округа"/>
        <xs:element name="palanago" fixed="Администрация городского округа поселок Палана"/>
        <xs:element name="aleutskiymr" fixed="Администрация Алеутского Муниципального района"/>
        <xs:element name="bystrinskiymr" fixed="Администрация Быстринского муниципального района"/>
        <xs:element name="elizovmr" fixed="Администрация Елизовского муниципального района"/>
        <xs:element name="karaginskiymr" fixed="Администрация Карагинского муниципального района"/>
        <xs:element name="milkovskiymr" fixed="Администрация Мильковского муниципального района"/>
        <xs:element name="olyutorskiymr" fixed="Администрация Олюторского муниципального района"/>
        <xs:element name="penzhinskiymr" fixed="Администрация Пенжинского муниципального района"/>
        <xs:element name="sobolevskiymr" fixed="Администрация Соболевского муниципального района"/>
        <xs:element name="tigilskiymr" fixed="Администрация Тигильского муниципального района"/>
        <xs:element name="ustbolshereckiymr" fixed="Администрации Усть-Большерецкого муниципального района"/>
        <xs:element name="ustkamchatskiymr" fixed="Администрация Усть-Камчатского муниципального района"/>
    </xs:choice>
</xs:complexType>

Пример одной схемы проекта

Вариант 1.

Диаграмма xsd-схемы:

../../_images/sxema1.png

Текстовое описание xsd:

<xs:complexType name="DocApplicationType">
        <xs:sequence>
            <xs:element name="scheme" type="schemeType">
                <xs:annotation>
                    <xs:documentation>Схема проекта</xs:documentation>
                </xs:annotation>
            </xs:element>
            ...
        </xs:sequence>
        <xs:attribute fixed="create" name="operation"/>
</xs:complexType>

<xs:complexType name="schemeType">
    <xs:choice>
        <xs:element name="tyulegenov" fixed="Сосногорский МР"/> - указывается наименование и псевдоним проекта в системе
    </xs:choice>
</xs:complexType>

Вариант 2.

Диаграмма xsd-схемы:

../../_images/sxema2.png

Текстовое описание xsd:

<xs:complexType name="DocApplicationType">
        <xs:sequence>
            <xs:element name="scheme">
                <xs:annotation>
                    <xs:documentation>Схема проекта</xs:documentation>
                </xs:annotation>
                <xs:complexType>
                  <xs:choice>
                    <xs:element name="tyulegenov" fixed="Сосногорский МР"/>
                  </xs:choice>
                </xs:complexType>
            </xs:element>
            ...
        </xs:sequence>
        <xs:attribute fixed="create" name="operation"/>
</xs:complexType>

Поля карточки#

Связующий элемент "Fields" объявляет элементы структуры объекта. Это поля карточки в Системе. Они могут быть обязательными и необязательными.

Диаграмма xsd-схемы:

../../_images/sxema3.png

Текстовое описание xsd:

<xs:complexType name="DocApplicationType">
    <xs:sequence>
        ...
        <xs:element name="Fields" type="FieldsType">
            <xs:annotation>
                <xs:documentation>Параметры заявления</xs:documentation>
            </xs:annotation>
        </xs:element>
    </xs:sequence>
    <xs:attribute fixed="create" name="operation"/>
</xs:complexType>


<xs:complexType name="FieldsType">
    ...
</xs:complexType>

Поля простого типа (строка, число, дата)#

Поле строкового типа

Поле числового типа

Поле с датой

Справочное поле#

Ссылочное поле (описание MR-связи)#

Связь с файлом#

Описание геометрии#

Геометрию можно добавить любому объекту, но если в метаданных объект не предполагает наличия геометрии, то при импорте возникнет ошибка. Геометрия проверяется на валидность при попытке импорта.

Геометрия в xsd-схеме представлена двумя полями:

  • текстовое поле с описанием геометрии в формате .geojson:

<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>

Примеры xsd-схем#