FHIR R4 export

Open Health Sync serves a user's records as FHIR R4 (4.0.1) Observations, so a FHIR client, an EHR integration or a research pipeline can read them without learning the REST JSON shapes: quantity samples (heart rate, steps, weight, SpO2...), blood pressure readings, sleep sessions, workouts and daily summaries. The user is served as a Patient, the devices the records came from as Devices, and who produced each Observation as its Provenance; $everything pages through all of them in one Bundle. The output is checked against the specification with the official HL7 validator, in CI (see Validation).

Category samples, nutrition, sleep phases, routes and the other resources are not in this version.

RoutesCopy Anchor Link

Every route takes a tenant key, like every read, and answers Content-Type: application/fhir+json. The Observation reads read the merged view by default (view=merged, see api.md): a record that a better ranked source covers is left out, and a daily summary carries only the figures no better ranked source of that day holds (a summary left with none is left out). view=all serves every stored record as is. A user of another tenant, a Patient id other than the user's, or a resource that is not the user's, is a 404. Errors are application/problem+json like the rest of the API (not an OperationOutcome).

One list for every kind of recordCopy Anchor Link

The search returns every kind of record in one list, so a client gets everything with one paged search. Observations come in time order, then by kind (quantity sample, sleep session, workout, daily summary), then by id:

The cursor in the next link is the last Observation's time, kind and id, so a page never skips or repeats one even when records of different kinds share a time. A REST list cursor is not a valid FHIR cursor (400). The merged list is read in two steps: one query takes the ids of the page from the four tables (each branch ordered and limited on its own index, then merged), a second reads those rows.

The search takes these parameters, all optional. They combine: an Observation is listed when it matches every one given.

Any other parameter is a 400 rather than being ignored, so a client never takes the whole list for a filtered one: use start and end where FHIR has date, and limit where it has _count. _format is accepted when it asks for JSON (json, application/json or application/fhir+json), the only format served.

The Bundle has a self link and, unless this is the last page, a next link that carries the cursor: follow next until there is none. total is left out (the API never counts). Links and fullUrl start with OHS_PUBLIC_URL, so set it to the address clients use.

curl -s "$OHS/v1/users/$USER_ID/fhir/Observation?code=http://loinc.org%7C8867-4&start=2026-03-01&limit=2" \
  -H "Authorization: Bearer $KEY"

{
  "resourceType": "Bundle",
  "type": "searchset",
  "link": [
    { "relation": "self", "url": "https://ohs.example.org/v1/users/3f0c.../fhir/Observation?code=...&limit=2" },
    { "relation": "next", "url": "https://ohs.example.org/v1/users/3f0c.../fhir/Observation?code=...&cursor=MjAy...&limit=2" }
  ],
  "entry": [
    {
      "fullUrl": "https://ohs.example.org/v1/users/3f0c.../fhir/Observation/qs-1001",
      "resource": {
        "resourceType": "Observation",
        "id": "qs-1001",
        "meta": {
          "source": "https://github.com/soma-intelligence/open-health-sync/fhir/provider/apple_health",
          "profile": [
            "http://hl7.org/fhir/StructureDefinition/vitalsigns",
            "http://hl7.org/fhir/StructureDefinition/heartrate"
          ],
          "tag": [{ "system": "https://github.com/soma-intelligence/open-health-sync/fhir/CodeSystem/source", "code": "apple" }]
        },
        "status": "final",
        "category": [{
          "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "vital-signs", "display": "Vital Signs" }],
          "text": "Vital Signs"
        }],
        "code": {
          "coding": [
            { "system": "http://loinc.org", "code": "8867-4" },
            { "system": "https://github.com/soma-intelligence/open-health-sync/fhir/CodeSystem/quantity-type", "code": "heart_rate" }
          ],
          "text": "heart rate"
        },
        "subject": { "reference": "Patient/3f0c2f8e-8b8a-4c55-9f5e-2b0f3a1d9c11" },
        "effectiveDateTime": "2026-03-01T08:00:00Z",
        "issued": "2026-03-01T09:15:30.25Z",
        "valueQuantity": { "value": 61, "unit": "bpm", "system": "http://unitsofmeasure.org", "code": "/min" },
        "device": { "reference": "Device/dev-4cd59d3e7b09cd28", "display": "apple_watch" }
      },
      "search": { "mode": "match" }
    }
  ]
}

The complete outputs for every case below are the golden files in internal/fhir/testdata.

MappingCopy Anchor Link

Every Observation shares these elements; the sections below give what each kind of record adds.

metadata and the other provider fields of the REST records are not mapped.

Quantity samplesCopy Anchor Link

One stored quantity sample is one Observation, except the blood pressure halves that are paired into a panel.

A quantity type without a LOINC code (VO2 max, body fat mass, the provider indices, a name a connector emits that the catalog does not declare yet...) is still served, coded with the quantity type system alone: leaving it out would make the FHIR view silently smaller than the REST one, and a client can always filter on the codes it knows.

CategoriesCopy Anchor Link

category uses the HL7 observation category codes. It is left out when none of them describes the measurement, rather than set to a wrong one.

Glucose from a CGMCopy Anchor Link

The catalog codes blood_glucose with LOINC 2339-0, glucose in blood. A continuous glucose monitor measures the fluid under the skin instead, so a glucose sample whose metadata.specimen is interstitial_fluid (every Dexcom reading, and Health Connect readings with that specimen source) is coded with LOINC 99504-3, glucose in interstitial fluid, the code the HL7 CGM implementation guide uses. A code search for 2339-0 finds both kinds, through the catalog; a search for 99504-3 finds nothing yet.

Vital signsCopy Anchor Link

R4 requires an Observation that carries one of its vital signs LOINC codes to meet the matching profile. The mapping does, and names the profiles in meta.profile.

Every profiled Observation also names the base vitalsigns profile. A profile is claimed only when the catalog gives the type the code above and the value is in a unit the profile accepts.

Blood pressureCopy Anchor Link

Systolic and diastolic pressure are stored as two samples, and R4 allows their LOINC codes (8480-6, 8462-4) only as the two components of one blood pressure panel (85354-9). So a systolic and a diastolic sample of the same reading become one panel Observation:

• Pairing. The two samples pair when they share user, provider, start, end, source and device (an unknown end, source or device matches only an unknown one). When several samples of one type share that key (a duplicate reading), the one with the lowest id pairs and the others stay single, so a sample is in at most one pair and the pairing does not depend on the page or the filters.
• The panel. id is bp- and the systolic sample's id. code is LOINC 85354-9 and the record type blood_pressure; there is no valueQuantity; component holds the systolic value (LOINC 8480-6, then the quantity type) and the diastolic value (8462-4), each in mm[Hg], or a dataAbsentReason when it is NaN or infinite. effective, device and meta come from the systolic sample, identifier lists both samples' external ids, and issued is the later of the two. It meets the vitalsigns and bp profiles.
• Paging. The pairing is done in SQL: the diastolic half of a pair is never listed on its own, and the panel is listed at the systolic sample's place, so a pair is never split across pages or listed twice. qs- and either half's id is a 404; so is bp- and the id of a sample that is not the systolic half of a pair.
• Unpaired halves stay as before: their own Observation in the vital-signs category, coded with the quantity type system only (no LOINC code, no profile).
• A half in a unit other than mm[Hg] keeps its value, but the panel then carries neither 85354-9 nor a profile (the profile requires mm[Hg]). The storage unit is mmHg, so this does not happen with data the connectors write today.

Sleep sessionsCopy Anchor Link

One sleep session is one Observation of its total sleep duration.

Every component code also carries the field name in the component code system. The stage durations carry no LOINC code: LOINC's sleep stage codes were not checked against a terminology server, and a wrong code is worse than none. Sleep phases are not mapped.

WorkoutsCopy Anchor Link

One workout is one Observation of its duration.

Daily summariesCopy Anchor Link

One daily summary is one Observation with each metric the provider gave as a component (one Observation per day rather than per metric keeps one id per row and one place in the list).

A code search matches Observation.code only, so code=http://loinc.org|41950-7 does not find daily summaries; use code=.../CodeSystem/record-type|daily_summary.

UnitsCopy Anchor Link

valueQuantity.code is UCUM. For a quantity sample it is the catalog's UCUM unit when the type has one, else the spelling of the storage unit below; a unit outside this table (a type the catalog does not declare) is kept in unit with no system or code. The components of sleep sessions, workouts and daily summaries use the units of their tables above.

A count, index or score is dimensionless: its UCUM code is an annotation, which means 1, and unit repeats the annotation's word ({steps} reads steps). Values are the stored ones, in the storage unit: nothing is converted on the way out (durations stay in seconds).

PatientCopy Anchor Link

GET /v1/users/{id}/fhir/Patient/{id} serves the user, and the subject of every Observation points to it. Open Health Sync stores no name, birth date or other demographics, so the Patient holds only what it does store:

DevicesCopy Anchor Link

A Device is one device the user's records came from, as their provenance names it. Its identity is five stored fields: the provider, the source (source_slug), and the device fields of the record: device_id, and for a quantity sample device_model and product_type (sleep sessions and workouts keep device_id only; daily summaries keep none). A record with no device id, model or product type names no Device. Two records with the same five fields name the same Device, whatever their kind.

The id is computed from the record's own fields, so an Observation references its Device with no extra query. GET /fhir/Device reads the five fields of the user's quantity samples, sleep sessions and workouts whose time is in [start, end) (both optional, as for Observations), each device once, in one page with no next link: a user has a handful of devices. It reads the (tenant_id, user_id, time) index of each table, so a window reads only the chunks it covers; with no window it reads the device fields of every record of the user once, which on years of minute-level samples takes seconds. Pass start and end on a large history, or use $everything, which gives the Devices of each page from the rows it already reads. cursor and limit are a 400. GET /fhir/Device/{device_id} makes the same read with no window, then answers the Device of that id (404 when none of the user's records names it).

ProvenanceCopy Anchor Link

Each Observation has one Provenance: who and what produced it.

The agent types are codes of the HL7 provenance participant type system. The vendor that produced the record is not an agent of its own: it is the meta.tag of the Observation and of the Device. The raw upload or provider response a record was read from is not linked: the stored records do not keep its key.

GET /fhir/Provenance takes one target, Observation/ and an Observation id, and answers a Bundle with its Provenance, or no entry when the user has no such Observation. Without target, or with another resource type, it is a 400. GET /fhir/Provenance/{provenance_id} reads one; the Provenance of an Observation that does not exist is a 404.

$everythingCopy Anchor Link

GET /v1/users/{id}/fhir/Patient/{id}/$everything is a searchset Bundle of the Patient and all their resources, paged like the Observation search: follow next until there is none.

The entries come in that order. limit counts the Observations, and the cursor in the next link is the Observation search's, so no Observation is skipped or repeated and every reference of a page resolves to an entry of the same page, except Patient/{user id} on the later pages, which the first page holds. start and end bound the Observations only. The Devices and the Provenance are made from the rows of the page: $everything costs the Observation search's two queries and a read of the user. type, code and category are not taken (type is a 400); the FHIR _since, _type and _count parameters are not supported.

CapabilityStatementCopy Anchor Link

GET /v1/users/{id}/fhir/metadata describes these routes as a CapabilityStatement of kind instance, for the user's FHIR base (implementation.url): read and search-type on Observation, Device and Provenance with their parameters, read and the everything operation on Patient. It needs a tenant key like every route.

Identifiers Open Health Sync definesCopy Anchor Link

Every URI below starts with https://github.com/soma-intelligence/open-health-sync/fhir. They are identifiers, documented here; nothing is served at them.

No custom extension is used, so a validator needs nothing beyond the R4 specification.

ValidationCopy Anchor Link

Each mapping case has a golden file in internal/fhir/testdata: a profiled vital sign of each kind, resting heart rate, an unpaired systolic sample, a blood pressure panel, an interval, a laboratory value, a type without LOINC code, a type and unit outside the catalog, a NaN value, a sleep session, a workout, a daily summary on a daylight saving day, searchset Bundles (vital signs, every kind of record, empty), a Patient with and without identifier, a Device with every field and one with a model only, the Provenance of a sample, of a blood pressure panel and of a daily summary (no device), the Device and Provenance searchsets, a first and a last $everything page, and the CapabilityStatement. go test ./internal/fhir compares the mapping with them (-update rewrites them), and checks they hold no empty array, object or string, which FHIR JSON forbids. The contract tests check the same files against api/openapi.yaml, each against the route that answers it.

make fhir-validate (scripts/fhir-validate.sh) runs the official HL7 validator on the golden files with -version 4.0.1. It needs Java 17 or later and the network. CI runs it (.github/workflows/fhir-validate.yml, Java 21) on every pull request and push to main that changes internal/fhir, the script or the workflow, and fails on any error. The warnings left are expected:

• no narrative (dom-6) and no performer: both best practice, neither required;
• a reference to a resource the file does not hold (the Device/ of a single Observation, the Patient/ of a Bundle page that is not the first) cannot be resolved;
• the Open Health Sync code systems are not published, so their codes cannot be checked;
• a UCUM annotation such as {steps} is flagged as best practice to review.

Run offline (FHIR_VALIDATOR_TX=n/a), the validator also says it cannot check the UCUM and LOINC codes; with the default terminology server it checks them.

Not in this versionCopy Anchor Link

Planned, in no fixed order:

• Category samples, nutrition, sleep phases and workout routes as FHIR resources, and the devices of those records.
• Patient demographics (none are stored), a Patient search, and an Organization for each provider (the Provenance names it by identifier only).
• A Provenance entity for the raw upload or provider response a record was read from.
• Bulk export ($export), OperationOutcome errors, the FHIR date, component-code, _count, _since, _type, _include and _revinclude parameters, and access with a user token.
• Open mHealth schemas.