Многофайловые схемы и документирование

Большие схемы делят на файлы: общие типы — отдельно, схемы сообщений — отдельно. Для этого есть три элемента.

xs:include

Подключает схему с тем же целевым пространством имён (или без него — тогда подключённые компоненты «принимают» пространство имён подключающей схемы).

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           targetNamespace="http://example.com/shop"
           xmlns="http://example.com/shop"
           elementFormDefault="qualified">
  <xs:include schemaLocation="common/types.xsd"/>
  <xs:element name="order" type="Order"/>
</xs:schema>

xs:import

Подключает схему другого пространства имён. Префикс для этого пространства объявляется в корне схемы, и компоненты используются с ним.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:addr="http://example.com/address"
           targetNamespace="http://example.com/shop"
           elementFormDefault="qualified">
  <xs:import namespace="http://example.com/address" schemaLocation="address.xsd"/>
  <xs:complexType name="Customer">
    <xs:sequence>
      <xs:element name="address" type="addr:Address"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

xs:include, xs:import и xs:redefine должны идти в начале схемы, до объявлений. В проектах «Помощника SA» schemaLocation разрешается по дереву папок проекта, а Ctrl+клик по нему открывает подключённый файл.

xs:redefine

Подключает схему того же пространства имён и переопределяет в ней отдельные типы и группы (новое определение основано на старом). Используйте осторожно: переопределение действует на все места, где тип используется.

Расширяемые схемы: xs:any и xs:anyAttribute

xs:any разрешает в указанном месте любые элементы, xs:anyAttribute — любые атрибуты. Атрибуты:

• namespace — из каких пространств имён: ##any, ##other (любое, кроме целевого), ##targetNamespace, ##local или список URI;
• processContents — как проверять: strict (по схеме, она должна быть известна), lax (по схеме, если она есть), skip (не проверять).

<xs:complexType name="Message">
  <xs:sequence>
    <xs:element name="header" type="xs:string"/>
    <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
  </xs:sequence>
  <xs:anyAttribute namespace="##other" processContents="skip"/>
</xs:complexType>

Так делают «точки расширения»: новые версии формата добавляют свои элементы, а старые получатели их пропускают.

Документирование

xs:annotation можно поставить в начало почти любого элемента схемы:

• xs:documentation — описание для людей (атрибут xml:lang — язык);
• xs:appinfo — служебная информация для инструментов (генераторов кода, маппинга).

<xs:element name="inn" type="xs:string">
  <xs:annotation>
    <xs:documentation xml:lang="ru">ИНН плательщика</xs:documentation>
    <xs:appinfo>
      <mapping column="PAYER_INN"/>
    </xs:appinfo>
  </xs:annotation>
</xs:element>

Советы по проектированию

• Задавайте targetNamespace и elementFormDefault="qualified" — так документы однозначны и проще подключаются к другим схемам.
• Выносите повторяющиеся структуры в именованные типы и группы, общие типы — в отдельный файл.
• Версию формата отражайте в пространстве имён (…/shop/v2) или атрибуте version — и не меняйте смысл существующих элементов.
• Проверяйте схему на примерах документов: и корректных, и заведомо ошибочных.