8 The information model§

AGREED The class set was reduced from v0.1 in two places and extended in four. See Decision Record group B.

8.1 The entity envelope§

An entity carrying nothing beyond id and type is valid. It asserts existence and nothing more, which is occasionally the honest thing to assert.

NOTE v0.1 carried a References field group in the envelope. It was removed: it violates 5.3.1 and duplicates the bus:documentedBy relationship.

8.2 Abstract types and graceful degradation§

PROVISIONAL New in v0.2.

Promotion criterion — an importer that does not understand a leaf class correctly places the entity via `abstractTypes` in a published conformance run.

An entity SHOULD declare its ancestor classes. A receiver meeting bus:Asset with assetKind of a value it does not recognize, or an extension class it has never seen, can then still place it correctly rather than treating it as opaque.

"type": "bus:Asset",
"assetKind": "equipment",
"abstractTypes": ["bus:Asset", "bus:PhysicalEntity", "bus:Entity"]

The same principle governs symbol roles (13.4.2), and the two SHOULD behave alike: unknown leaf, known ancestor, correct handling.

8.3 Parties§

bus:Party is a person or organization with a role in the building: owner, operator, occupant, tenant, service provider, vendor, integrator, consultant, or authority.

The owner SHOULD be identified and named in the manifest subject. A standard whose purpose is owner rights, in which the owner is not addressable, cannot state whose asset a package is.

NOTE Provenance may name an acting party inline as an Agent. Where the party is addressable, the agent SHOULD carry a partyRef so that the two are connected.

8.4 Buildings, spaces, and zones§

Three classes carry structure, on a deliberate cut.

• bus:Building — the unit of ownership and transfer. The manifest subject points at buildings. Carries address, geographic position, time zone, and gross figures that let a receiving system sanity-check a model before trusting it. timeZone MUST be an identifier from [TZDB]; a fixed offset is not acceptable.
• bus:Space — a bounded region, with a spaceKind of site, storey, room, open area, circulation, shaft, plant room, exterior, parking, or roof. Spaces nest through bus:contains, so a site contains a building’s spaces and a storey contains rooms. Where spaceKind is storey, a signed ordinal gives an orderable value that survives translation, with 0 the principal ground storey.
• bus:Zone — a set of spaces behaving as one for some purpose, named by zoneKind. A zone is not a region and has no boundary. Modeling a zone as a space makes containment lie.

Spatial containment is expressed with relationships, not parent pointers, so a space MAY be contained by more than one thing — the usual case for a space that is both on a storey and in a fire compartment.

NOTE v0.1 had five classes here. Site, storey, and room differ in attributes rather than in kind, and were collapsed. Building and Zone were kept for the reasons above.

8.5 Systems, asset types, and assets§

bus:System groups assets that together deliver something, named by a coarse systemKind and, where relevant, a medium. Systems are not physical; they are how the building is reasoned about.

bus:Asset is a single class with an assetKind:

The distinction between equipment and device is functional, not physical. A packaged unit with an integral controller is one physical object and SHOULD be modeled as two entities related by bus:hasPart, because the controller will be replaced several times during the life of the unit and history should follow the right one.

An asset MAY declare the ports at which connections land — which side of a valve, which of a coil’s two water tappings. Ports are declared by the asset and named by the relationship; 9.4 specifies them.

bus:AssetType carries what is true of a product rather than of a unit: manufacturer, model, product line, and rated properties. An asset references it through assetTypeRef. Four hundred identical terminal units then carry one copy of the product facts rather than four hundred, and replacing every actuator with a new model becomes a single assertion.

PROVISIONAL The type and instance split is new in v0.2 and adds an indirection every reader must resolve. It is the change most likely to irritate implementers.

8.6 Points§

pointKind is the durable distinction between an observation, an instruction, a state, and a configured value. It is separate from dataType because the two are independent, and collapsing them is how systems lose the ability to tell a setpoint from a reading.

NOTE A writable point is not necessarily a command. A parameter may be writable and is not an instruction to the plant.

8.7 Telemetry binding§

A binding on a point records how it is reached: protocol, address, an OPTIONAL deviceRef, an OPTIONAL networkRef, and parameters. protocol is a token from the registry of 8.10.2. The free-string network of v0.2 is deprecated in favor of networkRef and MUST still be accepted; 8.10.3 sets out the transition.

"binding": {
  "protocol": "bacnet",
  "address": "analog-input,3",
  "deviceRef": "urn:uuid:...053",
  "network": "BACnet/IP 2001",
  "parameters": { "objectName": "AHU1_SAT", "covIncrement": 0.2 }
}

address and parameters are opaque to this standard. An importer MUST preserve them verbatim (test RT-9) and MUST NOT normalize them, even where it recognizes the protocol and believes it knows a better form.

This is the least glamorous part of the model and among the most valuable. A migration preserving every semantic relationship but losing the addresses obliges an integrator to rediscover and rebind tens of thousands of points by hand.

NOTE A telemetry binding is not a presentation binding. The two share a word and nothing else: one says how a value is acquired, the other says what a value drives on a page.

8.8 History at the interface§

BUS-1 does not carry time-series payloads, and as of this version that is a boundary between parts rather than a deferral: BUS-2: Time Series specifies how history travels — a bus:Series entity declaring each series, and a sample file carried as a package resource under the digest machinery of 16.5. What this clause carries is the point-level declaration that durable history exists, its extent, and its nominal interval, which is what a receiving system needs in order to know what it is missing. An exporter holding history and not including it MUST declare the timeSeries domain as partial or absent (16.6).

NOTE history.resourceRef is deprecated in this version in favor of bus:Series.resourceRef (BUS-2 clause 3): it was a locator with no statement of format, coverage, unit, or count. It MUST still be accepted, per 15.5. Where both are present, the series entity is the statement and the point field is a label.

8.9 Knowledge§

bus:KnowledgeNote carries a noteKind, a body of free text, an OPTIONAL observedAt, an OPTIONAL reviewState, and provenance. It is attached by bus:explains, bus:supports, bus:justifies, or the generic bus:appliesTo.

NOTE Structured knowledge types are deferred to BUS-3. A premature structure would be worse than free text, because it would encourage implementers to discard what does not fit.

8.10 Networks and drivers§

PROVISIONAL New in v0.3. The network entity and the protocol registry close the first half of the gap Annex F.1 recorded; driver configuration is declined, in 8.10.4, on the record.

Promotion criterion — three independent exporters produce network entities for MS/TP or BACnet/IP trunks, and importers preserve `networkRef` without normalization.

8.10.1 The network entity§

bus:Network is a communications network that devices sit on: an MS/TP trunk, an IP subnet, a radio mesh, a driver’s list of devices. It carries a REQUIRED networkKind, an OPTIONAL protocol, and the identifier, segment and parameters by which the source system names it.

Through v0.2 the network was a free string on each telemetry binding. That put the same fact in as many places as there were points, and it put it in the wrong place. Sharing a trunk is a fact about a set of devices, not an intrinsic property of any one of them, which is precisely what 5.3.1 forbids. It also failed in practice: two controllers whose bindings read BACnet/IP 2001 and BACnet IP 2001 are on the same wire and no receiving system can tell, because there is nothing for the two strings to be the same as.

A network entity is that thing. It is asserted once, every binding on the trunk points at it, and bus:hostedBy and bus:connectedTo relate devices to it in the ordinary way.

NOTE An importer whose source carries no network kind MUST write other and MUST NOT infer fieldbus from the presence of a device list. Project Haystack, whose root ^network entity type this follows, carries no kind at all.

8.10.2 The protocol token registry§

protocol is a token from the registry published as bus-protocols.json. It holds 22 tokens: 18 seeded from the protocol defs of Project Haystack 4.0.0, and the remainder field buses that implementers reported and for which Haystack has no def.

The registry is registered but open, in the sense of 7.5. A token outside it is valid and MUST be preserved verbatim. An exporter for which a registered token exists MUST use it rather than a variant spelling.

This does not close the field and is not meant to. It fixes the spelling of the protocols that actually recur, which is the whole of the problem: through v0.2 an exporter writing bacnet and one writing BACnet/IP both validated, and a receiver could not determine whether two bindings reached the same kind of device.

8.10.3 Binding a point to a network§

TelemetryBinding.networkRef names the bus:Network over which a point is reached. The free-string network of v0.2 is deprecated. An importer MUST continue to accept it, per the deprecation rule of 15.5, and an exporter SHOULD write both while both are read. Where both are present, networkRef is the statement and the string is a label. A future MINOR version will set a sunset after which the free-string form MAY be omitted; until it does, dual-writing is what keeps a package readable by importers on either side of the transition.

identifier and parameters on a network are opaque to this standard for exactly the reasons address and parameters on a telemetry binding are (8.7). An importer MUST preserve them verbatim and MUST NOT normalize them. A BACnet network number that arrives as 2001 and leaves as 2001 is worth more than one a receiver has tidied into a form it prefers.

{ "id": "urn:uuid:...071",
  "type": "bus:Network",
  "name": "MS/TP trunk 2, mechanical room 2",
  "networkKind": "fieldbus",
  "protocol": "mstp",
  "identifier": "2001",
  "segment": "MSTP-2" }

"binding": {
  "protocol": "bacnet",
  "address": "analog-input,3",
  "deviceRef": "urn:uuid:...053",
  "networkRef": "urn:uuid:...071",
  "parameters": { "objectName": "AHU1_SAT", "covIncrement": 0.2 }
}

8.10.4 Driver configuration is out of scope§

This version does not model driver configuration, and the omission is a decision rather than an oversight.

Poll rates, retry counts, COV subscription lifetimes, scan intervals, thread pools, license terms, a vendor’s device template: these describe how a piece of integration software is set up. They fail the boundary test of 5.2. A building does not have a poll rate; a product does. Carrying them would mean this standard tracking the configuration surface of every driver any vendor ships, which ages at the speed of the fastest-moving product in the field and describes none of the building.

What BUS carries instead is which network, which device, which address. That is enough for an integrator to rediscover the driver, which is a day of work. It is not enough to rediscover the points, which is the multi-month exercise this standard exists to prevent. The line falls where the labor is irreplaceable.

NOTE The gap table of 20.3 names integration and driver configuration as a row nothing serializes. v0.3 does not close that row and does not claim to. It closes the part of the row that describes the building and says plainly that the rest is not the standard’s to hold.

Brick’s ICT equipment classes were considered and declined. Brick 1.4.4 carries classes for the boxes — BACnet and Modbus controllers, gateways, routers, switches, access points — and carries no network entity and no network-membership predicate at all, so adopting them would import an equipment taxonomy without importing the thing that was missing. 5.3.3 refuses equipment taxonomy. A BACnet router is a bus:Asset with assetKind: "device" and a brick: classification, and it loses nothing by being one; Annex G states the classification rule.