Dev:Creating instructions

From wiki.railML.org
Jump to: navigation, search

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.

If you have any comments on the railML® XML-Tree or want to suggest modifications please tell us your proposal in our forum on http://forum.railml.org (railML® website).

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

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 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). 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.

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