Dev:SemanticConstraints

Semantic constraints
 

XML Schema Definitions (XSDs) offer a variety of possibilities to define syntactic constraints, describing the syntax of an XML file, including the type and multiplicity of an element. For example in railML^® 2, it is possible to describe and validate that a <train> must reference one or more <trainPart>s, that all <trackElements> must have a position on the <track>, that the length of a <tunnel> is a decimal number and that allowed positions of <couplers> are at the front, rear or both ends of a <wagon>. However, XML Schema Definitions are not able to express a constraint on one element or attribute that depends on the value or existence of another element or attribute. One example is that an XSD cannot express that a departure time must be greater than or equal to the arrival time, or that it does not make sense to specify a stopOnRequest and at the same time that the train is not allowed to stop. Such rules restricting the contents, or semantics, of one element or attribute depending on other content, are called semantic constraints.

Semantic constraints are as important as syntactic constraints. If they are ignored, other software may not be able to handle your railML^® files, or may interpret the contents in different ways. Therefore, their implementation will be checked during certification.

Elements with approved semantic constraints are listed in Category:Semantic constraints. On the element documentation pages, the semantic constraints can be found in a dedicated chapter below the syntactic constraints. Proposed semantic constraints are listed in Category:Semantic constraints_proposed. A list of the semantic constraints by introduction date of a can be found below.

Every application of railML^® has to be checked not only on XSD compliance but also on the obedience to the semantic constraints.

How to introduce Semantic Constraints

Before proposing a semantic constraint, please note:

• The purpose of semantic constraints is to restrict the allowed values of one property depending on the values of other properties.
• Descriptions of the meaning of an element or property belong in the schema documentation. This includes how (not) to interpret or use possible values of a property.
• Constraints that can be described by XML Schema Definitions (XSDs) should be implemented syntactically in the schemas. Please, follow the guideline for participating in the development process. If a constraint cannot be described by XML Schema Definitions, you can propose a semantic constraint.

Semantic constraints can be proposed either by one of the railML^® working groups (link to the railML^® website) or suggested by anyone through the following process:

1. If you see the need for a semantic constraint beyond the schema, please propose it in the forum (link to the railML^® website). The responsible schema coordinator will bring it to the relevant working group or directly to the group of coordinators.
2. If there is consensus in a working group to add a new semantic constraint, a post will be made in the forum and the proposed constraint will be defined in Template:Switch/Dev:SemanticConstraints using Template:DefSemcon, with status=proposed, and added to the respective article and to the list below. The details are explained at Template:DefSemcon#Workflow. The other working groups will also be notified, so they can check if the proposed constraint affects their use cases.
3. After the community has been given a reasonable time to raise any objections in the forum, the coordinators will decide if the proposed semantic constraint is approved. Following this decision, the documentation will be updated accordingly.

🗒️ Semantic constraints that have been proposed before the 10th of December 2018 shall be considered as approved until decided otherwise.

🗒️ The process above was revised in January 2025, adding a decision by the group of coordinators to replace automatic approval when no objections were raised within six weeks after a new semantic constraint was proposed in the forum. The coordinators will also review the semantic constraints listed below, as not all of them have followed the previous process. The list may therefore change.

Design guidelines

• Implement a seperate semantic constraint for every rule.
• Remember that all new semantic constraints must be proposed in the forum (link to the railML^® website)
• Use the template with all mandatory arguments according to Template:SemanticConstraint.
• Record the semantic constraint on the respective list below (Dev:Semantic_Constraints/table2 for railML^® 2 and Dev:Semantic_Constraints/table3 for railML^® 3).
• assign a serial id to the semantic constraint according to the appropriate list below.

Current Constraints as of railML 2.x

View/edit list on the separate source page.

ID	Text	Status	Proposed	Approved	Deprecated	Forum	Instances
CO:001	Any starting time stamp (as it may result e.g. from a combination of startDate and startTime) shall be lower or equal any ending time stamp (e.g. endDate) if both are given. Must not overlap with the validity periods of other entries of the same register of the same enclosing element.	approved	2018-11-12	2019-03-21		FIXME Forum missing	CO:designator IS:designator impairmentSection IS:designator ocp IS:designator state IS:designator state with length
CO:002	Any starting time stamp (as it may result e.g. from a combination of startDate and startTime) shall be lower or equal any ending time stamp (e.g. endDate) if both are given.	approved	2018-11-12	2019-03-21		FIXME Forum missing	CO:phase Template:InheritDesignator RS:designator TT:circulation TT:operatingPeriod TT:operatingPeriodRef trainPart TT:specialService operatingPeriod TT:specialService operatingPeriodRef
IS:002	The value of @pos in <trackBegin> is always the lowest value of all specified <trackElements> and <ocsElements>. It is always lower than the value of @pos of <trackEnd>. The value of @pos in <trackEnd> is always the highest value of all specified <trackElements> and <ocsElements>. It is always higher than the value of @pos of <trackBegin>. Subtracting the value of @pos in <trackBegin> from the value of @pos in <trackEnd> will result in the length of the enclosing <track>. If two <track>s are connected, the @absPos values of the connected <trackBegin> and <trackEnd> must be identical if both are provided and no <mileageChange> is defined at this point and both <track>s belong to the same mileage system.	proposed	2019-06-17	Not yet approved		FIXME Forum missing	IS:trackEnd
IS:003	The value of @pos in <trackBegin> is always the lowest value of all specified <trackElements> and <ocsElements>. It is always lower than the value of @pos of <trackEnd>. The value of @pos in <trackEnd> is always the highest value of all specified <trackElements> and <ocsElements>. It is always higher than the value of @pos of <trackBegin>. Subtracting the value of @pos in <trackBegin> from the value of @pos in <trackEnd> will result in the length of the enclosing <track>. If two <track>s are connected, the @absPos values of the connected <trackBegin> and <trackEnd> must be identical if both are provided and no <mileageChange> is defined at this point and both <track>s belong to the same mileage system.	proposed	2019-06-17	Not yet approved		FIXME Forum missing	IS:trackBegin
IS:006	Define attributes @absPosIn and @absPos for "real" mileage changes Define attribute @absPosIn alone in case of an ending mileage Define attribute @absPos alone in case of a starting mileage For starting mileages and "real" mileage changes, the @absDir has to be given to define the ongoing orientation of the mileage	proposed	2019-06-19	Not yet approved		FIXME Forum missing	IS:mileageChange
IS:008	An <ocp> with <propOperational>@operationalType=blockSignal shall not have @mode=manned (as a manned blockSignal shall be modelled in railML® 2.x as a blockPost).	proposed	2020-02-20	Not yet approved		FIXME Forum missing	IS:uptime
IS:009	An <ocp> with attribute <propOperational>@operationalType=stoppingPoint shall not have @mode=manned (as a stoppingPoint has no operational usage and therefore no operational staff by the IM).	proposed	2020-02-28	Not yet approved		FIXME Forum missing	IS:uptime
IS:010	An enumeration of several time periods by @from and @until for one <ocp> shall not overlap so that for every time there shall be a unique status of <uptime>.	proposed	2020-02-28	Not yet approved		FIXME Forum missing	IS:uptime
IS:012	If a <speedProfile> is marked with @basicSpeedProfile=true the attribute @influence shall have the value increasing.	proposed	2022-03-14	Not yet approved		#424	IS:speedProfile
IS:013	@influence=increasing: The <speedProfile> increases the permitted speed. If multiple "increasing" speed profiles are applicable, select the one with the highest @vMax value. @influence=decreasing: The <speedProfile> decreases the permitted speed. If multiple "decreasing" speed profiles are applicable, select the one with the lowest @vMax value. If this value is lower than the speed of an "increasing" speed profile, it overrides that speed.	proposed	2022-03-14	Not yet approved		#424	IS:speedProfile
IS:014	Define the tunnel resistance factor @resistanceFactorPassenger resp. @resistanceFactorFreight only if @kind and @crossSection are not known.	proposed	2022-03-14	Not yet approved		FIXME Forum missing	IS:tunnel
IS:015	When specifying @parentOcpRef for an <ocp> circles are not allowed. That means that when following the chain of @parentOcpRef no <ocp> shall be visited twice.	approved	2022-07-14	2022-08-11		Approved during the timetable developer group meeting on 2022-08-11	IS:ocp
IS:020	Any starting time stamp (as it may result from @startDateTime or a combination of @operatingPeriod and @startTime) shall be lower or equal any ending time stamp (as it may result from @endDateTime or a combination of @endDayOffset and @endTime) if both are given. Must not overlap with other <state> validity periods of the same enclosing <states> collection. See also Dev:Defining_temporal_availability_of_infrastructure_elements_and_speed_profiles	approved	2018-11-12	2019-03-21		FIXME Forum missing	IS:state
IS:021	Any starting time stamp (as it may result from @startDateTime or a combination of @operatingPeriod and @startTime) shall be lower or equal any ending time stamp (as it may result from @endDateTime or a combination of @endDayOffset and @endTime) if both are given. Must not overlap with other <state (with length)> validity periods of the same enclosing <states (with length)> collection. See also Dev:Defining_temporal_availability_of_infrastructure_elements_and_speed_profiles	approved	2018-11-12	2019-03-21		FIXME Forum missing	IS:state with length
RS:002	Any starting time stamp (as it may result e.g. from a combination of startDate and startTime) shall be lower or equal any ending time stamp (e.g. endDate) if both are given. Must not overlap with other <operator> validity periods of the same enclosing <vehicle>/<classification>.	approved	2018-11-12	2019-03-21		FIXME Forum missing	RS:operator
RS:003	Any starting time stamp (as it may result e.g. from a combination of startDate and startTime) shall be lower or equal any ending time stamp (e.g. endDate) if both are given. Must not overlap with other <owner> validity periods of the same enclosing <vehicle>/<classification>.	approved	2018-11-12	2019-03-21		FIXME Forum missing	RS:owner
RS:004	Any starting time stamp (as it may result from @startDateTime or a combination of @operatingPeriod and @startTime) shall be lower or equal any ending time stamp (as it may result from @endDateTime or a combination of @endDayOffset and @endTime) if both are given. Must not overlap with other <state> validity periods of the same enclosing <vehicle>/<states>.	approved	2018-11-12	2019-03-21		FIXME Forum missing	RS:state
TT:001	Any starting time stamp (as it may result e.g. from a combination of startDate and startTime) shall be lower or equal any ending time stamp (e.g. endDate) if both are given. Must not overlap with other validity periods. TT:001	approved	2018-11-12	2019-03-21		FIXME Forum missing	TT:timetablePeriod
TT:002	The attribute sequence is shall be increasing according to the train path. Das Attribut sequence muss ansteigend entsprechend dem Zuglauf sein.	approved	2018-10-25	2019-06-20		FIXME Forum missing	TT:ocpTT ocpsTT patternTrainPart TT:ocpTT ocpsTT trainPart
TT:003	By means of a <blockPart> it is possible to model both journeys with and without reference to a <trainPart> within a roster, as well as services without change of location (without reference to a <trainPart>). These 3 basic types are distinguished by the attribute mission. The following table presents the semantic constraints: Mit Hilfe eines <blockPart> können innerhalb eines Umlaufplans sowohl Fahrten mit und ohne Referenz auf einen <trainPart> abgebildet werden, als auch Dienste ohne Ortsveränderung (ohne Referenz auf einen <trainPart>). Unterschieden werden diese 3 Grundtypen anhand des Attributs mission. In der folgenden folgende Tabelle werden die semantischen Abhängigkeiten gegenüber gestellt: attributes of <blockPart> mission trainPartRef startOcpRef / endOcpRef begin / end, beginDay / endDay runLength trip with reference to a <trainPart> timetable mandatory redundant to referenced <trainPart>, must be empty or without contradiction to referenced <trainPart> trip without reference to a <trainPart> fullRun, emptyRun shall not be used mandatory mandatory optional service all other values shall not be used mandatory, startOcpRef = endOcpRef mandatory optional	approved	2019-06-13	2019-07-18		FIXME Forum missing	TT:blockPart
TT:004	vehicleRef and formationRef shall not be used within the same blockPart, since a blockPart is either one for a certain vehicle or one for a whole formation. The only exception to this rule is if the formation consists of only one vehicle that is also specified via vehicleRef. Es ist nur entweder vehicleRef oder formationRef anzugeben (nicht jedoch beide gleichzeitig), da es sich entweder um einen Blockpart eines Einzelfahrzeugs oder einer Fahrzeuggruppe handelt. Die einzige zulässige Ausnahme stellt der Fall dar, dass die angegebene Formation ausschließlich aus dem über vehicleRef angegbenen Fahrzeug besteht.	approved	2019-06-20	2019-07-18		FIXME Forum missing	TT:blockPart
TT:005	vehicleRef and formationRef are to be used exceptional since the circulation plan is either one for a certain vehicle or one for a whole formation. The only exception to this rule is if the formation consists of only one vehicle that is also specified via vehicleRef Es ist nur entweder vehicleRef oder formationRef anzugeben (nicht jedoch beide gleichzeitig), da es sich entweder um einen Umlauf eines Einzelfahrzeugs oder einer Fahrzeuggruppe handelt. Die einzige zulässige Ausnahme stellt der Fall dar, dass die angegebene Formation ausschließlich aus dem über vehicleRef angegbenen Fahrzeug besteht.	approved	2019-05-22	2019-06-25		FIXME Forum missing	TT:rostering
TT:006	The following table summarises the semantical constraints between the attributes <ocpTT>.ocpType, <stopDescription>.guaranteedPass, .commercial, .onOff, .stopOnRequest and .operationalStopOrdered: Green cells are default values. ocpType='begin','end' are deprecated from railML® 2.2. If no <stopDescription> is given, it is either a non-guaranteed pass (1.2) or a stop with undefined properties, depending on the attribute ocpType. The term "commercial" of the attribute in railML® traditionally refers to the contractual relationship between RU and end-customer, not to the contractual relationship between IM and RU. The term "ordered" in the attribute operationalStopOrdered refers to the contractual relationship between IM and RU.	approved	2018-09-03	2019-06-20		FIXME Forum missing	TT:stopDescription ocpTT ocpsTT patternTrainPart TT:stopDescription ocpTT ocpsTT trainPart
TT:008	The representation of differentiated track usage must not result in differences in arrival and departure times. In these cases, a separate <trainPart> / <train> with different arrival and departure times must be created. Die Abbildung unterschiedlicher Gleisnutzungen darf keine Unterschiede in den Ankunfts- und Abfahrtszeiten zur Folge haben. In diesen Fällen muss ein separater <trainPart> / <train> mit abweichenden Ankunfts-/Abfahrtszeiten angelegt werden.	approved	2018-08-21	2019-06-20		FIXME Forum missing	TT:trackInfo originalTrackInfo
TT:009	The operating days of the <operatingPeriodRef>s of the individual <trackInfo> entries must be disjoint and must not contain more traffic days than the parent <trainPart>. If fewer traffic days are provided in the <trackInfo> entries than the parent <trainPart> contains, the information (e.g. attribute trackInfo) of the parent <ocpTT> must be evaluated for these operating days. Die Verkehrstage der <operatingPeriodRef>s der einzelnen <trackInfo>-Einträge müssen untereinander disjunkt sein und dürfen nicht mehr Verkehrstage als der übergeordnete <trainPart> enthalten. Werden durch die <trackInfo>-Einträge weniger Verkehrstage abgedeckt, als der übergeordnete <trainPart> aufweist, so sind für diese Verkehrstage die Angaben (z.B. Attribut trackInfo) der übergeordneten <ocpTT> zu verwenden.	approved	2018-08-21	2019-06-20		FIXME Forum missing	TT:trackInfo originalTrackInfo TT:trackInfo stopDescription ocpTT ocpsTT patternTrainPart TT:trackInfo stopDescription ocpTT ocpsTT trainPart
TT:012	When @scope='actual' is used, then the operating period and/or timetable period specified at the trainpart level shall refer to only one operating day. Like this the operating day to which the actual times refer is defined. Wenn @scope= 'actual' verwendet wird, bezieht sich die operating period und/oder timetable period des train(part) auf nur einen einzelnen Betriebstag. Es muss so festgelegt werden, auf welchen Betriebstag sich die erfassten Ist-Zeiten beziehen.	approved	2019-06-19	2022-06-02		FIXME Forum missing	TT:times ocpTT ocpsTT patternTrainPart TT:times ocpTT ocpsTT trainPart
TT:014	@arrival is not to be specified if the attribute ocpType of the parent <ocpTT> has the value pass - use departure for run-through (passing) times; This is in line with the definition of @arrival as the moment at which the train ends its movement and gets to a halt at the parent <ocpTT>.	approved	2019-06-19	2022-06-02		FIXME Forum missing	TT:times ocpTT ocpsTT patternTrainPart TT:times ocpTT ocpsTT trainPart
TT:015	Arrival times at the common operating point of two consecutive <patternTrainPart>'s of the same <patternTrain> must not contradict each other. This can be implemented either - by only the preceding <patternTrainPart> having arrival times while the succeeding <patternTrainPart> does not at this operating point or - by both <trainPart>'s having identical arrival times. These rules apply to the arrival times in each of the specified @scope's.	approved	2019-06-19	2022-06-02		https://www.railml.org/forum/index.php?t=msg&th=1017&start=0&	TT:times ocpTT ocpsTT patternTrainPart TT:times ocpTT ocpsTT trainPart
TT:016	Departure times at the common operating point of two consecutive <patternTrainPart>'s of the same <patternTrain> must not contradict each other. This can be implemented either - by the preceding <patternTrainPart> having no departure times and only the succeeding <patternTrainPart> specifying them at this operating point or - by both <patternTrainPart>'s having identical departure times. These rules apply to the departure times in each of the specified @scope's.	approved	2020-10-09	2022-06-02		https://www.railml.org/forum/index.php?t=msg&th=1017&start=0&	TT:times ocpTT ocpsTT patternTrainPart TT:times ocpTT ocpsTT trainPart
TT:017	If the trainPartRef attribute is given, then there must also be a trainRef attribute, and the trainPartRef attribute must point to a train part of the train referenced by the trainRef attribute.	approved	2022-12-15	2022-12-15		Agreed at the TT-devellopers-conference on December 15th 2022	TT:connection
TT:019	Any starting time stamp (as it may result e.g. from a combination of startDate and startTime) shall be lower or equal any ending time stamp (e.g. endDate) if both are given. Must not overlap with other <operatingDay> validity periods of the same enclosing <operatingPeriod>.	approved	2018-11-12	2019-03-21		FIXME Forum missing	TT:operatingDay
TT:020	No two attributes //<times>/@scope of the same enclosing <ocpTT> element shall have the same value.	approved	2025-04-07	2024-12-19		https://www.railml.org/forum/index.php?t=msg&th=1013&start=0&	TT:times ocpTT ocpsTT patternTrainPart TT:times ocpTT ocpsTT trainPart
TT:021	Within the same <operatingPeriod> element, a date must not be contained in more than one <specialService> element.	approved	2025-02-13	2025-04-07		https://www.railml.org/forum/index.php?t=msg&th=1014&start=0&	TT:specialService operatingPeriod TT:specialService operatingPeriodRef
TT:022	The values of @singleDate, @startDate and @endDate of <specialService> must not be outside of the time period defined in the enclosing <operatingPeriod>.	approved	2025-02-13	2025-04-07		https://www.railml.org/forum/index.php?t=msg&th=1014&start=0&	TT:specialService operatingPeriod TT:specialService operatingPeriodRef
TT:023	The attribute @airBrakeApplicationPosition if specified shall have the value N/A if the attribute @brakeType indicates a different type of brake than a pneumatic brake system (value compressedAir or vacuum).	approved	2025-03-13	2025-04-07		https://www.railml.org/forum/index.php?t=msg&th=1031&start=0&	TT:brakeUsage
TT:024	Any starting time (as it may result e.g. from a combination of @beginDay and @begin) shall be lower or equal any ending time (as it may result e.g. from a combination of @endDay and @end) if both are given.	approved	2018-11-12	2019-03-21		FIXME Forum missing	TT:blockPart

Deprecated Constraints as of railML 2.5

View/edit list on the separate source page.

Element	ID	Proposal date	Date of acceptance	Date of deprecation	Description
<TT:ocpTT>		2018-10-25	discarded		No ocpRef is allowed to occur more than one time in the same <trainPart>
<IS:speedChange>	IS:001	2019-04-11	discarded		Always define trainRelation
<IS:propOperational>	IS:007	2020-02-25	discarded
<TT:stopDescription> (Stop on request / More than one stop type per OCP)	TT:007	2019-06-19	discarded	2020-04-23
<IS:speedChange>	IS:011	2020-10-12 (date of creation of ticket 425)	2021-11-10 (40th conference slide 11)	2024-10-02 (railML.org e.V. Governance Coord approved)	*Every <track> has to have at least one <speedChange> at the track begin with parameters @pos="0" and @dir="up". Every <track> has to have at least one <speedChange> at the track end with parameters @pos="{value equal to trackEnd@pos}" and @dir="down".
<TT:times>	TT:011	2019-06-19	discarded