Менее громоздкий способ документировать XSD?

Question

Недавно мы начали предоставлять извлечение данных клиентам через XML. У нас есть схема (XSD), которая определяет структуру этого XML. Я хотел бы включить документацию об элементах и ​​атрибутах в саму схему. Единственное, что я нахожу, это очень громоздкие теги «аннотация» и «документация».

Итак, вы берете что-то такое простое и легкое для чтения, как это:

<xs:element name="TransactionType" type="xs:string"  />

И в конечном итоге этот ужасный беспорядок:

<xs:element name="TransactionType" type="xs:string">
    <xs:annotation>
        <xs:documentation>
            Type of transaction
        </xs:documentation>
    </xs:annotation>
</xs:element>

Есть что-нибудь лучше? Скажи что-то вроде этого:

<xs:element name="TransactionType" type="xs:string" description="Type of transaction"  />

PS: Мы уже предоставили этот экстракт в виде простого файла фиксированной длины и в виде CSV. Один клиент запросил XML, и теперь у нас есть второй клиент, желающий использовать XML. Меня попросили о документации. Первый клиент, для которого мы изначально разработали версию XML, просто хотел XSD. Поэтому я надеюсь просто отправить второму клиенту один документ - XSD с простыми аннотациями, описывающими элементы.

Answer 1

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

Магия называется xs3p , и это довольно существенный XSLT-файл для преобразования вашего XSD (в конце концов, просто еще одного XML) в красиво структурированную, очень полезную документацию HTML.

Это бесплатно, это работает - просто великолепно! : -)

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

Марк

Answer 2

Нет, нет. <xs:annotation><xs:documentation> это все, что есть.

Answer 3

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

<xs:element name="TransactionType" type="xs:string" description="Type of transaction" />

и передайте его через XSLT, чтобы преобразовать его в полный формат

<xs:element name="TransactionType" type="xs:string"> 
 <xs:annotation> 
  <xs:documentation> Type of transaction </xs:documentation> 
 </xs:annotation> 
</xs:element>

Вы предоставляете преобразованный XSD клиентам, внутри вы используете компактную версию.

Answer 4

Да, это громоздко, но, к сожалению, это единственный механизм документирования. Тем не менее, тег аннотации предоставляется для удовлетворения многих потребностей. Вы можете поместить туда инструкции по компьютерной обработке, вы можете поместить туда удобочитаемую документацию.

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

Кроме того, тег документации аннотации может содержать текст произвольной длины. Он может включать теги HTML и фактически произвольный XML. Вот почему это не атрибут, а элемент.

Answer 5

XSD предоставляет теги, которые вы упоминаете для документации. Я согласен с вами, они громоздки и делают ваши файлы еще больше.

К сожалению, это то, что у нас есть.