Coding Policy

File intentions

*Types.xsd Files in schema/

XML components

XML Elements

XML Attributes

1. Attribute names for identities

• Unique identities

Attributes that are bound to the base type xs:ID (rail:tGenericID) should be named id or *ID.

XML validators check their uniqueness across an XML file. They also check references (xs:IDREF, rail:tGenericRef) to match one of their values.

• Other domain specific identities

Other attributes that represent domain specific unique identities across a company, country or region should either use the generic code attribute or should be named with “number” or something like that.

Attribute names using acronyms and abbreviations

• Abbreviated word

Some attributes appear really often, they could be named with an abbreviation.

example: dir for “direction”

• Domain specific acronym

Some attributes represent a domain specific acronym, which should be fully declared in its schema annotation.

example: srsVersion for “ETCS System Requirements Specification Version”

• Other names

All other attribute names should not be abbreviated for easier understanding the XML content without special schema annotations.

example: numberNonDrivenAxles

Attribute names in elements context

• Context specific attribute name

The attribute name has to be interpreted in the elements context. It doesn’t need to be declarative without its elements context. The elements name shouldn’t be repeated inside the attributes name.

example: <axleWeight value="..."/>

XML Types

1. XML model group

Use of xs:sequence as xml model group for complex types

<xs:complexType name="eClassification">
  <xs:sequence>
    <xs:element name="manufacturer" type="rail:tManufacturer" minOccurs="0">
      ...
    </xs:element>
    <xs:element name="operator" type="rail:tOperator" minOccurs="0" maxOccurs="unbounded">
      ...
    </xs:element>
  </xs:sequence>
</xs:complexType>

2. Simple types constrained by enumeration values

• General XML schema structure

Often the enumeration list can’t cover all possible values. Adding the xs:union with rail:tOtherEnumerationValue type allows for using “other:xxx” enumeration values in XML without declaring them in XML schema.

example:

<xs:simpleType name="tMotivePowerType">
  <xs:union>
    <xs:simpleType>
      <xs:restriction base="xs:string">
        <xs:enumeration value="electric" />
        <xs:enumeration value="diesel" />
        <xs:enumeration value="steam" />
      </xs:restriction>
    </xs:simpleType>
    <xs:simpleType>
      <xs:restriction base="rail:tOtherEnumerationValue" />
    </xs:simpleType>
  </xs:union>
</xs:simpleType>

Camel case in enumeration values

Enumeration values should be named with typical XML camel case. No whitespaces should be used.

example: <xs:enumeration value="outOfOrder" />

Syntactic Guidelines

Camel Case

Whitespaces

1. Empty end-tags
   

   Implementation with 1 space before closing empty end-tags

   example: <xs:restriction base="xs:ID" />

2. Indents
   

   Implementation with 2 spaces

   example:
   

   <xs:element name="railml">
     <xs:complexType>
       <xs:sequence>
         <xs:element name="metadata" type="dc:elementContainer" minOccurs="0" />
         <xs:element ref="rail:infrastructure" minOccurs="0" />

Line Breaks

1. Each component declaration must be followed by a line break.
   

   example:
   

   <xs:attributeGroup name="aPlaces">
     <xs:attribute name="category" type="rail:tPlaceCategory" use="required" />
     <xs:attribute name="count" type="rail:tCounter" use="required" />

2. There is no maximum line length
   

   Each component has to be fully declared on one line without line breaks.

   example:
   

   <xs:schema xmlns:rail="http://www.railml.org/schemas/2009" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:dc="http://purl.org/dc/elements/1.1/" targetNamespace="http://www.railml.org/schemas/2009"	elementFormDefault="qualified" version="2.0">

XML Default Values

1. Empty elements and attributes
   

   see also: http://www.w3.org/TR/REC-xml/#NT-EmptyElemTag

   Implementation with shortened syntax instead of extra closing tag

   example: <xs:element ref="rail:infrastructure" minOccurs="0" />

XMLSchema Default Values

1. Optional and required attributes
   

   see also: http://www.w3.org/TR/xmlschema-1/#declare-attribute

   • Implementation without use="optional"
     

     example: <xs:attribute name="description" type="rail:tElementDescription" />

   • Implementation with use="required"
     

     example: <xs:attribute name="id" type="rail:tGenericID" use="required" />

2. Elements with minimum 1 or maximum 1 occurrence
   

   see also: http://www.w3.org/TR/xmlschema-1/#declare-element

   • Implementation without minOccurs="1"
     

     example: <xs:element name="train" type="rail:eTrain" maxOccurs="unbounded" />

   • Implementation without maxOccurs="1"
     

     example: <xs:element ref="rail:timetable" minOccurs="0" />

3. Occurence restrictions into elements
   

   If possible, all occurence restrictions have to go into element definitions.

   xs:sequence should stand without the attributes minOccurs and/or maxOccurs.

   example:

   <xs:extension base="rail:tElementWithIDAndName">
     <xs:sequence>
       <xs:element name="metadata" type="dc:elementContainer" minOccurs="0" />
     </xs:sequence>
   

Pathes inside XML documents

1. Attribute xsi:schemaLocation
   

   see also: http://www.w3.org/TR/xmlschema-1/#schema-loc

   • Implementation with slashes, no backslashes permitted
     

     example:
     

     <railml xmlns="http://www.railml.org/schemas/2009" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
       xsi:schemaLocation="http://www.railml.org/schemas/2009 ../schema/railML.xsd">