Document Structure

Table of Contents

• Document Structure
  • Top Level Nodes
    • XMLTransactionHeaderInformation
    • SoftwareInfo
    • Contractor
    • Customer
    • Building
    • Project
    • Utility
    • Consumption
  • Extension Elements

Top Level Nodes

Each of the top level nodes described below with the exception of XMLTransactionHeaderInformation and SoftwareInfo represent a high-level block of information about a building or project that can be related to other nodes to describe useful information about a building, the people and businesses who interact with the building, and actions taken on the building. The relationships between the top level nodes are defined with XML Element References that can be used, for example, to associate a Building with a Project, Consumption with a Building, or a Contractor with a Project.

The schema itself does not enforce the particular constraints for Standard HPXML Datasets, but rather provides a container for all the relevant components and a referencing scheme to relate them.

XMLTransactionHeaderInformation

The XMLTransactionHeaderInformation element meta data about the HPXML file.

<XMLTransactionHeaderInformation>
  <XMLType>audit</XMLType>
  <XMLGeneratedBy>Housesoft 1.0</XMLGeneratedBy>
  <CreatedDateAndTime>2014-09-02T17:32:12Z</CreatedDateAndTime>
  <Transaction>create</Transaction>
</XMLTransactionHeaderInformation>

XMLType is generally unused and may be deprecated in the future.

XMLGeneratedBy is often used to transmit the name of the software that generated the HPXML file. It may also be deprecated in the future due to its redundancy with SoftwareInfo.

CreatedDateAndTime is the date and time the file was generated in the ISO 8601 format.

Transaction describes whether this is a new document or an update to a previous one.

SoftwareInfo

SoftwareInfo provides a place to transmit information about the software used to generate the HPXML.

<SoftwareInfo>
  <SoftwareProgramUsed>WOPR</SoftwareProgramUsed>
  <SoftwareProgramVersion>1.0</SoftwareProgramVersion>
</SoftwareInfo>

Contractor

The Contractor node describes a business that the customer works with to do an audit or upgrade to their building.

Customer

A customer is the owner, tenant, or some other person who has a vested interest in the house being described and worked on. This node is a place to describe that person, their contact information, and their relation to the building.

Building

The Building node describes the physical characteristics of a building at a point in time - past, present, or future.

Project

The Project node describes work that has been completed or is to be completed to a Building. The measures described can have references pointing to specific components on the building and what was changed between the pre- and post-upgrade states and associated costs.

Utility

The Utility node represents a utility company.

Consumption

The Consumption node stores and represents the energy and/or water use of a building. It can contain high resolution electric smart meter data, information on fuel oil, or more typically, monthly gas or electric bills.

Extension Elements

Because it is impossible to foresee every possible data point that will ever need to be collected and transmitted about a house or upgrade, most elements in HPXML contain an extension element containing an <xs:any> designation. That allows any element from any namespace to be inserted. This is to facilitate transfer of data elements not available in the standard.

<extension>
   <QuantityWoodChucked>as much wood as a wood chuck could chuck</QuantityWoodChucked>
</extension>

Warning

Please exercise extreme caution and discretion when you consider implementing extension elements. Typically, the temptation to use them happens when a difference arises between the way your software and/or home performance program represents a certain data field and the way HPXML represents it. It is crucial in these cases to either map your data into HPXML or change the way you represent it internally to conform to the HPXML standard. If each software vendor and home performance program extends HPXML in non-standard ways, the value proposition of the standard is nullified.

If there is no possible way to map your data into existing HPXML data fields, please contact the HPXML working group before implementing an extension. The working group would prefer to extend the standard for the benefit of everyone and avoid the use of extensions wherever possible.

Usually, you will not be the only one with the need for a particular element that was overlooked in the standard. By participating in the working group and lobbying for the elements you need you can enhance the value of HPXML for all parties.