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