diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 00000000..dba71e97 --- /dev/null +++ b/.claude/CLAUDE.md @@ -0,0 +1 @@ +@../AGENTS.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..a8efda75 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,5 @@ +# BuildingSync Schema - Copilot Instructions + +All repository rules for AI agents live in [AGENTS.md](../AGENTS.md). Read and follow it before making changes. + +File-scoped rules in [.github/instructions/](instructions/) apply automatically to `BuildingSync.xsd` and `proposals/**/*.md`. diff --git a/.github/instructions/proposals.instructions.md b/.github/instructions/proposals.instructions.md new file mode 100644 index 00000000..d1e5f089 --- /dev/null +++ b/.github/instructions/proposals.instructions.md @@ -0,0 +1,15 @@ +--- +applyTo: "proposals/**/*.md" +description: "Format and process for BuildingSync feature proposals" +--- + +# Writing a proposal + +Follow [proposals/README.md](../../proposals/README.md). + +- Location: `proposals//.md` (e.g. `proposals/2026/Add Field-assembled DX system to DXSystemType.md`). +- Required sections, in order: `## Overview` (brief summary), `## Justification` (evidence the change is needed and beneficial), `## Implementation` (exact XSD changes: element paths, types, enumerations, documentation text). Optional: `## References`. +- State whether the change is breaking or non-breaking per [docs/versioning.md](../../docs/versioning.md); breaking proposals must discuss severity of the breakage and the migration path. +- Reference the GitHub issue it addresses. +- Proposal PRs are discussed and accepted/rejected before (or alongside) the implementation PR; the project lead decides if no consensus. +- Markdown is formatted by prettier via `poetry run pre-commit run --all-files`. diff --git a/.github/instructions/schema-xsd.instructions.md b/.github/instructions/schema-xsd.instructions.md new file mode 100644 index 00000000..c600f12a --- /dev/null +++ b/.github/instructions/schema-xsd.instructions.md @@ -0,0 +1,47 @@ +--- +applyTo: "BuildingSync.xsd" +description: "Conventions for editing the BuildingSync XSD" +--- + +# Editing BuildingSync.xsd + +Read the surrounding region first and keep edits minimal; do not reformat unrelated content. Classify the change (breaking / non-breaking / patch, per [docs/versioning.md](../../docs/versioning.md)) before editing. + +## Structure + +- Indent with 2 spaces, never tabs; no XMLSpy comments (run `bundle exec rake remove_tabs` after editing). +- Never use `xs:complexContent` (test-enforced); compose with named types, `xs:sequence`, and `ref`. +- New elements are optional (`minOccurs="0"`) unless a breaking change is intended and approved. +- Inserting a new optional element into an `xs:sequence` is fine; moving or reordering existing elements is breaking. +- `xs:element` names must be unique across the schema. To reuse a structure, define a named `xs:complexType`/`xs:simpleType` (suffix `Type`) or a global element used via `ref="auc:..."`. +- Global names must not collide with gbXML global names. +- Do not modify the header (`version` attribute, title documentation, root `version` enumeration) outside a release; see [docs/release_instructions.md](../../docs/release_instructions.md). + +## Documentation + +- Every new element, type, and enumeration-bearing element gets `<xs:annotation><xs:documentation>`. +- Write a clear definition sentence; put units in parentheses at the end, e.g. `... gross floor area. (ft2)`, `(kBtu/ft2)`, `($)`, `(cfm)`, `(W/ft2)`. +- Documentation-only changes are patch-level. + +## Enumerations + +- Adding a value is non-breaking; removing or renaming one is breaking (deprecate instead). +- Follow the existing wording/casing style of sibling values; include `Other` and `Unknown` where siblings do. + +## Common patterns + +- Identity: `<xs:attribute name="ID" type="xs:ID" use="required"/>`. +- Links: element with `<xs:attribute name="IDref" type="xs:IDREF" use="required"/>`; document the valid target in [docs/linking_elements.md](../../docs/linking_elements.md). +- Data provenance: `<xs:attribute ref="auc:Source"/>`; system state: `ref="auc:Status"`. +- Extensibility: `<xs:element ref="auc:UserDefinedFields" minOccurs="0"/>`. +- gbXML content uses the `gbxml` prefix (see [docs/gbXML_reference.md](../../docs/gbXML_reference.md)). + +## Deprecation + +- Never remove elements outside a major version (XSD header Rule #1). +- Mark deprecated items in documentation: `WARNING: This element is being deprecated, use <Replacement> instead.` (for enum values: `WARNING: This enumeration is being deprecated, use ... instead`). +- Update examples to use the replacement. + +## Verify + +`bundle exec rake` and `bundle exec rake generate_data_dictionary` must pass. diff --git a/.gitignore b/.gitignore index 7e691c19..a2784370 100644 --- a/.gitignore +++ b/.gitignore @@ -49,3 +49,4 @@ gbxml.xsd *.bak *.backup *.tmp +/tmp diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..06abf7ff --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,75 @@ +# BuildingSync Schema - AI Agent Instructions + +This is the canonical instruction file for AI coding agents (Copilot, Claude Code, Codex, Cursor, etc.). `.claude/CLAUDE.md` and `.github/copilot-instructions.md` point here. + +BuildingSync is an XML schema (`BuildingSync.xsd`, namespace prefix `auc`) for exchanging building energy audit and building characteristics data. Every change must keep historical documents and downstream tools (Audit Template, Use Case Validator, BuildingSync-gem, bsyncpy, website schema viewer) working unless a major version bump is intended. + +## Repository layout + +| Path | Purpose | +| --------------------------------------------- | ------------------------------------------------------------------------------------------------------ | +| `BuildingSync.xsd` | The schema (single file). Imports gbXML v6.01 via URL. | +| `examples/*.xml` | Example instances. All must validate (except files named `*Invalid Schema*`). | +| `proposals/<YEAR>/*.md` | Feature proposals (see [proposals/README.md](proposals/README.md)). | +| `docs/` | Versioning, release, linking (ID/IDREF), gbXML, developer docs; Jupyter notebooks in `docs/notebooks`. | +| `migration_scripts/` | `upgrade_from_X_to_Y.py` scripts for breaking upgrades between adjacent versions. | +| `spec/validation_spec.rb` | RSpec checks run by `bundle exec rake`. | +| `src/data_dictionary.rb`, `src/change_log.rb` | Data dictionary and changelog generators. | +| `.github/instructions/` | File-scoped rules; read before editing matching files (see below). | +| `tmp/` | Git-ignored scratch space. Never commit it. | + +## File-scoped rules (read before editing) + +- `BuildingSync.xsd`: [.github/instructions/schema-xsd.instructions.md](.github/instructions/schema-xsd.instructions.md) +- `proposals/**/*.md`: [.github/instructions/proposals.instructions.md](.github/instructions/proposals.instructions.md) + +## Commands + +- Tests (CI): `bundle exec rake` then `bundle exec rake generate_data_dictionary` (the latter also detects name conflicts). +- Format XSD/examples (removes tabs and XMLSpy comments, 2-space indent): `bundle exec rake remove_tabs`. +- Lint/format everything else: `poetry run pre-commit run --all-files` (prettier for Markdown/YAML/JSON, ruff for Python with line length 140, trailing whitespace, end-of-file newline, JSON pretty-format). +- Bulk documentation edits: `bundle exec rake generate_documentation_csv`, edit `updated_documentation` column, then `bundle exec rake update_documentation`. +- On Windows, `C:\Ruby32-x64\bin\ruby.exe -S bundle exec rake` is more reliable than bare `bundle`. + +## Rules enforced by tests (`spec/validation_spec.rb`) + +1. Every `examples/*.xml` (except `*Invalid Schema*`) validates against `BuildingSync.xsd`. +2. No tab characters in `BuildingSync.xsd` or `examples/*.xml`. +3. No `XMLSpy` text in `BuildingSync.xsd` or `examples/*.xml`. +4. No `xs:complexContent` anywhere in `BuildingSync.xsd`. +5. Global `xs:element`/`xs:complexType`/`xs:simpleType`/`xs:attribute` names must not collide with gbXML global names (only `Capacity Latitude Location Longitude Manufacturer State ZipCode` are permitted). +6. Named `xs:element` names must be unique across the whole schema, except the legacy `ignored_dupes` list. Never add to that list; reuse a shared type or `ref` instead. + +## Versioning and change classification ([docs/versioning.md](docs/versioning.md)) + +Classify every schema change before making it and report the classification: + +- **Breaking (MAJOR)**: any historical document could stop validating - adding a required element/attribute, moving/renaming an element (including order in a sequence or new parent), changing to an incompatible type (e.g. decimal to integer), narrowing a simple-type restriction (removing an enum, tighter bounds). +- **Non-breaking (MINOR)**: new optional element/attribute, compatible type widening (e.g. decimal to string), new enum value. +- **Patch**: documentation-only changes, or restructuring that does not change what validates (e.g. inline definition to named type or `ref`). + +Deprecation policy (in the XSD header): **"Schema elements may only be removed by incrementing the major version of the schema document."** In a minor/patch release, deprecate instead of removing or renaming. Breaking changes need a migration script in `migration_scripts/` (see [upgrade_from_2.4_to_2.5.py](migration_scripts/upgrade_from_2.4_to_2.5.py)) that updates the root `version` and inserts a generated-from comment. + +## Workflow for a schema change + +1. Non-trivial features start with a proposal in `proposals/<current year>/<Title Case Name>.md` containing at least **Overview**, **Justification**, **Implementation** (breaking changes must discuss severity); optional **References**. +2. Edit `BuildingSync.xsd` following [.github/instructions/schema-xsd.instructions.md](.github/instructions/schema-xsd.instructions.md). +3. Update or add `examples/*.xml` when the change affects them; keep examples free of deprecated elements where possible. +4. If a linking (`IDref`) element is added, update [docs/linking_elements.md](docs/linking_elements.md). +5. Run `bundle exec rake remove_tabs`, `bundle exec rake`, `bundle exec rake generate_data_dictionary`, and pre-commit. +6. Do **not** edit `CHANGELOG.md` or schema version numbers in feature PRs; the changelog is generated from PR labels at release time ([docs/release_instructions.md](docs/release_instructions.md)). + +## Pull requests ([docs/developer_resources.md](docs/developer_resources.md), `.github/workflows/CI_Labels.yml`) + +- One logical/discrete change per PR (e.g. removing an element is separate from adding an unrelated enum). +- Use [.github/PULL_REQUEST_TEMPLATE.md](.github/PULL_REQUEST_TEMPLATE.md): background, what it does, how to test, relevant tickets, screenshots. +- Labels (CI-enforced on `develop-v2`/`develop-v3`): either exactly one of `Breaking Change` / `Non-breaking Change` **plus** a `Schema: ...` scope label (`Controls`, `Documentation`, `General`, `Measures`, `Reports`, `Systems`, `Validation`), or `No Schema Changes` alone, or `ignore` alone (release/procedural PRs). +- Contributions align with the release schedule: two releases per year (about end of May and November), cutoff about two weeks before ([.github/CONTRIBUTING.md](.github/CONTRIBUTING.md)). + +## Agent behavior + +- Read the relevant XSD region before editing; cite line numbers; never reformat unrelated parts of the 17k-line XSD. +- Prefer additive, non-breaking changes; flag anything breaking and ask before proceeding. +- Do not push, tag, release, or comment on GitHub issues/PRs without explicit approval. +- Do not add files to the repo root or create summary markdown files unless asked; use `tmp/` for scratch notes. +- Keep this file the single source of truth; update it (not the pointer files) when rules change. diff --git a/BuildingSync.xsd b/BuildingSync.xsd index 51b42ffc..555d3ed2 100644 --- a/BuildingSync.xsd +++ b/BuildingSync.xsd @@ -259,7 +259,7 @@ <xs:documentation>Details about the the assessment. This might include methods used, criteria, evidence, or basis of evaluation.</xs:documentation> </xs:annotation> </xs:element> - <xs:element name="Tightness" type="auc:Tightness" minOccurs="0"> + <xs:element name="Tightness" type="auc:TightnessType" minOccurs="0"> <xs:annotation> <xs:documentation>Description of the infiltration characteristics for an opaque surface, fenestration unit, a thermal zone.</xs:documentation> </xs:annotation> @@ -10677,7 +10677,7 @@ <xs:documentation>True if fenestration is weatherstripped, false otherwise.</xs:documentation> </xs:annotation> </xs:element> - <xs:element name="TightnessFitCondition" type="auc:Tightness" minOccurs="0"> + <xs:element name="TightnessFitCondition" type="auc:TightnessType" minOccurs="0"> <xs:annotation> <xs:documentation>Indicator of expected air leakage through fenestration.</xs:documentation> </xs:annotation> @@ -15598,7 +15598,7 @@ <xs:enumeration value="Unknown"/> </xs:restriction> </xs:simpleType> - <xs:simpleType name="Tightness"> + <xs:simpleType name="TightnessType"> <xs:restriction base="xs:string"> <xs:enumeration value="Very Tight"/> <xs:enumeration value="Tight"/> diff --git a/docs/linking_elements.md b/docs/linking_elements.md index 95bd42a0..3de97b93 100644 --- a/docs/linking_elements.md +++ b/docs/linking_elements.md @@ -8,66 +8,66 @@ BuildingSync uses `xs:ID` to identify an element and `xs:IDREF` to link to that The following table lists all elements that require an `IDREF` attribute, and annotates the valid `ID` elements they can link to. Ideally, this annotation should be standardized and "programmable" in the future, for editing and validation purpose. -| element_name | linked elements | full paths | +| element_name | linked elements | full paths | | --------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- | -| ExistingSystemReplaced\* | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | -| AlternativeSystemReplacement\* | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | -| ExistingSystemAffected\* | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | -| ModifiedSystem\* | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | -| AlternativeSystemAdded\* | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | -| ExistingSystemRemoved\* | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | -| SystemIDReceivingHeat | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | -| SystemIDProvidingHeat | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | -| LinkedSystemID | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | -| LinkedBuildingID | Building | BuildingSync/Facilities/Facility/Sites/Site/Buildings/Building | -| CeilingID | CeilingSystem | BuildingSync/Facilities/Facility/Systems/CeilingSystems/CeilingSystem | -| CondenserPlantID | CondenserPlant | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/Plants/CondenserPlants/ | CondenserPlant | -| ContactID | Contact | BuildingSync/Facilities/Facility/Contacts/Contact | -| CertifiedAuditTeamMemberContactID | Contact | BuildingSync/Facilities/Facility/Contacts/Contact | -| AuditorContactID | Contact | BuildingSync/Facilities/Facility/Contacts/Contact | -| PrimaryContactID | Contact | BuildingSync/Facilities/Facility/Contacts/Contact | -| CoolingPlantID | CoolingPlant | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/Plants/CoolingPlants/CoolingPlant | -| CoolingSourceID | CoolingSource | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/HeatingAndCoolingSystems/CoolingSources/CoolingSource | -| DeliveryID\* | Delivery | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/HeatingAndCoolingSystems/Deliveries/Delivery | -| HeatingDeliveryID | Delivery | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/HeatingAndCoolingSystems/Deliveries/Delivery | -| CoolingDeliveryID | Delivery | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/HeatingAndCoolingSystems/Deliveries/Delivery | -| LinkedDeliveryID | Delivery | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/HeatingAndCoolingSystems/Deliveries/Delivery | -| DoorID | Door | BuildingSync/Facilities/Facility/Systems/FenestrationSystems/FenestrationSystem/FenestrationType/Door | -| ExteriorFloorID | ExteriorFloorSystem | BuildingSync/Facilities/Facility/Systems/ExteriorFloorSystems/ExteriorFloorSystem | -| LinkedFacilityID | Facility | BuildingSync/Facilities/Facility | -| FoundationID | FoundationSystem | BuildingSync/Facilities/Facility/Systems/FoundationSystems/FoundationSystem | -| SourceHeatingPlantID\* | HeatingPlant | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/Plants/HeatingPlants/HeatingPlant | -| LinkedHeatingPlantID\* | HeatingPlant | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/Plants/HeatingPlants/HeatingPlant | -| ReheatPlantID | HeatingPlant | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/Plants/HeatingPlants/HeatingPlant | -| HeatingPlantID | HeatingPlant | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/Plants/HeatingPlants/HeatingPlant | -| HeatingSourceID | HeatingSource | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/HeatingAndCoolingSystems/HeatingSources/HeatingSource | -| MeasureID | Measure | BuildingSync/Facilities/Facility/Measures/Measure | -| BaselinePeriodModelID | Model | BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario/ScenarioType/DerivedModel/Models/Model | -| ReportingPeriodModelID | Model | BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario/ScenarioType/DerivedModel/Models/Model | -| ParentResourceUseID | ResourceUse | BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario/ResourceUses/ResourceUse | -| ResourceUseID | ResourceUse | BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario/ResourceUses/ResourceUse | -| RoofID | RoofSystem | BuildingSync/Facilities/Facility/Systems/RoofSystems/RoofSystem | -| MeasuredScenarioID | Scenario | BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario | -| ReferenceCase\* | Scenario | BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario | -| HVACScheduleID | Schedule | BuildingSync/Facilities/Facility/Schedules/Schedule | -| OccupancyScheduleID | Schedule | BuildingSync/Facilities/Facility/Schedules/Schedule | -| ExistingScheduleAffected\* | Schedule | BuildingSync/Facilities/Facility/Schedules/Schedule | -| LinkedScheduleID | Schedule | BuildingSync/Facilities/Facility/Schedules/Schedule | -| ModifiedSchedule\* | Schedule | BuildingSync/Facilities/Facility/Schedules/Schedule | -| ExcludedSectionID | Section | BuildingSync/Facilities/Facility/Sites/Site/Buildings/Building/Sections/Section | -| LinkedSectionID | Section | BuildingSync/Facilities/Facility/Sites/Site/Buildings/Building/Sections/Section | -| LinkedSiteID | Site | BuildingSync/Facilities/Facility/Sites/Site | -| SkylightID | Skylight | BuildingSync/Facilities/Facility/Systems/FenestrationSystems/FenestrationSystem/FenestrationType/Skylight | -| LinkedSpaceID | Space | BuildingSync/Facilities/Facility/Sites/Site/Buildings/Building/Sections/Section/ThermalZones/ThermalZone/Spaces/Space | -| SpaceID | Space | BuildingSync/Facilities/Facility/Sites/Site/Buildings/Building/Sections/Section/ThermalZones/ThermalZone/Spaces/Space | -| MakeupAirSourceID\* | Space | BuildingSync/Facilities/Facility/Sites/Site/Buildings/Building/Sections/Section/ThermalZones/ThermalZone/Spaces/Space | -| TenantID | Tenant | BuildingSync/Facilities/Facility/Tenants/Tenant | -| LinkedThermalZoneID | ThermalZone | BuildingSync/Facilities/Facility/Sites/Site/Buildings/Building/Sections/Section/ThermalZones/ThermalZone | -| ThermalZoneID | ThermalZone | BuildingSync/Facilities/Facility/Sites/Site/Buildings/Building/Sections/Section/ThermalZones/ThermalZone | -| LinkedTimeSeriesID | TimeSeries | BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario/TimeSeriesData/TimeSeries, BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario/ScenarioType/DerivedModel/SavingSummaries/SavingSummary/\*\*\*Data/TimeSeries, BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario/ScenarioType/DerivedModel/Models/Model/ModeledTimeSeriesData/TimeSeries | -| UtilityID | Utility | BuildingSync/Facilities/Facility/Reports/Report/Utilities/Utility | -| WallID | WallSystem | BuildingSync/Facilities/Facility/Systems/WallSystems/WallSystem | -| WeatherStationID | WeatherStation | BuildingSync/Facilities/Facility/Sites/Site/(Buildings/Building/)WeatherStations/WeatherStation | -| WindowID | Window | BuildingSync/Facilities/Facility/Systems/FenestrationSystems/FenestrationSystem/FenestrationType/Window | +| ExistingSystemReplaced\* | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | +| AlternativeSystemReplacement\* | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | +| ExistingSystemAffected\* | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | +| ModifiedSystem\* | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | +| AlternativeSystemAdded\* | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | +| ExistingSystemRemoved\* | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | +| SystemIDReceivingHeat | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | +| SystemIDProvidingHeat | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | +| LinkedSystemID | \*\*\*System | BuildingSync/Facilities/Facility/Systems/\*\*\*Systems/\*\*\*System | +| LinkedBuildingID | Building | BuildingSync/Facilities/Facility/Sites/Site/Buildings/Building | +| CeilingID | CeilingSystem | BuildingSync/Facilities/Facility/Systems/CeilingSystems/CeilingSystem | +| CondenserPlantID | CondenserPlant | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/Plants/CondenserPlants/ | CondenserPlant | +| ContactID | Contact | BuildingSync/Facilities/Facility/Contacts/Contact | +| CertifiedAuditTeamMemberContactID | Contact | BuildingSync/Facilities/Facility/Contacts/Contact | +| AuditorContactID | Contact | BuildingSync/Facilities/Facility/Contacts/Contact | +| PrimaryContactID | Contact | BuildingSync/Facilities/Facility/Contacts/Contact | +| CoolingPlantID | CoolingPlant | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/Plants/CoolingPlants/CoolingPlant | +| CoolingSourceID | CoolingSource | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/HeatingAndCoolingSystems/CoolingSources/CoolingSource | +| DeliveryID\* | Delivery | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/HeatingAndCoolingSystems/Deliveries/Delivery | +| HeatingDeliveryID | Delivery | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/HeatingAndCoolingSystems/Deliveries/Delivery | +| CoolingDeliveryID | Delivery | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/HeatingAndCoolingSystems/Deliveries/Delivery | +| LinkedDeliveryID | Delivery | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/HeatingAndCoolingSystems/Deliveries/Delivery | +| DoorID | Door | BuildingSync/Facilities/Facility/Systems/FenestrationSystems/FenestrationSystem/FenestrationType/Door | +| ExteriorFloorID | ExteriorFloorSystem | BuildingSync/Facilities/Facility/Systems/ExteriorFloorSystems/ExteriorFloorSystem | +| LinkedFacilityID | Facility | BuildingSync/Facilities/Facility | +| FoundationID | FoundationSystem | BuildingSync/Facilities/Facility/Systems/FoundationSystems/FoundationSystem | +| SourceHeatingPlantID\* | HeatingPlant | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/Plants/HeatingPlants/HeatingPlant | +| LinkedHeatingPlantID\* | HeatingPlant | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/Plants/HeatingPlants/HeatingPlant | +| ReheatPlantID | HeatingPlant | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/Plants/HeatingPlants/HeatingPlant | +| HeatingPlantID | HeatingPlant | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/Plants/HeatingPlants/HeatingPlant | +| HeatingSourceID | HeatingSource | BuildingSync/Facilities/Facility/Systems/HVACSystems/HVACSystem/HeatingAndCoolingSystems/HeatingSources/HeatingSource | +| MeasureID | Measure | BuildingSync/Facilities/Facility/Measures/Measure | +| BaselinePeriodModelID | Model | BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario/ScenarioType/DerivedModel/Models/Model | +| ReportingPeriodModelID | Model | BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario/ScenarioType/DerivedModel/Models/Model | +| ParentResourceUseID | ResourceUse | BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario/ResourceUses/ResourceUse | +| ResourceUseID | ResourceUse | BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario/ResourceUses/ResourceUse | +| RoofID | RoofSystem | BuildingSync/Facilities/Facility/Systems/RoofSystems/RoofSystem | +| MeasuredScenarioID | Scenario | BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario | +| ReferenceCase\* | Scenario | BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario | +| HVACScheduleID | Schedule | BuildingSync/Facilities/Facility/Schedules/Schedule | +| OccupancyScheduleID | Schedule | BuildingSync/Facilities/Facility/Schedules/Schedule | +| ExistingScheduleAffected\* | Schedule | BuildingSync/Facilities/Facility/Schedules/Schedule | +| LinkedScheduleID | Schedule | BuildingSync/Facilities/Facility/Schedules/Schedule | +| ModifiedSchedule\* | Schedule | BuildingSync/Facilities/Facility/Schedules/Schedule | +| ExcludedSectionID | Section | BuildingSync/Facilities/Facility/Sites/Site/Buildings/Building/Sections/Section | +| LinkedSectionID | Section | BuildingSync/Facilities/Facility/Sites/Site/Buildings/Building/Sections/Section | +| LinkedSiteID | Site | BuildingSync/Facilities/Facility/Sites/Site | +| SkylightID | Skylight | BuildingSync/Facilities/Facility/Systems/FenestrationSystems/FenestrationSystem/FenestrationType/Skylight | +| LinkedSpaceID | Space | BuildingSync/Facilities/Facility/Sites/Site/Buildings/Building/Sections/Section/ThermalZones/ThermalZone/Spaces/Space | +| SpaceID | Space | BuildingSync/Facilities/Facility/Sites/Site/Buildings/Building/Sections/Section/ThermalZones/ThermalZone/Spaces/Space | +| MakeupAirSourceID\* | Space | BuildingSync/Facilities/Facility/Sites/Site/Buildings/Building/Sections/Section/ThermalZones/ThermalZone/Spaces/Space | +| TenantID | Tenant | BuildingSync/Facilities/Facility/Tenants/Tenant | +| LinkedThermalZoneID | ThermalZone | BuildingSync/Facilities/Facility/Sites/Site/Buildings/Building/Sections/Section/ThermalZones/ThermalZone | +| ThermalZoneID | ThermalZone | BuildingSync/Facilities/Facility/Sites/Site/Buildings/Building/Sections/Section/ThermalZones/ThermalZone | +| LinkedTimeSeriesID | TimeSeries | BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario/TimeSeriesData/TimeSeries, BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario/ScenarioType/DerivedModel/SavingSummaries/SavingSummary/\*\*\*Data/TimeSeries, BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario/ScenarioType/DerivedModel/Models/Model/ModeledTimeSeriesData/TimeSeries | +| UtilityID | Utility | BuildingSync/Facilities/Facility/Reports/Report/Utilities/Utility | +| WallID | WallSystem | BuildingSync/Facilities/Facility/Systems/WallSystems/WallSystem | +| WeatherStationID | WeatherStation | BuildingSync/Facilities/Facility/Sites/Site/(Buildings/Building/)WeatherStations/WeatherStation | +| WindowID | Window | BuildingSync/Facilities/Facility/Systems/FenestrationSystems/FenestrationSystem/FenestrationType/Window | Notes: elements with \* marks will be renamed soon to enhance consistency; elements with \*\*\* in names refer to multiple options (any valid element with name matching the pattern) within the path. diff --git a/docs/notebooks/bsync_examples/Small-Office-Level-1.md b/docs/notebooks/bsync_examples/Small-Office-Level-1.md index 2c7c4fe7..f2590732 100644 --- a/docs/notebooks/bsync_examples/Small-Office-Level-1.md +++ b/docs/notebooks/bsync_examples/Small-Office-Level-1.md @@ -835,11 +835,11 @@ utilities += ng_ut Now that we have a current building measured scenario, we want to declare energy and monthly billing data. Per Std 211 6.1.2.1, a minimum of 12 months (preferably up to 3 years) of energy use data is required. The mechanical system of the small office prototype is a heatpump air handler with natural gas backup. We know that Missoula is cold, so likely it will use natural gas backup at some point during its operation. We run an example simulation to get estimates for this, which come out as follows: -| Resource Type | Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec | +| Resource Type | Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec | | ---------------------- | ------- | ------- | ------- | ------ | ------- | ------- | ------- | ------- | ------- | ------- | ------- | ------- | ----- | -| Electricity (kWh) | 6792.89 | 5841.75 | 6025.19 | 4985.3 | 5184.04 | 5358.55 | 5755.67 | 5981.78 | 5401.94 | 5225.84 | 5672.15 | 6291.63 | -| Natural Gas (MMBtu) | 5.7 | 4.01 | 0.58 | 0.4 | 0.02 | 0 | 0 | 0 | 0 | 0.01 | 0.36 | 6.08 | 17.16 | -| GHG Emissions (MtCO2e) | 250.0 | 240.0 | 260.0 | 250.0 | 260.0 | 230.0 | 280.0 | 270.0 | 260.0 | 250.0 | 240.0 | 250.0 | +| Electricity (kWh) | 6792.89 | 5841.75 | 6025.19 | 4985.3 | 5184.04 | 5358.55 | 5755.67 | 5981.78 | 5401.94 | 5225.84 | 5672.15 | 6291.63 | +| Natural Gas (MMBtu) | 5.7 | 4.01 | 0.58 | 0.4 | 0.02 | 0 | 0 | 0 | 0 | 0.01 | 0.36 | 6.08 | 17.16 | +| GHG Emissions (MtCO2e) | 250.0 | 240.0 | 260.0 | 250.0 | 260.0 | 230.0 | 280.0 | 270.0 | 260.0 | 250.0 | 240.0 | 250.0 | In BuildingSync land, we need to declare an resource use for each resource type. Standard, allowable enumerations exist for this already. We do this as follows: diff --git a/proposals/2026/Rename Tightness simpleType to TightnessType.md b/proposals/2026/Rename Tightness simpleType to TightnessType.md new file mode 100644 index 00000000..daec8d0e --- /dev/null +++ b/proposals/2026/Rename Tightness simpleType to TightnessType.md @@ -0,0 +1,51 @@ +# Rename Tightness simpleType to TightnessType + +## Overview + +This proposal renames the global `xs:simpleType` `auc:Tightness` to `auc:TightnessType` so that it no longer shares a name with the element `auc:Tightness`. It addresses [issue #428](https://github.com/BuildingSync/schema/issues/428). + +## Justification + +The schema currently defines both an element and a simple type named `Tightness`: + +- Element: `auc:AirInfiltrationSystem/auc:Tightness` with `type="auc:Tightness"` +- Element: `auc:FenestrationSystemType/auc:TightnessFitCondition` with `type="auc:Tightness"` +- Simple type: `<xs:simpleType name="Tightness">` + +XSD allows elements and types to share a name because they live in separate symbol spaces, but the duplication: + +- causes name collisions in tools that generate code or documentation from the schema (e.g. classes for both the element and the type in a single namespace); +- is inconsistent with the schema's naming convention, where named types carry a `Type` suffix (e.g. `SiteType`, `HVACSystemType`); +- makes the schema harder to read, because `type="auc:Tightness"` looks like a reference to the element. + +## Implementation + +Rename the simple type and update its two references in `BuildingSync.xsd`: + +```xml +<xs:simpleType name="TightnessType"> + <xs:restriction base="xs:string"> + <xs:enumeration value="Very Tight"/> + <xs:enumeration value="Tight"/> + <xs:enumeration value="Average"/> + <xs:enumeration value="Leaky"/> + <xs:enumeration value="Very Leaky"/> + <xs:enumeration value="Unknown"/> + </xs:restriction> +</xs:simpleType> +``` + +- `auc:AirInfiltrationSystem/auc:Tightness`: `type="auc:Tightness"` -> `type="auc:TightnessType"` +- `auc:FenestrationSystemType/auc:TightnessFitCondition`: `type="auc:Tightness"` -> `type="auc:TightnessType"` + +The enumeration values, element names, element locations, and documentation are unchanged. + +### Classification + +Patch-level per [docs/versioning.md](../../docs/versioning.md): type names do not appear in instance documents, so every document that validated before still validates and vice versa. No migration script is needed. + +Downstream tools that generate code from XSD type names (e.g. [bsyncpy](https://github.com/BuildingSync/bsyncpy)) may see the generated class for this type renamed from `Tightness` to `TightnessType`, and should be regenerated against the new schema. + +## References + +- [Issue #428](https://github.com/BuildingSync/schema/issues/428)