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.

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.

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, network, and parameters.

"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§

v0.2 does not carry time-series payloads. It carries the declaration that history exists, which is what a receiving system needs 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).

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-2. A premature structure would be worse than free text, because it would encourage implementers to discard what does not fit.