Skip to content

ADR-0032 — Culture-neutral address representation: the three-facet address value

  • Status: Accepted
  • Date: 2026-06-27
  • Refines: ADR-0014

Context

Demographic data shape varies enormously by nation, legislation, and culture — name models, address structure, and identifier systems all differ. Cairn is international and anti-capture: the infrastructure must carry any demographic representation while the UI localises presentation to the operator's context. The same record must work for a clinician in a refugee camp and one in a metropolitan hospital, and neither may emit something the other cannot read (principle 12, uniform core / plural edges).

The characteristic failure of single-jurisdiction designs is to weld one culture's address structure into the schema — street/town/postcode columns, a fixed town lookup — so supporting another jurisdiction means a schema migration. That is the same mistake as encoding national identifier types as columns: it forces a lockstep, per-jurisdiction change and violates additive-only evolution (ADR-0012 / principle 11).

Demographics §4 already models names richly (multi-valued set + transliteration + per-assertion comparator profile, ADR-0014) and identifiers as a keyed set, but treated address thinly — "volatile; recency wins; nearly meaningless for matching." That is a matching statement, not a representation one. The address value shape is a can't-retrofit, day-one decision (like the ADR-0013 attachment-reference shape): once records carry a shape, changing it is a migration across the whole record. So it is fixed now.

Decision

An address is asserted through the existing §4.1 mechanism; the value is a three-facet structure, only the first mandatory:

  1. display (mandatory) — the human-readable address, the principle 11 legibility twin. Always sufficient on its own. Derived from the structured parts via the profile's formatter when structured parts are present (so it cannot drift); authored verbatim when they are absent; materialised into the signed event at authoring time so a node lacking the profile still has correct display text.
  2. geo (optional) — a first-class geolocation (lat, lon, accuracy_m, basis), precision-aware (principle 4 applied to space). The culture-neutral universal locator, often the only viable address in informal-settlement / refugee / disaster / remote contexts.
  3. structured (optional) — an open ordered bag of named parts plus a content-addressed locale profile (namespace@hash) that defines the parts, their order, the formatter, advisory validators, and the ADR-0014 matcher comparator. The profile reference travels per-assertion as signed data; the profile code travels the security §7.6 distribution plane. One locale bundle per culture carries comparator + grammar + formatter + validators — not two parallel systems.

There are no canonical part names in the wire model — parts keys are interpreted by the profile, never by Cairn core; parts values are opaque text to the core. Country is a part, not a privileged column (stateless / disputed-territory / cross-border cases). Validation is advisory per profile, flagging for human review, never rejecting (principle 4); the in-DB floor enforces only the culture-neutral structural invariants (display non-empty; structured ⇒ profile present; parts are text) and never holds a profile (principle 12). Multiple scripts/transliterations are multiple assertions, each with its own profile+display. A clinic that needs structured addresses enforces it as soft policy in its UI (ADR-0021) — a bespoke UI can demand structure but can never emit a wire-incompatible address.

Profile assignment follows ADR-0014 verbatim: defaults silently from the registering node's locale, registrar-overridable, per-assertion. When a node lacks a record's profile it degrades honestly — display and geo still work, parts show as opaque labelled strings (never reinterpreted under a substitute profile), matching goes to human review.

Consequences

  • Easier: any jurisdiction is supported with no schema migration (parts + profile are data); the refugee-camp and low-infrastructure cases work via geo and/or freeform display; address history is intact (append-only; "moved out" is an explicit superseding assertion, not a flag); FHIR address mapping stays in the interop façade (§9.7), out of the wire model.
  • Harder / the bet: moving structure to data trades away DB-guaranteed format validation and uniqueness (recovered as advisory per-profile validators). Cross-facet consistency (display == formatter(parts)) is not floor-gated — to keep the floor culture-neutral — so a buggy/hostile authoring node could sign an inconsistent display; this is detectable (any profile-holding node recomputes and flags it) and is not silent record corruption (both facets signed, immutable, attributable), surfaced for human review per "flag, never auto-resolve." We are betting (as in ADR-0014) that content-addressed profiles distribute reliably off the clinical plane.
  • How we'd know the bet fails: addresses arrive that no available profile can format; clinicians are forced into a wrong structure (should be impossible — display/freeform is always available); or display-vs-parts drift goes undetected at scale (watch the advisory consistency-flag yield).