TT:itinerary

Documentation

Syntax

Autoexport from the XML-Schema for element TT:itinerary of railML® version 3.3      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. If an itinerary is composed from two or more base itineraries the last base itinerary point of the ending base itinerary is used to define the arrival information for the resulting itinerary point while the first base itinerary point of the starting base itinerary is used to describe the departure information of that itinerary point. In case of an itinerary that is composed from a subset of a single base itinerary the same principle applies and the first base itinerary point defines the departure information for the resulting first stop of the enclosing itinerary. The last base itinerary point that is included in the enclosing itinerary specifies the arrival information at that last stop of the itinerary.
Subschema	timetable
Parents*	itineraries
Children	range (1..*)
Attributes: id: the identifier of the object; this can be either of type xs:ID or UUID (obligatory; xs:ID); 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.

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

There exists an overview of all changes between railML^® 3.1 and railML^® 3.2 on page Dev:Changes/3.2.

Introduced with version 3.2.

Changes 3.2→3.3

There exists an overview of all changes between railML^® 3.2 and railML^® 3.3 on page Dev:Changes/3.3.

The element documentation has been changed.

The parents have been changed.

The children have been changed.

The attributes have been changed.

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"/>
        <opEquipment>
          <ownsInfrastructureElement ref="tk-11"/>
        </opEquipment>
		</operationalPoint>
	</operationalPoints>
	...
      <tracks>
        <!-- Tracks at Kudowa -->
        <track type="mainTrack" id="tk-11">
          <name language="de" name="1b"/>
        </track>
      </tracks>
</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>

<itinerary> "it-2" imports both darker green arrow and the lighter green arrow representing the parts of "bi-5".

This example demonstrates that it is valid to base two or more 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.