RELAX NG Tools

RELAX NG has not been available as a standard as long as DTDs or W3C XML Schema, so there are fewer tools available for creating or editing RELAX NG files. Many of the most commonly used tools were written by the specification authors themselves. However, because RELAX NG is now an official OASIS standard, more tools are beginning to add support for RELAX NG. Two tools that support the creation of RELAX NG schemas are the Oxygen XML editor and Trang.

Oxygen

As described in Chapter 2, Oxygen is a full-featured XML editor. One of the features that make it unique among similar products is its support for RELAX NG schemas (both the XML form and the compact syntax).

You can create RELAX NG schemas in Oxygen using either a text-based or graphical editor. (RELAX NG compact schemas only allow text-based editing.) Figure 7-1 shows a split screen of the two editors displaying the same schema.

Figure 7-1

In this figure, the central editing area is composed of two parts: the top area is a graphical model of the schema structure, and the lower half is the text of the schema. Oxygen enables you to edit the schema using either section; the other is updated with the changes.

In addition to editing RELAX NG schemas, Oxygen includes a graphical interface to the Trang schema converter. This convertor (see Figure 7-2) enables you to convert between the XML syntax and compact syntax of RELAX NG, as well as convert a DTD into the corresponding RELAX NG schema.

Figure 7-2

Trang

Trang is a multiformat schema converter, originally written by James Clark (one of the authors of the RELAX NG specification). Internally, it uses the RELAX NG syntax, but it is capable of converting RELAX NG (both the XML and compact syntaxes), DTDs, and W3C XML Schemas. It is also capable of inferring a schema based on a number of XML documents. This last capability is useful for generating a schema after the fact based on a set of XML examples, such as when a throwaway format needs to be formalized.

Trang is written in Java and distributed in jar format. It is intended for use as a command-line tool, and has no associated GUI (although the Oxygen XML editor provides this support, see the previous section). The basic syntax using Trang is as follows:

      java -jar trang.jar -I <input format> -O <output format> -i <input options> -o      <output options> <input filename> <output filename> 

All of the options except the filenames are optional. The input and output formats will be inferred from the extensions of the filenames provided. You can override this behavior by adding the -I and -O options. There may be multiple input and output option items on the command line. Generally, these options are not needed, and the most common usage is to identify the encoding of the incoming or outgoing document. For example, the following command lines convert the DocBook 4.5 schema from DTD format to RELAX NG syntax, specify UTF-16 for the RELAX NG encoding, and set the indent to 4:

      java -jar trang.jar -o indent=4 -o encoding=UTF-16        C:\temp\docbook-xml-4.5\docbookx.dtd c:\temp\docbook\docbook4_5.rng 

The Trang convertor maintains the structure of the original schema. This means that if the original schema is defined using multiple documents (as with the DocBook DTD), then the resulting RELAX NG schema will use multiple files as well. Comments are also maintained.

Trang can also provide a shortcut approach to writing a schema by inferring the schema from the structure of a number of XML documents. This is useful if you have XML documents that you may have used informally, but for which you now need a format definition (for example, if an internal format will now need to be transmitted to another company). For example, Listing 7-20 shows three XML fragments. Each displays the same type of document, but in slightly different ways.

Listing 7-20: Converting schemas using Trang-Original XML files

      contacts1.xml      <contacts>        <contact name="Foo deBar" phone="[phone]"          email="[e-mail]" />        <contact name="Bob Sjeruncle" phone="[phone]"          email="[e-mail]" />      </contacts>      contacts2.xml      <contacts>        <contact>          <fullName>Foo deBar</fullName>          <email>[e-mail]</email>        </contact>        <contact>          <fullName>Bob Sjeruncle</fullName>          <email>[e-mail]</email>        </contact>      </contacts>      contacts3.xml      <contacts>        <contact >          <name>            <first>Foo</first>            <surname>deBar</surname>          </name>        </contact>        <contact >          <name>            <first>Bob</first>            <surname>Sjeruncle</surname>          </name>        </contact>      </contacts> 

You can generate a schema that applies to all three XML files using the following Trang command.

      java -jar trang.jar contacts1.xml contacts2.xml contacts3.xml contacts.rng 

This creates a merged schema that will validate each of the above contact listings (see Listing 7-21).

Listing 7-21: Converting schemas using Trang-RELAX NG Schema

      <?xml version="1.0" encoding="UTF-8"?>      <grammar ns="" xmlns="http://relaxng.org/ns/structure/1.0"        datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">        <start>          <element name="contacts">            <oneOrMore>              <element name="contact">                <optional>                  <attribute name="email"/>                </optional>                <optional>                  <attribute name="id">                    <data type="integer"/>                  </attribute>                </optional>                <optional>                  <attribute name="name"/>                </optional>                <optional>                  <attribute name="phone"/>                </optional>                <optional>                  <choice>                    <element name="name">                      <element name="first">                        <data type="NCName"/>                      </element>                      <element name="surname">                        <data type="NCName"/>                      </element>                    </element>                    <group>                      <element name="fullName">                        <text/>                      </element>                      <element name="email">                        <text/>                      </element>                    </group>                  </choice>                </optional>              </element>            </oneOrMore>          </element>        </start>      </grammar> 

The resulting RELAX NG schema includes a number of optional items, because the three XML files were structurally distinct. If the structure were more consistent, the resulting schema would be simpler. Notice also that the data type of some of the nodes (such as the id) is identified and added to the schema.

Although you will probably not need to convert schema formats very often, but there may be times when all you have is a schema in one format and you need it in a different format. Trang fills this need admirably-not only for RELAX NG schemas, but for W3C XML Schema and DTDs as well.