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: 3
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: 85
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: 240
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: 3
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: 240
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 messageGo to next message
Thomas Nygreen is currently offline  Thomas Nygreen
Messages: 138
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
Re: [railML 3] Clarification regarding unused DistanceBasedCalculationRule element [message #4236 is a reply to message #4208] Mon, 12 October 2026 11:24 Go to previous messageGo to next message
Milan Wölke is currently offline  Milan Wölke
Messages: 240
Registered: April 2007
Senior Member
Hi Ricardo,

We discussed adding the DistanceBasedCalculationRule in the Timetable Developer group and agreed to include it with a slight modification.

Instead of the two previous parameters, absReserveTimeSecondsPerDistance and distanceMetres, we decided to use a single factor, distanceSupplement, specified in seconds per meter.

The reason for this change was to avoid ambiguity in how the rule should be applied. The group pointed out that the previous model could be interpreted as adding absReserveTimeSecondsPerDistance for every complete distanceMetres, rather than applying a proportional amount.

Using your previous example (absReserveTimeSecondsPerDistance = 600, distanceMetres = 100000), the distanceSupplement in the new model would be 0.006 s/m.

I hope this works for you as well, since the information remains the same. We will include the rule in this form in the 3.4 release candidate so that people can review it.

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 #4261 is a reply to message #4208] Tue, 27 October 2026 15:13 Go to previous messageGo to next message
Christian Rößiger is currently offline  Christian Rößiger
Messages: 85
Registered: March 2015
Member
Hello Thomas,

Thomas Nygreen wrote on Fri, 25 September 2026 14:03
Dear all,
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?

Unfortunately, I do not know exactly what the explanation “General as defined by UIC 451-1:2000” in the railML Wiki means for the railML value “general”. I also find the reference to “UIC 451” in this part of the railML schema problematic for two reasons:

1. UIC 451 includes both reserves “to improve timetable stability” and “due to scheduled trackwork”. If “general” were to stand for UIC 451, it would overlap in content with the values “qualityByInfrastructureManager” and “trackworkByInfrastructureManager”.

2. The reserve calculation of UIC 451 is usually made up of a distance-dependent (min/km) and a runtime-dependent (%) component. However, the <reserve> element only permits a maximum of one child element of type <rule>. Consequently, only the distance-dependent or the runtime-dependent component can be represented via the <rule>.

Although the mapping is not entirely consistent, I would assign the different types of reserves from UIC 451 to the railML types as follows:
- recovery margins -> qualityByInfrastructureManager
- supplementary margins -> trackworkByInfrastructureManager

In the railML schema I would remove the entire 'general' value from then enumeration. For reserves without a specific origin, we still have the "unspecified" value.
If we still need to declare a reserve time explicitely as "according to UIC 451", we could add a name and/or description subelement to the <reserve> element.

Best regards
Christian


Re: [railML 3] Clarification regarding unused DistanceBasedCalculationRule element [message #4262 is a reply to message #4236] Tue, 27 October 2026 15:38 Go to previous messageGo to next message
Christian Rößiger is currently offline  Christian Rößiger
Messages: 85
Registered: March 2015
Member
Hello Milan,

Milan Wölke wrote on Mon, 12 October 2026 11:24
The reason for this change was to avoid ambiguity in how the rule should be applied. The group pointed out that the previous model could be interpreted as adding absReserveTimeSecondsPerDistance for every complete distanceMetres, rather than applying a proportional amount.

Using your previous example (absReserveTimeSecondsPerDistance = 600, distanceMetres = 100000), the distanceSupplement in the new model would be 0.006 s/m.

I just wanted to ask again whether we’d prefer to use ‘min/km’ or ‘seconds/km’ as a unit. I know that kilometres aren’t an SI unit, but values in ‘seconds/m’ are very hard to understand for humans. These values also have to be displayed or entered somewhere within an application, so we’d inevitably have to convert them back and forth to ‘seconds/m’ for railML.

To point out, that the value is a proportional amount and not for every completed kilometre, I would consider a remark in the wiki as sufficent.

Best regards
Christian
Re: [railML 3] Clarification regarding unused DistanceBasedCalculationRule element [message #4263 is a reply to message #4236] Wed, 28 October 2026 16:36 Go to previous message
Ricardo Subtil is currently offline  Ricardo Subtil
Messages: 3
Registered: July 2026
Junior Member
Hi Milan,

Thanks for the followup. The change to a single distanceSupplement works without issue for our use-case, and in fact I do agree with this decision, as it also facilitates implementation by it having a railML-defined standardized unit.

Thanks,
Ricardo Subtil
Previous Topic: [railML 3] Qualifier for train times
Next Topic: [railML3] Move category from timetable to common
Goto Forum:
  


Current Time: Wed Nov 18 18:11:32 GMT+1 2026