XML-схема (W3C)

Спецификация W3C XML Schema 1.0

Спецификация W3C XML Schema 1.1

Схема XML описывает структуру XML-документа, просто
как DTD.

XML-документ с правильным синтаксисом называется «хорошо сформированным».

XML-документ, проверенный на соответствие XML-схеме, одновременно является «Ну
Сформирован» и «Действителен».

Наиболее очевидными функциями, предлагаемыми в XSD, которые недоступны в собственных определениях типов документов XML (DTD), являются осведомленность о пространстве имен и типах данных, то есть возможность определять содержимое элементов и атрибутов как содержащее такие значения, как целые числа и даты, а не чем произвольный текст.

Как и все языки схем XML, XSD может использоваться для выражения набора правил, которым должен соответствовать документ XML, чтобы считаться «действительным» в соответствии с этой схемой. Однако, в отличие от большинства других языков схем, XSD также был разработан с намерением, чтобы при определении действительности документа производился сбор информации, относящейся к конкретным типам данных. Такой информационный набор после проверки может быть полезен при разработке программного обеспечения для обработки XML-документов.

Использование заглавной буквы в слове схемы: существует некоторая путаница относительно того, когда использовать написание слова «Схема» с заглавной буквы, а когда — строчные. Форма нижнего регистра является общим термином и может относиться к любому типу схемы, включая DTD, схему XML (она же XSD), RELAX NG или другие, и ее всегда следует писать в нижнем регистре, за исключением случаев, когда она появляется в начале предложения. Форма «Схема» (с заглавной буквы), широко используемая в сообществе XML, всегда относится к XML-схеме W3C.

После проверки на основе XML-схемы можно выразить структуру и содержимое XML-документа в терминах модели данных, которая была неявной во время проверки. Модель данных XML-схемы включает в себя:

Этот набор информации называется информационным набором после проверки схемы (PSVI). PSVI присваивает допустимому XML-документу его «тип» и облегчает обработку документа как объекта, используя парадигмы объектно-ориентированного программирования (ООП).

Процесс проверки соответствия XML-документа схеме называется проверкой и отличается от основной концепции XML — синтаксической правильности. Все документы XML должны быть правильно сформированы, но не требуется, чтобы документ был действительным, если только синтаксический анализатор XML не выполняет «проверку», и в этом случае документ также проверяется на соответствие связанной с ним схемой. D Синтаксические анализаторы с проверкой TD являются наиболее распространенными, но некоторые из них также поддерживают XML Schema или RELAX NG.

Проверка экземпляра документа на соответствие схеме может рассматриваться как концептуально отдельная операция от анализа XML. Однако на практике многие средства проверки схемы интегрированы с анализатором XML.

XSD 1.1 стал рекомендацией W3C в апреле 2012 года, что означает, что это утвержденная спецификация W3C.

Важными новыми функциями XSD 1.1 являются:

До проекта Предлагаемой Рекомендации в XSD 1.1 также предлагалось добавление нового числового типа данных, PrecisionDecimal. Это оказалось спорным, и поэтому было исключено из спецификации на поздней стадии разработки.

Если вы тестируете API, необходимо знать о двух основных формах передачи данных:

Сегодня я расскажу вам про XML.

XML, в переводе на английский eXtensible Markup Language — расширяемый язык разметки. Используется для хранения и передачи данных. Так что увидеть его можно не только в API, но и в коде.

Этот формат является предпочтительным Консорциумом Всемирной паутины (W3C), поэтому он часто используется для передачи данных по API. В SOAP API это вообще возможенй формат входных и выходных данных!

См также:
Что такое API — общее знакомство с API
Что такое JSON — второй популярный формат
Введение в SOAP и REST: что это и с чем думает — видео о разнице между SOAP и REST.

Так что давайте разберемся, как он выглядит, как его читать, и как ломать! Да-да, а куда же без этого? Надо ведь выяснить, как отреагирует система в кривом формате присланных данных.

Эта статья посвящена схемам XML в целом. Информацию о рекомендациях W3C см. в разделе XML-схема (W3C).

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

There are languages developed specifically to express XML schemas. The document type definition (DTD) language, which is native to the XML specification, is a schema language that is of relatively limited capability, but that also has other uses in XML aside from the expression of schemas. Two more expressive XML schema languages in widespread use are XML Schema (with a capital S) and RELAX NG.

The mechanism for associating an XML document with a schema varies according to the schema language. The association may be achieved via markup within the XML document itself, or via some external means.

The XML Schema Definition is commonly referred to as XSD.

Текущая версия страницы пока не проверялась опытными участниками и может значительно отличаться от версии, проверенной 12 марта 2021 года; проверки требуют 6 правок.

XML Schema — язык описания структуры XML-документа. Спецификация XML Schema является рекомендацией W3C.

XML Schema, как и большинство языков описания данных XML, был задуман для определения правил, которым должен подчиняться документ. Но в отличие от других языков описания данных он был разработан так, чтобы его можно было использовать в создании программного обеспечения для обработки XML-документов.

После проверки документа на соответствие XML Schema читающая программа может создать модель документа (конкретный тип документа как в DTD), которая включает:

Каждый элемент в этой модели ассоциируется с определённым типом данных, позволяя строить в памяти как каркас (по схеме) будущего объекта, так и сам объект (при наполнении каркаса данными), соответствующие заданной структуре (схеме) XML-документа. Языкам объектно-ориентированного программирования гораздо легче иметь дело с таким объектом, чем с текстовым файлом.

Другим удобством XML Schema является то, что один словарь может ссылаться на другой, и, таким образом, разработчик может использовать уже существующие словари и легче устанавливать и распространять стандарты XML-структуры для определённых задач (например, словарь протокола SOAP).

Файл, содержащий XML Schema, обычно имеет расширение «.xsd» (XML Schema definition).

Practical limitations of expressibility:

XML Schemas use XML Syntax

Another great strength about XML Schemas is that they are written in XML.

XML Schemas are extensible, because they are written in XML.

With an extensible Schema definition you can:

Secondary uses for XML Schemas

The primary reason for defining an XML schema is to formally describe an XML document; however the resulting schema has a number of other uses that go beyond simple validation.

The schema can be used to generate code, referred to as XML Data Binding. This code allows contents of XML documents to be treated as objects within the programming environment.

Generation of XML file structure documentation

The schema can be used to generate human-readable documentation of an XML file structure; this is especially useful where the authors have made use of the annotation elements. No formal standard exists for documentation generation, but a number of tools are available, such as the Xs3p stylesheet, that will produce high-quality readable HTML and printed material.

Schemas and schema documents

Technically, a schema is an abstract collection of metadata, consisting of a set of schema components: chiefly element and attribute declarations and complex and simple type definitions. These components are usually created by processing a collection of schema documents, which contain the source language definitions of these components. In popular usage, however, a schema document is often referred to as a schema.

Schema documents are organized by namespace: all the named schema components belong to a target namespace, and the target namespace is a property of the schema document as a whole. A schema document may include other schema documents for the same namespace, and may import schema documents for a different namespace.

When an instance document is validated against a schema (a process known as assessment), the schema to be used for validation can either be supplied as a parameter to the validation engine, or it can be referenced directly from the instance document using two special attributes, xsi:schemaLocation and xsi:noNamespaceSchemaLocation. ( The latter mechanism requires the client invoking validation to trust the document sufficiently to know that it is being validated against the correct schema. «xsi» is the conventional prefix for the namespace «http://www.w3.org/2001/XMLSchema-instance».)

XML Schema Documents usually have the filename extension «.xsd». A unique Internet Media Type is not yet registered for XSDs, so «application/xml» or «text/xml» should be used, as per RFC 3023.

Версия 1.0 была одобрена в качестве рекомендации консорциума W3C 2 мая 2001 года. Таким образом XML Schema стала первой спецификацией описания схемы XML-документа, получившей статус рекомендации W3С, среди множества предложенных на рассмотрение. 28 октября 2004 года была опубликована вторая редакция версии 1.0, исправляющая ряд ошибок.

5 апреля 2012 года была одобрена в качестве рекомендации консорциума Версия 1.1.

Простой пример схемы на XML Schema, расположенной в файле «country.xsd» и описывающей данные о населении страны:

Пример документа, соответствующего этой схеме:

Referencing a Schema in an XML Document

This XML document has a reference to an XML Schema:

specifies the default namespace declaration. This declaration tells the
schema-validator that all the elements used in this XML document are declared in
the «https://www.w3schools.com» namespace.

Once you have the XML Schema Instance namespace available:

you can use the schemaLocation attribute. This attribute has two values,
separated by a space. The first value is the namespace to use. The second value is the location of the XML schema to use for that namespace:

XSD — The Element

indicates that the elements and data types used in the schema come from the «http://www.w3.org/2001/XMLSchema»
namespace. It also specifies that the elements and data types that come from the «http://www.w3.org/2001/XMLSchema» namespace should be prefixed with xs:

indicates that the elements defined by this schema (note, to, from, heading, body.) come from the «https://www.w3schools.com» namespace.

indicates that the default namespace is «https://www.w3schools.com».

indicates that any elements used by the XML instance document which were
declared in this schema must be namespace qualified.

Well Formed XML

Разработчик сам решает, какой XML будет считаться правильным, а какой нет. Но есть общие правила, которые нельзя нарушать. X ML должен быть well formed, то есть синтаксически корректный.

Чтобы проверить XML на синтаксис, можно использовать любой XML Validator (так и гуглите). Я рекомендую сайт w3schools. Там есть сам валидатор + описание типичных ошибок с примерами.

В готовый валидатор вы просто вставляете свой XML (например, запрос для сервера) и смотрите, всё ли с ним хорошо. Но можете проверить его и сами. Пройдитесь по правилам синтаксиса и посмотрите, следует ли им ваш запрос.

Правила well formed XML:

Давайте пройдемся по каждому правилу и обсудим, как нам применять их в тестировании. То есть как правильно «ломать» запрос, проверяя его на well-formed xml. Зачем это нужно? Посмотреть на фидбек от системы. Сможете ли вы по тексту ошибки понять, где именно облажались?

См также:
Сообщения об ошибках — тоже документация, тестируйте их! — зачем тестировать сообщения об ошибках

Есть корневой элемент

Нельзя просто положить рядышком 2 XML и полагать, что «система сама разберется, что это два запроса, а не один». Не разберется. Потому что не должна.

И если у вас будет лежать несколько тегов подряд без общего родителя — это плохой xml, не well formed. Всегда должен быть корневой элемент:

Что мы делаем для тестирования этого условия? Правильно, удаляем из нашего запроса корневые теги!

У каждого элемента есть закрывающийся тег

Тут все просто — если тег где-то открылся, он должен где-то закрыться. Хотите сломать? Удалите закрывающийся тег любого элемента.

Но тут стоит заметить, что тег может быть один. Если элемент пустой, мы можем обойтись одним тегом, закрыв его в конце:

Это тоже самое, что передать в нем пустое значение

Итого — если есть открывающийся тег, должен быть закрывающийся. Либо это будет один тег со слешом в конце.

Для тестирования удаляем в запросе любой закрывающийся тег.

Теги регистрозависимы

Как написали открывающий — также пишем и закрывающий. Т ОЧНО ТАК ЖЕ! А не так, как захотелось.

А вот для тестирования меняем регистр одной из частей. Такой XML будет невалидным

Правильная вложенность элементов

Элементы могут идти друг за другом

Один элемент может быть вложен в другой

Но накладываться друг на друга элементы НЕ могут!

Атрибуты оформлены в кавычках

Даже если вы считаете атрибут числом, он будет в кавычках:

Для тестирования пробуем передать его без кавычек:

Why Use an XML Schema?

With XML Schema, your XML files can carry a description of its own format.

With XML Schema, independent groups of people can agree on a standard for interchanging data.

With XML Schema, you can verify data.

Another great strength about XML Schemas is that they are written in XML:

If you want to study XML Schema, please read our
XML Schema Tutorial.

XML Schemas are More Powerful than DTD

One of the greatest strength of XML Schemas is the support for data types.

Well-Formed is Not Enough

A well-formed XML document is a document that conforms to the XML syntax
rules, like:

Even if documents are well-formed they can still contain errors, and those errors can have serious consequences.

XML Schemas Secure Data Communication

When sending data from a sender to a receiver, it is essential that both parts
have the same «expectations» about the content.

With XML Schemas, the sender can describe the data in a way that the receiver
will understand.

A date like: «03-11-2004» will, in some countries, be interpreted as 3. November
and in other countries as 11. March.

However, an XML element with a data type
like this:

ensures a mutual understanding of the content, because the XML data type «date»
requires the format «YYYY-MM-DD».

What is an XML Schema?

An XML Schema describes the structure of an XML document.

The XML Schema language is also referred to as XML Schema Definition (XSD).

XSD Example

XML Schema is an XML-based alternative to DTD:

The Schema above is interpreted like this:

Как устроен XML

Возьмем пример из документации подсказок Дадаты по ФИО:

И разберемся, что означает эта запись.

В XML каждый элемент должен быть заключен в теги. Тег — это некий текст, обернутый в угловые скобки:

Текст внутри угловых скобок — название тега.
Тега всегда два:

Ой, ну ладно, подловили! Не всегда. Бывают еще пустые элементы, у них один тег и открывающий, и закрывающий одновременно. Но об этом чуть позже!

С помощью тегов мы показываем системе «вот тут начинается элемент, а вот тут заканчивается». Это как дорожные знаки:

— На въезде в город написано его название: Москва
— На выезде написано то же самое название, но перечеркнутое:

* Пример с дорожными знаками я когда-то давно прочитала в статье Яндекса, только ссылку уже не помню. А пример отличный!

В любом XML-документе есть корневой элемент. Это тег, с которого документ начинается, и которым заканчивается. В случае REST API документ — это запрос, который отправляет система. Или ответ, который она получает.

Чтобы обозначить этот запрос, нам нужен корневой элемент. В подсказках корневой элемент — «req».

Он мог бы называться по другому:

Да как угодно. Он показывает начало и конец нашего запроса, не более того. А вот внутри уже идет тело документа — сам запрос. Те параметры, которые мы передаем внешней системе. Разумеется, они тоже будут в тегах, но уже в обычных, а не корневых.

Значение элемента

Значение элемента хранится между открывающим и закрывающим тегами. Это может быть число, строка, или даже вложенные теги!

Вот у нас есть тег «query». Он обозначает запрос, который мы отправляем в подсказки.

Внутри — значение запроса.

Это как если бы мы вбили строку «Виктор Иван» в GUI (графическом интерфейсе пользователя):

Пользователю лишняя обвязка не нужна, ему нужна красивая формочка. А вот системе надо как-то передать, что «пользователь ввел именно это». Как показать ей, где начинается и заканчивается переданное значение? Для этого и используются теги.

Система видит тег «query» и понимает, что внутри него «строка, по которой нужно вернуть подсказки».

Параметр count = 7 обозначает, сколько подсказок вернуть в ответе. Если тыкать подсказки на демо-форме Дадаты, нам вернется 7 подсказок. Это потому, что туда вшито как раз значение count = 7. А вот если обратиться к документации метода, count можно выбрать от 1 до 20.

См также:
Что тестировщику надо знать про панель разработчика — подробнее о том, как использовать консоль.

Но оба значения идут

кавычек. В XML нам нет нужды брать строковое значение в кавычки (а вот в JSON это сделать придется).

Атрибуты элемента

У элемента могут быть атрибуты — один или несколько. Их мы указываем внутри отрывающегося тега после названия тега через пробел в виде

название_атрибута = «значение атрибута»

Зачем это нужно? Из атрибутов принимающая API-запрос система понимает, что такое ей вообще пришло.

Например, мы делаем поиск по системе, ищем клиентов с именем Олег. Отправляем простой запрос:

А в ответ получаем целую пачку Олегов! С разными датами рождения, номерами телефонов и другими данными. Допустим, что один из результатов поиска выглядит так:

Давайте разберем эту запись. У нас есть основной элемент party.

У него есть 3 атрибута:

Внутри party есть элементы field.

У элементов field есть атрибут name. Значение атрибута — название поля: имя, дата рождения, тип или номер телефона. Так мы понимаем, что скрывается под конкретным field.

Это удобно с точки зрения поддержки, когда у вас коробочный продукт и 10+ заказчиков. У каждого заказчика будет свой набор полей: у кого-то в системе есть ИНН, у кого-то нету, одному важна дата рождения, другому нет, и т.д.

Но, несмотря на разницу моделей, у всех заказчиков будет одна XSD-схема (которая описывает запрос и ответ):

— есть элемент party;
— у него есть элементы field;
— у каждого элемента field есть атрибут name, в котором хранится название поля.

А вот конкретные названия полей уже можно не описывать в XSD. Их уже «смотрите в ТЗ». Конечно, когда заказчик один или вы делаете ПО для себя или «вообще для всех», удобнее использовать именованные поля — то есть «говорящие» теги. Какие плюшки у этого подхода:

— При чтении XSD сразу видны реальные поля. Т З может устареть, а код будет актуален.
— Запрос легко дернуть вручную в SOAP Ui — он сразу создаст все нужные поля, нужно только значениями заполнить. Это удобно тестировщику + заказчик иногда так тестирует, ему тоже хорошо.

В общем, любой подход имеет право на существование. Надо смотреть по проекту, что будет удобнее именно вам. У меня в примере неговорящие названия элементов — все как один будут field. А вот по атрибутам уже можно понять, что это такое.

Помимо элементов field в party есть элемент attribute. Не путайте xml-нотацию и бизнес-прочтение:

У элемента attribute есть атрибуты:

А так всё просто — у нас есть элементы, заключенные в теги. Внутри тегов — название элемента. Если после названия идет что-то через пробел: это атрибуты элемента.

XML пролог

Иногда вверху XML документа можно увидеть что-то похожее:

Эта строка называется XML прологом. Она показывает версию XML, который используется в документе, а также кодировку. Пролог необязателен, если его нет — это ок. Но если он есть, то это должна быть первая строка XML документа.

UTF-8 — кодировка XML документов по умолчанию.

XSD-схема

Фишка в том, что проверку по схеме можно делегировать машине. И разработчику даже не надо расписывать каждую проверку. Достаточно сказать «вот схема, проверяй по ней».

Если мы создаем SOAP-метод, то указываем в схеме:

Поэтому зачем запускать сложную процедуру, если запрос заведом «плохой»? И выдавать ошибку через 5 минут, а не сразу? Валидация по схеме помогает быстро отсеять явно невалидные запросы, не нагружая систему.

Более того, похожую защиту ставят и некоторые программы-клиенты для отправки запросов. Например, SOAP Ui умеет проверять ваш запрос на well formed xml, и он просто не отправит его на сервер, если вы облажались. Экономит время на передачу данных, молодец!

А простому пользователю вашего SOAP API схема помогает понять, как составить запрос. Кто такой «простой пользователь»?

Да-да, в идеале у нас есть подробное ТЗ, где всё хорошо описано. Но увы и ах, такое есть не всегда. Иногда ТЗ просто нет, а иногда оно устарело. А вот схема не устареет, потому что обновляется при обновлении кода. И она как раз помогает понять, как запрос должен выглядеть.

Итого, как используется схема при разработке SOAP API:

Попробуем написать для него схему. В запросе должны быть 3 элемента (email, name, password) с типом «string» (строка). Пишем:

А в WSDl сервиса она записана еще проще:

Конечно, в схеме могут быть не только строковые элементы. Это могут быть числа, даты, boolean-значения и даже какие-то свои типы:

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

См также:
XSD — умный XML — полезная статья с хабра
Язык определения схем XSD — тут удобные таблички со значениями, которые можно использовать
Язык описания схем XSD (XML-Schema)
Пример XML схемы в учебнике
Официальный сайт w3.org

Составляем свой запрос

Ок, теперь мы знаем, как «прочитать» запрос для API-метода в формате XML. Но как его составить по ТЗ? Давайте попробуем. Смотрим в документацию. И вот почему я даю пример из Дадаты — там классная документация!

Что, если я хочу, чтобы мне вернулись только женские ФИО, начинающиеся на «Ан»? Берем наш исходный пример:

В первую очередь меняем сам запрос. Теперь это уже не «Виктор Иван», а «Ан»:

Далее смотрим в ТЗ. Как вернуть только женские подсказки? Есть специальный параметр — gender. Название параметра — это название тегов. А внутри уже ставим пол. « Женский» по английски будет FEMALE, в документации также. Итого получили:

Ненужное можно удалить. Если нас не волнует количество подсказок, параметр count выкидываем. Ведь, согласно документации, он необязательный. Получили запрос:

Вот и все! Взяли за основу пример, поменяли одно значение, один параметр добавили, один удалили. Не так уж и сложно. Особенно, когда есть подробное ТЗ и пример )))

Why Learn XML Schema?

In the XML world, hundreds of standardized XML formats are in daily use.

Many of these XML standards are defined by XML Schemas.

XML Schema is an XML-based (and more powerful) alternative to DTD.

XML Schema. Рекомендация W3C.

One of the greatest strengths of XML Schemas is the support for data types:

Итого

XML (eXtensible Markup Language) используется для хранения и передачи данных.

Передача данных — это запросы и ответы в API-методах. Если вы отправляете SOAP-запрос, вы априори работаете именно с этим форматом. Потому что SOAP передает данные только в XML. Если вы используете REST, то там возможны варианты — или XML, или JSON.

Хранение данных — это когда XML встречается внутри кода. Его легко понимает как машина, так и человек. В формате XML можно описывать какие-то правила, которые будут применяться к данным, или что-то еще.

Вот пример использования XML в коде open-source проекта folks. Я не знаю, что именно делает JacksonJsonProvider, но могу «прочитать» этот код — есть функционал, который мы будем использовать (featuresToEnable), и есть тот, что нам не нужен(featuresToDisable).

Формат XML подчиняется стандартам. Синтаксически некорректный запрос даже на сервер не уйдет, его еще клиент порежет. Сначала проверка на well formed, потом уже бизнес-логика.

Если вы тестировщик, то при тестировании запросов в формате XML обязательно попробуйте нарушить каждое правило! Да, система должна уметь обрабатывать такие ошибки и возвращать адекватное сообщение об ошибке. Но далеко не всегда она это делает.

А если система публичная и возвращает пустой ответ на некорректный запрос — это плохо. Потому что разработчик другой системы налажает в запросе, а по пустому ответу даже не поймет, где именно. И будет приставать к поддержке: «Что же у меня не так?», кидая информацию по кусочкам и в виде скринов исходного кода. Оно вам надо? Нет? Тогда убедитесь, что система выдает понятное сообщение об ошибке!

Что такое XML
Учебник по XML
Изучаем XML. Эрик Рэй (книга по XML)
Заметки о XML и XLST

PS — больше полезных статей ищите в моем блоге по метке «полезное». А полезные видео — на моем youtube-канале