Документирование форматов информационного обмена — легко и просто

1. Вступление

2. Проблематика

3. Суть проблемы

• 1. Определить объем данных для информобмена – на этом шаге определяется объем данных, который нужно передавать между участниками информобмена – сущности, их атрибутивный состав и взаимосвязи.
• 2. Разработать XSD схемы – на основании шага № 1 архитектор или разработчик разрабатывает XSD схемы, которые кроме самих данных, содержат механизмы SOAP сообщений, необходимые для транспорта, безопасности и т.д.
• 3. Описать форматы сообщений – на этом шаге разрабатывается документация, в которой описываются форматы и приводятся примеры сообщений.
• 4. Согласовать – на этом шаге выполняется проверка и согласование форматов внутри команды, разрабатывающей эти форматы. Если обнаружены неточности, итерация разработки повторяется.

• 2. Разработать XSD схемы – архитектор вносит изменения в XSD схемы, это занимает намного меньше времени, чем заняла разработка этих схем на первой итерации.
• 3. Описать форматы сообщений – аналитик или технический писатель должен обновить документацию с описанием форматов.
  
  И вот тут у него возникает дилема: внести только те изменения, о которых сообщил ему архитектор или крыжить все схемы, у которых изменился размер файла. Любой, даже самый добросовестный работник выберет первый вариант – и будет неправ. Этот вариант не работает! – в схемах очень часто присутствуют незаявленные изменения, о которых архитектор или разработчик забывает сообщить и при таком подходе описание форматов неизбежно разойдется со схемами. Чем это грозит? – когда начнется разработка, расхождение обнаружится, что внесет толику хаоса и в разной степени усложнит разработку всем командам, участвующим в интеграции.
  
  Может ли быть еще хуже? – да, если график разработки у команд-участников разный. Одна из команд в начале года, в соответствии со спецификацией, реализует отправку сообщений с неверно заполненными данными и благополучно закрывает контракт. Другая команда в середине года реализует прием этих сообщений и обнаруживает расхождение между требуемыми данными и их описанием. В этот раз хаос приходит, чтобы остаться надолго и расхождение форматов с их описанием может обойтись слишком дорого.
  
  Каково же решение? Увы – остается единственный вариант – крыжить каждый раз, все изменившиеся схемы. Это принять очень непросто. Документ с альбомом форматов может занимать не одну сотню листов и прокрыжить его, это очень тяжелый и кропотливый труд. Очень часто, на того, кто разрабатывает этот документ оказывает сильное давление срочность выполнения. Не все понимают, почему изменить описание нескольких элементов в нескольких схемах может «стоить» целый рабочий день или еще больше.
  
  Таким образом данный шаг становится «узким местом» разработки, где каждый в меру своей ответственности определяет, что в данный момент ценнее – качество или время.
• 4. Согласовать – согласование на первых порах идет внутри команды разрабатывающей форматы. Когда внутреннее согласование пройдено наступает очередь согласования внешнего – у всех участников информобмена.

4. Документирование форматов сообщений

• Документирование структуры элементов одной или нескольких XSD схем с заполненным «documentation» – это самый простой вариант, когда мы формируем документ из одного источника информации (XSD схемы). Обычно это схемы, которые разработаны внутри команды в рамках текущей работы. Идеально, если разработка ведется с учетом соглашения о разработке схем, в котором указано, не только то, что элементы схемы должны документироваться, но и каким именно содержанием и формулировками.
• Документирование структуры элементов одной или нескольких XSD схем с незаполненным «documentation», либо заполненным частично – этот вариант посложнее. Это схемы, которые разработаны другими командами. Часто такие схемы регулярно приходят со стороны «As is» и мы не можем предъявлять к ним какие-либо требования. В этом случае из самой схемы может быть взята только структура, а описание элементов нужно добавлять ручками.
• Сравнение структуры элементов XSD схем разных версий – у нас есть схемы и их описание, и вот схемы поменялись и нужно актуализировать описание либо получить информацию об изменениях. Схемы могут меняться как значимо, когда добавляются или удаляются элементы, так и чисто косметически, когда в каком-то комментарии убрали лишний пробел и изменилась контрольная сумма файла. Отдельно нужно отметить случай, когда схема переписывается с использованием другого шаблона – в этом случае с точки зрения данных ничего не меняется, но узнать в новой схеме старую можно только потратив на это много времени или используя специальное ПО. С учетом того, что схемы могут приходить пачками из сотен штук, становится понятно, что сравнивать схемы глазками очень сложная и ресурсоемкая работа.

• Сама схема вторична – первичны данные. При разработке нам не требуется описание схемы как таковое – нам нужно описание данных, которые описывает эта схема. По сути нам нужно описание формата элементов в том виде, в котором они находятся в XML сообщении, или в XSD схеме, разработанной с использованием шаблона проектирования «Матрешка» (Russian Doll) (подробнее о шаблонах проектирования см. в статье «Шаблоны проектирования XSD»). Именно в этом виде удобно обсуждать схему как при разработке, так и много позже, при интеграции или сопровождении. Именно ее хочет видеть Заказчик в технической документации.
• Описание форматов должно быть простой и понятной таблицей, с которой могут одинаково легко работать как профессиональные разработчики, так и те, для которых все, что связано с разработкой является некой «магией». Всегда найдется тот, кто, являясь для Вас критически важным источником или потребителем информации, ткнет на XSD схему пальчиком и скажет: «Что это???».
• Все элементы должны быть описаны в альбоме форматов однократно. Это означает, что при описании какого-либо элемента, вынесенного в отдельную XSD схему, в таблице должен быть описан только этот элемент. Не нужно подтягивать туда весь формат SOAP сообщения, не нужно раскрывать типы, описанные в импортированных схемах. Такой подход не даст документу раздуться до неприличных размеров и лучше читается, а при необходимости внести дополнительную информацию по какому-либо элементу, сделать это нужно будет в одном месте!

• "№ п/п" — здесь показано позиционирование элемента на схеме в виде многоуровневого списка.
• «Наименование элемента и его тип» — здесь показаны данные, идентифицирующие элемент – наименование элемента и его тип.
• «Описание элемента» — здесь показаны бизнес данные по элементу – его описание с точки зрения бизнеса.
• «Правила заполнения» — здесь показаны технические данные: правила заполнения элемента, формат данных, примеры значений и т.д.
• «Мн.» — здесь показана мощность элемента – обязательность, множественность и возможность выбора элемента.

5. Поиск решения

• Генерация описания форматов элементов для выбранной XSD схемы.
• Генерация описания форматов элементов для всех XSD схем в выбранной папке и ее дочерних папках.
• Сравнение описания форматов элементов для выбранной схемы (либо схем в папках) и ее предыдущей версии.
• Обогащение описания форматов элементов в выходном документе с использованием описаний элементов, заданных в отдельном файле.
• Приведение описания форматов элементов к единому виду в структуре шаблона «Матрешка», независимо от использованного шаблона при проектировании XSD схем.

6. Решение

6.1. Пример обработки документированной схемы

6.1.1. Исходная схема

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example.org/Customer" xmlns:tns="http://www.example.org/Customer"  elementFormDefault="qualified">
    <xsd:annotation>
		<xsd:documentation>Пример схемы для описания атрибутов заказчика.</xsd:documentation>
    </xsd:annotation>
    <xsd:element name="Customer">
		<xsd:annotation>
			<xsd:documentation>Заказчик.</xsd:documentation>
		</xsd:annotation>
		<xsd:complexType>
            <xsd:sequence>
                <xsd:element name="CustomerId" type="xsd:int">
					<xsd:annotation>
						<xsd:documentation>ID заказчика.</xsd:documentation>
					</xsd:annotation>
				</xsd:element>
                <xsd:element name="FirstName" type="xsd:string">
					<xsd:annotation>
						<xsd:documentation>Имя.</xsd:documentation>
					</xsd:annotation>
				</xsd:element>
                <xsd:element name="LastName" type="xsd:string">
					<xsd:annotation>
						<xsd:documentation>Фамилия.</xsd:documentation>
					</xsd:annotation>
				</xsd:element>
                <xsd:element name="Address">
					<xsd:annotation>
						<xsd:documentation>Адрес.</xsd:documentation>
					</xsd:annotation>
                    <xsd:complexType>
                        <xsd:sequence>
                            <xsd:element name="StreetAddress" type="xsd:string">
								<xsd:annotation>
									<xsd:documentation>Наименование улицы.</xsd:documentation>
								</xsd:annotation>
							</xsd:element>
                            <xsd:element name="City" type="xsd:string">
								<xsd:annotation>
									<xsd:documentation>Наименование города.</xsd:documentation>
								</xsd:annotation>
							</xsd:element>
                            <xsd:element name="Zip" type="xsd:string">
								<xsd:annotation>
									<xsd:documentation>Почтовый индекс. >>> Заполняется в соответствии со справочником почтовых индексов.</xsd:documentation>
								</xsd:annotation>
							</xsd:element>
                        </xsd:sequence>
                    </xsd:complexType>
                </xsd:element>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
</xsd:schema>

6.1.2. Полученный результат

6.2. Пример использования внешнего описания

6.2.1. Исходная схема

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example.org/Customer" xmlns:tns="http://www.example.org/Customer"  elementFormDefault="qualified">
    <xsd:element name="Customer">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="CustomerId" type="xsd:int" />
                <xsd:element name="FirstName" type="xsd:string" />
                <xsd:element name="LastName" type="xsd:string" />
                <xsd:element name="Address">
                    <xsd:complexType>
                        <xsd:sequence>
                            <xsd:element name="StreetAddress" type="xsd:string"/>
                            <xsd:element name="City" type="xsd:string"/>
                            <xsd:element name="Zip" type="xsd:string"/>
                        </xsd:sequence>
                    </xsd:complexType>
                </xsd:element>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
</xsd:schema>

6.2.2. Данные файла внешнего описания

\matr			Пример схемы для описания атрибутов заказчика.
Customer 		Заказчик.
CustomerId		ID заказчика.
FirstName		Имя.
LastName		Фамилия.
Address  		Адрес.
StreetAddress		Наименование улицы.
City 			Наименование города.
Zip 			Почтовый индекс. >>> Заполняется в соответствии со справочником почтовых индексов.

6.2.3. Полученный результат

6.3. Пример сравнения двух схем

6.3.1. Исходная схема

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example.org/Customer" xmlns:tns="http://www.example.org/Customer"  elementFormDefault="qualified">
    <xsd:element name="Customer">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="CustomerId" type="xsd:int" />
                <xsd:element name="FirstName" type="xsd:string" />
                <xsd:element name="LastName" type="xsd:string" />
                <xsd:element name="Address">
                    <xsd:complexType>
                        <xsd:sequence>
                            <xsd:element name="StreetAddress" type="xsd:string"/>
                            <xsd:element name="City" type="xsd:string"/>
                            <xsd:element name="Zip" type="xsd:string"/>
                        </xsd:sequence>
                    </xsd:complexType>
                </xsd:element>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
</xsd:schema>

6.3.2. Предыдущая версия схемы

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example.org/Customer" xmlns:tns="http://www.example.org/Customer"  elementFormDefault="qualified">
    <xsd:element name="Customer">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="CustomerId" type="xsd:int" />
                <xsd:element name="FullName" type="xsd:string" />
                <xsd:element name="Address">
                    <xsd:complexType>
                        <xsd:sequence>
                            <xsd:element name="StreetAddress" type="xsd:string"/>
                            <xsd:element name="City" type="xsd:string"/>
                            <xsd:element name="Country" type="xsd:string"/>
                        </xsd:sequence>
                    </xsd:complexType>
                </xsd:element>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
</xsd:schema>

6.3.3. Полученный результат

7. Резюме