16 The exchange package§
AGREED Dictionaries (16.8) are PROVISIONAL and the compact wire format remains OPEN.
16.1 Overview§
cedar-street-building-a.buspkg
mimetype first entry, stored uncompressed
manifest.json the entry point
model/
identity.json parties and buildings
properties.json property definitions
spaces.json spaces and zones
assets.json systems, asset types, assets
points.json points and telemetry bindings
relationships.json the graph
intent.json objectives, targets, constraints, schedules, sequences
alarms.json alarm definitions
events.json events
knowledge.json knowledge notes
resources.json resource descriptors
presentation.json drawings, layers, elements, bindings
provenance.json change records
resources/ included artifacts
dictionaries/ optional compaction (16.8)
extensions/ unattached extension payloads16.2 The container§
A package MUST be a ZIP archive conforming to [ISO21320-1]. Only STORED and DEFLATED are permitted, and encryption MUST NOT be used at container level.
The first entry MUST be named mimetype, stored uncompressed, with no extra field, containing exactly the package media type with no trailing newline. This places the media type at a fixed byte offset so a file can be identified without parsing the archive, following the convention of ODF and EPUB.
The file extension is .buspkg. The media type is application/vnd.bus.package.
NOTE The media type is in the vendor tree because no recognized standards development organization holds this specification. On adoption, registration MUST move to the standards tree per [RFC6838] and the vendor-tree name MUST continue to be accepted.
16.3 The manifest§
| Field | Requirement |
|---|---|
busVersion, packageId, createdAt | REQUIRED. |
profile | REQUIRED. The conformance profile claimed. 2.3. |
subject | REQUIRED. Buildings, sites, owner, and the instant the model state was captured. |
exporter | REQUIRED. Vendor, product, version, and a URI for the published conformance statement. |
documents | REQUIRED. Path, type, media type, digest, byte length, entity count. |
resources | REQUIRED where resources are included. |
extensions | REQUIRED where extensions are used. 15.3. |
actuation | REQUIRED. 16.7. |
completeness | REQUIRED. 16.6. |
dictionaries | OPTIONAL. 16.8. |
predecessor | RECOMMENDED. The package this one succeeds, forming a chain of custody. |
signatures | OPTIONAL, but SHOULD be present where actuation is present. 19.2. |
16.4 Layout and partitioning§
Model documents MUST be under model/, resources under resources/, dictionaries under dictionaries/, and unattached extension payloads under extensions/.
A document type MAY be split across files; each part is listed separately with the same partOf value, and an importer MUST treat the parts as one logical document without assuming ordering. Every archive entry other than mimetype and manifest.json MUST appear in the manifest. No entry may be absolute, contain a .. segment, or resolve outside the package root.
16.5 Integrity§
Every document and included resource MUST carry a digest computed over the exact bytes stored in the archive. An importer MUST verify every digest before ingesting any content and MUST refuse a package in which any digest does not match. Partial ingestion of a package that fails verification is NOT permitted.
A resource referenced rather than included MUST carry a durable uri and SHOULD carry a digest. A reference with neither is not durable and does not satisfy 2.4.
16.6 The completeness declaration§
The twelve domains are identity, spaces, assets, points, relationships, intent, events, timeSeries, knowledge, resources, representation, and provenance.
NOTE v0.1 had eleven. The history domain was split into events and timeSeries because events are now core and time series remain deferred; an exporter can therefore be complete on one and absent on the other, which is the honest statement.
NOTE Document types map onto domains where the names differ: the alarms document declares under intent, because alarm definitions are operational intent (11.1); the presentation document declares under representation; and the properties and identityMap documents are infrastructure accompanying every profile rather than domains in their own right.
| Reason code | Meaning |
|---|---|
notHeldBySystem | The exporting system never held this. Not a limitation of the exporter. |
notSupportedByExporter | The system holds it; the export function does not carry it. The code an owner should read as a product gap. |
deferredToLaterVersion | This version of the standard does not specify the domain. |
excludedByOwner | Withheld at the owner’s instruction. |
excludedForConfidentiality | Withheld for confidentiality, including personal data. 19.3. |
excludedForSafety | Withheld because its disclosure would create operational risk. Typically actuation. 19.2. |
excludedForSize | Withheld for size, with the content available by another route. |
other | Anything else. A note is REQUIRED. |
NOTE The declaration is deliberately uncomfortable to write. An exporter that cannot carry graphics must say so, in a fixed code, in a file the owner reads before purchase. That discomfort is the enforcement mechanism, since no technical measure can compel completeness.
16.7 The actuation declaration§
AGREED New in v0.2, following the decision that command actions travel.
"actuation": {
"present": true,
"bindingCount": 2,
"highestPriority": 8,
"note": "Supply air setpoint at priority 10 and supply fan command at priority 8.
Both require confirmation. The fan command is interlocked against the
Level 2 fire alarm zone."
}The declaration exists so that a recipient knows what they are holding before they open the model. A package with actuation is not an ordinary document, and the difference should not have to be discovered by reading thirteen thousand entities.
16.8 Dictionaries§
PROVISIONAL
A package MAY carry dictionaries that replace repeated strings — entity types, predicates, property definition identifiers, units, classifications, symbol roles, entity identifiers — with compact tokens. Where present they MUST be declared in the manifest, and a conforming importer MUST be able to expand every dictionary declared.
Canonical JSON remains the form against which conformance is measured (17.5). The model must never become hostage to a compression scheme.
NOTE The volume driver in a graphics-bearing package is bindings, not points: thousands of near-identical records differing only in a target identifier. That is the ideal case for dictionary coding, and it is the reason dictionaries appear at all. The compact wire format itself is open; see Annex E.
16.9 Package chaining§
A package SHOULD carry a predecessor naming the identifier, digest, and creation time of the package it succeeds. Over several transfers this forms a chain of custody: an owner can demonstrate what was handed over, by whom, and when, without depending on any party in the chain still existing.