Наслаждайтесь компактным синтаксисом RELAX NG
Экспериментируя с различными языками XML-схем, я обнаружил, что RELAX NG лучше всего подходит для большинства случаев (в конце рассуждения).
Требования
- Разрешить документирование структуры XML-документа
- Сделайте это в читабельной форме
- Не усложняйте автору
Модифицированный образец XML (doc.xml)
Я добавил один атрибут, чтобы проиллюстрировать также этот тип структуры в документации.
<objectRoot created="2015-05-06T20:46:56+02:00">
<v>
<!-- Current version of the object from the repository. !-->
<!-- (Occurance: 1) -->
</v>
<label>
<!-- Name of the object from the repository. !-->
<!-- (Occurance: 0 or 1 or Many) -->
</label>
</objectRoot>
Использовать синтаксис RELAX NG Compact с комментариями (schema.rnc)
RELAX NG позволяет описать пример структуры XML следующим образом:
start =
## Container for one object
element objectRoot {
## datetime of object creation
attribute created { xsd:dateTime },
## Current version of the object from the repository
## Occurrence 1 is assumed by default
element v {
text
},
## Name of the object from the repository
## Note: the occurrence is denoted by the "*" and means 0 or more
element label {
text
}*
}
Я думаю, очень сложно победить простоту, сохраняя заданный уровень выразительности.
Как прокомментировать структуру
- всегда размещайте комментарий перед соответствующим элементом, а не после него.
- для удобства чтения используйте одну пустую строку перед блоком комментария
- использовать префикс
##, который автоматически переводится в элемент документации в другом формате схемы. Одиночный хеш # преобразуется в XML-комментарий, а не в элемент документации.
несколько последовательных комментариев (как в примере) превратятся в одну многострочную строку документации внутри одного элемента.
очевидный факт: встроенные XML-комментарии в doc.xml не имеют значения, учитывается только то, что в schema.rnc.
Если требуется XML Schema 1.0, сгенерируйте ее (schema.xsd)
Предполагая, что у вас есть (с открытым исходным кодом) инструмент под названием trang, вы можете создать файл схемы XML следующим образом:
$ trang schema.rnc schema.xsd
Результирующая схема выглядит следующим образом:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xs:element name="objectRoot">
<xs:annotation>
<xs:documentation>Container for one object</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element ref="v"/>
<xs:element minOccurs="0" maxOccurs="unbounded" ref="label"/>
</xs:sequence>
<xs:attribute name="created" use="required" type="xs:dateTime">
<xs:annotation>
<xs:documentation>datetime of object creation</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name="v" type="xs:string">
<xs:annotation>
<xs:documentation>Current version of the object from the repository
Occurance 1 is assumed by default</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="label" type="xs:string">
<xs:annotation>
<xs:documentation>Name of the object from the repository
Note: the occurance is denoted by the "*" and means 0 or more</xs:documentation>
</xs:annotation>
</xs:element>
</xs:schema>
Теперь ваши клиенты, настаивая на использовании только XML Schema 1.0, могут использовать спецификацию вашего XML-документа.
Проверка doc.xml по сравнению с schema.rnc
Существуют инструменты с открытым исходным кодом, такие как jing и rnv, поддерживающие синтаксис RELAX NG Compact и работающие как в Linux, так и в MS Windows.
Примечание: эти инструменты довольно старые, но очень стабильные. Прочитайте это как признак стабильности, а не как признак устаревания.
Используя Цзин:
$ jing -c schema.rnc doc.xml
Важно -c, jing по умолчанию предполагает RELAX NG в форме XML.
Используя rnv для проверки, сам schema.rnc действителен:
$ rnv -c schema.rnc
и для проверки doc.xml:
$ rnv schema.rnc doc.xml
rnv позволяет проверять сразу несколько документов:
$ rnv schema.rnc doc.xml otherdoc.xml anotherone.xml
RELAX NG Компактный синтаксис - плюсы
- очень читабельно, даже новичок должен понимать текст
- легко учиться (RELAX NG поставляется с хорошим учебником, большую часть можно выучить за один день)
- очень гибкий (несмотря на то, что он выглядит простым, он охватывает многие ситуации, некоторые из них даже не могут быть решены с помощью XML Schema 1.0).
- существуют некоторые инструменты для преобразования в другие форматы (форма RELAX NG XML, XML Schema 1.0, DTD, но даже создание образца XML-документа).
RELAX NG ограничения
- кратность может быть только «ноль или один», «только один», «ноль или более» или «один или более». (Множественность небольшого количества элементов можно описать «глупым повторением» определений «ноль или один»)
- Существуют конструкции XML Schema 1.0, которые RELAX NG не может описать.
Выводы
Для приведенного выше требования синтаксис RELAX NG Compact выглядит наилучшим образом. С RELAX NG вы получаете обе - удобочитаемую схему, которую даже можно использовать для автоматической проверки.
Существующие ограничения вступают в силу не очень часто и во многих случаях могут быть устранены с помощью комментариев или других средств.