Dev:catalog

Validating railML files

Structure and content types of railML files are defined in XML Schema. railML is based on a couple of such XSD files which require each other.

Basics

In order to validate the correct structure and syntax of your railML file, it has to comply the following conditions:

• The root element should be one of railml, infrastructure, rollingstock or timetable.

  <railml ...>

  ...

  </railml>

• The root element should contain an "attribute" which defines the reserved xsi namespace.

  <railml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  ...

  </railml>

• The root element should contain an "attribute" which defines the railML namespace.

  <railml xmlns="http://www.railml.org/schemas/2009" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  ...

  </railml>

  The example shows the simplified version using the default namespace definition.

  Example files in the railML repository show usage of namespace prefixes as alternative to the default namespace.

• The root element should contain an attribute which defines the file location of its XML schema.

  xsi:schemaLocation contains the railML namespace and an according file path to the XML Schema file (railML.xsd) separated by whitespace.

  This condition can be fulfilled using different mechanism. (see following subsections)

Local validation

The XML Schema files were downloaded to your local file system where your railML file is located.

• Absolute file path

  <railml xsi:schemaLocation="http://www.railml.org/schemas/2009 c:/project-railml/schema/railML.xsd"

  xmlns="http://www.railml.org/schemas/2009" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  ...

  </railml>

• Relative file path

  <railml xsi:schemaLocation="http://www.railml.org/schemas/2009 ../schema/railML.xsd"

  xmlns="http://www.railml.org/schemas/2009" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  ...

  </railml>

Note 1

You have to assure that all other XML Schema files are located in the same folder together with the file railML.xsd.

Note 2

If you transfer the railML file to partners they might not validate it. Either they have to adjust all file paths or you transfer the railML together with its XML Schema files.

Web-based validation

The XML Schema files are located on the railML Web-server.

• Web-based URI

  <railml xsi:schemaLocation="http://www.railml.org/schemas/2009 http://www.railml.org/schemas/2009/railML-2.0/railML.xsd"

  xmlns="http://www.railml.org/schemas/2009" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  ...

  </railml>

Note 3

Your local environment has to allow your validation tool to access the railML Web-server. There may be troubles with firewalls or something like that.

Validation using a local copy of the web-based URI (XML Catalog)

Your railML file contains the web-based URI as XML schema location but your validation tool knows the file path to a local copy of the XML schema set.

• Web-based URI

  <railml xsi:schemaLocation="http://www.railml.org/schemas/2009 http://www.railml.org/schemas/2009/railML-2.0/railML.xsd"

  xmlns="http://www.railml.org/schemas/2009" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  ...

  </railml>

This szenario uses the OASIS XML Catalogs specification. Your validation tool contains an XML catalog file which conforms the OASIS XML Catalogs requirements in structure and content.

• XML Catalog example

  <?xml version="1.0" encoding="UTF-8"?>

  <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

  <system systemId="http://www.railml.org/schemas/2009/railML-2.0/railML.xsd" uri="c:/project-railml/schema/railML.xsd"/>

  <uri name="http://www.railml.org/schemas/2009" uri="../schema/railML.xsd"/>

  </catalog>

The validation uses the first entry which matches either the "schema location" or the "namespace name" of your railML file.

• Schema location match

  <system systemId="http://www.railml.org/schemas/2009/railML-2.0/railML.xsd" uri="c:/project-railml/schema/railML.xsd"/>

  Attribute systemId in element system contains identically the same string as the xsi:schemaLocation attribute of your railML file.

  The validation tool uses the XML Schema at the uri file path instead of the web-based version.

• Namespace name match

  <uri name="http://www.railml.org/schemas/2009" uri="../schema/railML.xsd"/>

  Attribute name in element uri contains identically the same string as the xmlns attribute of your railML file.

  The validation tool uses the XML Schema at the uri file path instead of the declared path at the schemaLocation

Note 4

The uri attribute can specify absolute or relative file pathes.

Note 5

If you transfer the railML file to partners they might validate using the web-based schema location. Alternatively they could also create an XML catalog entry for railML and validate using a local copy. They don't have to touch the railML files.

Note 6

If you have defined such an XML catalog entry for railML it works for all railML files you create your own or get from others.

Implementation of XML catalogs in some XML validation tools

This is an to be completed list of XML validation tools supporting XML catalogs.

Altova XMLSpy

Altova XMLSpy supports XML catalogs.

• Edit the file named "CustomCatalog.xml" in your local "%PersonalFolder%/Altova/%AppAndVersionName%/" file path.
• Use the uri element with the "schema location" string.

  <uri name="http://www.railml.org/schemas/2009/railML-2.0/railML.xsd" uri="c:/project-railml/schema/railML.xsd"/>

• Restart Altova XMLSpy and validate your railML file.

Ant with Xerces

[to be added]

Eclipse

Eclipse supports XML catalogs.

• Select "Window > Preferences > XML > XML Catalog".
• Add new catalog entry with "Add".
• "Location" allows you browsing to your local XML Schema copy.
• For "Key Type" you can choose between "Namespace Name" and "Schema Location"
• The "Key" is by default filled with the "namespace name", alternatively you can enter the "schema location" string of your railML file.
• Re-start Eclipse and validate your railML file.

<oXygen/>

<oXygen/> supports XML catalogs.

• You have to create the catalog file, maybe supported by the according "Document Template".

  Use the system element with the "schema location" string

  <system systemId="http://www.railml.org/schemas/2009/railML-2.0/railML.xsd" uri="schema/railML.xsd"/>

• This file should be saved in your current project folder, typically as "catalog.xml".
• Select "Options > Preferences ... > XML > XML Catalog".
• Add current catalog file with "New".
• Re-start <oXygen/> and validate your railML file.

---

Please send any comments about validation handling and XML catalogs regarding named and unnamed tools to Common coordinator .