Dev:Creating instructions: Difference between revisions

From railML 2 Wiki
Jump to navigation Jump to search
[unchecked revision][checked 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…“)
 
({{mirror}})
(12 intermediate revisions by the same user not shown)
Line 1: Line 1:
<h1 class="western"><a name="__RefHeading___Toc84136237"></a>3<span lang="en-GB">Creating
{{mirror}}
Guidelines for railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
scheme</span></h1>
<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>
</p>
<p lang="en-GB" class="western">Wellformed means in this context:</p>
<ul>
<li/>
<p lang="en-GB" class="western">every start tag has got an end
tag on the same hierarchy;</p>
<li/>
<p lang="en-GB" class="western">nestings are not allowed;</p>
<li/>
<p lang="en-GB" class="western">attributes are ;</p>
<li/>
<p class="western"><span lang="en-GB">the first element (here:
</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>
</ul>
<p class="western"><span lang="en-GB">Valid means: the scheme or a
railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
partial scheme complies the creating instruc&shy;tions for XML
schemes published by World Wide Web Consortium (W3C). These creating
instructions determines all appropriable elements and attributes (see
[W3C01a]).</span></p>
<h2 lang="en-GB" class="western"><a name="__RefHeading___Toc84136238"></a>
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">
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">
partial schemes must redeem these creating instructions. </span>
</p>
<p class="western"><span lang="en-GB">All interested people,
companies and research institutions are invited to cooperate to
develop railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">.
This includes criticism, comments and proposals for modifications of
a railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
partial scheme. </span>
</p>
<p class="western"><span lang="en-GB">All comments must be given in
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
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">
</span>
</p>
<h2 lang="en-GB" class="western"><a name="__RefHeading___Toc84136239"></a>
3.2Scheme Language</h2>
<p class="western"><span lang="en-GB">The scheme uses “XML Schema
Definition Language V1.0 (XSD)”. This specification is available
free of charge at W3C (see [W3C01a]). All railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
partial schemes must be valid against XSD specifications.</span></p>
<h2 lang="en-GB" class="western"><a name="__RefHeading___Toc84136240"></a>
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>
<p lang="en-GB" class="western">This enables a worldwide use and
further development.</p>
<h2 lang="en-GB" class="western"><a name="__RefHeading___Toc84136241"></a>
3.4Comments</h2>
<h3 lang="en-GB" class="western">3.4.1Annotations to Objects</h3>
<p lang="en-GB" class="western">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">Annotations (element
</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">)
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
&lt;/xsd:documentation&gt;<br/>
&lt;/xsd:annotation&gt;<br/>
...
<br/>
&lt;/xsd:element&gt;</span></font></font></samp></font></p>
<h2 class="western"><a name="__RefHeading___Toc84136242"></a>3.5<span lang="en-GB">Identifiers</span></h2>
<p class="western"><span lang="en-GB">Identifiers are names of
elements, attributes and self-defined types. Only self-defined
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>
<p class="western"><span lang="en-GB">Some identifiers caused
problems in cooperation with computer software in past. Such
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">
partial scheme “rolling&shy;stock” caused problems in cooperation
with a data base. That’s why this element was renamed in
”operator“.)</span></samp></p>
<p lang="en-GB" class="western">No all possible identifiers can be
tested in cooperation with other computer software. Problems
appearing while using a partial scheme should be solved immediately.</p>
<h3 lang="en-GB" class="western">3.5.2Lower-case Characters</h3>
<p class="western"><span lang="en-GB">Identifiers consisting of one
word must be written in lower-case characters. </span><samp class="western"><span lang="en-GB">(Example:
element “track”)</span></samp></p>
<h3 lang="en-GB" class="western"><a name="_Ref83706856"></a>3.5.3Camel
Spelling</h3>
<p class="western"><span lang="en-GB">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). </span><samp class="western"><span lang="en-GB">(Exam&shy;ple:
element „trackData“)</span></samp></p>
<h3 lang="en-GB" class="western">3.5.4Upper-case Characters</h3>
<p class="western"><span lang="en-GB">Upper-case characters are used
only to name identifiers with to characters or abbre&shy;viations of
common known words. (</span><samp class="western"><span lang="en-GB">Example:
element „ID“, element „trackID“)</span></samp></p>
<h3 lang="en-GB" class="western">3.5.5Self-defined Data Types</h3>
<p class="western"><span lang="en-GB">railML</span><sup><span lang="en-GB">®</span></sup><span lang="en-GB">
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]). </span>
</p>
<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:
“trackType“)</span></samp></p>
<h3 lang="en-GB" class="western">3.5.6Abbreviations</h3>
<p lang="en-GB" class="western">The following rules must be redeemed
to avoid confusion.</p>
<ul>
<li/>
<p class="western"><span lang="en-GB">Abbreviations should not
be used as part of an identifier. </span><samp class="western"><span lang="en-GB">(Example:
“opMode“; better “operationMode“)</span></samp></p>
<li/>
<p class="western"><span lang="en-GB">Acronyms, which are not
generally accepted within the computer or railway sec&shy;tor, may
not be used. </span><samp class="western"><span lang="en-GB">(Example:
“TP”; better: “trainProtection“)</span></samp></p>
<li/>
<p class="western"><span lang="en-GB">Acronyms instead of long
words may be used if they are generally known. </span><samp class="western"><span lang="en-GB">(Exam&shy;ple:
„UI“ instead of “userInterface“)</span></samp></p>
<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:
“htmlText“ instead of „HTMLText“)</span></samp></p>
</ul>
<h2 lang="en-GB" class="western"><a name="__RefHeading___Toc84136243"></a>
3.6Globally Unique Identifiers</h2>
<p class="western"><span lang="en-GB">Every object (track, train,
wagon, crossing etc.) gets a unique identifier (GUID). This ID is
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>
<p lang="en-GB" class="western">Using GUIDs needs more discussion in
the news group.</p>
<h3 lang="en-GB" class="western">3.6.1Creating Instruction
</h3>
<p lang="en-GB" class="western">One creating instruction is:</p>
<ol>
<li/>
<p lang="en-GB" class="western">The first part is the unique
IP-adress of the computer which generates the ob&shy;ject. Used
IP-version (IPv4 or IPv6) is not relevant.</p>
<ol type="i">
<li/>
<p class="western"><span lang="en-GB">IPv4 is used in decimal
format. Absent zeros will be added, after it the dots as seperator
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
that in 153096011211.)</span></samp></p>
<li/>
<p class="western"><span lang="en-GB">IPv6 is used in
hexadecimal format. Zeros will be added to get always four digits.
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
3FFE040089AB381C7716AA9100000001)</span></samp></p>
</ol>
<li/>
<p lang="en-GB" class="western">This number is construed as
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 21:08, 23 January 2020

🗒️ This page is mirrored from page Dev:Creating instructions in The railML® 3 wiki.

[Template fetch failed for https://wiki3.railml.org/index.php?title=Dev:Creating_instructions&action=raw: HTTP 404]

Retrieved from "https://wiki2.railml.org/index.php?title=Dev:Creating_instructions&oldid=10397"