Dev:UsingAny: Difference between revisions
Jump to navigation
Jump to search
| [unchecked revision] | [unchecked revision] |
m (Newlines removed) |
m (Line numbering added with references in the text flow) |
||
| Line 18: | Line 18: | ||
==== XML Schema with comments ==== | ==== XML Schema with comments ==== | ||
<syntaxhighlight lang="xml"> | <syntaxhighlight line lang="xml"> | ||
<?xml version="1.0" encoding="UTF-8"?> | <?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"> | <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"> | ||
| Line 63: | Line 63: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
* This example does not re-use railML elements, attributes, attribute groups, types, groups. It is fully based on XML Schema types. | * This example does not re-use railML elements, attributes, attribute groups, types, groups. It is fully based on XML Schema types. (lines 17, 23, 29, 34) | ||
* The {{Attr|version}} attribute in the root element marks the version of the extension schema and should be not confused with the railML version. | * The {{Attr|version}} attribute in the root element marks the version of the extension schema and should be not confused with the railML version. (line 2) | ||
* It is recommended to use the XML comments for non-content related documentation, e.g. contact information: [http://www.w3.org/TR/REC-xml/#sec-comments <!-- ... -->] | * It is recommended to use the XML comments for non-content related documentation, e.g. contact information: [http://www.w3.org/TR/REC-xml/#sec-comments <!-- ... -->] (line 4) | ||
* It is recommended to use the XML Schema possibilities for documentation inside the extension schema: [http://www.w3.org/TR/xmlschema-1/#cAnnotations xs:annotation and xs:documentation] | * It is recommended to use the XML Schema possibilities for documentation inside the extension schema: [http://www.w3.org/TR/xmlschema-1/#cAnnotations xs:annotation and xs:documentation] (lines 7-9, 13-15, 18-20, 30-32, 35-37) | ||
* The elements '''mySpecifics''' and '''contract''' show how to define sub-trees. The elements '''personResponsible''', '''number''' and '''requirement''' however define single elements without children. | * The elements '''mySpecifics''' and '''contract''' show how to define sub-trees: [http://www.w3.org/TR/xmlschema-1/#Complex_Type_Definitions xs:complexType] (lines 10-24, 27-40) | ||
* The element '''contract''' may occur once or not at all at the certain position. The element '''personResponsible''' must occur | * The elements '''personResponsible''', '''number''' and '''requirement''' however define single elements without children. (lines 17, 29, 34) | ||
* The attribute {{Attr|version}} has to be defined inside the element '''mySpecifics'''. | * The element '''contract''' may occur once or not at all at the certain position. (line 12) | ||
* The element '''personResponsible''' must occur ones. (line 17) | |||
* 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. (lines 29, 34) | |||
* The attribute {{Attr|version}} has to be defined inside the element '''mySpecifics'''. (line 23) | |||
The following XML instance document shows an example how to deploy these extensions within a railML file. | The following XML instance document shows an example how to deploy these extensions within a railML file. | ||
| Line 75: | Line 78: | ||
==== XML Instance with comments ==== | ==== XML Instance with comments ==== | ||
<syntaxhighlight lang="xml"> | <syntaxhighlight line lang="xml"> | ||
<?xml version="1.0" encoding="UTF-8"?> | <?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"> | <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"> | ||
| Line 98: | Line 101: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
* 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 element '''timetable''' shows the full usage of the extension elements and attributes. (lines 4-10) | ||
* The extensions are clearly distinguishable from the railML core by defining the appropriate | * The first '''category''' element shows the usage of all required extension elements and attributes. (lines 13-15) | ||
* The second '''category''' element shows the absence of the extension elements and attributes. (line 17) | |||
* The extensions are clearly distinguishable from the railML core by defining the appropriate namespace: '''xmlns:my="<nowiki>http://www.my-company.com/my-department/</nowiki>"''' (line 1), using the prefix '''my''' (lines 4-10, 13-15) | |||
Generally, the prefix is a short abbreviation for the domain-specific extension up to three letters. | |||
Extensions in railML base elements (with {{Attr|id}}, {{Attr|code}}...) have to be inserted before the other railML child elements. In all other cases do the extensions apply after the railML child elements. | |||
=== Example for an extension XML Schema defining own elements with some railML re-use === | === Example for an extension XML Schema defining own elements with some railML re-use === | ||
| Line 105: | Line 114: | ||
==== XML Schema with comments ==== | ==== XML Schema with comments ==== | ||
<syntaxhighlight lang="XML"> | <syntaxhighlight line lang="XML"> | ||
<?xml version="1.0" encoding="UTF-8"?> | <?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"> | <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"> | ||
| Line 160: | Line 169: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
* The railML namespace has to be declared in any case where elements, attributes, types or groups are reused in the extension. | * The railML namespace has to be declared in any case where elements, attributes, types or groups are reused in the extension: '''xmlns:rail="<nowiki>http://www.railml.org/schemas/2011</nowiki>"''' (line 1) | ||
* The element '''requirement''' re-uses the railML type '''tGenericName'''. The attribute {{Attr|version}} re-uses the railML type '''tVersionNumber'''. | * The railML namespace has further to be imported using the XML Schema rules: [http://www.w3.org/TR/xmlschema-1/#composition-schemaImport xs:import]. (lines 6-12) | ||
* The content of element '''contract''' re-uses the railML base type '''tElementWithIDAndNameWithoutAny''' thats provides some generic attributes and elements. | * The element '''requirement''' re-uses the railML type '''tGenericName'''. (line 42) | ||
* The attribute {{Attr|version}} re-uses the railML type '''tVersionNumber'''. (line 31) | |||
* The content of element '''contract''' re-uses the railML base type '''tElementWithIDAndNameWithoutAny''' thats provides some generic attributes and elements. (lines 37-48) | |||
* This example has many in common with the previous one. See [[#XML_Schema_with_comments | that comments]], too. | * This example has many in common with the previous one. See [[#XML_Schema_with_comments | that comments]], too. | ||
| Line 169: | Line 180: | ||
==== XML Instance with comments ==== | ==== XML Instance with comments ==== | ||
<syntaxhighlight lang="XML"> | <syntaxhighlight line lang="XML"> | ||
<?xml version="1.0" encoding="UTF-8"?> | <?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"> | <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"> | ||
| Line 191: | Line 202: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
* 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" {{Attr|code}} for usage instead of the self-defined '''number''' element. It further forces the {{Attr|id}} attribute to be defined. | * 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" {{Attr|code}} for usage instead of the self-defined '''number''' element. It further forces the {{Attr|id}} attribute to be defined. (lines 4-9) | ||
* This example has many in common with the previous one. See [[#XML_Instance_with_comments|that comments]], too. | * This example has many in common with the previous one. See [[#XML_Instance_with_comments|that comments]], too. | ||
Revision as of 10:35, 13 September 2012
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. (lines 17, 23, 29, 34)
- The version attribute in the root element marks the version of the extension schema and should be not confused with the railML version. (line 2)
- It is recommended to use the XML comments for non-content related documentation, e.g. contact information: <!-- ... --> (line 4)
- It is recommended to use the XML Schema possibilities for documentation inside the extension schema: xs:annotation and xs:documentation (lines 7-9, 13-15, 18-20, 30-32, 35-37)
- The elements mySpecifics and contract show how to define sub-trees: xs:complexType (lines 10-24, 27-40)
- The elements personResponsible, number and requirement however define single elements without children. (lines 17, 29, 34)
- The element contract may occur once or not at all at the certain position. (line 12)
- The element personResponsible must occur ones. (line 17)
- 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. (lines 29, 34)
- The attribute version has to be defined inside the element mySpecifics. (line 23)
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. (lines 4-10)
- The first category element shows the usage of all required extension elements and attributes. (lines 13-15)
- The second category element shows the absence of the extension elements and attributes. (line 17)
- The extensions are clearly distinguishable from the railML core by defining the appropriate namespace: xmlns:my="http://www.my-company.com/my-department/" (line 1), using the prefix my (lines 4-10, 13-15)
Generally, the prefix is a short abbreviation for the domain-specific extension up to three letters.
Extensions in railML base elements (with id, code...) have to be inserted before the other railML child elements. In all other cases do the extensions apply after the railML child elements.
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: xmlns:rail="http://www.railml.org/schemas/2011" (line 1)
- The railML namespace has further to be imported using the XML Schema rules: xs:import. (lines 6-12)
- The element requirement re-uses the railML type tGenericName. (line 42)
- The attribute version re-uses the railML type tVersionNumber. (line 31)
- The content of element contract re-uses the railML base type tElementWithIDAndNameWithoutAny thats provides some generic attributes and elements. (lines 37-48)
- 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. (lines 4-9)
- This example has many in common with the previous one. See that comments, too.