TT:itinerary

Documentation

Syntax

Autoexport from the XML-Schema for element TT:itinerary of railML® version 3.2 UML-visualization of TT
Documentation	An Itinerary is created based upon one or several base itineraries. The base itineraries can be cut into parts and recombined for that. Additionally they can be transposed in time.
Subschema	timetable
Parents*	itineraries
Children	range (1..*)
Attributes: id: unique identifier (obligatory; xs:string; patterns: (urn:uuid:)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|{[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}}); compare: Dev:Identities
*Notice: Elements may have different parent elements. As a consequence they may be used in different contexts. Please, consider this as well as a user of this wiki as when developing this documentation further. Aspects that are only relevant with respect to one of several parents should be explained exclusively in the documentation of the respective parent element.

This element does not appear in railML^® 3.1 within the TT subschema. It is available only in railML^® 3.2. Do not hesitate to contact railML.org for further questions.

Changes 3.1→3.2

Introduced with version 3.2.

Best Practice / Examples

For these examples it is assumed that the reader is familiar with the concept of <baseItinerary> of railML3.

Combining base itineraries

Interpreting path

This example is based on the Advanced example infrastructure (link to the railML^® website). This example will show how to combine base itineraries to form new itineraries. Please note that the data provided for stations, tracks etc. in this example is very limited and does not reflect the typical level of detail provided in a railML document.

<infrastructure>
...
<operationalPoints>
  <operationalPoint id="op-3">
    <name language="de" name="Cranz"/>
  </operationalPoint>
  <operationalPoint id="op-4">
    <name language="de" name="Dunja"/>
  </operationalPoint>
  <operationalPoint id="op-5">
    <name language="de" name="Eimber"/>
  </operationalPoint>
  <operationalPoint id="op-6">
    <name language="de" name="Funera"/>
  </operationalPoint>
  <operationalPoint id="op-7">
    <name language="de" name="Grestin"/>
  </operationalPoint>
  <operationalPoint id="op-9">
    <name language="de" name="Intersee"/>
  </operationalPoint>
  <operationalPoint id="op-11">
    <name language="de" name="Kudowa"/>
  </operationalPoint>
</operationalPoints>
...
</infrastructure>
...
<timetable>
...
<baseItineraries>
...
<baseItinerary id="bi-4">
  <baseItineraryPoint id="bp-8" locationRef="op-5">
    <times scope="operational">
      <departure time="11:44:30"/>
    </times>
    <stop>
      <isCommercial/>
    </stop>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-9" locationRef="op-4">
    <times scope="operational">
      <arrival time="11:54:30"/>
      <departure time="11:55:30"/>
    </times>
    <stop>
      <isCommercial onRequest="true"/>
    </stop>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-10" locationRef="op-3">
    <times scope="operational">
      <arrival time="11:58:30"/>
    </times>
    <stop>
      <isCommercial/>
    </stop>
  </baseItineraryPoint>
</baseItinerary> 
...     
<baseItinerary id="bi-5">
  <baseItineraryPoint id="bp-11" locationRef="op-3">
    <times scope="operational">
      <departure time="12:01:30"/>
    </times>
    <stop>
      <isCommercial/>
    </stop>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-12" locationRef="op-6">
    <times scope="operational">
      <arrival time="12:03:30"/>
      <departure time="12:04:30"/>
    </times>
    <stop>
      <isCommercial onRequest="true"/>
    </stop>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-13" locationRef="op-7">
    <times scope="operational">
      <arrival time="12:09:30"/>
      <departure time="12:11:30"/>
    </times>
    <stop>
      <isCommercial onRequest="true"/>
    </stop>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-14" locationRef="op-9">
    <times scope="operational">
      <arrival time="12:12:30"/>
      <departure time="12:12:30"/>
    </times>
    <pass/>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-15" locationRef="op-11">
    <times scope="operational">
      <arrival time="12:15:30"/>
    </times>
    <trackRef ref="tk-11"/>
    <stop>
      <isCommercial/>
    </stop>
  </baseItineraryPoint>
</baseItinerary>
...
</baseItineraries>
<itineraries>
...
<itinerary id="it-7">
  <range baseItineraryRef="bi-4" start="bp-8" end="bp-10" offset="-PT11M"/>
  <!-- shortened base itinerary -->
  <range baseItineraryRef="bi-5" start="bp-11" end="bp-13" offset="-PT11M"/>
</itinerary>
...
</itineraries>
</timetable>

The above example of <itinerary> "it-7" combines <baseItinerary>s "bi-4" and a part of "bi-5". Together they describe the path from Eimber to Grestin. Originally the <baseItinerary> "bi-4" describes a path from Eimber via Dunja to Cranz, while <baseItinerary> "bi-5" describes a path from Cranz to Kudowa, over the intermediate operating <operationalPoint>s Funera, Grestin and Intersee. For <itinerary> "it-7" only the first 3 <baseItineraryPoint>s of <baseItinerary> "bi-5" are used. This is indicated by the @end attribute of the <itinerary:range>.

In order to combine 2 <baseItinerary>s the intersecting <baseItineraryPoint>s are expected to reference the same <operationalPoint> in this case Cranz. The resulting itinerary combines the information of the intersecting <baseItineraryPoint>s. Information regarding the arrival is taken from the last <baseItineraryPoint> of the ending <baseItinerary> (segment), while information regarding the departure is taken from the first <baseItineraryPoint> of the starting <baseItinerary> (segment).

The resulting <itinerary> schedule looks like this:

<operationalPoint>	Arrival time	Departure time
Eimber	-	11:33:30
Dunja	11:43:30	11:44:30
Cranz	11:47:30	11:50:30
Funera	11:52:30	11:53:30
Grestin	11:58:30	-

Please note that the last station is not listed with a departure time although the matching <baseItineraryPoint> does specify a departure time. The reason for this is that the range of "bi-5" which is imported into the <itinerary> "it-7" ends in Grestin. This means that any further information included in the <baseItinerary> is not considered in the resulting itinerary.

Please also note that the listed times above are shifted by -11 min. This is a result of the offset specified at the range importing the two <baseItinerary>s into the "it-7".

Visualization

The blue arrow represents <baseItinerary> "bi-4", while the green arrows represent <baseItinerary> "bi-5". The darker green arrow represents the part of "bi-5" that is imported into <itinerary> "it-7", while the lighter green arrow represents the part that is not imported.

Reusing base itineraries

Timetable from above can be extended with following itinerary:

      <itinerary id="it-2">
        <range baseItineraryRef="bi-4" start="bp-8" end="bp-10" offset="-PT10M"/>
        <range baseItineraryRef="bi-5" start="bp-11" end="bp-15" offset="-PT10M"/>
      </itinerary>

This example demonstrates that it is valid to base two itineraries on the same <baseItinerary>.

This way railML3 approach helps to reduce redundancy in code. Even though users can define a set of base itineraries specifically for new "it-2", the best practice of railML3 is to reuse the existing base itineraries as much as possible moving them in time with @offset attribute if needed.

Programmers may find parallels in object oriented programming to understand railML3 timetable model easily.