Skip to content

Schema viewer omits children of globally declared elements that use a named complexType (extends #474) #559

Closed
BuildingSync/BuildingSync-website
#230

Description

@JieXiong9119

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

  1. Fix the viewer (preferred): when an element is a ref, resolve the referenced global element and, if it has a type attribute, render that named complexType. This needs no schema change and fixes every case at once.
  2. 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

Activity

  1. self-assigned this
    on Oct 21, 2026
  2. JieXiong9119 commented on Oct 27, 2026

    @JieXiong9119
    ContributorAuthor

    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 through ref="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 places
    • TimeSeries: 18 children, 6 places
    • CalculationMethod: 16 children, 7 places
    • PortfolioManager: 3 children, 2 places

    All 17 of those places in the viewer tree show 0 children.

    ElectricResistance, NoCooling, NoHeating, OtherCombination and Unknown use 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_element only follows type="auc:..." when the type is an enumeration (simple) type; it skips named complex types. Elements declared locally with name + type go 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 Source on value elements like HeatingStageCapacityFraction. That's unrelated to ref, and it's listed as a possible follow-up in the website issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions