Dev:SemanticConstraints

From railML 3 Wiki
(Redirected from Dev:Semantic Constraints)
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

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 added to the element documentation using Template:Semcon, with status=proposed and added to the list below. 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

Current 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
<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

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:signalConstruction> IS:005 2024-01-22 2024-03-22 SCTP WG

2024-04-15 NEST WG

2025-02-03 Modelling coordination meeting @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 2024-08-09 SCTP WG

2025-01-28 NEST WG

if @isOpenEnd="true" then @type should be set as @type="area".
<IS:netElement> IS:008 2024-02-02 2024-08-09 SCTP WG 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 2024-08-09 SCTP WG 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 2024-08-09 SCTP WG

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

2024-05-13 ETCS 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". wording will be improved
<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.
<IS:netRelation> IS:015 2024-04-22 2024-08-09 SCTP WG 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.
<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:trainProtectionElement> IS:017 2009-10-17 2009-10-17 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 (link to the railML® website), 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.
<IS:opEquipment> IS:018 2024-08-26 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>.
<IS:infrastructureState> IS:019 2024-09-03 2024-09-13 SCTP WG When calculating which <infrastructureState> of an <infrastructure> is valid on a particular time always a maximum of one active <infrastructureState> shall be the result. See examples below.
<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.
<TT:times> TT:008 2024-11-21 No two attributes //<times>/@scope of the same enclosing stop/pass elements shall have the same value.
Retrieved from "https://wiki3.railml.org/index.php?title=Dev:SemanticConstraints&oldid=12034"