Skip to content

Commit 7d31182

Browse files
jscott3201jscott3201
authored
fix(points): normalize audited semantic mappings (#74)
Align AHU, VAV, and SYS semantic metadata with the immutable ontology pin while preserving all canonical point identities. Add deterministic network-free point validation, adversarial tests, and CI enforcement for the bounded reviewed mappings.
1 parent 742cdd0 commit 7d31182

7 files changed

Lines changed: 1047 additions & 51 deletions

File tree

‎.github/workflows/verify.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,10 @@ jobs:
5252
working-directory: cxf-library
5353
run: python3 tools/lint/registry.py
5454

55+
- name: point semantic lint
56+
working-directory: cxf-library
57+
run: python3 tools/lint/point_semantics.py
58+
5559
- name: Install routine schema lint dependencies
5660
working-directory: cxf-library
5761
run: python3 -m pip install --requirement tools/lint/requirements-routine-schemas.txt

‎SCHEMA.md‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -654,18 +654,26 @@ Target dialect: the open-control engine's composite subset
654654
rule graph.
655655
- A top-level `namespaces` map records the exact ontology IRIs and the versions
656656
the terms were verified against.
657+
- `routines/ontology/ontology-pins.json` is the point dictionaries' sole
658+
immutable authority for Brick, S223 compatibility, and QUDT namespace IRIs
659+
and version echoes.
657660
- `brick`: verified Brick class local name (namespace
658661
`https://brickschema.org/schema/Brick#`).
659662
- `s223`: object `{pattern, property_class, quantitykind, unit, medium,
660663
aspects, enumerationkind?}` using verified ASHRAE 223P terms
661664
(`enumerationkind` for enumerated properties). See
662665
the internal 223P point-modeling note (local-only, not distributed) for the modeling pattern.
663-
- Every term must be verified against the published ontology files — never
664-
from memory. `provisional: true` additionally marks entries with genuine
665-
ambiguity (class-choice judgment calls, unit conflicts, or patterns
666+
- Every term must be reviewed against the evidence named by the pin record —
667+
never from memory. `provisional: true` additionally marks entries with
668+
genuine ambiguity (class-choice judgment calls, unit conflicts, or patterns
666669
unattested in the standard's reference models); the per-point `notes` field
667670
records the specifics. All s223 entries also await confirmation against the
668671
formal ASHRAE 223 standard text once obtained.
672+
- `tools/lint/point_semantics.py` checks strict `points/v1` JSON and shape,
673+
namespace echoes, command/setpoint direction, actuatable quantity and unit
674+
requirements, and the bounded reviewed VAV/SYS mappings. It reads the local
675+
pin record without network access. It does not verify arbitrary external
676+
term existence, evaluate topology or SHACL, or certify building instances.
669677

670678
## `clusters/clusters.json` (`cxf-library/clusters/v1`)
671679

‎points/ahu.points.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,11 @@
88
},
99
"s223": {
1010
"iri": "http://data.ashrae.org/standard223#",
11-
"verified_version": "v1.0.0-2026"
11+
"verified_version": "1.0.0-ppr.2.1"
1212
},
1313
"s223_g36": {
1414
"iri": "http://data.ashrae.org/standard223/1.0/extensions/g36#",
15-
"verified_version": "v1.0.0-2026"
15+
"verified_version": "1.0.0-ppr.2.1"
1616
},
1717
"quantitykind": {
1818
"iri": "http://qudt.org/vocab/quantitykind/",
@@ -23,7 +23,7 @@
2323
"verified_version": "QUDT 3.1.4"
2424
}
2525
},
26-
"notes": "All brick/s223 terms grep-verified against the published ontology files (Brick 1.4.4; ASHRAE 223 v1.0.0-2026 incl. its G36 extension) and, where noted, the official 223P G36 reference model guideline36-2021-A-9 (github.com/open223/models.open223.info). provisional=true marks mappings with genuine ambiguity or unattested 223P patterns; every s223 entry additionally awaits confirmation against the formal ASHRAE 223 standard text, which we do not yet hold.",
26+
"notes": "Brick terms were checked against Brick 1.4.4. ASHRAE 223 terms were checked against the public-review artifact 223p-1.0.0-ppr2.1.ttl (owl:versionInfo 1.0.0-ppr.2.1), including its G36 extension and, where noted, the guideline36-2021-A-9 reference model (github.com/open223/models.open223.info). This artifact is a compatibility baseline, not the final published standard. provisional=true marks mappings with genuine ambiguity or unattested patterns; every s223 entry additionally awaits confirmation against the formal ASHRAE 223 standard text, which we do not yet hold.",
2727
"points": [
2828
{
2929
"name": "sat",

‎points/sys.points.json‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
},
99
"s223": {
1010
"iri": "http://data.ashrae.org/standard223#",
11-
"verified_version": "v1.0.0-2026"
11+
"verified_version": "1.0.0-ppr.2.1"
1212
},
1313
"quantitykind": {
1414
"iri": "http://qudt.org/vocab/quantitykind/",
@@ -257,11 +257,13 @@
257257
"brick": "Valve_Position_Command",
258258
"s223": {
259259
"pattern": "QuantifiableActuatableProperty on the reheat Valve via hasProperty; Actuator actuates the valve",
260-
"property_class": "QuantifiableObservableProperty",
261-
"quantitykind": null,
262-
"unit": null,
260+
"property_class": "QuantifiableActuatableProperty",
261+
"quantitykind": "DimensionlessRatio",
262+
"unit": "PERCENT",
263263
"medium": null,
264-
"aspects": []
264+
"aspects": [
265+
"Binary-Position"
266+
]
265267
},
266268
"notes": "Duplicate of points/vav.points.json rht_vlv_cmd — the reference files SYS-0007 under SYS but scopes it to VAV/FCU zones; bind per zone."
267269
},
@@ -277,7 +279,7 @@
277279
"property_class": "QuantifiableObservableProperty",
278280
"quantitykind": "Temperature",
279281
"unit": "DEG_C",
280-
"medium": "Air",
282+
"medium": "Fluid-Air",
281283
"aspects": []
282284
}
283285
}

‎points/vav.points.json‎

Lines changed: 49 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,11 @@
88
},
99
"s223": {
1010
"iri": "http://data.ashrae.org/standard223#",
11-
"verified_version": "v1.0.0-2026"
11+
"verified_version": "1.0.0-ppr.2.1"
1212
},
1313
"s223_g36": {
1414
"iri": "http://data.ashrae.org/standard223/1.0/extensions/g36#",
15-
"verified_version": "v1.0.0-2026"
15+
"verified_version": "1.0.0-ppr.2.1"
1616
},
1717
"quantitykind": {
1818
"iri": "http://qudt.org/vocab/quantitykind/",
@@ -35,9 +35,9 @@
3535
"s223": {
3636
"pattern": "Sensor observes QuantifiableObservableProperty on the Zone (DomainSpace) via hasProperty",
3737
"property_class": "QuantifiableObservableProperty",
38-
"quantitykind": null,
39-
"unit": null,
40-
"medium": null,
38+
"quantitykind": "Temperature",
39+
"unit": "DEG_C",
40+
"medium": "Fluid-Air",
4141
"aspects": []
4242
},
4343
"provisional": false,
@@ -52,11 +52,13 @@
5252
"brick": "Zone_Air_Heating_Temperature_Setpoint",
5353
"s223": {
5454
"pattern": "QuantifiableActuatableProperty (setpoint) on the Zone via hasProperty",
55-
"property_class": "QuantifiableObservableProperty",
56-
"quantitykind": null,
57-
"unit": null,
58-
"medium": null,
59-
"aspects": []
55+
"property_class": "QuantifiableActuatableProperty",
56+
"quantitykind": "Temperature",
57+
"unit": "DEG_C",
58+
"medium": "Fluid-Air",
59+
"aspects": [
60+
"Aspect-Setpoint"
61+
]
6062
},
6163
"provisional": false,
6264
"notes": "brick:Zone_Air_Heating_Temperature_Setpoint grep-verified in Brick 1.4.4. Bind the ACTIVE (occupied-mode) heating setpoint the loop is controlling to, not a schedule default — same active-setpoint convention as the AHU dictionary's sat_sp."
@@ -70,11 +72,13 @@
7072
"brick": "Zone_Air_Cooling_Temperature_Setpoint",
7173
"s223": {
7274
"pattern": "QuantifiableActuatableProperty (setpoint) on the Zone via hasProperty",
73-
"property_class": "QuantifiableObservableProperty",
74-
"quantitykind": null,
75-
"unit": null,
76-
"medium": null,
77-
"aspects": []
75+
"property_class": "QuantifiableActuatableProperty",
76+
"quantitykind": "Temperature",
77+
"unit": "DEG_C",
78+
"medium": "Fluid-Air",
79+
"aspects": [
80+
"Aspect-Setpoint"
81+
]
7882
},
7983
"provisional": false,
8084
"notes": "brick:Zone_Air_Cooling_Temperature_Setpoint grep-verified in Brick 1.4.4. Active-setpoint convention as zone_temp_sp_htg."
@@ -89,9 +93,9 @@
8993
"s223": {
9094
"pattern": "Sensor observes QuantifiableObservableProperty at the VAV box discharge via hasProperty",
9195
"property_class": "QuantifiableObservableProperty",
92-
"quantitykind": null,
93-
"unit": null,
94-
"medium": null,
96+
"quantitykind": "VolumeFlowRate",
97+
"unit": "L-PER-SEC",
98+
"medium": "Fluid-Air",
9599
"aspects": []
96100
},
97101
"provisional": false,
@@ -106,11 +110,13 @@
106110
"brick": "Supply_Air_Flow_Setpoint",
107111
"s223": {
108112
"pattern": "QuantifiableActuatableProperty (setpoint) on the VAV box via hasProperty",
109-
"property_class": "QuantifiableObservableProperty",
110-
"quantitykind": null,
111-
"unit": null,
112-
"medium": null,
113-
"aspects": []
113+
"property_class": "QuantifiableActuatableProperty",
114+
"quantitykind": "VolumeFlowRate",
115+
"unit": "L-PER-SEC",
116+
"medium": "Fluid-Air",
117+
"aspects": [
118+
"Aspect-Setpoint"
119+
]
114120
},
115121
"provisional": false,
116122
"notes": "brick:Supply_Air_Flow_Setpoint grep-verified in Brick 1.4.4. The ACTIVE setpoint the damper loop tracks (after G36 min/max clamping), not the design value — VAV-0004 compares measured flow against what the loop is currently trying to do."
@@ -124,11 +130,13 @@
124130
"brick": "Min_Air_Flow_Setpoint_Limit",
125131
"s223": {
126132
"pattern": "QuantifiableActuatableProperty (configuration limit) on the VAV box via hasProperty",
127-
"property_class": "QuantifiableObservableProperty",
128-
"quantitykind": null,
129-
"unit": null,
130-
"medium": null,
131-
"aspects": []
133+
"property_class": "QuantifiableActuatableProperty",
134+
"quantitykind": "VolumeFlowRate",
135+
"unit": "L-PER-SEC",
136+
"medium": "Fluid-Air",
137+
"aspects": [
138+
"Aspect-Setpoint"
139+
]
132140
},
133141
"provisional": false,
134142
"notes": "brick:Min_Air_Flow_Setpoint_Limit grep-verified in Brick 1.4.4 — the configured floor, distinct from the active setpoint. VAV-0001 reads it as a point so the rule can watch for bad commissioning values without a BAS config export."
@@ -143,8 +151,8 @@
143151
"s223": {
144152
"pattern": "Sensor observes QuantifiableActuatableProperty... position feedback on the box Damper via hasProperty",
145153
"property_class": "QuantifiableObservableProperty",
146-
"quantitykind": null,
147-
"unit": null,
154+
"quantitykind": "DimensionlessRatio",
155+
"unit": "PERCENT",
148156
"medium": null,
149157
"aspects": []
150158
},
@@ -160,11 +168,13 @@
160168
"brick": "Valve_Position_Command",
161169
"s223": {
162170
"pattern": "QuantifiableActuatableProperty on the reheat Valve via hasProperty; Actuator actuates the valve",
163-
"property_class": "QuantifiableObservableProperty",
164-
"quantitykind": null,
165-
"unit": null,
171+
"property_class": "QuantifiableActuatableProperty",
172+
"quantitykind": "DimensionlessRatio",
173+
"unit": "PERCENT",
166174
"medium": null,
167-
"aspects": []
175+
"aspects": [
176+
"Binary-Position"
177+
]
168178
},
169179
"provisional": false,
170180
"notes": "brick:Valve_Position_Command grep-verified in Brick 1.4.4; attach isPointOf brick:Reheat_Valve (verified). This is the per-box point whose building-wide aggregate became the AHU dictionary's zone_reheat_fraction — the grounding promised with that entry lands here."
@@ -179,8 +189,8 @@
179189
"s223": {
180190
"pattern": "QuantifiableObservableProperty on the Zone via hasProperty",
181191
"property_class": "QuantifiableObservableProperty",
182-
"quantitykind": null,
183-
"unit": null,
192+
"quantitykind": "DimensionlessRatio",
193+
"unit": "PERCENT",
184194
"medium": null,
185195
"aspects": []
186196
},
@@ -229,9 +239,9 @@
229239
"s223": {
230240
"pattern": "Sensor observes QuantifiableObservableProperty at the terminal discharge",
231241
"property_class": "QuantifiableObservableProperty",
232-
"quantitykind": null,
233-
"unit": null,
234-
"medium": null,
242+
"quantitykind": "Temperature",
243+
"unit": "DEG_C",
244+
"medium": "Fluid-Air",
235245
"aspects": []
236246
},
237247
"provisional": false,

0 commit comments

Comments
 (0)