Dev:Semantic Constraints

From railML 3 Wiki
Jump to navigation Jump to search

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

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 constraints.

Semantic constraints can be proposed either by one of the railML® working groups (link to the railML® website) or suggested by anyone through a post in the forum (link to the railML® website).

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 added to the element documentation using Template:Semcon, with status=proposed and added to the list below. If there are no objections in the forum, it will be approved after six weeks and implemented in the wiki with status=approved.

If you see the need for a semantic constraint beyond the schema, please discuss it in the forum (link to the railML® website) and then add a proposal in the element documentation using Template:Semcon, with status=proposed. Please also add the proposal to the list below! If a consensus is reached in the forum, the proposal will be accepted, it will implemented in the wiki with status=approved.

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

Design guidelines

Current Constraints

railML® 2

View/edit list on the separate source page.

Element ID Proposal date Date of acception Date of deprecation Description
<TT:timetablePeriod> TT:001 2018-11-12 2019-03-21 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:specialService> TT:001 2018-11-12 2019-03-21 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:operatingPeriodRef> TT:001 2018-11-12 2019-03-21 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:operatingPeriod> TT:001 2018-11-12 2019-03-21 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:operatingDay> TT:001 2018-11-12 2019-03-21 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:circulation> TT:001 2018-11-12 2019-03-21 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:blockPart> TT:001 2018-11-12 2019-03-21 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.
<RS:designator> (introduced with version 2.5) TT:001 2018-11-12 2019-03-21 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.
<RS:operator> TT:001 2018-11-12 2019-03-21 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.
<RS:owner> (introduced with version 2.5) TT:001 2018-11-12 2019-03-21 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.
<RS:state> TT:001 2018-11-12 2019-03-21 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.
<IS:state> TT:001 2018-11-12 2019-03-21 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. See also https://wiki2.railml.org/wiki/Dev:Defining_temporal_availability_of_infrastructure_elements_and_speed_profiles
<IS:state (with length)> TT:001 2018-11-12 2019-03-21 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. See also https://wiki2.railml.org/wiki/Dev:Defining_temporal_availability_of_infrastructure_elements_and_speed_profiles
<IS:designator> TT:001 2018-11-12 2019-03-21 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.
<CO:designator> (introduced with version 2.5) TT:001 2018-11-12 2019-03-21 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.
<CO:phase> (introduced with version 2.5) TT:001 2018-11-12 2019-03-21 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:ocpTT> TT:002 2018-10-25 2019-06-20 The attribute sequence is shall be increasing according to the train path.
<TT:ocpTT> 2018-10-25 discarded No ocpRef is allowed to occur more than one time in the same <trainPart>
<TT:blockPart> TT:003 2019-07-13 2019-07-18 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: (not included here)
<TT:blockPart> TT:004 2019-07-20 2019-07-18 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.
<TT:rostering> TT:005 2019-05-22 2019-06-25 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.
<TT:stopDescription> TT:006 2018-09-03 2019-06-20 Constraints between the attributes <ocpTT>.ocpType, <stopDescription>.guaranteedPass, .commercial, .onOff, .stopOnRequest and .operationalStopOrdered
<TT:stopDescription> (Stop on request / More than one stop type per OCP) TT:007 2019-06-19 discarded 2020-04-23
<TT:trackInfo> TT:008 2018-08-21 2019-06-20 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.
<TT:trackInfo> TT:009 2018-08-21 2019-06-20 The operating days 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.
<TT:times> (Correct encoding of run time supplements) TT:010 2019-06-19 2020-10-15 @scope='earliest' and 'latest' are not intended to encode supplement times, as this is redundant to <ocpTT>.<sectionTT>.<runTimes>@operationalReserve, @additionalReserve, @minimalTime.
<TT:times> TT:011 2019-06-19 discarded
<TT:times> TT:012 2019-06-19 2022-06-02 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.
<TT:times> TT:013 2019-06-19 discarded
<TT:times> (Arrival times for passing OCP's) TT:014 2019-06-19 2022-06-02 @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>.
<TT:times> (Arrival time at first OCP) TT:015 2019-06-19 2022-06-02 At the first <ocpTT> of a <trainPart> that is not the first one of the <trainPartSequence>, the attribute @arrival is optional. If it is set anyway, then, for consistency reasons, the value of @arrival of the regarding <ocpTT> must be identical for both this <trainPart> and the preceding one.
<TT:times> (Departure time at last OCP) TT:016 2020-10-09 2022-06-02 At the last <ocpTT> of a <trainPart> that is not the last one of the <trainPartSequence>, the attribute @departure is optional. If it is set anyway, then, for consistency reasons, the value of @departure of the regarding <ocpTT> must be identical for both this <trainPart> and the subsequent one.
<TT:connection> TT:017 2022-12-15 2022-12-15 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.
<IS:speedChange> IS:001 2019-04-11 discarded Always define trainRelation
<IS:trackEnd> IS:002 2019-06-17
<IS:trackBegin> IS:003 2019-06-17
<IS:track> IS:004 2019-06-17 Single track railway lines shall have main driving direction @mainDir="none" if they are used in both directions
<IS:ocp> IS:005 2019-06-19 2022-07-14 An <ocp> that refers to a parent <ocp> via an @parentOcpRef overwrites the attributes and elements of the parent <ocp> if explicitely defined. If an element is specified on an <ocp> that uses a @parentOcpRef any information provided with that element on a higher layer of the <ocp>-tree is overwritten. There is no merging of element-information from different levels. The same applies for attributes of <ocp>.
<IS:mileageChange> IS:006 2019-06-19
  • 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 fiven to define the ongoing orientation of the mileage
<IS:propOperational> IS:007 2020-02-25 discarded
<IS:uptime> IS:008 2020-02-28 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).

<IS:uptime> IS:009 2020-02-28 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).
<IS:uptime> IS:010 2020-02-28 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>.
<IS:speedChange> IS:011 2022-03-14 (to be def. more accurately) 2021-11-10 (40th conference slide 11)
  • 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".
<IS:speedProfile> IS:012 2022-03-14 @basicSpeedProfile is always linked with @influence=increasing
<IS:speedProfile> IS:013 2022-03-14
  • @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.
<IS:tunnel> IS:014 2022-03-14 Define the tunnel resistance factor @resistanceFactorPassenger resp. @resistanceFactorFreight only if @kind and @crossSection are not known.
<IS:ocp> IS:015 2022-07-14 2022-08-11 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.
<IS:axleWeightChange> <clearanceGaugeChange> <electrificationChange> <gaugeChange> <ownerChange> <gradientChange> <powerTransmissionChange> <radiusChange> IS:016 2021-11-10 2021-11-10 must not have @dir attribute according to Report from the Infrastructure developers in railML 3.2 and 2.5 (link to the railML® website) slide 9 and #357
<railml> <infrastructure> IS:017 2024-03-25 2021-03-25 either <infrastructure> or <railml> must have @version attribute
<metadata> @name IS:018 2024-03-25 2021-03-25 either <metadata> must have <dc:language> child or every @name attribute accompanied by @xml:lang
<IS:gradientChange> IS:019 2024-03-25 2021-03-25 there can be no two <gradientChange> belonging to the same track with the same @pos attribute

railML® 3

View/edit list on the separate source page.

Element ID Proposal date Date of acception Date of deprecation Description
<TT:operationalTrainSectionPart> TT:001 2022-09-15 2022-10-13 There is always only a single successor and predecessor for an <operationalTrainSectionPart> in the chain of <operationalTrainSectionPart>s that are linked via the attribute @next.
<TT:operationalTrainVariant> TT:002 2023-01-12 2023-04-06 When calculating which <operationalTrainVariant> of an <operationalTrain> is valid on a particular day always a maximum of one active <operationalTrainVariant> shall be the result. If the result is more than one <operationalTrainVariant>, all except one shall be marked as <isCancelled> or <isOnRequest>.
<TT:commercialTrainVariant> TT:003 2023-01-12 2023-04-06 When calculating which <commercialTrainVariant> of an <commercialTrain> is valid on a particular day always a maximum of one active <commercialTrainVariant> shall be the result. If the result is more than one <commercialTrainVariant>, all except one shall be marked as <isCancelled> or <isOnRequest>.
<TT:operationalTrainSection> TT:004 2022-01-12 2023-03-09 The itinerary sections of an <operationalTrainVariant>, defined by the <operationalTrainSection>s and their respective <range>s, that are not <isCancelled> and not marked as <isOnRequest>, must be pairwise disjoint, except for their respective first and last <baseItineraryPoint>s.
<TT:operationalTrainSection> TT:005 2022-01-12 2023-03-09 The first(last) <baseItineraryPoint> of each <operationalTrainSection> within an <operationalTrainVariant> must either be the referenced <itinerary>'s first(last) <baseItineraryPoint>, or coincide with another section's last(first) <baseItineraryPoint>.
<TT:commercialTrainSection> TT:006 2022-01-12 2023-03-09 The itinerary sections of an <commercialTrainVariant>, defined by the <commercialTrainSection>s and their respective <range>s, that are not <isCancelled> and not marked as <isOnRequest>, must be pairwise disjoint, except for their respective first and last <baseItineraryPoint>s.
<TT:commercialTrainSection> TT:007 2022-01-12 2023-03-09 The first(last) <baseItineraryPoint> of each <commercialTrainSection> within an <commercialTrainVariant> must either be the referenced <itinerary>'s first(last) <baseItineraryPoint>, or coincide with another section's last(first) <baseItineraryPoint>.
<RTM:isValid>, <CO:validityTime:period> IS:001 2024-01-15 2024-02-26 ETCS WG

2024-03-22 SCTP WG

2024-04-15 NEST WG

Starting time stamp (e.g. "from") shall be lower or equal any ending time stamp (e.g. "to") if both are given. Must not overlap with other validity periods.
<IS:trainProtectionElement> IS:002 2021-02-26 2024-02-26 ETCS WG

2024-03-22 SCTP WG

2024-04-15 NEST WG

<trainProtectionElement> shall only be used for national and/or legacy train protection systems. ETCS-based systems must not be modeled using <trainProtectionElement>.
<IS:levelCrossingIS> IS:003 2023-10-23 2024-02-26 ETCS WG

2024-03-22 SCTP WG

2024-04-15 NEST WG

<levelCrossingIS> should not have a <crossesElement> child of type railway. This case should be represented either by a <crossing> in case of a simple crossing, or by a <switchIS> of type doubleSwitchCrossing or singleSwitchCrossing.
<IS:underCrossing>, <IS:overCrossing> IS:004 2023-10-23 was declined 2024-02-26 should only have a <crossesElement> child of type railway when railway crosses railway (not on the same level!).
<IS:signalConstruction> IS:005 2024-01-22 2024-03-22 SCTP WG

2024-04-15 NEST WG

@height and @positionAtTrack should not be used with @type=virtual.

<IS:line> IS:006 2024-01-29 2024-02-26 ETCS WG

2024-04-15 NEST WG

each line with own mileage should always be associated with its own <linearPositioningSystem>, i.e. Advanced example of railML has three lines with their own mileages, thus should have thee <linearPositioningSystem>s.

2024-03-22 SCTP WG - GUI implementation not clear

<IS:border> IS:007 2024-01-29

if @isOpenEnd="true" then statement @type="area" is true.

<IS:netElement> IS:008 2024-02-02

Aggregation of net elements should follow the tree data structure. See figure below. This means that no two (mesoscopic) net elements can aggregate same (microscopic) net element. In other words, (microscopic) net element can be aggregated by at most one (mesoscopic) net element.

<IS:netElement> IS:009 2024-02-02

Linear (geometric) coordinates (explicit or implicit, e.g. calculated as a sum of the coordinate of beginning and the length of the net element) of the same place represented at different levels of aggregation should have the same value. In the figure below (linear) coordinate the coordinate of e.g. end of ne1 should be same as one of ne1.2.

<IS:netElement> IS:010 2024-02-26

Difference of linear coordinates if the beginning and end of <netElement>, represented by <intrinsicCoordinate> / @intrinsicCoord = 0 and 1 correspondingly, should equal the the @length of <netElement> if all are present in the data. For each case when a difference of linear coordinates if the beginning and end of <netElement>, represented by <intrinsicCoordinate> / @intrinsicCoord = 0 and 1 correspondingly, does not equal the the @length of <netElement> if all are present in the data, a <mileageChange> of <anchor> should be present explaining anomaly

<IS:netElement> IS:011 2024-02-29

Aggregation must not happen within the same level of detail. In the figure below, element 1.1 must not aggregate element 1.2. This means that aggregating and aggregated net elements must not be referred from the same <level>

<RTM:spotLocation> IS:012 2024-03-04 2024-04-19 SCTP WG

@pos should have only positive values because it's a distance, thus -1 is not a valid value

functional infrastructure and geometry entities IS:013 2024-03-25

there can be no two functional infrastructure or geometry entities of the same type located at the same coordinate of spot location, e.g. two railway switches or two gradient curves having the same linear coordinate make no sense. Except for the entities linked by the @belongsToParent attribute and railway crossing modelled as switch of type "doubleSwitchCrossing" and two railway switches of type "switchCrossingPart".

<RTM:linearPositioningSystem> IS:014 2024-04-08 2024-04-15 NEST WG

2024-04-19 SCTP WG

@startMeasure and @endMeasure are start and end values of a railway <IS:line> associated with <RTM:linearPositioningSystem> not max and min values of a current file with e.g. line section.

Implementation for infrastructure surveys is not clear https://www.railml.org/forum/index.php?t=rview&goto=3231&th=946#msg_3231

<IS:netRelation> IS:015 2024-04-22

There must be no "inverse" net relations in the topology, i.e. if "nr1 elemeneA ne1", "nr1 elementB ne2" and "nr2 elemeneA ne2", "nr2 elementB ne1" then topology is not valid. See invalid code below.

Retrieved from "https://wiki3.railml.org/index.php?title=Dev:Semantic_Constraints&oldid=6933"