From railML 3 Wiki
Jump to navigation Jump to search
A timetable for a competition (call for proposals)
Subschema: Timetable and Rostering
Related subschemas: IS RS 
Reported by: iRFP
Stift.png (version(s) not yet specified)
For general information on use cases see UC:Use cases

Use case / Anwendungsfall

proposal for a railML® use case:

A timetable for a competition (call for proposals) Ausschreibungsfahrplan

Description / Beschreibung

The use case describes a timetable which is transferred

  • from an authority issuing the invitation to bid
  • to any potential bidder

with the aim to describe which timetable is asked for in the competition, i. e. the amount of trains, their routes and (regular) operating days and possible any other properties of the trains such as services or minimum seating capacities.

The background behind such a data exchange with railML® files is, especially at competitions of large production amount, it will be easier for the bidders to reproduce the timetable in their own software systems. This allows a quicker calculation e. g. of the number of vehicles necessary or, at least, the price. Time consuming and potential faulty manual transcription of the timetable shall be avoided. The usage of railML® for such a data exchange (instead of more special file formats) shall keep this procedure transparent and non-discriminating.

The main intention of the use case is passenger traffic since the number of trains and the extent of the timetables is typically more complex than in freight traffic. But it may also be used for freight traffic.

Data Flows and Interfaces / Datenflüsse und Schnittstellen

The use case covers a one-direction data exchange only; a possibly offered timetable (from bidder to authority) is not part of this use case.

The use case covers the exchange of the following data in general:

  • <train> elements with their routes and timings (in associated <trainPart> elements),
  • <ocp> elements to describe the references from the trains to the infrastructure (stations).

There are several degrees of complexity of which the use case may be used:

  • with minimum infrastructure (general <ocp>s only) or all necessary infrastructure (<lines>, <track>s, gradients, speeds a. s. o.),
  • with or without <vehicle>s and <formation>s,
  • with or without a timetable period,
  • with or without circulation plans.

The following description refers to the usage of railML® model 2.2 for this use case since there is no version 3 in use at time of writing.


From the current experience, it is typical that railML® files of that use case contain a minimum infrastructure only. The main reason for that may be that normally the authority issuing is not the infrastructure manager. Nevertheless, general infrastructure data are quite published in a competion as a kind of “passing through” issue from the infrastructure manager(s) through the issuing authority. So it may be that they are included in the same railML® with the timetable. With the advent of national infrastructure registers, it is likely that such registers are referred or extracted in another, say, railML® file.

Anyway, <ocp>s must be included since without them no railML® <timetable> file is possible. <lines> and <tracks> are included if necessary to exactly describe the train’s route in complex infrastructure situations (areas of parallel lines). More infrastructure data (gradients, speed a. s. o.) are rather a matter of the previous paragraph.

It shall be assumed that a timetable of this use case is checked by the infrastructure manager(s) in advance and therefore planned in detail.

If more infrastructure is included, its scope is macroscopic.

Timetable period

Typically there is no <timetablePeriod> for timetables of this use case. The timetable is valid not for a certain but a number of years which are not specified in the railML® file.

The <operatingPeriod>s of the trains have regular weekdays only with no special operating days and no certain date references. The timetables are typically not planned with regard to public holidays or such; the amount of train kilometers a. s. o. is only calculated on a statistic basis (flat number of operating days, statistic year).

However, there may be a <timetablePeriod> defined for one year as a place-holder for all the years. This is common practice if seasonised trains operate, e. g. school trains or summer-only trains.

Theoretically, there may be a very long <timetablePeriod> for all the years the timetable shall be valid. Since this leads to very long bitmasks of <operatingPeriod>s with normally no additional benefit it is not common and not recommended.

<vehicle>s and <formation>s

If the supply of vehicles is component of the competition, often there are neither vehicles nor formations given with the timetable data because this is treated necessary for non-discrimination. However, for practical reasons, normally there is a master vehicle at least for run-time calculation. This is often the slowest acceptable vehicle and may be a theoretical one (a coefficient of power and mass only). It is common to publish this master vehicle with the call for tenders. If the vehicles are allocated there is no reason to exclude them from the timetable.

So, there may or may not be <rollingstock> data in the railML® file.

Circulation plans

Typically the construction of circulation plans is up to the bidder, so no circulation plans are included. This is likely to be because neither the type (and capacity) of the vehicle(s) nor the location of the depot(s) are known in advance. On the contrary, and even if the vehicles are allocated, circulation plans are expected from the bidders to show their competence. However if the organization that calls for proposals is offering vehicles of their own for operation on the infrastructure in questions, circulations are included in the exchanged data.

References to other data models or outside-world / Referenzen zu anderen Datenmodellen einschl. Nicht-Software-Daten

  • In any case, <ocp>s refer to one or more national register(s) of stations or other operational places by their <designator> elements. So, it is mandatory to use at least one <designator> with a pre-defined register. For Germany, this is currently register='RL100'.
  • If <line> elements are included, it must be possible to identify the <line> elements with the lines of the corresponding infrastructure manager. This can be done directly from attributes of the <line> elements or indirectly from attributes of the <track> elements. For Germany, currently the <line>.code attribute has to contain the VzG-Streckennummer, so it must be a 4-digit integer value.
  • If <track> elements are included, it must be possible to identify the <track> elements with the tracks of the corresponding infrastructure manager. This can be done by a unique attribute of the <track> elements (like code) or by a direction of the track in conjunction with the <line>s. For Germany, if <track> elements are included, also <line> elements have to be included. Each <track> element must be part of (referenced by) exactly one <line> element.
  • With regard to neutral (non-discriminating) data, the <category> elements do not necessarily need to refer to actual train categories of a certain operator. They can refer to categories of the corresponding infrastructure manager if applicable - or they can be missing or even contain "phantasy" categories. For Germany, since the kind of operator can still be deduced from the DB Netz’s category codes, it is likely to have "neutralised" categories. If <category>s are used, their attribute code has to be unique.
  • Since the timetable is more a virtual than an actual one, <train> elements are not necessarily to be identified externally. So, train codes nor numbers need not to be given. However, for reasons of practicability, it shall be possible to uniquely identify a train. For Germany, operational trains need to have a unique set of the attributes trainNumber, additionalTrainNumber, and scope (default railML® rules). Commercial trains need to have a unique trainNumber (additionalTrainNumber and scope do not apply here).

Interference with other railML® schemas / Interferenz mit anderen railML®-Schemen

  • <infrastructure> (mandatory)
  • <rollingstock> (optional)

<infrastructure> is referenced

  • from <ocpTT>.ocpRef to <ocp>.id (mandatory),
  • from <sectionTT>.lineRef to <line>.id (optional),
  • from <sectionTT>.<trackRef>.ref to <track>.id (optional)
  • from <trainPartSequence>.<speedProfileRef>.ref to <speedProfile>.id (optional)

<rollingstock> is referenced

  • from <formationTT>.formationRef to <formation>.id (optional)
  • from <rostering>.formationRef to <formation>.id (optional)
  • from <rostering>.vehicleRef to <vehicle>.id (optional)

Characterizing Data / Charakterisierung der Daten

This section serves to specify the required data regarding certain aspects.

How often do the data change (update)?

  • static (not changing)
  • in cases of error-corrections: weekly .. daily in rare cases during a short period (of submission); will probably be handled by a complete data renewal (overriding)

How big are the data fragments to be exchanged (complexity)?

  • infrastructure: medium (region), macroscopic
  • timetable: medium (region; several up to some hundred trains); operatingPeriod: tiny (one or none)
  • rolling stock: small (none, one or a few vehicles and formations)

Which views are represented by the data (focus)?

Long term planning (starting typically 1..5 years in future with a duration of typically 3..15 years)

Which specific data do you expect to receive/send (elements)?

Used elements (extract - more is allowed):

Element Mandatory Remarks
<infrastructure>.<tracks>.<track>.<trackTopology>.<trackBegin>.<macroscopicNode>.ocpRef <infrastructure>.<tracks>.<track>.<trackTopology>.<trackEnd>.<macroscopicNode>.ocpRef <infrastructure>.<tracks>.<track>.<trackTopology>.<crossSections>.<crossSection>.ocpRef *1 used to define the conjunction between <track>s and <ocp>s if <track>s are included
<infrastructure>.<trackGroups>.<line>.code *2 used to identify a line of the Infrastructure Manager(s)
<infrastructure>.<trackGroups>.<line>.infrastructureManagerRef used to identify the Infrastructure Manager(s) at least if more than one is involved
<infrastructure>.<trackGroups>.<line>.<trackRef>.ref *2 used to define the conjunction between <line>s and <tracks>s
<infrastructure>.<operationControlPoints>.<ocp>.<designator>.register / .entry x used to identify an <ocp> of the Infrastructure Manager(s)
<timetable>.<timetablePeriods>.<timetablePeriod>.startDate / .endDate
<timetable>.<operatingPeriods>.<operatingPeriod> x
<timetable>.<operatingPeriods>.<operatingPeriod>.timetablePeriodRef / .bitMask must be used if a <timetablePeriod> is included only
<timetable>.<operatingPeriods>.<operatingPeriod>.<operatingDay>.operatingCode x
<timetable>.<operatingPeriods>.<operatingPeriod>.<operatingDay>.<operatingDayDeviance>.operatingCode / .holidayOffset / .ranking
<timetable>.<operatingPeriods>.<operatingPeriod>.<specialService>.type / .startDate / .endDate can be used if a <timetablePeriod> is included only
<timetable>.<categories>.<category>.code used to identify a train type or category of the Infrastructure Manager(s) or a virtual one
<timetable>.<trainParts>.<trainPart> x
<timetable>.<trainParts>.<trainPart>.<formationTT>.<passengerUsage>.<places>.category / .count may be used to define a minimum necessary seating capacity
<timetable>.<trainParts>.<trainPart>.<formationTT>.<passengerUsage>.<service>.category / .count may be used to define a minimum acceptable service
<timetable>.<trainParts>.<trainPart>.<operatingPeriodRef> x
<timetable>.<trainParts>.<trainPart>.<ocpsTT>.<ocpTT>.ocpRef x
<timetable>.<trainParts>.<trainPart>.<ocpsTT>.<ocpTT>.<times scope='scheduled' …> x
<timetable>.<trainParts>.<trainPart>.<ocpsTT>.<ocpTT>.<times scope='scheduled'>.arrival / .departure> / .arrivalDay / .departureDay (x) mandatory in context as usual
<timetable>.<trainParts>.<trainPart>.<ocpsTT>.<ocpTT>.<sectionTT>.lineRef must be used if <line>s are included
<timetable>.<trainParts>.<trainPart>.<ocpsTT>.<ocpTT>.<sectionTT>.<trackRef>.ref must be used if <track>s are included
<timetable>.<trainParts>.<trainPart>.<ocpsTT>.<ocpTT>.<stopDescription>.commercial / .stopOnRequest
<timetable>.<trainParts>.<trainPart>.<ocpsTT>.<ocpTT>.<stopDescription>.<stopTimes>.minimalTime (x) mandatory in context for ordered traffic stops
<timetable>.<trains>.<train type='operational'> x each <trainPart> must be covered by exactly one operational train
<timetable>.<trains>.<train type='commercial'> used if operational trains are not sufficient to describe the timetable (especially with train coupling and sharing)
<timetable>.<trains>.<train>.trainNumber / .scope / .additionalTrainNumber
<timetable>.<trains>.<train>.<trainPartSequence> x
<timetable>.<trains>.<train>.<trainPartSequence>.sequence x
<timetable>.<trains>.<train>.<trainPartSequence>.<trainPartRef> x
<timetable>.<trains>.<train>.<trainPartSequence>.<trainPartRef>.ref / .position x

*1 mandatory if <track>s are included
*2 mandatory if <line>s are included

Additional requirements

Each <trainPart> must be covered by exactly one operational train. If commercial trains are given, each <trainPart> must be covered by exactly one commercial train.

If seating capacities or services are defined at <trainPart>s and at <formation>s or <vehicle>s, later defined values override earlier defined values in the meaning of concretising. Formations override vehicles, train parts override formations. In this special use case, the values at <trainPart>s shall be treated as minimum necessary values and the values at <formation>s or <vehicle>s as planned capacity of the master vehicle(s).

If minimum seating capacities differ for certain operating days (at the same train and route section), the corresponding train has to be split in several <trainPart>s with parallel route and disjunctive operating days. Each <trainPart> can refer to a different seating capacity. All these <trainPart>s have to be joined in the corresponding <trainPartSequence>s.

(This procedure also applies to other properties of trains and train parts. Train parts with disjunctive operating days do not have to be mixed with coupled train parts, which apply to train coupling, sharing and "strengthening". See corresponding descriptions for further information.)

Open Issues

  • Usage of tTimeScope="earliest" / ="latest" instead of or additionally to ="scheduled".
  • Defining (planned and/or expected) connections between the <train>s involved and also to other (external) <train>s.

Improvements for further versions

To be exact, the current railML® (railML 2.x) does not allow a distinction between values which are the minimum necessity and which are planned. There may be a difference between them especially in the use case of timtables for competitions. This applies to

  • arrival / departure / run times (planned run time with a master formation vs. maximum accepable run time with any other formation)
  • seating capacities (planned seating capacity with a master formation vs. minimum accepable seating capacity)
  • connections

and possibly more.

In the current implementation of railml® 2.x it is not clearly defined how two <trainPart> elements in succeeding <trainPartSequence>s must be chained to model a running through service (group of vehicles). One approach is to chain all <trainPart> elements with the same key (code, name, etc.) in an order whereat the last referenced <ocp> of the current <trainPart> is the same as the first <ocp> of the following <trainPart>. (This order can already be deduced from commercial train elements.) A better modelling for this aspect is, in the author’s opinion, to use the concept of commercial trains in a different way than currently described in Wiki: Each commercial train should model exactly one sequence of <trainPart> elements. Today it may contain several "parallel" sequences of <trainPart> elements at the same time, which makes it impossible to figure out which <trainPart> elements of two succeeding <trainPartSequence>s must be linked together.

The redundancy of repeated arrival and departure times of coupled <trainPart>s shall be avoided e. g. by extracting "itineraries" (refactoring).