-
Notifications
You must be signed in to change notification settings - Fork 3
Home
The core idea behind gbXML, is it provides the ability to describe multiple buildings that are somehow related (campus, property set) and located in the same climate region. Each building in the set can further be represented in a more detailed way (its geometry, zoning, airside systems, and waterside systems) along with other criteria that influence the overall energy consumption of the building (schedules of use, thermostat temperature setpoints, internal loads, materials and constructions).
Like any XML file, gbXML is nested. It is quite nested relative to some more simple XML formats. The format is governed by gbXML.org, which maintains an XML Schema Definition (XSD) that describes all of the current structure, naming convention, and requirements of a valid gbXML file. The current version of the XSD is 5.11. If you would like to see changes to XML, please email me at [email protected] and if approved by the board, the changes will be added to the XSD and released to the public after approval.
If you would like to learn more about gbXML and its work in making data analysis easier for energy modeling, visit here.
If you were to open a sample gbXML file today and read the file with your eyes, the basic gbXML structure is a series of containers:
- gbxml
- Campus
- Building(s)
- Space(s)
- with deeper nests...
- Space(s)
- Surface(s)
- Opening(s)
- Construction(s)
- Layer(s)
- Material(s)
- Meter(s)
- Zone(s)
- Schedule(s)
- Result(s)
- DocumentHistory
- Building(s)
- Campus
Each of these levels in the tree are different descriptions of a composition of buildings. You may have some familiarity with these sorts of items to describe a building or set of buildings.
This tree structure is not intended to be a definitive list of all the elements in a gbXML document, just to give you a sense of the level of nesting and the flavor of information. We only note the deeper nests inside spaces and surfaces just to give you an overview of the nature and intensity of nesting. All of these elements in the document are in reality further nested, the space and surface elements are the most nested of all elements. Also, how it is composed and organized. Where we put (s) at the end of the category, this implies that an array of these elements can exists.
Take note of the fact that surfaces, constructions, schedules, etc are not declared inside the building description. They are standalone. This basic structure of gbXML can confuse people, because many items that may conceptually belong inside an individual building exist at the very end of the document. These items can exist standalone in the document, connected to the building description by a shared identification attribute. This way, it is possible to re-use elements like this over and over again on different projects, or to reuse the same elements in different buildings. It is one way that gbXML tries to stay flexible for the people who use it the most and can appreciate that convenience. But it does seem counter-intuitive from a first glance at the document structure.
All of this information is also contained in the latest XSD file. But for people who would rather take a shortcut and read the minimum requirements in plain English, here is an overview of the gbXML minimum requirements.
As of version 5.11 (the current version), the standard is rather open with few required elements. The required features are heavily-weighted toward requiring information largely related to the building shape and location.
Here in plain language is the elements and attributes that must be defined at a bare minimum in every gbXML file. These elements and attributes are declared as required in the XSD (all other elements in a gbXML above and beyond these items below are optional):
- gbxml
- (attribute) lengthUnit (1 max)
- (attribute) temperatureUnit (1 max)
- (attribute) volumeUnit (1 max)
- (attribute) useSIUnitsForResults (1 max)
- (attribute) version (1 max)
- (child Element) Campus (1 max)
- (attribute) id (1 max)
- (child Element) Location (1 max)
- child Element) ZipCode (1 max)
- (child Element) Building (array with no maximum bound)
- (child Element) Area (1 max)
- (child Element) Space (array with no maximum bound
- (attribute) id (1 max)
- (child Element) SpaceBoundary (array with a minimum count of 4 with no maximum bound)
- (attribute) surfaceIdRef ** (1 max)
- (child Element) Planar Geometry (1 max)
- (child Element) PolyLoop (1 max)
- (child Element) CartesianPoint (array with 3 min and no max bound)
- (child Element) Coordinate (array with min 2 and max 3)
- (child Element) CartesianPoint (array with 3 min and no max bound)
- (child Element) PolyLoop (1 max)
- (Element) Area (1 max)
- (Element) Volume (1 max)
- (Element) PeopleNumber (1 max)
- (Element) PeopleHeatGain (3 required)
- (Element) LightPowerPerArea (1 max)
- (Element) EquipPowerPerArea (1 max)
- (Element) AirChangesPerHour (1 max)
- (Element) InfiltrationFlow (1 max)
- (attribute) lightScheduleIdRef (1 max)
- (attribute) equipmentScheduleIdRef (1 max)
- (attribute) peopleScheduleIdRef (1 max)
- (attribute) id (1 max, must be unique)
- (attribute) buildingType (1 max)
- (child Element) Surface (an array with no maximum bound)
- (attribute) id (1 max)
- (attribute) surfaceType (1 max)
- (attribute) constructionId (1 max)
- (child Element) AdjacentSpaceId (an array that requires 1 minimum, 2 maximum elements)
- (child Element) RectangularGeometry (1 max)
- (child Element) Azimuth (1 max)
- (child Element) CartesianPoint (1 max) complete
- (child Element) Coordinate (array with min 2 and max 3)
- (child Element) Tilt (1 max)
- (child Element) Height (1 max)
- (child Element) Width (1 max)
- (element) PlanarGeometry) (1 max) complete
- (child Element) Construction)(array with no maximum bound)
- (child Element) U-Value (1 max)
We have prepared a very simple gbXML description that meets these minimum requirements. You can see this example gbXML file in this github project, in the root directory. If you have a local copy of the project you can review it in more detail. Email me if you would like to have a copy without making a local copy of the project. You may also want to take a look at the XSD to read more about the datatypes that are accepted for each of these different elements.
Certain readers may recognize that the schema appears incomplete. Several items are currently under lobby as candidates for the next schema upgrade.
- energy modelers may notice that there is not a complete definition of infiltration (there is not a schedule requirement) and there is no option to enter in information related to the crack-flow method of infiltration.
- No temperature setpoints are defined or required. This information is defined at the Zone level with a zone ID reference defined at the Space Element. Some would like to require that at least one zone be defined with default setpoints.
- There are no latitude-longitude requirements or any address requirements that can be used for a geocode lookup.
- There is no specific ASHRAE 62.1 data entries that can be used, nor are there specific ASHRAE 62.1 space type enumerations
- The minimum requirements for the Construction element assumes that the wall is defined simply. It does not have an alternative definition for a more complex wall construction that has layers (which is more common for energy analysis where dynamic behavior must be captured).
A more thorough review of the minimum requirements may leave a person asking, why doesn't the XSD have minimum requirements for windows? And why is it possible to have a Cartesian point with only two coordinates? This is where the use of an XSD for a schema as complex as gbXML begins to fall apart, and if validation of the schema is to be robust, then a smarter form of validation must emerge to manage this complexity. We will address this in more detail in the Validator Description section of the wiki.
This serves as a summary of need-to-know features of any gbXML file, which may not be immediately obvious from a glance at the required fields section above and the XSD. The first is the treatment of interior surfaces. A surface is declared interior or exterior by its required surfaceType enumeration, which you can see in the required elements structure above. But there are no neighboring relationships identified. It is not clear what spaces are separated by this space.
In order to know this, there is an optional AdjacentSpaceId element array (currently there is lobby to make these fields required in the standard). There can be a minimum of 1 or a maximum of 2 AdjacentSpaceId elements if they are used. As a general rule, one AdjacentId element will always correspond to an exposed surface (this is a way to, in theory, check to see if "ExposedToSun" is true for a surface that is being converted to EnergyPlus). Two AdjacentSpaceId elements is a signal that the surface is an interior surface. The surfaceType enumerations should prove to match this standard pattern, e.g. - if a surface is declared as surfaceType=InteriorWall, it should have two AdjacentSpaceId elements, if the user wants to have this information. One of the AdjacentSpaceId elements will hold the name of one Space id the wall is adjacent to, the second AdjacentSpaceId contains the name of the other Space id. Logically you can figure out if the Surface is exterior, why there is only one AdjacentSpaceId and which Space id is assigned to it.
The one caveat where this rule about AdjacentSpaceId elements, is when surfaceType=SlabOnGrade. For this surface definition there are two AdjacentSpaceId elements, and each is filled with the same Space id value. This is a strange event which appears in gbXML definitions which should be improved in future standards as it doesn't make much logical sense.
A final thing to note about Interior Surfaces...interior surfaces are only represented once in a gbXML file. Whereas tools like EnergyPlus have the same wall entered twice, the use of the AdjacentSpaceId elements maintains the relationship between interior surfaces and walls quite nicely.
A second quirk of the standard is duplication of the optional SpaceBoundary element inside the Space Element. When this SpaceBoundary element is used it essentially is a duplicate, but abbreviated definition of a Surface Element. SpaceBoundary also has an optional attribute named surfaceRefId which should have the same value as the Surface id attribute. The surfaceRefId attribute of the SpaceBoundary, though, is optional. It is being considered to make this a requirement in future versions of the standard.
Under Concepts of gbXML Tree Structure above, we mentioned that gbXML sometimes connects data in one part of the schema to another through the use of an element attributes. It is important that meaning aligns in these assignments.
If a user would like to model surface thicknesses, gbXML has an optional geometry definition called ShellGeometry which is a child element of Space. This element holds an array of PolyLoop elements. The Coordinate elements of each PolyLoop define the interior surface of the Space. If the optional Space child element SpaceBoundary is activated and included along with ShellGeometry for each Space element, it should be possible with mathematics to deduce the wall thickness based on the coordinate offset between the ShellGeometry and its corresponding SpaceBoundary counterpart.
This exercise is made more difficult by the fact that each SpaceBoundary element for interior partitions, like Surface elements, are only represented once. This can prove to be a little bit of a challenge but not nearly as difficult as some. This is maybe fitting in the section on gbXML quirks.
If you are consuming all of this information, then you could imagine it can be hard to know what is "right" or "good" gbXML. It comes in so many flavors. See the validator wiki for more information.