Dev:Versions

Recommendations on version numbers

How to describe the version number of a RailML file? Or to find out which version a RailML file belongs to?

Version numbers

You will find a version attribute in the RailML root element <railml> as well as in the root elements of the sub-schemas as <infrastructure>, <rollingstock>, <timetable>, a. s. o.

This attribute is to be used for the version number of the RailML Schema the XML file is based on. This version number has the layout
<majorVersion>.<minorVersion>[rReleaseNumber]
e.g. 2.0, 1.1r4 or 2.0r271. Major version and minor version are separated by a dot, the optional release number is separated by r. The following rules apply:

• The release number shall be omitted if a RailML file is based on an official released RailML version. This applies to RailML 2.0r270 and 2.1r409 which both shall be given as 2.0 respectively 2.1 without release number.
• The release number shall be considered compulsory in all other cases, e. g. if it is not an official release version but an intermediate. For more information on the relevance of intermediate versions see Officially released versus developer version.
• The attribute version of the root element of the RailML file shall be considered compulsory. If the root element of the RailML file is <railml>, the attribute version of the subsequent elements <infrastructure>, <rollingstock>, <timetable>, a. s. o. are optional. If they are used, they have to be identical to the version of <railml> - no differences are allowed.

If the actual Schema is based on an official RailML Schema but has own minor changes, it is recommended to leave version with the original RailML version number and to use dc:format and/or dc:identifier for an own version number which describes the minor changes. (See also the description of these elements.) However, it is a question of how far the “minor changes” lead away from the original RailML schema. Normally, if compatibility is rather improbable, it should not be declared as RailML anymore and therefore explicitly use a version number (and namespace!) which cannot be mixed with the original RailML versions.

Common attributes depending on the RailML version

Both common attributes xmlns and xsi:schemaLocation depend at least indirectly on the RailML version. There are similar rules for these “namespaces” as for the versions.

The value of the railML namespace is defined by the railML initiative. A RailML file You have to use the namespace value which was released with the RailML version (as written in the XSD files). Not each RailML version needs to have an own namespace value. So some RailML versions may share the same namespace value. It is intended that each major version of RailML gets a new namespace value.

For general information about namespaces see Defining namespaces and validating railML files.

• A RailML file based on an official released RailML version must contain the namespace of the official version. This is
  
  • for RailML 2.0: http://www.railml.org/schemas/2009
  • for RailML 2.1: http://www.railml.org/schemas/2011
• A RailML file based on an intermediate release shall refer to the namespace of the previous (not the next) official version. This means, the last change from an intermediate release to a major version has to be the namespace value (and the version number, of course).

And, concerning web-based schema location:

• A RailML file based on an official released RailML with web-based schema location shall refer to the “railML.xsd” following the format <namespace>/railML-<version>/railML.xsd, e. g.
  • for RailML 2.0: http://www.railml.org/schemas/2009/railML-2.0/railML.xsd
  • for RailML 2.1: http://www.railml.org/schemas/2011/railML-2.1/railML.xsd
• A RailML file based on an intermediate release with web-based schema location shall refer to the Subversion repository of the release. This is http://trac.assembla.com/railML/export/<releaseNo>/trunk/schema/railML.xsd.

Examples

RailML file of official released RailML version 2.0, web-based schema location:

<?xml version="1.0" encoding="UTF-8"?>
<railml version="2.0"
  xmlns="http://www.railml.org/schemas/2009" 
  xsi:schemaLocation="http://www.railml.org/schemas/2009 http://www.railml.org/schemas/2009/railML-2.0/railML.xsd">
  ...
</railml>

RailML file of intermediate release #416 (between official releases 2.1 and 2.2) , web-based schema location:

<?xml version="1.0" encoding="UTF-8"?>
<railml version="2.1r416"
  xmlns="http://www.railml.org/schemas/2011" 
  xsi:schemaLocation="http://www.railml.org/schemas/2011 http://trac.assembla.com/railML/export/416/trunk/schema/railML.xsd">
  ...
</railml>