Data Integration & Ontologies
What is an independent data layer in a smart building?
What an independent data layer does, how to test its independence and why the operating model comes before the platform.
What should a building data API specification include?
An endpoint list is not a specification; require meaning, quality, time and change rules in writing.
On this page
The test of a building data API specification is simple: could another team build a working, reliable integration from it without reverse-engineering the supplier's behaviour? Passing that test takes more than a list of endpoints. The specification has to describe what the data means, how time and quality are represented, how access is secured, how the interface will change over time, and how it is supported.
An API (application programming interface) is the defined way one piece of software requests information or actions from another. In buildings, it is usually how analytics, reporting, maintenance and occupant applications obtain readings, history, events and asset information from a building management system (BMS) or a data layer.
Insist on a machine-readable description
The tender should require a formal description of the interface in a recognised format. For HTTP APIs, the OpenAPI Specification is widely used; version 3.2.1 was published in September 2026, and the specification site lists any later releases. It describes itself as a standard, programming-language-agnostic interface description that lets humans and computers understand a service's capabilities without access to its source code. A description in this form can drive documentation, client code generation and automated tests.
But the format describes structure, not meaning. It will not tell a developer what "temp" or "value" signifies in your building. That is the job of the rest of the specification.
Say what the data means
| Item | What to specify |
|---|---|
| Identifiers | Stable IDs for sites, spaces, assets and data points; how they relate; what happens on renaming |
| Units | Explicit units for every value, using a declared convention |
| Timestamps | Format, time zone (preferably UTC with offset), and whether the time is when measured or when received |
| Value type | Measured, set point, command, status, calculated |
| Interval data | Whether a value is a cumulative register or consumption for the interval, and which end of the interval the timestamp marks |
| Quality | How missing, stale, estimated or invalid values are flagged — and how they differ from a genuine zero |
| Context | Links between points, equipment and spaces, ideally using a documented semantic model such as Brick or Project Haystack |
Describe how the interface behaves
Developers also need to know how history is queried, including time ranges, resolution, aggregation methods, maximum response sizes and pagination. The specification should set out rate limits and how they are signalled, and error responses with meaningful codes and messages. It should explain how late-arriving or corrected data is handled and how consumers learn of corrections, and whether subscriptions or event streams are offered for near-real-time data.
Security and commands
Security has to be written into the specification itself: the authentication method, authorisation by role and by site, how credentials are issued and rotated, audit logging and encryption in transit. Reading data and sending commands should be separate permissions. Any command interface needs its own validation, acknowledgement, limits and failure handling, because it is a control function and should be specified as one.
Plan for change and support
Interfaces evolve, so the specification should state the versioning policy and how breaking changes are signalled, with a minimum notice period before a version is deprecated or withdrawn. A test or sandbox environment with representative data lets integrators work without touching live systems. Service levels for availability and support response, a named contact and a way of tracking issues complete the picture.
Testing against real decisions
Acceptance tests should be written around the decisions the data must support, and run with the receiving application before sign-off. Edge cases are where poorly specified APIs reveal themselves.
Practical application
Settle it at tender
Ambiguity removed at tender costs far less than ambiguity discovered during integration, so set these requirements in the tender documents and approve the supplier's specification before development starts. Pagin Consulting writes API requirements of this kind, with test cases like the clock change above.
Sources
This article connects to our work on Our services.
Related service
Our servicesWe can discuss how this subject fits the project brief.
Contact Pagin Consulting