-
Notifications
You must be signed in to change notification settings - Fork 0
What is gbXML
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) 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 download this example gbXML file here, so you can review it in more detail. 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 over, and if validation of the schema is to be robust, then a smarter form of validation must emerge to manage this complexity.
- validation (n.) - In computer science, the process of determining the degree to which a model or* *simulation is an accurate representation of the real world from the perspective of the intended uses of( *the model or simulation. * originsL 16th century Medieval Latin, validatus