-
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) 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 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 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 not currently true, 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...they 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, though, is optional.
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 element attributes. It is important that meaning aligns in these assignments.
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. * origins: 16th century Medieval Latin, validatus
This is the goal of validation, to determine the degree to which the gbXML is an accurate representation of a building, or set of buildings, from the perspective of the end user. And right there, we face a conundrum of sorts. The perspective of the end user varies from person to person, depending upon the type of simulation they wish to perform, and the constraints and inputs of the simulation tool which is being used. Since gbXML is a jack of all trades and should be ubiquitous in the transfer of information for any model, this can make validation tricky business.
To validate any XML file, gbXML.org decided to approach validation at the highest level of abstraction as three separate stages.
- Is the XML valid XML?
- Is the XML valid gbXML?
- How accurate is the data contained in the gbXML files?
The first two checks are really quite general, and a great deal of programming resource has not been required to make it work. The concept behind these two stages is to ensure that the language in the XML is properly formatted. That is, spelling is correct, structure is correct, all tags are well-formed. gbXML.org has relied upon standard Microsoft libraries to check the gbXML against the latest XSD, and if errors are found, the libraries automatically generate errors that are thrown and then reported to the user. Passage of these two tests essentially assured that the file is essentially gbXML and is capable of being read by any standard gbXML parser.
Accuracy, part 3, is where the validator and its code base first begin to step beyond the dependencies of the XSD and standard tools to begin intelligently analyzing the gbXML, on behalf of the user, to determine whether it is sufficiently robust for simulation.
Up until the time of this writing (March 13, 2014) there have really only been one group of people who wish to consume and process gbXML, mechanical engineers and energy modelers, though the origins of gbXML is the serializers embedded in architectural CAD and BIM programs. Each of these groups have specific goals, due in large part to the tools they have chosen to use for their simulations. In some cases, engineers place a self-imposed need for accuracy which is not based in any statistical significance. There has also been the already-discussed difference between a simple wall definition, and a complex one, and the different data needs that result from the two.
gbXML is inherently flexible,