Dev:Versions

From railML 2 Wiki
(Redirected from Dev:versioning)
Jump to navigation Jump to search
🗒️ This page is mirrored from page Dev:Versions in The railML® 3 Wiki.  

Version numbers and corresponding namespaces

🗒️ 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. The attribute version of the root element of the railML® file shall be considered mandatory.

This official railML® version number should not be confused with an implementation dependent software version in the <metadata> elements dc:format and/or dc:identifier.

Private-cloud-icon.png Semantic Constraint "CO:001":
 
Any starting time stamp (as it may result e.g. from a combination of startDate and startTime) shall be lower or equal any ending time stamp (e.g. endDate) if both are given. Must not overlap with the validity periods of other entries of the same register of the same enclosing element.
 
Proposed on November 12th 2018
Approved on March 21st 2019
FIXME Forum missing

Please, recognize our guidelines on semantic constraints 

Namespace declarations

As above mentioned the XML Namespace (Wiki banner.png) does also change with the railML® version. The following table shows this relationship for all official railML® versions.

railML® version number railML® namespace string Remote schema location HTTPS access Service Release[1] Wiki adapted since
1.0 no namespace different schema locations for sub-schemas no No longer supported No wiki documentation
1.1 http://www.railml.org/schemas/2007 https://schemas.railML.org/2007/railML-1.1/railML.xsd no No longer supported No wiki documentation
2.0 http://www.railml.org/schemas/2009 https://schemas.railML.org/2009/railML-2.0/railML.xsd yes, optional No longer supported No longer supported
2.1 http://www.railml.org/schemas/2011 https://schemas.railML.org/2011/railML-2.1/railML.xsd yes, optional No longer supported No longer supported
2.2 http://www.railml.org/schemas/2013 https://schemas.railML.org/2013/railML-2.2/railML.xsd yes, optional No longer supported No longer supported
2.3 http://www.railml.org/schemas/2016 https://schemas.railML.org/2016/railML-2.3/schema/railML.xsd yes, optional No longer supported No longer supported
2.4 https://www.railml.org/schemas/2018 https://schemas.railml.org/2018/railML-2.4/schema/railML.xsd yes, mandatory Final 2019
2.5 https://www.railml.org/schemas/2021 https://schemas.railML.org/2021/railML-2.5/schema/railML.xsd yes, mandatory SR2 SR2: July 28th 2025
3.0 (alpha & beta only) https://www.railml.org/schemas/2015 Alpha & Beta phases finished no No longer supported No wiki documentation
3.1 https://www.railml.org/schemas/3.1 https://schemas.railML.org/3.1/railml3.xsd yes, mandatory Final 2019
3.2 https://www.railml.org/schemas/3.2 https://schemas.railML.org/3.2/railml3.xsd yes, mandatory SR4 SR4: July 28th 2025
3.3 https://www.railml.org/schemas/3.3 https://schemas.railML.org/3.3/railml3.xsd yes, mandatory SR1 SR1: July 28th 2025

The XML file should declare the same XML Namespace (Wiki banner.png) (identical string) as defined by its corresponding XML Schema. For general information about namespaces see Defining namespaces and validating railML® files.

A railML® file based on an intermediate release with remote schema location shall refer to a commit on our development platform. This is

  • for railML® 2: https://development.railml.org/railml/version2/-/commit/<commit hash>
  • for railML® 3: https://development.railml.org/railml/version3/-/commit/<commit hash>

For instance commit 5f735749 (railML® 2) can be found under https://development.railml.org/railml/version2/-/commit/5f735749. It corresponds to commit [416] of our legacy Apache Subversion Control (Wiki banner.png) (SVN).
Commit 6e7d61fa (railML® 3) can be found under https://development.railml.org/railml/version3/-/commit/6e7d61fa and corresponds to SVN commit [1026].

Licenses

All currently supported railML® versions are licensed dually under a restricted form of the Creative Commons licence (Wiki banner.png) CC-BY-NC-ND and (for certified programmes) in a commercial licence. To learn more about the licence terms see https://www.railml.org/en/licence (link to the railML® website).

Examples

railML file of official released railML version 2.0, remote schema location: 

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

railML file of official released railML version 3.1, remote schema location: 

<?xml version="1.0" encoding="UTF-8"?>
<railML xmlns="https://www.railml.org/schemas/3.1" 
        xmlns:dc="http://purl.org/dc/elements/1.1/"
        xmlns:gml="http://www.opengis.net/gml/3.2/"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://www.railml.org/schemas/3.1 https://www.railml.org/schemas/3.1/railml3.xsd"
        version="3.1">
  ...
</railML>

Glossary

Major Release

  • Reason - major restructuring of the model or changes to the philosophy.
  • Decision - tagging a major release after railML® conferences' consensus.
  • Version number - increasing first digit, e.g. version="2.0", version="3.0".
  • Namespace - changing the year in the namespace string, e.g. xmlns="https://www.railml.org/schemas/2021” for railML 2.5 and xmlns=”https://www.railml.org/schemas/3.1” for railML 3.1.

Minor Release

railML2

  • Reason - you can add new elements and attributes but cannot remove them. Committed changes have no effect on XML-instance files, but on other coordinators' XSD-schema files. Commits of new elements, types and/or attributes are allowed.
  • Decision - tagging a minor release after railML® conference.
  • Version number - increasing second digit, e.g. version="2.1".
  • Namespace - up to railML® 2.x the year and version changed in the namespace string. This means that for every minor version a new namespace is defined.

railML 3

Up to railML 3.2
  • Reason - removal and renaming of elements that exist in the previous version can only be removed after a deprecation phase. Changes that only add elements, even mandatory ones are allowed.
  • Decision - tagging a minor release after railML® conference.
  • Version number - increasing second digit, e.g. version="3.1".
  • Namespace - the namespace is changed with each minor version, e.g. xmlns="https://www.railml.org/schemas/3.2".
From railML 3.3 on
  • Reason - changes from one minor version to the next are allowed without a deprecation phase. This allows changes that may happen without a deprecation phase, such as:
    • Renaming elements, attributes or enumeration values
    • Changing the minOccurs or maxOccurs of an element
    • Changing the use of an attribute (optional or mandatory)
    • Changing between xs:sequence, xs:choice and xs:all
    • Removals that are not replaced by something new
  • Decision - tagging a minor release on railML® conference.
  • Version number - increasing second digit, e.g. version="3.3".
  • Namespace - the namespace is changed with each minor version, e.g. xmlns="https://www.railml.org/schemas/3.3".

Service release

  • Reason - service releases contain an improved documentation of the XSD as well as to .xmi (Wiki banner.png) and minor corrigendum[2], but unchanged data exchange structure. Therefore the existing interfaces with their results (by the partner programmes) remain unchanged as well as certifications and documentations.
  • Decision - usually, service release of a version is published when enough additional documentation or corrigendum is gathered.
  • Version number - version does not change for service release. ZIP archive is tagged.
  • Namespace - namespace does not change for service release.

Beta (release candidate)/Developers Version

railML2

  • Reason - beta is needed for testing and reviewing. In railML2 beta is called release candidate (e.g. railML-2.5-RC).
  • Decision - user requirements from the forum are kept in the railML® ticket system. For railML 2 they can be found at https://development.railml.org/railml/version2/-/issues . The railML® coordinators prioritize them, code each single topic in a XSD and commit changed files into the Git repository.
  • Version number - tagging a beta after railML® coordinators' consensus.
  • Namespace - namespace does not change for Beta version.

railML 3

  • Reason - beta is needed for testing and reviewing. For railML 3final version is abbreviated as railML-3.2-final.
  • Decision - user requirements from the forum are kept in the railML® ticket system. For railML 3 they can be found https://development.railml.org/railml/version3/-/issues. The railML® coordinators prioritize them, code each single topic in Enterprise Architect (software) (Wiki banner.png) and commit changes into the Git (Wiki banner.png) repository. The XSDs and documentation are generated from the Enterprise Architect model.
  • Version number - tagging a beta after railML® coordinators' consensus.
  • Namespace - namespace does not change for Beta version.
  1. ↑ https://wiki3.railml.org/wiki/Dev:Versions#Service_release
  2. ↑ [a881cdcfa4dcc1a6de061b304d17147dfd688b7f]
Retrieved from "https://wiki2.railml.org/index.php?title=Dev:Versions&oldid=15683"