Как проверять XML по XSD-схеме: ошибки, инструменты и CI/CD

XSD расшифровывается как XML Schema Definition. Это стандарт W3C, который позволяет описать точную структуру, которой должен следовать XML-документ: какие элементы разрешены, в каком порядке они появляются, каким типам данных должен соответствовать их контент и какие атрибуты обязательны, а какие опциональны. Когда вы проверяете XML-документ по XSD, парсер читает оба файла и сообщает о каждом месте, где документ отклоняется от контракта схемы.

XSD вытеснил более старый формат DTD (Document Type Definition) как основной язык XML-схем, потому что сам написан на XML, поддерживает богатый набор встроенных типов данных (`xs:integer`, `xs:date`, `xs:boolean` и т. д.) и умеет выражать сложные ограничения: шаблоны строк, числовые диапазоны и условные требования к элементам. DTD ещё встречаются в унаследованных системах, но XSD — стандарт для любого обмена данными на базе XML, построенного за последние пятнадцать лет.

Где применяется XSD-валидация

XSD-валидация возникает везде, где структурированные XML-данные пересекают границу системы. Частые примеры: запросы и ответы SOAP-веб-сервисов (описываются WSDL, куда встраиваются XSD-схемы), форматы электронной инвойсинга и закупок вроде UBL 2.1 и EDIFACT, обмен медицинскими данными по профилям HL7 CDA и FHIR XML, государственные XML-подачи (налоговые декларации, таможенные декларации) и конфигурационные файлы корпоративного ПО вроде `pom.xml` в Maven или XML контекста приложения в Spring.

• SOAP-/WSDL-сервисы: каждый элемент запроса и ответа определён во встроенном XSD.
• Электронный инвойсинг (UBL, CII): форматы закупок и счетов несут публичные XSD-схемы, по которым проверяются торговые партнёры.
• Медицина (HL7, FHIR XML): обмен клиническими документами требует строгого соответствия XSD до принятия.
• Государственные подачи: налоговые и таможенные органы публикуют XSD-схемы, которым обязаны удовлетворять подаваемые документы.
• Инструменты сборки: pom.xml Maven, build.xml Ant и многие другие конфигурационные форматы используют XSD для автодополнения и валидации в IDE.

Каждый XML-документ должен сначала быть структурно корректным (well-formed), прежде чем его можно валидировать. Корректность структуры проверяет сам XML-парсер, схема не нужна. Валидность — дополнительный уровень, проверяемый по конкретной схеме. Понимание этого различия экономит много времени на отладке: XSD-валидатор, получивший структурно некорректный документ, часто выдаёт запутанные ошибки схемы вместо настоящей проблемы разбора.

Текстовый объект является well-formed XML-документом, если он соответствует продукционному правилу document и удовлетворяет всем ограничениям корректности структуры, заданным в спецификации.

Что проверяет корректность структуры

• Парность тегов: у каждого открывающего тега есть соответствующий закрывающий (`<item>` → `</item>`).
• Правильная вложенность: теги должны закрываться в обратном порядке — `<a><b></b></a>` корректно; `<a><b></a></b>` — нет.
• Единственный корневой элемент: в документе ровно один элемент верхнего уровня.
• Атрибуты в кавычках: все значения атрибутов заключены в одинарные или двойные кавычки.
• Экранированные спецсимволы: `<`, `>`, `&`, `"` и `'` внутри текстового содержимого должны использовать entity-ссылки или секции CDATA.
• Корректные имена элементов и атрибутов: имена начинаются с буквы или подчёркивания, а не с цифры или дефиса.

Что добавляет XSD-валидность поверх

Когда корректность структуры пройдена, XSD-валидация накладывает контракт схемы. Это включает проверку, что каждый элемент, объявленный обязательным через `minOccurs="1"`, действительно присутствует, что текстовое содержимое типизированных элементов соответствует объявленному `xs:type` (никаких строк в целочисленных полях), что числовые значения попадают в границы `xs:minInclusive` и `xs:maxInclusive`, что строковое содержимое удовлетворяет regex-ограничениям `xs:pattern`, и что дочерние элементы идут в sequence-, choice- или all-группе, определённой в схеме.

Прежде чем проверять XML по XSD, нужно понять, что содержит файл XSD. Файл схемы сам является корректным XML-документом с корневым элементом `xs:schema` в namespace `http://www.w3.org/2001/XMLSchema`. Всё внутри схемы описывает, как должны выглядеть целевые XML-документы.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <!-- Root element declaration --&gt;
  <xs:element name="Invoice">
    <xs:complexType>
      <xs:sequence>
        <!-- Required string - must be present exactly once --&gt;
        <xs:element name="InvoiceNumber" type="xs:string" minOccurs="1" maxOccurs="1"/>
        <!-- Required date --&gt;
        <xs:element name="IssueDate"     type="xs:date"   minOccurs="1" maxOccurs="1"/>
        <!-- Required positive integer --&gt;
        <xs:element name="TotalAmount"   type="xs:decimal" minOccurs="1" maxOccurs="1"/>
        <!-- Optional - 0 to many line items --&gt;
        <xs:element name="LineItem"      type="LineItemType" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
      <!-- Required attribute --&gt;
      <xs:attribute name="currency" type="xs:string" use="required"/>
    </xs:complexType>
  </xs:element>

  <!-- Reusable complex type definition --&gt;
  <xs:complexType name="LineItemType">
    <xs:sequence>
      <xs:element name="Description" type="xs:string"/>
      <xs:element name="Quantity"    type="xs:positiveInteger"/>
      <xs:element name="UnitPrice"   type="xs:decimal"/>
    </xs:sequence>
  </xs:complexType>

</xs:schema>

Ключевые понятия XSD

• xs:element: объявляет элемент по имени и типу. `minOccurs` и `maxOccurs` управляют кратностью.
• xs:complexType: определяет элемент, содержащий дочерние элементы или атрибуты (не только текст).
• xs:simpleType: определяет тип, производный от встроенного — используется для добавления ограничений вроде шаблонов или перечислений.
• xs:sequence: дочерние элементы должны появляться ровно в указанном порядке.
• xs:choice: должен появиться ровно один из перечисленных дочерних элементов.
• xs:all: все перечисленные дочерние элементы должны появиться, в любом порядке, каждый ровно один раз.
• xs:attribute: объявляет атрибут у сложного элемента. `use="required"` делает его обязательным.
• xs:restriction: добавляет ограничения к базовому типу — `xs:pattern`, `xs:minInclusive`, `xs:enumeration` и т. д.

Есть три практичных способа проверить XML-документ по XSD-схеме: браузерный инструмент для быстрых проверок, инструмент командной строки для локальной разработки и скриптов, и программный подход для интеграции в код приложения или CI-конвейеры. Все три способа сообщают об одних и тех же категориях ошибок — разница лишь в том, где и как вы запускаете проверку.

# Validate document.xml against schema.xsd using xmllint
xmllint --schema schema.xsd document.xml --noout

# Output on success:
document.xml validates

# Output on failure:
document.xml:12: element TotalAmount: Schemas validity error:
Element 'TotalAmount': 'abc' is not a valid value of the
atomic type 'xs:decimal'.

Ошибки XSD-валидации делятся на предсказуемые категории. Понимание смысла каждого типа ошибки позволяет быстро найти и исправить проблему в исходном документе, а не расшифровывать незнакомый вывод валидатора строка за строкой.

Ошибки несоответствия типов

Ошибки типов возникают, когда содержимое элемента или атрибута не соответствует объявленному `xs:type`. Самые частые: строка вроде `"N/A"` в поле, объявленном как `xs:integer`; дата в неверном формате (например, `15/06/2026` вместо `2026-06-15`) в поле `xs:date`; десятичное число в поле, объявленном как `xs:positiveInteger`. Исправляйте, корректируя значение в исходном документе или ослабляя объявление типа в схеме, если текущий тип слишком строг.

Отсутствуют обязательные элементы

Когда действует `minOccurs="1"` (значение по умолчанию для `xs:element`), а элемент отсутствует в документе-экземпляре, валидатор сообщает: `Element 'X': This element is not expected. Expected is one of ( Y )` или `Element 'X' is missing`. Обычно это значит, что производитель XML пропустил обязательное поле. Проверьте `xs:sequence` схемы, чтобы подтвердить, какие элементы обязательны и на какой позиции.

Неожиданные или необъявленные элементы

Если ваша схема не использует `xs:any` и не задаёт `processContents="lax"`, любой элемент, не объявленный в схеме, даст: `Element 'X': This element is not expected`. Это самая частая ошибка, когда производитель XML добавляет новое поле, не обновив схему, или когда документ содержит необъявленный префикс namespace-а. Проверьте имя элемента, контекст родительского элемента и объявления namespace-ов в начале документа.

Нарушения шаблона и перечисления

XSD поддерживает `xs:pattern` (regex) и `xs:enumeration` (список допустимых значений) как фасеты простых типов. Нарушение выглядит так: `Element 'Status': [facet 'enumeration'] The value 'ACTIVE' is not an element of the set active', 'inactive', 'pending`. Проверьте, использует ли схема чувствительные к регистру значения перечислений и совпадает ли документ-экземпляр с ожидаемым регистром точно.

Ручная проверка годится для разовых случаев, но XML-процессы в продакшене требуют автоматизированной валидации в каждой точке интеграции. Добавление XSD-валидации в код приложения и CI-конвейер гарантирует, что невалидные документы отклоняются до того, как вызовут повреждение данных, сбои обработки или нарушения соответствия требованиям ниже по потоку.

Валидация в Python с lxml

from lxml import etree

def validate_against_xsd(xml_path: str, xsd_path: str) -> list[str]:
    """Returns a list of validation error messages, empty if valid."""
    with open(xsd_path, 'rb') as f:
        schema_doc = etree.parse(f)
    schema = etree.XMLSchema(schema_doc)

    with open(xml_path, 'rb') as f:
        doc = etree.parse(f)

    schema.validate(doc)
    return [str(e) for e in schema.error_log]

errors = validate_against_xsd('invoice.xml', 'invoice.xsd')
if errors:
    for err in errors:
        print(err)
else:
    print('Document is valid.')

Добавление XSD-валидации в GitHub Actions

Для CI/CD-процессов, которые обрабатывают или генерируют XML, шаг валидации не даёт сломанным документам попадать в мерж. Команда `xmllint` доступна на Ubuntu-раннерах GitHub Actions через `sudo apt-get install -y libxml2-utils`. Добавьте шаг, который выполняет `xmllint --schema schema.xsd document.xml --noout` на каждом pull request, затрагивающем XML-файлы. Ненулевой код выхода проваливает проверку и блокирует мерж.

name: Validate XML
on:
  pull_request:
    paths:
      - '**/*.xml'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install xmllint
        run: sudo apt-get install -y libxml2-utils
      - name: Validate XML against XSD
        run: |
          xmllint --schema schemas/invoice.xsd \
                  data/invoices/*.xml \
                  --noout

Используйте XPath для инспекции конкретных значений перед проверкой

Перед полным XSD-проходом можно воспользоваться XPath-поисковиком и тестером, чтобы точно указать значение конкретного элемента или атрибута в большом XML-документе. XPath-запросы вроде `//Invoice/TotalAmount/text()` достают поле без ручного разбора всего файла. Это особенно полезно при диагностике несоответствия типов в документе с сотнями элементов — сначала найдите проблемное значение, потом применяйте исправление.

Сравнение подходов к валидации

Хорошо спроектированная XSD-схема делает документы проще в проверке, расширении и сопровождении между версиями схемы. Эти практики применимы как при создании схемы с нуля, так и при сопровождении схемы, полученной от внешнего партнёра.

Используйте именованные типы вместо анонимных встроенных

Определяйте сложные типы через `xs:complexType name="..."`, а не вкладывайте их анонимно внутрь объявлений элементов. Именованные типы можно переиспользовать в нескольких объявлениях элементов, что сокращает дублирование и упрощает изменения схемы — обновите определение типа один раз, и все использующие его элементы унаследуют изменение.

Для строгих контрактов предпочитайте xs:sequence, а не xs:all

`xs:all` разрешает элементам появляться в любом порядке, что кажется терпимым, но вносит неоднозначность для производителей и потребителей. `xs:sequence` более явный и соответствует естественному порядку чтения большинства XML-форматов. Используйте `xs:all` только тогда, когда порядок элементов действительно не важен и вы пишете схему для системы под вашим контролем; для любой схемы, пересекающей организационные границы, предпочитайте `xs:sequence`.

Версионируйте схемы через namespace

Используйте URI целевого namespace с индикатором версии, например `targetNamespace="urn:example:invoice:v2"`. Это делает ломающие изменения схемы явными — потребители на v1 увидят несовпадение namespace, а не молча провалидировать не ту версию схемы. Держите старую схему доступной для обратно совместимых развёртываний в течение окна миграции.

• Объявляйте targetNamespace: предотвращает коллизии имён элементов при объединении схем через xs:import.
• Используйте xs:documentation: добавляйте человекочитаемые описания внутри блоков xs:annotation, чтобы потребители схемы понимали каждое поле.
• Задавайте явные minOccurs/maxOccurs: не полагайтесь на значения по умолчанию — указывайте кратность явно, чтобы передать намерение.
• Используйте xs:restriction для ограниченных строк: поле почтового индекса должно применять xs:pattern, а не xs:string — валидация ловит ошибки формата на границе.
• Разбивайте большие схемы: используйте xs:include, чтобы разрезать схему на 500 строк на файлы по доменам (addresses.xsd, line-items.xsd) для удобства сопровождения.