Skip to content

Commit 514eb58

Browse files
nllongnllong
authored
Merge pull request #341 from BuildingSync/refactor/measurename-minoccurs-maxoccurs
Refactor Measurename minOccurs maxOccurs
2 parents 604a395 + b926785 commit 514eb58

File tree

7 files changed

+266
-89
lines changed

7 files changed

+266
-89
lines changed

‎.github/workflows/publish.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
name: Publish
22

33
on:
4-
tags:
5-
- 'v*.*.*'
4+
tags:
5+
- 'v*.*.*'
66

77
jobs:
88
publish:

‎BuildingSync.xsd

Lines changed: 92 additions & 86 deletions
Large diffs are not rendered by default.

‎docs/release_instructions.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Check out master locally, pull changes, and create a tag and push it
2727
git checkout master && git pull
2828
git tag -a v<version> -m "<message>" [SHA]
2929
```
30-
Where `v<version>` is a valid [semantic version](https://semver.org/) (e.g. `v1.2` or `v1.2-pr.1`) and `<message>` is the tagging message (e.g. "First official release")
30+
Where `v<version>` is a valid [semantic version](https://semver.org/) (e.g. `v1.2` or `v1.2-pr.1`) and `<message>` is the tagging message (e.g. "First official release"). See [Versioning](versioning.md) for more information.
3131
```bash
3232
# push the tag
3333
git push origin

‎docs/versioning.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Versioning
2+
3+
Having consistent meanings of versions is helpful to users. By the version alone, a user can determine whether or not an implementation of BuildingSync supports their existing documents or not.
4+
5+
Since version 2.0.0 (post 2016 version reset), BuildingSync attempts to follow [semantic versioning](https://semver.org/). Since semantic versioning (semver) is more directed towards APIs, it can be helpful to translate the meaning of breaking changes, non-breaking features, and patches. When thinking about the API of an xml schema, consider XPaths, when and how they break, as well as document validation, when and how historical documents are no longer valid, as these are the use cases of XML documents.
6+
7+
Note that BuildingSync reset the numbering of the schema in 2016.
8+
9+
## Breaking changes
10+
These are the changes that require a new MAJOR version. Generally this would be any time where there could exist a historical document that would not validate against the new schema. This would include:
11+
12+
- adding a required element/attribute that was not previously required
13+
- moving the location of an existing element or changing its name (e.g. moving order in sequence or to different parent)
14+
- changing to an incompatible type (e.g. decimal to integer)
15+
- changing the restrictions for a simple type to something which is not the superset of the previous restriction
16+
17+
## Non-breaking features
18+
These are the changes that require a new MINOR version. This would include any changes which are meaningful changes to the schema, but do not break the validation of historical documents. For example:
19+
20+
- adding a new non-required element/attribute
21+
- changing a simple type to a compatible type (e.g. decimal to string)
22+
- adding a new enum option for a simple type
23+
24+
## Patches
25+
These are the changes that require a new PATCH version. This would include changes which do not meaningfully change the schema. For example:
26+
27+
- updating the documentation
28+
- restructuring the XSD without changing the schema (e.g. turning an inline element definition into a reference or creating a new type)

‎proposals/2021/Add SpatialUnits to Section.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Add SpatialUnits to Section
2+
3+
## Overview
4+
5+
This proposal is to add the `SpatialUnits/SpatialUnit` element sets as a child of a `Section`. It entails breaking out the current `SpatialUnit` element into a standalone complex type for reuse, which, upon implementation, will have no change in the current usage of `SpatialUnit` at the building level, i.e. it is a non-breaking change.
6+
7+
## Justification
8+
9+
In mixed use real-estate, a particular section of a building might be designated for multi-family residential. A user would then want to associate spatial units specifically to that section of the building rather than the building at a whole. Currently, we are able to define spatial units at the building level, but not at any other level of the premise.
10+
11+
## Example
12+
```xml
13+
<auc:Buildings>
14+
<auc:Building ID="b1">
15+
<auc:OccupancyClassification>Mixed-use commercial</auc:OccupancyClassification>
16+
<!-- SpatialUnit at the building level remains the same -->
17+
<auc:SpatialUnits>
18+
<auc:SpatialUnit>
19+
<auc:NumberOfUnits>1</auc:NumberOfUnits>
20+
</auc:SpatialUnit>
21+
</auc:SpatialUnits>
22+
<auc:Sections>
23+
<auc:Section ID="S1">
24+
<auc:SectionType>Space function</auc:SectionType>
25+
<auc:OccupancyClassification>Multifamily</auc:OccupancyClassification>
26+
<!-- SpatialUnit added at the Section level -->
27+
<auc:SpatialUnits>
28+
<auc:SpatialUnit>
29+
<auc:NumberOfUnits>1</auc:NumberOfUnits>
30+
</auc:SpatialUnit>
31+
</auc:SpatialUnits>
32+
</auc:Section>
33+
</auc:Sections>
34+
</auc:Building>
35+
```
36+
37+
## Implementation
38+
39+
The current `SpatialUnit` element is broken out into a standalone complex type as `SpatialUnitTypeType`
40+
```xml
41+
<xs:complexType name="SpatialUnitTypeType">
42+
<xs:sequence>
43+
<xs:element name="SpatialUnitType" minOccurs="0">
44+
<xs:annotation>
45+
<xs:documentation>Unit type within the premises.</xs:documentation>
46+
</xs:annotation>
47+
<xs:simpleType>
48+
<xs:restriction base="xs:string">
49+
<xs:enumeration value="Lots"/>
50+
<xs:enumeration value="Parking spaces"/>
51+
<xs:enumeration value="Apartment units"/>
52+
<xs:enumeration value="Businesses"/>
53+
<xs:enumeration value="Guest rooms"/>
54+
<xs:enumeration value="Stations"/>
55+
<xs:enumeration value="Buildings"/>
56+
<xs:enumeration value="Areas"/>
57+
<xs:enumeration value="Thermal Zones"/>
58+
<xs:enumeration value="Floors"/>
59+
<xs:enumeration value="Rooms"/>
60+
<xs:enumeration value="Bedrooms"/>
61+
<xs:enumeration value="Other"/>
62+
<xs:enumeration value="Unknown"/>
63+
</xs:restriction>
64+
</xs:simpleType>
65+
</xs:element>
66+
<xs:element name="NumberOfUnits" minOccurs="0">
67+
<xs:annotation>
68+
<xs:documentation>Number of individual units within the premises.</xs:documentation>
69+
</xs:annotation>
70+
<xs:complexType>
71+
<xs:simpleContent>
72+
<xs:extension base="xs:integer">
73+
<xs:attribute ref="auc:Source"/>
74+
</xs:extension>
75+
</xs:simpleContent>
76+
</xs:complexType>
77+
</xs:element>
78+
<xs:element name="UnitDensity" minOccurs="0">
79+
<xs:annotation>
80+
<xs:documentation>Number of units per 1,000 square feet.</xs:documentation>
81+
</xs:annotation>
82+
<xs:complexType>
83+
<xs:simpleContent>
84+
<xs:extension base="xs:decimal">
85+
<xs:attribute ref="auc:Source"/>
86+
</xs:extension>
87+
</xs:simpleContent>
88+
</xs:complexType>
89+
</xs:element>
90+
<xs:element name="SpatialUnitOccupiedPercentage" minOccurs="0">
91+
<xs:annotation>
92+
<xs:documentation>Percentage of the spatial units that are occupied. (0-100) (%)</xs:documentation>
93+
</xs:annotation>
94+
<xs:complexType>
95+
<xs:simpleContent>
96+
<xs:extension base="xs:decimal"/>
97+
</xs:simpleContent>
98+
</xs:complexType>
99+
</xs:element>
100+
</xs:sequence>
101+
</xs:complexType>
102+
```
103+
104+
At the Building and Section level, the implementation then looks like:
105+
```xml
106+
...
107+
<xs:element name="SpatialUnits" minOccurs="0">
108+
<xs:complexType>
109+
<xs:sequence>
110+
<xs:element name="SpatialUnit" type="auc:SpatialUnitTypeType" minOccurs="1" maxOccurs="unbounded"/>
111+
</xs:sequence>
112+
</xs:complexType>
113+
</xs:element>
114+
...
115+
```
116+
117+
## References

‎proposals/2021/Refactor MeasureName minOccurs maxOccurs.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Refactor MeasureName minOccurs maxOccurs
2+
3+
## Overview
4+
5+
This proposal is to refactor the `minOccurs` and `maxOccurs` bounds for `MeasureName` element under each measure category, if it's restricted with enumerated options.
6+
7+
## Justification
8+
9+
For a measure category (`TechnologyCategory`) that a specific `Measure` element falls into, there should be one and only one `MeasureName` corresponding to it (or at least using `Other` indicating not covered by enumerated options).
10+
`MeasureName` under `HealthAndSafety` category should not have bounds as there is no enumeration, which means it could be left unspecified.
11+
12+
## Implementation
13+
14+
```xml
15+
<xs:element name="TechnologyCategoryName" minOccurs="0">
16+
...
17+
<xs:complexType>
18+
<xs:sequence>
19+
<xs:element name="MeasureName" minOccurs="1" maxOccurs="1">
20+
...
21+
</xs:element>
22+
```
23+
24+
## References

‎spec/validation_spec.rb

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -356,6 +356,8 @@
356356
'SpaceID',
357357
'SpaceIDs',
358358
'StartTimestamp',
359+
'SpatialUnit',
360+
'SpatialUnits',
359361
'SteamBoilerMaximumOperatingPressure',
360362
'SteamBoilerMinimumOperatingPressure',
361363
'Story',

0 commit comments

Comments
 (0)