13 Portable presentation§

AGREED The layering, the role-and-library mechanism, and the binding model are settled. The neutral vector format used by figure mode is specified in v0.3 as a closed profile of SVG; see 13.4.3.

Owners pay substantial sums to create floor plans, equipment graphics, point bindings, and navigation structures. Those assets describe the building and embody real engineering labor. At present they are rebuilt at every migration, and the rebuild is among the largest single costs an owner incurs in changing platforms.

The evidence that this is structural rather than incidental is set out in 20.4. In short: no standard anywhere defines operator graphics with live bindings; the one vendor format published as a specification keeps its bindings in a database rather than in the file; vendors’ own conversion utilities drop dynamics and require manual rebinding; and the third-party graphics industry is organized by platform with no conversion service between them.

13.1 The four layers of a graphic§

The reason this has never been standardized is that a graphic is treated as one thing. It is four, and the ownership line falls cleanly between the third and the fourth.

This standard specifies the first three layers and says nothing whatever about the fourth. A conforming receiving system is free to render a package in a visual language entirely unlike the one it came from, and remains conforming.

13.2 Drawings§

A bus:Drawing is a page: a floor plan, site plan, equipment graphic, schematic, one-line, riser, detail, or dashboard. It carries a coordinate system, an extent, an OPTIONAL nominal scale and reference dimension, and an OPTIONAL subject naming the space or asset it is of.

A drawing MUST contain at least one element. Layers and elements name their drawing; an element’s layer MUST belong to the same drawing as the element (test PK-14).

13.2.1 Layers§

A bus:Layer carries a declared purpose: background, architecture, structure, spaces, equipment, ductwork, piping, electrical, controls, annotation, or navigation.

Purpose is declared rather than left to naming convention so that a receiving system can drop the architectural context and keep the semantic content — which is what a system that already has its own base plan needs to do, and what a system rebuilding a plan from scratch cannot do at all today.

13.3 Coordinate systems and georeferencing§

A drawing MUST declare its coordinate system: the length unit code its coordinates are expressed in, the direction of increasing y, and an OPTIONAL origin.

A drawing of physical space SHOULD carry a georeference: a latitude and longitude, the drawing coordinate they correspond to, a rotation from true north, an OPTIONAL elevation, and an OPTIONAL coordinate reference system identifier per [ISO19111].

"coordinateSystem": {
  "unitCode": "m", "yAxis": "up", "origin": { "x": 0.0, "y": 0.0 },
  "georeference": {
    "latitude": 30.267105, "longitude": -97.723940,
    "atX": 0.0, "atY": 0.0, "rotation": 14.5,
    "elevation": { "value": 4.2, "unit": "m" }, "crs": "EPSG:4326" }
}

Georeferencing matters more than it appears to. An anchored plan survives into any CAD, BIM, or GIS tool indefinitely, and two plans produced by different vendors at different times will register against each other without manual alignment. An unanchored plan is a picture whose relationship to the world has to be re-established by hand every time it is reused.

New in this version, and additive: a georeference MAY also carry a precomputed `affine` — six numbers mapping drawing coordinates directly into the named CRS. The anchor form above, plus the drawing unit, already places a true-scale plan completely; the affine exists for the two cases the anchor form cannot express — the scale error of a scanned or traced plan, and shear — and for consumers that apply a transform rather than derive one, which is every GIS and every object store. Where both forms are present they MUST describe the same placement within the RT-18 tolerance, and a transform whose linear part is singular is a package error (test PK-27): two permitted encodings of one fact are tolerable only while the package proves they are the same fact.

A drawing SHOULD also carry a referenceDimension: a known real-world distance between two drawing coordinates. This makes a scale error detectable rather than silent, which matters because a plan imported at the wrong scale looks entirely correct until someone measures something (test PK-17).

13.4 Elements and symbol roles§

A bus:Element is a placed thing. It names its drawing and layer, and carries a transform, an OPTIONAL z-order and group, an OPTIONAL label, and an OPTIONAL represents naming the building entity it depicts.

An element MUST carry at least one of a role, a figure, or a geometry.

13.4.1 Role mode§

In role mode the package states that at a location, rotated, on a layer, there is an element of a declared symbol role. The receiving system supplies the artwork.

{ "type": "bus:Element",
  "localId": "AHU-SF",
  "drawing": "urn:uuid:...602", "layer": "urn:uuid:...617",
  "role": "fan.centrifugal.supply",
  "represents": "urn:uuid:...051",
  "transform": { "x": 1120, "y": 380, "rotation": 0 },
  "zOrder": 5 }

This is what preserves the owner’s survey, placement, and bindings in full while leaving the vendor’s design system entirely untouched. Vendor A draws a flat icon; Vendor B draws a rendered one; both are conforming, and neither has been asked to adopt the other’s visual language.

NOTE The mechanism is not speculative. IEC 61970-453, the CIM Diagram Layout Profile, exchanges power-system diagram layout with links to modeled objects and explicitly leaves the symbol library to the receiver. It has been in production use for over a decade.

13.4.2 Role fallback§

A symbol role is a hierarchical dotted path. Roles degrade by truncation: fan.centrifugal.supply to fan.centrifugal to fan.

This is what allows the vocabulary to grow indefinitely without breaking deployed importers, and it is the same property that abstract types give the entity model (8.2). Annex B defines the first tier: 52 roots with 75 named leaves.

13.4.3 Figure mode and bus-vector-1§

PROVISIONAL New in v0.3. v0.2 named the format and did not define it. The profile below is defined; the element list is where review is most wanted.

Promotion criterion — a graphics-bearing package using figure mode and dictionaries passes the full RT suite between two independent implementations.

Sometimes the owner paid for the artwork itself: a bespoke plant schematic, a one-line an engineer drew, a symbol no vocabulary contains. In figure mode an element carries a neutral vector payload, inline or as a resource, that a receiver MUST render substantially as given rather than replacing it with a library symbol (test RT-20).

An element MAY carry both a role and a figure. Where it does, the role is a hint for receivers that prefer their own library and the figure is the fallback. An exporter SHOULD prefer role mode where a role fits, because role mode is what lets the receiving vendor apply its own design system.

bus-vector-1 is a closed profile of SVG 1.1 Second Edition, Static processing mode. It is not a new format, and a new format was rejected: there is no second implementer to share the cost of one, no tooling for one, and no prior art to draw on — neither Project Haystack nor Brick has any vector, drawing, symbol or figure construct of any kind. Every plausible receiver already has an SVG parser. What this version adds is the constraint list that makes the security requirement of 19.3 true by construction rather than by vigilance.

Naming the format and not defining it was worse than either alternative. A package using figure mode was portable only between implementations that had privately agreed what the payload was, which is to say between none; and 19.3’s requirement that a receiver not execute script, resolve external references, or fetch remote content had no format to attach itself to.

A figure MUST use only these 15 elements: svg, g, defs, title, desc, use, path, rect, circle, ellipse, line, polyline, polygon, text, tspan.

The 16 elements below are forbidden. The reasons are not stylistic and are worth reading, because each one is a rule this document states elsewhere arriving in a new place.

script and foreignObject are excluded because 19.3 forbids a figure from executing anything or escaping into a document; a neutral vector payload is data, not a program. style is excluded because a receiver must be able to strip appearance and keep shape without parsing a stylesheet, which is the whole basis on which a figure is owner property under 13.1. filter, mask and clipPath claim to be appearance and change the geometry a receiver reads, so a receiver that stripped appearance would silently change the drawing.

VEC-5 is what gives 19.3’s requirement that a receiver bound the size of an inline figure payload a number to bound against: 16 levels of nesting and 4096 elements. A constraint graded SHOULD is a recommendation and nothing more: a figure that does not satisfy one is a valid figure, and an importer MUST NOT refuse it.

v0.2 named two format tokens, bus-vector-1 and svg-profile-1, for one thing that neither of them defined. Two undefined names for one undefined format is worse than one, so they are collapsed. bus-vector-1 is the name of the profile. A receiver MUST accept svg-profile-1 as an alias for one MINOR version; an exporter MUST NOT write it.

That definition is load-bearing, and it is why this clause needed a version of its own. Read loosely, 13.4.3 and 13.9 contradict each other: one requires a receiver to render a figure faithfully, the other says appearance belongs entirely to the vendor and that no conforming package carries a color at all. An implementer reading both in good faith could not tell which obligation won.

A figure is portable shape, not portable artwork. Both clauses stand once substantially means shape. The owner who paid a draftsman for a plant schematic gets the schematic back, with its geometry and its structure intact. They do not get the receiving vendor’s palette overruled, and they were never entitled to.

13.5 Geometry§

An element MAY carry geometry: a point, polyline, polygon, rectangle, circle, arc, or path, expressed as a flat array of alternating x and y values in drawing units, with OPTIONAL holes for polygons.

The single most valuable use of geometry is a space boundary polygon carrying the identifier of the space it bounds. That is what turns a plan from a picture into a view of the model: every downstream capability — coloring a floor plan by temperature, locating an alarm, computing an area, finding which zone a complaint came from — depends on it, and none of it is possible from a drawing file.

{ "type": "bus:Element", "localId": "L2-SP-201",
  "layer": "<spaces layer>", "represents": "<Open Office 201>",
  "geometry": { "kind": "polygon", "closed": true,
                "coordinates": [2, 18, 34, 18, 34, 32, 2, 32] } }

Geometry fidelity is tested to one part in ten thousand of the drawing extent (test RT-18), which is tighter than any plausible rendering difference and looser than floating-point representation noise.

13.6 Bindings§

A bus:Binding declares that an element is driven by, or writes to, a building entity. Both endpoints are intrinsic to it, exactly as a relationship names its subject and object, and no separate relationship is created.

NOTE This is a deliberate departure from 5.3.2. A binding carries a value-mapping table, which is more structure than relationship qualifiers should hold; and naming endpoints intrinsically avoids generating eight thousand relationship entities for a plan with four thousand bindings. Making it an entity rather than a property means bindings carry provenance and revision, so the fact that an element was repointed in 2019 becomes visible — bindings drift constantly and at present nobody can prove it.

13.6.1 Channels§

A binding names a channel: the aspect of the element the value drives. The vocabulary is closed and may be extended only by a MINOR version.

A channel names an intent, never an appearance. fill selects among named states; it does not carry #FF0000. This is what keeps the binding on the owner’s side of the boundary and the rendering on the vendor’s.

13.6.2 Mapping§

A binding MAY carry a mapping translating source values into element states: discrete states for enumerated targets, numeric ranges, and a scale, offset, format, and displayUnitCode. A displayUnitCode is a code from the Annex C vocabulary, exactly as unitCode is; a receiver formats the value, it does not invent a unit notation.

"mapping": { "ranges": [
  { "max": 20.0, "select": "cold", "label": "Below band" },
  { "min": 20.0, "max": 24.5, "select": "ok", "label": "In band" },
  { "min": 24.5, "select": "hot", "label": "Above band" } ] }

Where the target is an enumerated point, every when value in a state mapping SHOULD correspond to a member of the target’s enumeration. A mapping referring to a state the point cannot take is a modeling error and SHOULD be reported by a validator.

13.6.3 Quality behavior§

A binding SHOULD declare what the element does when its value is stale, unavailable, or out of service: a staleAfter interval and an action of indicate, gray, hide, hold, show a question mark, or show the last good value.

This is the field implementers are most likely to consider cosmetic and is not. A graphic that displays the last good value indefinitely, rather than graying out, tells an operator that a dead sensor is reading normally. That is a safety failure, and the decision about which behavior applies was made by an engineer who is unlikely to still be available.

13.7 Actuation§

AGREED Command actions travel. The consequence is a materially sharper security posture; see 19.2.

A binding whose direction is write or readWrite carries a write block. The ability to act on plant from a graphic is engineered, owner-funded behavior and meets the boundary test; excluding it would mean every migration rebuilds the command layer by hand, which is the most safety-critical part to rebuild.

"direction": "readWrite",
"write": {
  "priority": 10,
  "requiresConfirmation": true,
  "confirmationText": "Change the AHU-1 supply air temperature setpoint?",
  "constraintRef": "urn:uuid:...203",       // the safety low limit
  "releaseOnExit": false
}

13.7.1 Priority§

If a source binding writes at priority 8 and a receiver writes at priority 16, the graphic looks identical and the plant behaves differently. Nobody discovers this until an override fails to hold, typically during an incident. This is the presentation-layer analog of the unit-conversion rule of 7.4.

A declared priority MUST be within the target point’s declared priority model where one exists (test PK-16).

13.7.2 Limits and interlocks§

A write binding that restricts the permitted value range MUST reference a bus:Constraint through constraintRef rather than carrying its own minimum and maximum. Two places to state the same limit guarantees they diverge, and the graphic is the copy that gets edited without the model being updated.

An interlockRef names a constraint that must hold before the write is permitted — a fan that may not start while a fire alarm is active, for instance. Interlocks that the receiver cannot enforce MUST be reported, not assumed satisfied (10.4).

13.7.3 Confirmation§

requiresConfirmation records that an operator must confirm before the write is issued. The requirement travels; the design of the confirmation dialog does not. The same boundary test that gives the vendor the dialog gives the owner the requirement, because the decision that this particular action needs a second thought was an operator-safety judgment.

13.8 Navigation§

An element MAY carry navigatesTo naming another drawing. This preserves the structure by which an operator moves from a floor plan to an equipment graphic — which is engineered information architecture, not menu design.

How navigation is presented, whether as a click, a hover, a breadcrumb, or a search result, is entirely the receiving vendor’s.

13.9 What presentation does not carry§

For the avoidance of doubt, nothing in this clause constrains, and no conforming package carries:

• Colors, gradients, shadows, textures, or any other appearance value.
• Symbol artwork, except in figure mode where the owner funded the artwork itself.
• Animation curves, easing, timing, or transitions.
• Fonts, type sizes, or text styling.
• Hover, focus, selection, or gesture behavior.
• Responsive breakpoints, layout adaptation, or device-specific presentation.
• Menu structure, search, personalization, or role-based presentation.

A receiving system that renders a package in an entirely different visual idiom, with different symbols, different colors, and different interaction, is fully conforming. That is the intended outcome, not a tolerated one.