Trang

Translator for RELAX NG Schemas

Copyright © 2002, 2003 Thai Open Source Software Center Ltd

See the file copying.txt for copying permission.

Version 2003-01-08

Trang translates schemas written in RELAX NG into different formats. In particular, it can

• translate a RELAX NG schema in the compact syntax into the XML syntax
• translate a RELAX NG schema in the XML syntax into the compact syntax
• translate a RELAX NG schema in either the XML or compact syntax into a DTD
• translate a RELAX NG schema in either the XML or compact syntax into a W3C XML Schema

Trang aims to produce human-understandable schemas; it tries for a translation that preserves all aspects of the input schema that may be significant to a human reader, including the definitions, the way the schema is divided into files, annotations and comments.

The implementation is available for download as

• a JAR file
• source code (this uses the Jing source code)

The main class is com.thaiopensource.relaxng.output.Driver.

Trang requires at least two command-line arguments: the first is the URI or filename of the schema to be translated; the second is the output filename.

Trang infers the input and output format from the extension of input and output filenames as follows:

.rng

RELAX NG (XML syntax)

.rnc

RELAX NG compact syntax

.dtd

XML 1.0 DTD

.xsd

W3C XML Schema

This inference can be overridden using the -i and -o options.

Trang accepts the following command-line options:

-i format

format specifies the input format as follows:

rng

RELAX NG (XML syntax)

rnc

RELAX NG compact syntax

-o format

format specifies the output format as follows:

rng

RELAX NG (XML syntax)

rnc

RELAX NG compact syntax

dtd

XML 1.0 DTD

xsd

W3C XML Schema

-e enc

Use the encoding enc for schema input and output.

DTD output

The DTD output module of Trang has many limitations. There are many RELAX NG features that it cannot handle, including:

• Wildcards
• Multiple element patterns with the same name
• externalRef
• overriding definitions (in an include)
• combining definitions with combine="choice"

However, Trang can handle many RELAX NG features, including some that go beyond the capabilities of DTDs. When some part of a RELAX NG schema cannot be represented exactly in DTD, Trang will try to approximate it. The approximation will always be more general, that is, the DTD will allow everything that is allowed by the RELAX NG schema, but there may be some things that are allowed by the DTD that are not allowed by the RELAX NG schema. For example, if the RELAX NG schema specifies that the content of an element is a string conforming to some datatype, then Trang will make the content of the element be (#PCDATA); or if the RELAX NG schema specifies a choice between two attributes x and y, then the DTD will allow both x and y optionally. Whenever Trang approximates, it will give a warning message.

If you want to be able to generate a DTD but need to use some feature of RELAX NG that Trang is unable to convert into a DTD, then you might try one of the following approaches:

• Create a RELAX NG schema including the features you need, and then use XSLT (or some other XML transformation language) to transform the schema into something that Trang can handle, perhaps making use of annotations in the schema to guide the transformation.
• Create a RELAX NG schema S₁ which uses only features that Trang can handle but which, consequently, does not capture all the desired constraints; then create a second RELAX NG schema S₂ that includes S₁, and overrides definitions in S₁ replacing them with definitions that make unrestricted use of the features of RELAX NG.

W3C XML Schema

This is still under active development. It currently has several limitations including:

• it may generate schemas that violate W3C XML Schema's restrictions on ambiguous content models;
• it may generate schemas that violate W3C XML Schema's restrictions on consistent element types;
• when the RELAX NG schema cannot be represented by W3C XML Schema, a generalization is generated; it should give a warning in this case, but does not always do so.

More information is available in the slides for a talk given a XML 2002.

Annotations can be added to the RELAX NG schema to guide the translation. These annotations have the namespace URI http://www.thaiopensource.com/ns/relaxng/xsd. This document will use the convention that the prefix tx refers to this namespace URI; in other words, it will assume a namespace declaration of

xmlns:tx="http://www.thaiopensource.com/ns/relaxng/xsd"

Currently, only one annotation is supported, an attribute tx:enableAbstractElements. The value of this must be true or false. It applies to RELAX NG define elements. Trang will try to translate a define that contains a choice of element patterns into an abstract element declaration, which will be used as the head of a substitution group whose members are the elements in the choice. If tx:enableAbstractElements="false" is specified, then trang will not do this (which means the define will typically be translated into a group definition).

The tx:enableAbstractElements attribute is inherited in a similar way to the ns attribute: it can be specified on a grammar, div or include element to enable or disable the use of abstract elements for all descendant define elements. In the absence of any inherited tx:enableAbstractElements attribute, the use of abstract elements in enabled.

It can happen that the same element name occurs in a choice in more than one define element; at most one of these define elements can be translated to an abstract element. In this case, trang will not translate any of them to an abstract element, unless the use of abstract elements has been disabled by tx:enableAbstractElements for all except one of the define elements.

In fact, the use of abstract elements is not restricted to the case where the define consists of a choice that contains only element patterns; the choice may also contain ref patterns referring to definitions that are to be translated into element declarations, whether abstract or not. The tx:enableAbstractElements attribute applies equally to these definitions.

Future plans

Trang is constructed around a RELAX NG object model designed to support schema conversion. Trang can support additional input and output formats simply by adding modules that convert these formats from and to this object model.

Features planned for future releases include:

• Enhance the DTD output module to support more features of RELAX NG
• Adapt DTDinst for use as a DTD input module

Related software

DTDinst translates from DTDs into RELAX NG; like Trang, it tries for a translation that preserves definitions and file structure. Trang can handle all the features in RELAX NG schemas generated by DTDinst.

The Sun RELAX NG Converter converts from a variety of different schema languages into RELAX NG. However, it is based on an object model which is designed to support validation, and so does not preserve aspects of the input schemas that are irrelevant for validation (such as the definitional structure).