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 instructions for XML schemes published by World Wide Web Consortium (W3C). These creating instructions determines all appropriable elements and attributes (see #W3C01b).
- 1 Development
- 2 Scheme Language
- 3 Language
- 4 Comments
- 5 Identifiers
- 6 Globally Unique Identifiers
- 7 Date and Time
- 8 Bibliography
The creating of a new railML® partial scheme or the further development of an existing 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.
If you have any comments on the railML® XML-Tree or want to suggest modifications please tell us your proposal in our forum on https://forum.railml.org (link to the railML® website).
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.
All railML® partial schemes must be written in English. This includes names for objects, attributes, default values and comments / annotations.
This enables a worldwide use and further development.
Beside the XML-comments, the elements are also documented within this wiki. The XML-comments take the precedence over the wiki documentation, but the wiki documentation is broader. You can find the element documentations, following the XML-tree down from the main subschema elements IS:infrastructure, TT:timetable and RS:rollingstock.
Annotations to Objects
All elements, attributs, types and other identifiers of the scheme must be annotated shortly. That is necessary 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 comment).
Already existing railML® partial schemes must not converted.
All railML® partial schemes are refined persistantly to meet the requirements in market and technology. Every partial scheme is developed independently.
Every element and every attribute should get a special annotation containing information 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.
<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 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 “rollingstock” 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.
Identifiers consisting of one word must be written in lower-case characters. (Example: element “track”)
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). (Example: element „trackData“)
Upper-case characters are used only to name identifiers with to characters or abbreviations 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“)
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 sector, may not be used. (Example: “TP”; better: “trainProtection“)
- Acronyms instead of long words may be used if they are generally known. (Example: „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). GUIDs are a special form of UUIDs. This ID is unique within the whole railML® scheme and may not changed within the lifetime of this object.
One creating instruction is:
- The first part is the unique IP-adress of the computer which generates the object. Used IP-version (IPv4 or IPv6) is not relevant.
- IPv4 is used in decimal format. Absent zeros will be added, after it the dots as seperator will be removed. (Example: IP 220.127.116.11 will be converted in 153.096.011.211, after that in 153096011211.)
- 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)
- This number is construed as character string.
- Current system time as milliseconds since 1970-01-01, 00:00:00,0000 is concatenated as hexadecimal.
Two coding modes of GUID are possible: Base64 or Hexadecimal.
Alternative Creating Instructions
A second method can be:
- First part is physical network device number (media access control MAC) of generating 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.)
- 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.)
- Current system time as milliseconds since 1970-01-01, 00:00:00,0000 is concatenated as hexadecimal. (2004-04-14, 14:32:05,1234 an object is generated on computer with above MAC. Elapsed milliseconds since 1970-01-01; 00:00:00,0000 are in hexadecimal 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 within railML® scheme and railML® files must get the format YYYY-MM-DD. (Example: 2004-03-05 stands for 5.3.2004, 05.03.04, or 3/5/2004.)
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 – 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 https://www.timeanddate.com/library/abbreviations/timezones (external link).
Daylight Savings Time
Daylight savings time is not marked specially. It is a valid local time.
World Wide Web Consortium (W3C): W3C XML Schema. https://www.w3.org/XML/Schema (Download 2004-02-20, 2001)
World Wide Web Consortium (W3C): XML Schema Part 2: Datatypes W3C Recommendation 02 May 2001. https://www.w3.org/TR/xmlschema-2/#built-in-datatypes (Download 2004-02-20, 2001)