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="" xmlns=""
 targetNamespace="" 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="" schemaVersion="2.3">


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.[Year]/[Month]


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


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.


A patch version number is incremented when a backwards compatible change (as described in Minor) is made to address a bug.