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 the local folder where XMLSpy is installed into. This is typically "%PersonalFolder%/Altova/%AppAndVersionName%/" or, under Microsoft Windows, "%ProgramsFolder%/Altova/XMLSpy%Version%/".
• 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.

Apache Ant (with Xerces)

Apache Ant supports XML catalogs.

It includes catalog entries in its schemavalidate task, not conforming with OASIS XML Catalogs, but it works. :-)

• Use the "namespace name" for matching the schema.

  <schemavalidate file="myRailML.xml">
    <schema namespace="http://www.railml.org/schemas/2009" file="schema/railML.xsd"/>
  </schemavalidate>
  

• In order to assure full validation of well-formed XML against XML Schema you can use Xerces with some additional flags/parameter:

  <target name="xml-validate" description="Validate ${xml-file} against its schema files">
    <schemavalidate file="${xml-file}.xml" classname="org.apache.xerces.parsers.SAXParser">
      <schema namespace="http://www.railml.org/schemas/2009" file="railML-2-0/schema/railML.xsd"/>
      <attribute name="http://xml.org/sax/features/validation" value="true"/>
      <attribute name="http://apache.org/xml/features/validation/schema" value="true"/>
      <attribute name="http://xml.org/sax/features/namespaces" value="true"/>
      <attribute name="http://xml.org/sax/features/namespace-prefixes" value="true"/>
    </schemavalidate>
  </target>
  

  This way you have to define the property value of ${xml-file} with your to be validated railML file (e.g. "myRailML").

Note 1

Manual of xmlvalidate task states: "The schemavalidate task is better for validating W3C XML Schemas, as it extends this task with the right options automatically enabled, and makes it easy to add a list of schema files/URLs to act as sources."

Note 2

Look at the "xmlvalidate with xmlcatalog" thread (apache ant mailing list) for reasons not to use xmlvalidate.

Note 3

For all who want in spite of everthing test built-in catalog entries, look at the xmlcatalog manual.

Eclipse Webtools (WTP)

Eclipse Webtools (WTP) support 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.

Further railML related catalog entries

Dublin Core

Dublin Core Metadata Initiative (DCMI) provides an XML Schema (set) for metadata "to facilitate the finding, sharing and management of information".

railML integrates Dublin Core metadata with its metadata element.

How to define an XML catalog entry for Dublin Core metadata?

• Use of "namespace name":

  "http://purl.org/dc/elements/1.1/"

• Use of "schema location":

  "http://dublincore.org/schemas/xmls/qdc/dc.xsd"

• Point to local XML Schema dc.xsd

MathML

MathML provides XML Schema (set) for quite all mathematical expressions.

railML integrated MathML up to version 2.0 into its valueTable element.

Since railML 2.1 the inclusion of MathML in valueTable is optional. If you don't use it, you don't have to access MathML XML Schema files for validation purposes.

How to define an XML catalog entry for MathML?

• Use of "namespace name":

  "http://www.w3.org/1998/Math/MathML"

• Use of "schema location":

  "http://www.w3.org/Math/XMLSchema/mathml2/mathml2.xsd"

• Point to local XML Schema mathml2.xsd

xml.xsd

Since railML 2.0 outsourcing of subschema parts is allowed using XML Base implemented in the xml.xsd XML Schema.

Most XML validation tools have built-in support for this file and its attribute xml:base.

Nevertheless, how to define an XML catalog entry for xml.xsd?

• Use of "namespace name":

  "http://www.w3.org/XML/1998/namespace"

• Use of "schema location":

  "http://www.w3.org/2001/03/xml.xsd"

• Point to local XML Schema xml.xsd

---

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

Back to Common overview