Dev:Coding XML Components

XML Elements

Documentation

Elements without parent inheritance

Each XML element should be explained by a short documentation inside the XML Schema file.

Each XML element should link to its appropriate element documentation site in this railML wiki.

<xs:element ...>
  <xs:annotation>
    <xs:documentation><short-explanation></xs:documentation>
    <xs:documentation source="http://www.wiki.railml.org/index.php?title=<sub-schema-prefix>:<element-name>"/>
  </xs:annotation>
</xs:element>

example:

<xs:element name="vehicles" type="rail:eVehicles" minOccurs="0">
  <xs:annotation>
    <xs:documentation>container for single vehicle data or vehicle family data</xs:documentation>
    <xs:documentation source="http://www.wiki.railml.org/index.php?title=RS:vehicles"/>
  </xs:annotation>
</xs:element>

Elements with parent inheritance

Each XML element should be explained by a short documentation inside the XML Schema file.

Each XML element should link to its appropriate element documentation site in this railML wiki.

Elements with parent inheritance are used at several positions in the XML-Tree. All these occurences have their own element documentation site. Thus all these sites should be cited. Best way would be to use the order of occurence in a full XML instance document.

<xs:element ...>
  <xs:annotation>
    <xs:documentation><short-explanation></xs:documentation>
    <xs:documentation source="http://www.wiki.railml.org/index.php?title=<sub-schema-prefix>:<element-name>_<parent-element-name>"/>
    <xs:documentation source="http://www.wiki.railml.org/index.php?title=<sub-schema-prefix>:<element-name>_<parent-element-name>"/>
    <xs:documentation source="http://www.wiki.railml.org/index.php?title=<sub-schema-prefix>:<element-name>_<parent-element-name>"/>
    ...
  </xs:annotation>
</xs:element>

example:

<xs:element name="geoCoord" type="rail:tGeoCoord" minOccurs="0">
  <xs:annotation>
    <xs:documentation source="http://www.wiki.railml.org/index.php?title=IS:geoCoord_switch"/>
    <xs:documentation source="http://www.wiki.railml.org/index.php?title=IS:geoCoord_crossing"/>
    <xs:documentation source="http://www.wiki.railml.org/index.php?title=IS:geoCoord_crossSection"/>
    ...
  </xs:annotation>
</xs:element>

XML Attributes

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

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>

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" />