Dev:UsingAny

There are multiple possibilities for extending the officially published railML schemas by own needs, e.g. elements, attributes and enumeration values. The following sections show how to achieve this in a valid form.

Defining own elements, respective sub-trees (Use of xs:any)

There are multiple positions where the railML schemas provide the W3C xs:any element for optional extension by own elements, respective sub-trees. That's the case for all elements with the generic railML attributes id, code, name, description... and at other certain positions in the XML tree forseen for extensibility.

<xs:any namespace="##other" processContents="strict" minOccurs="0" maxOccurs="unbounded" />

• namespace="##other" means that the railML schemas force the extensions to be defined in an own new namespace that differs from the railML one. See also Namespace handling
• processContents="strict" means that the railML schemas force all extensions to be defined by an XML Schema (*.xsd).
• minOccurs="0" means that there may be no extensions at this certain position.
• maxOccurs="unbounded" means that the railML schemas allow an "unbounded" amount of extension elements at this certain position.

In case of general extensions this feedback should be provided to the railML community e.g. by announcing in the appropriate railML forum or at minimum by mail to the appropriate railML coordinator.

Example for an extension XML Schema defining own elements without any railML re-use

XML Schema with comments

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="http://www.my-company.com/my-department/" xmlns="http://www.my-company.com/my-department/" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.0">

  <!-- Person to contact in case of any questions regarding the schema: Max Mustermann, phone: +12-345-67890, mail: max.mustermann@my-company.com -->

  <xs:element name="mySpecifics">
    <xs:annotation>
      <xs:documentation>Our companies' extensions follow in this sub-tree</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name="contract" type="contractType" minOccurs="0">
	  <xs:annotation>
	    <xs:documentation>Each element may be enriched with contract details.</xs:documentation>
	  </xs:annotation>
	</xs:element>
	<xs:element name="personResponsible" type="xs:string">
	  <xs:annotation>
	    <xs:documentation>Each element should be defined with a person that is responsible for the content.</xs:documentation>
	  </xs:annotation>
	</xs:element>
      </xs:sequence>
      <xs:attribute name="version" type="xs:string" use="required"/>
    </xs:complexType>
  </xs:element>

  <xs:complexType name="contractType">
    <xs:sequence>
      <xs:element name="number" type="xs:string">
        <xs:annotation>
	  <xs:documentation>In case the contract details are known, the contract number for this element should be defined.</xs:documentation>
	</xs:annotation>
      </xs:element>
      <xs:element name="requirement" type="xs:string" maxOccurs="unbounded">
        <xs:annotation>
	  <xs:documentation>In case the contract details are known, the requirements numbers for this element should be defined.</xs:documentation>
	</xs:annotation>
      </xs:element>
    </xs:sequence>
  </xs:complexType>

</xs:schema>

• This example does not re-use railML elements, attributes, attribute groups, types, groups. It is fully based on XML Schema types.
• The version attribute in the root element marks the version of the extension schema and should be not confused with the railML version.
• It is recommended to use the XML comments for non-content related documentation, e.g. contact information: <!-- ... -->
• It is recommended to use the XML Schema possibilities for documentation inside the extension schema: xs:annotation and xs:documentation
• The elements mySpecifics and contract show how to define sub-trees. The elements personResponsible, number and requirement however define single elements without children.
• The element contract may occur once or not at all at the certain position. The element personResponsible must occur one. In case the element contract is used the elements number and requirement have to be used, too. The element requirement may occur more than once.
• The attribute version has to be defined inside the element mySpecifics.

The following XML instance document shows an example how to deploy these extensions within a railML file.

XML Instance with comments

<?xml version="1.0" encoding="UTF-8"?>
<railml xmlns="http://www.railml.org/schemas/2011" xmlns:my="http://www.my-company.com/my-department/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.railml.org/schemas/2011 ../schema/railML.xsd http://www.my-company.com/my-department/ genericExtension.xsd" version="2.1">
  <timetable id="tt1">
    <my:mySpecifics version="1.0">
      <my:contract>
        <my:number>1234-56/789</my:number>
	<my:requirement>123.456.78.9</my:requirement>
      </my:contract>
      <my:personResponsible>Max Mustermann</my:personResponsible>
    </my:mySpecifics>
    <categories>
      <category id="c1" code="IC" name="InterCity" description="Fast large city connection" trainUsage="passenger">
        <my:mySpecifics version="1.0">
          <my:personResponsible>Marie Mustermann</my:personResponsible>
        </my:mySpecifics>
      </category>
      <category id="c2" code="RE" name="RegionalExpress" description="Fast small city connection" trainUsage="passenger"/>
    </categories>
  </timetable>
</railml>

• The element timetable shows the full usage of the extension elements and attributes. The first category element shows the usage of all required extension elements and attributes. The second category element shows the absence of the extension elements and attributes.
• The extensions are clearly distinguishable from the railML core by defining the appropriate namespaces.

Example for an extension XML Schema defining own elements with some railML re-use

XML Schema with comments

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="http://www.my-company.com/my-department/" xmlns="http://www.my-company.com/my-department/" xmlns:rail="http://www.railml.org/schemas/2011" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.0">

  <!-- Person to contact in case of any questions regarding the schema: Max Mustermann, phone: +12-345-67890, mail: max.mustermann@my-company.com -->

  <xs:import namespace="http://www.railml.org/schemas/2011" schemaLocation="../schema/railML.xsd">
    <xs:annotation>
      <xs:documentation>Copyright (c) railML.org; All Rights Reserved.</xs:documentation>
      <xs:documentation>This work is licensed under a Creative Commons Attribution 2.0 License. http://creativecommons.org/licenses/by/2.0/</xs:documentation>
      <xs:documentation>For further information see: http://www.railml.org/</xs:documentation>
    </xs:annotation>
  </xs:import>

  <xs:element name="mySpecifics">
    <xs:annotation>
      <xs:documentation>Our companies' extensions follow in this sub-tree</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name="contract" type="contractType" minOccurs="0">
	  <xs:annotation>
	    <xs:documentation>Each element may be enriched with contract details.</xs:documentation>
	  </xs:annotation>
	</xs:element>
	<xs:element name="personResponsible" type="xs:string">
	  <xs:annotation>
	    <xs:documentation>Each element should be defined with a person that is responsible for the content.</xs:documentation>
	  </xs:annotation>
	</xs:element>
      </xs:sequence>
      <xs:attribute name="version" type="rail:tVersionNumber" use="required"/>
    </xs:complexType>
  </xs:element>

  <xs:complexType name="contractType">
    <xs:complexContent>
      <xs:extension base="rail:tElementWithIDAndNameWithoutAny">
        <xs:annotation>
	  <xs:documentation>In case the contract details are known, the contract number for this element should be defined within the 'code' attribute.</xs:documentation>
	</xs:annotation>
        <xs:sequence>
	  <xs:element name="requirement" type="rail:tGenericName" maxOccurs="unbounded">
	    <xs:annotation>
	      <xs:documentation>In case the contract details are known, the requirements numbers for this element should be defined.</xs:documentation>
	    </xs:annotation>
	  </xs:element>
	</xs:sequence>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

</xs:schema>

• The railML namespace has to be declared in any case where elements, attributes, types or groups are reused in the extension. It further has to be imported using the XML Schema rules: xs:import.
• The element requirement re-uses the railML type tGenericName. The attribute version re-uses the railML type tVersionNumber.
• The content of element contract re-uses the railML base type tElementWithIDAndNameWithoutAny thats provides some generic attributes and elements.
• This example has many in common with the previous one. See that comments, too.

The following XML instance document shows an example how to deploy these extensions within a railML file.

XML Instance with comments

<?xml version="1.0" encoding="UTF-8"?>
<railml xmlns="http://www.railml.org/schemas/2011" xmlns:my="http://www.my-company.com/my-department/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.railml.org/schemas/2011 ../schema/railML.xsd http://www.my-company.com/my-department/ genericExtensionWithRailML.xsd" version="2.1">
  <timetable id="tt1">
    <my:mySpecifics version="1.0">
      <my:contract id="ctr1" code="1234-56/789">
        <my:requirement>123.456.78.9</my:requirement>
      </my:contract>
      <my:personResponsible>Max Mustermann</my:personResponsible>
    </my:mySpecifics>
    <categories>
      <category id="c1" code="IC" name="InterCity" description="Fast large city connection" trainUsage="passenger">
        <my:mySpecifics version="1.0">
	  <my:personResponsible>Marie Mustermann</my:personResponsible>
	</my:mySpecifics>
      </category>
      <category id="c2" code="RE" name="RegionalExpress" description="Fast small city connection" trainUsage="passenger"/>
    </categories>
  </timetable>
</railml>

• The extension element mySpecifics in the element timetable holds the changed contract element. It is based on a railML type and therefore provides the "railML attribute" code for usage instead of the self-defined number element. It further forces the id attribute to be defined.
• This example has many in common with the previous one. See that comments, too.