ONIX for Books 3.0 tagname converter

The ONIX tagname converters switch-onix-3.0-tagnames-1.1.xsl and switch-onix-3.0-tagnames-2.0.xsl are XSLT scripts that replace reference tagnames with short tagnames and vice versa. They work for all ONIX message files that are valid according to either the reference tag or short tag versions of the ONIX 3.0 DTD, both available from the EDItEUR website.

These two scripts are functionally equivalent, but use different versions of the XSLT scripting language to achieve the same results.

Equivalent tagname converters are also available for the ONIX Acknowledgement message.

WARNING It is essential that the correct script is used! Please check which XSLT engine you are going to use and which version of XSLT that this engine uses before installing the correct version of the ONIX tagname converter.

Care should also be taken to use the correct tagname converter for a given ONIX release. Separate tagname converters are available for conversion of ONIX files that conform to ONIX Release 2.1: these can be obtained from the ‘Previous Releases’ page in the 'ONIX for Books' section of the EDItEUR website.

Preparation and installation

You must first decide which of the two versions of the ONIX tagname converter script you need to use. This will depend upon which version of XSLT is supported by your chosen XSLT engine.

To run the script it is necessary first to choose and install an XSLT ‘engine’. Suitable engines include Saxon and Xalan. Saxon is obtainable from http://saxon.sourceforge.net/. Xalan is obtainable from http://xml.apache.org/. Various versions are available – if in doubt, choose an engine that is described as ‘stable’, such as Saxon version 6.5.5, Saxon-B version 9.1.0.8 or Saxon version 9.2 HE (later stable versions may be available).

The script switch-onix-3.0-tagnames-1.1.xsl relies upon some Saxon XSLT 1.1 extensions. There is a stand-alone executable version of Saxon for pre-XP versions of Microsoft Windows, called Instant Saxon, but this requires the Microsoft Java Virtual Machine, which is no longer available for Windows XP. The best solution is to install the Sun Java 2 Virtual Machine (available from http://java.sun.com/) and run the version of Saxon (preferably version 6.5.5) or Xalan that is available for the Java 2 platform.

The alternative version of the script, switch-onix-3.0-tagnames-2.0.xsl, relies upon some XSLT 2.0 functionality, and this can be used with Saxon version 8.7.1 or later.

The script will only work if the ONIX file that is to be converted is DTD VALID, ie it either contains a DTD declaration that links to a copy of the ONIX DTD stored locally on your PC or server, or it has been normalised to include all fixed attributes explicitly by pre-processing by a suitable XML parser, and in addition, it doesn’t contain any tag errors. It is a common error to try to convert tagnames on an unprocessed ONIX message that does not contain a DOCTYPE declaration.

Note that it is not currently possible to convert ONIX files that link only to the ONIX 3.0 XSD or RNG Schemas and there are no current plans to make this possible.

Download the relevant XSLT script here:

The script should be placed in a convenient directory/folder.

Running the script

The method of running the script is the same in each case, and involves the use of at least one parameter. The parameter result-document must always be included, and this specifies the file to which the output is written. The parameter dtd-path is optional, and is used to specify the system path to be specified in a DTD declaration in the output file; if omitted, no DTD declaration will be included in the output file.

If run from the command line, a typical invocation using Saxon 6.5.5 to convert from short to reference tags and include a DTD declaration would be:

java –jar {path-to-saxon-6.5.5} original-onix.xml switch-onix-tagnames-1.1.xsl result-document="converted-onix.xml" dtd-path="ONIX_BookProduct_3.0_reference.dtd"

Similarly, a typical invocation using Saxon 9.x to convert from reference to short tags and include a DTD declaration would be:

java –jar {path-to-saxon-9.x} original-onix.xml switch-onix-tagnames-2.0.xsl result-document="converted-onix.xml" dtd-path="ONIX_BookProduct_3.0_short.dtd"

Either XSLT script can also be used within an XML editing tool such as oXygen.


The XSLT tagname converters are provided ‘as is’ and are not warranted in any way by EDItEUR. EDItEUR provides no technical support for these tools other than this document. EDItEUR disclaims all responsibility for any errors and for all consequential inconvenience or cost associated with their use. Bug reports and other enquiries may be sent to EDItEUR (info@editeur.org) or to the original author Francis Cave (francis@franciscave.com).