README for XML Zebra

Version 1.0-pre-2

http://www.xmlzebra.com/


What is XML Zebra?

XML Zebra is an XML Schema differencing tool that works by creating a "fingerprint" file for a set of Schemas. The "fingerprint" contains paths (like XPaths, but extended with extra information) that define what is allowed in valid XML documents for those Schemas. By comparing versions of the "fingerprint" files, both direct and indirect changes to the allowed XML can be detected between versions of the Schemas. The XML Zebra path syntax is described in the path syntax summary.

For more details about XML Zebra, see http://www.xmlzebra.com/.


How do you run XML Zebra?

You can run XML Zebra with either Scala or Java. You can also run it using Apache Ant.

How to run XML Zebra with Scala

  1. Download the Scala version of XML Zebra
  2. Unzip it into an empty directory
  3. Open a Windows "Command Prompt" or a Linux/Mac/etc. terminal window
  4. You must have Scala in your path. To test that you have Scala, run: scala -version
  5. Change directory to the directory where you unzipped XML Zebra
  6. For Windows, run: bin\xmlzebra.bat -o example\paths.xml example\xsd
  7. For Linux/Mac/etc., run: chmod 755 bin/xmlzebra.sh
  8. For Linux/Mac/etc., run: bin/xmlzebra.sh -o example/paths.xml example/xsd
  9. This processes the two XML Schemas from the "example/xsd" directory and saves the calculated path fingerprint, in XML format, in "example/paths.xml"
  10. The path file is not indented. Use an XML editor or formatting tool to indent it for readability, if required
  11. Alternatively, you can use the XSLT script "script/indent-xml.xsl" to indent the XML path file
  12. You can use the XSLT script "script/extract-sort-paths.xsl" to convert the XML path fingerprint into a textual list of paths
  13. Alternatively, if you have an XQuery processor like Saxon, you can use the XQuery "script/extract-sort-paths.xq" to convert the XML path fingerprint into a textual list of paths
  14. You can also set the namespace prefixes for the output file on the command line.
  15. For Windows, run bin\xmlzebra.bat -o example\paths2.xml example\xsd -xmlns:aa=http://xml.example.com/ns/testA -xmlns:bb=http://xml.example.com/ns/testB
  16. For Linux/Mac/etc., run bin/xmlzebra.sh -o example/paths2.xml example/xsd -xmlns:aa=http://xml.example.com/ns/testA -xmlns:bb=http://xml.example.com/ns/testB
  17. If you compare paths.xml and paths2.xml, you will see that the namespace prefixes are different in the two files. In paths.xml, the namespace prefixes were taken from the Schemas ("a" and "b"). In paths2.xml, the namespace prefixes are as set on the command line ("aa" and "bb")

How to run XML Zebra with Java

  1. Download the Java version of XML Zebra
  2. Unzip it into an empty directory
  3. Open a Windows "Command Prompt" or a Linux/Mac/etc. terminal window
  4. You must have Java in your path. To test that you have Java, run: java -version
  5. Change directory to the directory where you unzipped XML Zebra
  6. For Windows, run: bin\xmlzebra.bat -o example\paths.xml example\xsd
  7. For Linux/Mac/etc., run: chmod 755 bin/xmlzebra.sh
  8. For Linux/Mac/etc., run: bin/xmlzebra.sh -o example/paths.xml example/xsd
  9. This processes the two XML Schemas from the "example/xsd" directory and saves the calculated path fingerprint, in XML format, in "example/paths.xml"
  10. The path file is not indented. Use an XML editor or formatting tool to indent it for readability, if required
  11. Alternatively, you can use the XSLT script "script/indent-xml.xsl" to indent the XML path file
  12. You can use the XSLT script "script/extract-sort-paths.xsl" to convert the XML path fingerprint into a textual list of paths
  13. Alternatively, if you have an XQuery processor like Saxon, you can use the XQuery "script/extract-sort-paths.xq" to convert the XML path fingerprint into a textual list of paths
  14. You can also set the namespace prefixes for the output file on the command line.
  15. For Windows, run bin\xmlzebra.bat -o example\paths2.xml example\xsd -xmlns:aa=http://xml.example.com/ns/testA -xmlns:bb=http://xml.example.com/ns/testB
  16. For Linux/Mac/etc., run bin/xmlzebra.sh -o example/paths2.xml example/xsd -xmlns:aa=http://xml.example.com/ns/testA -xmlns:bb=http://xml.example.com/ns/testB
  17. If you compare paths.xml and paths2.xml, you will see that the namespace prefixes are different in the two files. In paths.xml, the namespace prefixes were taken from the Schemas ("a" and "b"). In paths2.xml, the namespace prefixes are as set on the command line ("aa" and "bb")

How to run XML Zebra with Apache Ant

  1. Download the Java version of XML Zebra
  2. Unzip it into an empty directory
  3. Open a Windows "Command Prompt" or a Linux/Mac/etc. terminal window
  4. You must have Java in your path. To test that you have Java, run: java -version
  5. You must have Apache Ant in your path. To test that you have Ant, run: ant -version
  6. Change directory to the directory where you unzipped XML Zebra
  7. Run: ant -f example/build.xml
  8. This processes the two XML Schemas from the "example/xsd" directory and saves the calculated path fingerprint, in XML format, in "example/paths.xml"
  9. It then creates an indented version of the XML file, "example/paths-indented.xml"
  10. Following that, it extracts the paths from the XML file into a text file, "example/paths.txt"
  11. Additionally, a second set of files is created user-defined namespace prefixes ("aa" instead of "a", "bb" instead of "b"). Have a look at "example/paths2-indented.xml" and "example/paths2.txt"

Last updated: 06 February 2010
XML Zebra is made available for use under the Apache 2.0 licence by Londata Limited.