Dev:Coding XML Components

From railML 2 Wiki
Jump to navigation Jump to search

XML Elements

Documentation

General Rules

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 page in the railML® 2 wiki (wiki2.railml.org). 

<xs:element ...>
  <xs:annotation>
    <xs:documentation><short-explanation></xs:documentation>
    <xs:documentation source="https://wiki2.railml.org/wiki/<sub-schema-prefix>:<element-name>"/>
  </xs:annotation>
</xs:element>

example for railML® 2: 

<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="https://wiki2.railml.org/wiki/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 page here in the railML® wiki.

Elements with parent inheritance are used at several positions in the XML-Tree.

In the railML® 2 wiki, the elements with parent inheritance can have either just one documentation page (see <geoCoord> for an example), or separate page per parent. In the latter case there will be a page listing the multiple uses (see <crossedElement> for an example). In both cases, it is normally sufficient to cite either the common documentation page or the multiple uses page. Note that in some cases, the parents may belong to more than one schema, and in that case you have to cite the multiple uses page for each schema: 

<xs:element name="additionalName" type="rail:tAdditionalName" minOccurs="0" maxOccurs="unbounded">
  <xs:annotation>
    <xs:documentation>additional names and its according descriptions to be provided in other languages, dialects, encodings...</xs:documentation>
    <xs:documentation source="https://wiki2.railml.org/wiki/IS:additionalName" />
    <xs:documentation source="https://wiki2.railml.org/wiki/RS:additionalName" />
    <xs:documentation source="https://wiki2.railml.org/wiki/TT:additionalName" />
  </xs:annotation>
</xs:element>

Key and keyref constraints

Keys and its references (keyref) may be used to define some semantic constraints. They ensure, that a reference may not point to an id of another element than foreseen by the schema. This mechanism is checked by the XML validator.

xs:key definition

Keys have to be defined for all id attributes which are referred somewhere within the railML® schema.

If all references are within one sub-schema the key has to be defined in the top-most element of this sub-schema, e.g. <infrastructure>, <rollingstock>, <timetable>.

Otherwise (references also in other sub-schema) the key has to be defined in the root element <railml>.

<!-- <element-name> identitiy in <sub-schema-name> subschema -->
<xs:key name="<element-name>Key">
  <xs:selector xpath=".//<unambiguous-path-to-element>" />
  <xs:field xpath="@id" />
</xs:key>

example: 

 <!-- ocp identitiy in infrastructure subschema -->
 <xs:key name="ocpKey">
   <xs:selector xpath=".//rail:operationControlPoints/rail:ocp" />
   <xs:field xpath="@id" />
 </xs:key>


xs:keyref definition

Keyrefs have to be defined for all ref and *Ref attributes. They should all refer to a certain element's id attribute.

The keyref has to be defined directly after its corresponding key definition in one of the following files <infrastructure>, <rollingstock>, <timetable>, <railml>.

All keyrefs for a certain key should be sorted by the sub-schema of its referring element.

    <xs:keyref name="ocp-<referring-element-name>Keyref" refer="rail:<referred-element-name>Key">
      <xs:selector xpath=".//<unambiguous-path-to-element>" />
      <xs:field xpath="@<referring-attribute-name>" />
    </xs:keyref>

example: 

    <xs:keyref name="ocp-platformEdgeKeyref" refer="rail:ocpKey">
      <xs:selector xpath=".//rail:platformEdges/rail:platformEdge" />
      <xs:field xpath="@ocpRef" />
    </xs:keyref>

xs:keyref constraints test

The XML-Validator may not check if the XPath in the xs:field element is right. This may only be checked with an XML example that fails with a wrong ref or *Ref attribute. That's the reason for the files in the folder defectSamples.

  1. Open the appropriate file for the sub-schema of the reference, that should be checked.
  2. If the file does not contain the referred element with its id attribute, define it.
  3. Insert the reference with a valid value.
  4. Validate.
  5. If you encounter an error message for your newly introduced reference, there is an error in the XPath of the xs:field element of the xs:keyref definition.
    Correct it and validate again until you don't get an error message for this attribute.
  6. In the comment at the top of the file there is a counter for the current error messages. At this stage there should be exactly this number of error messages.
  7. Change the reference to a value that is covered by another id attribute, but not the correct one.
    If you define a value that is not used as an id within this file the XML Validator gives error messages regarding the identity constraint. The "real keyref problem" may then be hidden behind this error and does not show up.
  8. There should be one more error message.
  9. Change the count of error messages in the comment.
  10. Commit all changes (key, keyref, defectSample) together, if possible. Thank you.

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" />
Retrieved from "https://wiki2.railml.org/index.php?title=Dev:Coding_XML_Components&oldid=15245"