Dev:Creating instructions: Difference between revisions

From railML 2 Wiki
Jump to navigation Jump to search
[unchecked revision][unchecked revision]
(Die Seite wurde neu angelegt: „<h1 class="western"><a name="__RefHeading___Toc84136237"></a>3<span lang="en-GB">Creating Guidelines for railML</span><sup><span lang="en-GB">®</span></sup><s…“)
 
No edit summary
Line 1: Line 1:
<h1 class="western"><a name="__RefHeading___Toc84136237"></a>3<span lang="en-GB">Creating
'''Creating Guidelines for {{rml}} scheme'''
Guidelines for railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
 
scheme</span></h1>
This page informs you about the creating instructions for the {{rml}} XML schema in the scope of the [[Dev:Guideline for participating in the development process|development of {{rml}}]].
<p class="western"><span lang="en-GB">The railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
 
scheme (“the scheme”) is based on wellformed and valid XML </span>
The {{rml}} scheme (“the scheme”) is based on wellformed and valid XML  
</p>
 
<p lang="en-GB" class="western">Wellformed means in this context:</p>
Wellformed means in this context:
<ul>
* every start tag has got an end tag on the same hierarchy;
<li/>
* nestings are not allowed;
<p lang="en-GB" class="western">every start tag has got an end
* attributes are ;
tag on the same hierarchy;</p>
* the first element (here: <railml>) is unique within the whole file.
<li/>
 
<p lang="en-GB" class="western">nestings are not allowed;</p>
Valid means: the scheme or a {{rml}} partial scheme complies the creating instruc­tions for XML schemes published by World Wide Web Consortium (W3C). These creating instructions determines all appropriable elements and attributes (see [[#W3C01b]]).
<li/>
 
<p lang="en-GB" class="western">attributes are ;</p>
== Development ==
<li/>
 
<p class="western"><span lang="en-GB">the first element (here:
The creating of a new {{rml}} partial scheme or the further development of an exist­ing scheme is concluded by railML.org initiative. All {{rml}} partial schemes must redeem these creating instructions.  
</span><font face="Courier, monospace"><font size="3" style="font-size: 12pt"><span lang="de-DE"><span lang="en-GB">&lt;railml&gt;</span></span></font></font><span lang="en-GB">)
 
is unique within the whole file.</span></p>
All interested people, companies and research institutions are invited to cooperate to develop {{rml}}. This includes criticism, comments and proposals for modifications of a {{rml}} partial scheme.  
</ul>
 
<p class="western"><span lang="en-GB">Valid means: the scheme or a
All comments must be given in the specific news group at news://sifa.ivi.fhg.de.
railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
 
partial scheme complies the creating instruc&shy;tions for XML
Proposals for modifications may only given via web form using http://www.railml.org > development<ref name="ftn1"><sup>Until the web form will be released the proposal must be given in the specific news group.</sup></ref>  
schemes published by World Wide Web Consortium (W3C). These creating
 
instructions determines all appropriable elements and attributes (see
== Scheme Language ==
[W3C01a]).</span></p>
 
<h2 lang="en-GB" class="western"><a name="__RefHeading___Toc84136238"></a>
The scheme uses “XML Schema Definition Language V1.0 (XSD)”. This specification is available free of charge at W3C (see [[#W3C01a]]). All {{rml}} partial schemes must be valid against XSD specifications.
3.1Development</h2>
 
<p class="western"><span lang="en-GB">The creating of a new railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
== Language ==
partial scheme or the further development of an exist&shy;ing scheme
 
is concluded by railML.org initiative. All railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
All {{rml}} partial schemes must be written in English. This includes names for ob­jects, attributes, default values and comments / annotations.
partial schemes must redeem these creating instructions. </span>
 
</p>
This enables a worldwide use and further development.
<p class="western"><span lang="en-GB">All interested people,
 
companies and research institutions are invited to cooperate to
== Comments ==
develop railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">.
 
This includes criticism, comments and proposals for modifications of
=== Annotations to Objects ===
a railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
 
partial scheme. </span>
All elements, attributs, types and other identifiers of the scheme must be annotated shortly. That is neccesarry for better understanding and efficent further development.
</p>
 
<p class="western"><span lang="en-GB">All comments must be given in
Annotations (element annotations) should be used to comment an identifier. Comments (element comment) are allowed in an area where an annotation is not possible.  
the specific news group at </span><font face="Courier, monospace"><font size="3" style="font-size: 12pt"><span lang="de-DE"><span lang="en-GB">news://sifa.ivi.fhg.de</span></span></font></font><span lang="en-GB">.</span></p>
 
<p class="western"><span lang="en-GB">Proposals for modifications may
Not allowed are comments in brackets (<!-- as start of comment; --> end of com­ment).  
only given via web form using </span><font face="Courier, monospace"><font size="3" style="font-size: 12pt"><span lang="de-DE"><span lang="en-GB">http://www.railml.org</span></span></font></font><span lang="en-GB">
 
&gt; development</span><sup><span lang="en-GB"><a class="sdfootnoteanc" name="sdfootnote1anc" href="#sdfootnote1sym"><sup>1</sup></a></span></sup><span lang="en-GB">
Already existing {{rml}} partial schemes must not converted.
</span>
 
</p>
=== Element History ===
<h2 lang="en-GB" class="western"><a name="__RefHeading___Toc84136239"></a>
 
3.2Scheme Language</h2>
All {{rml}} partial schemes are refined persistantly to meet the requirements in mar­ket and technology. Every partial scheme is developed independently.
<p class="western"><span lang="en-GB">The scheme uses “XML Schema
 
Definition Language V1.0 (XSD)”. This specification is available
Every element and every attribute should get a special annotation containing infor­mation about element’s history. This annotiation should contain
free of charge at W3C (see [W3C01a]). All railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
* the partial scheme’s version with first appearance of this object;
partial schemes must be valid against XSD specifications.</span></p>
 
<h2 lang="en-GB" class="western"><a name="__RefHeading___Toc84136240"></a>
* modifications within this object (name, attributes, hierarchie etc).
3.3Language</h2>
 
<p class="western"><span lang="en-GB">All railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
 
partial schemes must be written in English. This includes names for
 
ob&shy;jects, attributes, default values and comments / annotations.</span></p>
Documentation of an element or a {{rml}} partial scheme can be generated efficently by using these annotations.
<p lang="en-GB" class="western">This enables a worldwide use and
 
further development.</p>
Example:  
<h2 lang="en-GB" class="western"><a name="__RefHeading___Toc84136241"></a>
 
3.4Comments</h2>
<pre>
<h3 lang="en-GB" class="western">3.4.1Annotations to Objects</h3>
<xsd:element name="railml">
<p lang="en-GB" class="western">All elements, attributs, types and
<xsd:annotation>
other identifiers of the scheme must be annotated shortly. That is
<xsd:documentation>railML document root
neccesarry for better understanding and efficent further development.</p>
  </xsd:documentation>
<p class="western"><span lang="en-GB">Annotations (element
<xsd:documentation>History:
</span><font face="Courier, monospace"><font size="3" style="font-size: 12pt"><span lang="de-DE"><span lang="en-GB">annotations</span></span></font></font><span lang="en-GB">)
V0.90 First release
should be used to comment an identifier. Comments (element </span><font face="Courier, monospace"><font size="3" style="font-size: 12pt"><span lang="de-DE"><span lang="en-GB">comment</span></span></font></font><span lang="en-GB">)
are allowed in an area where an annotation is not possible. </span>
</p>
<p class="western"><span lang="en-GB">Not allowed are comments in
brackets (</span><font face="Courier, monospace"><font size="3" style="font-size: 12pt"><span lang="de-DE"><span lang="en-GB">&lt;!--</span></span></font></font><span lang="en-GB">
as start of comment; </span><font face="Courier, monospace"><font size="3" style="font-size: 12pt"><span lang="de-DE"><span lang="en-GB">--&gt;</span></span></font></font><span lang="en-GB">
end of com&shy;ment). </span>
</p>
<p class="western"><span lang="en-GB">Already existing railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
partial schemes must not converted.</span></p>
<h3 lang="en-GB" class="western">3.4.2Element History</h3>
<p class="western"><span lang="en-GB">All railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
partial schemes are refined persistantly to meet the requirements in
mar&shy;ket and technology. Every partial scheme is developed
independently.</span></p>
<p lang="en-GB" class="western">Every element and every attribute
should get a special annotation containing infor&shy;mation about
element’s history. This annotiation should contain  
</p>
<ul>
<li/>
<p lang="en-GB" class="western">the partial scheme’s version
with first appearance of this object;</p>
</ul>
<ul>
<li/>
<p lang="en-GB" class="western">modifications within this
object (name, attributes, hierarchie etc).</p>
</ul>
<p class="western"><span lang="en-GB">Documentation of an element or
a railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
partial scheme can be generated efficently by using these
annotations.</span></p>
<p class="western"><samp class="western"><span lang="en-GB">Example: </span></samp>
</p>
<p align="left"><font face="Courier, monospace"><samp class="western"><font face="Courier, monospace"><font size="3" style="font-size: 12pt"><span lang="en-GB"> &lt;xsd:element
name=&quot;railml&quot;&gt;<br/>
&lt;xsd:annotation&gt;<br/>
&lt;xsd:documentation&gt;railML
document root
&lt;/xsd:documentation&gt;<br/>
&lt;xsd:documentation&gt;History:<br/>
V0.90 First
release<br/>
V0.94 Visualisation included
V0.94 Visualisation included
&lt;/xsd:documentation&gt;<br/>
  </xsd:documentation>
&lt;/xsd:annotation&gt;<br/>
</xsd:annotation>
...
...  
<br/>
</xsd:element>
&lt;/xsd:element&gt;</span></font></font></samp></font></p>
</pre>
<h2 class="western"><a name="__RefHeading___Toc84136242"></a>3.5<span lang="en-GB">Identifiers</span></h2>
== Identifiers ==
<p class="western"><span lang="en-GB">Identifiers are names of
 
elements, attributes and self-defined types. Only self-defined
Identifiers are names of elements, attributes and self-defined types. Only self-defined identifiers are used within {{rml}}.
identifiers are used within railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">.</span></p>
 
<h3 lang="en-GB" class="western">3.5.1Not using Identifiers</h3>
=== Not using Identifiers ===
<p class="western"><span lang="en-GB">Some identifiers caused
 
problems in cooperation with computer software in past. Such
Some identifiers caused problems in cooperation with computer software in past. Such identifiers should not used. (Example: Element “user“ in {{rml}} partial scheme “rolling­stock” caused problems in cooperation with a data base. That’s why this element was renamed in ”operator“.)
identifiers should not used. </span><samp class="western"><span lang="en-GB">(Example:
 
Element “user“ in railML</span></samp><samp class="western"><sup><span lang="en-GB">®</span></sup></samp><samp class="western"><span lang="en-GB">
No all possible identifiers can be tested in cooperation with other computer software. Problems appearing while using a partial scheme should be solved immediately.
partial scheme “rolling&shy;stock” caused problems in cooperation
 
with a data base. That’s why this element was renamed in
=== Lower-case Characters ===
”operator“.)</span></samp></p>
 
<p lang="en-GB" class="western">No all possible identifiers can be
Identifiers consisting of one word must be written in lower-case characters. (Example: element “track”)
tested in cooperation with other computer software. Problems
 
appearing while using a partial scheme should be solved immediately.</p>
=== Camel Spelling ===
<h3 lang="en-GB" class="western">3.5.2Lower-case Characters</h3>
 
<p class="western"><span lang="en-GB">Identifiers consisting of one
Identifiers consisting of more than one word must be concatenated. Thereto the so called “camel spelling” must be used (first character of first word in lower case, first character of all other words in upper case; all other characters in lower case). (Exam­ple: element „trackData“)
word must be written in lower-case characters. </span><samp class="western"><span lang="en-GB">(Example:
 
element “track”)</span></samp></p>
=== Upper-case Characters ===
<h3 lang="en-GB" class="western"><a name="_Ref83706856"></a>3.5.3Camel
 
Spelling</h3>
Upper-case characters are used only to name identifiers with to characters or abbre­viations of common known words. (Example: element „ID“, element „trackID“)
<p class="western"><span lang="en-GB">Identifiers consisting of more
 
than one word must be concatenated. Thereto the so called “camel
=== Self-defined Data Types ===
spelling” must be used (first character of first word in lower
 
case, first character of all other words in upper case; all other
{{rml}} mainly uses self-defined data types. These data types are extension of the existing datat types which are provided by XML Schema Definition (see [[#W3C01b]]).
characters in lower case). </span><samp class="western"><span lang="en-GB">(Exam&shy;ple:
 
element „trackData“)</span></samp></p>
These self-defined data types must be extended with the word “type”. (Example: “trackType“)
<h3 lang="en-GB" class="western">3.5.4Upper-case Characters</h3>
 
<p class="western"><span lang="en-GB">Upper-case characters are used
=== Abbreviations ===
only to name identifiers with to characters or abbre&shy;viations of
 
common known words. (</span><samp class="western"><span lang="en-GB">Example:
The following rules must be redeemed to avoid confusion.* Abbreviations should not be used as part of an identifier. (Example: “opMode“; better “operationMode“)
element „ID“, element „trackID“)</span></samp></p>
* Acronyms, which are not generally accepted within the computer or railway sec­tor, may not be used. (Example: “TP”; better: “trainProtection“)
<h3 lang="en-GB" class="western">3.5.5Self-defined Data Types</h3>
* Acronyms instead of long words may be used if they are generally known. (Exam­ple: „UI“ instead of “userInterface“)
<p class="western"><span lang="en-GB">railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
* Using camel spelling (see 3.5.3) is recommended for abbreviations / acronyms with more than two characters. (Example: “htmlText“ instead of „HTMLText“)
mainly uses self-defined data types. These data types are extension
 
of the existing datat types which are provided by XML Schema
== Globally Unique Identifiers ==
Definition (see [W3C01b]). </span>
 
</p>
Every object (track, train, wagon, crossing etc.) gets a unique identifier (GUID). This ID is unique within the whole {{rml}} scheme and may not changed within the lifetime of this object.
<p class="western"><span lang="en-GB">These self-defined data types
 
must be extended with the word “type”. </span><samp class="western"><span lang="en-GB">(Example:
Using GUIDs needs more discussion in the news group.
“trackType“)</span></samp></p>
 
<h3 lang="en-GB" class="western">3.5.6Abbreviations</h3>
=== Creating Instruction  ===
<p lang="en-GB" class="western">The following rules must be redeemed
 
to avoid confusion.</p>
One creating instruction is:
<ul>
# The first part is the unique IP-adress of the computer which generates the ob­ject. Used IP-version (IPv4 or IPv6) is not relevant.
<li/>
## IPv4 is used in decimal format. Absent zeros will be added, after it the dots as seperator will be removed. (Example: IP 153.96.11.211 will be con­verted in 153.096.011.211, after that in 153096011211.)
<p class="western"><span lang="en-GB">Abbreviations should not
## IPv6 is used in hexadecimal format. Zeros will be added to get always four digits. Colons as seperator will be removed (Example: IPv6 3FFE:400:89AB:381C:7716: AA91::1 is converted into 3FFE040089AB381C7716AA9100000001)
be used as part of an identifier. </span><samp class="western"><span lang="en-GB">(Example:
# This number is construed as character string.
“opMode“; better “operationMode“)</span></samp></p>
# Current system time as milliseconds since 1970-01-01, 00:00:00,0000 is con­catenated as hexadecimal.
<li/>
 
<p class="western"><span lang="en-GB">Acronyms, which are not
Two coding modes of GUID are possible: Base64 or Hexadecimal.
generally accepted within the computer or railway sec&shy;tor, may
 
not be used. </span><samp class="western"><span lang="en-GB">(Example:
=== Alternative Creating Instructions ===
“TP”; better: “trainProtection“)</span></samp></p>
 
<li/>
A second method can be:
<p class="western"><span lang="en-GB">Acronyms instead of long
# First part is physical network device number (media access control MAC) of gen­erating computer. MAC consists of 48 bits. If there exist more than one MAC (more than one netword device) the smallest must be used. (Example: First MAC is 00-02-3F-93-2D-65.)
words may be used if they are generally known. </span><samp class="western"><span lang="en-GB">(Exam&shy;ple:
# Hyphens or colons as seperator within the MAC will be seperated; the result is construed as character string. (Example; MAC 00-02-3F-93-2D-65 is converted into 00023F932D65.)
„UI“ instead of “userInterface“)</span></samp></p>
# Current system time as milliseconds since 1970-01-01, 00:00:00,0000 is con­catenated as hexadecimal. (2004-04-14, 14:32:05,1234 an object is generated on com­puter with above MAC. Elapsed milliseconds since 1970-01-01; 00:00:00,0000 are in hexa­decimal 000000FBE96E875A. GUID is 00023F932D65000000FBE96E875A)
<li/>
 
<p class="western"><span lang="en-GB">Using camel spelling
 
(see 3.5.3) is recommended for abbreviations / acronyms with more
 
than two characters. </span><samp class="western"><span lang="en-GB">(Example:
Two coding modes of GUID are possible: Base64 or Hexadecimal.  
“htmlText“ instead of „HTMLText“)</span></samp></p>
 
</ul>
== Date and Time ==
<h2 lang="en-GB" class="western"><a name="__RefHeading___Toc84136243"></a>
 
3.6Globally Unique Identifiers</h2>
Date and time must be stored uniform, international applicable, understandably and must have a uniform length within {{rml}}. Thereto formates described in ISO 8601 / EN 28601 are applicable.
<p class="western"><span lang="en-GB">Every object (track, train,
 
wagon, crossing etc.) gets a unique identifier (GUID). This ID is
Formats for date and time exist in XML Scheme Definition (see [[#W3C01b]]). These formats must be used.
unique within the whole railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
 
scheme and may not changed within the lifetime of this object.</span></p>
=== Date ===
<p lang="en-GB" class="western">Using GUIDs needs more discussion in
 
the news group.</p>
Date within {{rml}} scheme and {{rml}} files must get the format YYYY-MM-DD. (Ex­ample: 2004-03-05 stands for 5.3.2004, 05.03.04, or 3/5/2004.)
<h3 lang="en-GB" class="western">3.6.1Creating Instruction
 
</h3>
=== Time ===
<p lang="en-GB" class="western">One creating instruction is:</p>
 
<ol>
Times in {{rml}} scheme and {{rml}} files must get the format hh:mm:ss,d. Other formates are not allowed. (Example: 15:54:23,4 stands for 3:54:23,4 PM or 15.54.23,4)
<li/>
 
<p lang="en-GB" class="western">The first part is the unique
=== Time Zone ===
IP-adress of the computer which generates the ob&shy;ject. Used
 
IP-version (IPv4 or IPv6) is not relevant.</p>
Time zone – if needed – is not coded, but the difference to UTC (Universal Time; known also as Greenwich Mean Time GMT or Zulu Time).
<ol type="i">
 
<li/>
All times in time zones eastern to Greenwich/GB will be concatenated with a plus sign “+” and their difference to UTC. Example: 15:54:23,4+0100 (European Standard Time EST)
<p class="western"><span lang="en-GB">IPv4 is used in decimal
 
format. Absent zeros will be added, after it the dots as seperator
All times in time zones western to Greenwich/GB will be concatenated with a minus sign “-” and their difference to UTC. Example: 15:54:23,4-0400 (Atlantic Standard Time AST)
will be removed. </span><samp class="western"><span lang="en-GB">(Example:
 
IP 153.96.11.211 will be con&shy;verted in 153.096.011.211, after
Examples for time zones and their difference to UTC are available at http:// www.timeanddate.com/library/abbreviations/timezones/.
that in 153096011211.)</span></samp></p>
 
<li/>
=== Daylight Savings Time ===
<p class="western"><span lang="en-GB">IPv6 is used in
 
hexadecimal format. Zeros will be added to get always four digits.
Daylight savings time is not marked specially. It is a valid local time.
Colons as seperator will be removed </span><samp class="western"><span lang="en-GB">(Example:
 
IPv6 3FFE:400:89AB:381C:7716: AA91::1 is converted into
==Bibliography==
3FFE040089AB381C7716AA9100000001)</span></samp></p>
===W3C01a===
</ol>
World Wide Web Consortium (W3C): W3C XML Schema. http:// www.w3.org/XML/Schema, Download 2004-02-20, 2001
<li/>
===W3C01b===
<p lang="en-GB" class="western">This number is construed as
World Wide Web Consortium (W3C): XML Schema Part 2: Datatypes W3C Recommendation 02 May 2001. http://www.w3.org/TR/ xmlschema-2/#built-in-datatypes, Download 2004-02-20, 2001
character string.</p>
<li/>
<p lang="en-GB" class="western">Current system time as
milliseconds since 1970-01-01, 00:00:00,0000  is con&shy;catenated
as hexadecimal.</p>
</ol>
<p lang="en-GB" class="western">Two coding modes of GUID are
possible: Base64 or Hexadecimal.  
</p>
<h3 lang="en-GB" class="western">3.6.2Alternative Creating
Instructions</h3>
<p lang="en-GB" class="western">A second method can be:</p>
<ol>
<li/>
<p class="western"><span lang="en-GB">First part is physical
network device number (media access control MAC) of gen&shy;erating
computer. MAC consists of 48 bits. If there exist more than one MAC
(more than one netword device) the smallest must be used. </span><samp class="western"><span lang="en-GB">(Example:
First MAC is 00-02-3F-93-2D-65.)</span></samp></p>
<li/>
<p class="western"><span lang="en-GB">Hyphens or colons as
seperator within the MAC will be seperated; the result is construed
as character string. </span><samp class="western"><span lang="en-GB">(Example;
MAC 00-02-3F-93-2D-65 is converted into 00023F932D65.)</span></samp></p>
<li/>
<p class="western"><span lang="en-GB">Current system time as
milliseconds since 1970-01-01, 00:00:00,0000 is con&shy;catenated as
hexadecimal. </span><samp class="western"><span lang="en-GB">(2004-04-14,
14:32:05,1234 an object is generated on com&shy;puter with above
MAC. Elapsed milliseconds since 1970-01-01; 00:00:00,0000 are in
hexa&shy;decimal 000000FBE96E875A. GUID is
00023F932D65000000FBE96E875A)</span></samp></p>
</ol>
<p class="western"><span lang="en-GB">Two coding modes of GUID are
possible: Base64 or Hexadecimal. </span>
</p>
<h2 lang="en-GB" class="western"><a name="__RefHeading___Toc84136244"></a>
3.7Date and Time</h2>
<p class="western"><span lang="en-GB">Date and time must be stored
uniform, international applicable, understandably and must have a
uniform length within railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">.
Thereto formates described in ISO 8601 / EN 28601 are applicable.</span></p>
<p lang="en-GB" class="western">Formats for date and time exist in
XML Scheme Definition (see [W3C01b]). These formats must be used.</p>
<h3 lang="en-GB" class="western">3.7.1Date</h3>
<p class="western"><span lang="en-GB">Date within railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
scheme and railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
files must get the format YYYY-MM-DD. </span><samp class="western"><span lang="en-GB">(Ex&shy;ample:
2004-03-05 stands for 5.3.2004, 05.03.04, or 3/5/2004.)</span></samp></p>
<h3 lang="en-GB" class="western">3.7.2Time</h3>
<p class="western"><span lang="en-GB">Times in railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
scheme and railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
files must get the format hh:mm:ss,d. Other formates are not allowed.
</span><samp class="western"><span lang="en-GB">(Example: 15:54:23,4
stands for 3:54:23,4 PM or 15.54.23,4)</span></samp></p>
<h3 lang="en-GB" class="western">3.7.3Time Zone</h3>
<p lang="en-GB" class="western">Time zone – if needed – is not
coded, but the difference to UTC (Universal Time; known also as
Greenwich Mean Time GMT or Zulu Time).
</p>
<p class="western"><span lang="en-GB">All times in time zones eastern
to Greenwich/GB will be concatenated with a plus sign “+” and
their difference to UTC. </span><samp class="western"><span lang="en-GB">Example:
15:54:23,4+0100 (European Standard Time EST)</span></samp></p>
<p class="western"><span lang="en-GB">All times in time zones western
to Greenwich/GB will be concatenated with a minus sign “-” and
their difference to UTC. </span><samp class="western"><span lang="en-GB">Example:
15:54:23,4-0400 (Atlantic Standard Time AST)</span></samp></p>
<p class="western"><span lang="en-GB">Examples for time zones and
their difference to UTC are available at </span><font face="Courier, monospace"><font size="3" style="font-size: 12pt"><span lang="de-DE"><span lang="en-GB">http://
www.timeanddate.com/library/abbreviations/timezones/</span></span></font></font><span lang="en-GB">.</span></p>
<h3 lang="en-GB" class="western">3.7.4Daylight Savings Time</h3>
<p lang="en-GB" class="western">Daylight savings time is not marked
specially. It is a valid local time. 
</p>

Revision as of 19:51, 19 May 2016

Creating Guidelines for railML® scheme

This page informs you about the creating instructions for the railML® XML schema in the scope of the development of railML®.

The railML® scheme (“the scheme”) is based on wellformed and valid XML

Wellformed means in this context:

  • every start tag has got an end tag on the same hierarchy;
  • nestings are not allowed;
  • attributes are ;
  • the first element (here: <railml>) is unique within the whole file.

Valid means: the scheme or a railML® partial scheme complies the creating instruc­tions for XML schemes published by World Wide Web Consortium (W3C). These creating instructions determines all appropriable elements and attributes (see #W3C01b).

Development

The creating of a new railML® partial scheme or the further development of an exist­ing scheme is concluded by railML.org initiative. All railML® partial schemes must redeem these creating instructions.

All interested people, companies and research institutions are invited to cooperate to develop railML®. This includes criticism, comments and proposals for modifications of a railML® partial scheme.

All comments must be given in the specific news group at news://sifa.ivi.fhg.de.

Proposals for modifications may only given via web form using http://www.railml.org > development[1]

Scheme Language

The scheme uses “XML Schema Definition Language V1.0 (XSD)”. This specification is available free of charge at W3C (see #W3C01a). All railML® partial schemes must be valid against XSD specifications.

Language

All railML® partial schemes must be written in English. This includes names for ob­jects, attributes, default values and comments / annotations.

This enables a worldwide use and further development.

Comments

Annotations to Objects

All elements, attributs, types and other identifiers of the scheme must be annotated shortly. That is neccesarry for better understanding and efficent further development.

Annotations (element annotations) should be used to comment an identifier. Comments (element comment) are allowed in an area where an annotation is not possible.

Not allowed are comments in brackets ( end of com­ment).

Already existing railML® partial schemes must not converted.

Element History

All railML® partial schemes are refined persistantly to meet the requirements in mar­ket and technology. Every partial scheme is developed independently.

Every element and every attribute should get a special annotation containing infor­mation about element’s history. This annotiation should contain

  • the partial scheme’s version with first appearance of this object;
  • modifications within this object (name, attributes, hierarchie etc).


Documentation of an element or a railML® partial scheme can be generated efficently by using these annotations.

Example:

	<xsd:element name="railml">
		<xsd:annotation>
			<xsd:documentation>railML document root
			  </xsd:documentation>
			<xsd:documentation>History:
					V0.90	First release
					V0.94	Visualisation included
			  </xsd:documentation>
		</xsd:annotation>
		... 
	</xsd:element>

Identifiers

Identifiers are names of elements, attributes and self-defined types. Only self-defined identifiers are used within railML®.

Not using Identifiers

Some identifiers caused problems in cooperation with computer software in past. Such identifiers should not used. (Example: Element “user“ in railML® partial scheme “rolling­stock” caused problems in cooperation with a data base. That’s why this element was renamed in ”operator“.)

No all possible identifiers can be tested in cooperation with other computer software. Problems appearing while using a partial scheme should be solved immediately.

Lower-case Characters

Identifiers consisting of one word must be written in lower-case characters. (Example: element “track”)

Camel Spelling

Identifiers consisting of more than one word must be concatenated. Thereto the so called “camel spelling” must be used (first character of first word in lower case, first character of all other words in upper case; all other characters in lower case). (Exam­ple: element „trackData“)

Upper-case Characters

Upper-case characters are used only to name identifiers with to characters or abbre­viations of common known words. (Example: element „ID“, element „trackID“)

Self-defined Data Types

railML® mainly uses self-defined data types. These data types are extension of the existing datat types which are provided by XML Schema Definition (see #W3C01b).

These self-defined data types must be extended with the word “type”. (Example: “trackType“)

Abbreviations

The following rules must be redeemed to avoid confusion.* Abbreviations should not be used as part of an identifier. (Example: “opMode“; better “operationMode“)

  • Acronyms, which are not generally accepted within the computer or railway sec­tor, may not be used. (Example: “TP”; better: “trainProtection“)
  • Acronyms instead of long words may be used if they are generally known. (Exam­ple: „UI“ instead of “userInterface“)
  • Using camel spelling (see 3.5.3) is recommended for abbreviations / acronyms with more than two characters. (Example: “htmlText“ instead of „HTMLText“)

Globally Unique Identifiers

Every object (track, train, wagon, crossing etc.) gets a unique identifier (GUID). This ID is unique within the whole railML® scheme and may not changed within the lifetime of this object.

Using GUIDs needs more discussion in the news group.

Creating Instruction

One creating instruction is:

  1. The first part is the unique IP-adress of the computer which generates the ob­ject. Used IP-version (IPv4 or IPv6) is not relevant.
    1. IPv4 is used in decimal format. Absent zeros will be added, after it the dots as seperator will be removed. (Example: IP 153.96.11.211 will be con­verted in 153.096.011.211, after that in 153096011211.)
    2. IPv6 is used in hexadecimal format. Zeros will be added to get always four digits. Colons as seperator will be removed (Example: IPv6 3FFE:400:89AB:381C:7716: AA91::1 is converted into 3FFE040089AB381C7716AA9100000001)
  2. This number is construed as character string.
  3. Current system time as milliseconds since 1970-01-01, 00:00:00,0000 is con­catenated as hexadecimal.

Two coding modes of GUID are possible: Base64 or Hexadecimal.

Alternative Creating Instructions

A second method can be:

  1. First part is physical network device number (media access control MAC) of gen­erating computer. MAC consists of 48 bits. If there exist more than one MAC (more than one netword device) the smallest must be used. (Example: First MAC is 00-02-3F-93-2D-65.)
  2. Hyphens or colons as seperator within the MAC will be seperated; the result is construed as character string. (Example; MAC 00-02-3F-93-2D-65 is converted into 00023F932D65.)
  3. Current system time as milliseconds since 1970-01-01, 00:00:00,0000 is con­catenated as hexadecimal. (2004-04-14, 14:32:05,1234 an object is generated on com­puter with above MAC. Elapsed milliseconds since 1970-01-01; 00:00:00,0000 are in hexa­decimal 000000FBE96E875A. GUID is 00023F932D65000000FBE96E875A)


Two coding modes of GUID are possible: Base64 or Hexadecimal.

Date and Time

Date and time must be stored uniform, international applicable, understandably and must have a uniform length within railML®. Thereto formates described in ISO 8601 / EN 28601 are applicable.

Formats for date and time exist in XML Scheme Definition (see #W3C01b). These formats must be used.

Date

Date within railML® scheme and railML® files must get the format YYYY-MM-DD. (Ex­ample: 2004-03-05 stands for 5.3.2004, 05.03.04, or 3/5/2004.)

Time

Times in railML® scheme and railML® files must get the format hh:mm:ss,d. Other formates are not allowed. (Example: 15:54:23,4 stands for 3:54:23,4 PM or 15.54.23,4)

Time Zone

Time zone – if needed – is not coded, but the difference to UTC (Universal Time; known also as Greenwich Mean Time GMT or Zulu Time).

All times in time zones eastern to Greenwich/GB will be concatenated with a plus sign “+” and their difference to UTC. Example: 15:54:23,4+0100 (European Standard Time EST)

All times in time zones western to Greenwich/GB will be concatenated with a minus sign “-” and their difference to UTC. Example: 15:54:23,4-0400 (Atlantic Standard Time AST)

Examples for time zones and their difference to UTC are available at http:// www.timeanddate.com/library/abbreviations/timezones/.

Daylight Savings Time

Daylight savings time is not marked specially. It is a valid local time.

Bibliography

W3C01a

World Wide Web Consortium (W3C): W3C XML Schema. http:// www.w3.org/XML/Schema, Download 2004-02-20, 2001

W3C01b

World Wide Web Consortium (W3C): XML Schema Part 2: Datatypes W3C Recommendation 02 May 2001. http://www.w3.org/TR/ xmlschema-2/#built-in-datatypes, Download 2004-02-20, 2001

  1. Until the web form will be released the proposal must be given in the specific news group.