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

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


    В далеком 2001 году, консорциум W3C выработал рекомендации языка определения схем XML (XSD), объединив наиболее популярные языки описания схем в один стандарт. Основная цель, которая при этом преследовалась – получение платформо-независимого стандарта, который могут использовать все участники информационного обмена. Обуздав хаос, XML стал самым привлекательным форматом информационного обмена. В наши дни XML формат в информационных технологиях используется очень широко, выйдя далеко за рамки простого обмена данных.

    Следствием популярности и широты использования XML становятся как увеличение объемов, так и усложнение структуры передаваемых в XML данных. Свою немалую лепту в этот процесс внес и более молодой и простой формат JSON, который «отобрал» у XML все информационные потоки с более-менее простой структурой форматов сообщений. На сегодня мы имеем то, что XSD схемы, описывающие структуру данных XML сообщений, стали большими и сложными. Читать большие и сложные схемы в текстовом виде стало очень тяжело, поэтому возникает необходимость как в специальном ПО, так и в актуальной документации, которая описывает форматы XML сообщений.
    В этой статье я расскажу о том, как решалась проблема документирования форматов XML сообщений, используемых для информационного обмена…



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


    Самая лучшая документация по XSD схеме – это сама XSD схема. Эта аксиома верна до тех пор, пока схема не превысит некоторый порог сложности или вы не встретите человека, который не умеет или не хочет читать XSD схемы. При разработке приложения, использующего XSD схемы, Вы также можете столкнуться с требованием описать разработанные форматы сообщений в технической или сопроводительной документации.

    Если же Вы связаны с разработкой приложений со слабосвязанными или распределенными компонентами в сервис-ориентированной архитектуре, Вам знакомы понятия SOA (service-oriented architecture) и SOAP (Simple Object Access Protocol), то очень скоро наступит момент, когда Вы сами будете нуждаться в актуальной документации больше, чем Ваш заказчик.

    Поэтому вопрос «Нужна ли документация?» имеет однозначный ответ «Да», рано или поздно с этим столкнется каждый, кто связан с разработкой ПО, использующего XML.

    Следующий очевидный вопрос – каким должен быть результат документирования форматов? Ответить на этот вопрос довольно сложно, ведь у разных потребителей результата (архитекторов, разработчиков, аналитиков, технических писателей, администраторов, представителей Заказчика и всех остальных) стоят совершенно разные задачи.

    Решают эту задачу по-разному. Кто-то (например, разработчики oXygen) пошел по пути полного описания XSD схемы. В результате чего описание становится еще более сложным для понимания, чем сама схема. Другие стоят на том, что все должны уметь читать XSD схемы и никакой документации не нужно – иногда только потому, что понимают, что они не в состоянии поддерживать актуальность этой документации. Как всегда, истина лежит где-то посередине…

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


    Процесс разработки форматов сообщений можно представить следующими крупными шагами (см. рисунок ниже).



    Итерация № 1:

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

    Процесс разработки форматов сообщений итеративный. После того, как первая итерация пройдена и замечания получены, следующая начинается сразу с шага № 2:

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

      И вот тут у него возникает дилема: внести только те изменения, о которых сообщил ему архитектор или крыжить все схемы, у которых изменился размер файла. Любой, даже самый добросовестный работник выберет первый вариант – и будет неправ. Этот вариант не работает! – в схемах очень часто присутствуют незаявленные изменения, о которых архитектор или разработчик забывает сообщить и при таком подходе описание форматов неизбежно разойдется со схемами. Чем это грозит? – когда начнется разработка, расхождение обнаружится, что внесет толику хаоса и в разной степени усложнит разработку всем командам, участвующим в интеграции.

      Может ли быть еще хуже? – да, если график разработки у команд-участников разный. Одна из команд в начале года, в соответствии со спецификацией, реализует отправку сообщений с неверно заполненными данными и благополучно закрывает контракт. Другая команда в середине года реализует прием этих сообщений и обнаруживает расхождение между требуемыми данными и их описанием. В этот раз хаос приходит, чтобы остаться надолго и расхождение форматов с их описанием может обойтись слишком дорого.

      Каково же решение? Увы – остается единственный вариант – крыжить каждый раз, все изменившиеся схемы. Это принять очень непросто. Документ с альбомом форматов может занимать не одну сотню листов и прокрыжить его, это очень тяжелый и кропотливый труд. Очень часто, на того, кто разрабатывает этот документ оказывает сильное давление срочность выполнения. Не все понимают, почему изменить описание нескольких элементов в нескольких схемах может «стоить» целый рабочий день или еще больше.

      Таким образом данный шаг становится «узким местом» разработки, где каждый в меру своей ответственности определяет, что в данный момент ценнее – качество или время.
    • 4. Согласовать – согласование на первых порах идет внутри команды разрабатывающей форматы. Когда внутреннее согласование пройдено наступает очередь согласования внешнего – у всех участников информобмена.

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

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


    Самый очевидный вариант документирования форматов – ручками. Открываете схему и описываете ее элемент за элементом, что занимает очень много рабочего времени. Если схема большая или их много, то уже через несколько дней Вы приобретете специфический красный оттенок глаз профессионального программиста и стойкое отвращение к этой работе. Следом придет понимание того, что не может быть, чтобы подобную работу давно не автоматизировали и последующий упорный поиск готового инструмента.

    Прежде чем искать инструмент для автоматизации, неплохо было бы понять, как его хотелось бы использовать и каким должен быть результат его работы?

    Вся работа по документированию форматов сообщений укладывается в следующие сценарии использования:

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

    Что касается результата, за много лет работы со схемами и их документацией, я выработал собственное понимание, каким должен быть результат описания форматов сообщений, что называется «от сохи». Основу концепции можно описать всего тремя пунктами:

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

    Как же выглядит описание форматов в документе? В процессе работы, таблица с описанием форматов элементов XSD схемы не раз менялась, как по набору колонок, так и по их наполнению, пока не получила колонки, описанные в ниже:

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

    Пример описания форматов приведен ниже в разделе «Решение»…

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


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

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

    Не смотря на распространенность использования XSD и большое количество ПО, с ним работающего, я так и не нашел инструмента, которое хотя бы частично соответствовало этим требованиям.

    Однако, проблема была как никогда актуальна и такой инструмент был создан…

    6. Решение


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

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


    Здесь показан результат описания форматов элементов, полученного из XSD схемы с заполненным «documentation».

    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. Пример использования внешнего описания


    Здесь показан результат описания форматов элементов, полученного из XSD схемы с незаполненным «documentation».

    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. Пример сравнения двух схем


    Здесь показано описание форматов элементов, полученного при сравнении разных версий XSD схемы.

    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. Полученный результат



    У новых элементов «FirstName», «LastName» и «Zip» выделены жирным шрифтом все колонки. У элемента «Address» изменилась позиция – жирным шрифтом выделена только первая колонка. Удаленные элементы «FullName» и «Country» выделены серым шрифтом. Также «читать» изменения помогает фон строк.

    Данное представление делает отличия легко читаемыми как на экране, так и в печатном виде.

    7. Резюме


    Сейчас, чтобы сделать новую версию альбома форматов для нескольких сотен XSD схем, требуется всего несколько минут. Выходной файл в формате документа Word получается объемом без малого в 1500 листов. Исчезли проблемы ошибок в описании, а самое главное — неактуальности описания схем. Таким образом, получилось успешно автоматизировать одно из самых трудозатратных направлений в управлении разработкой приложений.
    Поделиться публикацией
    Комментарии 10
      0
      Ссылка на программу XSD-DOC: www.xsddoc.ru
        0
        Какие ещё варианты кроме «[1]» бывают в колонке «Мн.»? Из статьи и описания на сайте не понятно.
          +1
          Примеры значений в колонке «Мн.»:
          [0..n]
          [0..1]
          choice [0..1]
          0
          Правильно ли я понимаю, что Вы по сути просто прошлись XSL-трансформацией по XSD-схеме?
            0
            По результату — да, хотя механизм другой.
              0
              А если не видно разницы, то зачем платить больше?
                0
                При таком подходе нет необходимости в XSLT-шаблонах а при изменении XSD схем еще и в их сопровождении.
                  0
                  По приведённому тексту совершенно непонятно, какая использовалась технология.
                  Я вижу на входе XSD (суть XML), на выходе HTML, между ними логично встраивается XSLT.
            0
            «в огороде бузина а в киеве дядька»

            XML Schema Definition (XSD) — отличный самодокументированный формат, далее при помощи того же xlst можно получить всё что угодно под ваши личные требования.
            Это не manifest, best practice, vision, approach, наскальная живопись — это specification.

            Разработчику xsd-схема (точнее даже лучше WSDL контракт(интерфейс) который включает в себя «типы» и описание самого сервиса) нужны только для одного — сгенерировать соответствующие для работы классы. Это если интеграция, если разработка, то документацию(техническое задание, паспорт сервиса в том или иным виде никто не отменяет.

            Хочется кастомизированного отображения в pdf/word/excel? — есть серьезные продукты к примеру от Altova (XMLSpy+Altova StyleVision + возможно и MapForce не окажется лишним… etc).

            «пока не получила колонки, описанные в ниже:»

            --> кастрировано под свои личные требования и задачи, как только пойдут ошибки вида: у Васи в БД поле Address длиной 100 символов, а у Пети 255, и прочие связанные с упрощением.

            «Заполняется в соответствии со справочником почтовых индексов»
            --> без комментариев, ждем, что пришлют Washington/25301-25396 и будете ли вы к этому готовы.

            Тем более есть бесплатные генераторы документации (human readable documentation...) по схеме, пример: xs3p, terrajobst/xsddoc.

            Но, тотже Oxygen — стоит от 200$, Altova® StyleVision 99 eu, Liquid Studio, в среднем за 999-1500$ можно купить отличный инструмент для enterprise работы.

            Но цена вашего ПО: 1000р (~15$ = два обеда) и для маленьких компаний может быть полезен при наличии поддержки (допила нужных фич).

            Что же касается бизнес пользователей/аналитиков — для них ближе Excel, который в том числе умеет загружать xsd схему и тутже лёгким движением мыши позволяет создать «мапу/карту» на лист Excel и указать дополнительный binding на пример файла с данными.
              0
              Полностью поддерживаю все, что вы написали! Ну разве что по поводу отличного самодокументированного формата я не так уверен. Причины я описал в статье…

              Я и сам пользуюсь и Altova и Oxygen, только вот результат генерации документации из этих инструментов не всех устраивает…

            Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

            Самое читаемое