IS:designator ocp: Difference between revisions

From railML 2 Wiki
Jump to navigation Jump to search
[unchecked revision][checked revision]
No edit summary
(railML→{{rml}})
 
(32 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{ElementDocu|
{{inheritDesignator
elementName = key
|intro=2.2
 
|parent = {{IS:Tag|ocp}}
 
|semantics =
|semantics =
There are normally several abbreviations and/or numbers for the same {{IS:Tag|ocp}} (station), even in one country. So, the writing and reading software of a railML file can have different external primary keys for the same {{IS:Tag|ocp}} (station).<br>
There are normally several abbreviations and/or numbers for the same {{IS:Tag|ocp}} (station), even in one country. So, the writing and reading software of a {{rml}} file can have different external primary keys for the same {{IS:Tag|ocp}} (station).<br>


The {{IS:Tag|key}} sequence allows to enumerate more than one external primary key for one {{IS:Tag|ocp}}. Such, it defines the mapping from one to another register.<br>
The {{IS:Tag|designator}} sequence allows to enumerate more than one external primary key for one {{IS:Tag|ocp}}. Such, it defines the mapping from one to another register.<br>


It supersets the older (now deprecated) attributes 'code' and 'abbrev[i]ation' of {{IS:Tag|ocp}}.
It substitutes the older (now deprecated) attributes {{attr|number}} ({{depr|2.1}}) and {{attr|abbrev[i]ation}} ({{depr|2.1}}) of {{IS:Tag|ocp}}.


|ownAttributes =
|ownAttributes =
* {{Attr|register}}: Enumeration defining the catalogue, index, or directory where the external primary key comes from or refers to. See below for a list of the currently registered catalogues.
* {{Attr|register}}: A string value for defining the catalogue, index, or directory where the external primary key comes from or refers to. Attribute register is used to link a designator with the [[dev:Codelists|codelist]] ''[[Registers.xml]]''. A list of the currently registered catalogues can be found [[Dev:Registers#Current_entries|here]].
 
* {{Attr|value}}: Contains the external primary key of the OCP belonging to the referred register.
 
|notes =
{{Intro|2.2}}<br>
THIS IS A PRE-ANNOUNCEMENT FOR A NEW ELEMENT AND NOT YET RELEASED. CONTENTS MAY CHANGE UNTIL FINAL RELEASE OF RAILML 2.2.<br>
'''Please check the discussion in the [http://www.railml.org/forum/ro/?group=1 railML-Forum] and the [https://trac.assembla.com/railML/ticket/112 ticket].'''
 
Currently predefined 'register' enumeration entries:
* {{Enum|ENEE}} Station code of ENEE database managed by UIC.
* {{Enum|IBNR}} Numbers used in some public timetable databases and some customer information systems (EFZ - Europäisches Fahrplanzentrum der DB; Frankfurt/Main). This enumeration entry requires the value to be an integer number.
* {{Enum|DS100}} German "Betriebsstellenkürzel", Dienstvorschrift/Richtlinie No. 100 of Deutsche Bahn.
* {{Enum|DB640}} Austrian "Dienstbehelf No. 640" of Österreichische Bundesbahnen.
* {{Enum|DIDOK}} Swiss "Dienststellendokumentation" of Schweizerische Bundesbahnen on behalf of [http://www.bav.admin.ch/dokumentation/publikationen/00475/01497/index.html?lang=de Bundesamt für Verkehr].
 
Since the values change over the years, each one of the 'register' enumeration entries can be used with _xxxx (underline and a four-digit year number) to specify the year of the key values if necessary.


|constraints =
* {{Attr|entry}}: Contains the external primary key of the OCP belonging to the referred [[Registers.xml|register]]. To fulfill the requirements of a primary key, {{Attr|entry}} must be '''unique''' through all other entries of {{IS:Tag|ocp}}s with the same 'register'.
* {{Attr|register}} {{XsdType|enumeration}}, required: For short-time or internal purposes new enumeration entries can be used additional to that of railML's XSD. But for official data exchange between two software programs it is _strongly_ recommended that each new 'register' entry has to be 'registered' at the Scheme Coordinator.


* {{Attr|value}} {{XsdType|string}}, required: May be a string or a number depending on the 'register'. This means, some 'register' entries require a pure numeric number and do not allow characters or other signs. This is not forced by railML so far.
* {{Attr|startDate}}: Date from when (including) the entry becomes or became valid. The entry can be considered as "valid since ever"  if this attribute is not used (no other entry of that register was valid during the validity period of the file). Before {{Attr|startDate}}, either the whole {{IS:Tag|ocp}} wasn't part of the register or there is another entry for that {{IS:Tag|ocp}} and register with a lower {{Attr|endDate}}. {{StartEndDoc}}


* {{Attr|endDate}}: Date (including) when the entry becomes or became invalid. The entry can be considered as valid until canceled  if this attribute is not used (no other entry of that register will become valid during the validity period of the file as known so far). After {{Attr|endDate}}, either the whole {{IS:Tag|ocp}} will no longer be part of the register or there is another entry for that {{IS:Tag|ocp}} and register with a higher {{Attr|startDate}}. {{StartEndDoc}}
|example =
|example =
===Examples for OCPs with several designators in distinct registers===
<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
<ocp ... name='Passau Hbf.' ...>
<ocp ... name='Passau Hbf.' ...>
     <designator register='ENEE' entry='80-26506-6'/>
     <designator register='ENEE' entry='80-26506-6'/>
    <designator register='PLC' entry='DE18274'/>
     <designator register='IBNR' entry='8000298'/>
     <designator register='IBNR' entry='8000298'/>
     <designator register='DS100' entry='NPA'/>
     <designator register='RL100' entry='NPA'/>
     <designator register='DB640' entry='Pa'/>
     <designator register='DB640' entry='Pa'/>
</ocp>
</ocp>
Line 46: Line 29:
<ocp ... name='Fieberbrunn' ...>
<ocp ... name='Fieberbrunn' ...>
     <designator register='ENEE' entry='81-01155-1'/>
     <designator register='ENEE' entry='81-01155-1'/>
    <designator register='PLC' entry='AT1155'/>
     <designator register='IBNR' entry='8100053'/>
     <designator register='IBNR' entry='8100053'/>
     <designator register='DB640_2011' entry='Fie'/>
     <designator register='DB640' entry='Fie' endDate='2011-12-31'/>
     <designator register='DB640_2012' entry='Hch H2'/>
     <designator register='DB640' entry='Hch H2' startDate='2012-01-01'/>
     <designator register='DS100' entry='XAFB'/>
     <designator register='RL100' entry='XAFB'/>
</ocp>
</ocp>


<ocp ... name='Buchs (SG)' ...>
<ocp ... name='Buchs (SG)' ...>
     <designator register='ENEE' entry='85-09404-X'/>
     <designator register='ENEE' entry='85-09404-X'/>
    <designator register='PLC' entry='CH9404'/>
     <designator register='IBNR' entry='8509404'/>
     <designator register='IBNR' entry='8509404'/>
     <designator register='DB640' entry='Bc'/>
     <designator register='DB640' entry='Bc'/>
     <designator register='DS100' entry='XSBU'/>
     <designator register='RL100' entry='XSBU'/>
     <designator register='DIDOK' entry='BU'/>
     <designator register='DIDOK' entry='BU'/>
</ocp>
</ocp>
Line 62: Line 47:
</syntaxhighlight>
</syntaxhighlight>


|backHome = IS:elements
===Examples concerning {{Attr|startDate}} and {{Attr|endDate}}===
<syntaxhighlight lang="xml">
  <designator register='DB640' entry='Bc1'/>
  <designator register='DB640' entry='Bc2' startDate='2001-01-01'/>
</syntaxhighlight>
'Bc1' was valid until 31.12.2000.
<syntaxhighlight lang="xml">
  <designator register='DB640' entry='Bc1' endDate='2013-01-01'/>
  <designator register='DB640' entry='Bc2'/>
</syntaxhighlight>
'Bc1' is valid until 01.01.2013, 'Bc2' will be valid from 02.01.2013.
<syntaxhighlight lang="xml">
  <designator register='DB640' entry='Bc1' startDate='2001-01-01' endDate='2013-01-01'/>
  <designator register='DB640' entry='Bc2'/>
</syntaxhighlight>
'Bc2' was valid until 31.12.2000 and will be valid again from 02.01.2013. (A case not very common in practice.)
 
===Examples for wrong usage (invalid code)===
{{note|<syntaxhighlight lang="xml">
  <designator register='DB640' entry='Bc1' endDate='2012-12-31'/>
  <designator register='DB640' entry='Bc2' startDate='2012-01-01'/>
</syntaxhighlight>
'''Not allowed''', because there are two different valid designators in the same register from 2012-01-01 until 2012-12-31.
|error}}<br>&nbsp;<br>
{{note|<syntaxhighlight lang="xml">
  <designator register='DB640' entry='Bc1'/>
  <designator register='DB640' entry='Bc2'/>
</syntaxhighlight>
'''Not allowed''', because there are two different valid designators in the same register permanently.
|error}}
}}
}}

Latest revision as of 19:25, 22 January 2024


designator
 


Scheme description / Schemenbeschreibung

Position of designator in the XML-Tree / Position von designator im XML-Baum

  • Parent: <ocp>
  • Children: None

Multiplicity / Anzahl

[0..1]

Semantics / Bedeutung

There are normally several abbreviations and/or numbers for the same <ocp> (station), even in one country. So, the writing and reading software of a railML® file can have different external primary keys for the same <ocp> (station).

The <designator> sequence allows to enumerate more than one external primary key for one <ocp>. Such, it defines the mapping from one to another register.

It substitutes the older (now deprecated) attributes number ((deprecated with version 2.1)) and abbrev[i]ation ((deprecated with version 2.1)) of <ocp>.(introduced with version 2.2)
 
Please, be aware of the semantic constraint(s)!

Attributes of designator / Attribute von designator

  • register: Name of the register, e.g. registers for OCPs: IBNR, DB640, RL100 or DIDOK. Choose a value from the railML® codelist Registers.xml or name your own register starting with an underscore.
  • entry: An entity's code in the specified register.
  • startDate: Date from when (including) the entry becomes or became valid. The entry can be considered as "valid since ever" if this attribute is not used (no other entry of that register was valid during the validity period of the file).
  • endDate: Date (including) when the entry becomes or became invalid. The entry can be considered as valid until canceled if this attribute is not used (no other entry of that register will become valid during the validity period of the file as known so far).

Syntactic Constraints / Syntaktische Beschränkungen

  • register xs:string, required
  • entry xs:string, required
  • startDate xs:date, optional: shall be lower or equal endDate if both are used. Must not overlap with other validity periods of the same register for the same <ocp>.
  • endDate xs:date, optional: shall be higher or equal startDate if both are used. Must not overlap with other validity periods of the same register for the same <ocp>.

Semantic Constraints / Semantische Beschränkungen

Private-cloud-icon.png Semantic Constraint "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. See also https://wiki2.railml.org/wiki/Dev:Defining_temporal_availability_of_infrastructure_elements_and_speed_profiles
 
Proposed on November 12th 2018
Approved on March 21st 2019
FIXME: add Link to discussion!
Please, recognize our guidelines on semantic constraints

Best practice & Examples / Empfohlene Anwendung & Beispiele

Examples for OCPs with several designators in distinct registers

<ocp ... name='Passau Hbf.' ...>
    <designator register='ENEE' entry='80-26506-6'/>
    <designator register='PLC' entry='DE18274'/>
    <designator register='IBNR' entry='8000298'/>
    <designator register='RL100' entry='NPA'/>
    <designator register='DB640' entry='Pa'/>
</ocp>

<ocp ... name='Fieberbrunn' ...>
    <designator register='ENEE' entry='81-01155-1'/>
    <designator register='PLC' entry='AT1155'/>
    <designator register='IBNR' entry='8100053'/>
    <designator register='DB640' entry='Fie' endDate='2011-12-31'/>
    <designator register='DB640' entry='Hch H2' startDate='2012-01-01'/>
    <designator register='RL100' entry='XAFB'/>
</ocp>

<ocp ... name='Buchs (SG)' ...>
    <designator register='ENEE' entry='85-09404-X'/>
    <designator register='PLC' entry='CH9404'/>
    <designator register='IBNR' entry='8509404'/>
    <designator register='DB640' entry='Bc'/>
    <designator register='RL100' entry='XSBU'/>
    <designator register='DIDOK' entry='BU'/>
</ocp>

Examples concerning startDate and endDate

   <designator register='DB640' entry='Bc1'/>
   <designator register='DB640' entry='Bc2' startDate='2001-01-01'/>

'Bc1' was valid until 31.12.2000. 

   <designator register='DB640' entry='Bc1' endDate='2013-01-01'/>
   <designator register='DB640' entry='Bc2'/>

'Bc1' is valid until 01.01.2013, 'Bc2' will be valid from 02.01.2013. 

   <designator register='DB640' entry='Bc1' startDate='2001-01-01' endDate='2013-01-01'/>
   <designator register='DB640' entry='Bc2'/>

'Bc2' was valid until 31.12.2000 and will be valid again from 02.01.2013. (A case not very common in practice.)

Examples for wrong usage (invalid code)

❗ 
   <designator register='DB640' entry='Bc1' endDate='2012-12-31'/>
   <designator register='DB640' entry='Bc2' startDate='2012-01-01'/>

Not allowed, because there are two different valid designators in the same register from 2012-01-01 until 2012-12-31.


 

❗ 
   <designator register='DB640' entry='Bc1'/>
   <designator register='DB640' entry='Bc2'/>

Not allowed, because there are two different valid designators in the same register permanently.

Notes / Anmerkungen

A list of current entries can be found on page Dev:Registers#Current entries. The procedure to add entries to the codelist is described on page Dev:Codelists#Missing entries.

Open issues / Offene Punkte/Pendenzen

Not yet described. / Noch nicht beschrieben.

Retrieved from "https://wiki2.railml.org/index.php?title=IS:designator_ocp&oldid=15276"