Versioning¶
The HPXML schemas follow the Semantic Versioning v2.0 specification. The version numbers follow a pattern of Major. Minor. Patch (i.e. 2.3.0).
The first element of HPXML.xsd
will indicate the version of the schema via
the version
attribute. Note that when referencing a version, the patch
number is assumed to be zero if it is omitted.
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://hpxmlonline.com/2014/6"
targetNamespace="http://hpxmlonline.com/2014/6" elementFormDefault="qualified" version="2.3">
Additionally, starting with version 2.0, the version of the schema used is
required in the schemaVersion
attribute on the root element of every
document.
<HPXML xmlns="http://hpxmlonline.com/2014/6" schemaVersion="2.3">
Major¶
The major version number is incremented when the schemas are changed in a manner which is incompatible with previous versions. Examples of changes which necessitate a major version change include:
- Renaming elements
- Removing elements
- Moving elements
- Removing enumerations
A different xml namespace is used for each major revision. Starting with version 2.0, the namespaces follow the pattern where the year and month are when the major version number was changed.
http://hpxmlonline.com/[Year]/[Month]
Minor¶
The minor version number is incremented when the schemas are changed in a manner that is backwards compatible with previous versions that share the same Major version. Backwards compatible in the context of HPXML means that given the schema changes, a document created in a previous version of the schema will also validate against the new schema. Example of changes which necessitate a minor version change include:
- Adding elements
- Adding enumerations
- Changing the annotation in the schema for an element
Warning
Based on the definition of backwards compatibility, adding enumerations is a non-breaking change. However, it can be breaking for receiving systems if they are not expecting the change. The working group will provide warning when new enumerations are added so that receivers have an opportunity to respond by updating support.