Dev:catalog

From railML 2 Wiki
Revision as of 15:47, 29 January 2018 by RailML Coord Documentation (talk | contribs) (Ferri Leberl moved page CO:catalog to Dev:catalog: Vereinheitlichung)
Jump to navigation Jump to search

Defining namespaces and validating railML files

Structure and content types of railML files are defined in XML Schema (external link). railML is based on a couple of such XSD files which require each other.
Verwendung von XML Schemata (Wikipedia) (external link)

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. The value of the railML namespace is defined by the railML initiative and depends on the railML version. It can be assumed as an alias for the railML version. An overview of the existing namespace values can be found here: http://www.railml.org/index.php/download-archive.html (external link).
    • Default namespace
      <railml xmlns="http://www.railml.org/schemas/2009" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
       ...
      </railml>
      
    • Prefixed namespace
      <rail:railml xmlns:rail="http://www.railml.org/schemas/2009" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
       ...
      </rail:railml>
      
  • The root element should contain an attribute which defines the file location of the XML schema (XSD files) of the namespace defined above.
    xsi:schemaLocation contains the railML namespace (same value as above) and an according file path to the XML Schema file (railML.xsd) of that namespace, both separated by whitespace. This condition can be fulfilled using one of two different mechanisms (see following subsections).
Note
The XSD file location should be considered as nothing more than a "note" for the software which reads the railML file. Most validation tools allow overwriting of the Schema location as described below at Implementation of XML catalogs in some XML validation tools XML. The term catalog (as it is used here) refers to a kind of location list for XML namespaces. This is a major difference between the namespace value and its location: The namespace value is a unique identifier depending on the railML version and not to be varied by the writing software. The namespace location can be set to any value which the writing software finds appropriate.

Local Schema location and 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
It is recommended to use "forward slashes" / instead of backslashes \ (of the Microsoft Windows world) for better interoperability.
Note
You have to assure that all other XML Schema files are located in the same folder together with the file railML.xsd.
Note
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.
That's why it is assumed that local Schema location demands distributing of the corresponding XSD files.

Remote Schema location and validation

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

  • Remote 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
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.
Note
For testing unstable (not officially released) railML schemas from the Subversion repository the remote schema location should be used. See 'Exchange a railML file based on unstable schemas' at 'Versioning' for further explanations.

Validation using a local copy of the remote URI (XML Catalog)

This refers to "validating" a railML file using a common XML validation tool. Your railML file contains the remote URI as XML schema location but your validation tool knows the file path to a local copy of the XML schema set. This technology does not change the <railml> attributes as above mentioned.

  • Remote 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 scenario uses the OASIS XML Catalogs specification (external link). 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 remote 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
The uri attribute can specify absolute or relative file paths. Since a catalog entry applies to your local file system you have to consider using the appropriate path separator of your file system (\ or /).
Note
If you transfer the railML file to partners they might validate using the remote 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
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.

Remarks on railML 1

The above mentioned namespace definition and Schema location applies from railML 2 onwards. For railML 1, no namespace value has been defined at that time, so the namespace definition using xmlns cannot be used for railML 1. Nevertheless to define a Schema location the attribute xsi:noNamespaceSchemaLocation can be used. Thus, a typical railML 1 root element looks like that:

  • Local Schema location
    <railml version="1.00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="timetable_100.xsd">
     ...
    </railml>
    
  • Remote Schema location
    <railml version="1.00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.railml.org/schemas/2005/railML-1.0/timetable.xsd">
     ...
    </railml>
    

Implementation of XML catalogs in some XML validation tools

This is a to be completed list of XML validation tools supporting XML catalogs. The term catalog (as it is used here) refers to a kind of location list for XML namespaces.

Altova XMLSpy

Altova XMLSpy (external link) supports XML catalogs (external link).

  • 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 (external link) supports XML catalogs (external link).

It includes catalog entries in its schemavalidate task, not conforming with {{external|http://www.oasis-open.org/committees/entity/spec-2001-08-06.html%7COASIS 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
Manual of xmlvalidate task (external link) 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
Look at the "xmlvalidate with xmlcatalog" (external link) thread (apache ant mailing list) for reasons not to use xmlvalidate.
Note
For all who want in spite of everthing test built-in catalog entries, look at the xmlcatalog manual http://ant.apache.org/manual/Types/xmlcatalog.html xmlcatalog manual (external link).

Eclipse Webtools (WTP)

Eclipse Webtools (WTP) (external link) support XML catalogs http://www.eclipse.org/webtools/community/tutorials/XMLCatalog/XMLCatalogTutorial.html XML catalogs (external link).

  • 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/> http://www.oxygenxml.com/ <oXygen/> (external link) supports XML catalogs (external link).

  • 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) (external link) 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 http://www.w3.org/Math/ MathML (external link) 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 (external link) 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