From a549c468b960cc21626c4cd3d25caf0e52dbe9e8 Mon Sep 17 00:00:00 2001 From: JieXiong9119 <69597597+JieXiong9119@users.noreply.github.com> Date: Wed, 28 Oct 2026 02:19:25 -0600 Subject: [PATCH 1/3] add proposal and implement --- BuildingSync.xsd | 35 +++++++++++++------ ...centType and Allow Negative Bias Errors.md | 28 +++++++++++++++ 2 files changed, 52 insertions(+), 11 deletions(-) create mode 100644 proposals/2026/Add PercentType and Allow Negative Bias Errors.md diff --git a/BuildingSync.xsd b/BuildingSync.xsd index 51b42ffc..b5902fb6 100644 --- a/BuildingSync.xsd +++ b/BuildingSync.xsd @@ -15626,6 +15626,25 @@ + + + A percentage of a whole, expressed on a 0 to 100 scale (not as a 0 to 1 fraction). (0-100) (%) + + + + + + + + + A percentage of a whole, expressed on a 0 to 100 scale, with an optional Source attribute. (0-100) (%) + + + + + + + @@ -15907,24 +15926,18 @@ - + The Coefficient of Variation of the Root Mean Square Error expressed as a percentage. - - - - - - - The Net Determination Bias Error expressed as a percentage. + The Net Determination Bias Error expressed as a percentage. May be negative. (-100-100) (%) - + @@ -15936,11 +15949,11 @@ - The Normalized Mean Bias Error expressed as a percentage. + The Normalized Mean Bias Error expressed as a percentage. May be negative. (-100-100) (%) - + diff --git a/proposals/2026/Add PercentType and Allow Negative Bias Errors.md b/proposals/2026/Add PercentType and Allow Negative Bias Errors.md new file mode 100644 index 00000000..a5a8430c --- /dev/null +++ b/proposals/2026/Add PercentType and Allow Negative Bias Errors.md @@ -0,0 +1,28 @@ +# Add PercentType and Allow Negative Bias Errors + +## Overview + +Addresses [#297](https://github.com/BuildingSync/schema/issues/297). Adds reusable named types for percentages on a 0-100 scale and fixes the lower bound of the `NDBE` and `NMBE` model fit metrics, which are signed quantities but are currently restricted to 0-100. + +## Justification + +- Many elements are documented as percentages (e.g. `PercentOccupiedByOwner`, `PercentPremisesServed`, `PercentOfWindowAreaShaded`) but are plain `xs:decimal`, and examples mix 0-1 fractions and 0-100 percents. A shared `PercentType` gives new and future elements a single, documented definition, analogous to the existing `BoundedDecimalZeroToOne`. +- `NDBE` (Net Determination Bias Error) and `NMBE` (Normalized Mean Bias Error) are signed by definition (ASHRAE Guideline 14); a model can over- or under-predict. The current `minInclusive value="0"` rejects valid negative results. + +## Implementation + +Non-breaking change (MINOR). + +- Add global `xs:simpleType` `PercentType`: `xs:decimal` restricted to `[0, 100]`. +- Add global `xs:complexType` `PercentWithSourceAttribute`: `simpleContent` extension of `auc:PercentType` with `auc:Source` attribute. +- `.../DerivedModelPerformance/CVRMSE`: replace the inline 0-100 restriction with `type="auc:PercentType"` (identical value space; patch-level). +- `.../DerivedModelPerformance/NDBE` and `.../DerivedModelPerformance/NMBE`: change `minInclusive` from `0` to `-100` (widening; non-breaking). Documentation notes the value may be negative. + +Out of scope (would be breaking, since it narrows existing `xs:decimal` elements): migrating existing percentage elements to `PercentType`. That requires first resolving fraction-vs-percent values in examples and producer data (e.g. Audit Template) and is deferred to a major version. + +No element names, paths, or enumerations change, so downstream repos (use-cases, BOSS, asset-extractor) are unaffected; bsyncpy gains two new types on regeneration. + +## References + +- [#297](https://github.com/BuildingSync/schema/issues/297) +- ASHRAE Guideline 14-2014, Measurement of Energy, Demand, and Water Savings From c51026602d73fb6478bc1128c501beee47c020cd Mon Sep 17 00:00:00 2001 From: JieXiong9119 <69597597+JieXiong9119@users.noreply.github.com> Date: Wed, 28 Oct 2026 10:04:54 -0600 Subject: [PATCH 2/3] update proposal for fields that should apply percenttype --- ...centType and Allow Negative Bias Errors.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/proposals/2026/Add PercentType and Allow Negative Bias Errors.md b/proposals/2026/Add PercentType and Allow Negative Bias Errors.md index a5a8430c..8b90e85c 100644 --- a/proposals/2026/Add PercentType and Allow Negative Bias Errors.md +++ b/proposals/2026/Add PercentType and Allow Negative Bias Errors.md @@ -7,6 +7,14 @@ Addresses [#297](https://github.com/BuildingSync/schema/issues/297). Adds reusab ## Justification - Many elements are documented as percentages (e.g. `PercentOccupiedByOwner`, `PercentPremisesServed`, `PercentOfWindowAreaShaded`) but are plain `xs:decimal`, and examples mix 0-1 fractions and 0-100 percents. A shared `PercentType` gives new and future elements a single, documented definition, analogous to the existing `BoundedDecimalZeroToOne`. +- `PercentWithSourceAttribute` is needed because most existing percentage elements already carry the optional `auc:Source` attribute (data provenance such as `Estimate`, `Auditor`, `Direct measurement`), for example: + + ```xml + 40 + ``` + + A plain `xs:simpleType` such as `PercentType` cannot have attributes, so moving these elements to `PercentType` would drop `Source` and invalidate such documents. `PercentWithSourceAttribute` has the same 0-100 value space plus the optional `Source` attribute. This mirrors the existing pair `BoundedDecimalZeroToOne` (used directly by elements without `Source`, e.g. `ConfidenceLevel`) and `BoundedDecimalZeroToOneWithSourceAttribute` (a `simpleContent` extension adding `auc:Source`, used by e.g. `OverallWindowToWallRatio`, `SupplyFractionOfDuctLeakage`, `MinimumDimmingLightFraction`, `WaterFixtureFractionHotWater`). + - `NDBE` (Net Determination Bias Error) and `NMBE` (Normalized Mean Bias Error) are signed by definition (ASHRAE Guideline 14); a model can over- or under-predict. The current `minInclusive value="0"` rejects valid negative results. ## Implementation @@ -20,6 +28,36 @@ Non-breaking change (MINOR). Out of scope (would be breaking, since it narrows existing `xs:decimal` elements): migrating existing percentage elements to `PercentType`. That requires first resolving fraction-vs-percent values in examples and producer data (e.g. Audit Template) and is deferred to a major version. +Candidate share-of-whole elements for a future (breaking) migration. Each is documented as a percentage of a bounded whole (area, floor area, length, time, consumption, savings), so values outside 0-100 are not meaningful. Example statistics are from all valid `examples/*.xml`; "Fractions" counts values strictly between 0 and 1. + +| Element | Current type | Target type | Uses in examples | Example range | Fractions | Fraction-to-percent fix needed? | +| ---------------------------------------------------- | ---------------- | ---------------------------- | ---------------- | ------------- | --------- | ----------------------------------------------- | +| `PartialOperationPercentage` | decimal + Source | `PercentWithSourceAttribute` | 714 | 0 to 1 | 484 | Yes: all values are fractions | +| `PercentPremisesServed` | decimal + Source | `PercentWithSourceAttribute` | 38 | 0.05 to 1 | 6 | Yes | +| `PercentSkylightArea` | decimal + Source | `PercentWithSourceAttribute` | 50 | 0 to 0.0375 | 2 | Yes | +| `PercentResource` | decimal | `PercentType` | 13 | 1 | 0 | Ambiguous: 1 probably means 100% | +| `PercentEndUse` | decimal | `PercentType` | 13 | 1 | 0 | Ambiguous: 1 probably means 100% | +| `PipeLocation` | decimal + Source | `PercentWithSourceAttribute` | 4 | 1 | 0 | Ambiguous | +| `PercentOccupiedByOwner` | decimal + Source | `PercentWithSourceAttribute` | 6 | 20 to 78 | 0 | No | +| `PercentLeasedByOwner` | decimal + Source | `PercentWithSourceAttribute` | 6 | 15 to 80 | 0 | No | +| `SpatialUnitOccupiedPercentage` | decimal | `PercentType` | 1 | 90 | 0 | No | +| `PercentOfWindowAreaShaded` | decimal + Source | `PercentWithSourceAttribute` | 200 | 0 | 0 | No | +| `FloorAreaPercentage` | float [0, 100] | `PercentType` | 88 | 0 to 100 | 0 | No; already bounded, change is float to decimal | +| `PercentageOfCommonSpace` | decimal + Source | `PercentWithSourceAttribute` | 0 | - | - | Not used in examples | +| `BoilerPercentCondensateReturn` | decimal + Source | `PercentWithSourceAttribute` | 0 | - | - | Not used in examples | +| `DuctPressureTestLeakagePercentage` | decimal + Source | `PercentWithSourceAttribute` | 0 | - | - | Not used in examples | +| `SupplyDuctPercentConditionedSpace` | decimal + Source | `PercentWithSourceAttribute` | 0 | - | - | Not used in examples | +| `ReturnDuctPercentConditionedSpace` | decimal + Source | `PercentWithSourceAttribute` | 0 | - | - | Not used in examples | +| `DutyCycle` | decimal + Source | `PercentWithSourceAttribute` | 0 | - | - | Not used in examples | +| `PumpDutyCycle` | decimal + Source | `PercentWithSourceAttribute` | 0 | - | - | Not used in examples | +| `MinimumOutsideAirPercentage` | decimal + Source | `PercentWithSourceAttribute` | 0 | - | - | Not used in examples | +| `HumidityControlMinimum` | decimal + Source | `PercentWithSourceAttribute` | 0 | - | - | Not used in examples | +| `HumidityControlMaximum` | decimal + Source | `PercentWithSourceAttribute` | 0 | - | - | Not used in examples | +| `PercentGuaranteedSavings` | decimal + Source | `PercentWithSourceAttribute` | 0 | - | - | Not used in examples | +| `FederalSustainabilityChecklistCompletionPercentage` | decimal + Source | `PercentWithSourceAttribute` | 0 | - | - | Not used in examples | + +Rates and ratios that can be negative or exceed 100 (`EscalationRate` and the price escalation rates, `InflationRate`, `DiscountRate`, `DiscountFactor`, `InternalRateOfReturn`, `ProjectMarkup`, `DemandRatchetPercentage`) are excluded. + No element names, paths, or enumerations change, so downstream repos (use-cases, BOSS, asset-extractor) are unaffected; bsyncpy gains two new types on regeneration. ## References From dedb1594c96dca2b4ba37e4e92e32a8507b64bb3 Mon Sep 17 00:00:00 2001 From: JieXiong9119 <69597597+JieXiong9119@users.noreply.github.com> Date: Fri, 6 Nov 2026 14:07:48 -0700 Subject: [PATCH 3/3] revise NDBE and NMBE bounds --- BuildingSync.xsd | 20 ++++--------------- ...centType and Allow Negative Bias Errors.md | 6 +++--- 2 files changed, 7 insertions(+), 19 deletions(-) diff --git a/BuildingSync.xsd b/BuildingSync.xsd index e867c0a9..f24dc5de 100644 --- a/BuildingSync.xsd +++ b/BuildingSync.xsd @@ -15941,32 +15941,20 @@ The Coefficient of Variation of the Root Mean Square Error expressed as a percentage. - + - The Net Determination Bias Error expressed as a percentage. May be negative. (-100-100) (%) + The Net Determination Bias Error expressed as a percentage. May be negative, and its magnitude may exceed 100. (%) - - - - - - The Mean Bias Error. - + - The Normalized Mean Bias Error expressed as a percentage. May be negative. (-100-100) (%) + The Normalized Mean Bias Error expressed as a percentage. May be negative, and its magnitude may exceed 100. (%) - - - - - - diff --git a/proposals/2026/Add PercentType and Allow Negative Bias Errors.md b/proposals/2026/Add PercentType and Allow Negative Bias Errors.md index 8b90e85c..a7b1ba66 100644 --- a/proposals/2026/Add PercentType and Allow Negative Bias Errors.md +++ b/proposals/2026/Add PercentType and Allow Negative Bias Errors.md @@ -2,7 +2,7 @@ ## Overview -Addresses [#297](https://github.com/BuildingSync/schema/issues/297). Adds reusable named types for percentages on a 0-100 scale and fixes the lower bound of the `NDBE` and `NMBE` model fit metrics, which are signed quantities but are currently restricted to 0-100. +Addresses [#297](https://github.com/BuildingSync/schema/issues/297). Adds reusable named types for percentages on a 0-100 scale and removes the 0-100 bounds on the `NDBE` and `NMBE` model fit metrics, which are signed quantities whose magnitude can exceed 100%. ## Justification @@ -15,7 +15,7 @@ Addresses [#297](https://github.com/BuildingSync/schema/issues/297). Adds reusab A plain `xs:simpleType` such as `PercentType` cannot have attributes, so moving these elements to `PercentType` would drop `Source` and invalidate such documents. `PercentWithSourceAttribute` has the same 0-100 value space plus the optional `Source` attribute. This mirrors the existing pair `BoundedDecimalZeroToOne` (used directly by elements without `Source`, e.g. `ConfidenceLevel`) and `BoundedDecimalZeroToOneWithSourceAttribute` (a `simpleContent` extension adding `auc:Source`, used by e.g. `OverallWindowToWallRatio`, `SupplyFractionOfDuctLeakage`, `MinimumDimmingLightFraction`, `WaterFixtureFractionHotWater`). -- `NDBE` (Net Determination Bias Error) and `NMBE` (Normalized Mean Bias Error) are signed by definition (ASHRAE Guideline 14); a model can over- or under-predict. The current `minInclusive value="0"` rejects valid negative results. +- `NDBE` (Net Determination Bias Error) and `NMBE` (Normalized Mean Bias Error) are signed by definition (ASHRAE Guideline 14); a model can over- or under-predict. The current `minInclusive value="0"` rejects valid negative results, and no fixed bound is correct: with NMBE = Σ(yᵢ − ŷᵢ) / ((n − p) · ȳ) × 100, 12 observations of 100 with predictions of 250 and p = 1 give NMBE ≈ −163.6%, and predictions of 0 give ≈ +109.1%. NDBE likewise falls below −100% when predictions exceed twice the observations (the same data give −150%). Both elements are therefore unbounded `xs:decimal`, consistent with `MBE`. ## Implementation @@ -24,7 +24,7 @@ Non-breaking change (MINOR). - Add global `xs:simpleType` `PercentType`: `xs:decimal` restricted to `[0, 100]`. - Add global `xs:complexType` `PercentWithSourceAttribute`: `simpleContent` extension of `auc:PercentType` with `auc:Source` attribute. - `.../DerivedModelPerformance/CVRMSE`: replace the inline 0-100 restriction with `type="auc:PercentType"` (identical value space; patch-level). -- `.../DerivedModelPerformance/NDBE` and `.../DerivedModelPerformance/NMBE`: change `minInclusive` from `0` to `-100` (widening; non-breaking). Documentation notes the value may be negative. +- `.../DerivedModelPerformance/NDBE` and `.../DerivedModelPerformance/NMBE`: remove the inline `[0, 100]` restriction and use `type="xs:decimal"` (widening; non-breaking). Documentation notes the value may be negative and its magnitude may exceed 100. Out of scope (would be breaking, since it narrows existing `xs:decimal` elements): migrating existing percentage elements to `PercentType`. That requires first resolving fraction-vs-percent values in examples and producer data (e.g. Audit Template) and is deferred to a major version.