Dev:Coding XML Components

From railML 2 Wiki
Revision as of 13:19, 16 October 2012 by RailML Superseded Users (talk | contribs) (Content copied from Assemblas Wiki page "Coding_Policy")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

XML Elements

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