Home » railML newsgroups » railml.timetable » [railML 3] Clarification regarding unused DistanceBasedCalculationRule element
[railML 3] Clarification regarding unused DistanceBasedCalculationRule element [message #4084] Mon, 20 July 2026 15:21 Go to next message
Ricardo Subtil is currently offline  Ricardo Subtil
Messages: 2
Registered: July 2026
Junior Member
Good afternoon!

While working on import functionality of railML 3.2 timetable schema for our software, I noticed the existence of a DistanceBasedCalculationRule element in the railML 3.2 schema. It looks to be entirely unused, but judging by its semantics, it appears to be a specialization of another rule element for followup sections and calculated reserve times, akin to the existing timeBasedRule.

We would like to use this element as is currently in the schema, since it fits our use-case nicely, without modifications necessary. When communicating calculated reserve times, we need to document the original distance based property for our software to reconstruct the information at import time. Here's an example of how we would use this element in an actual railML export:

<!-- 5 minutes -->
<reserve reserve="PT5M">
  <rule>
    <!-- 10 minutes every 100 kilometres (100000 metres) -->
    <distanceBasedRule referenceDistanceMeters="100000" supplement="PT10M" />
  </rule>
</reserve>

The only extension we would require in our software would be to allow this element to be present in the rule element. However we need some clarification if this element should be used as I described. While I believe we have a legitimate use-case for it, it was also subsequently deleted from the upcoming 3.4 version, suggesting a deprecation path.

Kind regards,
Ricardo Subtil
Re: [railML 3] Clarification regarding unused DistanceBasedCalculationRule element [message #4088 is a reply to message #4084] Thu, 06 August 2026 10:18 Go to previous messageGo to next message
Christian Rößiger is currently offline  Christian Rößiger
Messages: 82
Registered: March 2015
Member
Hello Ricardo,

I recall that the railML 3.2 specification was intended to support different rules for runtime reserves. Unfortunately, I cannot explain why, in the end, only one rule made it into the final version, and why this second rule element nevertheless remained in the XSD as a type definition without being used in the schema. As the current modelling of the `rule` element was explicitly designed to allow for extensions, I see no reason why a `distanceBasedRule` could not also be included in a future version of railML.

Ricardo Subtil wrote on Mon, 20 July 2026 15:21

<!-- 5 minutes -->
<reserve reserve="PT5M">
  <rule>
    <!-- 10 minutes every 100 kilometres (100000 metres) -->
    <distanceBasedRule referenceDistanceMeters="100000" supplement="PT10M" />
  </rule>
</reserve>

The only extension we would require in our software would be to allow this element to be present in the rule element. However we need some clarification if this element should be used as I described. While I believe we have a legitimate use-case for it, it was also subsequently deleted from the upcoming 3.4 version, suggesting a deprecation path.

I don't know how the rule represented by the 'distanceBaseRule' element actually works, so I'm unable to evaluate if you're using the element in the right way. In particular, it is unclear for me how distances that aren't multiples of 'referenceDistanceMeters' are handled. I would therefore suggest that you specify your rule or send us your own XML/XSD proposal and we introduce a new rule element explicitly for your needs. I'd rather not recycle something when I can't remember what it was originally intended for.

Best regards
Christian Rößiger
Re: [railML 3] Clarification regarding unused DistanceBasedCalculationRule element [message #4089 is a reply to message #4088] Mon, 10 August 2026 19:35 Go to previous messageGo to next message
Milan Wölke is currently offline  Milan Wölke
Messages: 235
Registered: April 2007
Senior Member
Hi Ricardo,
the reason why the distanceBasedCalculation rule didnt make it into the release was actually, that we didnt know if there was a demand for it. It was not part of any use case we knew about and in consequence we couldnt tell if the element actually was suitable to describe what we want to describe with these rules. The idea is allow importing systems to follow up the logic that lead to the supplement times specified. Basically, exactly like what you wrote. If you say, that this would be useful to you, I can only agree with Christian, please provide us with some description of how you are using it, and what the calculation behind that would be so we can add that to our documentation. I could imagine this to be a late addition for the upcoming 3.4. The reason why the type was removed from 3.4 is simple, we wanted to clean up orphaned types, but of course this could be reversed if there is need for the element.

Assuming that you are want to stay on 3.2, however, this would probably not help you right away. What I would recommend you in this case would be to create an extension of the type RuntimeReserveCalculationRule and add an element of the DistanceBasedCalculationRule type to the choice. If you are unsure, how to do that, please take a look at https://wiki3.railml.org/wiki/Dev:Using_xsi:type.

So in summary, for 3.2, feel free to use the type from the schema in your extension, and for 3.4, we would really appreciate, if you could explain a little on how that calculation is done in your system, so we could add this to the upcoming release.

Best regards, Milan


Milan Hoffmann – Timetable schema coordinator
railML.org (Registry of Associations: VR 5750)
Altplauen 19h; 01187 Dresden; Germany www.railML.org
Re: [railML 3] Clarification regarding unused DistanceBasedCalculationRule element [message #4201 is a reply to message #4089] Mon, 21 September 2026 12:16 Go to previous messageGo to next message
Ricardo Subtil is currently offline  Ricardo Subtil
Messages: 2
Registered: July 2026
Junior Member
Hello Christian & Milan,

We are currently targeting only railML 3.2, and in that regard the only modification we require on our schema is to allow the distanceBasedRule to be added to a rule element, as the distance element itself requires no additional modification to accomodate our use case.

To go into a bit more detail on that, our software TPS.plan allows assigning optional, customer-specific data to trains, a concept we call "reference codes", which largely consist of key-value pairs that affect train information in various areas.

One such code is "Absolute Reserve per Distance", which is a quantity of time (in seconds) to be added to a train's reserve time per each 100Km travelled. This property is then used during runtime calculation, based on the train's itinerary and distance between stations.

To re-use the previous railML example, let's say we have a train travelling between stations A and B, with the travel distance being 50Km (50000 metres). An operator defines on our software an additional distance reserve time of 10 minutes (600 seconds) per 100Km. This would result in an additional reserve time of 5 minutes (300 seconds) being considered for this itinerary portion, according to the following formula:

reserveTimeSeconds = (absReserveTimeSecondsPerDistance * distanceMetres) / 100000
                   = (600 * 50000) / 100000
                   = 300

In regards to how this works for "... distances that aren't multiples of 'referenceDistanceMeters'", I see no issues due to two reasons:

  • The formula above allows distances smaller than the reference distance, which is our interpretation of the current distanceBasedRule specification. The provided example is also one such case of this.
  • The rule element has an informational nature only, detailing how the given time value was calculated. So any inaccuracies in the rule are mitigated by this; the specification states that the value to be considered (aka the "source of truth") is the reserve attribute of the reserve element:

    • rule: "A runtime reserve calculation rule can be provided for ducumentation purposed."
    • reserve: "The rule element can be used to further explain the value of this attribute, the field value however is the leading data here."
    • minimalTime: "Between two base itinerary points several runtime reserves can be specified independently from each other. The actual runtime of the train in a section is calculated by adding the minimum runtime to the sum of all supplements."
Thanks,
Ricardo
Re: [railML 3] Clarification regarding unused DistanceBasedCalculationRule element [message #4204 is a reply to message #4201] Tue, 22 September 2026 10:44 Go to previous messageGo to next message
Milan Wölke is currently offline  Milan Wölke
Messages: 235
Registered: April 2007
Senior Member
Hi Ricardo,

thanks for the explanation. I will add this to the agenda of the next timetable developer meeting. I have already modelled the restoration of the distance based calculation rule in a branch of our git repo. Given the approval of the timetable developers this will still get added to 3.4. This will not help you with railML 3.2, but it may help others when implementing railML 3.4 and may also make it easier for you to migrate to a newer version of railML later on. Thanks for sharing.

Best regards, Milan


Milan Hoffmann – Timetable schema coordinator
railML.org (Registry of Associations: VR 5750)
Altplauen 19h; 01187 Dresden; Germany www.railML.org
Re: [railML 3] Clarification regarding unused DistanceBasedCalculationRule element [message #4208 is a reply to message #4204] Fri, 25 September 2026 14:03 Go to previous message
Thomas Nygreen is currently offline  Thomas Nygreen
Messages: 137
Registered: March 2008
Senior Member
Dear all,

Ricardo's case is also how recovery margins are given in UIC 451-1: "A recovery margin should be expressed as a combination of distance-based margins (min/km) and journey time-based margins (%)." The UIC leaflet provides minimums per 100 km based on vehicle type and additional percentage minimums based on vehicle type, tonnage and line speed.

This is also the basis for the timetabling standard we use at Jernbanedirektoratet. But we convert the distance-based margins into a percentage for each speed interval, and then add the two components together as one percentage per speed interval.

While mentioning UIC 451-1, I have a related question: reserve/@type provides the option "general", documented as "General as defined by UIC 451-1:2000". Does this mean any of the reserve types defined in UIC 451-1? Or is it supposed to refer to a definition of "general" in UIC 451-1? The defines four terms: basic running time (this already includes mean performance variations), recovery margin, supplementary margin and standard running time (the sum of the previous three). How can one separate between the recovery margin and supplementary margin using reserve/@type?

Best regards,
Thomas


Thomas Nygreen – Common Schema Coordinator
railML.org (Registry of Associations: VR 5750)
Altplauen 19h; 01187 Dresden; Germany www.railML.org
Previous Topic: [railML3] Move category from timetable to common
Goto Forum:
  


Current Time: Sun Oct 11 19:11:49 GMT+2 2026