Brick · Part 3 of 3 · The production contract
The Semantic Interface.
A graph becomes infrastructure when applications can discover dependable context, locate external data and rely on controlled validation, versions and change. The interface is not one endpoint. It is a governed contract.
TL;DR
Query the meaning.
Retrieve the value from its source.
Brick can provide the discovery and context layer of an integration without becoming the transport, historian or control API.
- SPARQL discovers entities, relationships and external representations.
- External references can locate BACnet or time-series representations, but Brick prescribes no standard data API.
- Brick publishes SHACL shapes; tooling can use them alongside owner-defined constraints to validate a model.
- Inference can add superclasses, inverse relationships and tags, but is not strictly required for every deployment.
- Production use needs explicit versions, provenance, extension policy, acceptance tests and a named owner.
A semantic interface is a contract, not a new monolith.
In production, the Brick graph has a specific job: expose shared meaning and navigable context. It can tell an application that SAT-3 is a supply-air temperature sensor belonging to AHU-3, and provide a reference that helps locate the corresponding representation elsewhere.
The graph does not need to ingest every time-series value or become the command path. The building automation system, gateway, historian or data platform can remain authoritative for those payloads.
Brick’s official interfaces guidance describes ways to work with graph data, but Brick does not prescribe a standard API for retrieving every external payload. Calling it an interface is useful only when that boundary remains explicit.
The graph answers “what should I ask for?” The source system answers “what is its value now?”
Let SPARQL find the sources and their context.
SPARQL queries graph patterns rather than local tag syntax. An application can ask for air-handling units, their supply-air temperature sensors and any external representations attached to those points.
brick:Air_Handling_Unit, traverse brick:hasPoint to supply-air temperature sensors, then return the reference nodes or properties that identify external representations.The query result should return identities and metadata, not silently pretend to return the live temperature. A BACnet reference can identify a device, object type and object instance. A time-series reference can identify a database, stream or collection according to the external representation being used.
| SPARQL discovers | External system provides |
|---|---|
| Which AHUs match the requested class | Current equipment state |
| Which points belong to each AHU | Current and historical values |
| How points and equipment are related | Sampling, quality and retention behaviour |
| Which external representations are declared | Authentication and data-access semantics |
The application still needs a connector that understands the referenced platform. Brick standardises useful meaning in the graph; it does not erase the operational differences between BACnet, a historian and a cloud time-series service.
Separate discovery from retrieval.
A robust query-to-data flow has visible hand-offs. Each step can fail independently and should produce diagnostics that identify whether the problem is semantic, referential, connective or operational.
AHU + SAT sensorAHU-3 → SAT-3ref:hasExternalReferencevalue + timestamp + qualityanalysis / display / ruleThis separation protects ownership boundaries. Replacing a historian may require updating references and connectors without rewriting the semantic question. Refining the graph may improve discovery without moving the time-series store.
Runtime design must also define missing-reference behaviour, stale identifiers, access denial, timeout, quality flags and unit handling. Semantics reduce interpretation work; they do not remove operational error handling.
Use SHACL as a gate, not a slogan.
Brick publishes SHACL shapes, and SHACL-capable tooling can validate graph data against them. A deployment can also add owner-defined shapes for project requirements: required points, allowed extensions, identifier patterns or relationships needed by an application.
Validation does not prove that a relationship is true in the physical building. It tests the supplied graph against declared constraints. An AHU can pass a structural shape and still be linked to the wrong sensor if the source evidence or mapping was wrong.
Run Brick-published and owner-approved SHACL shapes.
Treat the validation profile as a versioned deliverable. Record which shapes ran, which severity levels block release, how exceptions are approved and which graph version produced the report.
Make implicit behaviour an explicit deployment choice.
Brick inference can add useful statements, including superclass types, inverse relationships and tags. A point typed as a specific supply-air temperature sensor can also be recognised through broader classes; a declared feeds edge can yield its inverse; class definitions can contribute tags.
Inference is not strictly required to use Brick. A deployment may query explicit statements only, perform reasoning at load time, materialise an inferred graph or reason during query execution. The chosen behaviour changes query results and must be part of the contract.
| Decision | Production question |
|---|---|
| Inference profile | Which rules run, and when? |
| Materialisation | Are inferred triples stored or calculated? |
| Query assumptions | May applications rely on superclasses or inverse edges being present? |
| Refresh | When are inferences recomputed after a source change? |
The ontology version must also be explicit. Import the intended Brick release through an approved, reproducible mechanism and record the ontology IRI/version information used to build and validate the graph. Avoid silently following an unpinned “latest” dependency in production.
If reasoning changes the answer, reasoning is part of the interface version.
Extend locally without forking the shared language.
Projects often need concepts that are not represented at the desired specificity in Brick. A local namespace can define additional classes or properties and relate them to Brick where semantically justified. The extension should remain visibly local, documented and testable.
Do not mint a new predicate merely because the team cannot find the official one, and do not redefine an official Brick term to mean something project-specific. Search the current ontology and documentation first. Where a local term is necessary, state its definition, owner, status, expected domain/range and migration plan.
Provenance can be managed in a graph, release manifest, data catalogue or controlled repository. The mechanism matters less than the ability to answer: who asserted this, from which evidence, through which transformation, under which approved version?
External references deserve the same discipline. A changed BACnet object instance or time-series key is an interface change even if the semantic entity remains AHU-3.
Accept the interface with tests and a named owner.
A syntactically valid RDF file is not an accepted semantic interface. Acceptance should exercise the behaviours that consumers depend on, using representative data and expected results.
- Parse and load the graph with the approved ontology and imports.
- Run the agreed Brick and owner SHACL validation profiles.
- Execute competency-question SPARQL tests with expected result sets.
- Resolve a representative set of BACnet and time-series references.
- Retrieve sample values and preserve timestamp, unit and quality context.
- Confirm inference-dependent tests under the approved reasoning profile.
- Run regression tests for consumers before a version is promoted.
Ownership closes the contract. A named owner approves ontology upgrades, local extensions, exceptions, reference changes and release timing. Producers know what they must supply. Consumers know which version and behaviour they can rely on. Operations knows how a broken reference or stale graph is corrected.
This is the point where data governance becomes concrete: not a policy document beside the graph, but decisions embedded in releases, tests and accountabilities.
A semantic model becomes an interface when someone owns the promises it makes.
The series conclusion
Meaning becomes infrastructure when it is discoverable, testable, versioned and owned.
Brick supplies vocabulary and graph semantics. Production architecture supplies connectors, controls and accountability. Keep those responsibilities connected without confusing them.
The semantic interface is a governed promise between producers and consumers.Continue reading
Brick: One Object, a Graph of Context
Build a useful Brick subgraph around AHU-3 using classes, instances, composition, topology, location, points, controls and governed graph boundaries.
Read article
Brick: From Tags to Meaning
Learn how Brick turns building-system tags into machine-readable entities, classes and relationships, and why it complements IEC 81346.
Read articleThe Complete Object: Who Owns Which Truth?
A practical owner-side guide to technical information authority: who contributes, governs and assures each part of a complete technical object.
Read article