Что означает xs complextype

<Complete Reference XML — схемы

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

A complex element contains other elements and/or attributes.

Смешанный сложный тип элемента может содержать атрибуты, элементы и текст.

Что такое сложный элемент?

Сложный элемент представляет собой XML-элемент, содержащий другие элементы и / или атрибутов.

Есть четыре вида сложных элементов:

Note: Каждый из этих элементов может содержать атрибуты , как хорошо!

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

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

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

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

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

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

Смешанный составной тип XML элементов может содержать атрибуты, элементы и текст.

XML элемент «letter», который содержит как текст, так и другие элементы:

Следующая XML схема декларирует элемент «letter»:

Также можно присвоить имя элементу complexType, а в элементе «letter» определить атрибут type с этим именем (в этом случае один и тот же составной тип могут использовать несколько элементов):

Время на прочтение

XSD — это язык описания структуры XML документа. Его также называют XML Schema. При использовании XML Schema XML парсер может проверить не только правильность синтаксиса XML документа, но также его структуру, модель содержания и типы данных.

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

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

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

Рассмотрим в качестве примера XSD документ, описывающий часть структуры аккаунта на хабре.

Текст XSD схемы и XML документ, соответствующий этой схеме я не стал включать в статью из-за их размера.

Первая строчка схемы указывает, что документ является XML документом и использует кодировку UTF-8.

Строки, документирующие элемент:

Главный элемент схемы. Описывает пользователя хабра

Элемент date_of_birth имеет тип данных «дата» и описывает дату рождения.

Дату регистрации описывает register_date, имеющий собственный тип данных customDateTime. Значение этого тега будет задаваться с помощью атрибута value. На это указывают строки.

При этом атрибут — обязательный. Чтобы значение соответствовало требованиям, опишем «проверки»:

Элементы contact_info и blog — массивы, на это указывает атрибут maxOccurs=«unbounded».

Дополнительно о XSD схемах можно почитать Wikipedia и W3C. Для создания макета была использована программа Altova XMLSpy.

Спасибо за внимание!

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

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

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

Примеры составных XML элементов

Составной XML элемент «product», который является пустым:

Составной XML элемент «employee», который содержит только другие элементы:

Составной XML элемент «food», который содержит только текст:

Составной XML элемент «description», который содержит как элементы, так и текст:

Как определить составной XML элемент

Посмотрите на следующий составной XML элемент «employee», который содержит только другие элементы:

В XML схеме мы можем определить составной элемент двумя разными способами:

1. Элемент «employee» может быть декларирован напрямую путем присваивания имени элемента:

2. Элемент «employee» может иметь атрибут type, который указывает на имя используемого составного типа:

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

Также можно, основываясь на каком-либо существующем составном элементе, добавить ему новые элементы:

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 будет невалидным

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

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

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

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

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

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

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

What is a Complex Element?

A complex element is an XML element that contains other elements and/or attributes.

There are four kinds of complex elements:

Note: Each of these elements may contain attributes as well!

XSD

A complex text-only element can contain text and attributes.

This type contains only simple content (text and attributes), therefore we
add a simpleContent element around the content. When using simple content, you
must define an extension OR a restriction within the simpleContent element, like this:

Tip: Use the extension/restriction element to expand or to limit the base simple type for the element.

Here is an example of an XML element, «shoesize», that contains text-only:

We could also give the complexType element a name, and let the «shoesize» element
have a type attribute that refers to the name of the complexType (if you use
this method, several elements can refer to the same complex type):

Определение и использование

Элемент ComplexType определяет сложный тип. Сложный тип элемент представляет собой XML-элемент, содержащий другие элементы и / или атрибутов.

Элемент информации

(Знак? Заявляет, что элемент может появиться ноль или один раз, а знак * заявляет, что элемент может появиться ноль или более раз внутри элемента ComplexType)

Пример 1

В следующем примере есть элемент с именем , который является сложным типом:

Пример 2

Следующий пример имеет сложный тип, , который является производным от другого сложного типа, , расширяя унаследованное тип с тремя дополнительными элементами (address, city and country) :

В приведенном выше примере элемент должен содержать, в последовательности, следующие элементы: , , , и .

Как устроен 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 выкидываем. Ведь, согласно документации, он необязательный. Получили запрос:

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

Examples of Complex Elements

A complex XML element, «product», which is empty:

A complex XML element, «employee», which contains only other elements:

A complex XML element, «food», which contains only text:

A complex XML element, «description», which contains both elements and text:

Сложные типы со смешанным содержимым

XML — элемент, , который содержит текст и другие элементы:

Следующая схема объявляет элемент:

Note: Чтобы включить символьных данных, отображаемых между дочерними элементами , то атрибут должен быть установлен в положение . Тег означает , что элементы , определенные (name, orderid and shipdate) должны появляться в указанном порядке внутри элемента.

Мы могли бы также дать ComplexType элемент имя, и пусть элемента имеют атрибут типа , который ссылается на имя ComplexType (если вы используете этот метод, несколько элементов , может относиться к тому же сложного типа):

Как определить сложный элемент

Посмотрите на этот сложный XML — элемент, , который содержит только другие элементы:

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

1. элемент может быть объявлен непосредственно именования элемента, как это:

Если вы используете метод , описанный выше, только элемент может использовать указанный сложный тип. Обратите внимание , что дочерние элементы, и , окружены индикатор. Это означает, что дочерние элементы должны появляться в том же порядке, как они были объявлены. Вы узнаете больше о показателях в главе XSD индикаторов.

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

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

Вы можете также основать сложный элемент на существующем сложном элементе и добавить некоторые элементы, например:

How to Define a Complex Element

Look at this complex XML element, «employee», which contains only other elements:

We can define a complex element in an XML Schema two different ways:

1. The «employee» element can be declared directly by naming the element, like this:

2. The «employee» element can have a type attribute that refers to the name of the complex type to use:

If you use the method described above, several elements can refer to the same complex type, like this:

You can also base a complex type on an existing complex type and add some elements, like this:

Примеры сложных элементов

Сложный XML — элемент, , который является пустым:

Сложный XML — элемент, , которая содержит только текст:

Сложный XML — элемент, , который содержит как элементы и текст:

Итого

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-канале