Personal Health Records

The Health Connect platform provides a range of data types, mostly covering wellness and fitness use cases, enabling apps in the Android ecosystem to share data without the need for high-cost one-to-one API integrations. Personal Health Records (PHR) extends this capability to include basic medical data in Fast Healthcare Interoperability Resources (FHIR®) format, including:

  • An API for applications writing medical data.
  • A user-facing browser experience for medical data stored in Health Connect as new medical data types, along with fine-grained permissions for allowing downstream reads.
  • An API for applications reading medical data based on user-granted permissions.
An overview of how Personal Health Records work with Health Connect.
Figure 1. How Personal Health Records work with Health Connect.

PHR APIs are made available through the Android 16 SDK. See Set up the Android 16 SDK for instructions on getting started.

Limitations

As these APIs are still under development, there are still some limitations and some components aren't fully available.

  • The Health Connect Jetpack SDK is typically used to simplify the integration by wrapping the Health Connect APIs, but these aren't yet available, so the underlying Android framework APIs must be used.
  • The Play Policy for PHR access is still being developed, and apps may need to meet additional requirements before they can be released on the Play Store.
  • Some features, such as changelogs-based APIs, have not been developed for PHR APIs yet.

PHR data format

PHR data is stored in the HL7 FHIR format, initially supporting only version R4.

Data validation

The PHR APIs accept valid R4 FHIR resources and Health Connect will perform some validation to ensure that the FHIR R4 spec is followed.

Validation checks marked as Coming soon are not yet enforced, but will be in a future release. We recommend developing against all listed validation checks to avoid issues with future releases.

Table 1: Health Connect validation of FHIR data
Level Validation Check
Valid JSON Data is compliant with the JSON format.
Supported FHIR

FHIR version declared by the writing application is supported. The following FHIR versions are supported by Health Connect:

  • 4.0.1
  • 4.3.0
Supported FHIR

FHIR resource type recorded in the resource instance is supported. The following FHIR resource types are supported by Health Connect:

  • AllergyIntolerance
  • Condition
  • Encounter
  • Immunization
  • Location
  • Medication
  • MedicationRequest
  • MedicationStatement
  • Observation
  • Organization
  • Patient
  • Practitioner
  • PractitionerRole
  • Procedure
Unique resource ID Resource has an ID field with a value that meets regular expression requirements.
Unique resource ID Resource does not share an ID with another FHIR resource of the same resource type from the same MedicalDataSource.
Business Rules Does not contain a contained FHIR resource.

Contained resources are FHIR resources nested within a "parent" resource. They are used when the parent resource needs to reference another resource, but the system does not have sufficient information to create this a standalone resource with independent existence.
Valid Base FHIR Top-level fields in the FHIR JSON exist in the FHIR specification for the given resource type.
Valid Base FHIR Top-level fields don't have JSON null values.
Valid Base FHIR Top-level fields defined as repeating elements in FHIR have a JSON array data type.
Valid Base FHIR Top-level fields (including elements within JSON arrays) defined as Complex types in FHIR have a JSON object data type.
Valid Base FHIR Top-level fields (including elements within JSON arrays) defined as Primitive types in FHIR have the correct JSON data type.

FHIR data type JSON data type
integer, unsignedInt, positiveInt, decimal number
boolean boolean
instant, time, date, dateTime, string, code, markdown, id uri, url, oid, uuid, canonical, integer64, base64Binary number
Coming soon
Valid Base FHIR Top-level fields defined as Primitive types in FHIR meet regular expression requirements.

Coming soon
Valid Base FHIR Extensions to Primitive types exist in the FHIR specification and have a JSON object data type.
Valid Base FHIR No more than one field is recorded for Choice fields (fieldname[x]).

For example, effectiveDateTime and effectivePeriod cannot both be present in the same resource instance.
Valid Base FHIR Complex data types contain fields and data types that match the FHIR specification.

Coming soon
Valid Base FHIR Backbone elements (and elements within complex types) contain fields and data types that match the FHIR specification.

Coming soon
Valid Base FHIR Extensions element value[x] fields are a valid type and contain contents according to that data type.

Extension elements can be included in any resource to represent additional information not part of the base spec. They contain a field url which links to the definition of the extension, and a field value[x] which contains the extension value. value[x] must be from set list of accepted data types.

Coming soon
Valid Base FHIR Top-level required fields are all present.

Data categories

The supported set of FHIR resources and corresponding categories are based roughly on the International Patient Summary sections:

  • Allergy intolerance category - contains AllergyIntolerance resources.
  • Conditions category - contains Condition resources.
  • Visits category - contains Encounter, Location, Organization resources.
  • Vaccines category - contains Immunization resources.
  • Personal details category - contains Patient resources.
  • Practitioner details category - contains Practitioner, PractitionerRole resources.
  • Procedures category - contains Procedure resources.
  • Medication category - contains Medication, MedicationRequest, MedicationStatement resources.

Observation resources are categorized based on their content:

  • Pregnancy - based on pregnancy LOINC codes.
  • Social History - based on Social History LOINC codes or "social-history" FHIR category.
  • Vital Signs - based on vital signs LOINC codes or "vital-signs" FHIR category.
  • Laboratory - based on "laboratory" FHIR category.

Observations not belonging to any of the these categories are not written to Health Connect.

Patient resources

Health Connect is intended to store PHR data for a single individual only at this time. Therefore all FHIR resources written should belong to the same person.

It is not uncommon for multiple FHIR Patient resources to exist in a system for a single individual. We prefer writing apps to reconcile data and write a single Patient resource to Health Connect. However, this is not enforced to accommodate the different organizational structures that may exist.

Transformed FHIR data

Some apps transform FHIR data to meet their own requirements. For example:

  • Merging data from different sources (typically FHIR APIs).
  • Mapping codes to global terminologies (for example, SNOMED, LOINC, ICD) and standardising units.
  • Consolidating and deduplicating data.
  • Fixing formatting or other data quality issues.
  • Filtering records based on app-specific business rules.

Either the untransformed and transformed FHIR data could be written to Health Connect, provided they comply with the FHIR R4 specification. We recommend that you write transformed data where possible. But keep in mind the following considerations:

  • Apps with narrow use-cases may filter out a significant number of records that other apps in the ecosystem could create user value from. In such situations, it may be beneficial to write the untransformed FHIR that is more complete. However, make sure to inform users that this wider dataset is being shared.
  • If merging data that originates from different sources, you can write data to a single MedicalDataSource in Health Connect. You must also assign a new ID to each resource to avoid clashes, and update resource references to point to the new Ids.
  • Merging data from multiple sources into a single MedicalDataSource can obscure the data origin. As it is often useful for data consumers to understand the provenance of data, we recommend populating the meta.source field for each resource with the original source of the record (typically a FHIR base URL).

User experience

General information about the user experience is provided in this section.

Permissions

Requesting read or write medical record permissions behaves similarly to the existing Health Connect permissions screens, but a separate health records screen is shown:

permissions

Data browsing

Health Connect also provides basic visualization and browsing of PHR data stored, similar to existing Health Connect data types.

browsing