All Blogs
Health Connect medical records: FHIR needs provenance as well as permission
Health Connect Medical Records uses FHIR R4 and R4B. A developer guide to experimental APIs, permissions, provenance and record reconciliation.
One person can have several patient records. Two organisations can assign the same ID to entirely different observations. A field can contain valid JSON and still make a very unhelpful addition to a health timeline.
These are the details that make Android's Health Connect Medical Records feature interesting. It gives applications a way to read and write basic medical data in Fast Healthcare Interoperability Resources (FHIR) format, with user controls over access. The capability is already documented, rather than a new October launch. Medical Records overview.
Health Connect Medical Records remains experimental. Google's APIs carry the ExperimentalPersonalHealthRecordApi annotation and are subject to change. Play distribution requirements are still developing, and changelog-based APIs are not available yet. The current guide uses Jetpack Health Connect 1.1.0-beta02 and requires compiling against the Android 16 SDK. Those are practical boundaries for a team choosing a production dependency. Current API limitations and setup.
For a developer already working with wearable data, the opportunity is to bring more context into a product. The challenge is to preserve what that context actually means.
A supported device and a willing user come first
Google's reading guide requires a feature-availability check using FEATURE_PERSONAL_HEALTH_RECORD. It documents separate read permissions for categories including laboratory results, medications, conditions, and vital signs. Apps need to check granted permissions before use and handle revocation. Read medical data.
Design the experience around partial access from the beginning. Someone may want to share laboratory results and keep other categories private. The app should explain what remains useful with the available record, rather than treating every missing permission as an onboarding defect.
A permission allows an operation. It is poor evidence that the person wants every possible use of the resulting information.
Preserve the source before reconciling it
Health Connect groups medical records into MedicalDataSource objects. Google advises separate sources for unreconciled records from different systems; combining them requires reconciliation and unique resource-type and ID combinations. Resources are written through upsert operations. Write medical data.
Keep the original source identity intact and maintain a separate reconciliation layer. If two incoming observations appear to describe the same test, retain enough evidence to explain why they were matched. Do not merge them simply because their display labels are similar.
A useful review screen should let someone move from the normalised view back to the source record. This is particularly valuable when a correction arrives or a mapping turns out to have been mistaken. You want to revise a decision, not reconstruct an entire import.
FHIR gives the record structure
Google documents support for FHIR R4 and R4B and a defined set of resources. Observation records are categorised using their content, including codes and FHIR categories; observations outside the supported categories are not written. Google also recommends retaining the original record source in meta.source. Data format documentation.
Those rules belong in the ingestion design. Track accepted, rejected, and unsupported records explicitly. A successful request should not become a cheerful assertion that the person's entire medical history is now present.
The next layer is your product's meaning. A clinical observation and a wearable-derived metric may both look like measurements, but their context can be very different. Source, collection time, units, and measurement method should travel with the value. The product can then decide which comparisons are appropriate instead of assuming that a shared label makes two records interchangeable.
Build the small view you can explain
An initial feature could show selected clinical observations beside a wearable history, with explicit dates and links back to their sources. Keep the first version narrow enough that the team can inspect every transformation involved.
Test the unpleasant cases: duplicate-looking records, changed results, conflicting units, missing timestamps, unavailable features, and permissions withdrawn halfway through a session. A parser that accepts every happy-path sample has only demonstrated excellent manners.
For teams already collecting wearable data, Terra's mobile SDK reference documents a Health Connect connection. It does not establish support for the experimental medical-record APIs; verify the specific resource and access path before combining that data with the wearable feed.
The payoff is a view a person can trust. They can see what the product has, where it came from, and why it appears on the timeline. They can also see what is missing.
FHIR makes exchange possible. Careful reconciliation makes a combined record understandable. We have a soft spot for that second part: the patient rarely applauds a tidy data model, but they will notice when an old result stops masquerading as a new one.
