Domain Semantics 3 capabilities
Lesson 1 of 4 domains — 3 capabilities: what the municipality ultimately cares about.
This domain answers: What does the municipality ultimately care about — service, infrastructure, or resources?
Source for this lesson
semantic-capabilities-reference.md, section "Domain Semantics (3 capabilities)"
1. The question this domain answers
Domain Semantics separates three things that get confused constantly in municipal data: whether the service actually worked, what the infrastructure itself did, and what it cost to do it. All three can be true at once and still tell completely different stories — a streetlight can burn full brightness (infrastructure did its job) while the street stays dark (service failed, because a tree grew in front of it) at high energy cost (resource spent). One number never tells you which of the three you're looking at; you have to know what question it's answering.
2. The three capabilities
| Capability | Question it answers | Reference doc's examples |
|---|---|---|
| Service Outcome | Did the real-world effect actually happen, independent of how the infrastructure behaved? | Street illuminance at road surface level; soil moisture at root level; water pressure delivered to consumers |
| Infrastructure Output | What did the asset itself physically produce, regardless of whether that achieved the goal? | Lumens emitted by a luminaire; pump flow rate; valve opening percentage; motor speed |
| Resource Consumption | What did it cost — in energy, water, fuel, battery — to produce that output? | Energy; water; fuel; battery usage; active/reactive power; voltage; frequency |
3. The tie-breaker: outcome vs output
The pair people mix up most is Service Outcome vs Infrastructure Output, because they often move together. The reference doc's rule: Service Outcome is the "so what" — an effect experienced by people, infrastructure, or the environment. Infrastructure Output is what the asset is doing or producing, full stop, with no claim about whether that produced the intended effect. If a sub-observation would still be true even when the service completely fails, it's Infrastructure Output, not Service Outcome.
4. Fresh example — an irrigation cycle
| Sub-observation | Primary Capability | Why |
|---|---|---|
| Root-level soil moisture at 22% | Service Outcome | This is the real-world effect the irrigation exists to achieve — moisture in the soil, not anything the valve or pump did. |
| Valve V7 at 40% open | Infrastructure Output | This is what the asset itself is doing. It stays true even if a clogged emitter meant that opening never reached the roots. |
| Pump drew 3.1 kWh | Resource Consumption | Cost of the cycle, independent of whether the moisture target was hit. |
Now suppose the emitter really was clogged and root-level moisture stayed at 8% despite all that valve opening and energy spent. Nothing above changes — Infrastructure Output and Resource Consumption still read exactly the same. Only Service Outcome exposes the failure. That's the entire reason this capability exists as its own thing instead of being folded into Infrastructure Output.