From API to Ontology: An Architecture for On-demand Semantic Digital Twins
Subscribe
Apple
Spotify
Overcast
Stitcher
RSS
-->
About<br>Home
In our previous post, we drew a line between two layers of an urban energy digital twin: the Truth Layer , a relational system of record that protects the structural integrity of a city's data, and a promised Knowledge Layer , a semantic graph that would let that data reason about itself. We closed with a claim left undefended: that connecting the two creates the infrastructure needed to understand cities, compare them, and design better ones.<br>This post defends that claim. It is the reference architecture for the Ontological Engine — the system that sits atop a Truth Layer API and materialises, on demand, the Brick and RealEstateCore knowledge graphs that make a digital twin queryable, comparable, and interoperable with the wider ecosystem of energy and building tools.<br>I. The Problem with "Build It All" Ontologies<br>The naive approach to ontology generation is exhaustive translation: take every entity in the Truth Layer, convert it to RDF, load the entire result into a triple store, and call it the city's digital twin. This approach fails for three structural reasons.<br>First, staleness . A city's energy systems, meters, and occupancy schedules change continuously. An exhaustively built graph is correct only at the moment of construction; every subsequent API update silently invalidates part of it.<br>Second, irrelevance at scale . A researcher studying the thermal envelope of a single 1966 building has no use for triples describing ten thousand other buildings. A district planner comparing two parcels needs those two parcels, not the city. Building everything up front optimises for a query pattern almost nobody has.<br>Third, the compute and storage costs grow with the wrong variable . They grow with the size of the Truth Layer, when they should grow with the size of the question being asked.<br>The architectural answer is to invert the construction order. Rather than building the graph and then querying it, the engine first queries the Truth Layer and constructs only the graph needed to answer the query . We call this on-demand materialisation: a knowledge graph is not a static export; it is the result of a question.<br>II. Scope as a First-Class Architectural Concept<br>Every digital twin platform eventually confronts the question: a twin of what, exactly? A single building? A parcel containing several? An entire district? An arbitrary geographic bounding box drawn by a researcher on a map?<br>Treating this as an afterthought leads to brittle, special-cased code. We treat it instead as the primary architectural seam, using a strategy pattern: each scope — building, parcel, district, bounding box — is an interchangeable unit that knows only how to fetch raw data for its own boundary. Nothing downstream of it needs to know which scope produced the data it's working with.<br>This decouples which region of the city is being asked about from how we handle the answer. Adding a new scope — say, "all buildings served by a given transformer," or "all buildings within an emission zone" — means writing one new strategy and registering it. The ontology mapper, the persistence layer, and every API consumer remain untouched.<br>The unit that travels between these layers is a context object: a typed container holding exactly the raw entities fetched for a given scope, along with a single piece of architectural connective tissue — a unique, addressable identifier for the resulting graph. We mint these as URNs of the form urn:ngci:twin:{scope}:{identifier} — urn:ngci:twin:building:1, urn:ngci:twin:district:1.<br>III. The System That Makes This Possible<br>The principle of on-demand, scoped materialisation only matters if there is a concrete system capable of executing it reliably, at two very different scales of request, without asking the caller to know the difference. Picture the system as a chain of calls, each layer asking the next to do one narrow thing on its behalf.<br>Two entry points sit at the top, and the architecture deliberately treats them as equally first-class: a command-line interface for direct, scriptable use, and a FastAPI service for programmatic and remote access. Both terminate at the same orchestrator — the twin builder — which means a researcher running a one-off query from a terminal and a production service triggering twins on a schedule are exercising identical logic underneath.<br>The fork beneath FastAPI is the architecture's answer to a problem every twin-building system eventually faces: a single building can be materialised in under a second, while a district can take minutes. Forcing both through the same synchronous request path means either the fast case waits needlessly behind infrastructure built for the slow one, or the slow case times out a caller that was never designed to wait. We resolve this by routing scope, not by routing endpoint: building- and parcel-scoped...