Annex A — Conformance test suite — Building Understanding Standard

A Conformance test suite outline§

Normative as to what must be tested. A fixture kit of twelve tampered packages, each declaring the behavior a conforming implementation must exhibit, is published with the reference tooling, together with two implementations — Python and TypeScript — that pass the suite and reconstruct each other’s exports canonically. Both share an author; results from an independent party remain self-declared until one exists.

A.1 Structure§

Four groups, matching the four conformance targets of 2.2. Each test carries a grade:

MUST — failure means the implementation does not conform at the claimed profile.
SHOULD — failure is reported in the conformance statement but does not defeat conformance.
INFO — measured and reported; no pass or fail.

A machine-readable form is distributed as bus-conformance-tests.json. Where the two differ, this annex governs. Group RT is the heart of the suite: each test exports package A, imports it, re-exports package B, and compares in canonical form per 17.5.

A.2 Group PK — Package validity§

Target: package.

ID	Grade	Test and pass criterion
`PK-1`	MUST	Container form (BUS-1 16.2). Open the package as a ZIP archive. Pass: The archive opens, the first entry is named 'mimetype', it is stored uncompressed, and its content is exactly the registered media type string with no trailing newline.
`PK-2`	MUST	Manifest present and valid (BUS-1 16.3). Read manifest.json at the package root and validate against bus-manifest.schema.json. Pass: The manifest exists and validates with no errors.
`PK-3`	MUST	Document validity (BUS-1 17.4). Validate every file listed in manifest.documents against bus-document.schema.json. Pass: Every listed document exists and validates with no errors.
`PK-4`	MUST	Digest integrity (BUS-1 16.5). Recompute the digest of every entry in manifest.documents and manifest.resources. Pass: Every recomputed digest equals the declared digest, and every declared byteLength matches.
`PK-5`	MUST	No undeclared payload (BUS-1 16.4). Enumerate all archive entries. Pass: Every entry other than 'mimetype' and 'manifest.json' appears in manifest.documents or manifest.resources.
`PK-6`	MUST	Path safety (BUS-1 16.4). Inspect every archive entry name. Pass: No entry is absolute, contains a '..' segment, or resolves outside the package root.
`PK-7`	MUST	Identifier uniqueness (BUS-1 6.2). Collect every entity id in the package. Pass: No id occurs twice.
`PK-8`	MUST	Referential closure (BUS-1 9.2). Resolve every subject, object, deviceRef, targetOf, appliesToRef, scheduleRef and ChangeRecord subject. Pass: Every reference resolves to an entity present in the package, or to an entity explicitly declared external in the manifest.
`PK-9`	MUST	Extension declaration (BUS-1 15.3). Collect every namespace prefix used in type names, predicates and extension keys. Pass: Every non-bus prefix is declared in manifest.extensions.
`PK-10`	MUST	Completeness declaration (BUS-1 16.6). Inspect manifest.completeness.domains. Pass: All twelve substrate domains are present, and every domain in state partial or absent carries a reason.
`PK-11`	SHOULD	Profile support (BUS-1 2.3). Compare the declared profile against the domains actually populated. Pass: Every domain required by the declared profile is in state complete or partial, not absent.
`PK-12`	MUST	Property definition coverage (BUS-1 7.8). Collect every property value in the package and resolve its definition. Pass: Every property value references a bus:PropertyDefinition present in the package. No bare key-value property data appears anywhere.
`PK-13`	MUST	Property value agrees with its definition (BUS-1 7.8). For each property value, compare its shape against the declared datatype and unit. Pass: Quantity values carry the unit declared by the definition; string, number and enum values match their declared datatype.
`PK-14`	MUST	Presentation referential integrity (BUS-1 13). Resolve every element drawing and layer, every layer drawing, every represents and navigatesTo, and every binding element and target. Pass: All resolve. Every element's layer belongs to the same drawing as the element. Every navigatesTo names a drawing.
`PK-15`	MUST	Actuation declaration is accurate (BUS-1 16.7). Count write and readWrite bindings and compare against manifest.actuation. Pass: present matches whether any write binding exists; bindingCount and highestPriority match the content. A package containing write bindings and declaring actuation absent fails.
`PK-16`	MUST	Write bindings are well formed (BUS-1 13.7). For each write binding, inspect its write block and its target. Pass: A command priority is declared, the target point is writable, the priority is within the target's declared priority model, and any constraintRef or interlockRef resolves to a bus:Constraint.
`PK-17`	SHOULD	Drawing scale is checkable (BUS-1 13.3). Inspect each drawing for a reference dimension. Pass: A reference dimension is present and its stated length agrees with the distance between its two drawing coordinates under the declared units.

A.3 Group RT — Round-trip reconstruction§

Target: roundTrip. Each test exports package A from the source system, imports A into the receiving system, re-exports package B from the receiving system, and compares A with B after canonicalization per BUS-1 14.5.

ID	Grade	Test and pass criterion
`RT-1`	MUST	Identity preservation (BUS-1 6.4). Compare the id of every entity in A with its counterpart in B. Pass: Every id in A appears unchanged in B, or B contains a bus:IdentityMapping with equivalence 'same' linking the new id to the original. No entity is silently reidentified.
`RT-2`	MUST	Object meaning (BUS-1 8). Compare type, pointKind, dataType, unit, range, enumeration, classifications and attributes for every entity. Pass: All are preserved. Unit codes are preserved without conversion, or converted with the original code recorded in provenance.
`RT-3`	MUST	Relationship graph (BUS-1 9). Construct the labeled directed graph of relationships in A and in B and test for isomorphism under the identity mapping from RT-1. Pass: The graphs are isomorphic, including predicate, direction, medium and qualifiers. Inverse-form substitution is permitted; loss of a relationship is not.
`RT-4`	MUST	Intent distinguishability (BUS-1 10). For each Objective, Target, Constraint, Schedule and SequenceReference in A, locate it in B. Pass: The receiving system can still distinguish what should happen from what is happening and what happened. Constraints retain their constraintKind and bounds; schedules retain their recurrence and exceptions.
`RT-5`	MUST	Provenance retention (BUS-1 14). Compare provenance blocks and ChangeRecords. Pass: assertedBy, assertedAt, method, source, confidence and approvals survive. The receiving system MAY add its own provenance; it MUST NOT overwrite the original.
`RT-6`	MUST	Unknown extension preservation (BUS-1 15.4). Include in A an extension namespace the receiving system does not implement, with mustUnderstand false, attached to at least one entity of each core class. Pass: Every extension value reappears in B byte-identical after canonicalization, and the namespace is still declared in B's manifest.
`RT-7`	MUST	Must-understand refusal (BUS-1 15.4). Include in A an extension with mustUnderstand true that the receiving system does not implement. Pass: The importer reports the import as incomplete and names the namespace. It MUST NOT report success, and it MUST still preserve the data.
`RT-8`	MUST	Resource integrity (BUS-1 16.5). Compare resource payloads and digests between A and B. Pass: Included resources are byte-identical and digests match. Externally referenced resources retain their URI and digest.
`RT-9`	MUST	Telemetry binding retention (BUS-1 8.6). Compare the binding object of every point. Pass: protocol, address, network and parameters are preserved verbatim, so acquisition can be re-established without rediscovery.
`RT-10`	MUST	Knowledge retention (BUS-1 8.9). Compare every KnowledgeNote and its attachment relationship. Pass: Body text, noteKind, observedAt and the appliesTo relationship survive unaltered.
`RT-11`	MUST	Lifecycle continuity (BUS-1 9.3). In A, replace an asset and record bus:replaces and bus:replacedBy. Round-trip. Pass: B retains both the superseded and the superseding entity and the replacement relationship, so history remains attributable across the change.
`RT-12`	MUST	Omission honesty (BUS-1 16.6). Compare B's completeness declaration against what B actually contains, and against A. Pass: Anything present in A but absent from B is declared in B's completeness block with a reason. Silent loss is a failure of this test even when every other test passes.
`RT-13`	SHOULD	Idempotence (BUS-1 17.5). Import B and re-export as C. Pass: C and B are identical after canonicalization. Drift between successive round trips indicates unstable identity or unstable ordering.
`RT-14`	INFO	Scale (BUS-1 16.4). Round-trip a package with at least 50000 points and 250000 relationships. Pass: Report wall-clock export time, import time and peak memory. No pass or fail threshold is set in v0.1.
`RT-15`	MUST	Binding preservation (BUS-1 13.6). Compare every binding in A with its counterpart in B: element, target, channel, direction, mapping, quality. Pass: All survive. A binding lost, repointed, or reduced to a different channel is a failure, even where the graphic still renders.
`RT-16`	MUST	Command priority is not substituted (BUS-1 13.7). Round-trip a write binding whose priority the receiving system does not natively support. Pass: The priority is re-exported unchanged and the importer reported that it could not honor it. Silent substitution is a failure even though the graphic appears identical.
`RT-17`	MUST	Quality behavior preservation (BUS-1 13.6). Compare the quality block of every binding. Pass: staleAfter, onStale, onUnavailable and onOutOfService survive unchanged.
`RT-18`	MUST	Geometry fidelity (BUS-1 13.5). Compare drawing coordinate systems, extents, layer purposes, and every element geometry and transform. Pass: Coordinates agree within one part in 10000 of the drawing extent. The coordinate system, georeference, and layer purposes are unchanged.
`RT-19`	MUST	Symbol role fallback (BUS-1 13.4). Include an element whose leaf symbol role the receiving system does not implement but whose ancestor it does. Pass: The receiver renders using the ancestor role and re-exports the original leaf role unchanged. Substituting the ancestor into the exported data is a failure.
`RT-20`	MUST	Bespoke figure preservation (BUS-1 13.4). Round-trip an element carrying a figure payload for which no symbol role applies. Pass: The figure survives byte-identical after canonicalization and is rendered substantially as given rather than replaced by a library symbol.
`RT-21`	MUST	Property definitions survive (BUS-1 7.8). Compare every property definition and every property value. Pass: Definitions survive with their meaning text intact. No property is re-exported without its definition, and no definition is silently merged with another of the same name but different meaning.
`RT-22`	MUST	Alarm configuration survives (BUS-1 11). Compare every alarm definition: limits, deadband, delays, priority, acknowledgment, shelving and routing. Pass: All survive. Routing that the receiver cannot execute is preserved and reported as unenforced, not dropped.
`RT-23`	MUST	Events survive with their subjects (BUS-1 12). Compare every event and its subject reference. Pass: Event kind, timestamps, actor, values and subject survive. An override event that loses its subject is a failure.
`RT-24`	MUST	Revision continuity (BUS-1 6.6). Compare the versioning block of every entity across the round-trip. Pass: Revision numbers are preserved or advanced, never reset. An entity re-exported at revision 1 having arrived at revision 4 is a failure.

A.4 Group IM — Importer behavior§

Target: importer.

ID	Grade	Test and pass criterion
`IM-1`	MUST	Rejects a corrupt digest (BUS-1 16.5). Present a package in which one document digest does not match. Pass: The importer refuses the package and names the failing path. Partial silent ingestion is a failure.
`IM-2`	MUST	Rejects an unknown major version (BUS-1 18.2). Present a package whose busVersion has a higher major number. Pass: The importer refuses and reports the version it supports.
`IM-3`	MUST	Accepts an unknown minor version (BUS-1 18.2). Present a package whose busVersion has the same major and a higher minor number. Pass: The importer accepts it, preserves what it does not understand, and reports which constructs it ignored.
`IM-4`	MUST	Tolerates unknown enumeration members (BUS-1 18.3). Present a package using an enumeration member added after the importer was built. Pass: The importer preserves the value and does not coerce it to a default.
`IM-5`	SHOULD	Reports a coverage summary (BUS-1 2.5). Import a valid package. Pass: The importer produces a machine-readable summary of entities ingested, entities preserved but not interpreted, and constructs not understood.
`IM-6`	MUST	Unknown symbol role degrades rather than fails (BUS-1 13.4). Present an element with a symbol role several levels deeper than the importer implements. Pass: The importer walks the dotted path upward, renders at the deepest ancestor it knows, and preserves the original role. Refusing the package or dropping the element is a failure.
`IM-7`	MUST	Reports unenforceable actuation (BUS-1 13.7). Present write bindings whose priority model, interlock, or confirmation requirement the importer cannot enforce. Pass: Each is named in the import report as unenforced. Importing them as ordinary writes without report is a failure.
`IM-8`	MUST	Refuses undefined properties (BUS-1 7.8). Present a package containing a property value whose definition is absent. Pass: The importer reports the package as invalid and names the property. Accepting it as an untyped string is a failure.

A.5 Group EX — Exporter behavior§

Target: exporter.

ID	Grade	Test and pass criterion
`EX-1`	MUST	Exports without a live vendor dependency (BUS-1 2.4). Produce a package and inspect it for references that can only be resolved by the exporting vendor. Pass: Every reference is either resolvable inside the package or is a durable external locator with a digest. No reference requires a proprietary service to interpret.
`EX-2`	MUST	Identifier stability across exports (BUS-1 6.4). Export the same building twice with no intervening change. Pass: Every entity id is identical in both exports.
`EX-3`	MUST	Identifier stability across change (BUS-1 6.4). Rename an asset, then export again. Pass: The id is unchanged and the rename appears as a ChangeRecord.
`EX-4`	MUST	Export is not narrower than operation (BUS-1 2.4). Compare the exported model against the model the system uses to operate the building. Pass: No construct the system relies on to operate is omitted without a completeness declaration naming it.
`EX-5`	SHOULD	Owner-initiated export (BUS-1 2.2). Attempt an export as an operator-role user without vendor assistance. Pass: The export completes without vendor involvement, professional services, or a support ticket.
`EX-6`	MUST	Graphics export is unaided (BUS-1 2.4). Export a floor plan and an equipment graphic as an operator-role user. Pass: Both export with geometry, roles and bindings intact, without vendor involvement or professional services. This is the test the rebuild tax is measured against.
`EX-7`	MUST	Property definitions are published, not invented per export (BUS-1 7.8). Export the same building twice and compare property definition identifiers. Pass: Definition identifiers are stable between exports. Regenerating identifiers each time defeats RT-21 and makes cross-package comparison impossible.

A.6 Reporting§

A conformance statement MUST report every applicable test by identifier with its result and MUST NOT omit failures (2.5). A statement reporting RT-12 as passed while declaring domains absent without reasons is internally inconsistent and SHOULD be treated as no statement at all.