Clause 6 — Identity and addressing — Building Understanding Standard

6 Identity and addressing§

AGREED

Identity is the load-bearing wall of this standard. Every other guarantee — relationships, provenance, events, bindings, replacement — rests on the proposition that the thing referred to today is the thing referred to in twenty years.

6.1 Identifier form§

Every entity MUST carry an id that is an absolute URI conforming to [RFC3986]. The urn:uuid form is RECOMMENDED, and version 7 UUIDs are RECOMMENDED within it because they sort by creation time and make large packages cheaper to diff.

An implementation MAY use https URIs under a domain it controls. If it does, it MUST NOT rely on those URIs being dereferenceable: a receiving system MUST treat every identifier as an opaque string and MUST NOT attempt retrieval in order to interpret the model. An identifier that must be fetched to be understood is a dependency on the exporting vendor and defeats 2.4.

6.2 Uniqueness§

Within a package, an id MUST NOT occur more than once. Across packages describing the same building, an id MUST refer to the same entity. An exporter MUST NOT mint an identifier unique only within its own database unless the scoping is explicit in the form.

6.3 External identifiers§

An entity SHOULD carry, in externalIds, every identifier by which other systems know it. This is how a receiving system re-establishes correspondence with a CMMS, a BIM model, a controller, or a spreadsheet this standard never touches.

"externalIds": [
  { "scheme": "org.bacnet.deviceInstance", "value": "201001",
    "authority": "BACnet/IP network 2001" },
  { "scheme": "org.buildingsmart.ifc.guid", "value": "1Xh2LmQz9E8vRk3TbYpQaB" },
  { "scheme": "com.example.cmms.assetId", "value": "AST-118240",
    "authority": "Maximo PRD" }
]

An importer MUST preserve every external identifier it receives, including those whose scheme it does not recognize. They are frequently the only bridge back to a system that has since been replaced.

6.4 Stability and identity mapping§

An exporter MUST NOT change the id of an entity between exports because of an internal event: a database migration, a rename, a re-commissioning, a change of asset tag, or a change of product version. Tests EX-2 and EX-3.

IdentityMapping also carries narrower, broader, and related for cases where correspondence is real but not exact — a merge, a split, a partial match against a foreign system. These preserve the fact that a human once decided the two were connected, which is otherwise lost entirely.

6.5 Local identifiers§

An entity SHOULD carry a localId: the name the building actually goes by. AHU-1. VAV-2-01. A localId MUST be unique within a package and MUST NOT be used as a reference target. It exists because a durable identifier is unreadable, and because in thirty years the tag on the physical unit may be the only surviving link between the model and the machine.

6.6 Revision§

PROVISIONAL New in v0.2. The semantics of revision under concurrent editing are not yet specified.

An entity SHOULD carry a versioning block with a revision that increases monotonically with each change to that entity. Revision supports synchronization and merge, which history alone does not: a receiving system can determine whether the copy it holds is behind the one it has been sent without comparing every field.

An importer MUST preserve or advance a revision. It MUST NOT reset one. An entity re-exported at revision 1 having arrived at revision 4 is a conformance failure (test RT-24), because it asserts that three changes never happened.

"versioning": {
  "revision": 4,
  "schemaVersion": "0.2",
  "effectiveFrom": "2009-09-14T00:00:00-05:00"
}

6.6.1 Single-writer assumption§

This version assumes a single authoritative writer for any given entity at a point in time. An exporter that receives concurrent updates from multiple systems MUST do one of two things: serialize them under a single writer and advance revision monotonically, or emit distinct packages with distinct packageIds and record the succession under 16.9. Doing neither — advancing one revision counter under two authorities — produces a package whose revision numbers assert an ordering nobody enforced, and is a conformance failure (test EX-11).

A future MINOR version is expected to define a minimal multi-writer merge rule: identity mapping for structural divergence, and last-writer-wins or an explicit ChangeRecord for property divergence. Until that rule is published, an implementer holding concurrent writes SHOULD treat them as requiring a new packageId. The assumption is stated here rather than left implicit so that an implementer who correctly assumes single-writer today does not discover the boundary by crossing it.

Promotion criterion — at least two independent implementations report successful round-trip of revision under concurrent package exchange, or the multi-writer merge rule is ratified.