Repository navigation
Description
Describe the bug or data model issue
#474 reported that the schema viewer on the website shows no child elements under FanBased. The same schema pattern is used by several other elements, so they likely have the same problem.
The pattern:
<!-- global declaration with a named type -->
<xs:element name="FanBased" type="auc:FanBasedType"/>
<!-- used elsewhere by reference -->
<xs:element ref="auc:FanBased" minOccurs="0"/>The viewer appears not to follow the reference through to the element's named type (ref → global element → type), so it shows no children. Elements that are declared locally with a named type (e.g. <xs:element name="HVACSystem" type="auc:HVACSystemType"/>) render correctly.
Affected elements
A scan of BuildingSync.xsd found 12 global elements declared with a named type. These are the ones where content is likely missing in the viewer:
Named type has child elements (children likely not shown):
| Global element | Type | # descendant elements | Referenced from |
|---|---|---|---|
FanBased (#474) |
FanBasedType |
21 | DeliveryType/ZoneEquipment/FanBased, DeliveryType/CentralAirDistribution/FanBased |
TimeSeries |
TimeSeriesType |
18 | TimeSeriesData, DerivedModel sections (6 references) |
CalculationMethod |
CalculationMethodType |
16 | Benchmark, BenchmarkType children, savings / Scenario (6 references) |
PortfolioManager |
PortfolioManagerType |
3 | Building, Benchmark/BenchmarkType |
Named simpleContent type (bounds and/or the Source attribute may not be shown):
| Global element | Type |
|---|---|
HeatingStageCapacityFraction |
BoundedDecimalZeroToOneWithSourceAttribute |
MinimumPartLoadRatio |
BoundedDecimalZeroToOneWithSourceAttribute |
RatedCoolingSensibleHeatRatio |
BoundedDecimalZeroToOneWithSourceAttribute |
Not visibly affected (named type is empty): NoCooling, NoHeating, ElectricResistance, OtherCombination, Unknown.
Expected Behavior
The schema viewer shows the full content model of each element listed above, the same way it does for locally declared elements.
Actual Behavior
FanBased shows no children (see screenshots in #474). The other elements listed above are expected to behave the same way. Screenshots to be added.
Proposed solutions
- Fix the viewer (preferred): when an element is a
ref, resolve the referenced global element and, if it has atypeattribute, render that named complexType. This needs no schema change and fixes every case at once. - Change the schema: replace each
<xs:element ref="auc:X"/>with a local declaration<xs:element name="X" type="auc:XType" minOccurs="..." maxOccurs="..."/>and remove the global element. Instance documents keep the same structure, so existing files stay valid. However, documentation, annotations, and any tooling (e.g.src/data_dictionary.rb) that relies on the global declarations would need review.
Additional Context
- Related: FanBased child elements omitted #474
- Found by parsing
BuildingSync.xsdfor globalxs:elementdeclarations that have atype="auc:..."attribute and are used throughref=.
Activity
JieXiong9119 commentedon Oct 27, 2026
I checked how widespread this is and found the cause.
Scope (v2.7.0, confirmed on the live viewer). Your earlier comment is right: any element that is defined globally as
<xs:element name="X" type="auc:XType"/>and used throughref="auc:X"loses its children in the viewer. In the current schema, four such elements have children to lose:FanBased: 21 children, appears in 2 placesTimeSeries: 18 children, 6 placesCalculationMethod: 16 children, 7 placesPortfolioManager: 3 children, 2 placesAll 17 of those places in the viewer tree show 0 children.
ElectricResistance,NoCooling,NoHeating,OtherCombinationandUnknownuse the same pattern, but their types are empty, so nothing is missing. Refs to enumeration-typed elements (PrimaryFuel,OccupancyClassification,EndUse, ...) display their values correctly.Cause. This is a bug in the website's schema parser, not in the schema. In
bsyncviewer/lib/schema_parser.py,_walk_named_elementonly followstype="auc:..."when the type is an enumeration (simple) type; it skips named complex types. Elements declared locally withname+typego through a different code path that handles complex types, which is why they display correctly.Decision. We'll fix this in the viewer rather than change the schema. Changing the schema would mean duplicating element names, which breaks the unique-name rule, and it would only fix future releases. Tracking in BuildingSync/BuildingSync-website#. Once that fix is deployed and the published versions are re-parsed, all versions will display correctly, and this issue can be closed.
The viewer also doesn't show attributes such as
Sourceon value elements likeHeatingStageCapacityFraction. That's unrelated toref, and it's listed as a possible follow-up in the website issue.