Annotation for Applications
As mentioned in the introduction to this chapter, common uses of annotations by applications include preprocessing instructions, helpers for generating other schemas out of a RELAX NG schema, and extensions of RELAX NG itself.
Annotations for Preprocessing
Bob DuCharme has proposed an interesting application of annotation for preprocessing. He says that annotation can derive specific schemas by the restriction of a generic schema. The benefits of this approach are that it is extremely simple and that it provides a straightforward workaround to the lack of derivation by restriction (a W3C XML Schema feature) in RELAX NG. It is language-neutral and can be applied to other schema languages such as W3C XML Schema: it is much simpler than the derivation by restriction feature built into the language.
You can find Bob DuCharme’s proposal on the web at: http://www.snee.com/xml/schemaStages.html and download the XSLT transformation implementing it from http://www.snee.com/xml/schemaStages.zip.
The idea behind his proposal is to add annotations in elements that
need to be removed in a variant of the schema. You then use these
annotations to generate the different variants using an XSLT
transformation. Each variant is called a stage.
The list of the available stages is declared in an
sn:stages element. For each element that is
conditional, the list of the stages in which it needs to be kept is
declared through an sn:stages attributes.
Because this technique uses annotations, the global schema can still be a valid schema that validates a superset of the instance documents that are valid per each stage.
If you wanted to derive schemas requiring a book,
author, library, or
character element or both book
and author as a document element from a generic
schema that allows any of these, you could write:
<?xml version="1.0" encoding="utf-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0"
xmlns:sn="http://www.snee.com/ns/stages">
<sn:stages>
<sn:stage name="library"/>
<sn:stage name="book"/>
<sn:stage name="author"/>
<sn:stage name="character"/>
<sn:stage name="author-or-book"/>
</sn:stages>
<start>
<choice>
<ref name="library-element" sn:stages="library"/>
<ref name="book-element" sn:stages="book author-or-book"/>
<ref name="author-element" sn:stages="author author-or-book"/>
<ref name="character-element" sn:stages="character"/>
</choice>
</start>
...
</grammar>or:
namespace sn = "http://www.snee.com/ns/stages"
sn:stages [
sn:stage [ name = "library" ]
sn:stage [ name = "book" ]
sn:stage [ name = "author" ]
sn:stage [ name = "character" ]
sn:stage [ name = "author-or-book" ]
]
start =
[ sn:stages = "library" ] library-element
| [ sn:stages = "book author-or-book" ] book-element
| [ sn:stages = "author author-or-book" ] author-element
| [ sn:stages = "character" ] character-element
...This schema is a valid RELAX NG schema that accepts any of these
elements as a root. A transformation of the XML syntax through the
XSLT transformation getStage.xsl, provided in
the ZIP file mentioned previously and with a parameter
stageName set to author-or-book
removes all elements with an sn:stage attribute
that don’t have author-or-book in
their list of values:
$ xsltproc --stringparam stageName author-or-book getStage.xsl doc-snee.rng
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0"
xmlns:sn="http://www.snee.com/ns/stages">
<start>
<choice>
<ref name="book-element"/>
<ref name="author-element"/>
</choice>
</start>
...
</grammar>This transformation has thus performed a restriction on the schema.
You can generate as many schemas this way, as there are stages that
have been declared in the sn:stages
element.
Annotations for Conversion
RELAX NG works well as a pivot format. A pivot format is a reference format in which schemas are kept and transformed into other languages. One of the limits of the pivot approach is that features that are part of the target languages but not part of RELAX NG seems to be out of reach. It would be true, except for annotations. The two most common examples of such annotations are used to generate DTDs and W3C XML Schema.
Annotations to generate DTDs
This is the
third and final facet of the DTD
Compatibility specification, and it deals with default values for
attributes. They can be declared using an
a:defaultValue attribute:
<?xml version="1.0" encoding="utf-8"?>
<element xmlns="http://relaxng.org/ns/structure/1.0"
xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"
name="library">
<oneOrMore>
<element name="book">
<attribute name="id"/>
<optional>
<attribute name="available" a:defaultValue="true">
<choice>
<value>true</value>
<value>false</value>
</choice>
</attribute>
</optional>
...
</element>
</oneOrMore>
...
</element>or:
namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0"
element library {
element book {
attribute id { text },
[ a:defaultValue = "true" ]
attribute available { "true" | "false" }?,
element isbn { text },
element title {
attribute xml:lang { text },
text
},
...
}+
}The attribute needs to be declared as optional to use this feature. Hence there is no impact on the validation by a RELAX NG processor. However, converters such as Trang use this annotation to generate a default value in a DTD:
<!ATTLIST book id CDATA #REQUIRED available (true|false) 'true'>
Annotations to generate W3C XML Schema
There is no official specification about how to generate W3C XML Schema from RELAX NG, so what I will say in this small section is derived from Trang’s documentation.
Tip
If you want to know how to use Trang, check its web page at http://www.thaiopensource.com/relaxng/trang-manual.html.
The first thing to note is that Trang supports the
a:defaultValue attribute. The schema presented
earlier can be translated as:
<xs:element name="book">
<xs:complexType>
<xs:sequence>
<xs:element ref="isbn"/>
<xs:element ref="title"/>
<xs:element minOccurs="0" maxOccurs="unbounded" ref="author"/>
<xs:element minOccurs="0" maxOccurs="unbounded" ref="character"/>
</xs:sequence>
<xs:attribute name="id" use="required"/>
<xs:attribute name="available" default="true">
<xs:simpleType>
<xs:restriction base="xs:token">
<xs:enumeration value="true"/>
<xs:enumeration value="false"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>Note the default attribute in the declaration of
the available attribute.
In addition to this annotation, James Clark has created a specific namespace, http://www.thaiopensource.com/ns/relaxng/xsd, to manage the translation to W3C XML Schema. This translation is far from obvious, and a RELAX NG schema can often be translated using different features of W3C XML Schema. James Clark has made a lot of choices in his implementation based on best practices, but there are still some context-dependent options; in those situations, the users can be given a choice.
In the current version (as of June 19, 2003), there is only one
annotation attribute available to perform such choices: the
tx:enableAbstractElements
attribute, which can be included in
grammar, div, or
include. This attribute can take the values
true or false and controls
whether abstract elements can be used in substitution groups.
Substitution groups are a fairly advanced feature of W3C XML Schema,
and I won’t present the concept here, but you can
find more information on this feature in my XML.com tutorial at
http://xml.com/pub/a/2000/11/29/schemas/part1.html
or in my book, XML Schema.
The Trang manual indicates that more annotations might be added in the future.
Schema Adjunct Framework
The Schema Adjunct Framework (SAF) is a generic framework that stores processing information in relation to schemas and can work either standalone or as a schema adornment to annotations embedded in schemas. Although it has been developed to work with W3C XML Schema, there is no reason that it couldn’t be used to adorn RELAX NG schemas.
Tip
You can find more information about SAF on the Web: http://www.tibco.com/solutions/products/extensibility/resources/saf.jsp.
The momentum behind SAF seems to have decreased a lot since end of 2001, but it’s definitely something worth examining if you need to add processing information to a schema. A simple example of a SAF adornment in RELAX NG looks like:
<define name="author-element">
<sql:select>select <sql:elem>name</sql:elem>,
<sql:elem>birthdate</sql:elem>,<sql:elem>deathdate</sql:elem>
from tbl_author</sql:select>
<element name="author">
<attribute name="id"/>
<ref name="name-element"/>
<ref name="born-element"/>
<optional>
<ref name="died-element"/>
</optional>
</element>
</define>or:
[
sql:select [
"select "
sql:elem [ "name" ]
", "
sql:elem [ "birthdate" ]
", "
sql:elem [ "deathdate" ]
" from tbl_author"
]
]
author-element =
element author {
attribute id { text },
name-element,
born-element,
died-element?
}These examples both add SQL-based processing information to the schema.
Annotations for Extension
Annotations can also be used as extensions to influence the behavior of the RELAX NG processors that support them. This application is controversial but can also be very useful. The two applications of which I am aware in this category are one for embedding Schematron rules, and my own XVIF project, which allows a user to define validation and transformation pipes that act as RELAX NG patterns.
Embedded Schematron rules
Schematron is a rather atypical XML schema language. Instead of being grammar-based like RELAX NG and focusing on describing documents, Schematron is rule-based and consists of lists of rules to check against documents. Giving the exhaustive list of all the rules needed to validate a document is a very verbose and error-prone task, but on the other hand, the ability to write your own rules gives a flexibility and a power that can’t be matched by a grammar-based schema language. The two types of languages appear to be more complementary than their competitors. Using both together allows you to get the best from each of them.
Tip
You can find more information about Schematron on its web site: http://www.ascc.net/xml/resource/schematron/schematron.html.
Schematron can get into places no other schema language can. For
example, Schematron is a good fit when checking whether the
id attribute of a book element is composed of the
ISBN number prefixed by the letter b. In this
case, you would write:
<?xml version="1.0" encoding="utf-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0"
xmlns:s="http://www.ascc.net/xml/schematron">
<define name="book-element">
<element name="book">
<s:rule context="book">
<s:assert test="@id = concat('b', isbn)">
The id needs to be the isbn number prefixed by "b" </s:assert>
</s:rule>
<attribute name="id"/>
<attribute name="available"/>
<ref name="isbn-element"/>
<ref name="title-element"/>
<zeroOrMore>
<ref name="author-element"/>
</zeroOrMore>
<zeroOrMore>
<ref name="character-element"/>
</zeroOrMore>
</element>
</define>
...
</grammar>or:
namespace s = "http://www.ascc.net/xml/schematron"
book-element =
[
s:rule [
context = "book"
s:assert [
test = "@id = concat('b', isbn)"
' The id needs to be the isbn number prefixed by "b" '
]
]
]
element book {
attribute id { text },
attribute available { text },
isbn-element,
title-element,
author-element*,
character-element*
}
...The Schematron annotation comprises a rule
element, which sets the context and embedded
assert elements defining assertions. Instead of
assert, report elements can be
used. They are the opposite of assertions and report errors when they
are true. These checks are applied to all the elements meeting the
XPath expression provided in the context attribute
of the rule elements, and the
test attribute of the assert or
report elements are also XPath expressions.
At this point, I must mention that there is an appreciable difference between implementations on the scope in which the rules must be applied, which can lead to potential issues of interoperability between implementations.
On one hand, the Schematron specification states that when Schematron
rules are embedded in another language, they must be collected and
bundled into a Schematron schema independently of where they have
been found in the original schema. In other words, the rule that was
defined earlier should be applied to all the book
elements in the instance documents. This is the approach taken by the
Topologi multivalidator (see
http://www.topologi.com/products/validator/index.html).
On the other hand, when a Schematron rule is embedded in a RELAX NG
element pattern, as is the case here, it is
tempting to evaluate the rule in the context of the pattern. In that
case, the rule applies only to the book elements
that are included in the context node. If the rule fails, the element
pattern fails, and other alternatives will be checked. This is the
approach taken by Sun’s Multi Schema
Validator (see http://wwws.sun.com/software/xml/developers/multischema/).
The difference can be seen in an example such as:
<define name="book-element">
<choice>
<element name="book">
<s:rule context="book">
<s:assert test="@id = concat('b', isbn)">
The id needs to be the isbn number prefixed by "b" </s:assert>
</s:rule>
<attribute name="id"/>
<attribute name="available"/>
<ref name="isbn-element"/>
<ref name="title-element"/>
<zeroOrMore>
<ref name="author-element"/>
</zeroOrMore>
<zeroOrMore>
<ref name="character-element"/>
</zeroOrMore>
</element>
<element name="book">
<attribute name="id">
<value>ggjh0836217462</value>
</attribute>
<attribute name="available"/>
<ref name="isbn-element"/>
<ref name="title-element"/>
<zeroOrMore>
<ref name="author-element"/>
</zeroOrMore>
<zeroOrMore>
<ref name="character-element"/>
</zeroOrMore>
</element>
</choice>
</define>In this case, the approach taken by the Schematron specification
would consider an instance document with a book ID equal to
ggjh0836217462 to be invalid. The evaluation of
the Schematron rules is completely decoupled from the validation by
the RELAX NG schema. The approach taken by MSV considers the same
document as valid, because it meets one of the alternative
definitions for the book element.
XVIF
The interoperability issue mentioned previously is a good illustration of the difficulty of mixing elements from different languages that have been specified independently. The XML Validation Interoperability Framework (XVIF) is a proposal for a framework which would take care of this kind of issue.
Tip
You will find more information about XVIF at its home page: http://downloads.xmlschemata.org/python/xvif/.
The principle of XVIF is to define micro pipes, much like Unix pipes, of transformations and validations that can be embedded in different transformation and validation languages. When the host language is RELAX NG, these micro pipes behave as RELAX NG patterns.
There are many use cases for such micro pipes; one of them is to include transformations to fit text nodes into existing datatypes. For instance, we’ve been using dates that use the ISO 8601 format in our documents, but we can also use French date formats. In this case, a set of regular expressions can be defined to do the transformation between these dates and the ISO 8601 format. XVIF gives a way to integrate these regular expressions in a RELAX NG schema:
<?xml version="1.0" encoding="utf-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0"
xmlns:if="http://namespaces.xmlschemata.org/xvif/iframe"
datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
<define name="born-element">
<element name="born">
<if:pipe>
<if:validate type="http://namespaces.xmlschemata.org/xvif/regexp"
apply="m/[0-9]+ .+ [0-9]+/"/>
<if:transform type="http://namespaces.xmlschemata.org/xvif/regexp"
apply="s/^[
]*([0-9] .*)$/01/"/>
<if:transform type="http://namespaces.xmlschemata.org/xvif/regexp"
apply="s/([0-9]+) janvier ([0-9]+)/2-01-1/"/>
<if:transform type="http://namespaces.xmlschemata.org/xvif/regexp"
apply="s/([0-9]+) fevrier ([0-9]+)/2-02-1/"/>
<if:transform type="http://namespaces.xmlschemata.org/xvif/regexp"
apply="s/([0-9]+) mars ([0-9]+)/2-03-1/"/>
<if:transform type="http://namespaces.xmlschemata.org/xvif/regexp"
apply="s/([0-9]+) avril ([0-9]+)/2-04-1/"/>
<if:transform type="http://namespaces.xmlschemata.org/xvif/regexp"
apply="s/([0-9]+) mai ([0-9]+)/2-05-1/"/>
<if:transform type="http://namespaces.xmlschemata.org/xvif/regexp"
apply="s/([0-9]+) juin ([0-9]+)/2-06-1/"/>
<if:transform type="http://namespaces.xmlschemata.org/xvif/regexp"
apply="s/([0-9]+) juillet ([0-9]+)/2-07-1/"/>
<if:transform type="http://namespaces.xmlschemata.org/xvif/regexp"
apply="s/([0-9]+) aout ([0-9]+)/2-08-1/"/>
<if:transform type="http://namespaces.xmlschemata.org/xvif/regexp"
apply="s/([0-9]+) septembre ([0-9]+)/2-09-1/"/>
<if:transform type="http://namespaces.xmlschemata.org/xvif/regexp"
apply="s/([0-9]+) octobre ([0-9]+)/2-10-1/"/>
<if:transform type="http://namespaces.xmlschemata.org/xvif/regexp"
apply="s/([0-9]+) novembre ([0-9]+)/2-11-1/"/>
<if:transform type="http://namespaces.xmlschemata.org/xvif/regexp"
apply="s/([0-9]+) decembre ([0-9]+)/2-12-1/"/>
<if:validate type="http://relaxng.org/ns/structure/1.0">
<if:apply>
<data type="date">
<param name="minInclusive">1900-01-01</param>
<param name="maxInclusive">2099-12-31</param>
</data>
</if:apply>
</if:validate>
</if:pipe>
<text if:ignore="1"/>
</element>
</define>
...
</grammar>or, in the compact syntax:
namespace if = "http://namespaces.xmlschemata.org/xvif/iframe"
namespace rng = "http://relaxng.org/ns/structure/1.0"
datatypes d = "http://relaxng.org/ns/compatibility/datatypes/1.0"
born-element =
[
if:pipe [
if:validate [
type = "http://namespaces.xmlschemata.org/xvif/regexp"
apply = "m/[0-9]+ .+ [0-9]+/"
]
if:transform [
type = "http://namespaces.xmlschemata.org/xvif/regexp"
apply = "s/^[
]*([0-9] .*)$/01/"
]
if:transform [
type = "http://namespaces.xmlschemata.org/xvif/regexp"
apply = "s/([0-9]+) janvier ([0-9]+)/2-01-1/"
]
if:transform [
type = "http://namespaces.xmlschemata.org/xvif/regexp"
apply = "s/([0-9]+) fevrier ([0-9]+)/2-02-1/"
]
if:transform [
type = "http://namespaces.xmlschemata.org/xvif/regexp"
apply = "s/([0-9]+) mars ([0-9]+)/2-03-1/"
]
if:transform [
type = "http://namespaces.xmlschemata.org/xvif/regexp"
apply = "s/([0-9]+) avril ([0-9]+)/2-04-1/"
]
if:transform [
type = "http://namespaces.xmlschemata.org/xvif/regexp"
apply = "s/([0-9]+) mai ([0-9]+)/2-05-1/"
]
if:transform [
type = "http://namespaces.xmlschemata.org/xvif/regexp"
apply = "s/([0-9]+) juin ([0-9]+)/2-06-1/"
]
if:transform [
type = "http://namespaces.xmlschemata.org/xvif/regexp"
apply = "s/([0-9]+) juillet ([0-9]+)/2-07-1/"
]
if:transform [
type = "http://namespaces.xmlschemata.org/xvif/regexp"
apply = "s/([0-9]+) aout ([0-9]+)/2-08-1/"
]
if:transform [
type = "http://namespaces.xmlschemata.org/xvif/regexp"
apply = "s/([0-9]+) septembre ([0-9]+)/2-09-1/"
]
if:transform [
type = "http://namespaces.xmlschemata.org/xvif/regexp"
apply = "s/([0-9]+) octobre ([0-9]+)/2-10-1/"
]
if:transform [
type = "http://namespaces.xmlschemata.org/xvif/regexp"
apply = "s/([0-9]+) novembre ([0-9]+)/2-11-1/"
]
if:transform [
type = "http://namespaces.xmlschemata.org/xvif/regexp"
apply = "s/([0-9]+) decembre ([0-9]+)/2-12-1/"
]
if:validate [
type = "http://relaxng.org/ns/structure/1.0"
if:apply [
rng:data [
type = "date"
rng:param [ name = "minInclusive" "1900-01-01" ]
rng:param [ name = "maxInclusive" "2099-12-31" ]
]
]
]
]
]
element born { [ if:ignore = "1" ] text }In this example, I define a pipe (if:pipe) of 15
transformations (if:transform) using regular
expressions. Each converts one of the twelve months; a final
validation (if:validate) is itself using RELAX NG
to check that the result is a ISO 8601 date between 1900 and 2099.
The text pattern has an
if:ignore attribute, which shows XVIF-compliant
processors that it is a fallback pattern for other RELAX NG
processors.