View source for Dev:Coding XML Components

== 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 {{rml|2}} wiki ({{wiki2|#|wiki2.railml.org}}).

<syntaxhighlight line lang="xml">
<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>
</syntaxhighlight>

example for {{rml|2}}:

<syntaxhighlight line lang="xml">
<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>
</syntaxhighlight>

==== 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 {{rml}} wiki.

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

In the {{rml|2}} wiki, the elements with parent inheritance can have either just one documentation page (see {{IS:Tag|geoCoord|wiki=2}} for an example), or separate page per parent. In the latter case there will be a {{wiki2|:Category:Multiply_used_names|page listing the multiple uses}} (see {{IS:Tag|crossedElement|wiki=2}} 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:

<syntaxhighlight line lang="xml">
<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>
</syntaxhighlight>
=== Key and keyref constraints ===

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

==== xs:key definition ====

<p>Keys have to be defined for all {{Attr|id}} attributes which are referred somewhere within the {{rml}} schema.</p>
<p>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. {{IS:Tag|infrastructure}}, {{RS:Tag|rollingstock}}, {{TT:Tag|timetable}}.</p>
<p>Otherwise (references also in other sub-schema) the key has to be defined in the root element {{CO:Tag|railml}}.</p>

<syntaxhighlight line lang="xml">
<!-- <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>
</syntaxhighlight>

example:

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


==== xs:keyref definition ====

<p>Keyrefs have to be defined for all {{Attr|ref}} and {{Attr|*Ref}} attributes. They should all refer to a certain element's {{Attr|id}} attribute.</p>
<p>The keyref has to be defined directly after its corresponding key definition in one of the following files {{IS:Tag|infrastructure}}, {{RS:Tag|rollingstock}}, {{TT:Tag|timetable}}, {{CO:Tag|railml}}.</p>
<p>All keyrefs for a certain key should be sorted by the sub-schema of its referring element.</p>

<syntaxhighlight line lang="xml">
    <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>
</syntaxhighlight>

example:

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

==== xs:keyref constraints test ====

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

<ol>
<li>Open the appropriate file for the sub-schema of the reference, that should be checked.</li>
<li>If the file does not contain the referred element with its {{Attr|id}} attribute, define it.</li>
<li>Insert the reference with a valid value.</li>
<li>Validate.</li>
<li>If you encounter an error message for your newly introduced reference, there is an error in the XPath of the <code>xs:field</code> element of the <code>xs:keyref</code> definition.<br>Correct it and validate again until you don't get an error message for this attribute.</li>
<li>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.</li>
<li>Change the reference to a value that is covered by another {{Attr|id}} attribute, but not the correct one.<br>If you define a value that is not used as an {{Attr|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.</li>
<li>There should be one more error message.</li>
<li>Change the count of error messages in the comment.</li>
<li>Commit all changes (key, keyref, defectSample) together, if possible. Thank you.</li>
</ol>

== XML Attributes ==

=== Attribute names for identities ===

==== Unique identities ====

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

XML validators check their uniqueness across an XML file. They also check references (<code>xs:IDREF</code>, <code>rail:tGenericRef</code>) 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>code</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: <code>dir</code> for "direction"

==== Domain specific acronym ====

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

example: <code>srsVersion</code> 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: <code>numberNonDrivenAxles</code>

=== 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: <pre><axleWeight value="..."/></pre>


== XML Types ==

=== XML model group ===

Use of <code>xs:sequence</code> as xml model group for complex types

<syntaxhighlight line lang="xml">
<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>
</syntaxhighlight>

=== Simple types constrained by enumeration values ===

==== General XML schema structure ====

Often the enumeration list can't cover all possible values. Adding the <code>xs:union</code> with <code>rail:tOtherEnumerationValue</code> type allows for using "other:xxx" enumeration values in XML without declaring them in XML schema.

example:
<syntaxhighlight line lang="xml">
<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>
</syntaxhighlight>

==== Camel case in enumeration values ====

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

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

[[Category:GeneralDescription]]