Designing a Schema for Extensibility
The HydraExpress XML binding code generator creates a parser specifically designed to efficiently process XML documents that conform to the provided schema. The generated classes enforce the structure specified in the schema. If an XML document does not conform to the schema, the generated classes throw an exception while parsing the document.
However, this presents a problem for a schema that is intended to evolve over time. If a newer version of the schema simply adds elements, programs that use classes generated for an older version of the schema will refuse to parse the document.
One way to design a schema for extensibility is to use an optional, recurring any element. In this strategy, subsequent versions of a schema do not remove elements. At points where the schema may add elements, the schema defines an optional, recurring any element. This strategy works well with the XML bindings that HydraExpress creates.
The sample below shows a schema designed to allow future modification of the type extensibleType:
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:complexType name="extensibleType">
<xsd:sequence>
<xsd:element name="aString" type="xsd:string"/>
<xsd:element name="anInt" type="xsd:int" minOccurs="0"/>
<!-- recurring any element for extensibility -->
<xsd:any minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
Future versions of the schema may add elements to the sequence after the element anInt, but before the any. HydraExpress creates a std::vector of strings to represent the any element. For clients that use this version of the schema, any elements after anInt are preserved as strings in the vector.
The class generated from this version of the schema interprets additional elements as part of the any element. Further, a client built using an extensible schema can detect when the document received uses a newer schema. If the vector contains elements, then the document contains added information.
The sample below shows an updated version of the schema:
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:complexType name="extensibleType">
<xsd:sequence>
<xsd:element name="aString" type="xsd:string"/>
<xsd:element name="anInt" type="xsd:int" minOccurs="0"/>
<!-- added element in updated schema -->
<xsd:element name=”aDouble” type=”xsd:double”/>
<!-- recurring any element for extensibility -->
<xsd:any minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
This version adds the element aDouble to the schema. Classes generated from this version of the schema contain a member for the new element. Classes generated from the previous version of the schema interpret the new element as part of the any vector.
Notice that, although the element anInt is optional, this element cannot safely be removed from future versions of the schema. Should anInt be removed, classes generated for the updated version of the schema will fail to parse documents created by older clients when those documents contain the element anInt.