Smart Cities SIG

Lesson 0 — Foundations

Semantic Capabilities — Foundations

Lesson 0 — the two mechanics every other lesson in this workspace assumes you already have: splitting an observation, and picking one Primary Capability.

1. The problem this framework solves

Municipal infrastructure produces a constant stream of operational data — temperatures, flow rates, status codes, alarms. A raw value says little on its own: "22%" means nothing until you know it's soil moisture, at root level, measured ten minutes ago, by a sensor the city doesn't fully trust in heavy rain. A semantic capability is one dimension of that missing meaning — what the value represents, where it came from, how much to trust it, or how it should be acted on. The reference doc groups 14 of these capabilities into 4 semantic domains, aligned with the ISO/IEC 30141 IoT reference architecture.

2. Observation vs Sub-observation

Real operational reports are rarely about one thing. The reference doc's own definition:

An observation is the raw, possibly compound fact as originally stated; a sub-observation is what you get after splitting it so each piece has exactly one thing it's fundamentally about — its Primary Capability — though it may still carry Companion Capabilities for context.

Here's a fresh example — not from the reference doc — to make that concrete:

That single sentence is really three separate facts glued together. Splitting it:

Notice what didn't happen: we didn't force all three facts under one label just because they came from the same sentence about the same pump. Each sub-observation gets classified on its own terms.

3. Primary Capability vs Companion Capability

Every sub-observation gets exactly one Primary Capability — the thing it's fundamentally about, the answer to "what is this piece of information mainly telling me?" It can also carry one or more Companion Capabilities: other dimensions of meaning that are worth keeping attached, but aren't the main point.

Take the third row above: "on manual override, comms lost an hour ago" is mainly about what the pump is doing autonomously right now (Fallback Behaviour). The fact that this was triggered by a comms drop is useful context — worth recording — but it's not the main point of that sub-observation. That's why Network Operability rides along as a companion instead of competing for Primary.

This distinction matters because it's easy to get stuck arguing "but couldn't this also be about X?" for almost every sub-observation. The framework's answer is: yes, often — record X as a companion, and move on. Primary is reserved for the one thing the sub-observation is fundamentally about.

4. The 4 domains, at a glance

Each domain groups capabilities that answer a different kind of question:

Lessons 1–4 take one domain each. By the end you'll have all 14 capabilities and the tie-breaker rules the reference doc uses to resolve the cases that feel like they could go two ways.