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..82b4ee68 --- /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. +- The proposal and its implementation may be in the same PR or in separate PRs; separate PRs are not required. Either way, the proposal is discussed and accepted/rejected before merge; 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..ae399601 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,101 @@ +# 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 (see [BuildingSync ecosystem](#buildingsync-ecosystem)) 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). +- `generate_data_dictionary` writes `docs/DataDictionary.xlsx` and `docs/enumerations.json`; these are release artifacts built by the publish workflow. Do not commit them; delete them after a local run. +- 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. Every change to `BuildingSync.xsd` other than a documentation-only edit needs a proposal in `proposals/<current year>/<Title Case Name>.md` containing at least **Overview**, **Justification**, **Implementation** (state the breaking/non-breaking/patch classification; breaking changes must discuss severity and migration); optional **References**. If you skip a proposal, say so explicitly and explain why. +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). A proposal and its implementation count as one change and may share a PR; separate PRs are not required. +- 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)). + +## BuildingSync ecosystem + +This repo is the source of truth; the tools below consume released versions of `BuildingSync.xsd` (all under <https://github.com/BuildingSync>). Versions noted were current in October 2026; verify on GitHub before relying on them. + +| Repo | Role | Coupling to this schema | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [BuildingSync-website](https://github.com/BuildingSync/BuildingSync-website) (live at <https://buildingsync.net>) | Django app: schema viewer, validator (web + `POST /api/validate`), use case hosting, BEDES mapping | Parses each released XSD and `enumerations.json` from the release; hosts example files per schema version; BEDES terms re-mapped per schema version. | +| [use-cases](https://github.com/BuildingSync/use-cases) | Official/community Schematron use cases (`<Org>/schematron/<Name>-X.Y.Z.sch`) with examples (`<Org>/examples/<Name>-X.Y.Z-*.xml`) | XPaths in `.sch` files reference element paths; `schemaVersion` = `<sch ver>-<min bsync ver>[-<max bsync ver>]`. Renames/moves break rules. | +| [TestSuite](https://github.com/BuildingSync/TestSuite) (`pip install testsuite`) | Python library/CLI to generate and validate Schematron | Used by use-cases CI. | +| [BOSS](https://github.com/BuildingSync/BOSS) | BuildingSync OpenStudio Simulator: BuildingSync XML to OpenStudio workflow (OpenStudio 3.10, BuildingSync 2.7.0). Replaces BuildingSync-gem. | Reads specific XPaths (e.g. `OccupancyClassification`, `FloorAreas`, `PrincipalHVACSystemType`, `ClimateZoneType`, lighting `InstalledPower`, plug load `WeightedAverageLoad`). | +| [buildingsync-measures-gem](https://github.com/BuildingSync/buildingsync-measures-gem) | OpenStudio measures used by BOSS (HVAC, envelope, schedules, infiltration) | Measure arguments map from BuildingSync enumerations/values. | +| [BuildingSync-gem](https://github.com/BuildingSync/BuildingSync-gem) | Legacy Ruby translator (OpenStudio 3.4); superseded by BOSS | Do not target for new work. | +| [BuildingSync-asset-extractor](https://github.com/BuildingSync/BuildingSync-asset-extractor) | Python: extracts assets from BuildingSync for SEED; BuildingSync to CTS spreadsheet (BuildingSync 2.7.0) | Asset definitions reference element paths and enumerations. | +| [bsyncpy](https://github.com/BuildingSync/bsyncpy) | Python classes generated from a released XSD (currently 2.5.0) | Regenerated per schema release. | +| [bsyncr](https://github.com/BuildingSync/bsyncr), [bsyncr-server](https://github.com/BuildingSync/bsyncr-server) | R package/server serializing NMEC (nmecr) results to BuildingSync | Writes `Scenarios`, `TimeSeries`, `DerivedModels`. | +| [transformations](https://github.com/BuildingSync/transformations), [std211-translator](https://github.com/BuildingSync/std211-translator), [gbXML_Schemas](https://github.com/BuildingSync/gbXML_Schemas), [assetscore-schematron-docs](https://github.com/BuildingSync/assetscore-schematron-docs) | Older one-off scripts and reference material | Low activity; check before relying on them. | + +Archived repos (`website`, `website-schemas`, `website-legacy`, `measures`, `python-package`, `projectmonitor`) are out of scope. + +When a schema change renames, moves, deprecates, or changes the meaning of an element or enumeration: + +- Search the affected names in the repos above (at least use-cases, BOSS, buildingsync-measures-gem, BuildingSync-asset-extractor) and list impacted repos in the proposal's **Implementation** section. +- Suggest follow-up issues in those repos; do not edit or open issues/PRs in other repos without explicit approval. +- Do not assume another repo's internals from this file; fetch its README or source first. + +## 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/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/README.md b/proposals/README.md index e671678b..83c6477f 100644 --- a/proposals/README.md +++ b/proposals/README.md @@ -13,11 +13,11 @@ BuildingSync is intended to be a standardized language for commercial building e The process is semi-formal and is not intended to be rigidly applied. The procedure is roughly comprised of the following steps: 1. The proposer writes a Markdown document, modeled on this document, that succinctly describes the changes that are proposed. -2. The proposer creates a GitHub pull request that adds the document to the proposal directory in a subdirectory named for the year in which the submission is being made (e.g. proposals/2018/Add_New_Feature_XYZ.md). +2. The proposer creates a GitHub pull request that adds the document to the proposal directory in a subdirectory named for the year in which the submission is being made (e.g. proposals/2018/Add_New_Feature_XYZ.md). The pull request may also include the implementation of the proposed changes; separate proposal and implementation pull requests are not required. 3. The proposer, the BuildingSync team, and other stakeholders and interested parties discuss the proposal and make modifications using the GitHub pull request discussion facility. At the conclusion of this process, the proposal is accepted or rejected. If a clear consensus cannot be reached to accept or reject the proposal, the project lead will decide if the proposal should be accepted. -4. If the proposal is accepted, new GitHub issues are created to track the development (or a GitHub Project if it is a larger proposal), and a developer is assigned to the issues (not necessarily the proposer or a BuildingSync team member). The "proposal" pull request is then merged. -5. The change is made by the developer in accordance with the contribution policy. -6. The developer initiates a GitHub pull request when the changes are complete. The BuildingSync team and other stakeholders and interested parties will review the implementation and request necessary changes. If consensus can be reached that the implementation is acceptable, the pull request is merged and tracking items are closed. If a clear consensus cannot be reached to accept or reject the implementation, the project lead will decide if the implementation should be accepted. +4. If the proposal is accepted and the pull request already includes the implementation, the implementation is reviewed as described in step 6 and the pull request is merged once both are accepted. Otherwise, new GitHub issues are created to track the development (or a GitHub Project if it is a larger proposal), a developer is assigned to the issues (not necessarily the proposer or a BuildingSync team member), and the "proposal" pull request is merged. +5. If not already done, the change is made by the developer in accordance with the contribution policy. +6. The implementation is reviewed in its pull request (either the combined pull request or a separate one initiated by the developer when the changes are complete). The BuildingSync team and other stakeholders and interested parties will review the implementation and request necessary changes. If consensus can be reached that the implementation is acceptable, the pull request is merged and tracking items are closed. If a clear consensus cannot be reached to accept or reject the implementation, the project lead will decide if the implementation should be accepted. The proposal document must contain at least three sections: **Overview**, **Justification**, and **Implementation**. The purpose of each of the sections is as follows: