Dev:SemanticConstraints

From railML 3 Wiki
Jump to navigation Jump to search

Introduction

Constraints, which are needed to ensure that software can handle your railML® files and the contents in a needed way, are of two types:

  • Syntactic constraints;
  • Semantic constraints.

Syntactic constraints describe the syntax of an XML (Wiki banner.png) file. Syntactic constraints are given in XML Schema (W3C) (Wiki banner.png) as it offers a variety of possibilities to define them. For example, in railML®3 XML Schema (W3C) (Wiki banner.png), it is possible to describe and validate:

Semantic constraints are as important as syntactic constraints. Therefore, their implementation is checked during certification. Every application of railML® has to be checked not only on XML Schema (W3C) (Wiki banner.png) compliance but also on the obedience to the semantic constraints.

Semantic constraints are rules restricting the contents, or semantics, of one element or attribute depending on other content: the value or existence of another element or attribute.

XML Schema (W3C) (Wiki banner.png) cannot express semantic constraints. For example, in railML® 3.2 XML Schema (W3C) (Wiki banner.png), it is not possible to describe and validate:

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.

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 (W3C) (Wiki banner.png) should be implemented syntactically in the schemas. Please, follow the guideline for participating in the development process (link to the railML® website). If a constraint cannot be described by XML Schema (W3C) (Wiki banner.png), 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:

  • If you see the need for a semantic constraint beyond the schema, please propose it in theforum (link to the railML® website) . The responsible schema coordinator will bring it to the relevant working group or directly to the group of coordinators.
  • 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 list below. he 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.
  • After the community has been given a reasonable time to raise any objections in the forum (link to the railML® website) , the coordinators will decide if the proposed semantic constraint is approved. Following this decision, the documentation will be updated accordingly.
🗒️ 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 (link to the railML® website) . 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 principles

  • A separate semantic constraint is implemented for every rule.
  • New semantic constraints must be proposed in the forum (link to the railML® website)
  • The template with all mandatory arguments shall be used according to Template:SemanticConstraint
  • Semantic constraint is recorded on the respective list below (Template:Table/Dev:SemanticConstraints for railML® 3)
  • A serial ID is assigned to the semantic constraint according to the appropriate list below (link to the railML® website)
  • An issue is created for implementing semantic constraint in railVIVID (link to the railML® website)

Current Constraints as of railML® 3.x

View/edit list on the separate source page.

ID Text Status Proposed Approved Deprecated Forum Instances


CO:001
 @version shall correspond to the specified namespace of the <railML> element.
 approved
 2025-10-13
 2025-10-13
Proposal for new semantic constraint for the version of railML (link to the railML® website)


IS:001
 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 within the same enclosing element.
 proposed
 2024-01-15
 Not yet approved
FIXME Forum missing


IS:005
 @height and @positionAtTrack should not be used with @type=virtual.
 approved
 2021-02-26
 2025-02-03
Please, discuss this semantic constraint in the railML® forum topic "Construction of virtual signals (link to the railML® website)".


IS:007
 When providing the value 'true' to the attribute @isOpenEnd of <border> the attribute @type shall always be set to area.
 approved
 2024-06-25
 2025-05-19
<border> representing open ends (link to the railML® website)


IS:008
 When aggregating net elements each <netElement> of a lower level of aggregation shall only directly belong to a single <netElement> of a higher level of aggregation.
 approved
 2024-04-29
 2025-05-19
Please, discuss this semantic constraint in the railML® forum topic Restricting aggregation of RailTopoModel (link to the railML® website)".


IS:009
 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.
 proposed
 2024-04-29
 Not yet approved
Please, discuss this semantic constraint in the railML® forum topic "Restricting aggregation of RTM (link to the railML® website)".


IS:010
 Difference of linear coordinates if the beginning and end of net elements, represented by intrinsic coordinates 0 and 1 correspondingly, should equal the the @length of net element if all are present in the data.
 proposed
 2021-02-26
 Not yet approved




IS:011
 Aggregation must not happen within the same <level> of aggregation. No <netElement> of a certain <level> of aggregation shall be part of another <netElement> on the same <level> of aggregation.
 approved
 2024-02-29
 2025-05-19
Please, discuss this semantic constraint in the railML® forum topic "Restricting aggregation of RTM (link to the railML® website)".


IS:012
 @pos should have only positive values because its a distance, thus -1 is not a valid value – Compare #567
 proposed
 2024-03-04
 Not yet approved




IS:014
 @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
 proposed
 2024-04-08
 Not yet approved
Please, discuss this semantic constraint in the railML® forum topic Restricting IS:line and RTM:linearPositioningSystem (link to the railML® website)".


IS:015
 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 – Compare
 proposed
 2021-04-22
 Not yet approved




IS:017
 Users can refer to the train protection system using the attribute @trainProtectionSystem that shall link to the codelist (link to the railML® website) TrainProtectionSystems.xml, section trainProtectionSystemsAtTrack. Only if this list does not contain the specific train protection system to be modelled, it shall be described in its functionality using attributes @medium and @monitoring.
 proposed
 2025-04-29
 Not yet approved
Please, discuss this semantic constraint in the railML® forum topic Consistent use of <train-Protection-System> (link to the railML® website)".


IS:018
 Any functional infrastructure element that belongs to an <operationalPoint> may be listed as its equipment. This may be done by adding it to a specific container, such as <ownsPlatform>, <ownsTrack> and <ownsSignal> or it may be added to the generic container <ownsInfrastructureElement>. Any such added infrastructure element must be added to the most specific container available. No element shall be part of two such containers. If no specific container for the functional infrastructure element exists, it shall be listed in the generic container. Example: a <signalIS> must not be added to <ownsInfrastructureElement>. It shall be added to <ownsSignal>. As there is no container for levelCrossings a <levelCrossingIS> belonging to an <operationalPoint> shall be added to <ownsInfrastructureElement>.
 proposed
 2024-08-26
 Not yet approved
Please, discuss this semantic constraint in the railML® forum topic "Usage of <owns-Platform> vs <owns-Infrastructure-Element> (link to the railML® website)".


IS:019
 When calculating which <infrastructureState> of an <infrastructure> is valid on a particular time always a maximum of one active <infrastructureState> shall be the result.
 proposed
 2024-09-03
 Not yet approved
Please, discuss this semantic constraint in the railML® forum topic New semantic constraint to ensure unambiguous infrastructure states (link to the railML® website)".


IS:021
 The element <baliseGroup> shall always use the railML® option <spotLocation> when defining the balise group location on the topology.
 approved
 2025-04-30
 2025-05-19
Please, discuss this semantic constraint in the railML® forum topic "Proposal of a semantic constraint for <baliseGroup> (link to the railML® website)".


IS:022
 The element <balise> shall always use the railML® option <spotLocation> when defining the balise location on the topology.
 approved
 2025-04-30
 2025-05-19
Please, discuss this semantic constraint in the railML® forum topic "Proposal of a semantic constraint for <baliseGroup> (link to the railML® website)".


IS:023
 <linearCoordinate>/@measure , <linearCoordinateBegin>/@measure , <linearCoordinateEnd>/@measure must be ≥ @startMeasure and ≤ @endMeasure of the corresponding <linearPositioningSystem>.
 approved
 2025-02-17
 2025-09-08
Making consistent linearPositioningSystem and linear coordinates (link to the railML® website)


IS:024
 When specifying an <intrinsicCoordinate> with 0 < @intrinsicCoord < 1, it needs to be ensured that a given <linearCoordinate> is aligned with the referenced <linearPositioningSystem>.
 approved
 2025-04-02
 2025-10-13
Please, discuss this semantic constraint in the railML® forum topic "Proposal for a new semantic constraint for associatedPositioningSystem (link to the railML® website)".


IS:025
 Each <netElement> must belong to exactly one <level>.
 proposed
 2025-02-27
 Not yet approved
Please, discuss this semantic constraint in the railML® forum topic New semantic constraint restricting RTM:level, IS:netElement and IS:netRelation (link to the railML® website)".


IS:026
 Each <netRelation> must belong to exactly one <level>.
 proposed
 2025-02-27
 Not yet approved
Please, discuss this semantic constraint in the railML® forum topic New semantic constraint restricting RTM:level, IS:netElement and IS:netRelation (link to the railML® website)".


IS:027
 If <switchToLevel>/@levelType="ETCS", then only the following values are accepted: <switchToLevel>/@levelValue="0", <switchToLevel>/@levelValue="1", <switchToLevel>/@levelValue="2", <switchToLevel>/@levelValue="3".
 proposed
 2025-10-08
 Not yet approved
Please, discuss this semantic constraint in the railML® forum topic "Semantic constraint for etcsLevelTransition/switchToLevel (link to the railML® website)".


IS:028
 If <switchToLevel>/@levelType="NTC", then the <switchToLevel>/@levelValue shall conform to the NID_NTC-values specified in the ERA document Assignment of values to ETCS variables (external link).
 proposed
 2025-10-08
 Not yet approved
Please, discuss this semantic constraint in the railML® forum topic "Semantic constraint for etcsLevelTransition/switchToLevel (link to the railML® website)".


TT:001
 The next attribute shall reference an <operationalTrainSectionPart> that is not referenced by any other next-reference. In other words: Within the chain of <operationalTrainSectionPart>s linked by the attribute next, there can be no element that has more than one predecessor. The @next reference must establish a one to one relationship between two <operationalTrainSectionPart>s.
 approved
 2022-09-15
 2025-09-08
Please, discuss this semantic constraint in the railML® forum topic "Semantic Constraint TT:001 <operationalTrainSectionPart>/@next (link to the railML® website)".


TT:002
 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>.
 approved
 2023-01-12
 2025-09-08
Please, discuss this semantic constraint in the railML® forum topic "Semantic Constraint TT:002 <operationalTrainVariant> (link to the railML® website)".


TT:003
 When calculating which <commercialTrainVariant> of a <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>.
 approved
 2023-01-12
 2025-09-08
Please, discuss this semantic constraint in the railML® forum topic "Semantic Constraint TT:003 <commercialTrainVariant> (link to the railML® website)".


TT:004
 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.
 approved
 2023-01-12
 2023-03-09
Please, discuss this semantic constraint in the railML® forum topic Semantic Constraints for Train Section (link to the railML® website).


TT:005
 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>.
 approved
 2023-01-12
 2023-03-09
Please, discuss this semantic constraint in the railML® forum topic Semantic Constraints for Train Section (link to the railML® website)".


TT:006
 The itinerary sections of a <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.
 approved
 2023-01-12
 2023-03-09
Please, discuss this semantic constraint in the railML® forum topic Semantic Constraints for Train Section (link to the railML® website)".


TT:007
 The first(last) <baseItineraryPoint> of each <commercialTrainSection> within a <commercialTrainVariant> must either be the referenced <itinerary>'s first(last) <baseItineraryPoint>, or coincide with another section's last(first) <baseItineraryPoint>.
 approved
 2023-01-12
 2023-03-09
Please, discuss this semantic constraint in the railML® forum topic Semantic Constraints for Train Section (link to the railML® website)".


TT:008
 No two attributes //<times>/@scope of the same enclosing <baseItineraryPoint> element shall have the same value.
 approved
 2024-11-21
 2025-04-07
Please, discuss this semantic constraint in the railML® forum topic "Proposed semantic constraint for <times> (link to the railML® website)".


TT:009
 When combining <baseItinerary>'s in an <itinerary> it shall be ensured that the last <baseItineraryPoint> of the preceding <baseItinerary> references that same <operationalPoint> as the first <baseItineraryPoint> of the succeeding <baseItinerary>. The order of the <baseItinerary>'s is determined by the @sequenceNumber specified in the <range> of the <itinerary>.
 proposed
 2025-03-07
 Not yet approved
Please, discuss this semantic constraint in the railML® forum topic "Proposal for new semantic constraints and change of existing ones (link to the railML® website)".


TT:010
 In an <operationalTrainSection>, the <range> element's start and end must reference <baseItineraryPoint> elements such that their order aligns with the sequencing defined by the <itinerary>.
 proposed
 2025-03-07
 Not yet approved
Please, discuss this semantic constraint in the railML® forum topic "Proposal for new semantic constraints and change of existing ones (link to the railML® website)".


TT:011
 In an <commercialTrainSection>, the <range> element's start and end must reference <baseItineraryPoint> elements such that their order aligns with the sequencing defined by the <itinerary>.
 proposed
 2025-03-07
 Not yet approved
Please, discuss this semantic constraint in the railML® forum topic "Proposal for new semantic constraints and change of existing ones (link to the railML® website)".


Deprecated Constraints as of railML 3.3

View/edit list on the separate source page.

Element ID Proposal date Working groups Date of acceptance Date of deprecation Description
<IS:trainProtectionElement> IS:002 2021-02-26 2024-02-26 ETCS WG

2024-03-22 SCTP WG 2024-04-15 NEST WG

2025-02-03 Modelling coordination meeting <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

2025-02-03 Modelling coordination meeting <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 declined 2024-02-26 should only have a <crossesElement> child of type railway when railway crosses railway (not on the same level!).
<IS:line> IS:006 2024-01-29 2024-02-26 ETCS WG

2024-04-15 NEST WG

2025-04-11[1] 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.[2]
<IS:gradientCurve> IS:016 2024-05-31 declined 2024-12-06 SCTP WG @gradient should not be used if @curveType="mixed". Instead of @gradient, @deltaGradient should be used.
<IS:speedSection> IS:020 2022-04-25 2025-02-03 Modelling coordination meeting Each railML® <speedSection> element must reference (at least) one global defined railML® <speedProfile> element.





  1. ↑ https://www.railml.org/forum/index.php?t=msg&th=946&goto=3521&#msg_3521 2025-04-11 confirmed by IS coordinator
  2. ↑ 2024-03-22 SCTP WG - GUI implementation not clear
Retrieved from "https://wiki3.railml.org/index.php?title=Dev:SemanticConstraints&oldid=17805"