RELAX NG Shorthand Guide

$Id: ShortRNG.docbook,v 1.3 2001-08-17 11:31:19-07 bear Exp bear $

Distributed under GPL

Abstract

This document describes the functionality of RELAX NG short-hand processor.


Table of Contents

Introduction
How it works
References
"occurs" attribute
"minCccurs"/"maxOccurs" attributes
"type" attribute for <attribute> and <element>
Future Work & Conclusion

Introduction

RELAX NG is a nice schema language, but sometimes it is painful to type all tags by hand. For example, if you want to write an optional attribute (which is IMO very common), you need to type in:


<optional>

	<attribute name="attrName">

		<data type="NMTOKEN"/>

	</attribute>

</optional>

It becomes especially hard if you are using normal text editor.

The RELAX NG short-hand processor partially addresses this problem by providing several "short-hand" notations that makes schema authoring easier.

I wrote a RELAX NG schema for VoiceXML by using this short-hand processor and it took 690 lines. After the processing, RELAX NG schema becomes 1036 lines. So in this case, it saves nearly 1/3 of the typing. Your experience will vary, but I hope you find this processor useful.

How it works

First, you write a schema in the short hand notation. It is a superset of RELAX NG, so you can write it as if you are writing an ordinary RELAX NG schema.

The only difference is the namespace. RELAX NG short hand schema uses the namespace URI of "http://relaxng.sourceforge.net/ns/shorthand". The following is an example of RELAX NG short hand.


<grammar xmlns="http://relaxng.sourceforge.net/ns/shorthand"

  datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">

  

  <start>

    <ref name="abc"/>

  </start>

  

  <define name="abc">

    <element name="abc">

      <attribute name="xyz" type="NMTOKEN" occurs="?"/>

      <choice occurs="*">

        <element name="def">

          <empty/>

        </element>

        <element name="ghi">

          <empty/>

        </element>

      </choice>

    </element>

  </define>

</optional>

As you see, it's almost like normal RELAX NG, but you'll notice that the namespace URI is different and there are unfamiliar attributes (@occurs and @type).

The current processor is written in XSLT, so once you completed the schema, use XSLT processor to produce a normal RELAX NG schema. If you are using Windows, you can use msxsl tool as:

c:\>msxsl myschema.srng shortRNG.xsl > myschema.rng

And the produced "myschema.rng" file can be used with any RELAX NG compliant processor!

References

This section describes short hand notations

"occurs" attribute

RELAX NG shorthand allows you to write the "occurs" attribute to any pattern. The value of the attribute must be either "?"(optional), "*"(zeroOrMore) or "+"(oneOrMore). Its semantics is similar to the "occurs" attribute of RELAX Core. For example, if you write


<choice occcurs="*">

  <ref name="abc"/>

  <ref name="def"/>

</choice>

Then the result would be:


<zeroOrMore>

  <choice>

    <ref name="abc"/>

    <ref name="def"/>

  </choice>

</zeroOrMore>

"minCccurs"/"maxOccurs" attributes

RELAX NG shorthand allows you to write W3C XML Schema's "maxOccurs"/"minOccurs" attributes to any pattern. And these attributes will be expanded as expected. For example, if you write


<ref name="abc" minOccurs="2" maxOccurs="4" />

Then the result would be:


<ref name="abc"/>

<ref name="abc"/>

<optional>

  <ref name="abc"/>

  <optional>

    <ref name="abc"/>

  </optional>

</optional>

Of course you can write maxOccurs="unbounded", or omit one of the attributes.

"type" attribute for <attribute> and <element>

You can add the "type" attribute to an attribute element or an element element. If specified, the "type" attribute will be expanded to a child <data type="..."/> element. For example, if you write as


<attribute name="abc" type="NMTOKEN"/>

Then the final result will be:


<attribute name="abc">

	<data type="NMTOKEN"/>

</attribute>

You can also use a name class, too. For example, the following RELAX NG shorthand


<element type="NMTOKEN">

	<anyName/>

</element>

... will give you the following result:


<element>

	<anyName/>

	<data type="NMTOKEN"/>

</element>

Of course there is no restriction to combine the occurs attribute with the type attribute, which is pretty common. For example:


<attribute name="abc" type="NMTOKEN" occurs="?"/>

the above shorthand schema represents the optional "abc" attribute whose value must be NMTOKEN. After the processing, you'll get the following RELAX NG schema:


<optional>

	<attribute name="abc">

		<data type="NMTOKEN"/>

	</attribute>

</optional>

Future Work & Conclusion

If you've got an idea of another short-hand, please let me know!

I hope this simple idea would help your relaxing life.