|
|
| (8 intermediate revisions by 3 users not shown) |
| Line 1: |
Line 1: |
| == XML Elements ==
| | {{mirror}} |
| | |
| === 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 [[:Category:RailML_Documentation | element documentation site]] in this railML wiki.
| |
| | |
| <syntaxhighlight line lang="xml">
| |
| <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>
| |
| </syntaxhighlight>
| |
| | |
| example:
| |
| | |
| <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="http://www.wiki.railml.org/index.php?title=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 [[:Category:RailML_Documentation | 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.
| |
| | |
| <syntaxhighlight line lang="xml">
| |
| <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>
| |
| </syntaxhighlight>
| |
| | |
| example:
| |
| | |
| <syntaxhighlight line lang="xml">
| |
| <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>
| |
| </syntaxhighlight>
| |
| | |
| == 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]]
| |