Data Mapping - Mirobody

Overview

In Mirobody, “data mapping” is three separate concerns:

Domain mapping — a vendor maps its endpoints onto the normalized DataDomain enum so callers request data by category.
Unit normalization — free-text units are folded to canonical UCUM (shipped).
FHIR representation — the canonical resource shape everything converges on is FHIR R4 (Observation for measurements).

fetch returns the vendor’s own JSON (or FHIR JSON for FHIR-native sources); the canonical store is the embedded FHIR R4 endpoint.

1 — Domain mapping

Every fetch takes a DataDomain, and each vendor maps it onto the endpoint(s) it actually brokers:

enum class DataDomain {
    Activity, Sleep, HeartRate, Glucose,
    Nutrition, BodyMetrics, Labs, Clinical
};

A REST vendor switches on the domain to pick a path (Fitbit):

switch (d) {
    case DataDomain::Activity:    return "/1/user/" + u + "/activities/steps/date/" + s + "/" + e + ".json";
    case DataDomain::HeartRate:   return "/1/user/" + u + "/activities/heart/date/" + s + "/" + e + ".json";
    case DataDomain::Sleep:       return "/1.2/user/" + u + "/sleep/date/" + s + "/" + e + ".json";
    case DataDomain::BodyMetrics: return "/1/user/" + u + "/body/log/weight/date/" + s + "/" + e + ".json";
    default: throw VendorError("fitbit: unsupported domain (activity, heart_rate, sleep, body_metrics)");
}

A FHIR vendor maps the domain onto the FHIR Observation category token instead (the ehr SMART-on-FHIR client):

case DataDomain::HeartRate:   return "vital-signs";
case DataDomain::BodyMetrics: return "vital-signs";
case DataDomain::Glucose:     return "laboratory";
case DataDomain::Labs:        return "laboratory";
case DataDomain::Activity:    return "activity";
case DataDomain::Clinical:    return nullptr;   // unfiltered: the full observation set

A vendor throws for domains it doesn’t broker rather than returning empty — the caller learns the source’s scope.

2 — Unit normalization (UCUM)

The terminology engine in src/fhir/units/ turns a free-text “value + unit” string into a canonical UCUM unit plus the LOINC PROPERTY family that disambiguates it. Pure local computation — no DB, no embedding API.

#include "fhir/units/normalize.hpp"
#include "fhir/units/families.hpp"
using namespace mirobody::fhir::units;

normalize_unit("MG/DL");        // "mg/dL"
normalize_unit(u8"毫摩尔每升");  // "mmol/L"
normalize_unit("mmHg");         // "mm[Hg]"

ParsedQuantity q = parse_value_unit("<5.6 mg/dL");
// q.comparator == "<", q.value == 5.6, q.unit == "mg/dL"

unit_family("mmol/L");          // "SCnc"
unit_family("mg/dL");           // "MCnc"

The pipeline: NFKC-lite (full-width forms, superscripts) → symbol fold → alias lookup → annotation strip → greedy morpheme tokenize-compose. Case is preserved (UCUM is case-sensitive). Multilingual input is supported: en, zh, ja, ko, ru, de, fr, es. Covered by tests/fhir/units_test.cpp.

3 — FHIR R4 representation

The canonical store is FHIR R4 (src/fhir/). FHIR-native vendors — the generic ehr client, plus Vitalera / HealthConnect / Redox / Particle Health / Metriport-Medical — already return FHIR resources; on-device stores POST Observations. A measurement is an Observation with a normalized (UCUM) valueQuantity:

{
  "resourceType": "Observation",
  "status": "final",
  "category": [{ "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "vital-signs" }] }],
  "code": { "text": "Heart rate" },
  "valueQuantity": { "value": 72, "unit": "/min", "system": "http://unitsofmeasure.org", "code": "/min" }
}

Resources are stored per-user as generic validated JSON and served over /fhir (see Data Flow).

Mapping an indicator to a coded Observation.code (SNOMED CT / LOINC / RxNorm) — i.e. terminology resolve and the document → coded-FHIR write-back — is in progress. UCUM normalization and the RESTful FHIR store are shipped; full terminology mapping is planned (see src/fhir/README.md phases 3–4). Until then, Observation.code may carry a text rather than a resolved code. (verify)

Mapping a new source

When you add a vendor::Vendor (Provider Integration):

Decide which DataDomains the source brokers; list them in VendorInfo.domains.
In fetch, map each domain onto the source’s endpoint (REST path) or FHIR category (FHIR source); throw for unsupported domains.
Return the source’s JSON (or FHIR JSON). Don’t pre-normalize — normalization/FHIR conversion is a downstream, shared concern.
If you surface units, run them through parse_value_unit / normalize_unit so they land as UCUM.

Next steps

Provider Integration

Implement fetch and domain mapping

Data Flow

From vendor JSON to the FHIR store

File Processing

UCUM normalization for document values

Provider Testing

Verify your fetch output

​Overview

​1 — Domain mapping

​2 — Unit normalization (UCUM)

​3 — FHIR R4 representation

​Mapping a new source

​Next steps

Provider Integration

Data Flow

File Processing

Provider Testing

Overview

1 — Domain mapping

2 — Unit normalization (UCUM)

3 — FHIR R4 representation

Mapping a new source

Next steps